cryptohome/le_credential_backend.h - mirrors/cros/chromiumos/platform2 - Git at Google

 // Copyright 2018 The Chromium OS 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 CRYPTOHOME_LE_CREDENTIAL_BACKEND_H_
 #define CRYPTOHOME_LE_CREDENTIAL_BACKEND_H_

 #include <map>
 #include <string>
 #include <vector>

 #include <brillo/secure_blob.h>

 namespace cryptohome {

 // Constants used to define the hash tree. Currently we place them here,
 // since they are used between LECredentialManager and LECredentialBackend.
 const uint32_t kLengthLabels = 14;
 const uint32_t kNumChildren = 4;
 const uint32_t kBitsPerLevel = 2;

 // List of error values returned from TPM for the Low Entropy Credential
 // check routine.
 enum LECredBackendError {
   // Credential check was successful.
   LE_TPM_SUCCESS = 0,
   // Check failed due to incorrect Low Entropy credential provided.
   LE_TPM_ERROR_INVALID_LE_SECRET,
   // Reset failed due to incorrect Reset credential provided.
   LE_TPM_ERROR_INVALID_RESET_SECRET,
   // Check failed since the credential has been locked out due to too many
   // attempts per the delay schedule.
   LE_TPM_ERROR_TOO_MANY_ATTEMPTS,
   // Check failed due to the hash tree being out of sync. This should
   // prompt a hash tree resynchronization and retry.
   LE_TPM_ERROR_HASH_TREE_SYNC,
   // Check failed due to an operation failing on the TPM side. This should
   // prompt a hash tree resynchronization and retry.
   LE_TPM_ERROR_TPM_OP_FAILED,
   // The PCR is in unexpected state. The basic way to proceed from here is to
   // reboot the device.
   LE_TPM_ERROR_PCR_NOT_MATCH,
 };

 // Enum used to denote the LE log entry type.
 enum LELogEntryType {
   LE_LOG_INSERT = 0,
   LE_LOG_CHECK,
   LE_LOG_REMOVE,
   LE_LOG_RESET,
   // Sentinel value.
   LE_LOG_INVALID,
 };

 // Container for LE credential log replay data obtained from the LE Backend.
 // This struct is used during sychronization operations which occur when the
 // on-disk hash tree state and LE Backend hash tree state are out-of-sync.
 struct LELogEntry {
   LELogEntryType type;
   // Label on which the log operation is performed.
   uint64_t label;
   // Value of root hash after the log operation is performed.
   std::vector<uint8_t> root;
   // For insert operations, this signifies the MAC of the inserted leaf.
   std::vector<uint8_t> mac;
 };

 // Defines a set of PCR indexes (in bitmask) and the digest that is valid
 // after computation of sha256 of concatenation of PCR values included in
 // bitmask.
 struct ValidPcrValue {
   /* The set of PCR indexes that have to pass the validation. */
   uint8_t bitmask[2];
   /* The hash digest of the PCR values contained in the bitmask */
   std::string digest;
 };

 typedef std::vector<ValidPcrValue> ValidPcrCriteria;

 // LECredentialBackend - class for performing Low Entropy (LE) Credential
 // related operations in the TPM. The Tpm class implementations which support LE
 // Credential handling will contain an object of a class which implements
 // this interface. The base Tpm Class will have a functnon which can be
 // used to retrieve a reference to this object. For Tpm implementations which
 // don't support LE Credentials, the aforementioned function will return a
 // nullptr.
 class LECredentialBackend {
  public:
   // Resets the TPM Low Entropy (LE) Credential Hash Tree root hash
   // with its initial known value, which assumes all MACs are all-zero.
   //
   // This function should be executed only when we are setting up a hash tree
   // on a new / wiped device, or resetting the hash tree due to an
   // unrecoverable error.
   //
   // Returns true on success, false otherwise.
   //
   // In all cases, the resulting root hash is returned in |new_root|.
   virtual bool Reset(std::vector<uint8_t>* new_root) = 0;

   // Returns whether LE credential protection is supported in this specific
   // backend. Not all TPM2-based h/w will support this feature (only Cr50
   // and later), so this function will only return true for h/w which does.
   virtual bool IsSupported() = 0;

   // Tries to insert a credential into the TPM.
   //
   // The label of the leaf node is in |label|, the list of auxiliary hashes is
   // in |h_aux|, the LE credential to be added is in |le_secret|. Along with
   // it, its associated reset_secret |reset_secret| and the high entropy
   // credential it protects |he_secret| are also provided. The delay schedule
   // which determines the delay enforced between authentication attempts is
   // provided by |delay_schedule|. The list of valid PCR values that would be
   // accepted by authentication is provided by |valid_pcr_criteria|.
   //
   // If successful, the new credential metadata will be placed in the blob
   // pointed by |cred_metadata|. The MAC of the credential will be returned
   // in |mac|.
   //
   // Returns true on success, false on failure.
   //
   // |h_aux| requires a particular order: starting from left child to right
   // child, from leaf upwards till the children of the root label.
   //
   // In all cases, the resulting root hash is returned in |new_root|.
   virtual bool InsertCredential(
       const uint64_t label,
       const std::vector<std::vector<uint8_t>>& h_aux,
       const brillo::SecureBlob& le_secret,
       const brillo::SecureBlob& he_secret,
       const brillo::SecureBlob& reset_secret,
       const std::map<uint32_t, uint32_t>& delay_schedule,
       const ValidPcrCriteria& valid_pcr_criteria,
       std::vector<uint8_t>* cred_metadata,
       std::vector<uint8_t>* mac,
       std::vector<uint8_t>* new_root) = 0;

   // Checks the metadata leaf version and returns if the leaf needs to be bound
   // to PCR.
   virtual bool NeedsPCRBinding(const std::vector<uint8_t>& cred_metadata) = 0;

   // Looks into the metadata and retrieves the number of wrong authentication
   // attempts. Returns -1 on error.
   virtual int GetWrongAuthAttempts(
       const std::vector<uint8_t>& cred_metadata) = 0;

   // Tries to verify/authenticate a credential.
   //
   // The obfuscated LE Credential is |le_secret| and the credential metadata is
   // in |orig_cred_metadata|.
   //
   // Returns true on success, false on failure.
   // On success, |err| is set to LE_TPM_SUCCESS.
   // On failure, |err| is set with the appropriate error code:
   // - LE_TPM_ERROR_INVALID_LE_SECRET for incorrect authentication attempt.
   // - LE_TPM_ERROR_TOO_MANY_ATTEMPTS for locked out credential.
   // - LE_TPM_ERROR_HASH_TREE for error in hash tree sync.
   // - LE_TPM_ERROR_TPM_OP_FAILED for Tpm operation error.
   //
   // On success, or failure due to an invalid |le_secret|, the updated
   // credential metadata and corresponding new MAC will be returned in
   // |new_cred_metadata| and |new_mac|.
   //
   // On success, the released high entropy credential will be returned in
   // |he_secret| and the reset secret in |reset_secret|.
   //
   // In all cases, the resulting root hash is returned in |new_root|.
   virtual bool CheckCredential(const uint64_t label,
                                const std::vector<std::vector<uint8_t>>& h_aux,
                                const std::vector<uint8_t>& orig_cred_metadata,
                                const brillo::SecureBlob& le_secret,
                                std::vector<uint8_t>* new_cred_metadata,
                                std::vector<uint8_t>* new_mac,
                                brillo::SecureBlob* he_secret,
                                brillo::SecureBlob* reset_secret,
                                LECredBackendError* err,
                                std::vector<uint8_t>* new_root) = 0;

   // Tries to reset a (potentially locked out) credential.
   //
   // The reset credential is |reset_secret| and the credential metadata is
   // in |orig_cred_metadata|.
   //
   // Returns true on success, false on failure.
   // On success, |err| is set to LE_TPM_SUCCESS.
   // On failure, |err| is set with the appropriate error code:
   // - LE_TPM_ERROR_INVALID_RESET_SECRET for incorrect authentication attempt.
   // - LE_TPM_ERROR_HASH_TREE for error in hash tree sync.
   // - LE_TPM_ERROR_TPM_OP_FAILED for Tpm operation error.
   //
   // On success, the updated credential metadata and corresponding new MAC will
   // be returned in |new_cred_metadata| and |new_mac|.
   //
   // In all cases, the resulting root hash is returned in |new_root|.
   virtual bool ResetCredential(const uint64_t label,
                                const std::vector<std::vector<uint8_t>>& h_aux,
                                const std::vector<uint8_t>& orig_cred_metadata,
                                const brillo::SecureBlob& reset_secret,
                                std::vector<uint8_t>* new_cred_metadata,
                                std::vector<uint8_t>* new_mac,
                                LECredBackendError* err,
                                std::vector<uint8_t>* new_root) = 0;

   // Removes the credential which has label |label|.
   //
   // The corresponding list of auxiliary hashes is in |h_aux|, and the MAC of
   // the label that needs to be removed is |mac|.
   //
   // Returns true on success, false on failure.
   //
   // In all cases, the resulting root hash is returned in |new_root|.
   virtual bool RemoveCredential(const uint64_t label,
                                 const std::vector<std::vector<uint8_t>>& h_aux,
                                 const std::vector<uint8_t>& mac,
                                 std::vector<uint8_t>* new_root) = 0;

   // Retrieves the replay log.
   //
   // The current on-disk root hash is supplied via |cur_disk_root_hash|.
   // The LE backend's current root hash is returned in |root_hash|
   //
   // Returns true on success (was able to communicate with the backend), and
   // false otherwise.
   // TODO(crbug.com/809710): Add a |log_data| vector which should return log
   // entries in already-parsed form.
   virtual bool GetLog(const std::vector<uint8_t>& cur_disk_root_hash,
                       std::vector<uint8_t>* root_hash,
                       std::vector<LELogEntry>* log) = 0;

   // Replays the log operation referenced by |log_entry_root|, where
   // |log_entry_root| is the resulting root hash after the operation, and is
   // retrieved from the log entry.
   // |h_aux| and |orig_cred_metadata| refer to, respectively, the list of
   // auxiliary hashes and the original credential metadata associated with the
   // label concerned (available in the log entry). The resulting metadata and
   // MAC are stored in |new_cred_metadata| and |new_mac|.
   //
   // Returns true on success, false on failure.
   virtual bool ReplayLogOperation(
       const std::vector<uint8_t>& log_entry_root,
       const std::vector<std::vector<uint8_t>>& h_aux,
       const std::vector<uint8_t>& orig_cred_metadata,
       std::vector<uint8_t>* new_cred_metadata,
       std::vector<uint8_t>* new_mac) = 0;
 };

 }  // namespace cryptohome

 #endif  // CRYPTOHOME_LE_CREDENTIAL_BACKEND_H_
	// Copyright 2018 The Chromium OS 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 CRYPTOHOME_LE_CREDENTIAL_BACKEND_H_
	#define CRYPTOHOME_LE_CREDENTIAL_BACKEND_H_

	#include <map>
	#include <string>
	#include <vector>

	#include <brillo/secure_blob.h>

	namespace cryptohome {

	// Constants used to define the hash tree. Currently we place them here,
	// since they are used between LECredentialManager and LECredentialBackend.
	const uint32_t kLengthLabels = 14;
	const uint32_t kNumChildren = 4;
	const uint32_t kBitsPerLevel = 2;

	// List of error values returned from TPM for the Low Entropy Credential
	// check routine.
	enum LECredBackendError {
	// Credential check was successful.
	LE_TPM_SUCCESS = 0,
	// Check failed due to incorrect Low Entropy credential provided.
	LE_TPM_ERROR_INVALID_LE_SECRET,
	// Reset failed due to incorrect Reset credential provided.
	LE_TPM_ERROR_INVALID_RESET_SECRET,
	// Check failed since the credential has been locked out due to too many
	// attempts per the delay schedule.
	LE_TPM_ERROR_TOO_MANY_ATTEMPTS,
	// Check failed due to the hash tree being out of sync. This should
	// prompt a hash tree resynchronization and retry.
	LE_TPM_ERROR_HASH_TREE_SYNC,
	// Check failed due to an operation failing on the TPM side. This should
	// prompt a hash tree resynchronization and retry.
	LE_TPM_ERROR_TPM_OP_FAILED,
	// The PCR is in unexpected state. The basic way to proceed from here is to
	// reboot the device.
	LE_TPM_ERROR_PCR_NOT_MATCH,
	};

	// Enum used to denote the LE log entry type.
	enum LELogEntryType {
	LE_LOG_INSERT = 0,
	LE_LOG_CHECK,
	LE_LOG_REMOVE,
	LE_LOG_RESET,
	// Sentinel value.
	LE_LOG_INVALID,
	};

	// Container for LE credential log replay data obtained from the LE Backend.
	// This struct is used during sychronization operations which occur when the
	// on-disk hash tree state and LE Backend hash tree state are out-of-sync.
	struct LELogEntry {
	LELogEntryType type;
	// Label on which the log operation is performed.
	uint64_t label;
	// Value of root hash after the log operation is performed.
	std::vector<uint8_t> root;
	// For insert operations, this signifies the MAC of the inserted leaf.
	std::vector<uint8_t> mac;
	};

	// Defines a set of PCR indexes (in bitmask) and the digest that is valid
	// after computation of sha256 of concatenation of PCR values included in
	// bitmask.
	struct ValidPcrValue {
	/* The set of PCR indexes that have to pass the validation. */
	uint8_t bitmask[2];
	/* The hash digest of the PCR values contained in the bitmask */
	std::string digest;
	};

	typedef std::vector<ValidPcrValue> ValidPcrCriteria;

	// LECredentialBackend - class for performing Low Entropy (LE) Credential
	// related operations in the TPM. The Tpm class implementations which support LE
	// Credential handling will contain an object of a class which implements
	// this interface. The base Tpm Class will have a functnon which can be
	// used to retrieve a reference to this object. For Tpm implementations which
	// don't support LE Credentials, the aforementioned function will return a
	// nullptr.
	class LECredentialBackend {
	public:
	// Resets the TPM Low Entropy (LE) Credential Hash Tree root hash
	// with its initial known value, which assumes all MACs are all-zero.
	//
	// This function should be executed only when we are setting up a hash tree
	// on a new / wiped device, or resetting the hash tree due to an
	// unrecoverable error.
	//
	// Returns true on success, false otherwise.
	//
	// In all cases, the resulting root hash is returned in \|new_root\|.
	virtual bool Reset(std::vector<uint8_t>* new_root) = 0;

	// Returns whether LE credential protection is supported in this specific
	// backend. Not all TPM2-based h/w will support this feature (only Cr50
	// and later), so this function will only return true for h/w which does.
	virtual bool IsSupported() = 0;

	// Tries to insert a credential into the TPM.
	//
	// The label of the leaf node is in \|label\|, the list of auxiliary hashes is
	// in \|h_aux\|, the LE credential to be added is in \|le_secret\|. Along with
	// it, its associated reset_secret \|reset_secret\| and the high entropy
	// credential it protects \|he_secret\| are also provided. The delay schedule
	// which determines the delay enforced between authentication attempts is
	// provided by \|delay_schedule\|. The list of valid PCR values that would be
	// accepted by authentication is provided by \|valid_pcr_criteria\|.
	//
	// If successful, the new credential metadata will be placed in the blob
	// pointed by \|cred_metadata\|. The MAC of the credential will be returned
	// in \|mac\|.
	//
	// Returns true on success, false on failure.
	//
	// \|h_aux\| requires a particular order: starting from left child to right
	// child, from leaf upwards till the children of the root label.
	//
	// In all cases, the resulting root hash is returned in \|new_root\|.
	virtual bool InsertCredential(
	const uint64_t label,
	const std::vector<std::vector<uint8_t>>& h_aux,
	const brillo::SecureBlob& le_secret,
	const brillo::SecureBlob& he_secret,
	const brillo::SecureBlob& reset_secret,
	const std::map<uint32_t, uint32_t>& delay_schedule,
	const ValidPcrCriteria& valid_pcr_criteria,
	std::vector<uint8_t>* cred_metadata,
	std::vector<uint8_t>* mac,
	std::vector<uint8_t>* new_root) = 0;

	// Checks the metadata leaf version and returns if the leaf needs to be bound
	// to PCR.
	virtual bool NeedsPCRBinding(const std::vector<uint8_t>& cred_metadata) = 0;

	// Looks into the metadata and retrieves the number of wrong authentication
	// attempts. Returns -1 on error.
	virtual int GetWrongAuthAttempts(
	const std::vector<uint8_t>& cred_metadata) = 0;

	// Tries to verify/authenticate a credential.
	//
	// The obfuscated LE Credential is \|le_secret\| and the credential metadata is
	// in \|orig_cred_metadata\|.
	//
	// Returns true on success, false on failure.
	// On success, \|err\| is set to LE_TPM_SUCCESS.
	// On failure, \|err\| is set with the appropriate error code:
	// - LE_TPM_ERROR_INVALID_LE_SECRET for incorrect authentication attempt.
	// - LE_TPM_ERROR_TOO_MANY_ATTEMPTS for locked out credential.
	// - LE_TPM_ERROR_HASH_TREE for error in hash tree sync.
	// - LE_TPM_ERROR_TPM_OP_FAILED for Tpm operation error.
	//
	// On success, or failure due to an invalid \|le_secret\|, the updated
	// credential metadata and corresponding new MAC will be returned in
	// \|new_cred_metadata\| and \|new_mac\|.
	//
	// On success, the released high entropy credential will be returned in
	// \|he_secret\| and the reset secret in \|reset_secret\|.
	//
	// In all cases, the resulting root hash is returned in \|new_root\|.
	virtual bool CheckCredential(const uint64_t label,
	const std::vector<std::vector<uint8_t>>& h_aux,
	const std::vector<uint8_t>& orig_cred_metadata,
	const brillo::SecureBlob& le_secret,
	std::vector<uint8_t>* new_cred_metadata,
	std::vector<uint8_t>* new_mac,
	brillo::SecureBlob* he_secret,
	brillo::SecureBlob* reset_secret,
	LECredBackendError* err,
	std::vector<uint8_t>* new_root) = 0;

	// Tries to reset a (potentially locked out) credential.
	//
	// The reset credential is \|reset_secret\| and the credential metadata is
	// in \|orig_cred_metadata\|.
	//
	// Returns true on success, false on failure.
	// On success, \|err\| is set to LE_TPM_SUCCESS.
	// On failure, \|err\| is set with the appropriate error code:
	// - LE_TPM_ERROR_INVALID_RESET_SECRET for incorrect authentication attempt.
	// - LE_TPM_ERROR_HASH_TREE for error in hash tree sync.
	// - LE_TPM_ERROR_TPM_OP_FAILED for Tpm operation error.
	//
	// On success, the updated credential metadata and corresponding new MAC will
	// be returned in \|new_cred_metadata\| and \|new_mac\|.
	//
	// In all cases, the resulting root hash is returned in \|new_root\|.
	virtual bool ResetCredential(const uint64_t label,
	const std::vector<std::vector<uint8_t>>& h_aux,
	const std::vector<uint8_t>& orig_cred_metadata,
	const brillo::SecureBlob& reset_secret,
	std::vector<uint8_t>* new_cred_metadata,
	std::vector<uint8_t>* new_mac,
	LECredBackendError* err,
	std::vector<uint8_t>* new_root) = 0;

	// Removes the credential which has label \|label\|.
	//
	// The corresponding list of auxiliary hashes is in \|h_aux\|, and the MAC of
	// the label that needs to be removed is \|mac\|.
	//
	// Returns true on success, false on failure.
	//
	// In all cases, the resulting root hash is returned in \|new_root\|.
	virtual bool RemoveCredential(const uint64_t label,
	const std::vector<std::vector<uint8_t>>& h_aux,
	const std::vector<uint8_t>& mac,
	std::vector<uint8_t>* new_root) = 0;

	// Retrieves the replay log.
	//
	// The current on-disk root hash is supplied via \|cur_disk_root_hash\|.
	// The LE backend's current root hash is returned in \|root_hash\|
	//
	// Returns true on success (was able to communicate with the backend), and
	// false otherwise.
	// TODO(crbug.com/809710): Add a \|log_data\| vector which should return log
	// entries in already-parsed form.
	virtual bool GetLog(const std::vector<uint8_t>& cur_disk_root_hash,
	std::vector<uint8_t>* root_hash,
	std::vector<LELogEntry>* log) = 0;

	// Replays the log operation referenced by \|log_entry_root\|, where
	// \|log_entry_root\| is the resulting root hash after the operation, and is
	// retrieved from the log entry.
	// \|h_aux\| and \|orig_cred_metadata\| refer to, respectively, the list of
	// auxiliary hashes and the original credential metadata associated with the
	// label concerned (available in the log entry). The resulting metadata and
	// MAC are stored in \|new_cred_metadata\| and \|new_mac\|.
	//
	// Returns true on success, false on failure.
	virtual bool ReplayLogOperation(
	const std::vector<uint8_t>& log_entry_root,
	const std::vector<std::vector<uint8_t>>& h_aux,
	const std::vector<uint8_t>& orig_cred_metadata,
	std::vector<uint8_t>* new_cred_metadata,
	std::vector<uint8_t>* new_mac) = 0;
	};

	} // namespace cryptohome

	#endif // CRYPTOHOME_LE_CREDENTIAL_BACKEND_H_