//
// Copyright (C) 2014 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#ifndef TRUNKS_TPM_UTILITY_H_
#define TRUNKS_TPM_UTILITY_H_
#include <string>
#include <base/macros.h>
#include "trunks/hmac_session.h"
#include "trunks/tpm_generated.h"
#include "trunks/trunks_export.h"
namespace trunks {
// These handles will be used by TpmUtility to create storage root keys.
const TPMI_DH_PERSISTENT kRSAStorageRootKey = PERSISTENT_FIRST;
const TPMI_DH_PERSISTENT kECCStorageRootKey = PERSISTENT_FIRST + 1;
const TPMI_DH_PERSISTENT kSaltingKey = PERSISTENT_FIRST + 2;
// This value to used to specify that no pcr are needed in the creation data
// for a key.
const int kNoCreationPCR = -1;
// 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;
// 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;
// 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 decyption 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. By default it is OAEP, but TPM_ALG_RSAES can be specified.
// |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 the hash of |plaintext|. 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
// 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,
AuthorizationDelegate* delegate,
std::string* signature) = 0;
// 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 sign the hash of |plaintext| and produce the signature.
// This value 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,
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 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_index| allows the caller to specify a pcr value to include
// in the creation data. If no pcr are needed in the creation data, this
// argument can take the value of kNoCreationPCR.
// 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,
int creation_pcr_index,
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 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
// retreived by fulfilling the policy represented by |policy_digest|.
virtual TPM_RC SealData(const std::string& data_to_seal,
const std::string& policy_digest,
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 |pcr_value| at |pcr_index|. If |pcr_value|
// is the empty string, this method uses the currect value of the pcr.
virtual TPM_RC GetPolicyDigestForPcrValue(int pcr_index,
const std::string& pcr_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.
// By default non-volatile space created is unlocked and anyone can write to
// it. The space can be permanently locked for writing by calling the
// LockNVSpace method.
virtual TPM_RC DefineNVSpace(uint32_t index,
size_t num_bytes,
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|. After a
// non-volatile space has been locked, it cannot be written to. Locked spaces
// can still be freely read. This command needs owner authorization.
virtual TPM_RC LockNVSpace(uint32_t index,
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.
virtual TPM_RC WriteNVSpace(uint32_t index,
uint32_t offset,
const std::string& nvram_data,
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.
virtual TPM_RC ReadNVSpace(uint32_t index,
uint32_t offset,
size_t num_bytes,
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;
private:
DISALLOW_COPY_AND_ASSIGN(TpmUtility);
};
} // namespace trunks
#endif // TRUNKS_TPM_UTILITY_H_