blob: cf0156877b30c37db7b0981180cfd290a95dc580 [file] [log] [blame]
// Copyright 2014 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 TRUNKS_TPM_UTILITY_H_
#define TRUNKS_TPM_UTILITY_H_
#include <map>
#include <string>
#include <vector>
#include <base/macros.h>
#include <brillo/secure_blob.h>
#include "trunks/hmac_session.h"
#include "trunks/pinweaver.pb.h"
#include "trunks/tpm_alerts.h"
#include "trunks/tpm_generated.h"
#include "trunks/trunks_export.h"
namespace trunks {
// These handles will be used by TpmUtility.
// * kStorageRootKey: Storage Root Key (Primary Key in Storage Hierarchy in
// TPM2.0) It is ECC key by default, if the RSA key is already generated, we
// will keep use it.
// * kSaltingKey: a RSA key under kStorageRootKey for
// asymmetric encrypting the salt when creating a HMAC session.
const TPMI_DH_PERSISTENT kStorageRootKey = PERSISTENT_FIRST;
// Deprecated: kECCStorageRootKey = PERSISTENT_FIRST + 1;
const TPMI_DH_PERSISTENT kSaltingKey = PERSISTENT_FIRST + 2;
const TPMI_DH_PERSISTENT kRSAEndorsementKey = PERSISTENT_FIRST + 3;
// VENDOR_RC_ERR | VENDOR_RC_NO_SUCH_COMMAND
const int TPM_RC_NO_SUCH_COMMAND = 0x57f;
// Real NVRAM index for endoresement certificate. It is the real index which
// sent to TPM.
constexpr uint32_t kRsaEndorsementCertificateIndex = 0x1C00000;
constexpr uint32_t kEccEndorsementCertificateIndex = 0x1C00001;
// The non-real NVRAM index is only used and accepted by tpm_utility API.
// TODO(crbug/956855): remove these indexes.
constexpr uint32_t kRsaEndorsementCertificateNonRealIndex =
kRsaEndorsementCertificateIndex & 0xFFFFFF;
constexpr uint32_t kEccEndorsementCertificateNonRealIndex =
kEccEndorsementCertificateIndex & 0xFFFFFF;
// An interface which provides convenient methods for common TPM operations.
class TRUNKS_EXPORT TpmUtility {
public:
enum AsymmetricKeyUsage { kDecryptKey, kSignKey, kDecryptAndSignKey };
TpmUtility() {}
virtual ~TpmUtility() {}
// Synchronously performs a TPM startup sequence and self tests. Typically
// this is done by the platform firmware. Returns the result of the startup
// and self-tests or, if already started, just the result of the self-tests.
virtual TPM_RC Startup() = 0;
// Check if the TPM is in a state which allows trunks to proceed. The only
// condition when the state is considered unacceptable and an error is
// returned is if there is no way to communicate with the TPM.
virtual TPM_RC CheckState() = 0;
// This method removes all TPM context associated with a specific Owner.
// As part of this process, it resets the SPS to a new random value, and
// clears ownerAuth, endorsementAuth and lockoutAuth.
// NOTE: This method needs to be called before InitializeTPM.
virtual TPM_RC Clear() = 0;
// Synchronously performs a TPM shutdown operation. It should always be
// successful.
virtual void Shutdown() = 0;
// Synchronously prepares a TPM for use by Chromium OS. Typically this is done
// by the platform firmware and, in that case, this method has no effect.
virtual TPM_RC InitializeTpm() = 0;
// Synchronously allocates the PCRs in the TPM. Currently we allocate
// the first 16 PCRs to use the SHA-256 hash algorithm.
// NOTE: PCR allocation only takes place at the next TPM_Startup call.
// NOTE: This command needs platform authorization and PP assertion.
virtual TPM_RC AllocatePCR(const std::string& platform_password) = 0;
// Performs steps needed for taking ownership, which can be done before
// a signal that an ownership can be attempted is received.
// This operation is an optional optimization: if PrepareForOwnership
// is not called, TakeOwnership will later run through those preparational
// steps, if needed.
virtual TPM_RC PrepareForOwnership() = 0;
// Synchronously takes ownership of the TPM with the given passwords as
// authorization values.
virtual TPM_RC TakeOwnership(const std::string& owner_password,
const std::string& endorsement_password,
const std::string& lockout_password) = 0;
// Stir the tpm random generation module with some random entropy data.
// |delegate| specifies an optional authorization delegate to be used.
virtual TPM_RC StirRandom(const std::string& entropy_data,
AuthorizationDelegate* delegate) = 0;
// This method returns |num_bytes| of random data generated by the tpm.
// |delegate| specifies an optional authorization delegate to be used.
virtual TPM_RC GenerateRandom(size_t num_bytes,
AuthorizationDelegate* delegate,
std::string* random_data) = 0;
// This method extends the pcr specified by |pcr_index| with the SHA256
// hash of |extend_data|. The exact action performed is
// TPM2_PCR_Extend(Sha256(extend_data));
// |delegate| specifies an optional authorization delegate to be used.
virtual TPM_RC ExtendPCR(int pcr_index,
const std::string& extend_data,
AuthorizationDelegate* delegate) = 0;
// This method reads the pcr specified by |pcr_index| and returns its value
// in |pcr_value|. NOTE: it assumes we are using SHA256 as our hash alg.
virtual TPM_RC ReadPCR(int pcr_index, std::string* pcr_value) = 0;
// This method performs an encryption operation using a LOADED RSA key
// referrenced by its handle |key_handle|. The |plaintext| is then encrypted
// to give us the |ciphertext|. |scheme| refers to the encryption scheme
// to be used. By default keys use OAEP, but can also use TPM_ALG_RSAES.
// |delegate| specifies an optional authorization delegate to be used.
virtual TPM_RC AsymmetricEncrypt(TPM_HANDLE key_handle,
TPM_ALG_ID scheme,
TPM_ALG_ID hash_alg,
const std::string& plaintext,
AuthorizationDelegate* delegate,
std::string* ciphertext) = 0;
// This method performs a decryption operating using a loaded RSA key
// referenced by its handle |key_handle|. The |ciphertext| is then decrypted
// to give us the |plaintext|. |scheme| refers to the decryption scheme
// used. Valid schemes are: TPM_ALG_NULL, TPM_ALG_OAEP, TPM_ALG_RSAES.
// |delegate| is an AuthorizationDelegate used to authorize this command.
virtual TPM_RC AsymmetricDecrypt(TPM_HANDLE key_handle,
TPM_ALG_ID scheme,
TPM_ALG_ID hash_alg,
const std::string& ciphertext,
AuthorizationDelegate* delegate,
std::string* plaintext) = 0;
// This method takes an unrestricted signing key referenced by |key_handle|
// and uses it to sign a hash: if |generate_hash| is true then get the hash
// of |plaintext| using |hash_alg|, otherwise |plaintext| is already the hash
// to sign. The signature produced is returned using the |signature| argument.
// |scheme| is used to specify the signature scheme used. By default it is
// TPM_ALG_RSASSA, but TPM_ALG_RSAPPS and TPM_ALG_ECDSA can be specified.
// |hash_alg| is the algorithm used in the signing operation. It is by default
// TPM_ALG_SHA256. |delegate| is an AuthorizationDelegate used to authorize
// this command.
virtual TPM_RC Sign(TPM_HANDLE key_handle,
TPM_ALG_ID scheme,
TPM_ALG_ID hash_alg,
const std::string& plaintext,
bool generate_hash,
AuthorizationDelegate* delegate,
std::string* signature) = 0;
// This method is identical to Sign() above except it returns the result
// in TPMT_SIGNATURE type, not in string type.
virtual TPM_RC RawSign(TPM_HANDLE key_handle,
TPM_ALG_ID scheme,
TPM_ALG_ID hash_alg,
const std::string& plaintext,
bool generate_hash,
AuthorizationDelegate* delegate,
TPMT_SIGNATURE* auth) = 0;
// Dead code removed at CL:1366670 (https://crrev.com/c/1366670)
// It's because we doesn't use Verify() in the reality.
// We sign-with-TPM -> verify-in-software at this moment.
//
// This method verifies that the signature produced on the plaintext was
// performed by |key_handle|. |scheme| and |hash| refer to the signature
// scheme used to produce the signature: if |generate_hash| is true, the
// hash of |plaintext| is signed, otherwise |plaintext| is already the hash
// to sign. The signature scheme is by default TPM_ALG_RSASSA with
// TPM_ALG_SHA256 but can take the value of TPM_ALG_RSAPPS with other hash
// algorithms supported by the tpm. Returns TPM_RC_SUCCESS when the signature
// is correct. |delegate| specifies an optional authorization delegate to be
// used.
// virtual TPM_RC Verify(TPM_HANDLE key_handle,
// TPM_ALG_ID scheme,
// TPM_ALG_ID hash_alg,
// const std::string& plaintext,
// bool generate_hash,
// const std::string& signature,
// AuthorizationDelegate* delegate) = 0;
// This method is used to check if a key was created in the TPM. |key_handle|
// refers to a loaded Tpm2.0 object, and |creation_blob| is the blob
// generated when the object was created. Returns TPM_RC_SUCCESS iff the
// object was created in the TPM.
virtual TPM_RC CertifyCreation(TPM_HANDLE key_handle,
const std::string& creation_blob) = 0;
// This method is used to change the authorization value associated with a
// |key_handle| to |new_password|. |delegate| is an AuthorizationDelegate
// that is loaded with the old authorization value of |key_handle|.
// When |key_blob| is not null, it is populated with the new encrypted key
// blob. Note: the key must be unloaded and reloaded to use the
// new authorization value.
virtual TPM_RC ChangeKeyAuthorizationData(TPM_HANDLE key_handle,
const std::string& new_password,
AuthorizationDelegate* delegate,
std::string* key_blob) = 0;
// This method imports an external RSA key of |key_type| into the TPM.
// |modulus| and |prime_factor| are interpreted as raw bytes in big-endian
// order. If the out argument |key_blob| is not null, it is populated with
// the imported key, which can then be loaded into the TPM.
virtual TPM_RC ImportRSAKey(AsymmetricKeyUsage key_type,
const std::string& modulus,
uint32_t public_exponent,
const std::string& prime_factor,
const std::string& password,
AuthorizationDelegate* delegate,
std::string* key_blob) = 0;
// This method imports an external ECC key of |key_type| into the TPM.
// |public_point_x| and |public_point_y| are the coordinates of the public key
// point on the curve |curve_id|. |private_value| is the private key.
// |public_point_x|, |public_point_y|, and |private_value| are interpreted as
// raw bytes in big-endian. |password| is the authorization value for the
// imported key. If the out argument |key_blob| is not null, it is populated
// with the imported key, which can then be loaded into the TPM.
virtual TPM_RC ImportECCKey(AsymmetricKeyUsage key_type,
TPMI_ECC_CURVE curve_id,
const std::string& public_point_x,
const std::string& public_point_y,
const std::string& private_value,
const std::string& password,
AuthorizationDelegate* delegate,
std::string* key_blob) = 0;
// This method uses the TPM to generates an RSA key of type |key_type|.
// |modulus_bits| is used to specify the size of the modulus, and
// |public_exponent| specifies the exponent of the key. After this function
// terminates, |key_blob| contains a key blob that can be loaded into the TPM.
// |policy_digest| specifies an optional policy to use to authorize this key.
// |use_only_policy_authorization| specifies if we can use HmacSession in
// addition to PolicySession to authorize use of this key.
// |creation_pcr_indexes| allows the caller to specify a list of pcr indexes
// in the creation data.
// If the |creation_blob| out param is defined, it will contain the
// serialized creation structures generated by the TPM.
// This can be used to verify the state of the TPM during key creation.
// NOTE: if |use_only_policy_authorization| is set to true,
// parameter_encryption must be disabled when the key is used.
virtual TPM_RC CreateRSAKeyPair(
AsymmetricKeyUsage key_type,
int modulus_bits,
uint32_t public_exponent,
const std::string& password,
const std::string& policy_digest,
bool use_only_policy_authorization,
const std::vector<uint32_t>& creation_pcr_indexes,
AuthorizationDelegate* delegate,
std::string* key_blob,
std::string* creation_blob) = 0;
// This method uses the TPM to generates an ECC key of type |key_type|.
// |curve_id| is the TPM curve ID of EC curve used for the generating the key.
// |password| is the authorization value to use to authorize the generating
// key.
// |policy_digest| specifies an optional policy to use to authorize the
// generating key.
// |use_only_policy_authorization| specifies if we can use
// HmacSession in addition to PolicySession to authorize use of this key.
// |creation_pcr_indexes| allows the caller to specify a list of pcr indexes
// in the creation data.
// |delegate| is an AuthorizationDelegate used to authorize the SRK which is
// the parent of created key.
// |key_blob| contains the key blob of created key that can be loaded into the
// TPM.
// If the |creation_blob| out param is defined, it will contain the serialized
// creation structures generated by the TPM. This can be used to verify the
// state of the TPM during key creation. NOTE: if
// |use_only_policy_authorization| is set to true, parameter_encryption must
// be disabled when the key is used.
virtual TPM_RC CreateECCKeyPair(
AsymmetricKeyUsage key_type,
TPMI_ECC_CURVE curve_id,
const std::string& password,
const std::string& policy_digest,
bool use_only_policy_authorization,
const std::vector<uint32_t>& creation_pcr_indexes,
AuthorizationDelegate* delegate,
std::string* key_blob,
std::string* creation_blob) = 0;
// This method loads a pregenerated TPM key into the TPM. |key_blob| contains
// the blob returned by a key creation function. The loaded key's handle is
// returned using |key_handle|.
virtual TPM_RC LoadKey(const std::string& key_blob,
AuthorizationDelegate* delegate,
TPM_HANDLE* key_handle) = 0;
// This method loads the public part of an external RSA key into the TPM. Key
// is of type |key_type|. Algorithm scheme and hashing algorithm are passed
// via |scheme| and |hash_alg|. |modulus| is interpreted as raw bytes in
// big-endian order. |public_exponent| specifies the exponent of the key. The
// loaded key's handle is returned using |key_handle|.
virtual TPM_RC LoadRSAPublicKey(AsymmetricKeyUsage key_type,
TPM_ALG_ID scheme,
TPM_ALG_ID hash_alg,
const std::string& modulus,
uint32_t public_exponent,
AuthorizationDelegate* delegate,
TPM_HANDLE* key_handle) = 0;
// This function sets |name| to the name of the object referenced by
// |handle|. This function only works on Transient and Permanent objects.
virtual TPM_RC GetKeyName(TPM_HANDLE handle, std::string* name) = 0;
// This function returns the public area of a handle in the tpm.
virtual TPM_RC GetKeyPublicArea(TPM_HANDLE handle,
TPMT_PUBLIC* public_data) = 0;
// This method seals |data_to_seal| to the TPM. The |sealed_data| can be
// retrieved by fulfilling the policy represented by |policy_digest|. The
// session used to unseal the data will need to have the
// EntityAuthorizationValue set to |auth_value| if non-empty.
virtual TPM_RC SealData(const std::string& data_to_seal,
const std::string& policy_digest,
const std::string& auth_value,
AuthorizationDelegate* delegate,
std::string* sealed_data) = 0;
// This method is used to retrieve data that was sealed to the TPM.
// |sealed_data| refers to sealed data returned from SealData.
virtual TPM_RC UnsealData(const std::string& sealed_data,
AuthorizationDelegate* delegate,
std::string* unsealed_data) = 0;
// This method sets up a given HmacSession with parameter encryption set to
// true. Returns an TPM_RC_SUCCESS on success.
virtual TPM_RC StartSession(HmacSession* session) = 0;
// This method uses a trial session to compute the |policy_digest| when
// the policy is bound to a given map of pcr_index -> pcr_value in |pcr_map|.
// If some values in the map are empty, the method uses the current value of
// the pcr for the corresponding indexes. If |use_auth_value| is set to true
// then a authorization value will be required when using the digest. In this
// case PolicyAuthValue is called on session first, and PolicyPCR is called
// after this. Those two calls must be made in the same order when we need to
// reveal the secret guarded by the authorization value.
virtual TPM_RC GetPolicyDigestForPcrValues(
const std::map<uint32_t, std::string>& pcr_map,
bool use_auth_value,
std::string* policy_digest) = 0;
// This method defines a non-volatile storage area in the TPM, referenced
// by |index| of size |num_bytes|. This command needs owner authorization.
// The |attributes| of the space must be specified as a combination of
// TPMA_NV_* values. Optionally, an |authorization_value| and / or
// |policy_digest| can be specified which will be associated with the space.
// These values must either be a valid SHA256 digest (or empty).
virtual TPM_RC DefineNVSpace(uint32_t index,
size_t num_bytes,
TPMA_NV attributes,
const std::string& authorization_value,
const std::string& policy_digest,
AuthorizationDelegate* delegate) = 0;
// This method destroys the non-volatile space referred to by |index|.
// This command needs owner authorization.
virtual TPM_RC DestroyNVSpace(uint32_t index,
AuthorizationDelegate* delegate) = 0;
// This method locks the non-volatile space referred to by |index|. The caller
// needs indicate whether they want to |lock_read| and / or |lock_write|. They
// also need to indicate if they are |using_owner_authorization|.
virtual TPM_RC LockNVSpace(uint32_t index,
bool lock_read,
bool lock_write,
bool using_owner_authorization,
AuthorizationDelegate* delegate) = 0;
// This method writes |nvram_data| to the non-volatile space referenced by
// |index|, at |offset| bytes from the start of the non-volatile space. The
// caller needs to indicate if they are |using_owner_authorization|. If
// |extend| is set, the value will be extended and offset ignored.
virtual TPM_RC WriteNVSpace(uint32_t index,
uint32_t offset,
const std::string& nvram_data,
bool using_owner_authorization,
bool extend,
AuthorizationDelegate* delegate) = 0;
// This method reads |num_bytes| of data from the |offset| located at the
// non-volatile space defined by |index|. This method returns an error if
// |length| + |offset| is larger than the size of the defined non-volatile
// space. The caller needs to indicate if they are |using_owner_authorization|
virtual TPM_RC ReadNVSpace(uint32_t index,
uint32_t offset,
size_t num_bytes,
bool using_owner_authorization,
std::string* nvram_data,
AuthorizationDelegate* delegate) = 0;
// This function sets |name| to the name of the non-volatile space referenced
// by |index|.
virtual TPM_RC GetNVSpaceName(uint32_t index, std::string* name) = 0;
// This function returns the public area of an non-volatile space defined in
// the TPM.
virtual TPM_RC GetNVSpacePublicArea(uint32_t index,
TPMS_NV_PUBLIC* public_data) = 0;
// Lists all defined NV indexes.
virtual TPM_RC ListNVSpaces(std::vector<uint32_t>* index_list) = 0;
// Sets dictionary attack parameters. Requires lockout authorization.
// Parameters map directly to TPM2_DictionaryAttackParameters in the TPM 2.0
// specification.
virtual TPM_RC SetDictionaryAttackParameters(
uint32_t max_tries,
uint32_t recovery_time,
uint32_t lockout_recovery,
AuthorizationDelegate* delegate) = 0;
// Reset dictionary attack lockout. Requires lockout authorization.
virtual TPM_RC ResetDictionaryAttackLock(AuthorizationDelegate* delegate) = 0;
// Gets the endorsement key of a given |key_type|, creating the key as needed
// If the |key_type| is RSA, the key will be made persistent. On success
// returns TPM_RC_SUCCESS and populates |key_handle|. Requires endorsement
// authorization to create the key and owner authorization to make the key
// persistent (RSA only). The |owner_delegate| is ignored if |key_type| is not
// RSA or if the key is already persistent.
virtual TPM_RC GetEndorsementKey(TPM_ALG_ID key_type,
AuthorizationDelegate* endorsement_delegate,
AuthorizationDelegate* owner_delegate,
TPM_HANDLE* key_handle) = 0;
// Creates an asymmetric restricted signing key of the given |key_type|.
// On success returns TPM_RC_SUCCESS and populates |key_blob|.
virtual TPM_RC CreateIdentityKey(TPM_ALG_ID key_type,
AuthorizationDelegate* delegate,
std::string* key_blob) = 0;
// For TPMs with updateable firmware: Declate the current firmware
// version stable and invalidate previous versions, if any.
// Returns the result of sending the appropriate command to the TPM.
// For TPMs with fixed firmware: NOP, always returns TPM_RC_SUCCESS.
virtual TPM_RC DeclareTpmFirmwareStable() = 0;
// Reads the RSA certificate from nvram space and extracts the public key
// modulus into |ekm|. Returns TPM_RC_SUCCESS on success.
virtual TPM_RC GetPublicRSAEndorsementKeyModulus(std::string* ekm) = 0;
// For TPMs that support it: allow setting the CCD password if |allow_pwd|
// is true, prohibit otherwise.
// Returns the result of sending the appropriate command to the TPM.
// For TPMs that don't support it: NOP, always returns TPM_RC_SUCCESS.
// Rationale for this behavior: All TPM revisions that need restricting CCD
// password implement this command. If the command is not implemented, the
// TPM firmware has no notion of restricting the CCD password and doesn't need
// a signal to lock things down at login.
virtual TPM_RC ManageCCDPwd(bool allow_pwd) = 0;
// Reads TPM alerts information from the chip.
// If alerts->chip_family equals to kFamilyUndefined then
// this operation is not supported by the chip.
// Returns TPM_RC_SUCCESS on success.
virtual TPM_RC GetAlertsData(TpmAlertsData* alerts) = 0;
// Input parameter:
// |request_version| is the pinweaver protocol version that cryptohome
// knows about.
// Output parameters:
// |protocol_version| is the current protocol version used by pinweaver.
// Returns TPM_RC_SUCCESS if PinWeaver is supported.
virtual TPM_RC PinWeaverIsSupported(uint8_t request_version,
uint8_t* protocol_version) = 0;
// Create an empty Merkle tree with the given parameters.
// On success:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to EC_SUCCESS (0).
// |root_hash| is set to the root hash of the empty tree with the given
// parameters.
// On failure:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to one of pw_error_codes_enum.
// |root_hash| is set to the root hash of the empty tree with the given.
// parameters.
virtual TPM_RC PinWeaverResetTree(uint8_t protocol_version,
uint8_t bits_per_level,
uint8_t height,
uint32_t* result_code,
std::string* root_hash) = 0;
// Insert a leaf to the Merkle tree where:
// |protocol_version| is the protocol version used to comunicate with
// pinweaver.
// |label| is the location of the leaf in the tree.
// |h_aux| is the auxiliary hashes started from the bottom of the tree
// working toward the root in index order.
// |le_secret| is the low entropy secret that is limited by the delay
// schedule.
// |he_secret| is the high entropy secret that is protected by Cr50 and
// returned on successful authentication.
// |reset_secret| is the high entropy secret used to reset the attempt
// counters and authenticate without following the delay schedule.
// |delay_schedule| is constructed of (attempt_count, time_delay) with at
// most PW_SCHED_COUNT entries.
// |valid_pcr_criteria| is list of at most PW_MAX_PCR_CRITERIA_COUNT entries
// where each entry represents a bitmask of PCR indexes and the expected
// digest corresponding to those PCR.
// On success:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to EC_SUCCESS (0).
// |root_hash| is set to the updated root hash of the tree.
// |cred_metadata| is set to the wrapped leaf data.
// |mac| is set to the HMAC used in the Merkle tree calculations.
// On failure:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to one of pw_error_codes_enum.
// |root_hash| is set to the unchanged root hash of the tree.
// |cred_metadata| and |mac| are both empty.
virtual TPM_RC PinWeaverInsertLeaf(
uint8_t protocol_version,
uint64_t label,
const std::string& 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,
uint32_t* result_code,
std::string* root_hash,
std::string* cred_metadata,
std::string* mac) = 0;
// Remove a leaf from the Merkle tree where:
// |protocol_version| is the protocol version used to comunicate with
// pinweaver.
// |label| is the location of the leaf in the tree.
// |h_aux| is the auxiliary hashes started from the bottom of the tree
// working toward the root in index order.
// |mac| is set to the HMAC used in the Merkle tree calculations.
// On success:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to EC_SUCCESS (0).
// |root_hash| is set to the updated root hash of the tree.
// On failure:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to one of pw_error_codes_enum.
// |root_hash| is set to the unchanged root hash of the tree.
virtual TPM_RC PinWeaverRemoveLeaf(uint8_t protocol_version,
uint64_t label,
const std::string& h_aux,
const std::string& mac,
uint32_t* result_code,
std::string* root_hash) = 0;
// Attempts to authenticate a leaf from the Merkle tree where:
// |protocol_version| is the protocol version used to comunicate with
// pinweaver.
// |le_secret| is the low entropy secret that is limited by the delay
// schedule.
// |h_aux| is the auxiliary hashes started from the bottom of the tree
// working toward the root in index order.
// |cred_metadata| is set to the wrapped leaf data.
// On auth success:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to EC_SUCCESS (0).
// |root_hash| is set to the updated root hash of the tree.
// |he_secret| is the high entropy secret that is protected by Cr50 and
// returned on successful authentication.
// |reset_secret| is the reset secret that is protected by Cr50 and
// returned on successful authentication.
// |cred_metadata_out| is set to the updated wrapped leaf data.
// |mac_out| is set to the updated HMAC used in the Merkle tree
// calculations.
// |seconds_to_wait| is 0
// On auth fail:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to PW_ERR_LOWENT_AUTH_FAILED.
// |root_hash| is set to the updated root hash of the tree.
// |cred_metadata_out| is set to the updated wrapped leaf data.
// |mac_out| is set to the updated HMAC used in the Merkle tree
// calculations.
// |seconds_to_wait| is 0
// |he_secret| and |reset_secret| are empty.
// On rate limited:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to PW_ERR_RATE_LIMIT_REACHED.
// |root_hash| is set to the unchanged root hash of the tree.
// |seconds_to_wait| is set to the seconds required before an authentication
// attempt can be made.
// |he_secret|, |reset_secret|, |cred_metadata_out|, and |mac| are all
// empty.
// On error:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to one of pw_error_codes_enum.
// |root_hash| is set to the unchanged root hash of the tree.
// |seconds_to_wait| is 0
// |he_secret|, |reset_secret|, |cred_metadata_out|, and |mac| are all
// empty.
//
// Note that for the invalid fields |seconds_to_wait| will be zero and the
// rest will be cleared (e.g. zero length), so it isn't necessary to check
// |result_code| to determine if fields are valid or not.
virtual TPM_RC PinWeaverTryAuth(uint8_t protocol_version,
const brillo::SecureBlob& le_secret,
const std::string& h_aux,
const std::string& cred_metadata,
uint32_t* result_code,
std::string* root_hash,
uint32_t* seconds_to_wait,
brillo::SecureBlob* he_secret,
brillo::SecureBlob* reset_secret,
std::string* cred_metadata_out,
std::string* mac_out) = 0;
// Attempts to reset a leaf from the Merkle tree where:
// |protocol_version| is the protocol version used to comunicate with
// pinweaver.
// |reset_secret| is the high entropy secret used to reset the attempt
// counters and authenticate without following the delay schedule.
// |h_aux| is the auxiliary hashes started from the bottom of the tree
// working toward the root in index order.
// |cred_metadata| is set to the wrapped leaf data.
// On auth success:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to EC_SUCCESS (0).
// |root_hash| is set to the updated root hash of the tree.
// |he_secret| is the high entropy secret that is protected by Cr50 and
// returned on successful authentication.
// |cred_metadata_out| is set to the updated wrapped leaf data.
// |mac_out| is set to the updated HMAC used in the Merkle tree
// calculations.
// On auth fail or error:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to one of pw_error_codes_enum.
// |root_hash| is set to the unchanged root hash of the tree.
// |he_secret|, |cred_metadata_out|, and |mac| are all empty.
virtual TPM_RC PinWeaverResetAuth(uint8_t protocol_version,
const brillo::SecureBlob& reset_secret,
const std::string& h_aux,
const std::string& cred_metadata,
uint32_t* result_code,
std::string* root_hash,
brillo::SecureBlob* he_secret,
std::string* cred_metadata_out,
std::string* mac_out) = 0;
// Retrieves the log of recent operations where:
// |protocol_version| is the protocol version used to comunicate with
// pinweaver.
// |root| is the last known root hash.
// On success:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to EC_SUCCESS (0).
// |root_hash| is set to the unchanged root hash of the tree.
// |log| is set to operations since |root| (inclusive) or the entire log if
// |root| isn't found.
// On error:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to one of pw_error_codes_enum.
// |root_hash| is set to the unchanged root hash of the tree.
// |log| is empty.
virtual TPM_RC PinWeaverGetLog(
uint8_t protocol_version,
const std::string& root,
uint32_t* result_code,
std::string* root_hash,
std::vector<trunks::PinWeaverLogEntry>* log) = 0;
// Attempts to replay a previous transaction from the PinWeaver log where:
// |log_root| is the root hash of the log entry to be replayed.
// |h_aux| is the auxiliary hashes started from the bottom of the tree
// working toward the root in index order.
// |cred_metadata| is set to the wrapped leaf data.
// On success:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to EC_SUCCESS (0).
// |root_hash| is set to the unchanged root hash of the tree.
// |cred_metadata_out| is set to the updated wrapped leaf data.
// |mac_out| is set to the updated HMAC used in the Merkle tree
// calculations.
// On error:
// returns VENDOR_RC_SUCCESS
// |result_code| is set to one of pw_error_codes_enum.
// |root_hash| is set to the unchanged root hash of the tree.
virtual TPM_RC PinWeaverLogReplay(uint8_t protocol_version,
const std::string& log_root,
const std::string& h_aux,
const std::string& cred_metadata,
uint32_t* result_code,
std::string* root_hash,
std::string* cred_metadata_out,
std::string* mac_out) = 0;
// Retrieves cached RSU device id.
virtual TPM_RC GetRsuDeviceId(std::string* device_id) = 0;
private:
DISALLOW_COPY_AND_ASSIGN(TpmUtility);
};
} // namespace trunks
#endif // TRUNKS_TPM_UTILITY_H_