chromeos/dbus/cryptohome_client.h

// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CHROMEOS_DBUS_CRYPTOHOME_CLIENT_H_
#define CHROMEOS_DBUS_CRYPTOHOME_CLIENT_H_

#include <string>
#include <vector>

#include "base/basictypes.h"
#include "base/callback.h"
#include "chromeos/attestation/attestation_constants.h"
#include "chromeos/chromeos_export.h"
#include "chromeos/dbus/dbus_client.h"
#include "chromeos/dbus/dbus_method_call_status.h"

namespace cryptohome {

class AccountIdentifier;
class AddKeyRequest;
class AuthorizationRequest;
class BaseReply;
class CheckKeyRequest;
class MountRequest;
class UpdateKeyRequest;
class RemoveKeyRequest;

} // namespace cryptohome

namespace chromeos {

// CryptohomeClient is used to communicate with the Cryptohome service.
// All method should be called from the origin thread (UI thread) which
// initializes the DBusThreadManager instance.
class CHROMEOS_EXPORT CryptohomeClient : public DBusClient {
 public:
  // A callback to handle AsyncCallStatus signals.
  typedef base::Callback<void(int async_id,
                              bool return_status,
                              int return_code)>
      AsyncCallStatusHandler;
  // A callback to handle AsyncCallStatusWithData signals.
  typedef base::Callback<void(int async_id,
                              bool return_status,
                              const std::string& data)>
      AsyncCallStatusWithDataHandler;
  // A callback to handle responses of AsyncXXX methods.
  typedef base::Callback<void(int async_id)> AsyncMethodCallback;
  // A callback for GetSystemSalt().
  typedef base::Callback<void(
      DBusMethodCallStatus call_status,
      const std::vector<uint8>& system_salt)> GetSystemSaltCallback;
  // A callback for WaitForServiceToBeAvailable().
  typedef base::Callback<void(bool service_is_ready)>
      WaitForServiceToBeAvailableCallback;
  // A callback to handle responses of Pkcs11GetTpmTokenInfo method.  The result
  // of the D-Bus call is in |call_status|.  On success, |label| holds the
  // PKCS #11 token label.  This is not useful in practice to identify a token
  // but may be meaningful to a user.  The |user_pin| can be used with the
  // C_Login PKCS #11 function but is not necessary because tokens are logged in
  // for the duration of a signed-in session.  The |slot| corresponds to a
  // CK_SLOT_ID for the PKCS #11 API and reliably identifies the token for the
  // duration of the signed-in session.
  typedef base::Callback<void(
      DBusMethodCallStatus call_status,
      const std::string& label,
      const std::string& user_pin,
      int slot)> Pkcs11GetTpmTokenInfoCallback;
  // A callback for methods which return both a bool result and data.
  typedef base::Callback<void(DBusMethodCallStatus call_status,
                              bool result,
                              const std::string& data)> DataMethodCallback;

  // A callback for methods which return both a bool and a protobuf as reply.
  typedef base::Callback<
      void(DBusMethodCallStatus call_status,
           bool result,
           const cryptohome::BaseReply& reply)> ProtobufMethodCallback;

  virtual ~CryptohomeClient();

  // Factory function, creates a new instance and returns ownership.
  // For normal usage, access the singleton via DBusThreadManager::Get().
  static CryptohomeClient* Create();

  // Returns the sanitized |username| that the stub implementation would return.
  static std::string GetStubSanitizedUsername(const std::string& username);

  // Sets AsyncCallStatus signal handlers.
  // |handler| is called when results for AsyncXXX methods are returned.
  // Cryptohome service will process the calls in a first-in-first-out manner
  // when they are made in parallel.
  virtual void SetAsyncCallStatusHandlers(
      const AsyncCallStatusHandler& handler,
      const AsyncCallStatusWithDataHandler& data_handler) = 0;

  // Resets AsyncCallStatus signal handlers.
  virtual void ResetAsyncCallStatusHandlers() = 0;

  // Runs the callback as soon as the service becomes available.
  virtual void WaitForServiceToBeAvailable(
      const WaitForServiceToBeAvailableCallback& callback) = 0;

  // Calls IsMounted method and returns true when the call succeeds.
  virtual void IsMounted(const BoolDBusMethodCallback& callback) = 0;

  // Calls Unmount method and returns true when the call succeeds.
  // This method blocks until the call returns.
  virtual bool Unmount(bool* success) = 0;

