wolfTPM2 Wrappers

More...

Functions

	Name
WOLFTPM_API int	wolfTPM2_Test(TPM2HalIoCb ioCb, void * userCtx, WOLFTPM2_CAPS Test initialization of a TPM and optionally the TPM capabilities can be received.
WOLFTPM_API int	wolfTPM2_Init(WOLFTPM2_DEV Complete initialization of a TPM.
WOLFTPM_API int	wolfTPM2_OpenExisting(WOLFTPM2_DEV Use an already initialized TPM, in its current TPM locality.
WOLFTPM_API int	wolfTPM2_Cleanup(WOLFTPM2_DEV Easy to use TPM and wolfcrypt deinitialization.
WOLFTPM_API int	wolfTPM2_Cleanup_ex(WOLFTPM2_DEV Deinitialization of a TPM (and wolfcrypt if it was used)
WOLFTPM_API int	wolfTPM2_GetTpmDevId(WOLFTPM2_DEV Provides the device ID of a TPM.
WOLFTPM_API int	wolfTPM2_SelfTest(WOLFTPM2_DEV Asks the TPM to perform its self test.
WOLFTPM_API int	wolfTPM2_GetCapabilities(WOLFTPM2_DEV Reports the available TPM capabilities.
WOLFTPM_API int	wolfTPM2_GetHandles(TPM_HANDLE handle, TPML_HANDLE Gets a list of handles.
WOLFTPM_API int	wolfTPM2_UnsetAuth(WOLFTPM2_DEV Clears one of the TPM Authorization slots, pointed by its index number.
WOLFTPM_API int	wolfTPM2_UnsetAuthSession(WOLFTPM2_DEV Clears one of the TPM Authorization session slots, pointed by its index number and saves the nonce from the TPM so the session can continue to be used again with wolfTPM2_SetAuthSession.
WOLFTPM_API int	wolfTPM2_SetAuth(WOLFTPM2_DEV Sets a TPM Authorization slot using the provided index, session handle, attributes and auth.
WOLFTPM_API int	wolfTPM2_SetAuthPassword(WOLFTPM2_DEV Sets a TPM Authorization slot using the provided user auth, typically a password.
WOLFTPM_API int	wolfTPM2_SetAuthHandle(WOLFTPM2_DEV Sets a TPM Authorization slot using the user auth associated with a wolfTPM2 Handle.
WOLFTPM_API int	wolfTPM2_SetAuthSession(WOLFTPM2_DEV Sets a TPM Authorization slot using the provided TPM session handle, index and session attributes.
WOLFTPM_API int	wolfTPM2_SetAuthHandleName(WOLFTPM2_DEV Updates the Name used in a TPM Session with the Name associated with wolfTPM2 Handle.
WOLFTPM_API int	wolfTPM2_StartSession(WOLFTPM2_DEV Create a TPM session, Policy, HMAC or Trial.
WOLFTPM_API int	wolfTPM2_CreateAuthSession_EkPolicy(WOLFTPM2_DEV Creates a TPM session with Policy Secret to satisfy the default EK policy.
WOLFTPM_API int	wolfTPM2_CreatePrimaryKey(WOLFTPM2_DEV Single function to prepare and create a TPM 2.0 Primary Key.
WOLFTPM_API int	wolfTPM2_ChangeAuthKey(WOLFTPM2_DEV Change the authorization secret of a TPM 2.0 key.
WOLFTPM_API int	wolfTPM2_CreateKey(WOLFTPM2_DEV Single function to prepare and create a TPM 2.0 Key.
WOLFTPM_API int	wolfTPM2_LoadKey(WOLFTPM2_DEV Single function to load a TPM 2.0 key.
WOLFTPM_API int	wolfTPM2_CreateAndLoadKey(WOLFTPM2_DEV Single function to create and load a TPM 2.0 Key in one step.
WOLFTPM_API int	wolfTPM2_CreateLoadedKey(WOLFTPM2_DEV Creates and loads a key using single TPM 2.0 operation, and stores encrypted private key material.
WOLFTPM_API int	wolfTPM2_LoadPublicKey(WOLFTPM2_DEV Wrapper to load the public part of an external key.
WOLFTPM_API int	wolfTPM2_LoadPrivateKey(WOLFTPM2_DEV Single function to import an external private key and load it into the TPM in one step.
WOLFTPM_API int	wolfTPM2_ImportPrivateKey(WOLFTPM2_DEV Single function to import an external private key and load it into the TPM in one step.
WOLFTPM_API int	wolfTPM2_LoadRsaPublicKey(WOLFTPM2_DEV Helper function to import the public part of an external RSA key.
WOLFTPM_API int	wolfTPM2_LoadRsaPublicKey_ex(WOLFTPM2_DEV Advanced helper function to import the public part of an external RSA key.
WOLFTPM_API int	wolfTPM2_ImportRsaPrivateKey(WOLFTPM2_DEV Import an external RSA private key.
WOLFTPM_API int	wolfTPM2_ImportRsaPrivateKeySeed(WOLFTPM2_DEV Import an external RSA private key with custom seed.
WOLFTPM_API int	wolfTPM2_LoadRsaPrivateKey(WOLFTPM2_DEV Helper function to import and load an external RSA private key in one step.
WOLFTPM_API int	wolfTPM2_LoadRsaPrivateKey_ex(WOLFTPM2_DEV Advanced helper function to import and load an external RSA private key in one step.
WOLFTPM_API int	wolfTPM2_LoadEccPublicKey(WOLFTPM2_DEV Helper function to import the public part of an external ECC key.
WOLFTPM_API int	wolfTPM2_ImportEccPrivateKey(WOLFTPM2_DEV Helper function to import the private material of an external ECC key.
WOLFTPM_API int	wolfTPM2_ImportEccPrivateKeySeed(WOLFTPM2_DEV Helper function to import the private material of an external ECC key.
WOLFTPM_API int	wolfTPM2_LoadEccPrivateKey(WOLFTPM2_DEV Helper function to import and load an external ECC private key in one step.
WOLFTPM_API int	wolfTPM2_ReadPublicKey(WOLFTPM2_DEV Helper function to receive the public part of a loaded TPM object using its handle.
WOLFTPM_API int	wolfTPM2_CreateKeySeal(WOLFTPM2_DEV Using this wrapper a secret can be sealed inside a TPM 2.0 Key.
WOLFTPM_API int	wolfTPM2_CreateKeySeal_ex(WOLFTPM2_DEV Using this wrapper a secret can be sealed inside a TPM 2.0 Key with pcr selection.
WOLFTPM_API int	wolfTPM2_ComputeName(const TPM2B_PUBLIC Helper function to generate a hash of the public area of an object in the format expected by the TPM.
WOLFTPM_API int	wolfTPM2_SensitiveToPrivate(TPM2B_SENSITIVE Helper function to convert TPM2B_SENSITIVE to TPM2B_PRIVATE.
WOLFTPM_API int	wolfTPM2_ImportPrivateKeyBuffer(WOLFTPM2_DEV Helper function to import PEM/DER or RSA/ECC private key.
WOLFTPM_API int	wolfTPM2_ImportPublicKeyBuffer(WOLFTPM2_DEV Helper function to import PEM/DER formatted RSA/ECC public key.
WOLFTPM_API int	wolfTPM2_ExportPublicKeyBuffer(WOLFTPM2_DEV Helper function to export a TPM RSA/ECC public key with PEM/DER formatting.
WOLFTPM_API int	wolfTPM2_RsaPrivateKeyImportDer(WOLFTPM2_DEV Helper function to import Der rsa key directly.
WOLFTPM_API int	wolfTPM2_RsaPrivateKeyImportPem(WOLFTPM2_DEV Helper function to import Pem rsa key directly.
WOLFTPM_API int	wolfTPM2_RsaKey_TpmToWolf(WOLFTPM2_DEV Extract a RSA TPM key and convert it to a wolfcrypt key.
WOLFTPM_API int	wolfTPM2_RsaKey_TpmToPemPub(WOLFTPM2_DEV Convert a public RSA TPM key to PEM format public key. Note: This API is a wrapper around wolfTPM2_ExportPublicKeyBuffer.
WOLFTPM_API int	wolfTPM2_RsaKey_WolfToTpm(WOLFTPM2_DEV Import a RSA wolfcrypt key into the TPM.
WOLFTPM_API int	wolfTPM2_RsaKey_WolfToTpm_ex(WOLFTPM2_DEV Import a RSA wolfcrypt key into the TPM under a specific Primary Key or Hierarchy.
WOLFTPM_API int	wolfTPM2_RsaKey_PubPemToTpm(WOLFTPM2_DEV Import a PEM format public key from a file into the TPM.
WOLFTPM_API int	wolfTPM2_DecodeRsaDer(const byte * der, word32 derSz, TPM2B_PUBLIC Import DER RSA private or public key into TPM public and sensitive structures. This does not make any calls to TPM hardware.
WOLFTPM_API int	wolfTPM2_EccKey_TpmToWolf(WOLFTPM2_DEV Extract a ECC TPM key and convert to to a wolfcrypt key.
WOLFTPM_API int	wolfTPM2_EccKey_WolfToTpm(WOLFTPM2_DEV Import a ECC wolfcrypt key into the TPM.
WOLFTPM_API int	wolfTPM2_EccKey_WolfToTpm_ex(WOLFTPM2_DEV Import ECC wolfcrypt key into the TPM under a specific Primary Key or Hierarchy.
WOLFTPM_API int	wolfTPM2_EccKey_WolfToPubPoint(WOLFTPM2_DEV Import a ECC public key generated from wolfcrypt key into the TPM.
WOLFTPM_API int	wolfTPM2_DecodeEccDer(const byte * der, word32 derSz, TPM2B_PUBLIC Import DER ECC private or public key into TPM public and sensitive structures. This does not make any calls to TPM hardware.
WOLFTPM_API int	wolfTPM2_SignHash(WOLFTPM2_DEV Helper function to sign arbitrary data using a TPM key.
WOLFTPM_API int	wolfTPM2_SignHashScheme(WOLFTPM2_DEV Advanced helper function to sign arbitrary data using a TPM key, and specify the signature scheme and hashing algorithm.
WOLFTPM_API int	wolfTPM2_VerifyHash(WOLFTPM2_DEV Helper function to verify a TPM generated signature.
WOLFTPM_API int	wolfTPM2_VerifyHash_ex(WOLFTPM2_DEV Helper function to verify a TPM generated signature.
WOLFTPM_API int	wolfTPM2_VerifyHashScheme(WOLFTPM2_DEV Advanced helper function to verify a TPM generated signature.
WOLFTPM_API int	wolfTPM2_VerifyHashTicket(WOLFTPM2_DEV Advanced helper function to verify a TPM generated signature and return ticket.
WOLFTPM_API int	wolfTPM2_ECDHGenKey(WOLFTPM2_DEV Generates and then loads a ECC key-pair with NULL hierarchy for Diffie-Hellman exchange.
WOLFTPM_API int	wolfTPM2_ECDHGen(WOLFTPM2_DEV Generates ephemeral key and computes Z (shared secret)
WOLFTPM_API int	wolfTPM2_ECDHGenZ(WOLFTPM2_DEV Computes Z (shared secret) using pubPoint and loaded private ECC key.
WOLFTPM_API int	wolfTPM2_ECDHEGenKey(WOLFTPM2_DEV Generates ephemeral ECC key and returns array index (2 phase method)
WOLFTPM_API int	wolfTPM2_ECDHEGenZ(WOLFTPM2_DEV Computes Z (shared secret) using pubPoint and counter (2 phase method)
WOLFTPM_API int	wolfTPM2_RsaEncrypt(WOLFTPM2_DEV Perform RSA encryption using a TPM 2.0 key.
WOLFTPM_API int	wolfTPM2_RsaDecrypt(WOLFTPM2_DEV Perform RSA decryption using a TPM 2.0 key.
WOLFTPM_API int	wolfTPM2_ReadPCR(WOLFTPM2_DEV Read the values of a specified TPM 2.0 Platform Configuration Registers(PCR)
WOLFTPM_API int	wolfTPM2_ExtendPCR(WOLFTPM2_DEV Extend a PCR register with a user provided digest.
WOLFTPM_API int	wolfTPM2_NVCreateAuth(WOLFTPM2_DEV Creates a new NV Index to be later used for storing data into the TPM's NVRAM.
WOLFTPM_API int	wolfTPM2_NVCreateAuthPolicy(WOLFTPM2_DEV Creates a new NV Index to be later used for storing data into the TPM's NVRAM.
WOLFTPM_API int	wolfTPM2_NVWriteAuth(WOLFTPM2_DEV Stores user data to a NV Index, at a given offset.
WOLFTPM_API int	wolfTPM2_NVReadAuth(WOLFTPM2_DEV Reads user data from a NV Index, starting at the given offset.
WOLFTPM_API int	wolfTPM2_NVIncrement(WOLFTPM2_DEV Increments an NV one-way counter.
WOLFTPM_API int	wolfTPM2_NVOpen(WOLFTPM2_DEV Open an NV and populate the required authentication and name hash.
WOLFTPM_API int	wolfTPM2_NVWriteLock(WOLFTPM2_DEV Lock writes on the specified NV Index.
WOLFTPM_API int	wolfTPM2_NVDeleteAuth(WOLFTPM2_DEV Destroys an existing NV Index.
WOLFTPM_API int	wolfTPM2_NVCreate(WOLFTPM2_DEV Deprecated, use newer API.
WOLFTPM_API int	wolfTPM2_NVWrite(WOLFTPM2_DEV Deprecated, use newer API.
WOLFTPM_API int	wolfTPM2_NVRead(WOLFTPM2_DEV Deprecated, use newer API.
WOLFTPM_API int	wolfTPM2_NVDelete(WOLFTPM2_DEV Deprecated, use newer API.
WOLFTPM_API int	wolfTPM2_NVReadPublic(WOLFTPM2_DEV Extracts the public information about an nvIndex, such as maximum size.
WOLFTPM_API int	wolfTPM2_NVStoreKey(WOLFTPM2_DEV Helper function to store a TPM 2.0 Key into the TPM's NVRAM.
WOLFTPM_API int	wolfTPM2_NVDeleteKey(WOLFTPM2_DEV Helper function to delete a TPM 2.0 Key from the TPM's NVRAM.
WOLFTPM_API struct WC_RNG *	wolfTPM2_GetRng(WOLFTPM2_DEV Get the wolfcrypt RNG instance used for wolfTPM.
WOLFTPM_API int	wolfTPM2_GetRandom(WOLFTPM2_DEV Get a set of random number, generated with the TPM RNG or wolfcrypt RNG.
WOLFTPM_API int	wolfTPM2_UnloadHandle(WOLFTPM2_DEV Use to discard any TPM loaded object.
WOLFTPM_API int	wolfTPM2_Clear(WOLFTPM2_DEV Deinitializes wolfTPM and wolfcrypt(if enabled)
WOLFTPM_API int	wolfTPM2_HashStart(WOLFTPM2_DEV Helper function to start a TPM generated hash.
WOLFTPM_API int	wolfTPM2_HashUpdate(WOLFTPM2_DEV Update a TPM generated hash with new user data.
WOLFTPM_API int	wolfTPM2_HashFinish(WOLFTPM2_DEV Finalize a TPM generated hash and get the digest output in a user buffer.
WOLFTPM_API int	wolfTPM2_LoadKeyedHashKey(WOLFTPM2_DEV Creates and loads a new TPM key of KeyedHash type, typically used for HMAC operations.
WOLFTPM_API int	wolfTPM2_HmacStart(WOLFTPM2_DEV Helper function to start a TPM generated hmac.
WOLFTPM_API int	wolfTPM2_HmacUpdate(WOLFTPM2_DEV Update a TPM generated hmac with new user data.
WOLFTPM_API int	wolfTPM2_HmacFinish(WOLFTPM2_DEV Finalize a TPM generated hmac and get the digest output in a user buffer.
WOLFTPM_API int	wolfTPM2_LoadSymmetricKey(WOLFTPM2_DEV Loads an external symmetric key into the TPM.
WOLFTPM_API int	wolfTPM2_SetCommand(WOLFTPM2_DEV Vendor specific TPM command, used to enable other restricted TPM commands.
WOLFTPM_API int	wolfTPM2_Shutdown(WOLFTPM2_DEV Helper function to shutdown or reset the TPM.
WOLFTPM_API int	wolfTPM2_UnloadHandles(WOLFTPM2_DEV One-shot API to unload subsequent TPM handles.
WOLFTPM_API int	wolfTPM2_UnloadHandles_AllTransient(WOLFTPM2_DEV One-shot API to unload all transient TPM handles.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_RSA(TPMT_PUBLIC Prepares a TPM public template for new RSA key based on user selected object attributes.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_RSA_ex(TPMT_PUBLIC Prepares a TPM public template for new RSA key based on user selected object attributes.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_ECC(TPMT_PUBLIC Prepares a TPM public template for new ECC key based on user selected object attributes.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_ECC_ex(TPMT_PUBLIC Prepares a TPM public template for new ECC key based on user selected object attributes.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_Symmetric(TPMT_PUBLIC Prepares a TPM public template for new Symmetric key.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_KeyedHash(TPMT_PUBLIC Prepares a TPM public template for new KeyedHash key.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_KeySeal(TPMT_PUBLIC Prepares a TPM public template for new key for sealing secrets.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_RSA_EK(TPMT_PUBLIC Prepares a TPM public template for generating the TPM Endorsement Key of RSA type.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_ECC_EK(TPMT_PUBLIC Prepares a TPM public template for generating the TPM Endorsement Key of ECC type.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_RSA_SRK(TPMT_PUBLIC Prepares a TPM public template for generating a new TPM Storage Key of RSA type.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_ECC_SRK(TPMT_PUBLIC Prepares a TPM public template for generating a new TPM Storage Key of ECC type.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_RSA_AIK(TPMT_PUBLIC Prepares a TPM public template for generating a new TPM Attestation Key of RSA type.
WOLFTPM_API int	wolfTPM2_GetKeyTemplate_ECC_AIK(TPMT_PUBLIC Prepares a TPM public template for generating a new TPM Attestation Key of ECC type.
WOLFTPM_API int	wolfTPM2_SetKeyTemplate_Unique(TPMT_PUBLIC Sets the unique area of a public template used by Create or CreatePrimary.
WOLFTPM_API int	wolfTPM2_GetNvAttributesTemplate(TPM_HANDLE auth, word32 * nvAttributes) Prepares a TPM NV Index template.
WOLFTPM_API int	wolfTPM2_CreateEK(WOLFTPM2_DEV Generates a new TPM Endorsement key, based on the user selected algorithm, RSA or ECC.
WOLFTPM_API int	wolfTPM2_CreateSRK(WOLFTPM2_DEV Generates a new TPM Primary Key that will be used as a Storage Key for other TPM keys.
WOLFTPM_API int	wolfTPM2_CreateAndLoadAIK(WOLFTPM2_DEV Generates a new TPM Attestation Key under the provided Storage Key.
WOLFTPM_API int	wolfTPM2_GetTime(WOLFTPM2_KEY One-shot API to generate a TPM signed timestamp.
WOLFTPM_API int	wolfTPM2_CSR_SetCustomExt(WOLFTPM2_DEV Helper for Certificate Signing Request (CSR) generation to set a custom request extension oid and value usage for a WOLFTPM2_CSR structure.
WOLFTPM_API int	wolfTPM2_CSR_SetKeyUsage(WOLFTPM2_DEV Helper for Certificate Signing Request (CSR) generation to set a extended key usage or key usage for a WOLFTPM2_CSR structure. Pass either extended key usage or key usage values. Mixed string types are not supported, however you can call wolfTPM2_CSR_SetKeyUsage twice (once for extended key usage strings and once for standard key usage strings).
WOLFTPM_API int	wolfTPM2_CSR_SetSubject(WOLFTPM2_DEV Helper for Certificate Signing Request (CSR) generation to set a subject for a WOLFTPM2_CSR structure.
WOLFTPM_API int	wolfTPM2_CSR_MakeAndSign_ex(WOLFTPM2_DEV Helper for Certificate Signing Request (CSR) generation using a TPM based key (WOLFTPM2_KEY). Uses a provided WOLFTPM2_CSR structure with subject and key usage already set.
WOLFTPM_API int	wolfTPM2_CSR_MakeAndSign(WOLFTPM2_DEV Helper for Certificate Signing Request (CSR) generation using a TPM based key (WOLFTPM2_KEY). Uses a provided WOLFTPM2_CSR structure with subject and key usage already set.
WOLFTPM_API int	wolfTPM2_CSR_Generate_ex(WOLFTPM2_DEV Helper for Certificate Signing Request (CSR) generation using a TPM based key (WOLFTPM2_KEY). Single shot API for outputting a CSR or self-signed cert based on TPM key.
WOLFTPM_API int	wolfTPM2_CSR_Generate(WOLFTPM2_DEV Helper for Certificate Signing Request (CSR) generation using a TPM based key (WOLFTPM2_KEY). Single shot API for outputting a CSR or self-signed cert based on TPM key.
WOLFTPM_API int	wolfTPM2_ChangePlatformAuth(WOLFTPM2_DEV Helper to set the platform heirarchy authentication value to random. Setting the platform auth to random value is used to prevent application from being able to use platform hierarchy. This is defined in section 10 of the TCG PC Client Platform specification.
WOLFTPM_API int	wolfTPM2_CryptoDevCb(int devId, wc_CryptoInfo * info, void * ctx) A reference crypto callback API for using the TPM for crypto offload. This callback function is registered using wolfTPM2_SetCryptoDevCb or wc_CryptoDev_RegisterDevice.
WOLFTPM_API int	wolfTPM2_SetCryptoDevCb(WOLFTPM2_DEV Register a crypto callback function and return assigned devId.
WOLFTPM_API int	wolfTPM2_ClearCryptoDevCb(WOLFTPM2_DEV Clears the registered crypto callback.
WOLFTPM_API WOLFTPM2_DEV *	wolfTPM2_New(void ) Allocate and initialize a WOLFTPM2_DEV.
WOLFTPM_API int	wolfTPM2_Free(WOLFTPM2_DEV Cleanup and Free a WOLFTPM2_DEV that was allocated by wolfTPM2_New.
WOLFTPM_API WOLFTPM2_KEYBLOB *	wolfTPM2_NewKeyBlob(void ) Allocate and initialize a WOLFTPM2_KEYBLOB.
WOLFTPM_API int	wolfTPM2_FreeKeyBlob(WOLFTPM2_KEYBLOB Free a WOLFTPM2_KEYBLOB that was allocated with wolfTPM2_NewKeyBlob.
WOLFTPM_API TPMT_PUBLIC *	wolfTPM2_NewPublicTemplate(void ) Allocate and initialize a TPMT_PUBLIC.
WOLFTPM_API int	wolfTPM2_FreePublicTemplate(TPMT_PUBLIC Free a TPMT_PUBLIC that was allocated with wolfTPM2_NewPublicTemplate.
WOLFTPM_API WOLFTPM2_KEY *	wolfTPM2_NewKey(void ) Allocate and initialize a WOLFTPM2_KEY.
WOLFTPM_API int	wolfTPM2_FreeKey(WOLFTPM2_KEY Free a WOLFTPM2_KEY that was allocated with wolfTPM2_NewKey.
WOLFTPM_API WOLFTPM2_SESSION *	wolfTPM2_NewSession(void ) Allocate and initialize a WOLFTPM2_SESSION.
WOLFTPM_API int	wolfTPM2_FreeSession(WOLFTPM2_SESSION Free a WOLFTPM2_SESSION that was allocated with wolfTPM2_NewSession.
WOLFTPM_API WOLFTPM2_CSR *	wolfTPM2_NewCSR(void ) Allocate and initialize a WOLFTPM2_CSR.
WOLFTPM_API int	wolfTPM2_FreeCSR(WOLFTPM2_CSR Free a WOLFTPM2_CSR that was allocated with wolfTPM2_NewCSR.
WOLFTPM_API WOLFTPM2_HANDLE *	wolfTPM2_GetHandleRefFromKey(WOLFTPM2_KEY Retrieve the WOLFTPM2_HANDLE from a WOLFTPM2_KEY.
WOLFTPM_API WOLFTPM2_HANDLE *	wolfTPM2_GetHandleRefFromKeyBlob(WOLFTPM2_KEYBLOB Retrieve the WOLFTPM2_HANDLE from a WOLFTPM2_KEYBLOB.
WOLFTPM_API WOLFTPM2_HANDLE *	wolfTPM2_GetHandleRefFromSession(WOLFTPM2_SESSION Retrieve the WOLFTPM2_HANDLE from a WOLFTPM2_SESSION.
WOLFTPM_API TPM_HANDLE	wolfTPM2_GetHandleValue(WOLFTPM2_HANDLE * handle) Get the 32-bit handle value from the WOLFTPM2_HANDLE.
WOLFTPM_API int	wolfTPM2_SetKeyAuthPassword(WOLFTPM2_KEY Set the authentication data for a key.
WOLFTPM_API int	wolfTPM2_GetKeyBlobAsBuffer(byte * buffer, word32 bufferSz, WOLFTPM2_KEYBLOB Marshal data from a keyblob to a binary buffer. This can be stored to disk for loading in a separate process or after power cycling. If buffer is not provided then size only will be returned.
WOLFTPM_API int	wolfTPM2_GetKeyBlobAsSeparateBuffers(byte * pubBuffer, word32 * pubBufferSz, byte * privBuffer, word32 * privBufferSz, WOLFTPM2_KEYBLOB Marshal data from a keyblob to a binary buffer. This can be stored to disk for loading in a separate process or after power cycling. If either buffer is NULL then the size will be returned for each part.
WOLFTPM_API int	wolfTPM2_SetKeyBlobFromBuffer(WOLFTPM2_KEYBLOB Unmarshal data into a WOLFTPM2_KEYBLOB struct. This can be used to load a keyblob that was previously marshaled by wolfTPM2_GetKeyBlobAsBuffer.
WOLFTPM_API int	wolfTPM2_PolicyRestart(WOLFTPM2_DEV Restart the policy digest for a policy session.
WOLFTPM_API int	wolfTPM2_GetPolicyDigest(WOLFTPM2_DEV Get the policy digest of the session that was passed in wolfTPM2_GetPolicyDigest.
WOLFTPM_API int	wolfTPM2_PolicyPCR(WOLFTPM2_DEV Apply the PCR's to the policy digest for the policy session.
WOLFTPM_API int	wolfTPM2_PolicyAuthorize(WOLFTPM2_DEV Apply the PCR's to the policy digest for the policy session.
WOLFTPM_API int	wolfTPM2_PCRGetDigest(WOLFTPM2_DEV Get a cumulative digest of the PCR's specified.
WOLFTPM_API int	wolfTPM2_PolicyRefMake(TPM_ALG_ID pcrAlg, byte * digest, word32 * digestSz, const byte * policyRef, word32 policyRefSz) Utility for generating a policy ref digest. If no policy reference (nonce) used then just rehash the provided digest again (update _> final)
WOLFTPM_API int	wolfTPM2_PolicyPCRMake(TPM_ALG_ID pcrAlg, byte * pcrArray, word32 pcrArraySz, const byte * pcrDigest, word32 pcrDigestSz, byte * digest, word32 * digestSz) Utility for generating a policy PCR digest.
WOLFTPM_API int	wolfTPM2_PolicyAuthorizeMake(TPM_ALG_ID pcrAlg, const TPM2B_PUBLIC Utility for generating a policy authorization digest based on a public key.

Detailed Description

This module describes the rich API of wolfTPM called wrappers.

wolfTPM wrappers are used in two main cases:

• Perform common TPM 2.0 tasks, like key generation and storage
• Perform complex TPM 2.0 tasks, like attestation and parameter encryption

wolfTPM enables quick and rapid use of TPM 2.0 thanks to its many wrapper functions.

Functions Documentation

function wolfTPM2_Test

WOLFTPM_API int wolfTPM2_Test(
    TPM2HalIoCb ioCb,
    void * userCtx,
    WOLFTPM2_CAPS * caps
)

Test initialization of a TPM and optionally the TPM capabilities can be received.

Parameters:

• ioCb function pointer to a IO callback (see hal/tpm_io.h)
• userCtx pointer to a user context (can be NULL)
• caps to a structure of WOLFTPM2_CAPS type for returning the TPM capabilities (can be NULL)

See:

• wolfTPM2_Init
• TPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_Init

WOLFTPM_API int wolfTPM2_Init(
    WOLFTPM2_DEV * dev,
    TPM2HalIoCb ioCb,
    void * userCtx
)

Complete initialization of a TPM.

Parameters:

• dev pointer to an empty structure of WOLFTPM2_DEV type
• ioCb function pointer to a IO callback (see hal/tpm_io.h)
• userCtx pointer to a user context (can be NULL)

See:

• wolfTPM2_OpenExisting
• wolfTPM2_Test
• TPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO communication)
• BAD_FUNC_ARG: check the provided arguments

Example

int rc;
WOLFTPM2_DEV dev;

rc = wolfTPM2_Init(&dev, TPM2_IoCb, userCtx);
if (rc != TPM_RC_SUCCESS) {
    //wolfTPM2_Init failed
    goto exit;
}

function wolfTPM2_OpenExisting

WOLFTPM_API int wolfTPM2_OpenExisting(
    WOLFTPM2_DEV * dev,
    TPM2HalIoCb ioCb,
    void * userCtx
)

Use an already initialized TPM, in its current TPM locality.

Parameters:

• dev pointer to an empty structure of WOLFTPM2_DEV type
• ioCb function pointer to a IO callback (see hal/tpm_io.h)
• userCtx pointer to a user context (can be NULL)

See:

• wolfTPM2_Init
• wolfTPM2_Cleanup
• TPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO communication)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_Cleanup

WOLFTPM_API int wolfTPM2_Cleanup(
    WOLFTPM2_DEV * dev
)

Easy to use TPM and wolfcrypt deinitialization.

Parameters:

• dev pointer to a populated structure of WOLFTPM2_DEV type

See:

• wolfTPM2_OpenExisting
• wolfTPM2_Test
• TPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO communication)
• BAD_FUNC_ARG: check the provided arguments

Note: Calls wolfTPM2_Cleanup_ex with appropriate doShutdown parameter

Example

int rc;

rc = wolfTPM2_Cleanup(&dev);
if (rc != TPM_RC_SUCCESS) {
    //wolfTPM2_Cleanup failed
    goto exit;
}

function wolfTPM2_Cleanup_ex

WOLFTPM_API int wolfTPM2_Cleanup_ex(
    WOLFTPM2_DEV * dev,
    int doShutdown
)

Deinitialization of a TPM (and wolfcrypt if it was used)

Parameters:

• dev pointer to a populated structure of WOLFTPM2_DEV type
• doShutdown flag value, if true a TPM2_Shutdown command will be executed

See:

• wolfTPM2_OpenExisting
• wolfTPM2_Test
• TPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO communication)
• BAD_FUNC_ARG: check the provided arguments

Example

int rc;

//perform TPM2_Shutdown after deinitialization
rc = wolfTPM2_Cleanup_ex(&dev, 1);
if (rc != TPM_RC_SUCCESS) {
    //wolfTPM2_Cleanup_ex failed
    goto exit;
}

function wolfTPM2_GetTpmDevId

WOLFTPM_API int wolfTPM2_GetTpmDevId(
    WOLFTPM2_DEV * dev
)

Provides the device ID of a TPM.

Parameters:

• dev pointer to an populated structure of WOLFTPM2_DEV type

See:

• wolfTPM2_GetCapabilities
• wolfTPM2_Init

Return:

• an integer value of a valid TPM device ID
• or INVALID_DEVID if the TPM initialization could not extract DevID

Example

int tpmDevId;

tpmDevId = wolfTPM2_GetTpmDevId(&dev);
if (tpmDevId != INVALID_DEVID) {
    //wolfTPM2_Cleanup_ex failed
    goto exit;
}

function wolfTPM2_SelfTest

WOLFTPM_API int wolfTPM2_SelfTest(
    WOLFTPM2_DEV * dev
)

Asks the TPM to perform its self test.

Parameters:

• dev pointer to a populated structure of WOLFTPM2_DEV type

See:

• wolfTPM2_OpenExisting
• wolfTPM2_Test
• TPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO communication and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Example

int rc;

//perform TPM2_Shutdown after deinitialization
rc = wolfTPM2_SelfTest(&dev);
if (rc != TPM_RC_SUCCESS) {
    //wolfTPM2_SelfTest failed
    goto exit;
}

function wolfTPM2_GetCapabilities

WOLFTPM_API int wolfTPM2_GetCapabilities(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_CAPS * caps
)

Reports the available TPM capabilities.

Parameters:

• dev pointer to a populated structure of WOLFTPM2_DEV type
• caps pointer to an empty structure of WOLFTPM2_CAPS type to store the capabilities

See:

• wolfTPM2_GetTpmDevId
• wolfTPM2_SelfTest
• wolfTPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO communication and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Example

int rc;
WOLFTPM2_CAPS caps;

//perform TPM2_Shutdown after deinitialization
rc = wolfTPM2_GetCapabilities(&dev, &caps);
if (rc != TPM_RC_SUCCESS) {
    //wolfTPM2_GetCapabilities failed
    goto exit;
}

function wolfTPM2_GetHandles

WOLFTPM_API int wolfTPM2_GetHandles(
    TPM_HANDLE handle,
    TPML_HANDLE * handles
)

Gets a list of handles.

Parameters:

• handle handle to start from (example: PCR_FIRST, NV_INDEX_FIRST, HMAC_SESSION_FIRST, POLICY_SESSION_FIRST, PERMANENT_FIRST, TRANSIENT_FIRST or PERSISTENT_FIRST)
• handles pointer to TPML_HANDLE to return handle results (optional)

See: wolfTPM2_GetCapabilities

Return:

• 0 or greater: successful, count of handles
• TPM_RC_FAILURE: generic failure (check TPM IO communication and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Example

int persistent_handle_count;

// get count of persistent handles
persistent_handle_count = wolfTPM2_GetHandles(PERSISTENT_FIRST, NULL);

function wolfTPM2_UnsetAuth

WOLFTPM_API int wolfTPM2_UnsetAuth(
    WOLFTPM2_DEV * dev,
    int index
)

Clears one of the TPM Authorization slots, pointed by its index number.

Parameters:

• dev pointer to a TPM2_DEV struct
• index integer value, specifying the TPM Authorization slot, between zero and three

See:

• wolfTPM2_SetAuth
• wolfTPM2_SetAuthPassword
• wolfTPM2_SetAuthHandle
• wolfTPM2_SetAuthSession

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: unable to get lock on the TPM2 Context
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_UnsetAuthSession

WOLFTPM_API int wolfTPM2_UnsetAuthSession(
    WOLFTPM2_DEV * dev,
    int index,
    WOLFTPM2_SESSION * session
)

Clears one of the TPM Authorization session slots, pointed by its index number and saves the nonce from the TPM so the session can continue to be used again with wolfTPM2_SetAuthSession.

Parameters:

• dev pointer to a TPM2_DEV struct
• index integer value, specifying the TPM Authorization slot, between zero and three
• session pointer to a WOLFTPM2_SESSION struct used with wolfTPM2_StartSession and wolfTPM2_SetAuthSession

See:

• wolfTPM2_StartSession
• wolfTPM2_SetAuthSession

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: unable to get lock on the TPM2 Context
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_SetAuth

WOLFTPM_API int wolfTPM2_SetAuth(
    WOLFTPM2_DEV * dev,
    int index,
    TPM_HANDLE sessionHandle,
    const TPM2B_AUTH * auth,
    TPMA_SESSION sessionAttributes,
    const TPM2B_NAME * name
)

Sets a TPM Authorization slot using the provided index, session handle, attributes and auth.

Parameters:

• dev pointer to a TPM2_DEV struct
• index integer value, specifying the TPM Authorization slot, between zero and three
• sessionHandle integer value of TPM_HANDLE type
• auth pointer to a structure of type TPM2B_AUTH containing one TPM Authorization
• sessionAttributes integer value of type TPMA_SESSION, selecting one or more attributes for the Session
• name pointer to a TPM2B_NAME structure

See:

• wolfTPM2_SetAuthPassword
• wolfTPM2_SetAuthHandle
• wolfTPM2_SetAuthSession

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

Note: It is recommended to use one of the other wolfTPM2 wrappers, like wolfTPM2_SetAuthPassword. Because the wolfTPM2_SetAuth wrapper provides complete control over the TPM Authorization slot for advanced use cases. In most scenarios, wolfTPM2_SetAuthHandle and SetAuthPassword are used.

function wolfTPM2_SetAuthPassword

WOLFTPM_API int wolfTPM2_SetAuthPassword(
    WOLFTPM2_DEV * dev,
    int index,
    const TPM2B_AUTH * auth
)

Sets a TPM Authorization slot using the provided user auth, typically a password.

Parameters:

• dev pointer to a TPM2_DEV struct
• index integer value, specifying the TPM Authorization slot, between zero and three
• auth pointer to a structure of type TPM2B_AUTH, typically containing a TPM Key Auth

See:

• wolfTPM2_SetAuthHandle
• wolfTPM2_SetAuthSession
• wolfTPM2_SetAuth

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

Note: Often used for authorizing the loading and use of TPM keys, including Primary Keys

function wolfTPM2_SetAuthHandle

WOLFTPM_API int wolfTPM2_SetAuthHandle(
    WOLFTPM2_DEV * dev,
    int index,
    const WOLFTPM2_HANDLE * handle
)

Sets a TPM Authorization slot using the user auth associated with a wolfTPM2 Handle.

Parameters:

• dev pointer to a TPM2_DEV struct
• index integer value, specifying the TPM Authorization slot, between zero and three
• handle pointer to a populated structure of WOLFTPM2_HANDLE type

See:

• wolfTPM2_SetAuth
• wolfTPM2_SetAuthPassword
• wolfTPM2_SetAuthHandle
• wolfTPM2_SetAuthSession

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

Note: This wrapper is especially useful when using a TPM key for multiple operations and TPM Authorization is required again.

function wolfTPM2_SetAuthSession

WOLFTPM_API int wolfTPM2_SetAuthSession(
    WOLFTPM2_DEV * dev,
    int index,
    WOLFTPM2_SESSION * tpmSession,
    TPMA_SESSION sessionAttributes
)

Sets a TPM Authorization slot using the provided TPM session handle, index and session attributes.

Parameters:

• dev pointer to a TPM2_DEV struct
• index integer value, specifying the TPM Authorization slot, between zero and three
• tpmSession sessionHandle integer value of TPM_HANDLE type
• sessionAttributes integer value of type TPMA_SESSION, selecting one or more attributes for the Session

See:

• wolfTPM2_SetAuth
• wolfTPM2_SetAuthPassword
• wolfTPM2_SetAuthHandle

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

Note: This wrapper is useful for configuring TPM sessions, e.g. session for parameter encryption

function wolfTPM2_SetAuthHandleName

WOLFTPM_API int wolfTPM2_SetAuthHandleName(
    WOLFTPM2_DEV * dev,
    int index,
    const WOLFTPM2_HANDLE * handle
)

Updates the Name used in a TPM Session with the Name associated with wolfTPM2 Handle.

Parameters:

• dev pointer to a TPM2_DEV struct
• index integer value, specifying the TPM Authorization slot, between zero and three
• handle pointer to a populated structure of WOLFTPM2_HANDLE type

See:

• wolfTPM2_SetAuth
• wolfTPM2_SetAuthPassword
• wolfTPM2_SetAuthHandle
• wolfTPM2_SetAuthSession

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

Note: Typically, this wrapper is used from another wrappers and in very specific use cases. For example, wolfTPM2_NVWriteAuth

function wolfTPM2_StartSession

WOLFTPM_API int wolfTPM2_StartSession(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_SESSION * session,
    WOLFTPM2_KEY * tpmKey,
    WOLFTPM2_HANDLE * bind,
    TPM_SE sesType,
    int encDecAlg
)

Create a TPM session, Policy, HMAC or Trial.

Parameters:

• dev pointer to a TPM2_DEV struct
• session pointer to an empty WOLFTPM2_SESSION struct
• tpmKey pointer to a WOLFTPM2_KEY that will be used as a salt for the session
• bind pointer to a WOLFTPM2_HANDLE that will be used to make the session bounded
• sesType byte value, the session type (HMAC, Policy or Trial)
• encDecAlg integer value, specifying the algorithm in case of parameter encryption (TPM_ALG_CFB or TPM_ALG_XOR). Any value not CFB or XOR is considered NULL and parameter encryption is disabled.

See: wolfTPM2_SetAuthSession

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

Note: This wrapper can also be used to start TPM session for parameter encryption, see wolfTPM nvram or keygen example

function wolfTPM2_CreateAuthSession_EkPolicy

WOLFTPM_API int wolfTPM2_CreateAuthSession_EkPolicy(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_SESSION * tpmSession
)

Creates a TPM session with Policy Secret to satisfy the default EK policy.

Parameters:

• dev pointer to a TPM2_DEV struct
• tpmSession pointer to an empty WOLFTPM2_SESSION struct

See:

• wolfTPM2_SetAuthSession
• wolfTPM2_StartSession

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments
• TPM_RC_FAILURE: check TPM return code, check available handles, check TPM IO

Note: This wrapper can be used only if the EK authorization is not changed from default

function wolfTPM2_CreatePrimaryKey

WOLFTPM_API int wolfTPM2_CreatePrimaryKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    TPM_HANDLE primaryHandle,
    TPMT_PUBLIC * publicTemplate,
    const byte * auth,
    int authSz
)

Single function to prepare and create a TPM 2.0 Primary Key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty struct of WOLFTPM2_KEY type
• primaryHandle integer value, specifying one of four TPM 2.0 Primary Seeds: TPM_RH_OWNER, TPM_RH_ENDORSEMENT, TPM_RH_PLATFORM or TPM_RH_NULL
• publicTemplate pointer to a TPMT_PUBLIC structure populated manually or using one of the wolfTPM2_GetKeyTemplate_... wrappers
• auth pointer to a string constant, specifying the password authorization for the Primary Key
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_CreateKey
• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_ECC

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: TPM 2.0 allows only asymmetric RSA or ECC primary keys. Afterwards, both symmetric and asymmetric keys can be created under a TPM 2.0 Primary Key Typically, Primary Keys are used to create Hierarchies of TPM 2.0 Keys. The TPM uses a Primary Key to wrap the other keys, signing or decrypting.

function wolfTPM2_ChangeAuthKey

WOLFTPM_API int wolfTPM2_ChangeAuthKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    WOLFTPM2_HANDLE * parent,
    const byte * auth,
    int authSz
)

Change the authorization secret of a TPM 2.0 key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty struct of WOLFTPM2_KEY type
• parent pointer to a struct of WOLFTPM2_HANDLE type, specifying a TPM 2.0 Primary Key to be used as the parent(Storage Key)
• auth pointer to a string constant, specifying the password authorization of the TPM 2.0 key
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_CreatePrimaryKey
• wolfTPM2_SetAuthHandle
• wolfTPM2_UnloadHandle

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: TPM does not allow the authorization secret of a Primary Key to be changed. Instead, use wolfTPM2_CreatePrimary to create the same PrimaryKey with a new auth.

function wolfTPM2_CreateKey

WOLFTPM_API int wolfTPM2_CreateKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEYBLOB * keyBlob,
    WOLFTPM2_HANDLE * parent,
    TPMT_PUBLIC * publicTemplate,
    const byte * auth,
    int authSz
)

Single function to prepare and create a TPM 2.0 Key.

Parameters:

• dev pointer to a TPM2_DEV struct
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type
• parent pointer to a struct of WOLFTPM2_HANDLE type, specifying the a 2.0 Primary Key to be used as the parent(Storage Key)
• publicTemplate pointer to a TPMT_PUBLIC structure populated manually or using one of the wolfTPM2_GetKeyTemplate_... wrappers
• auth pointer to a string constant, specifying the password authorization for the TPM 2.0 Key
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_LoadKey
• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_ECC
• wolfTPM2_CreatePrimaryKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: This function only creates the key material and stores it into the keyblob argument. To load the key use wolfTPM2_LoadKey

function wolfTPM2_LoadKey

WOLFTPM_API int wolfTPM2_LoadKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEYBLOB * keyBlob,
    WOLFTPM2_HANDLE * parent
)

Single function to load a TPM 2.0 key.

Parameters:

• dev pointer to a TPM2_DEV struct
• keyBlob pointer to a struct of WOLFTPM2_KEYBLOB type
• parent pointer to a struct of WOLFTPM2_HANDLE type, specifying a TPM 2.0 Primary Key to be used as the parent(Storage Key)

See:

• wolfTPM2_CreateKey
• wolfTPM2_CreatePrimaryKey
• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_ECC

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: To load a TPM 2.0 key its parent(Primary Key) should also be loaded prior to this operation. Primary Keys are loaded when they are created.

function wolfTPM2_CreateAndLoadKey

WOLFTPM_API int wolfTPM2_CreateAndLoadKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    WOLFTPM2_HANDLE * parent,
    TPMT_PUBLIC * publicTemplate,
    const byte * auth,
    int authSz
)

Single function to create and load a TPM 2.0 Key in one step.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty struct of WOLFTPM2_KEY type
• parent pointer to a struct of WOLFTPM2_HANDLE type, specifying a TPM 2.0 Primary Key to be used as the parent(Storage Key)
• publicTemplate pointer to a TPMT_PUBLIC structure populated manually or using one of the wolfTPM2_GetKeyTemplate_... wrappers
• auth pointer to a string constant, specifying the password authorization of the TPM 2.0 key
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_CreateKey
• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_ECC

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CreateLoadedKey

WOLFTPM_API int wolfTPM2_CreateLoadedKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEYBLOB * keyBlob,
    WOLFTPM2_HANDLE * parent,
    TPMT_PUBLIC * publicTemplate,
    const byte * auth,
    int authSz
)

Creates and loads a key using single TPM 2.0 operation, and stores encrypted private key material.

Parameters:

• dev pointer to a TPM2_DEV struct
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type, contains private key material as encrypted data
• parent pointer to a struct of WOLFTPM2_HANDLE type, specifying a TPM 2.0 Primary Key to be used as the parent(Storage Key)
• publicTemplate pointer to a TPMT_PUBLIC structure populated manually or using one of the wolfTPM2_GetKeyTemplate_... wrappers
• auth pointer to a string constant, specifying the password authorization of the TPM 2.0 key
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_CreateAndLoadKey
• wolfTPM2_CreateKey
• wolfTPM2_LoadKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_LoadPublicKey

WOLFTPM_API int wolfTPM2_LoadPublicKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const TPM2B_PUBLIC * pub
)

Wrapper to load the public part of an external key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty struct of WOLFTPM2_KEY type
• pub pointer to a populated structure of TPM2B_PUBLIC type

See:

• wolfTPM2_LoadRsaPublicKey
• wolfTPM2_LoadEccPublicKey
• wolfTPM2_wolfTPM2_LoadPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: The key must be formatted to the format expected by the TPM, see the 'pub' argument and the alternative wrappers.

function wolfTPM2_LoadPrivateKey

WOLFTPM_API int wolfTPM2_LoadPrivateKey(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEY * key,
    const TPM2B_PUBLIC * pub,
    TPM2B_SENSITIVE * sens
)

Single function to import an external private key and load it into the TPM in one step.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys)
• key pointer to an empty struct of WOLFTPM2_KEY type
• pub pointer to a populated structure of TPM2B_PUBLIC type
• sens pointer to a populated structure of TPM2B_SENSITIVE type

See:

• wolfTPM2_CreateKey
• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_ECC

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: The private key material needs to be prepared in a format that the TPM expects, see the 'sens' argument

function wolfTPM2_ImportPrivateKey

WOLFTPM_API int wolfTPM2_ImportPrivateKey(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEYBLOB * keyBlob,
    const TPM2B_PUBLIC * pub,
    TPM2B_SENSITIVE * sens
)

Single function to import an external private key and load it into the TPM in one step.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys)
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type
• pub pointer to a populated structure of TPM2B_PUBLIC type
• sens pointer to a populated structure of TPM2B_SENSITIVE type

See:

• wolfTPM2_ImportRsaPrivateKey
• wolfTPM2_ImportEccPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: The primary key material needs to be prepared in a format that the TPM expects, see the 'sens' argument

function wolfTPM2_LoadRsaPublicKey

WOLFTPM_API int wolfTPM2_LoadRsaPublicKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const byte * rsaPub,
    word32 rsaPubSz,
    word32 exponent
)

Helper function to import the public part of an external RSA key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty struct of WOLFTPM2_KEY type
• rsaPub pointer to a byte buffer containing the public key material
• rsaPubSz integer value of word32 type, specifying the buffer size
• exponent integer value of word32 type, specifying the RSA exponent

See:

• wolfTPM2_LoadRsaPublicKey_ex
• wolfTPM2_LoadPublicKey
• wolfTPM2_LoadEccPublicKey
• wolfTPM2_ReadPublicKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Recommended for use, because it does not require TPM format of the public part

function wolfTPM2_LoadRsaPublicKey_ex

WOLFTPM_API int wolfTPM2_LoadRsaPublicKey_ex(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const byte * rsaPub,
    word32 rsaPubSz,
    word32 exponent,
    TPMI_ALG_RSA_SCHEME scheme,
    TPMI_ALG_HASH hashAlg
)

Advanced helper function to import the public part of an external RSA key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty struct of WOLFTPM2_KEY type
• rsaPub pointer to a byte buffer containing the public key material
• rsaPubSz integer value of word32 type, specifying the buffer size
• exponent integer value of word32 type, specifying the RSA exponent
• scheme value of TPMI_ALG_RSA_SCHEME type, specifying the RSA scheme
• hashAlg value of TPMI_ALG_HASH type, specifying the TPM hashing algorithm

See:

• wolfTPM2_LoadRsaPublicKey
• wolfTPM2_LoadPublicKey
• wolfTPM2_LoadEccPublicKey
• wolfTPM2_ReadPublicKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Allows the developer to specify TPM hashing algorithm and RSA scheme

function wolfTPM2_ImportRsaPrivateKey

WOLFTPM_API int wolfTPM2_ImportRsaPrivateKey(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEYBLOB * keyBlob,
    const byte * rsaPub,
    word32 rsaPubSz,
    word32 exponent,
    const byte * rsaPriv,
    word32 rsaPrivSz,
    TPMI_ALG_RSA_SCHEME scheme,
    TPMI_ALG_HASH hashAlg
)

Import an external RSA private key.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy)
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type
• rsaPub pointer to a byte buffer, containing the public part of the RSA key
• rsaPubSz integer value of word32 type, specifying the public part buffer size
• exponent integer value of word32 type, specifying the RSA exponent
• rsaPriv pointer to a byte buffer, containing the private material of the RSA key
• rsaPrivSz integer value of word32 type, specifying the private material buffer size
• scheme value of TPMI_ALG_RSA_SCHEME type, specifying the RSA scheme
• hashAlg integer value of TPMI_ALG_HASH type, specifying a supported TPM 2.0 hash algorithm

See:

• wolfTPM2_ImportRsaPrivateKeySeed
• wolfTPM2_LoadRsaPrivateKey
• wolfTPM2_LoadRsaPrivateKey_ex
• wolfTPM2_LoadPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments
• BUFFER_E: arguments size is larger than what the TPM buffers allow

function wolfTPM2_ImportRsaPrivateKeySeed

WOLFTPM_API int wolfTPM2_ImportRsaPrivateKeySeed(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEYBLOB * keyBlob,
    const byte * rsaPub,
    word32 rsaPubSz,
    word32 exponent,
    const byte * rsaPriv,
    word32 rsaPrivSz,
    TPMI_ALG_RSA_SCHEME scheme,
    TPMI_ALG_HASH hashAlg,
    TPMA_OBJECT attributes,
    byte * seed,
    word32 seedSz
)

Import an external RSA private key with custom seed.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy)
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type
• rsaPub pointer to a byte buffer, containing the public part of the RSA key
• rsaPubSz integer value of word32 type, specifying the public part buffer size
• exponent integer value of word32 type, specifying the RSA exponent
• rsaPriv pointer to a byte buffer, containing the private material of the RSA key
• rsaPrivSz integer value of word32 type, specifying the private material buffer size
• scheme value of TPMI_ALG_RSA_SCHEME type, specifying the RSA scheme
• hashAlg integer value of TPMI_ALG_HASH type, specifying a supported TPM 2.0 hash algorithm
• attributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM (or 0 to automatically populate)
• seedSz Optional (use NULL) or supply a custom seed for KDF
• seed Size of the seed (use 32 bytes for SHA2-256)

See:

• wolfTPM2_ImportRsaPrivateKey
• wolfTPM2_LoadRsaPrivateKey
• wolfTPM2_LoadRsaPrivateKey_ex
• wolfTPM2_LoadPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments
• BUFFER_E: arguments size is larger than what the TPM buffers allow

function wolfTPM2_LoadRsaPrivateKey

WOLFTPM_API int wolfTPM2_LoadRsaPrivateKey(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEY * key,
    const byte * rsaPub,
    word32 rsaPubSz,
    word32 exponent,
    const byte * rsaPriv,
    word32 rsaPrivSz
)

Helper function to import and load an external RSA private key in one step.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy)
• key pointer to an empty struct of WOLFTPM2_KEY type
• rsaPub pointer to a byte buffer, containing the public part of the RSA key
• rsaPubSz integer value of word32 type, specifying the public part buffer size
• exponent integer value of word32 type, specifying the RSA exponent
• rsaPriv pointer to a byte buffer, containing the private material of the RSA key
• rsaPrivSz integer value of word32 type, specifying the private material buffer size

See:

• wolfTPM2_ImportRsaPrivateKey
• wolfTPM2_LoadRsaPrivateKey_ex
• wolfTPM2_LoadPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_LoadRsaPrivateKey_ex

WOLFTPM_API int wolfTPM2_LoadRsaPrivateKey_ex(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEY * key,
    const byte * rsaPub,
    word32 rsaPubSz,
    word32 exponent,
    const byte * rsaPriv,
    word32 rsaPrivSz,
    TPMI_ALG_RSA_SCHEME scheme,
    TPMI_ALG_HASH hashAlg
)

Advanced helper function to import and load an external RSA private key in one step.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy)
• key pointer to an empty struct of WOLFTPM2_KEY type
• rsaPub pointer to a byte buffer, containing the public part of the RSA key
• rsaPubSz integer value of word32 type, specifying the public part buffer size
• exponent integer value of word32 type, specifying the RSA exponent
• rsaPriv pointer to a byte buffer, containing the private material of the RSA key
• rsaPrivSz integer value of word32 type, specifying the private material buffer size
• scheme value of TPMI_ALG_RSA_SCHEME type, specifying the RSA scheme
• hashAlg value of TPMI_ALG_HASH type, specifying the TPM hashing algorithm

See:

• wolfTPM2_LoadRsaPrivateKey
• wolfTPM2_LoadPrivateKey
• wolfTPM2_ImportRsaPrivateKey
• wolfTPM2_LoadEccPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_LoadEccPublicKey

WOLFTPM_API int wolfTPM2_LoadEccPublicKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    int curveId,
    const byte * eccPubX,
    word32 eccPubXSz,
    const byte * eccPubY,
    word32 eccPubYSz
)

Helper function to import the public part of an external ECC key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty struct of WOLFTPM2_KEY type
• curveId integer value, one of the accepted TPM_ECC_CURVE values
• eccPubX pointer to a byte buffer containing the public material of point X
• eccPubXSz integer value of word32 type, specifying the point X buffer size
• eccPubY pointer to a byte buffer containing the public material of point Y
• eccPubYSz integer value of word32 type, specifying the point Y buffer size

See:

• wolfTPM2_LoadPublicKey
• wolfTPM2_LoadRsaPublicKey
• wolfTPM2_ReadPublicKey
• wolfTPM2_LoadEccPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Recommended for use, because it does not require TPM format of the public part

function wolfTPM2_ImportEccPrivateKey

WOLFTPM_API int wolfTPM2_ImportEccPrivateKey(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEYBLOB * keyBlob,
    int curveId,
    const byte * eccPubX,
    word32 eccPubXSz,
    const byte * eccPubY,
    word32 eccPubYSz,
    const byte * eccPriv,
    word32 eccPrivSz
)

Helper function to import the private material of an external ECC key.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy)
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type
• curveId integer value, one of the accepted TPM_ECC_CURVE values
• eccPubX pointer to a byte buffer containing the public material of point X
• eccPubXSz integer value of word32 type, specifying the point X buffer size
• eccPubY pointer to a byte buffer containing the public material of point Y
• eccPubYSz integer value of word32 type, specifying the point Y buffer size
• eccPriv pointer to a byte buffer containing the private material
• eccPrivSz integer value of word32 type, specifying the private material size

See:

• wolfTPM2_ImportEccPrivateKeySeed
• wolfTPM2_LoadEccPrivateKey
• wolfTPM2_LoadEccPrivateKey_ex
• wolfTPM2_LoadPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ImportEccPrivateKeySeed

WOLFTPM_API int wolfTPM2_ImportEccPrivateKeySeed(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEYBLOB * keyBlob,
    int curveId,
    const byte * eccPubX,
    word32 eccPubXSz,
    const byte * eccPubY,
    word32 eccPubYSz,
    const byte * eccPriv,
    word32 eccPrivSz,
    TPMA_OBJECT attributes,
    byte * seed,
    word32 seedSz
)

Helper function to import the private material of an external ECC key.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy)
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type
• curveId integer value, one of the accepted TPM_ECC_CURVE values
• eccPubX pointer to a byte buffer containing the public material of point X
• eccPubXSz integer value of word32 type, specifying the point X buffer size
• eccPubY pointer to a byte buffer containing the public material of point Y
• eccPubYSz integer value of word32 type, specifying the point Y buffer size
• eccPriv pointer to a byte buffer containing the private material
• eccPrivSz integer value of word32 type, specifying the private material size
• attributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM (or 0 to automatically populate)
• seedSz Optional (use NULL) or supply a custom seed for KDF
• seed Size of the seed (use 32 bytes for SHA2-256)

See:

• wolfTPM2_ImportEccPrivateKey
• wolfTPM2_LoadEccPrivateKey
• wolfTPM2_LoadEccPrivateKey_ex
• wolfTPM2_LoadPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_LoadEccPrivateKey

WOLFTPM_API int wolfTPM2_LoadEccPrivateKey(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEY * key,
    int curveId,
    const byte * eccPubX,
    word32 eccPubXSz,
    const byte * eccPubY,
    word32 eccPubYSz,
    const byte * eccPriv,
    word32 eccPrivSz
)

Helper function to import and load an external ECC private key in one step.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy)
• key pointer to an empty struct of WOLFTPM2_KEY type
• curveId integer value, one of the accepted TPM_ECC_CURVE values
• eccPubX pointer to a byte buffer containing the public material of point X
• eccPubXSz integer value of word32 type, specifying the point X buffer size
• eccPubY pointer to a byte buffer containing the public material of point Y
• eccPubYSz integer value of word32 type, specifying the point Y buffer size
• eccPriv pointer to a byte buffer containing the private material
• eccPrivSz integer value of word32 type, specifying the private material size

See:

• wolfTPM2_ImportEccPrivateKey
• wolfTPM2_LoadEccPublicKey
• wolfTPM2_LoadPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ReadPublicKey

WOLFTPM_API int wolfTPM2_ReadPublicKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const TPM_HANDLE handle
)

Helper function to receive the public part of a loaded TPM object using its handle.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty struct of WOLFTPM2_KEY type
• handle integer value of TPM_HANDLE type, specifying handle of a loaded TPM object

See:

• wolfTPM2_LoadRsaPublicKey
• wolfTPM2_LoadEccPublicKey
• wolfTPM2_LoadPublicKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: The public part of a TPM symmetric keys contains just TPM meta data

function wolfTPM2_CreateKeySeal

WOLFTPM_API int wolfTPM2_CreateKeySeal(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEYBLOB * keyBlob,
    WOLFTPM2_HANDLE * parent,
    TPMT_PUBLIC * publicTemplate,
    const byte * auth,
    int authSz,
    const byte * sealData,
    int sealSize
)

Using this wrapper a secret can be sealed inside a TPM 2.0 Key.

Parameters:

• dev pointer to a TPM2_DEV struct
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type
• parent pointer to a struct of WOLFTPM2_HANDLE type, specifying the a 2.0 Primary Key to be used as the parent(Storage Key)
• publicTemplate pointer to a TPMT_PUBLIC structure populated using one of the wolfTPM2_GetKeyTemplate_KeySeal
• auth pointer to a string constant, specifying the password authorization for the TPM 2.0 Key
• authSz integer value, specifying the size of the password authorization, in bytes
• sealData pointer to a byte buffer, containing the secret(user data) to be sealed
• sealSize integer value, specifying the size of the seal buffer, in bytes

See:

• wolfTPM2_GetKeyTemplate_KeySeal
• TPM2_Unseal
• wolfTPM2_CreatePrimary

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: The secret size can not be larger than 128 bytes

function wolfTPM2_CreateKeySeal_ex

WOLFTPM_API int wolfTPM2_CreateKeySeal_ex(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEYBLOB * keyBlob,
    WOLFTPM2_HANDLE * parent,
    TPMT_PUBLIC * publicTemplate,
    const byte * auth,
    int authSz,
    TPM_ALG_ID pcrAlg,
    byte * pcrArray,
    word32 pcrArraySz,
    const byte * sealData,
    int sealSize
)

Using this wrapper a secret can be sealed inside a TPM 2.0 Key with pcr selection.

Parameters:

• dev pointer to a WOLFTPM2_DEV struct
• keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type
• parent pointer to a struct of WOLFTPM2_HANDLE type, specifying the a 2.0 Primary Key to be used as the parent(Storage Key)
• publicTemplate pointer to a TPMT_PUBLIC structure populated using one of the wolfTPM2_GetKeyTemplate_KeySeal
• auth pointer to a string constant, specifying the password authorization for the TPM 2.0 Key
• authSz integer value, specifying the size of the password authorization, in bytes
• pcrAlg hash algorithm to use when calculating pcr digest
• pcrArray optional array of pcrs to be used when creating the tpm object
• pcrArraySz length of the pcrArray
• sealData pointer to a byte buffer, containing the secret(user data) to be sealed
• sealSize integer value, specifying the size of the seal buffer, in bytes

See:

• wolfTPM2_GetKeyTemplate_KeySeal
• TPM2_Unseal
• wolfTPM2_CreatePrimary

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: The secret size can not be larger than 128 bytes

function wolfTPM2_ComputeName

WOLFTPM_API int wolfTPM2_ComputeName(
    const TPM2B_PUBLIC * pub,
    TPM2B_NAME * out
)

Helper function to generate a hash of the public area of an object in the format expected by the TPM.

Parameters:

• pub pointer to a populated structure of TPM2B_PUBLIC type, containing the public area of a TPM object
• out pointer to an empty struct of TPM2B_NAME type, to store the computed name

See: wolfTPM2_ImportPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Computed TPM name includes hash of the TPM_ALG_ID and the public are of the object

function wolfTPM2_SensitiveToPrivate

WOLFTPM_API int wolfTPM2_SensitiveToPrivate(
    TPM2B_SENSITIVE * sens,
    TPM2B_PRIVATE * priv,
    TPMI_ALG_HASH nameAlg,
    TPM2B_NAME * name,
    const WOLFTPM2_KEY * parentKey,
    TPMT_SYM_DEF_OBJECT * sym,
    TPM2B_DATA * symSeed
)

Helper function to convert TPM2B_SENSITIVE to TPM2B_PRIVATE.

Parameters:

• sens pointer to a correctly populated structure of TPM2B_SENSITIVE type
• priv pointer to an empty struct of TPM2B_PRIVATE type
• nameAlg integer value of TPMI_ALG_HASH type, specifying a valid TPM2 hashing algorithm
• name pointer to a TPM2B_NAME structure
• parentKey pointer to a WOLFTPM2_KEY structure, specifying a parentKey, if it exists
• sym pointer to a structure of TPMT_SYM_DEF_OBJECT type
• symSeed pointer to a structure of derived secret (RSA=random, ECC=ECDHE)

See: wolfTPM2_ImportPrivateKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ImportPrivateKeyBuffer

WOLFTPM_API int wolfTPM2_ImportPrivateKeyBuffer(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    int keyType,
    WOLFTPM2_KEYBLOB * keyBlob,
    int encodingType,
    const char * input,
    word32 inSz,
    const char * pass,
    TPMA_OBJECT objectAttributes,
    byte * seed,
    word32 seedSz
)

Helper function to import PEM/DER or RSA/ECC private key.

Parameters:

• dev pointer to a TPM2_DEV struct
• keyType The type of key (TPM_ALG_RSA or TPM_ALG_ECC)
• parentKey pointer to a WOLFTPM2_KEY struct, pointing to a Primary Key or TPM Hierarchy
• keyBlob pointer to a struct of WOLFTPM2_KEYBLOB type, to import the private key to
• encodingType ENCODING_TYPE_PEM or ENCODING_TYPE_ASN1 (DER)
• input buffer holding the rsa pem
• inSz length of the input pem buffer
• pass optional password of the key
• objectAttributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM
• seedSz Optional (use NULL) or supply a custom seed for KDF
• seed Size of the seed (use 32 bytes for SHA2-256)

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ImportPublicKeyBuffer

WOLFTPM_API int wolfTPM2_ImportPublicKeyBuffer(
    WOLFTPM2_DEV * dev,
    int keyType,
    WOLFTPM2_KEY * key,
    int encodingType,
    const char * input,
    word32 inSz,
    TPMA_OBJECT objectAttributes
)

Helper function to import PEM/DER formatted RSA/ECC public key.

Parameters:

• dev pointer to a TPM2_DEV struct
• keyType The type of key (TPM_ALG_RSA or TPM_ALG_ECC)
• key pointer to a struct of WOLFTPM2_KEY type, to import the public key to
• encodingType ENCODING_TYPE_PEM or ENCODING_TYPE_ASN1 (DER)
• input buffer holding the rsa pem
• inSz length of the input pem buffer
• objectAttributes integer value of OR'd TPMA_OBJECT_* types

Return:

• TPM_RC_SUCCESS: successful - populates key->pub
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ExportPublicKeyBuffer

WOLFTPM_API int wolfTPM2_ExportPublicKeyBuffer(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * tpmKey,
    int encodingType,
    byte * out,
    word32 * outSz
)

Helper function to export a TPM RSA/ECC public key with PEM/DER formatting.

Parameters:

• dev pointer to a TPM2_DEV struct
• tpmKey pointer to a WOLFTPM2_KEY with populated key
• encodingType ENCODING_TYPE_PEM or ENCODING_TYPE_ASN1 (DER)
• out buffer to export public key
• outSz pointer to length of the out buffer

Return:

• TPM_RC_SUCCESS: successful - populates key->pub
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BUFFER_E: insufficient space in provided buffer
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_RsaPrivateKeyImportDer

WOLFTPM_API int wolfTPM2_RsaPrivateKeyImportDer(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEYBLOB * keyBlob,
    const byte * input,
    word32 inSz,
    TPMI_ALG_RSA_SCHEME scheme,
    TPMI_ALG_HASH hashAlg
)

Helper function to import Der rsa key directly.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a WOLFTPM2_KEY struct, pointing to a Primary Key or TPM Hierarchy
• keyBlob pointer to a struct of WOLFTPM2_KEYBLOB type, to import the rsa key to
• input buffer holding the rsa der
• inSz length of the input der buffer
• scheme value of TPMI_ALG_RSA_SCHEME type, specifying the RSA scheme
• hashAlg value of TPMI_ALG_HASH type, specifying the TPM hashing algorithm

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_RsaPrivateKeyImportPem

WOLFTPM_API int wolfTPM2_RsaPrivateKeyImportPem(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEYBLOB * keyBlob,
    const char * input,
    word32 inSz,
    char * pass,
    TPMI_ALG_RSA_SCHEME scheme,
    TPMI_ALG_HASH hashAlg
)

Helper function to import Pem rsa key directly.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a WOLFTPM2_KEY struct, pointing to a Primary Key or TPM Hierarchy
• keyBlob pointer to a struct of WOLFTPM2_KEYBLOB type, to import the rsa key to
• input buffer holding the rsa pem
• inSz length of the input pem buffer
• pass optional password of the key
• scheme value of TPMI_ALG_RSA_SCHEME type, specifying the RSA scheme
• hashAlg value of TPMI_ALG_HASH type, specifying the TPM hashing algorithm

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_RsaKey_TpmToWolf

WOLFTPM_API int wolfTPM2_RsaKey_TpmToWolf(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * tpmKey,
    RsaKey * wolfKey
)

Extract a RSA TPM key and convert it to a wolfcrypt key.

Parameters:

• dev pointer to a TPM2_DEV struct
• tpmKey pointer to a struct of WOLFTPM2_KEY type, holding a TPM key
• wolfKey pointer to an empty struct of RsaKey type, to store the converted key

See:

• wolfTPM2_RsaKey_WolfToTpm
• wolfTPM2_RsaKey_WolfToTpm_ex

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_RsaKey_TpmToPemPub

WOLFTPM_API int wolfTPM2_RsaKey_TpmToPemPub(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * keyBlob,
    byte * pem,
    word32 * pemSz
)

Convert a public RSA TPM key to PEM format public key. Note: This API is a wrapper around wolfTPM2_ExportPublicKeyBuffer.

Parameters:

• dev pointer to a TPM2_DEV struct
• keyBlob pointer to a struct of WOLFTPM2_KEY type, holding a TPM key
• pem pointer to an array of byte type, used as temporary storage for PEM conversation
• pemSz pointer to integer variable, to store the used buffer size

See:

• wolfTPM2_ExportPublicKeyBuffer
• wolfTPM2_RsaKey_TpmToWolf
• wolfTPM2_RsaKey_WolfToTpm

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_RsaKey_WolfToTpm

WOLFTPM_API int wolfTPM2_RsaKey_WolfToTpm(
    WOLFTPM2_DEV * dev,
    RsaKey * wolfKey,
    WOLFTPM2_KEY * tpmKey
)

Import a RSA wolfcrypt key into the TPM.

Parameters:

• dev pointer to a TPM2_DEV struct
• wolfKey pointer to a struct of RsaKey type, holding a wolfcrypt key
• tpmKey pointer to an empty struct of WOLFTPM2_KEY type, to hold the imported TPM key

See: wolfTPM2_RsaKey_TpmToWolf

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Allows the use of externally generated keys by wolfcrypt to be used with TPM 2.0

function wolfTPM2_RsaKey_WolfToTpm_ex

WOLFTPM_API int wolfTPM2_RsaKey_WolfToTpm_ex(
    WOLFTPM2_DEV * dev,
    const WOLFTPM2_KEY * parentKey,
    RsaKey * wolfKey,
    WOLFTPM2_KEY * tpmKey
)

Import a RSA wolfcrypt key into the TPM under a specific Primary Key or Hierarchy.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a WOLFTPM2_KEY struct, pointing to a Primary Key or TPM Hierarchy
• wolfKey pointer to a struct of RsaKey type, holding a wolfcrypt key
• tpmKey pointer to an empty struct of WOLFTPM2_KEY type, to hold the imported TPM key

See:

• wolfTPM2_RsaKey_WolfToTpm
• wolfTPM2_RsaKey_TpmToWolf

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Allows the use of wolfcrypt generated keys with wolfTPM

function wolfTPM2_RsaKey_PubPemToTpm

WOLFTPM_API int wolfTPM2_RsaKey_PubPemToTpm(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * tpmKey,
    const byte * pem,
    word32 pemSz
)

Import a PEM format public key from a file into the TPM.

Parameters:

• dev pointer to a TPM2_DEV struct
• tpmKey pointer to an empty struct of WOLFTPM2_KEY type, to hold the imported TPM key
• pem pointer to an array of byte type, containing a PEM formatted public key material
• pemSz pointer to integer variable, specifying the size of PEM key data

See:

• wolfTPM2_RsaKey_WolfToTpm
• wolfTPM2_RsaKey_TpmToPem
• wolfTPM2_RsaKey_TpmToWolf

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)

function wolfTPM2_DecodeRsaDer

WOLFTPM_API int wolfTPM2_DecodeRsaDer(
    const byte * der,
    word32 derSz,
    TPM2B_PUBLIC * pub,
    TPM2B_SENSITIVE * sens,
    TPMA_OBJECT attributes
)

Import DER RSA private or public key into TPM public and sensitive structures. This does not make any calls to TPM hardware.

Parameters:

• der The der encoding of the content of the extension.
• derSz The size in bytes of the der encoding.
• pub pointer to a populated structure of TPM2B_PUBLIC type
• sens pointer to a populated structure of TPM2B_SENSITIVE type
• attributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM (or 0 to automatically populate)

See:

• wolfTPM2_ImportPublicKeyBuffer
• wolfTPM2_ImportPrivateKeyBuffer
• wolfTPM2_DecodeEccDer

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)

function wolfTPM2_EccKey_TpmToWolf

WOLFTPM_API int wolfTPM2_EccKey_TpmToWolf(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * tpmKey,
    ecc_key * wolfKey
)

Extract a ECC TPM key and convert to to a wolfcrypt key.

Parameters:

• dev pointer to a TPM2_DEV struct
• tpmKey pointer to a struct of WOLFTPM2_KEY type, holding a TPM key
• wolfKey pointer to an empty struct of ecc_key type, to store the converted key

See:

• wolfTPM2_EccKey_WolfToTpm
• wolfTPM2_EccKey_WolfToTpm_ex

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_EccKey_WolfToTpm

WOLFTPM_API int wolfTPM2_EccKey_WolfToTpm(
    WOLFTPM2_DEV * dev,
    ecc_key * wolfKey,
    WOLFTPM2_KEY * tpmKey
)

Import a ECC wolfcrypt key into the TPM.

Parameters:

• dev pointer to a TPM2_DEV struct
• wolfKey pointer to a struct of ecc_key type, holding a wolfcrypt key
• tpmKey pointer to an empty struct of WOLFTPM2_KEY type, to hold the imported TPM key

See: wolfTPM2_EccKey_TpmToWolf

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Allows the use of externally generated keys by wolfcrypt to be used with TPM 2.0

function wolfTPM2_EccKey_WolfToTpm_ex

WOLFTPM_API int wolfTPM2_EccKey_WolfToTpm_ex(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * parentKey,
    ecc_key * wolfKey,
    WOLFTPM2_KEY * tpmKey
)

Import ECC wolfcrypt key into the TPM under a specific Primary Key or Hierarchy.

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a WOLFTPM2_KEY struct, pointing to a Primary Key or TPM Hierarchy
• wolfKey pointer to a struct of ecc_key type, holding a wolfcrypt key
• tpmKey pointer to an empty struct of WOLFTPM2_KEY type, to hold the imported TPM key

See:

• wolfTPM2_EccKey_WolfToTPM
• wolfTPM2_EccKey_TpmToWolf

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Allows the use of wolfcrypt generated keys with wolfTPM

function wolfTPM2_EccKey_WolfToPubPoint

WOLFTPM_API int wolfTPM2_EccKey_WolfToPubPoint(
    WOLFTPM2_DEV * dev,
    ecc_key * wolfKey,
    TPM2B_ECC_POINT * pubPoint
)

Import a ECC public key generated from wolfcrypt key into the TPM.

Parameters:

• dev pointer to a TPM2_DEV struct
• wolfKey pointer to a struct of ecc_key type, holding a wolfcrypt public ECC key
• pubPoint pointer to an empty struct of TPM2B_ECC_POINT type

See: wolfTPM2_EccKey_TpmToWolf

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Allows the use of externally generated public ECC key by wolfcrypt to be used with TPM 2.0

function wolfTPM2_DecodeEccDer

WOLFTPM_API int wolfTPM2_DecodeEccDer(
    const byte * der,
    word32 derSz,
    TPM2B_PUBLIC * pub,
    TPM2B_SENSITIVE * sens,
    TPMA_OBJECT attributes
)

Import DER ECC private or public key into TPM public and sensitive structures. This does not make any calls to TPM hardware.

Parameters:

• der The der encoding of the content of the extension.
• derSz The size in bytes of the der encoding.
• pub pointer to a populated structure of TPM2B_PUBLIC type
• sens pointer to a populated structure of TPM2B_SENSITIVE type
• attributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM (or 0 to automatically populate)

See:

• wolfTPM2_ImportPublicKeyBuffer
• wolfTPM2_ImportPrivateKeyBuffer
• wolfTPM2_DecodeRsaDer

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)

function wolfTPM2_SignHash

WOLFTPM_API int wolfTPM2_SignHash(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const byte * digest,
    int digestSz,
    byte * sig,
    int * sigSz
)

Helper function to sign arbitrary data using a TPM key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a struct of WOLFTPM2_KEY type, holding a TPM key material
• digest pointer to a byte buffer, containing the arbitrary data
• digestSz integer value, specifying the size of the digest buffer, in bytes
• sig pointer to a byte buffer, containing the generated signature
• sigSz integer value, specifying the size of the signature buffer, in bytes

See:

• wolfTPM2_VerifyHash
• wolfTPM2_SignHashScheme
• wolfTPM2_VerifyHashScheme

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_SignHashScheme

WOLFTPM_API int wolfTPM2_SignHashScheme(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const byte * digest,
    int digestSz,
    byte * sig,
    int * sigSz,
    TPMI_ALG_SIG_SCHEME sigAlg,
    TPMI_ALG_HASH hashAlg
)

Advanced helper function to sign arbitrary data using a TPM key, and specify the signature scheme and hashing algorithm.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a struct of WOLFTPM2_KEY type, holding a TPM key material
• digest pointer to a byte buffer, containing the arbitrary data
• digestSz integer value, specifying the size of the digest buffer, in bytes
• sig pointer to a byte buffer, containing the generated signature
• sigSz integer value, specifying the size of the signature buffer, in bytes
• sigAlg integer value of TPMI_ALG_SIG_SCHEME type, specifying a supported TPM 2.0 signature scheme
• hashAlg integer value of TPMI_ALG_HASH type, specifying a supported TPM 2.0 hash algorithm

See:

• wolfTPM2_SignHash
• wolfTPM2_VerifyHash
• wolfTPM2_VerifyHashScheme

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_VerifyHash

WOLFTPM_API int wolfTPM2_VerifyHash(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const byte * sig,
    int sigSz,
    const byte * digest,
    int digestSz
)

Helper function to verify a TPM generated signature.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a struct of WOLFTPM2_KEY type, holding a TPM 2.0 key material
• sig pointer to a byte buffer, containing the generated signature
• sigSz integer value, specifying the size of the signature buffer, in bytes
• digest pointer to a byte buffer, containing the signed data
• digestSz integer value, specifying the size of the digest buffer, in bytes

See:

• wolfTPM2_SignHash
• wolfTPM2_SignHashScheme
• wolfTPM2_VerifyHashScheme
• wolfTPM2_VerifyHash_ex

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_VerifyHash_ex

WOLFTPM_API int wolfTPM2_VerifyHash_ex(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const byte * sig,
    int sigSz,
    const byte * digest,
    int digestSz,
    int hashAlg
)

Helper function to verify a TPM generated signature.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a struct of WOLFTPM2_KEY type, holding a TPM 2.0 key material
• sig pointer to a byte buffer, containing the generated signature
• sigSz integer value, specifying the size of the signature buffer, in bytes
• digest pointer to a byte buffer, containing the signed data
• digestSz integer value, specifying the size of the digest buffer, in bytes
• hashAlg hash algorithm used to sign

See:

• wolfTPM2_SignHash
• wolfTPM2_SignHashScheme
• wolfTPM2_VerifyHashScheme

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_VerifyHashScheme

WOLFTPM_API int wolfTPM2_VerifyHashScheme(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const byte * sig,
    int sigSz,
    const byte * digest,
    int digestSz,
    TPMI_ALG_SIG_SCHEME sigAlg,
    TPMI_ALG_HASH hashAlg
)

Advanced helper function to verify a TPM generated signature.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a struct of WOLFTPM2_KEY type, holding a TPM 2.0 key material
• sig pointer to a byte buffer, containing the generated signature
• sigSz integer value, specifying the size of the signature buffer, in bytes
• digest pointer to a byte buffer, containing the signed data
• digestSz integer value, specifying the size of the digest buffer, in bytes
• sigAlg integer value of TPMI_ALG_SIG_SCHEME type, specifying a supported TPM 2.0 signature scheme
• hashAlg integer value of TPMI_ALG_HASH type, specifying a supported TPM 2.0 hash algorithm

See:

• wolfTPM2_SignHash
• wolfTPM2_SignHashScheme
• wolfTPM2_VerifyHash

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_VerifyHashTicket

WOLFTPM_API int wolfTPM2_VerifyHashTicket(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const byte * sig,
    int sigSz,
    const byte * digest,
    int digestSz,
    TPMI_ALG_SIG_SCHEME sigAlg,
    TPMI_ALG_HASH hashAlg,
    TPMT_TK_VERIFIED * checkTicket
)

Advanced helper function to verify a TPM generated signature and return ticket.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a struct of WOLFTPM2_KEY type, holding a TPM 2.0 key material
• sig pointer to a byte buffer, containing the generated signature
• sigSz integer value, specifying the size of the signature buffer, in bytes
• digest pointer to a byte buffer, containing the signed data
• digestSz integer value, specifying the size of the digest buffer, in bytes
• sigAlg integer value of TPMI_ALG_SIG_SCHEME type, specifying a supported TPM 2.0 signature scheme
• hashAlg integer value of TPMI_ALG_HASH type, specifying a supported TPM 2.0 hash algorithm
• checkTicket returns the validation ticket proving the signature for digest was checked

See:

• wolfTPM2_VerifyHashScheme
• wolfTPM2_VerifyHashTicket
• wolfTPM2_VerifyHash

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ECDHGenKey

WOLFTPM_API int wolfTPM2_ECDHGenKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * ecdhKey,
    int curve_id,
    const byte * auth,
    int authSz
)

Generates and then loads a ECC key-pair with NULL hierarchy for Diffie-Hellman exchange.

Parameters:

• dev pointer to a TPM2_DEV struct
• ecdhKey pointer to an empty structure of WOLFTPM2_KEY type
• curve_id integer value, specifying a valid TPM_ECC_CURVE value
• auth pointer to a string constant, specifying the password authorization for the TPM 2.0 Key
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_ECDHGen
• wolfTPM2_ECDHGenZ
• wolfTPM2_ECDHEGenKey
• wolfTPM2_ECDHEGenZ

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ECDHGen

WOLFTPM_API int wolfTPM2_ECDHGen(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * privKey,
    TPM2B_ECC_POINT * pubPoint,
    byte * out,
    int * outSz
)

Generates ephemeral key and computes Z (shared secret)

Parameters:

• dev pointer to a TPM2_DEV struct
• privKey pointer to a structure of WOLFTPM2_KEY type
• pubPoint pointer to an empty structure of TPM2B_ECC_POINT type
• out pointer to a byte buffer, to store the generated shared secret
• outSz integer value, specifying the size of the shared secret, in bytes

See:

• wolfTPM2_ECDHGenZ
• wolfTPM2_ECDHGenKey
• wolfTPM2_ECDHEGenKey
• wolfTPM2_ECDHEGenZ

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: One shot API using private key handle to generate key-pair and return public point and shared secret

function wolfTPM2_ECDHGenZ

WOLFTPM_API int wolfTPM2_ECDHGenZ(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * privKey,
    const TPM2B_ECC_POINT * pubPoint,
    byte * out,
    int * outSz
)

Computes Z (shared secret) using pubPoint and loaded private ECC key.

Parameters:

• dev pointer to a TPM2_DEV struct
• privKey pointer to a structure of WOLFTPM2_KEY type, containing a valid TPM handle
• pubPoint pointer to a populated structure of TPM2B_ECC_POINT type
• out pointer to a byte buffer, to store the computed shared secret
• outSz integer value, specifying the size of the shared secret, in bytes

See:

• wolfTPM2_ECDHGen
• wolfTPM2_ECDHGenKey
• wolfTPM2_ECDHEGenKey
• wolfTPM2_ECDHEGenZ

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ECDHEGenKey

WOLFTPM_API int wolfTPM2_ECDHEGenKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * ecdhKey,
    int curve_id
)

Generates ephemeral ECC key and returns array index (2 phase method)

Parameters:

• dev pointer to a TPM2_DEV struct
• ecdhKey pointer to an empty structure of WOLFTPM2_KEY type
• curve_id integer value, specifying a valid TPM_ECC_CURVE value

See:

• wolfTPM2_ECDHEGenZ
• wolfTPM2_ECDHGen
• wolfTPM2_ECDHGenKey
• wolfTPM2_ECDHGenZ

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: One time use key

function wolfTPM2_ECDHEGenZ

WOLFTPM_API int wolfTPM2_ECDHEGenZ(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * parentKey,
    WOLFTPM2_KEY * ecdhKey,
    const TPM2B_ECC_POINT * pubPoint,
    byte * out,
    int * outSz
)

Computes Z (shared secret) using pubPoint and counter (2 phase method)

Parameters:

• dev pointer to a TPM2_DEV struct
• parentKey pointer to a structure of WOLFTPM2_KEY type, containing a valid TPM handle of a primary key
• ecdhKey pointer to a structure of WOLFTPM2_KEY type, containing a valid TPM handle
• pubPoint pointer to an empty struct of TPM2B_ECC_POINT type
• out pointer to a byte buffer, to store the computed shared secret
• outSz integer value, specifying the size of the shared secret, in bytes

See:

• wolfTPM2_ECDHEGenKey
• wolfTPM2_ECDHGen
• wolfTPM2_ECDHGenKey
• wolfTPM2_ECDHGenZ

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: The counter, array ID, can only be used one time

function wolfTPM2_RsaEncrypt

WOLFTPM_API int wolfTPM2_RsaEncrypt(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    TPM_ALG_ID padScheme,
    const byte * msg,
    int msgSz,
    byte * out,
    int * outSz
)

Perform RSA encryption using a TPM 2.0 key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a struct of WOLFTPM2_KEY type, holding a TPM key material
• padScheme integer value of TPM_ALG_ID type, specifying the padding scheme
• msg pointer to a byte buffer, containing the arbitrary data for encryption
• msgSz integer value, specifying the size of the arbitrary data buffer
• out pointer to a byte buffer, where the encrypted data will be stored
• outSz integer value, specifying the size of the encrypted data buffer

See: wolfTPM2_RsaDecrypt

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_RsaDecrypt

WOLFTPM_API int wolfTPM2_RsaDecrypt(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    TPM_ALG_ID padScheme,
    const byte * in,
    int inSz,
    byte * msg,
    int * msgSz
)

Perform RSA decryption using a TPM 2.0 key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a struct of WOLFTPM2_KEY type, holding a TPM key material
• padScheme integer value of TPM_ALG_ID type, specifying the padding scheme
• in pointer to a byte buffer, containing the encrypted data
• inSz integer value, specifying the size of the encrypted data buffer
• msg pointer to a byte buffer, containing the decrypted data
• msgSz pointer to size of the encrypted data buffer, on return set actual size

See: wolfTPM2_RsaEncrypt

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ReadPCR

WOLFTPM_API int wolfTPM2_ReadPCR(
    WOLFTPM2_DEV * dev,
    int pcrIndex,
    int hashAlg,
    byte * digest,
    int * pDigestLen
)

Read the values of a specified TPM 2.0 Platform Configuration Registers(PCR)

Parameters:

• dev pointer to a TPM2_DEV struct
• pcrIndex integer value, specifying a valid PCR index, between 0 and 23 (TPM locality could have an impact on successful access)
• hashAlg integer value, specifying a TPM_ALG_SHA256 or TPM_ALG_SHA1 registers to be accessed
• digest pointer to a byte buffer, where the PCR values will be stored
• pDigestLen pointer to an integer variable, where the size of the digest buffer will be stored

See: wolfTPM2_ExtendPCR

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Make sure to specify the correct hashing algorithm, because there are two sets of PCR registers, one for SHA256 and the other for SHA1(deprecated, but still possible to be read)

function wolfTPM2_ExtendPCR

WOLFTPM_API int wolfTPM2_ExtendPCR(
    WOLFTPM2_DEV * dev,
    int pcrIndex,
    int hashAlg,
    const byte * digest,
    int digestLen
)

Extend a PCR register with a user provided digest.

Parameters:

• dev pointer to a TPM2_DEV struct
• pcrIndex integer value, specifying a valid PCR index, between 0 and 23 (TPM locality could have an impact on successful access)
• hashAlg integer value, specifying a TPM_ALG_SHA256 or TPM_ALG_SHA1 registers to be accessed
• digest pointer to a byte buffer, containing the digest value to be extended into the PCR
• digestLen the size of the digest buffer

See: wolfTPM2_ReadPCR

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Make sure to specify the correct hashing algorithm

function wolfTPM2_NVCreateAuth

WOLFTPM_API int wolfTPM2_NVCreateAuth(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HANDLE * parent,
    WOLFTPM2_NV * nv,
    word32 nvIndex,
    word32 nvAttributes,
    word32 maxSize,
    const byte * auth,
    int authSz
)

Creates a new NV Index to be later used for storing data into the TPM's NVRAM.

Parameters:

• dev pointer to a TPM2_DEV struct
• parent pointer to a WOLFTPM2_HANDLE, specifying the TPM hierarchy for the new NV Index
• nv pointer to an empty structure of WOLFTPM2_NV type, to hold the new NV Index
• nvIndex integer value, holding the NV Index Handle given by the TPM upon success
• nvAttributes integer value, use wolfTPM2_GetNvAttributesTemplate to create correct value
• maxSize integer value, specifying the maximum number of bytes written at this NV Index
• auth pointer to a string constant, specifying the password authorization for this NV Index
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_NVCreateAuthPolicy
• wolfTPM2_NVWriteAuth
• wolfTPM2_NVReadAuth
• wolfTPM2_NVDeleteAuth
• wolfTPM2_NVOpen

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: This is a wolfTPM2 wrapper around TPM2_NV_DefineSpace

function wolfTPM2_NVCreateAuthPolicy

WOLFTPM_API int wolfTPM2_NVCreateAuthPolicy(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HANDLE * parent,
    WOLFTPM2_NV * nv,
    word32 nvIndex,
    word32 nvAttributes,
    word32 maxSize,
    const byte * auth,
    int authSz,
    const byte * authPolicy,
    int authPolicySz
)

Creates a new NV Index to be later used for storing data into the TPM's NVRAM.

Parameters:

• dev pointer to a TPM2_DEV struct
• parent pointer to a WOLFTPM2_HANDLE, specifying the TPM hierarchy for the new NV Index
• nv pointer to an empty structure of WOLFTPM2_NV type, to hold the new NV Index
• nvIndex integer value, holding the NV Index Handle given by the TPM upon success
• nvAttributes integer value, use wolfTPM2_GetNvAttributesTemplate to create correct value
• maxSize integer value, specifying the maximum number of bytes written at this NV Index
• auth pointer to a string constant, specifying the password authorization for this NV Index
• authSz integer value, specifying the size of the password authorization, in bytes
• authPolicy optional policy for using this key (The policy is computed using the nameAlg of the object)
• authPolicySz size of the authPolicy

See:

• wolfTPM2_NVCreateAuth
• wolfTPM2_NVWriteAuth
• wolfTPM2_NVReadAuth
• wolfTPM2_NVDeleteAuth
• wolfTPM2_NVOpen

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: This is a wolfTPM2 wrapper around TPM2_NV_DefineSpace

function wolfTPM2_NVWriteAuth

WOLFTPM_API int wolfTPM2_NVWriteAuth(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_NV * nv,
    word32 nvIndex,
    byte * dataBuf,
    word32 dataSz,
    word32 offset
)

Stores user data to a NV Index, at a given offset.

Parameters:

• dev pointer to a TPM2_DEV struct
• nv pointer to a populated structure of WOLFTPM2_NV type
• nvIndex integer value, holding an existing NV Index Handle value
• dataBuf pointer to a byte buffer, containing the user data to be written to the TPM's NVRAM
• dataSz integer value, specifying the size of the user data buffer, in bytes
• offset integer value of word32 type, specifying the offset from the NV Index memory start, can be zero

See:

• wolfTPM2_NVReadAuth
• wolfTPM2_NVCreateAuth
• wolfTPM2_NVDeleteAuth

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: User data size should be less or equal to the NV Index maxSize specified using wolfTPM2_CreateAuth

function wolfTPM2_NVReadAuth

WOLFTPM_API int wolfTPM2_NVReadAuth(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_NV * nv,
    word32 nvIndex,
    byte * dataBuf,
    word32 * pDataSz,
    word32 offset
)

Reads user data from a NV Index, starting at the given offset.

Parameters:

• dev pointer to a TPM2_DEV struct
• nv pointer to a populated structure of WOLFTPM2_NV type
• nvIndex integer value, holding an existing NV Index Handle value
• dataBuf pointer to an empty byte buffer, used to store the read data from the TPM's NVRAM
• pDataSz pointer to an integer variable, used to store the size of the data read from NVRAM, in bytes
• offset integer value of word32 type, specifying the offset from the NV Index memory start, can be zero

See:

• wolfTPM2_NVWriteAuth
• wolfTPM2_NVCreateAuth
• wolfTPM2_NVDeleteAuth

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: User data size should be less or equal to the NV Index maxSize specified using wolfTPM2_CreateAuth

function wolfTPM2_NVIncrement

WOLFTPM_API int wolfTPM2_NVIncrement(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_NV * nv
)

Increments an NV one-way counter.

Parameters:

• dev pointer to a TPM2_DEV struct
• nv pointer to a populated structure of WOLFTPM2_NV type

See:

• wolfTPM2_NVOpen
• wolfTPM2_NVCreateAuth

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_NVOpen

WOLFTPM_API int wolfTPM2_NVOpen(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_NV * nv,
    word32 nvIndex,
    const byte * auth,
    word32 authSz
)

Open an NV and populate the required authentication and name hash.

Parameters:

• dev pointer to a TPM2_DEV struct
• nv pointer to an empty structure of WOLFTPM2_NV type, to hold the new NV Index
• nvIndex integer value, holding the NV Index Handle given by the TPM upon success
• auth pointer to a string constant, specifying the password authorization for this NV Index
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_NVCreateAuth
• wolfTPM2_UnloadHandle

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_NVWriteLock

WOLFTPM_API int wolfTPM2_NVWriteLock(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_NV * nv
)

Lock writes on the specified NV Index.

Parameters:

• dev pointer to a TPM2_DEV struct
• nv pointer to an structure of WOLFTPM2_NV type loaded using wolfTPM2_NVOpen

See:

• wolfTPM2_NVOpen
• wolfTPM2_NVCreateAuth
• wolfTPM2_NVWriteAuth
• wolfTPM2_NVReadAuth

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_NVDeleteAuth

WOLFTPM_API int wolfTPM2_NVDeleteAuth(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HANDLE * parent,
    word32 nvIndex
)

Destroys an existing NV Index.

Parameters:

• dev pointer to a TPM2_DEV struct
• parent pointer to a WOLFTPM2_HANDLE, specifying the TPM hierarchy for the new NV Index
• nvIndex integer value, holding the NV Index Handle given by the TPM upon success

See:

• wolfTPM2_NVCreateAuth
• wolfTPM2_NVWriteAuth
• wolfTPM2_NVReadAuth

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_NVCreate

WOLFTPM_API int wolfTPM2_NVCreate(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE authHandle,
    word32 nvIndex,
    word32 nvAttributes,
    word32 maxSize,
    const byte * auth,
    int authSz
)

Deprecated, use newer API.

See: wolfTPM2_NVCreateAuth

function wolfTPM2_NVWrite

WOLFTPM_API int wolfTPM2_NVWrite(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE authHandle,
    word32 nvIndex,
    byte * dataBuf,
    word32 dataSz,
    word32 offset
)

Deprecated, use newer API.

See: wolfTPM2_NVWriteAuth

function wolfTPM2_NVRead

WOLFTPM_API int wolfTPM2_NVRead(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE authHandle,
    word32 nvIndex,
    byte * dataBuf,
    word32 * dataSz,
    word32 offset
)

Deprecated, use newer API.

See: wolfTPM2_NVReadAuth

function wolfTPM2_NVDelete

WOLFTPM_API int wolfTPM2_NVDelete(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE authHandle,
    word32 nvIndex
)

Deprecated, use newer API.

See: wolfTPM2_NVDeleteAuth

function wolfTPM2_NVReadPublic

WOLFTPM_API int wolfTPM2_NVReadPublic(
    WOLFTPM2_DEV * dev,
    word32 nvIndex,
    TPMS_NV_PUBLIC * nvPublic
)

Extracts the public information about an nvIndex, such as maximum size.

Parameters:

• dev pointer to a TPM2_DEV struct
• nvIndex integer value, holding the NV Index Handle given by the TPM upon success
• nvPublic pointer to a TPMS_NV_PUBLIC, used to store the extracted nvIndex public information

See:

• wolfTPM2_NVCreateAuth
• wolfTPM2_NVDeleteAuth
• wolfTPM2_NVWriteAuth
• wolfTPM2_NVReadAuth

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_NVStoreKey

WOLFTPM_API int wolfTPM2_NVStoreKey(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE primaryHandle,
    WOLFTPM2_KEY * key,
    TPM_HANDLE persistentHandle
)

Helper function to store a TPM 2.0 Key into the TPM's NVRAM.

Parameters:

• dev pointer to a TPM2_DEV struct
• primaryHandle integer value, specifying a TPM 2.0 Hierarchy. typically TPM_RH_OWNER
• key pointer to a structure of WOLFTPM2_KEY type, containing the TPM 2.0 key for storing
• persistentHandle integer value, specifying an existing nvIndex

See:

• wolfTPM2_NVDeleteKey
• wolfTPM2_NVCreateAuth
• wolfTPM2_NVDeleteAuth

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_NVDeleteKey

WOLFTPM_API int wolfTPM2_NVDeleteKey(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE primaryHandle,
    WOLFTPM2_KEY * key
)

Helper function to delete a TPM 2.0 Key from the TPM's NVRAM.

Parameters:

• dev pointer to a TPM2_DEV struct
• primaryHandle integer value, specifying a TPM 2.0 Hierarchy. typically TPM_RH_OWNER
• key pointer to a structure of WOLFTPM2_KEY type, containing the nvIndex handle value

See:

• wolfTPM2_NVDeleteKey
• wolfTPM2_NVCreateAuth
• wolfTPM2_NVDeleteAuth

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetRng

WOLFTPM_API struct WC_RNG * wolfTPM2_GetRng(
    WOLFTPM2_DEV * dev
)

Get the wolfcrypt RNG instance used for wolfTPM.

Parameters:

• dev pointer to a TPM2_DEV struct

See: wolfTPM2_GetRandom

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Only if wolfcrypt is enabled and configured for use instead of the TPM RNG

function wolfTPM2_GetRandom

WOLFTPM_API int wolfTPM2_GetRandom(
    WOLFTPM2_DEV * dev,
    byte * buf,
    word32 len
)

Get a set of random number, generated with the TPM RNG or wolfcrypt RNG.

Parameters:

• dev pointer to a TPM2_DEV struct
• buf pointer to a byte buffer, used to store the generated random numbers
• len integer value of word32 type, used to store the size of the buffer, in bytes

See: wolfTPM2_GetRandom

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Define WOLFTPM2_USE_HW_RNG to use the TPM RNG source

function wolfTPM2_UnloadHandle

WOLFTPM_API int wolfTPM2_UnloadHandle(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HANDLE * handle
)

Use to discard any TPM loaded object.

Parameters:

• dev pointer to a TPM2_DEV struct
• handle pointer to a structure of WOLFTPM2_HANDLE type, with a valid TPM 2.0 handle value

See: wolfTPM2_Clear

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_Clear

WOLFTPM_API int wolfTPM2_Clear(
    WOLFTPM2_DEV * dev
)

Deinitializes wolfTPM and wolfcrypt(if enabled)

Parameters:

• dev pointer to a TPM2_DEV struct

See: wolfTPM2_Clear

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_HashStart

WOLFTPM_API int wolfTPM2_HashStart(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HASH * hash,
    TPMI_ALG_HASH hashAlg,
    const byte * usageAuth,
    word32 usageAuthSz
)

Helper function to start a TPM generated hash.

Parameters:

• dev pointer to a TPM2_DEV struct
• hash pointer to a WOLFTPM2_HASH structure
• hashAlg integer value, specifying a valid TPM 2.0 hash algorithm
• usageAuth pointer to a string constant, specifying the authorization for subsequent use of the hash
• usageAuthSz integer value, specifying the size of the authorization, in bytes

See:

• wolfTPM2_HashUpdate
• wolfTPM2_HashFinish

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_HashUpdate

WOLFTPM_API int wolfTPM2_HashUpdate(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HASH * hash,
    const byte * data,
    word32 dataSz
)

Update a TPM generated hash with new user data.

Parameters:

• dev pointer to a TPM2_DEV struct
• hash pointer to a WOLFTPM2_HASH structure
• data pointer to a byte buffer, containing the user data to be added to the hash
• dataSz integer value of word32 type, specifying the size of the user data, in bytes

See:

• wolfTPM2_HashStart
• wolfTPM2_HashFinish

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Make sure the auth is correctly set

function wolfTPM2_HashFinish

WOLFTPM_API int wolfTPM2_HashFinish(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HASH * hash,
    byte * digest,
    word32 * digestSz
)

Finalize a TPM generated hash and get the digest output in a user buffer.

Parameters:

• dev pointer to a TPM2_DEV struct
• hash pointer to a WOLFTPM2_HASH structure
• digest pointer to a byte buffer, used to store the resulting digest
• digestSz pointer to size of digest buffer, on return set to bytes stored in digest buffer

See:

• wolfTPM2_HashStart
• wolfTPM2_HashUpdate

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Make sure the auth is correctly set

function wolfTPM2_LoadKeyedHashKey

WOLFTPM_API int wolfTPM2_LoadKeyedHashKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    WOLFTPM2_HANDLE * parent,
    int hashAlg,
    const byte * keyBuf,
    word32 keySz,
    const byte * usageAuth,
    word32 usageAuthSz
)

Creates and loads a new TPM key of KeyedHash type, typically used for HMAC operations.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty structure of WOLFTPM2_KEY type, to store the generated key
• parent pointer to a structure of WOLFTPM2_KEY type, containing a valid TPM handle of a primary key
• hashAlg integer value, specifying a valid TPM 2.0 hash algorithm
• keyBuf pointer to a byte array, containing derivation values for the new KeyedHash key
• keySz integer value, specifying the size of the derivation values stored in keyBuf, in bytes
• usageAuth pointer to a string constant, specifying the authorization of the new key
• usageAuthSz integer value, specifying the size of the authorization, in bytes

See:

• wolfTPM2_HmacStart
• wolfTPM2_HmacUpdate
• wolfTPM2_HmacFinish

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: To generate HMAC using the TPM it is recommended to use the wolfTPM2_Hmac wrappers

function wolfTPM2_HmacStart

WOLFTPM_API int wolfTPM2_HmacStart(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HMAC * hmac,
    WOLFTPM2_HANDLE * parent,
    TPMI_ALG_HASH hashAlg,
    const byte * keyBuf,
    word32 keySz,
    const byte * usageAuth,
    word32 usageAuthSz
)

Helper function to start a TPM generated hmac.

Parameters:

• dev pointer to a TPM2_DEV struct
• hmac pointer to a WOLFTPM2_HMAC structure
• parent pointer to a structure of WOLFTPM2_KEY type, containing a valid TPM handle of a primary key
• hashAlg integer value, specifying a valid TPM 2.0 hash algorithm
• keyBuf pointer to a byte array, containing derivation values for the new KeyedHash key
• keySz integer value, specifying the size of the derivation values stored in keyBuf, in bytes
• usageAuth pointer to a string constant, specifying the authorization for subsequent use of the hmac
• usageAuthSz integer value, specifying the size of the authorization, in bytes

See:

• wolfTPM2_HmacUpdate
• wolfTPM2_HmacFinish
• wolfTPM2_LoadKeyedHashKey

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_HmacUpdate

WOLFTPM_API int wolfTPM2_HmacUpdate(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HMAC * hmac,
    const byte * data,
    word32 dataSz
)

Update a TPM generated hmac with new user data.

Parameters:

• dev pointer to a TPM2_DEV struct
• hmac pointer to a WOLFTPM2_HMAC structure
• data pointer to a byte buffer, containing the user data to be added to the hmac
• dataSz integer value of word32 type, specifying the size of the user data, in bytes

See:

• wolfTPM2_HmacStart
• wolfTPM2_HMACFinish

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Make sure the TPM authorization is correctly set

function wolfTPM2_HmacFinish

WOLFTPM_API int wolfTPM2_HmacFinish(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_HMAC * hmac,
    byte * digest,
    word32 * digestSz
)

Finalize a TPM generated hmac and get the digest output in a user buffer.

Parameters:

• dev pointer to a TPM2_DEV struct
• hmac pointer to a WOLFTPM2_HMAC structure
• digest pointer to a byte buffer, used to store the resulting hmac digest
• digestSz integer value of word32 type, specifying the size of the digest, in bytes

See:

• wolfTPM2_HmacStart
• wolfTPM2_HmacUpdate

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Make sure the TPM authorization is correctly set

function wolfTPM2_LoadSymmetricKey

WOLFTPM_API int wolfTPM2_LoadSymmetricKey(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    int alg,
    const byte * keyBuf,
    word32 keySz
)

Loads an external symmetric key into the TPM.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to an empty structure of WOLFTPM2_KEY type, to store the TPM handle and key information
• alg integer value, specifying a valid TPM 2.0 symmetric key algorithm, e.g. TPM_ALG_CFB for AES CFB
• keyBuf pointer to a byte array, containing private material of the symmetric key
• keySz integer value, specifying the size of the key material stored in keyBuf, in bytes

See:

• wolfTPM2_EncryptDecryptBlock
• wolfTPM2_EncryptDecrypt
• TPM2_EncryptDecrypt2

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_SetCommand

WOLFTPM_API int wolfTPM2_SetCommand(
    WOLFTPM2_DEV * dev,
    TPM_CC commandCode,
    int enableFlag
)

Vendor specific TPM command, used to enable other restricted TPM commands.

Parameters:

• dev pointer to a TPM2_DEV struct
• commandCode integer value, representing a valid vendor command
• enableFlag integer value, non-zero values represent "to enable"

See: TPM2_GPIO_Config

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_Shutdown

WOLFTPM_API int wolfTPM2_Shutdown(
    WOLFTPM2_DEV * dev,
    int doStartup
)

Helper function to shutdown or reset the TPM.

Parameters:

• dev pointer to a TPM2_DEV struct
• doStartup integer value, non-zero values represent "perform Startup after Shutdown"

See: wolfTPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: If doStartup is set, then TPM2_Startup is performed right after TPM2_Shutdown

function wolfTPM2_UnloadHandles

WOLFTPM_API int wolfTPM2_UnloadHandles(
    WOLFTPM2_DEV * dev,
    word32 handleStart,
    word32 handleCount
)

One-shot API to unload subsequent TPM handles.

Parameters:

• dev pointer to a TPM2_DEV struct
• handleStart integer value of word32 type, specifying the value of the first TPM handle
• handleCount integer value of word32 type, specifying the number of handles

See: wolfTPM2_Init

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_UnloadHandles_AllTransient

WOLFTPM_API int wolfTPM2_UnloadHandles_AllTransient(
    WOLFTPM2_DEV * dev
)

One-shot API to unload all transient TPM handles.

Parameters:

• dev pointer to a TPM2_DEV struct

See:

• wolfTPM2_UnloadHandles
• wolfTPM2_CreatePrimary

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: If there are Primary Keys as transient objects, they need to be recreated before TPM keys can be used

function wolfTPM2_GetKeyTemplate_RSA

WOLFTPM_API int wolfTPM2_GetKeyTemplate_RSA(
    TPMT_PUBLIC * publicTemplate,
    TPMA_OBJECT objectAttributes
)

Prepares a TPM public template for new RSA key based on user selected object attributes.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new RSA template
• objectAttributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM

See:

• wolfTPM2_GetKeyTemplate_RSA_ex
• wolfTPM2_GetKeyTemplate_ECC
• wolfTPM2_GetKeyTemplate_Symmetric
• wolfTPM2_GetKeyTemplate_KeyedHash
• wolfTPM2_GetKeyTemplate_KeySeal

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_RSA_ex

WOLFTPM_API int wolfTPM2_GetKeyTemplate_RSA_ex(
    TPMT_PUBLIC * publicTemplate,
    TPM_ALG_ID nameAlg,
    TPMA_OBJECT objectAttributes,
    int keyBits,
    long exponent,
    TPM_ALG_ID sigScheme,
    TPM_ALG_ID sigHash
)

Prepares a TPM public template for new RSA key based on user selected object attributes.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new RSA template
• nameAlg integer value of TPM_ALG_ID type, specifying a TPM supported hashing algorithm, typically TPM_ALG_SHA256 for SHA 256
• objectAttributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM
• keyBits integer value, specifying the size of the symmetric key, typically 128 or 256 bits
• exponent integer value of word32 type, specifying the RSA exponent
• sigScheme integer value of TPM_ALG_ID type, specifying a TPM supported signature scheme
• sigHash integer value of TPM_ALG_ID type, specifying a TPM supported signature hash scheme

See:

• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_ECC
• wolfTPM2_GetKeyTemplate_ECC_ex
• wolfTPM2_GetKeyTemplate_Symmetric
• wolfTPM2_GetKeyTemplate_KeyedHash
• wolfTPM2_GetKeyTemplate_KeySeal

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_ECC

WOLFTPM_API int wolfTPM2_GetKeyTemplate_ECC(
    TPMT_PUBLIC * publicTemplate,
    TPMA_OBJECT objectAttributes,
    TPM_ECC_CURVE curve,
    TPM_ALG_ID sigScheme
)

Prepares a TPM public template for new ECC key based on user selected object attributes.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new ECC key template
• objectAttributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM
• curve integer value of TPM_ECC_CURVE type, specifying a TPM supported ECC curve ID
• sigScheme integer value of TPM_ALG_ID type, specifying a TPM supported signature scheme

See:

• wolfTPM2_GetKeyTemplate_ECC_ex
• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_Symmetric
• wolfTPM2_GetKeyTemplate_KeyedHash
• wolfTPM2_GetKeyTemplate_KeySeal

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_ECC_ex

WOLFTPM_API int wolfTPM2_GetKeyTemplate_ECC_ex(
    TPMT_PUBLIC * publicTemplate,
    TPM_ALG_ID nameAlg,
    TPMA_OBJECT objectAttributes,
    TPM_ECC_CURVE curve,
    TPM_ALG_ID sigScheme,
    TPM_ALG_ID sigHash
)

Prepares a TPM public template for new ECC key based on user selected object attributes.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new ECC key template
• nameAlg integer value of TPM_ALG_ID type, specifying a TPM supported hashing algorithm, typically TPM_ALG_SHA256 for SHA 256
• objectAttributes integer value of TPMA_OBJECT type, can contain one or more attributes, e.g. TPMA_OBJECT_fixedTPM
• curve integer value of TPM_ECC_CURVE type, specifying a TPM supported ECC curve ID
• sigScheme integer value of TPM_ALG_ID type, specifying a TPM supported signature scheme
• sigHash integer value of TPM_ALG_ID type, specifying a TPM supported signature hash scheme

See:

• wolfTPM2_GetKeyTemplate_ECC
• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_Symmetric
• wolfTPM2_GetKeyTemplate_KeyedHash
• wolfTPM2_GetKeyTemplate_KeySeal

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_Symmetric

WOLFTPM_API int wolfTPM2_GetKeyTemplate_Symmetric(
    TPMT_PUBLIC * publicTemplate,
    int keyBits,
    TPM_ALG_ID algMode,
    int isSign,
    int isDecrypt
)

Prepares a TPM public template for new Symmetric key.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new Symmetric key template
• keyBits integer value, specifying the size of the symmetric key, typically 128 or 256 bits
• algMode integer value of TPM_ALG_ID type, specifying a TPM supported symmetric algorithm, e.g. TPM_ALG_CFB for AES CFB
• isSign integer value, non-zero values represent "a signing key"
• isDecrypt integer value, non-zero values represent "a decryption key"

See:

• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_ECC
• wolfTPM2_GetKeyTemplate_KeyedHash
• wolfTPM2_GetKeyTemplate_KeySeal

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_KeyedHash

WOLFTPM_API int wolfTPM2_GetKeyTemplate_KeyedHash(
    TPMT_PUBLIC * publicTemplate,
    TPM_ALG_ID hashAlg,
    int isSign,
    int isDecrypt
)

Prepares a TPM public template for new KeyedHash key.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template
• hashAlg integer value of TPM_ALG_ID type, specifying a TPM supported hashing algorithm, e.g. TPM_ALG_SHA256 for SHA 256
• isSign integer value, non-zero values represent "a signing key"
• isDecrypt integer value, non-zero values represent "a decryption key"

See:

• wolfTPM2_GetKeyTemplate_RSA
• wolfTPM2_GetKeyTemplate_ECC
• wolfTPM2_GetKeyTemplate_Symmetric
• wolfTPM2_GetKeyTemplate_KeySeal

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_KeySeal

WOLFTPM_API int wolfTPM2_GetKeyTemplate_KeySeal(
    TPMT_PUBLIC * publicTemplate,
    TPM_ALG_ID nameAlg
)

Prepares a TPM public template for new key for sealing secrets.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template
• nameAlg integer value of TPM_ALG_ID type, specifying a TPM supported hashing algorithm, typically TPM_ALG_SHA256 for SHA 256

See:

• wolfTPM2_GetKeyTemplate_ECC
• wolfTPM2_GetKeyTemplate_Symmetric
• wolfTPM2_GetKeyTemplate_KeyedHash
• wolfTPM2_GetKeyTemplate_KeySeal

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

Note: There are strict requirements for a Key Seal, therefore most of the key parameters are predetermined by the wrapper

function wolfTPM2_GetKeyTemplate_RSA_EK

WOLFTPM_API int wolfTPM2_GetKeyTemplate_RSA_EK(
    TPMT_PUBLIC * publicTemplate
)

Prepares a TPM public template for generating the TPM Endorsement Key of RSA type.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template

See:

• wolfTPM2_GetKeyTemplate_ECC_EK
• wolfTPM2_GetKeyTemplate_RSA_SRK
• wolfTPM2_GetKeyTemplate_RSA_AIK

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_ECC_EK

WOLFTPM_API int wolfTPM2_GetKeyTemplate_ECC_EK(
    TPMT_PUBLIC * publicTemplate
)

Prepares a TPM public template for generating the TPM Endorsement Key of ECC type.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template

See:

• wolfTPM2_GetKeyTemplate_RSA_EK
• wolfTPM2_GetKeyTemplate_ECC_SRK
• wolfTPM2_GetKeyTemplate_ECC_AIK

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_RSA_SRK

WOLFTPM_API int wolfTPM2_GetKeyTemplate_RSA_SRK(
    TPMT_PUBLIC * publicTemplate
)

Prepares a TPM public template for generating a new TPM Storage Key of RSA type.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template

See:

• wolfTPM2_GetKeyTemplate_ECC_SRK
• wolfTPM2_GetKeyTemplate_RSA_AIK
• wolfTPM2_GetKeyTemplate_RSA_EK

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_ECC_SRK

WOLFTPM_API int wolfTPM2_GetKeyTemplate_ECC_SRK(
    TPMT_PUBLIC * publicTemplate
)

Prepares a TPM public template for generating a new TPM Storage Key of ECC type.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template

See:

• wolfTPM2_GetKeyTemplate_RSA_SRK
• wolfTPM2_GetKeyTemplate_ECC_AIK
• wolfTPM2_GetKeyTemplate_ECC_EK

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_RSA_AIK

WOLFTPM_API int wolfTPM2_GetKeyTemplate_RSA_AIK(
    TPMT_PUBLIC * publicTemplate
)

Prepares a TPM public template for generating a new TPM Attestation Key of RSA type.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template

See:

• wolfTPM2_GetKeyTemplate_ECC_AIK
• wolfTPM2_GetKeyTemplate_RSA_SRK

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyTemplate_ECC_AIK

WOLFTPM_API int wolfTPM2_GetKeyTemplate_ECC_AIK(
    TPMT_PUBLIC * publicTemplate
)

Prepares a TPM public template for generating a new TPM Attestation Key of ECC type.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template

See:

• wolfTPM2_GetKeyTemplate_RSA_AIK
• wolfTPM2_GetKeyTemplate_ECC_SRK

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_SetKeyTemplate_Unique

WOLFTPM_API int wolfTPM2_SetKeyTemplate_Unique(
    TPMT_PUBLIC * publicTemplate,
    const byte * unique,
    int uniqueSz
)

Sets the unique area of a public template used by Create or CreatePrimary.

Parameters:

• publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template
• unique optional pointer to buffer to populate unique area of public template. If NULL, the buffer will be zeroized.
• uniqueSz size to fill the unique field. If zero the key size is used.

See:

• wolfTPM2_CreateKey
• wolfTPM2_CreatePrimaryKey

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetNvAttributesTemplate

WOLFTPM_API int wolfTPM2_GetNvAttributesTemplate(
    TPM_HANDLE auth,
    word32 * nvAttributes
)

Prepares a TPM NV Index template.

Parameters:

• auth integer value, representing the TPM Hierarchy under which the new TPM NV index will be created
• nvAttributes pointer to an empty integer variable, to store the NV Attributes

See:

• wolfTPM2_CreateAuth
• wolfTPM2_WriteAuth
• wolfTPM2_ReadAuth
• wolfTPM2_DeleteAuth

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CreateEK

WOLFTPM_API int wolfTPM2_CreateEK(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * ekKey,
    TPM_ALG_ID alg
)

Generates a new TPM Endorsement key, based on the user selected algorithm, RSA or ECC.

Parameters:

• dev pointer to a TPM2_DEV struct
• ekKey pointer to an empty WOLFTPM2_KEY structure, to store information about the new EK
• alg can be only TPM_ALG_RSA or TPM_ALG_ECC, see Note above

See:

• wolfTPM2_CreateSRK
• wolfTPM2_GetKeyTemplate_RSA_EK
• wolfTPM2_GetKeyTemplate_ECC_EK

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

Note: Although only RSA and ECC can be used for EK, symmetric keys can be created and used by the TPM

function wolfTPM2_CreateSRK

WOLFTPM_API int wolfTPM2_CreateSRK(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * srkKey,
    TPM_ALG_ID alg,
    const byte * auth,
    int authSz
)

Generates a new TPM Primary Key that will be used as a Storage Key for other TPM keys.

Parameters:

• dev pointer to a TPM2_DEV struct
• srkKey pointer to an empty WOLFTPM2_KEY structure, to store information about the new EK
• alg can be only TPM_ALG_RSA or TPM_ALG_ECC, see Note above
• auth pointer to a string constant, specifying the password authorization for the TPM 2.0 Key
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_CreateEK
• wolfTPM2_CreateAndLoadAIK
• wolfTPM2_GetKeyTemplate_RSA_SRK
• wolfTPM2_GetKeyTemplate_ECC_SRK

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: Although only RSA and ECC can be used for EK, symmetric keys can be created and used by the TPM

function wolfTPM2_CreateAndLoadAIK

WOLFTPM_API int wolfTPM2_CreateAndLoadAIK(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * aikKey,
    TPM_ALG_ID alg,
    WOLFTPM2_KEY * srkKey,
    const byte * auth,
    int authSz
)

Generates a new TPM Attestation Key under the provided Storage Key.

Parameters:

• dev pointer to a TPM2_DEV struct
• aikKey pointer to an empty WOLFTPM2_KEY structure, to store the newly generated TPM key
• alg can be only TPM_ALG_RSA or TPM_ALG_ECC
• srkKey pointer to a WOLFTPM2_KEY structure, pointing to valid TPM handle of a loaded Storage Key
• auth pointer to a string constant, specifying the password authorization for the TPM 2.0 Key
• authSz integer value, specifying the size of the password authorization, in bytes

See:

• wolfTPM2_CreateSRK
• wolfTPM2_GetKeyTemplate_RSA_AIK
• wolfTPM2_GetKeyTemplate_ECC_AIK

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetTime

WOLFTPM_API int wolfTPM2_GetTime(
    WOLFTPM2_KEY * aikKey,
    GetTime_Out * getTimeOut
)

One-shot API to generate a TPM signed timestamp.

Parameters:

• aikKey pointer to a WOLFTPM2_KEY structure, containing valid TPM handle of a loaded attestation key
• getTimeOut pointer to an empty structure of GetTime_Out type, to store the output of the command

See:

• wolfTPM2_CreateSRK
• wolfTPM2_GetKeyTemplate_RSA_EK
• wolfTPM2_GetKeyTemplate_ECC_EK

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

Note: The attestation key must be generated and loaded prior to this call

function wolfTPM2_CSR_SetCustomExt

WOLFTPM_API int wolfTPM2_CSR_SetCustomExt(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_CSR * csr,
    int critical,
    const char * oid,
    const byte * der,
    word32 derSz
)

Helper for Certificate Signing Request (CSR) generation to set a custom request extension oid and value usage for a WOLFTPM2_CSR structure.

Parameters:

• dev pointer to a TPM2_DEV struct (not used)
• csr pointer to a WOLFTPM2_CSR structure
• critical If 0, the extension will not be marked critical, otherwise it will be marked critical.
• oid Dot separated oid as a string. For example "1.2.840.10045.3.1.7"
• der The der encoding of the content of the extension.
• derSz The size in bytes of the der encoding.

See:

• wolfTPM2_CSR_SetSubject
• wolfTPM2_CSR_SetKeyUsage
• wolfTPM2_CSR_MakeAndSign
• wolfTPM2_CSR_MakeAndSign_ex

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CSR_SetKeyUsage

WOLFTPM_API int wolfTPM2_CSR_SetKeyUsage(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_CSR * csr,
    const char * keyUsage
)

Helper for Certificate Signing Request (CSR) generation to set a extended key usage or key usage for a WOLFTPM2_CSR structure. Pass either extended key usage or key usage values. Mixed string types are not supported, however you can call wolfTPM2_CSR_SetKeyUsage twice (once for extended key usage strings and once for standard key usage strings).

Parameters:

• dev pointer to a TPM2_DEV struct (not used)
• csr pointer to a WOLFTPM2_CSR structure
• keyUsage string list of comma separated key usage attributes. Possible Extended Key Usage values: any, serverAuth, clientAuth, codeSigning, emailProtection, timeStamping and OCSPSigning Possible Key Usage values: digitalSignature, nonRepudiation, contentCommitment, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly Default: "serverAuth,clientAuth,codeSigning"

See:

• wolfTPM2_CSR_SetSubject
• wolfTPM2_CSR_SetCustomExt
• wolfTPM2_CSR_MakeAndSign
• wolfTPM2_CSR_MakeAndSign_ex

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CSR_SetSubject

WOLFTPM_API int wolfTPM2_CSR_SetSubject(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_CSR * csr,
    const char * subject
)

Helper for Certificate Signing Request (CSR) generation to set a subject for a WOLFTPM2_CSR structure.

Parameters:

• dev pointer to a TPM2_DEV struct (not used)
• csr pointer to a WOLFTPM2_CSR structure
• subject distinguished name string using /CN= syntax. Example: "/C=US/ST=Washington/L=Seattle/O=wolfSSL/OU=Development/CN=www.wolfssl.com/emailAddress=info@wolfssl.com"

See:

• wolfTPM2_CSR_SetKeyUsage
• wolfTPM2_CSR_SetCustomExt
• wolfTPM2_CSR_MakeAndSign
• wolfTPM2_CSR_MakeAndSign_ex

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CSR_MakeAndSign_ex

WOLFTPM_API int wolfTPM2_CSR_MakeAndSign_ex(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_CSR * csr,
    WOLFTPM2_KEY * key,
    int outFormat,
    byte * out,
    int outSz,
    int sigType,
    int selfSignCert,
    int devId
)

Helper for Certificate Signing Request (CSR) generation using a TPM based key (WOLFTPM2_KEY). Uses a provided WOLFTPM2_CSR structure with subject and key usage already set.

Parameters:

• dev pointer to a TPM2_DEV struct
• csr pointer to a WOLFTPM2_CSR structure
• key WOLFTPM2_KEY structure
• outFormat CTC_FILETYPE_ASN1 or CTC_FILETYPE_PEM
• out destination buffer for CSR as ASN.1/DER or PEM
• outSz destination buffer maximum size
• sigType Use 0 to automatically select SHA2-256 based on keyType (CTC_SHA256wRSA or CTC_SHA256wECDSA). See wolfCrypt "enum Ctc_SigType" for list of possible values.
• selfSignCert If set to 1 (non-zero) then result will be a self signed certificate. Zero (0) will generate a CSR (Certificate Signing Request) to be used by a CA.
• devId The device identifier used when registering the crypto callback. Use INVALID_DEVID (-2) to automatically register the required crypto callback.

See:

• wolfTPM2_CSR_SetSubject
• wolfTPM2_CSR_SetKeyUsage
• wolfTPM2_CSR_SetCustomExt
• wolfTPM2_CSR_MakeAndSign

Return:

• Success: Positive integer (size of the output)
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CSR_MakeAndSign

WOLFTPM_API int wolfTPM2_CSR_MakeAndSign(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_CSR * csr,
    WOLFTPM2_KEY * key,
    int outFormat,
    byte * out,
    int outSz
)

Helper for Certificate Signing Request (CSR) generation using a TPM based key (WOLFTPM2_KEY). Uses a provided WOLFTPM2_CSR structure with subject and key usage already set.

Parameters:

• dev pointer to a TPM2_DEV struct
• csr pointer to a WOLFTPM2_CSR structure
• key WOLFTPM2_KEY structure
• outFormat CTC_FILETYPE_ASN1 or CTC_FILETYPE_PEM
• out destination buffer for CSR as ASN.1/DER or PEM
• outSz destination buffer maximum size

See:

• wolfTPM2_CSR_SetSubject
• wolfTPM2_CSR_SetKeyUsage
• wolfTPM2_CSR_SetCustomExt
• wolfTPM2_CSR_MakeAndSign_ex

Return:

• Success: Positive integer (size of the output)
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CSR_Generate_ex

WOLFTPM_API int wolfTPM2_CSR_Generate_ex(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const char * subject,
    const char * keyUsage,
    int outFormat,
    byte * out,
    int outSz,
    int sigType,
    int selfSignCert,
    int devId
)

Helper for Certificate Signing Request (CSR) generation using a TPM based key (WOLFTPM2_KEY). Single shot API for outputting a CSR or self-signed cert based on TPM key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a loaded WOLFTPM2_KEY structure
• subject distinguished name string using /CN= syntax. Example: "/C=US/ST=Washington/L=Seattle/O=wolfSSL/OU=Development/CN=www.wolfssl.com/emailAddress=info@wolfssl.com"
• keyUsage string list of comma separated key usage attributes. Possible values: any, serverAuth, clientAuth, codeSigning, emailProtection, timeStamping and OCSPSigning Default: "serverAuth,clientAuth,codeSigning"
• outFormat CTC_FILETYPE_ASN1 or CTC_FILETYPE_PEM
• out destination buffer for CSR as ASN.1/DER or PEM
• outSz destination buffer maximum size
• sigType Use 0 to automatically select SHA2-256 based on keyType (CTC_SHA256wRSA or CTC_SHA256wECDSA). See wolfCrypt "enum Ctc_SigType" for list of possible values.
• selfSignCert If set to 1 (non-zero) then result will be a self signed certificate. Zero (0) will generate a CSR (Certificate Signing Request) to be used by a CA.
• devId The device identifier used when registering the crypto callback. Use INVALID_DEVID (-2) to automatically register the required crypto callback.

See:

• wolfTPM2_SetCryptoDevCb
• wolfTPM2_CSR_Generate

Return:

• Success: Positive integer (size of the output)
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CSR_Generate

WOLFTPM_API int wolfTPM2_CSR_Generate(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_KEY * key,
    const char * subject,
    const char * keyUsage,
    int outFormat,
    byte * out,
    int outSz
)

Helper for Certificate Signing Request (CSR) generation using a TPM based key (WOLFTPM2_KEY). Single shot API for outputting a CSR or self-signed cert based on TPM key.

Parameters:

• dev pointer to a TPM2_DEV struct
• key pointer to a loaded WOLFTPM2_KEY structure
• subject distinguished name string using /CN= syntax. Example: "/C=US/ST=Washington/L=Seattle/O=wolfSSL/OU=Development/CN=www.wolfssl.com/emailAddress=info@wolfssl.com"
• keyUsage string list of comma separated key usage attributes. Possible values: any, serverAuth, clientAuth, codeSigning, emailProtection, timeStamping and OCSPSigning Default: "serverAuth,clientAuth,codeSigning"
• outFormat CTC_FILETYPE_ASN1 or CTC_FILETYPE_PEM
• out destination buffer for CSR as ASN.1/DER or PEM
• outSz destination buffer maximum size

See:

• wolfTPM2_SetCryptoDevCb
• wolfTPM2_CSR_Generate_ex

Return:

• Success: Positive integer (size of the output)
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ChangePlatformAuth

WOLFTPM_API int wolfTPM2_ChangePlatformAuth(
    WOLFTPM2_DEV * dev,
    WOLFTPM2_SESSION * session
)

Helper to set the platform heirarchy authentication value to random. Setting the platform auth to random value is used to prevent application from being able to use platform hierarchy. This is defined in section 10 of the TCG PC Client Platform specification.

Parameters:

• dev pointer to a TPM2_DEV struct
• session the current session, a session is required to protect the new platform auth

See: TPM2_HierarchyChangeAuth

Return:

• Success: Positive integer (size of the output)
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_CryptoDevCb

WOLFTPM_API int wolfTPM2_CryptoDevCb(
    int devId,
    wc_CryptoInfo * info,
    void * ctx
)

A reference crypto callback API for using the TPM for crypto offload. This callback function is registered using wolfTPM2_SetCryptoDevCb or wc_CryptoDev_RegisterDevice.

Parameters:

• devId The devId used when registering the callback. Any signed integer value besides INVALID_DEVID
• info point to wc_CryptoInfo structure with detailed information about crypto type and parameters
• ctx The user context supplied when callback was registered with wolfTPM2_SetCryptoDevCb

See:

• wolfTPM2_SetCryptoDevCb
• wolfTPM2_ClearCryptoDevCb

Return:

• TPM_RC_SUCCESS: successful
• CRYPTOCB_UNAVAILABLE: Do not use TPM hardware, fall-back to default software crypto.
• WC_HW_E: generic hardware failure

function wolfTPM2_SetCryptoDevCb

WOLFTPM_API int wolfTPM2_SetCryptoDevCb(
    WOLFTPM2_DEV * dev,
    CryptoDevCallbackFunc cb,
    TpmCryptoDevCtx * tpmCtx,
    int * pDevId
)

Register a crypto callback function and return assigned devId.

Parameters:

• dev pointer to a TPM2_DEV struct
• cb The wolfTPM2_CryptoDevCb API is a template, but you can also provide your own
• tpmCtx The user supplied context. For wolfTPM2_CryptoDevCb use TpmCryptoDevCtx, but can also be your own.
• pDevId Pointer to automatically assigned device ID.

See:

• wolfTPM2_CryptoDevCb
• wolfTPM2_ClearCryptoDevCb

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_ClearCryptoDevCb

WOLFTPM_API int wolfTPM2_ClearCryptoDevCb(
    WOLFTPM2_DEV * dev,
    int devId
)

Clears the registered crypto callback.

Parameters:

• dev pointer to a TPM2_DEV struct
• devId The devId used when registering the callback

See:

• wolfTPM2_CryptoDevCb
• wolfTPM2_SetCryptoDevCb

Return:

• TPM_RC_SUCCESS: successful
• TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code)
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_New

WOLFTPM_API WOLFTPM2_DEV * wolfTPM2_New(
    void 
)

Allocate and initialize a WOLFTPM2_DEV.

See: wolfTPM2_Free

Return:

• pointer to new device struct
• NULL: on any error

function wolfTPM2_Free

WOLFTPM_API int wolfTPM2_Free(
    WOLFTPM2_DEV * dev
)

Cleanup and Free a WOLFTPM2_DEV that was allocated by wolfTPM2_New.

Parameters:

• dev pointer to a TPM2_DEV struct

See: wolfTPM2_New

Return: TPM_RC_SUCCESS: successful

function wolfTPM2_NewKeyBlob

WOLFTPM_API WOLFTPM2_KEYBLOB * wolfTPM2_NewKeyBlob(
    void 
)

Allocate and initialize a WOLFTPM2_KEYBLOB.

See: wolfTPM2_FreeKeyBlob

Return:

• pointer to newly initialized WOLFTPM2_KEYBLOB
• NULL on any error

function wolfTPM2_FreeKeyBlob

WOLFTPM_API int wolfTPM2_FreeKeyBlob(
    WOLFTPM2_KEYBLOB * blob
)

Free a WOLFTPM2_KEYBLOB that was allocated with wolfTPM2_NewKeyBlob.

Parameters:

• blob pointer to a WOLFTPM2_KEYBLOB that was allocated by wolfTPM2_NewKeyBlob

See: wolfTPM2_NewKeyBlob

Return: TPM_RC_SUCCESS: successful

function wolfTPM2_NewPublicTemplate

WOLFTPM_API TPMT_PUBLIC * wolfTPM2_NewPublicTemplate(
    void 
)

Allocate and initialize a TPMT_PUBLIC.

See: wolfTPM2_FreePublicTemplate

Return:

• pointer to newly initialized
• NULL on any error

function wolfTPM2_FreePublicTemplate

WOLFTPM_API int wolfTPM2_FreePublicTemplate(
    TPMT_PUBLIC * PublicTemplate
)

Free a TPMT_PUBLIC that was allocated with wolfTPM2_NewPublicTemplate.

Parameters:

• PublicTemplate pointer to a TPMT_PUBLIC that was allocated with wolfTPM2_NewPublicTemplate

See: wolfTPM2_NewPublicTemplate

Return: TPM_RC_SUCCESS: successful

function wolfTPM2_NewKey

WOLFTPM_API WOLFTPM2_KEY * wolfTPM2_NewKey(
    void 
)

Allocate and initialize a WOLFTPM2_KEY.

See: wolfTPM2_FreeKey

Return:

• pointer to newly initialized WOLFTPM2_KEY
• NULL on any error

function wolfTPM2_FreeKey

WOLFTPM_API int wolfTPM2_FreeKey(
    WOLFTPM2_KEY * key
)

Free a WOLFTPM2_KEY that was allocated with wolfTPM2_NewKey.

Parameters:

• key pointer to a WOLFTPM2_KEY that was allocated by wolfTPM2_NewKey

See: wolfTPM2_NewKey

Return: TPM_RC_SUCCESS: successful

function wolfTPM2_NewSession

WOLFTPM_API WOLFTPM2_SESSION * wolfTPM2_NewSession(
    void 
)

Allocate and initialize a WOLFTPM2_SESSION.

See: wolfTPM2_FreeSession

Return:

• pointer to newly initialized WOLFTPM2_SESSION
• NULL on any error

function wolfTPM2_FreeSession

WOLFTPM_API int wolfTPM2_FreeSession(
    WOLFTPM2_SESSION * session
)

Free a WOLFTPM2_SESSION that was allocated with wolfTPM2_NewSession.

Parameters:

• session pointer to a WOLFTPM2_SESSION struct

See: wolfTPM2_NewSession

Return: TPM_RC_SUCCESS: successful

function wolfTPM2_NewCSR

WOLFTPM_API WOLFTPM2_CSR * wolfTPM2_NewCSR(
    void 
)

Allocate and initialize a WOLFTPM2_CSR.

See: wolfTPM2_FreeCSR

Return:

• pointer to newly initialized WOLFTPM2_CSR
• NULL on any error

function wolfTPM2_FreeCSR

WOLFTPM_API int wolfTPM2_FreeCSR(
    WOLFTPM2_CSR * csr
)

Free a WOLFTPM2_CSR that was allocated with wolfTPM2_NewCSR.

Parameters:

• csr pointer to a WOLFTPM2_CSR that was allocated by wolfTPM2_NewCSR

See: wolfTPM2_NewCSR

Return: TPM_RC_SUCCESS: successful

function wolfTPM2_GetHandleRefFromKey

WOLFTPM_API WOLFTPM2_HANDLE * wolfTPM2_GetHandleRefFromKey(
    WOLFTPM2_KEY * key
)

Retrieve the WOLFTPM2_HANDLE from a WOLFTPM2_KEY.

Parameters:

• key pointer to a WOLFTPM2_KEY struct

Return:

• pointer to handle in the key structure
• NULL if key pointer is NULL

function wolfTPM2_GetHandleRefFromKeyBlob

WOLFTPM_API WOLFTPM2_HANDLE * wolfTPM2_GetHandleRefFromKeyBlob(
    WOLFTPM2_KEYBLOB * keyBlob
)

Retrieve the WOLFTPM2_HANDLE from a WOLFTPM2_KEYBLOB.

Parameters:

• keyBlob pointer to a WOLFTPM2_KEYBLOB struct

Return:

• pointer to handle in the key blob structure
• NULL if key pointer is NULL

function wolfTPM2_GetHandleRefFromSession

WOLFTPM_API WOLFTPM2_HANDLE * wolfTPM2_GetHandleRefFromSession(
    WOLFTPM2_SESSION * session
)

Retrieve the WOLFTPM2_HANDLE from a WOLFTPM2_SESSION.

Parameters:

• session pointer to a WOLFTPM2_SESSION struct

Return:

• pointer to handle in the session structure
• NULL if key pointer is NULL

function wolfTPM2_GetHandleValue

WOLFTPM_API TPM_HANDLE wolfTPM2_GetHandleValue(
    WOLFTPM2_HANDLE * handle
)

Get the 32-bit handle value from the WOLFTPM2_HANDLE.

Parameters:

• handle pointer to WOLFTPM2_HANDLE structure

Return: TPM_HANDLE value from TPM

function wolfTPM2_SetKeyAuthPassword

WOLFTPM_API int wolfTPM2_SetKeyAuthPassword(
    WOLFTPM2_KEY * key,
    const byte * auth,
    int authSz
)

Set the authentication data for a key.

Parameters:

• key pointer to wrapper key struct
• auth pointer to auth data
• authSz length in bytes of auth data

Return:

• TPM_RC_SUCCESS: successful
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyBlobAsBuffer

WOLFTPM_API int wolfTPM2_GetKeyBlobAsBuffer(
    byte * buffer,
    word32 bufferSz,
    WOLFTPM2_KEYBLOB * key
)

Marshal data from a keyblob to a binary buffer. This can be stored to disk for loading in a separate process or after power cycling. If buffer is not provided then size only will be returned.

Parameters:

• buffer pointer to buffer in which to store marshaled keyblob
• bufferSz size of the above buffer
• key pointer to keyblob to marshal

See: wolfTPM2_SetKeyBlobFromBuffer

Return:

• Positive integer (size of the output)
• BUFFER_E: insufficient space in provided buffer
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetKeyBlobAsSeparateBuffers

WOLFTPM_API int wolfTPM2_GetKeyBlobAsSeparateBuffers(
    byte * pubBuffer,
    word32 * pubBufferSz,
    byte * privBuffer,
    word32 * privBufferSz,
    WOLFTPM2_KEYBLOB * key
)

Marshal data from a keyblob to a binary buffer. This can be stored to disk for loading in a separate process or after power cycling. If either buffer is NULL then the size will be returned for each part.

Parameters:

• pubBuffer pointer to buffer in which to store the public part of the marshaled keyblob
• pubBufferSz pointer to the size of the above buffer
• privBuffer pointer to buffer in which to store the private part of the marshaled keyblob
• privBufferSz pointer to the size of the above buffer
• key pointer to keyblob to marshal

See: wolfTPM2_GetKeyBlobAsSeparateBuffers

Return:

• TPM_RC_SUCCESS: successful
• BUFFER_E: insufficient space in provided buffer
• BAD_FUNC_ARG: check the provided arguments
• LENGTH_ONLY_E: Returning length only (when either of the buffers is NULL)

function wolfTPM2_SetKeyBlobFromBuffer

WOLFTPM_API int wolfTPM2_SetKeyBlobFromBuffer(
    WOLFTPM2_KEYBLOB * key,
    byte * buffer,
    word32 bufferSz
)

Unmarshal data into a WOLFTPM2_KEYBLOB struct. This can be used to load a keyblob that was previously marshaled by wolfTPM2_GetKeyBlobAsBuffer.

Parameters:

• key pointer to keyblob to load and unmarshall data into
• buffer pointer to buffer containing marshalled keyblob to load from
• bufferSz size of the above buffer

See: wolfTPM2_GetKeyBlobAsBuffer

Return:

• TPM_RC_SUCCESS: successful
• BUFFER_E: buffer is too small or there is extra data remaining and not unmarshalled
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_PolicyRestart

WOLFTPM_API int wolfTPM2_PolicyRestart(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE sessionHandle
)

Restart the policy digest for a policy session.

Parameters:

• dev pointer to a TPM2_DEV struct
• sessionHandle the handle of the current session, a session is required to use policy pcr

See:

• wolfTPM2_GetPolicyDigest
• wolfTPM2_PolicyPCR
• wolfTPM2_PolicyAuthorize

Return:

• TPM_RC_SUCCESS: successful
• INPUT_SIZE_E: policyDigestSz is too small to hold the returned digest
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_GetPolicyDigest

WOLFTPM_API int wolfTPM2_GetPolicyDigest(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE sessionHandle,
    byte * policyDigest,
    word32 * policyDigestSz
)

Get the policy digest of the session that was passed in wolfTPM2_GetPolicyDigest.

Parameters:

• dev pointer to a TPM2_DEV struct
• sessionHandle the handle of the current session, a session is required to use policy pcr
• policyDigest output digest of the policy
• policyDigestSz pointer to the size of the policyDigest

See:

• wolfTPM2_PolicyPCR
• wolfTPM2_PolicyAuthorize
• wolfTPM2_PolicyRestart

Return:

• TPM_RC_SUCCESS: successful
• INPUT_SIZE_E: policyDigestSz is too small to hold the returned digest
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_PolicyPCR

WOLFTPM_API int wolfTPM2_PolicyPCR(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE sessionHandle,
    TPM_ALG_ID pcrAlg,
    byte * pcrArray,
    word32 pcrArraySz
)

Apply the PCR's to the policy digest for the policy session.

Parameters:

• dev pointer to a TPM2_DEV struct
• sessionHandle the handle of the current policy session, a session is required to use policy PCR
• pcrAlg the hash algorithm to use with PCR policy
• pcrArray array of PCR Indexes to use when creating the policy
• pcrArraySz the number of PCR Indexes in the pcrArray

See:

• wolfTPM2_GetPolicyDigest
• wolfTPM2_PolicyPCR
• wolfTPM2_PolicyAuthorize
• wolfTPM2_PolicyRestart

Return:

• TPM_RC_SUCCESS: successful
• INPUT_SIZE_E: policyDigestSz is too small to hold the returned digest
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_PolicyAuthorize

WOLFTPM_API int wolfTPM2_PolicyAuthorize(
    WOLFTPM2_DEV * dev,
    TPM_HANDLE sessionHandle,
    const TPM2B_PUBLIC * pub,
    const TPMT_TK_VERIFIED * checkTicket,
    const byte * pcrDigest,
    word32 pcrDigestSz,
    const byte * policyRef,
    word32 policyRefSz
)

Apply the PCR's to the policy digest for the policy session.

Parameters:

• dev pointer to a TPM2_DEV struct
• sessionHandle the handle of the current policy session, a session is required to use policy PCR
• pub pointer to a populated structure of TPM2B_PUBLIC type
• checkTicket returns the validation ticket proving the signature for digest was checked
• pcrDigest digest for the PCR(s) collected with wolfTPM2_PCRGetDigest
• pcrDigestSz size of the PCR digest
• policyRef optional nonce
• policyRefSz optional nonce size

See:

• wolfTPM2_GetPolicyDigest
• wolfTPM2_PolicyPCR
• wolfTPM2_PolicyAuthorize
• wolfTPM2_PolicyRestart
• wolfTPM2_PCRGetDigest

Return:

• TPM_RC_SUCCESS: successful
• INPUT_SIZE_E: policyDigestSz is too small to hold the returned digest
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_PCRGetDigest

WOLFTPM_API int wolfTPM2_PCRGetDigest(
    WOLFTPM2_DEV * dev,
    TPM_ALG_ID pcrAlg,
    byte * pcrArray,
    word32 pcrArraySz,
    byte * pcrDigest,
    word32 * pcrDigestSz
)

Get a cumulative digest of the PCR's specified.

Parameters:

• dev pointer to a TPM2_DEV struct
• pcrAlg the hash algorithm to use with pcr policy
• pcrArray array of pcr Index to use when creating the policy
• pcrArraySz the number of Index in the pcrArray
• pcrDigest digest for the PCR(s) collected with wolfTPM2_PCRGetDigest
• pcrDigestSz size of the PCR digest

See:

• wolfTPM2_PolicyPCR
• wolfTPM2_PolicyAuthorize

Return:

• TPM_RC_SUCCESS: successful
• INPUT_SIZE_E: policyDigestSz is too small to hold the returned digest
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_PolicyRefMake

WOLFTPM_API int wolfTPM2_PolicyRefMake(
    TPM_ALG_ID pcrAlg,
    byte * digest,
    word32 * digestSz,
    const byte * policyRef,
    word32 policyRefSz
)

Utility for generating a policy ref digest. If no policy reference (nonce) used then just rehash the provided digest again (update -> final)

Parameters:

• pcrAlg the hash algorithm to use with pcr policy
• digest input/out digest
• digestSz input/out digest size
• policyRef optional nonce
• policyRefSz optional nonce size

See:

• wolfTPM2_PolicyPCRMake
• wolfTPM2_PolicyAuthorizeMake

Return:

• TPM_RC_SUCCESS: successful
• INPUT_SIZE_E: policyDigestSz is too small to hold the returned digest
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_PolicyPCRMake

WOLFTPM_API int wolfTPM2_PolicyPCRMake(
    TPM_ALG_ID pcrAlg,
    byte * pcrArray,
    word32 pcrArraySz,
    const byte * pcrDigest,
    word32 pcrDigestSz,
    byte * digest,
    word32 * digestSz
)

Utility for generating a policy PCR digest.

Parameters:

• pcrAlg the hash algorithm to use with pcr policy
• pcrArray optional array of pcrs to be used when creating the tpm object
• pcrArraySz length of the pcrArray
• pcrDigest digest for the PCR(s) collected (can get using wolfTPM2_PCRGetDigest)
• pcrDigestSz size of the PCR digest
• digest input/out digest
• digestSz input/out digest size

See:

• wolfTPM2_PolicyPCRMake
• wolfTPM2_PolicyAuthorizeMake
• wolfTPM2_PCRGetDigest

Return:

• TPM_RC_SUCCESS: successful
• INPUT_SIZE_E: policyDigestSz is too small to hold the returned digest
• BAD_FUNC_ARG: check the provided arguments

function wolfTPM2_PolicyAuthorizeMake

WOLFTPM_API int wolfTPM2_PolicyAuthorizeMake(
    TPM_ALG_ID pcrAlg,
    const TPM2B_PUBLIC * pub,
    byte * digest,
    word32 * digestSz,
    const byte * policyRef,
    word32 policyRefSz
)

Utility for generating a policy authorization digest based on a public key.

Parameters:

• pcrAlg the hash algorithm to use with pcr policy
• pub pointer to a populated structure of TPM2B_PUBLIC type
• digest input/out digest
• digestSz input/out digest size
• policyRef optional nonce
• policyRefSz optional nonce size

See:

• wolfTPM2_PolicyPCRMake
• wolfTPM2_PolicyPCRMake

Return:

• TPM_RC_SUCCESS: successful
• INPUT_SIZE_E: policyDigestSz is too small to hold the returned digest
• BAD_FUNC_ARG: check the provided arguments

---

Updated on 2024-04-26 at 01:13:04 +0000