1bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// 2bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// Copyright (C) 2014 The Android Open Source Project 3bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// 4bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// Licensed under the Apache License, Version 2.0 (the "License"); 5bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// you may not use this file except in compliance with the License. 6bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// You may obtain a copy of the License at 7bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// 8bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// http://www.apache.org/licenses/LICENSE-2.0 9bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// 10bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// Unless required by applicable law or agreed to in writing, software 11bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// distributed under the License is distributed on an "AS IS" BASIS, 12bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// See the License for the specific language governing permissions and 14bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// limitations under the License. 15bbef5dff2b94fef72012e721cd6124cd87621af4Utkarsh Sanghi// 16c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 17c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn#ifndef TRUNKS_TPM_UTILITY_H_ 18c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn#define TRUNKS_TPM_UTILITY_H_ 19c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 20e31034f28641c9bc3e5576cab6d2c7d918bb427cUtkarsh Sanghi#include <string> 21b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn#include <vector> 22e31034f28641c9bc3e5576cab6d2c7d918bb427cUtkarsh Sanghi 23c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn#include <base/macros.h> 24c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 25a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi#include "trunks/hmac_session.h" 26c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn#include "trunks/tpm_generated.h" 27ef87f3e63b93ff722a8cbcee9c54d55d085221a3Darren Krahn#include "trunks/trunks_export.h" 28c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 29c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahnnamespace trunks { 30c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 3152e2a45f585fbe34032eae5b094a092afdf217caDarren Krahn// These handles will be used by TpmUtility to create storage root keys. 3252e2a45f585fbe34032eae5b094a092afdf217caDarren Krahnconst TPMI_DH_PERSISTENT kRSAStorageRootKey = PERSISTENT_FIRST; 3352e2a45f585fbe34032eae5b094a092afdf217caDarren Krahnconst TPMI_DH_PERSISTENT kECCStorageRootKey = PERSISTENT_FIRST + 1; 342ee32a9d61896f544d87ecee24dc25cc33c9ebb3Utkarsh Sanghiconst TPMI_DH_PERSISTENT kSaltingKey = PERSISTENT_FIRST + 2; 3552e2a45f585fbe34032eae5b094a092afdf217caDarren Krahn 360ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghi// This value to used to specify that no pcr are needed in the creation data 370ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghi// for a key. 380ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghiconst int kNoCreationPCR = -1; 390ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghi 4003d54dfbcbdd04384e8c0419b7c45282664a2c1aDarren Krahn// An interface which provides convenient methods for common TPM operations. 41ef87f3e63b93ff722a8cbcee9c54d55d085221a3Darren Krahnclass TRUNKS_EXPORT TpmUtility { 42c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn public: 434dc4629c415e7ca90ff146d7bb75b5646ecd8b17Darren Krahn enum AsymmetricKeyUsage { kDecryptKey, kSignKey, kDecryptAndSignKey }; 4482b03cf80cbe7ab5d5edb2cb46d245721e993a68Utkarsh Sanghi 45c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn TpmUtility() {} 46c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn virtual ~TpmUtility() {} 47c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 4803d54dfbcbdd04384e8c0419b7c45282664a2c1aDarren Krahn // Synchronously performs a TPM startup sequence and self tests. Typically 4903d54dfbcbdd04384e8c0419b7c45282664a2c1aDarren Krahn // this is done by the platform firmware. Returns the result of the startup 5003d54dfbcbdd04384e8c0419b7c45282664a2c1aDarren Krahn // and self-tests or, if already started, just the result of the self-tests. 5103d54dfbcbdd04384e8c0419b7c45282664a2c1aDarren Krahn virtual TPM_RC Startup() = 0; 5203d54dfbcbdd04384e8c0419b7c45282664a2c1aDarren Krahn 53d75dcae8a010d1ced7554dd25a440bee350a2d06Utkarsh Sanghi // This method removes all TPM context associated with a specific Owner. 54d75dcae8a010d1ced7554dd25a440bee350a2d06Utkarsh Sanghi // As part of this process, it resets the SPS to a new random value, and 55d75dcae8a010d1ced7554dd25a440bee350a2d06Utkarsh Sanghi // clears ownerAuth, endorsementAuth and lockoutAuth. 56d75dcae8a010d1ced7554dd25a440bee350a2d06Utkarsh Sanghi // NOTE: This method needs to be called before InitializeTPM. 57d75dcae8a010d1ced7554dd25a440bee350a2d06Utkarsh Sanghi virtual TPM_RC Clear() = 0; 58d75dcae8a010d1ced7554dd25a440bee350a2d06Utkarsh Sanghi 59e8b9a556d4561617747fed4ee5ced70fce9a4392Utkarsh Sanghi // Synchronously performs a TPM shutdown operation. It should always be 60e8b9a556d4561617747fed4ee5ced70fce9a4392Utkarsh Sanghi // successful. 61e8b9a556d4561617747fed4ee5ced70fce9a4392Utkarsh Sanghi virtual void Shutdown() = 0; 62e8b9a556d4561617747fed4ee5ced70fce9a4392Utkarsh Sanghi 6303d54dfbcbdd04384e8c0419b7c45282664a2c1aDarren Krahn // Synchronously prepares a TPM for use by Chromium OS. Typically this is done 6403d54dfbcbdd04384e8c0419b7c45282664a2c1aDarren Krahn // by the platform firmware and, in that case, this method has no effect. 65c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn virtual TPM_RC InitializeTpm() = 0; 66c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 67e7eb2bf306af6e8408cd77125861542d19e5ec6dUtkarsh Sanghi // Synchronously allocates the PCRs in the TPM. Currently we allocate 68e7eb2bf306af6e8408cd77125861542d19e5ec6dUtkarsh Sanghi // the first 16 PCRs to use the SHA-256 hash algorithm. 69e7eb2bf306af6e8408cd77125861542d19e5ec6dUtkarsh Sanghi // NOTE: PCR allocation only takes place at the next TPM_Startup call. 70e7eb2bf306af6e8408cd77125861542d19e5ec6dUtkarsh Sanghi // NOTE: This command needs platform authorization and PP assertion. 71e7eb2bf306af6e8408cd77125861542d19e5ec6dUtkarsh Sanghi virtual TPM_RC AllocatePCR(const std::string& platform_password) = 0; 72e7eb2bf306af6e8408cd77125861542d19e5ec6dUtkarsh Sanghi 732ee32a9d61896f544d87ecee24dc25cc33c9ebb3Utkarsh Sanghi // Synchronously takes ownership of the TPM with the given passwords as 742ee32a9d61896f544d87ecee24dc25cc33c9ebb3Utkarsh Sanghi // authorization values. 752ee32a9d61896f544d87ecee24dc25cc33c9ebb3Utkarsh Sanghi virtual TPM_RC TakeOwnership(const std::string& owner_password, 762ee32a9d61896f544d87ecee24dc25cc33c9ebb3Utkarsh Sanghi const std::string& endorsement_password, 772ee32a9d61896f544d87ecee24dc25cc33c9ebb3Utkarsh Sanghi const std::string& lockout_password) = 0; 782ee32a9d61896f544d87ecee24dc25cc33c9ebb3Utkarsh Sanghi 79e31034f28641c9bc3e5576cab6d2c7d918bb427cUtkarsh Sanghi // Stir the tpm random generation module with some random entropy data. 805d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi // |delegate| specifies an optional authorization delegate to be used. 818b2bf63478b292937f85b3b0e215882af461a999Utkarsh Sanghi virtual TPM_RC StirRandom(const std::string& entropy_data, 825d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate) = 0; 83e31034f28641c9bc3e5576cab6d2c7d918bb427cUtkarsh Sanghi 84e31034f28641c9bc3e5576cab6d2c7d918bb427cUtkarsh Sanghi // This method returns |num_bytes| of random data generated by the tpm. 855d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi // |delegate| specifies an optional authorization delegate to be used. 868b2bf63478b292937f85b3b0e215882af461a999Utkarsh Sanghi virtual TPM_RC GenerateRandom(size_t num_bytes, 875d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate, 888b2bf63478b292937f85b3b0e215882af461a999Utkarsh Sanghi std::string* random_data) = 0; 89e31034f28641c9bc3e5576cab6d2c7d918bb427cUtkarsh Sanghi 90579dd8a934c684f2e2a34d9aa2f67953320428acUtkarsh Sanghi // This method extends the pcr specified by |pcr_index| with the SHA256 91579dd8a934c684f2e2a34d9aa2f67953320428acUtkarsh Sanghi // hash of |extend_data|. The exact action performed is 92579dd8a934c684f2e2a34d9aa2f67953320428acUtkarsh Sanghi // TPM2_PCR_Extend(Sha256(extend_data)); 935d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi // |delegate| specifies an optional authorization delegate to be used. 948b2bf63478b292937f85b3b0e215882af461a999Utkarsh Sanghi virtual TPM_RC ExtendPCR(int pcr_index, 958b2bf63478b292937f85b3b0e215882af461a999Utkarsh Sanghi const std::string& extend_data, 965d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate) = 0; 97579dd8a934c684f2e2a34d9aa2f67953320428acUtkarsh Sanghi 98579dd8a934c684f2e2a34d9aa2f67953320428acUtkarsh Sanghi // This method reads the pcr specified by |pcr_index| and returns its value 99579dd8a934c684f2e2a34d9aa2f67953320428acUtkarsh Sanghi // in |pcr_value|. NOTE: it assumes we are using SHA256 as our hash alg. 100579dd8a934c684f2e2a34d9aa2f67953320428acUtkarsh Sanghi virtual TPM_RC ReadPCR(int pcr_index, std::string* pcr_value) = 0; 101579dd8a934c684f2e2a34d9aa2f67953320428acUtkarsh Sanghi 102b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi // This method performs an encryption operation using a LOADED RSA key 103b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi // referrenced by its handle |key_handle|. The |plaintext| is then encrypted 104b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi // to give us the |ciphertext|. |scheme| refers to the encryption scheme 105748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi // to be used. By default keys use OAEP, but can also use TPM_ALG_RSAES. 1065d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi // |delegate| specifies an optional authorization delegate to be used. 107b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi virtual TPM_RC AsymmetricEncrypt(TPM_HANDLE key_handle, 108b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi TPM_ALG_ID scheme, 1099dc77fecdb2446da134b9b2901173bb4dcf5e5e4Utkarsh Sanghi TPM_ALG_ID hash_alg, 110b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi const std::string& plaintext, 1115d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate, 112b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi std::string* ciphertext) = 0; 113b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi 114b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // This method performs a decryption operating using a loaded RSA key 115b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi // referenced by its handle |key_handle|. The |ciphertext| is then decrypted 1161ef82e4a52abc91d0e8db12500c2da0d8c21f62cUtkarsh Sanghi // to give us the |plaintext|. |scheme| refers to the decryption scheme 1171ef82e4a52abc91d0e8db12500c2da0d8c21f62cUtkarsh Sanghi // used. By default it is OAEP, but TPM_ALG_RSAES can be specified. 1185d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi // |delegate| is an AuthorizationDelegate used to authorize this command. 119b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi virtual TPM_RC AsymmetricDecrypt(TPM_HANDLE key_handle, 120b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi TPM_ALG_ID scheme, 1219dc77fecdb2446da134b9b2901173bb4dcf5e5e4Utkarsh Sanghi TPM_ALG_ID hash_alg, 122b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi const std::string& ciphertext, 1235d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate, 124b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi std::string* plaintext) = 0; 125b3ba5e0b579a5462c7137cf49b49cc9a78d87944Utkarsh Sanghi 126748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi // This method takes an unrestricted signing key referenced by |key_handle| 127887ccbcc4db5fa0b5221018296aa49b86a5ac26fUtkarsh Sanghi // and uses it to sign the hash of |plaintext|. The signature produced is 1281ef82e4a52abc91d0e8db12500c2da0d8c21f62cUtkarsh Sanghi // returned using the |signature| argument. |scheme| is used to specify the 1291ef82e4a52abc91d0e8db12500c2da0d8c21f62cUtkarsh Sanghi // signature scheme used. By default it is TPM_ALG_RSASSA, but TPM_ALG_RSAPPS 1301ef82e4a52abc91d0e8db12500c2da0d8c21f62cUtkarsh Sanghi // can be specified. |hash_alg| is the algorithm used in the signing 1315d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi // operation. It is by default TPM_ALG_SHA256. 1325d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi // |delegate| is an AuthorizationDelegate used to authorize this command. 133748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi virtual TPM_RC Sign(TPM_HANDLE key_handle, 134748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi TPM_ALG_ID scheme, 135748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi TPM_ALG_ID hash_alg, 136887ccbcc4db5fa0b5221018296aa49b86a5ac26fUtkarsh Sanghi const std::string& plaintext, 1375d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate, 138748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi std::string* signature) = 0; 139748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi 140887ccbcc4db5fa0b5221018296aa49b86a5ac26fUtkarsh Sanghi // This method verifies that the signature produced on the plaintext was 141748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi // performed by |key_handle|. |scheme| and |hash| refer to the signature 142887ccbcc4db5fa0b5221018296aa49b86a5ac26fUtkarsh Sanghi // scheme used to sign the hash of |plaintext| and produce the signature. 143887ccbcc4db5fa0b5221018296aa49b86a5ac26fUtkarsh Sanghi // This value is by default TPM_ALG_RSASSA with TPM_ALG_SHA256 but can take 144887ccbcc4db5fa0b5221018296aa49b86a5ac26fUtkarsh Sanghi // the value of TPM_ALG_RSAPPS with other hash algorithms supported by the 145887ccbcc4db5fa0b5221018296aa49b86a5ac26fUtkarsh Sanghi // tpm. Returns TPM_RC_SUCCESS when the signature is correct. 1466f68562edf5f66006c08de24d558732d6a389631Utkarsh Sanghi // |delegate| specifies an optional authorization delegate to be used. 147748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi virtual TPM_RC Verify(TPM_HANDLE key_handle, 148748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi TPM_ALG_ID scheme, 149748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi TPM_ALG_ID hash_alg, 150887ccbcc4db5fa0b5221018296aa49b86a5ac26fUtkarsh Sanghi const std::string& plaintext, 1516f68562edf5f66006c08de24d558732d6a389631Utkarsh Sanghi const std::string& signature, 1526f68562edf5f66006c08de24d558732d6a389631Utkarsh Sanghi AuthorizationDelegate* delegate) = 0; 153748f7d68284813a78b883f9c05988f6de535fc8aUtkarsh Sanghi 154fded77411da5ef66dff7389e49f40900c19d510cUtkarsh Sanghi // This method is used to check if a key was created in the TPM. |key_handle| 155fded77411da5ef66dff7389e49f40900c19d510cUtkarsh Sanghi // refers to a loaded Tpm2.0 object, and |creation_blob| is the blob 156fded77411da5ef66dff7389e49f40900c19d510cUtkarsh Sanghi // generated when the object was created. Returns TPM_RC_SUCCESS iff the 157fded77411da5ef66dff7389e49f40900c19d510cUtkarsh Sanghi // object was created in the TPM. 158fded77411da5ef66dff7389e49f40900c19d510cUtkarsh Sanghi virtual TPM_RC CertifyCreation(TPM_HANDLE key_handle, 159fded77411da5ef66dff7389e49f40900c19d510cUtkarsh Sanghi const std::string& creation_blob) = 0; 160fded77411da5ef66dff7389e49f40900c19d510cUtkarsh Sanghi 16133ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi // This method is used to change the authorization value associated with a 1625d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi // |key_handle| to |new_password|. |delegate| is an AuthorizationDelegate 1631ef82e4a52abc91d0e8db12500c2da0d8c21f62cUtkarsh Sanghi // that is loaded with the old authorization value of |key_handle|. 16433ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi // When |key_blob| is not null, it is populated with the new encrypted key 16533ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi // blob. Note: the key must be unloaded and reloaded to use the 16633ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi // new authorization value. 16733ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi virtual TPM_RC ChangeKeyAuthorizationData(TPM_HANDLE key_handle, 16833ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi const std::string& new_password, 1695d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate, 17033ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi std::string* key_blob) = 0; 17133ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi 17233ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi // This method imports an external RSA key of |key_type| into the TPM. 17333ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi // |modulus| and |prime_factor| are interpreted as raw bytes in big-endian 17433ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi // order. If the out argument |key_blob| is not null, it is populated with 17533ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi // the imported key, which can then be loaded into the TPM. 17633ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi virtual TPM_RC ImportRSAKey(AsymmetricKeyUsage key_type, 17733ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi const std::string& modulus, 17833ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi uint32_t public_exponent, 17933ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi const std::string& prime_factor, 18033ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi const std::string& password, 1815d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate, 18233ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi std::string* key_blob) = 0; 18333ca033c9665b8496f3491037403ae1574a54227Utkarsh Sanghi 1846465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // This method uses the TPM to generates an RSA key of type |key_type|. 1856465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // |modulus_bits| is used to specify the size of the modulus, and 1866465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // |public_exponent| specifies the exponent of the key. After this function 1876465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // terminates, |key_blob| contains a key blob that can be loaded into the TPM. 188fc942a5ffc967b7b2b206aee8b91b3bae1933382Utkarsh Sanghi // |policy_digest| specifies an optional policy to use to authorize this key. 1896ea135676cf391fac45b0051242ccac935c8bc62Utkarsh Sanghi // |use_only_policy_authorization| specifies if we can use HmacSession in 1906ea135676cf391fac45b0051242ccac935c8bc62Utkarsh Sanghi // addition to PolicySession to authorize use of this key. 1910ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghi // |creation_pcr_index| allows the caller to specify a pcr value to include 1920ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghi // in the creation data. If no pcr are needed in the creation data, this 1930ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghi // argument can take the value of kNoCreationPCR. 194a5a2f2ea49e0085bf8d7f6f2b6e7cd624d710c01Utkarsh Sanghi // If the |creation_blob| out param is defined, it will contain the 195a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // serialized creation structures generated by the TPM. 1960ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghi // This can be used to verify the state of the TPM during key creation. 1976ea135676cf391fac45b0051242ccac935c8bc62Utkarsh Sanghi // NOTE: if |use_only_policy_authorization| is set to true, 1986ea135676cf391fac45b0051242ccac935c8bc62Utkarsh Sanghi // parameter_encryption must be disabled when the key is used. 1996465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi virtual TPM_RC CreateRSAKeyPair(AsymmetricKeyUsage key_type, 2006465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi int modulus_bits, 2016465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi uint32_t public_exponent, 2026465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi const std::string& password, 203fc942a5ffc967b7b2b206aee8b91b3bae1933382Utkarsh Sanghi const std::string& policy_digest, 2046ea135676cf391fac45b0051242ccac935c8bc62Utkarsh Sanghi bool use_only_policy_authorization, 2050ebbc58fe6d45378a5b502c33eb1c4289fd8b05bUtkarsh Sanghi int creation_pcr_index, 2065d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate, 207a5a2f2ea49e0085bf8d7f6f2b6e7cd624d710c01Utkarsh Sanghi std::string* key_blob, 208a5a2f2ea49e0085bf8d7f6f2b6e7cd624d710c01Utkarsh Sanghi std::string* creation_blob) = 0; 2096465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi 2106465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // This method loads a pregenerated TPM key into the TPM. |key_blob| contains 2116465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // the blob returned by a key creation function. The loaded key's handle is 2126465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // returned using |key_handle|. 2136465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi virtual TPM_RC LoadKey(const std::string& key_blob, 2145d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate, 2156465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi TPM_HANDLE* key_handle) = 0; 2166465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi 2176465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // This function sets |name| to the name of the object referenced by 2186465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // |handle|. This function only works on Transient and Permanent objects. 2196465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi virtual TPM_RC GetKeyName(TPM_HANDLE handle, std::string* name) = 0; 2206465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi 2216465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi // This function returns the public area of a handle in the tpm. 2226465502c740d2599d95e09232c744f6d2ed54505Utkarsh Sanghi virtual TPM_RC GetKeyPublicArea(TPM_HANDLE handle, 2238b2bf63478b292937f85b3b0e215882af461a999Utkarsh Sanghi TPMT_PUBLIC* public_data) = 0; 22482b03cf80cbe7ab5d5edb2cb46d245721e993a68Utkarsh Sanghi 225a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // This method seals |data_to_seal| to the TPM. The |sealed_data| can be 226a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // retreived by fulfilling the policy represented by |policy_digest|. 227a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi virtual TPM_RC SealData(const std::string& data_to_seal, 228a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi const std::string& policy_digest, 229a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi AuthorizationDelegate* delegate, 230a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi std::string* sealed_data) = 0; 231a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi 232a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // This method is used to retrieve data that was sealed to the TPM. 233a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // |sealed_data| refers to sealed data returned from SealData. 234a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi virtual TPM_RC UnsealData(const std::string& sealed_data, 235a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi AuthorizationDelegate* delegate, 236a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi std::string* unsealed_data) = 0; 237a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi 238a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // This method sets up a given HmacSession with parameter encryption set to 239a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // true. Returns an TPM_RC_SUCCESS on success. 240a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi virtual TPM_RC StartSession(HmacSession* session) = 0; 241a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi 242a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // This method uses a trial session to compute the |policy_digest| when 243a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // the policy is bound to a given |pcr_value| at |pcr_index|. If |pcr_value| 244a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi // is the empty string, this method uses the currect value of the pcr. 245a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi virtual TPM_RC GetPolicyDigestForPcrValue(int pcr_index, 246a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi const std::string& pcr_value, 247a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi std::string* policy_digest) = 0; 248a6e332ee7f5fe52c1291d961dbeda975c8272044Utkarsh Sanghi 24939dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // This method defines a non-volatile storage area in the TPM, referenced 25039dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // by |index| of size |num_bytes|. This command needs owner authorization. 251b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // The |attributes| of the space must be specified as a combination of 252b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // TPMA_NV_* values. Optionally, an |authorization_value| and / or 253b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // |policy_digest| can be specified which will be associated with the space. 254b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // These values must either be a valid SHA256 digest (or empty). 25539dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi virtual TPM_RC DefineNVSpace(uint32_t index, 25639dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi size_t num_bytes, 257b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn TPMA_NV attributes, 258b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn const std::string& authorization_value, 259b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn const std::string& policy_digest, 2605d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate) = 0; 26139dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi 26239dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // This method destroys the non-volatile space referred to by |index|. 26339dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // This command needs owner authorization. 26439dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi virtual TPM_RC DestroyNVSpace(uint32_t index, 2655d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate) = 0; 26639dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi 267b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // This method locks the non-volatile space referred to by |index|. The caller 268b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // needs indicate whether they want to |lock_read| and / or |lock_write|. They 269b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // also need to indicate if they are |using_owner_authorization|. 2705d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi virtual TPM_RC LockNVSpace(uint32_t index, 271b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn bool lock_read, 272b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn bool lock_write, 273b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn bool using_owner_authorization, 2745d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate) = 0; 27539dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi 27639dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // This method writes |nvram_data| to the non-volatile space referenced by 277b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // |index|, at |offset| bytes from the start of the non-volatile space. The 278b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // caller needs to indicate if they are |using_owner_authorization|. If 279b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // |extend| is set, the value will be extended and offset ignored. 28039dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi virtual TPM_RC WriteNVSpace(uint32_t index, 28139dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi uint32_t offset, 28239dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi const std::string& nvram_data, 283b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn bool using_owner_authorization, 284b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn bool extend, 2855d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate) = 0; 28639dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi 28739dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // This method reads |num_bytes| of data from the |offset| located at the 28839dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // non-volatile space defined by |index|. This method returns an error if 28939dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // |length| + |offset| is larger than the size of the defined non-volatile 290b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // space. The caller needs to indicate if they are |using_owner_authorization| 29139dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi virtual TPM_RC ReadNVSpace(uint32_t index, 29239dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi uint32_t offset, 29339dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi size_t num_bytes, 294b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn bool using_owner_authorization, 29539dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi std::string* nvram_data, 2965d3b9451ae2e912aefed0669dd50b2a777ea0ab2Utkarsh Sanghi AuthorizationDelegate* delegate) = 0; 29739dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi 29839dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // This function sets |name| to the name of the non-volatile space referenced 29939dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // by |index|. 30039dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi virtual TPM_RC GetNVSpaceName(uint32_t index, std::string* name) = 0; 30139dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi 30239dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // This function returns the public area of an non-volatile space defined in 30339dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi // the TPM. 30439dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi virtual TPM_RC GetNVSpacePublicArea(uint32_t index, 30539dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi TPMS_NV_PUBLIC* public_data) = 0; 30639dd58452d7fe3ebe93490a6239a76b385bd676dUtkarsh Sanghi 307b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // Lists all defined NV indexes. 308b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn virtual TPM_RC ListNVSpaces(std::vector<uint32_t>* index_list) = 0; 309b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn 310b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // Sets dictionary attack parameters. Requires lockout authorization. 311b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // Parameters map directly to TPM2_DictionaryAttackParameters in the TPM 2.0 312b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // specification. 313b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn virtual TPM_RC SetDictionaryAttackParameters( 314b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn uint32_t max_tries, 315b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn uint32_t recovery_time, 316b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn uint32_t lockout_recovery, 317b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn AuthorizationDelegate* delegate) = 0; 318b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn 319b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn // Reset dictionary attack lockout. Requires lockout authorization. 320b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn virtual TPM_RC ResetDictionaryAttackLock(AuthorizationDelegate* delegate) = 0; 321b180754b429c078cbc99175a6059a8b5d0491002Darren Krahn 322c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn private: 323c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn DISALLOW_COPY_AND_ASSIGN(TpmUtility); 324c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn}; 325c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 326c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn} // namespace trunks 327c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn 328c364caa9d091baae8eeb9144a6abf69e1fcabb39Darren Krahn#endif // TRUNKS_TPM_UTILITY_H_ 329