  // Calls AsyncCheckKey method.  |callback| is called after the method call
  // succeeds.
  virtual void AsyncCheckKey(const std::string& username,
                             const std::string& key,
                             const AsyncMethodCallback& callback) = 0;

  // Calls AsyncMigrateKey method.  |callback| is called after the method call
  // succeeds.
  virtual void AsyncMigrateKey(const std::string& username,
                               const std::string& from_key,
                               const std::string& to_key,
                               const AsyncMethodCallback& callback) = 0;

  // Calls AsyncRemove method.  |callback| is called after the method call
  // succeeds.
  virtual void AsyncRemove(const std::string& username,
                           const AsyncMethodCallback& callback) = 0;

  // Calls GetSystemSalt method.  |callback| is called after the method call
  // succeeds.
  virtual void GetSystemSalt(const GetSystemSaltCallback& callback) = 0;

  // Calls GetSanitizedUsername method.  |callback| is called after the method
  // call succeeds.
  virtual void GetSanitizedUsername(
      const std::string& username,
      const StringDBusMethodCallback& callback) = 0;

  // Same as GetSanitizedUsername() but blocks until a reply is received, and
  // returns the sanitized username synchronously. Returns an empty string if
  // the method call fails.
  // This may only be called in situations where blocking the UI thread is
  // considered acceptable (e.g. restarting the browser after a crash or after
  // a flag change).
  virtual std::string BlockingGetSanitizedUsername(
      const std::string& username) = 0;

  // Calls the AsyncMount method to asynchronously mount the cryptohome for
  // |username|, using |key| to unlock it. For supported |flags|, see the
  // documentation of AsyncMethodCaller::AsyncMount().
  // |callback| is called after the method call succeeds.
  virtual void AsyncMount(const std::string& username,
                          const std::string& key,
                          int flags,
                          const AsyncMethodCallback& callback) = 0;

  // Calls the AsyncAddKey method to asynchronously add another |new_key| for
  // |username|, using |key| to unlock it first.
  // |callback| is called after the method call succeeds.
  virtual void AsyncAddKey(const std::string& username,
                           const std::string& key,
                           const std::string& new_key,
                           const AsyncMethodCallback& callback) = 0;

  // Calls AsyncMountGuest method.  |callback| is called after the method call
  // succeeds.
  virtual void AsyncMountGuest(const AsyncMethodCallback& callback) = 0;

  // Calls the AsyncMount method to asynchronously mount the cryptohome for
  // |public_mount_id|. For supported |flags|, see the documentation of
  // AsyncMethodCaller::AsyncMount().  |callback| is called after the method
  // call succeeds.
  virtual void AsyncMountPublic(const std::string& public_mount_id,
                                int flags,
                                const AsyncMethodCallback& callback) = 0;

  // Calls TpmIsReady method.
  virtual void TpmIsReady(const BoolDBusMethodCallback& callback) = 0;

  // Calls TpmIsEnabled method.
  virtual void TpmIsEnabled(const BoolDBusMethodCallback& callback) = 0;

  // Calls TpmIsEnabled method and returns true when the call succeeds.
  // This method blocks until the call returns.
  // TODO(hashimoto): Remove this method. crbug.com/141006
  virtual bool CallTpmIsEnabledAndBlock(bool* enabled) = 0;

  // Calls TpmGetPassword method.
  virtual void TpmGetPassword(const StringDBusMethodCallback& callback) = 0;

  // Calls TpmIsOwned method.
  virtual void TpmIsOwned(const BoolDBusMethodCallback& callback) = 0;

  // Calls TpmIsOwned method and returns true when the call succeeds.
  // This method blocks until the call returns.
  // TODO(hashimoto): Remove this method. crbug.com/141012
  virtual bool CallTpmIsOwnedAndBlock(bool* owned) = 0;

  // Calls TpmIsBeingOwned method.
  virtual void TpmIsBeingOwned(const BoolDBusMethodCallback& callback) = 0;

  // Calls TpmIsBeingOwned method and returns true when the call succeeds.
  // This method blocks until the call returns.
  // TODO(hashimoto): Remove this method. crbug.com/141011
  virtual bool CallTpmIsBeingOwnedAndBlock(bool* owning) = 0;

  // Calls TpmCanAttemptOwnership method.
  // This method tells the service that it is OK to attempt ownership.
  virtual void TpmCanAttemptOwnership(
      const VoidDBusMethodCallback& callback) = 0;

  // Calls TpmClearStoredPasswordMethod.
  virtual void TpmClearStoredPassword(
      const VoidDBusMethodCallback& callback) = 0;

