Skip to content

wolfTPM2 Wrappers

This module describes the rich API of wolfTPM called 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
Reported the available TPM capabilities.
WOLFTPM_API int wolfTPM2_UnsetAuth(WOLFTPM2_DEV
Clears one of the TPM Authorization slots, pointed by its index number.
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_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_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_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_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: pem and tempBuf must be different buffers, of equal size.
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_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_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_VerifyHashScheme(WOLFTPM2_DEV
Advanced helper function to verify a TPM generated signature.
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_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_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_ECC(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 key usage for a WOLFTPM2_CSR structure.
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_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.
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.

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 examples/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:

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 examples/tpm_io.h)
  • userCtx pointer to a user context (can be NULL)

See:

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 examples/tpm_io.h)
  • userCtx pointer to a user context (can be NULL)

See:

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:

See:

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:

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:

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:

See:

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
)

Reported 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:

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_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:

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:

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:

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:

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,
    const 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:

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:

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
  • session pointer to an empty WOLFTPM2_SESSION struct

See:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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_ENCRYPTED_SECRET * 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 TPM2B_ENCRYPTED_SECRET type

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_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:

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: pem and tempBuf must be different buffers, of equal size.

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:

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:

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:

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:

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:

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_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:

  • verifyHash
  • signHashScheme
  • 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:

  • signHash
  • verifyHash
  • 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:

  • signHash
  • signHashScheme
  • 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:

  • signHash
  • signHashScheme
  • 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:

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:

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:

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:

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:

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:

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:

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:

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_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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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 key usage for a WOLFTPM2_CSR structure.

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 values: any, serverAuth, clientAuth, codeSigning, emailProtection, timeStamping and OCSPSigning Default: "serverAuth,clientAuth,codeSigning"

See:

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:

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 WOLFSSL_FILETYPE_ASN1 or WOLFSSL_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:

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 WOLFSSL_FILETYPE_ASN1 or WOLFSSL_FILETYPE_PEM
  • out destination buffer for CSR as ASN.1/DER or PEM
  • outSz destination buffer maximum size

See:

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 WOLFSSL_FILETYPE_ASN1 or WOLFSSL_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:

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 WOLFSSL_FILETYPE_ASN1 or WOLFSSL_FILETYPE_PEM
  • out destination buffer for CSR as ASN.1/DER or PEM
  • outSz destination buffer maximum size

See:

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:

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:

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:

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:

function wolfTPM2_FreeKeyBlob

WOLFTPM_API int wolfTPM2_FreeKeyBlob(
    WOLFTPM2_KEYBLOB * blob
)

Free a WOLFTPM2_KEYBLOB that was allocated with wolfTPM2_NewKeyBlob.

Parameters:

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:

function wolfTPM2_FreeSession

WOLFTPM_API int wolfTPM2_FreeSession(
    WOLFTPM2_SESSION * session
)

Free a WOLFTPM2_SESSION that was allocated with wolfTPM2_NewSession.

Parameters:

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:

  • blob 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:

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:

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:

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:

  • dev pointer to a TPM2_DEV 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.

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_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

Updated on 2022-08-16 at 08:33:19 +0000