  // Calls TpmClearStoredPassword method and returns true when the call
  // succeeds.  This method blocks until the call returns.
  // TODO(hashimoto): Remove this method. crbug.com/141010
  virtual bool CallTpmClearStoredPasswordAndBlock() = 0;

  // Calls Pkcs11IsTpmTokenReady method.
  virtual void Pkcs11IsTpmTokenReady(
      const BoolDBusMethodCallback& callback) = 0;

  // Calls Pkcs11GetTpmTokenInfo method.  This method is deprecated, you should
  // use Pkcs11GetTpmTokenInfoForUser instead.  On success |callback| will
  // receive PKCS #11 token information for the token associated with the user
  // who originally signed in (i.e. PKCS #11 slot 0).
  virtual void Pkcs11GetTpmTokenInfo(
      const Pkcs11GetTpmTokenInfoCallback& callback) = 0;

  // Calls Pkcs11GetTpmTokenInfoForUser method.  On success |callback| will
  // receive PKCS #11 token information for the user identified by |user_email|.
  // The |user_email| must be a canonical email address as returned by
  // chromeos::User::email().
  virtual void Pkcs11GetTpmTokenInfoForUser(
      const std::string& user_email,
      const Pkcs11GetTpmTokenInfoCallback& callback) = 0;

  // Calls InstallAttributesGet method and returns true when the call succeeds.
  // This method blocks until the call returns.
  // The original content of |value| is lost.
  virtual bool InstallAttributesGet(const std::string& name,
                                    std::vector<uint8>* value,
                                    bool* successful) = 0;

  // Calls InstallAttributesSet method and returns true when the call succeeds.
  // This method blocks until the call returns.
  virtual bool InstallAttributesSet(const std::string& name,
                                    const std::vector<uint8>& value,
                                    bool* successful) = 0;

  // Calls InstallAttributesFinalize method and returns true when the call
  // succeeds.  This method blocks until the call returns.
  virtual bool InstallAttributesFinalize(bool* successful) = 0;

  // Calls InstallAttributesIsReady method.
  virtual void InstallAttributesIsReady(
      const BoolDBusMethodCallback& callback) = 0;

  // Calls InstallAttributesIsInvalid method and returns true when the call
  // succeeds.  This method blocks until the call returns.
  virtual bool InstallAttributesIsInvalid(bool* is_invalid) = 0;

  // Calls InstallAttributesIsFirstInstall method and returns true when the call
  // succeeds. This method blocks until the call returns.
  virtual bool InstallAttributesIsFirstInstall(bool* is_first_install) = 0;

  // Calls the TpmAttestationIsPrepared dbus method.  The callback is called
  // when the operation completes.
  virtual void TpmAttestationIsPrepared(
        const BoolDBusMethodCallback& callback) = 0;

  // Calls the TpmAttestationIsEnrolled dbus method.  The callback is called
  // when the operation completes.
  virtual void TpmAttestationIsEnrolled(
        const BoolDBusMethodCallback& callback) = 0;

  // Asynchronously creates an attestation enrollment request.  The callback
  // will be called when the dbus call completes.  When the operation completes,
  // the AsyncCallStatusWithDataHandler signal handler is called.  The data that
  // is sent with the signal is an enrollment request to be sent to the Privacy
  // CA of type |pca_type|.  The enrollment is completed by calling
  // AsyncTpmAttestationEnroll.
  virtual void AsyncTpmAttestationCreateEnrollRequest(
      chromeos::attestation::PrivacyCAType pca_type,
      const AsyncMethodCallback& callback) = 0;

  // Asynchronously finishes an attestation enrollment operation.  The callback
  // will be called when the dbus call completes.  When the operation completes,
  // the AsyncCallStatusHandler signal handler is called.  |pca_response| is the
  // response to the enrollment request emitted by the Privacy CA of type
  // |pca_type|.
  virtual void AsyncTpmAttestationEnroll(
      chromeos::attestation::PrivacyCAType pca_type,
      const std::string& pca_response,
      const AsyncMethodCallback& callback) = 0;

  // Asynchronously creates an attestation certificate request according to
  // |certificate_profile|.  Some profiles require that the |user_id| of the
  // currently active user and an identifier of the |request_origin| be
  // provided.  |callback| will be called when the dbus call completes.  When
  // the operation completes, the AsyncCallStatusWithDataHandler signal handler
  // is called.  The data that is sent with the signal is a certificate request
  // to be sent to the Privacy CA of type |pca_type|.  The certificate request
  // is completed by calling AsyncTpmAttestationFinishCertRequest.  The
  // |user_id| will not be included in the certificate request for the Privacy
  // CA.
  virtual void AsyncTpmAttestationCreateCertRequest(
      chromeos::attestation::PrivacyCAType pca_type,
      attestation::AttestationCertificateProfile certificate_profile,
      const std::string& user_id,
      const std::string& request_origin,
      const AsyncMethodCallback& callback) = 0;

  // Asynchronously finishes a certificate request operation.  The callback will
  // be called when the dbus call completes.  When the operation completes, the
  // AsyncCallStatusWithDataHandler signal handler is called.  The data that is
  // sent with the signal is a certificate chain in PEM format.  |pca_response|
  // is the response to the certificate request emitted by the Privacy CA.
  // |key_type| determines whether the certified key is to be associated with
  // the current user.  |key_name| is a name for the key.  If |key_type| is
  // KEY_USER, a |user_id| must be provided.  Otherwise |user_id| is ignored.
  // For normal GAIA users the |user_id| is a canonical email address.
  virtual void AsyncTpmAttestationFinishCertRequest(
      const std::string& pca_response,
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const AsyncMethodCallback& callback) = 0;

  // Checks if an attestation key already exists.  If the key specified by
  // |key_type| and |key_name| exists, then the result sent to the callback will
  // be true.  If |key_type| is KEY_USER, a |user_id| must be provided.
  // Otherwise |user_id| is ignored.  For normal GAIA users the |user_id| is a
  // canonical email address.
  virtual void TpmAttestationDoesKeyExist(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const BoolDBusMethodCallback& callback) = 0;

  // Gets the attestation certificate for the key specified by |key_type| and
  // |key_name|.  |callback| will be called when the operation completes.  If
  // the key does not exist the callback |result| parameter will be false.  If
  // |key_type| is KEY_USER, a |user_id| must be provided.  Otherwise |user_id|
  // is ignored.  For normal GAIA users the |user_id| is a canonical email
  // address.
  virtual void TpmAttestationGetCertificate(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const DataMethodCallback& callback) = 0;

  // Gets the public key for the key specified by |key_type| and |key_name|.
  // |callback| will be called when the operation completes.  If the key does
  // not exist the callback |result| parameter will be false.  If |key_type| is
  // KEY_USER, a |user_id| must be provided.  Otherwise |user_id| is ignored.
  // For normal GAIA users the |user_id| is a canonical email address.
  virtual void TpmAttestationGetPublicKey(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const DataMethodCallback& callback) = 0;

  // Asynchronously registers an attestation key with the current user's
  // PKCS #11 token.  The |callback| will be called when the dbus call
  // completes.  When the operation completes, the AsyncCallStatusHandler signal
  // handler is called.  |key_type| and |key_name| specify the key to register.
  // If |key_type| is KEY_USER, a |user_id| must be provided.  Otherwise
  // |user_id| is ignored.  For normal GAIA users the |user_id| is a canonical
  // email address.
  virtual void TpmAttestationRegisterKey(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const AsyncMethodCallback& callback) = 0;

  // Asynchronously signs an enterprise challenge with the key specified by
  // |key_type| and |key_name|.  |domain| and |device_id| will be included in
  // the challenge response.  |options| control how the challenge response is
  // generated.  |challenge| must be a valid enterprise attestation challenge.
  // The |callback| will be called when the dbus call completes.  When the
  // operation completes, the AsyncCallStatusWithDataHandler signal handler is
  // called.  If |key_type| is KEY_USER, a |user_id| must be provided.
  // Otherwise |user_id| is ignored.  For normal GAIA users the |user_id| is a
  // canonical email address.
  virtual void TpmAttestationSignEnterpriseChallenge(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const std::string& domain,
      const std::string& device_id,
      attestation::AttestationChallengeOptions options,
      const std::string& challenge,
      const AsyncMethodCallback& callback) = 0;

  // Asynchronously signs a simple challenge with the key specified by
  // |key_type| and |key_name|.  |challenge| can be any set of arbitrary bytes.
  // A nonce will be appended to the challenge before signing; this method
  // cannot be used to sign arbitrary data.  The |callback| will be called when
  // the dbus call completes.  When the operation completes, the
  // AsyncCallStatusWithDataHandler signal handler is called.  If |key_type| is
  // KEY_USER, a |user_id| must be provided.  Otherwise |user_id| is ignored.
  // For normal GAIA users the |user_id| is a canonical email address.
  virtual void TpmAttestationSignSimpleChallenge(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const std::string& challenge,
      const AsyncMethodCallback& callback) = 0;

  // Gets the payload associated with the key specified by |key_type| and
  // |key_name|.  The |callback| will be called when the operation completes.
  // If the key does not exist the callback |result| parameter will be false.
  // If no payload has been set for the key the callback |result| parameter will
  // be true and the |data| parameter will be empty.  If |key_type| is
  // KEY_USER, a |user_id| must be provided.  Otherwise |user_id| is ignored.
  // For normal GAIA users the |user_id| is a canonical email address.
  virtual void TpmAttestationGetKeyPayload(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const DataMethodCallback& callback) = 0;

  // Sets the |payload| associated with the key specified by |key_type| and
  // |key_name|.  The |callback| will be called when the operation completes.
  // If the operation succeeds, the callback |result| parameter will be true.
  // If |key_type| is KEY_USER, a |user_id| must be provided.  Otherwise
  // |user_id| is ignored.  For normal GAIA users the |user_id| is a canonical
  // email address.
  virtual void TpmAttestationSetKeyPayload(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_name,
      const std::string& payload,
      const BoolDBusMethodCallback& callback) = 0;

  // Deletes certified keys as specified by |key_type| and |key_prefix|.  The
  // |callback| will be called when the operation completes.  If the operation
  // succeeds, the callback |result| parameter will be true.  If |key_type| is
  // KEY_USER, a |user_id| must be provided.  Otherwise |user_id| is ignored.
  // For normal GAIA users the |user_id| is a canonical email address.  All keys
  // where the key name has a prefix matching |key_prefix| will be deleted.  All
  // meta-data associated with the key, including certificates, will also be
  // deleted.
  virtual void TpmAttestationDeleteKeys(
      attestation::AttestationKeyType key_type,
      const std::string& user_id,
      const std::string& key_prefix,
      const BoolDBusMethodCallback& callback) = 0;

  // Asynchronously calls CheckKeyEx method. |callback| is called after method
  // call, and with reply protobuf.
  // CheckKeyEx just checks if authorization information is valid.
  virtual void CheckKeyEx(
      const cryptohome::AccountIdentifier& id,
      const cryptohome::AuthorizationRequest& auth,
      const cryptohome::CheckKeyRequest& request,
      const ProtobufMethodCallback& callback) = 0;

  // Asynchronously calls MountEx method. |callback| is called after method
  // call, and with reply protobuf.
  // MountEx attempts to mount home dir using given authorization, and can
  // create new home dir if necessary values are specified in |request|.
  virtual void MountEx(
      const cryptohome::AccountIdentifier& id,
      const cryptohome::AuthorizationRequest& auth,
      const cryptohome::MountRequest& request,
      const ProtobufMethodCallback& callback) = 0;

  // Asynchronously calls AddKeyEx method. |callback| is called after method
  // call, and with reply protobuf.
  // AddKeyEx adds another key to the given key set. |request| also defines
  // behavior in case when key with specified label already exist.
  virtual void AddKeyEx(
      const cryptohome::AccountIdentifier& id,
      const cryptohome::AuthorizationRequest& auth,
      const cryptohome::AddKeyRequest& request,
      const ProtobufMethodCallback& callback) = 0;

  // Asynchronously calls UpdateKeyEx method. |callback| is called after method
  // call, and with reply protobuf. Reply will contain MountReply extension.
  // UpdateKeyEx replaces key used for authorization, without affecting any
  // other keys. If specified at home dir creation time, new key may have
  // to be signed and/or encrypted.
  virtual void UpdateKeyEx(
      const cryptohome::AccountIdentifier& id,
      const cryptohome::AuthorizationRequest& auth,
      const cryptohome::UpdateKeyRequest& request,
      const ProtobufMethodCallback& callback) = 0;

  // Asynchronously calls RemoveKeyEx method. |callback| is called after method
  // call, and with reply protobuf.
  // RemoveKeyEx removes key from the given key set.
  virtual void RemoveKeyEx(const cryptohome::AccountIdentifier& id,
                           const cryptohome::AuthorizationRequest& auth,
                           const cryptohome::RemoveKeyRequest& request,
                           const ProtobufMethodCallback& callback) = 0;

 protected:
  // Create() should be used instead.
  CryptohomeClient();

 private:
  DISALLOW_COPY_AND_ASSIGN(CryptohomeClient);
};

}  // namespace chromeos

#endif  // CHROMEOS_DBUS_CRYPTOHOME_CLIENT_H_