Skip to content

TPM2 Proprietary

This module describes TPM2 commands specific only to wolfTPM. More...

Functions

Name
WOLFTPM_API TPM_RC TPM2_Init([TPM2_CTX](#typedef_TPM_RC](tpm2_8h.md#typedef_tpm_rc)
WOLFTPM_API TPM_RC TPM2_Init_ex([TPM2_CTX](#typedef_TPM_RC](tpm2_8h.md#typedef_tpm_rc)
WOLFTPM_API TPM_RC TPM2_Init_minimal([TPM2_CTX](#typedef_TPM_RC](tpm2_8h.md#typedef_tpm_rc)
WOLFTPM_API TPM_RC TPM2_Cleanup([TPM2_CTX](#typedef_TPM_RC](tpm2_8h.md#typedef_tpm_rc)
WOLFTPM_API TPM_RC TPM2_ChipStartup([TPM2_CTX](#typedef_TPM_RC](tpm2_8h.md#typedef_tpm_rc)
WOLFTPM_API TPM_RC TPM2_SetHalIoCb([TPM2_CTX](#typedef_TPM_RC](tpm2_8h.md#typedef_tpm_rc)
WOLFTPM_API TPM_RC TPM2_SetSessionAuth([TPM2_AUTH_SESSION](#typedef_TPM_RC](tpm2_8h.md#typedef_tpm_rc)
WOLFTPM_API int TPM2_GetSessionAuthCount(TPM2_CTX
Determine the number of currently set TPM Authorizations.
WOLFTPM_API void TPM2_SetActiveCtx(TPM2_CTX
Sets a new TPM2 context for use.
WOLFTPM_API TPM2_CTX * TPM2_GetActiveCtx(void )
Provides a pointer to the TPM2 context in use.
WOLFTPM_API int TPM2_GetHashDigestSize(TPMI_ALG_HASH hashAlg)
Determine the size in bytes of a TPM 2.0 hash digest.
WOLFTPM_API int TPM2_GetHashType(TPMI_ALG_HASH hashAlg)
Translate a TPM2 hash type to its corresponding wolfcrypt hash type.
WOLFTPM_API int TPM2_GetNonce(byte * nonceBuf, int nonceSz)
Generate a fresh nonce of random numbers.
WOLFTPM_API void TPM2_SetupPCRSel(TPML_PCR_SELECTION
Helper function to prepare a correct PCR selection For example, when preparing to create a TPM2_Quote.
const WOLFTPM_API char * TPM2_GetRCString(int rc)
Get a human readable string for any TPM 2.0 return code.
const WOLFTPM_API char * TPM2_GetAlgName(TPM_ALG_ID alg)
Get a human readable string for any TPM 2.0 algorithm.
WOLFTPM_API int TPM2_GetCurveSize(TPM_ECC_CURVE curveID)
Determine the size in bytes of any TPM ECC Curve.
WOLFTPM_API int TPM2_GetTpmCurve(int curveID)
Translate a wolfcrypt curve type to its corresponding TPM curve type.
WOLFTPM_API int TPM2_GetWolfCurve(int curve_id)
Translate a TPM curve type to its corresponding wolfcrypt curve type.
WOLFTPM_API int TPM2_ParseAttest(const TPM2B_ATTEST
Parses TPM2B_ATTEST and populates the data in TPMS_ATTEST structure.
WOLFTPM_API int TPM2_HashNvPublic(TPMS_NV_PUBLIC
Computes fresh NV Index name based on a nvPublic structure.
WOLFTPM_API int TPM2_AppendPublic(byte * buf, word32 size, int * sizeUsed, TPM2B_PUBLIC
Populates TPM2B_PUBLIC structure based on a user provided buffer.
WOLFTPM_API int TPM2_ParsePublic(TPM2B_PUBLIC
Parses TPM2B_PUBLIC structure and stores in a user provided buffer.
WOLFTPM_LOCAL int TPM2_GetName(TPM2_CTX
Provides the Name of a TPM object.
WOLFTPM_API UINT16 TPM2_GetVendorID(void )
Provides the vendorID of the active TPM2 context.
WOLFTPM_API void TPM2_PrintBin(const byte * buffer, word32 length)
Helper function to print a binary buffer in a formatted way.
WOLFTPM_API void TPM2_PrintAuth(const TPMS_AUTH_COMMAND
Helper function to print a structure of TPMS_AUTH_COMMAND type in a human readable way.
WOLFTPM_API void TPM2_PrintPublicArea(const TPM2B_PUBLIC
Helper function to print a structure of TPM2B_PUBLIC type in a human readable way.

Detailed Description

This module describes TPM2 commands specific only to wolfTPM.

Typically, these commands include helpers for handling TPM 2.0 data structures.

There are also functions to help debugging and testing during development.

Functions Documentation

function TPM2_Init

WOLFTPM_API TPM_RC TPM2_Init(
    TPM2_CTX * ctx,
    TPM2HalIoCb ioCb,
    void * userCtx
)

Initializes a TPM with HAL IO callback and user supplied context. When using wolfTPM with –enable-devtpm or –enable-swtpm configuration, the ioCb and userCtx are not used.

Parameters:

  • ctx pointer to a TPM2_CTX struct
  • ioCb pointer to TPM2HalIoCb (HAL IO) callback function
  • userCtx pointer to the user's context that will be stored as a member of the ctx struct

See:

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: general error (possibly IO)
  • BAD_FUNC_ARG check arguments provided

Note: TPM2_Init_minimal() calls TPM2_Init_ex() with both ioCb and userCtx set to NULL. In other modes, the ioCb shall be set in order to use TIS. Example ioCB for baremetal and RTOS applications are provided in examples/tpm_io.c

Example

int rc;
TPM2_CTX tpm2Ctx;

rc = TPM2_Init(&tpm2Ctx, TPM2_IoCb, userCtx);
if (rc != TPM_RC_SUCCESS) {
    // TPM2_Init failed
}

function TPM2_Init_ex

WOLFTPM_API TPM_RC TPM2_Init_ex(
    TPM2_CTX * ctx,
    TPM2HalIoCb ioCb,
    void * userCtx,
    int timeoutTries
)

Initializes a TPM with timeoutTries, HAL IO callback and user supplied context.

Parameters:

  • ctx pointer to a TPM2_CTX struct
  • ioCb pointer to TPM2HalIoCb (HAL IO) callback function
  • userCtx pointer to the user's context that will be stored as a member of the ctx struct
  • timeoutTries specifies the number of attempts to confirm that TPM2 startup has completed

See:

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: general error (possibly IO)
  • BAD_FUNC_ARG check arguments provided

Note: It is recommended to use TPM2_Init instead of using TPM2_Init_ex directly.

function TPM2_Init_minimal

WOLFTPM_API TPM_RC TPM2_Init_minimal(
    TPM2_CTX * ctx
)

Initializes a TPM and sets the wolfTPM2 context that will be used. This function is typically used for rich operating systems, like Windows.

Parameters:

See:

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: general error (possibly IO)
  • BAD_FUNC_ARG check arguments provided

Note: It is recommended to use TPM2_Init instead of using TPM2_Init_minimal directly.

function TPM2_Cleanup

WOLFTPM_API TPM_RC TPM2_Cleanup(
    TPM2_CTX * ctx
)

Deinitializes a TPM and wolfcrypt (if it was initialized)

Parameters:

See:

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: could not acquire the lock on the wolfTPM2 context
  • BAD_FUNC_ARG: the TPM2 device structure is a NULL pointer

Example

int rc;
TPM2_CTX tpm2Ctx;

rc = TPM2_Cleanup(&tpm2Ctx->dev);
if (rc != TPM_RC_SUCCESS) {
    // TPM2_Cleanup failed
}

function TPM2_ChipStartup

WOLFTPM_API TPM_RC TPM2_ChipStartup(
    TPM2_CTX * ctx,
    int timeoutTries
)

Makes sure the TPM2 startup has completed and extracts the TPM device information.

Parameters:

  • ctx pointer to a TPM2_CTX struct
  • timeoutTries specifies the number of attempts to check if TPM2 startup has completed

See:

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: general error (possibly IO)
  • BAD_FUNC_ARG: check the provided arguments
  • TPM_RC_TIMEOUT: timeout occurred

Note: This function is used in TPM2_Init_ex

function TPM2_SetHalIoCb

WOLFTPM_API TPM_RC TPM2_SetHalIoCb(
    TPM2_CTX * ctx,
    TPM2HalIoCb ioCb,
    void * userCtx
)

Sets the user's context and IO callbacks needed for TPM communication.

Parameters:

  • ctx pointer to a TPM2_CTX struct
  • ioCb pointer to TPM2HalIoCb (HAL IO) callback function
  • userCtx pointer to the user's context that will be stored as a member of the ctx struct

See:

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: could not acquire the lock on the wolfTPM2 context
  • BAD_FUNC_ARG: the TPM2 device structure is a NULL pointer

Note: SetHalIoCb will fail if built with devtpm or swtpm as the callback is not used for TPM. For other configuration builds, ioCb must be set to a non-NULL function pointer and userCtx is optional.

Typically, TPM2_Init or wolfTPM2_Init are used to set the HAL IO.

function TPM2_SetSessionAuth

WOLFTPM_API TPM_RC TPM2_SetSessionAuth(
    TPM2_AUTH_SESSION * session
)

Sets the structure holding the TPM Authorizations.

Parameters:

See:

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: could not acquire the lock on the wolfTPM2 context
  • BAD_FUNC_ARG: the TPM2 context structure is a NULL pointer

Rarely used, because TPM2_Init functions and wolfTPM2_Init perform this initialization as well TPM 2.0 Commands can have up to three authorization slots, therefore it is recommended to supply an array of size MAX_SESSION_NUM to TPM2_SetSessionAuth(see example below).

Example

int rc;
TPM2_AUTH_SESSION session[MAX_SESSION_NUM];

XMEMSET(session, 0, sizeof(session));
session[0].sessionHandle = TPM_RS_PW;

rc = TPM2_SetSessionAuth(session);
if (rc != TPM_RC_SUCCESS) {
    // TPM2_SetSessionAuth failed
}

function TPM2_GetSessionAuthCount

WOLFTPM_API int TPM2_GetSessionAuthCount(
    TPM2_CTX * ctx
)

Determine the number of currently set TPM Authorizations.

Parameters:

See:

Return:

  • the number of active TPM Authorizations (between one and three)
  • BAD_FUNC_ARG: check the arguments provided for a NULL pointer

Example

int authCount;
TPM2_CTX tpm2Ctx;

authCount = TPM2_GetSessionAuthCount(tpm2ctx);
if (authCount == BAD_FUNC_ARG) {
    // TPM2_GetSessionAuthCount failed
}

function TPM2_SetActiveCtx

WOLFTPM_API void TPM2_SetActiveCtx(
    TPM2_CTX * ctx
)

Sets a new TPM2 context for use.

Parameters:

See:

Example

TPM2_CTX tpm2Ctx;

TPM2_SetActiveCtx(tpm2ctx);

function TPM2_GetActiveCtx

WOLFTPM_API TPM2_CTX * TPM2_GetActiveCtx(
    void 
)

Provides a pointer to the TPM2 context in use.

See:

Return: ctx pointer to a TPM2_CTX struct

Example

TPM2_CTX *tpm2Ctx;

tpm2Ctx = TPM2_GetActiveCtx();

function TPM2_GetHashDigestSize

WOLFTPM_API int TPM2_GetHashDigestSize(
    TPMI_ALG_HASH hashAlg
)

Determine the size in bytes of a TPM 2.0 hash digest.

Parameters:

  • hashAlg a valid TPM 2.0 hash type

Return:

  • the size of a TPM 2.0 hash digest as number of bytes
  • 0 if hash type is invalid

Example

int digestSize = 0;
TPMI_ALG_HASH hashAlg = TPM_ALG_SHA256;

digestSize = TPM2_GetHashDigestSize(hashAlg);
if (digestSize > 0) {
    //digestSize contains a valid value
}

function TPM2_GetHashType

WOLFTPM_API int TPM2_GetHashType(
    TPMI_ALG_HASH hashAlg
)

Translate a TPM2 hash type to its corresponding wolfcrypt hash type.

Parameters:

  • hashAlg a valid TPM 2.0 hash type

Return:

  • a value specifying a hash type to use with wolfcrypt
  • 0 if hash type is invalid

Example

int wc_hashType;
TPMI_ALG_HASH hashAlg = TPM_ALG_SHA256;

wc_hashType = TPM2_GetHashDigestSize(hashAlg);
if (wc_hashType > 0) {
    //wc_hashType contains a valid wolfcrypt hash type
}

function TPM2_GetNonce

WOLFTPM_API int TPM2_GetNonce(
    byte * nonceBuf,
    int nonceSz
)

Generate a fresh nonce of random numbers.

Parameters:

  • nonceBuf pointer to a BYTE buffer
  • nonceSz size of the nonce in bytes

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: generic failure (TPM IO issue or wolfcrypt configuration)
  • BAD_FUNC_ARG: check the provided arguments

Note: Can use the TPM random number generator if WOLFTPM2_USE_HW_RNG is defined

Example

int rc, nonceSize = 32;
BYTE freshNonce[32];

rc = TPM2_GetNonce(&freshNonce, nonceSize);
if (rc != TPM_RC_SUCCESS) {
    //TPM2_GetNonce failed
}

function TPM2_SetupPCRSel

WOLFTPM_API void TPM2_SetupPCRSel(
    TPML_PCR_SELECTION * pcr,
    TPM_ALG_ID alg,
    int pcrIndex
)

Helper function to prepare a correct PCR selection For example, when preparing to create a TPM2_Quote.

Parameters:

  • pcr pointer to a structure of type TPML_PCR_SELECTION
  • alg value of type TPM_ALG_ID specifying the type of hash algorithm used
  • pcrIndex value between 0 and 23 specifying the PCR register for use

See:

Example

int pcrIndex = 16; // This is a PCR register for DEBUG & testing purposes
PCR_Read_In pcrRead;

TPM2_SetupPCRSel(&pcrRead.pcrSelectionIn, TPM_ALG_SHA256, pcrIndex);

function TPM2_GetRCString

const WOLFTPM_API char * TPM2_GetRCString(
    int rc
)

Get a human readable string for any TPM 2.0 return code.

Parameters:

  • rc integer value representing a TPM return code

Return: pointer to a string constant

Example

int rc;

rc = wolfTPM2_Init(&dev, TPM2_IoCb, userCtx);
if (rc != TPM_RC_SUCCESS) {
    printf("wolfTPM2_Init failed 0x%x: %s\n", rc, TPM2_GetRCString(rc));
    return rc;
}

function TPM2_GetAlgName

const WOLFTPM_API char * TPM2_GetAlgName(
    TPM_ALG_ID alg
)

Get a human readable string for any TPM 2.0 algorithm.

Parameters:

  • alg value of type TPM_ALG_ID specifying a valid TPM 2.0 algorithm

Return: pointer to a string constant

Example

int paramEncAlg = TPM_ALG_CFB;

printf("\tUse Parameter Encryption: %s\n", TPM2_GetAlgName(paramEncAlg));

function TPM2_GetCurveSize

WOLFTPM_API int TPM2_GetCurveSize(
    TPM_ECC_CURVE curveID
)

Determine the size in bytes of any TPM ECC Curve.

Parameters:

  • curveID value of type TPM_ECC_CURVE

Return:

  • 0 in case of invalid curve type
  • integer value representing the number of bytes

Example

int bytes;
TPM_ECC_CURVE curve = TPM_ECC_NIST_P256;

bytes = TPM2_GetCurveSize(curve);
if (bytes == 0) {
    //TPM2_GetCurveSize failed
}

function TPM2_GetTpmCurve

WOLFTPM_API int TPM2_GetTpmCurve(
    int curveID
)

Translate a wolfcrypt curve type to its corresponding TPM curve type.

Parameters:

  • curveID pointer to a BYTE buffer

See: TPM2_GetWolfCurve

Return:

  • integer value representing a wolfcrypt curve type
  • ECC_CURVE_OID_E in case of invalid curve type

Example

int tpmCurve;
int wc_curve = ECC_SECP256R1;

tpmCurve = TPM2_GetTpmCurve(curve);
\\in this case tpmCurve will be TPM_ECC_NIST_P256
if (tpmCurve = ECC_CURVE_OID_E) {
    //TPM2_GetTpmCurve failed
}

function TPM2_GetWolfCurve

WOLFTPM_API int TPM2_GetWolfCurve(
    int curve_id
)

Translate a TPM curve type to its corresponding wolfcrypt curve type.

Parameters:

  • curve_id pointer to a BYTE buffer

See: TPM2_GetTpmCurve

Return:

  • integer value representing a TPM curve type
  • -1 or ECC_CURVE_OID_E in case of invalid curve type

Example

int tpmCurve = TPM_ECC_NIST_P256;
int wc_curve;

wc_curve = TPM2_GetWolfCurve(tpmCurve);
\\in this case tpmCurve will be ECC_SECP256R1
if (wc_curve = ECC_CURVE_OID_E || wc_curve == -1) {
    //TPM2_GetWolfCurve failed
}

function TPM2_ParseAttest

WOLFTPM_API int TPM2_ParseAttest(
    const TPM2B_ATTEST * in,
    TPMS_ATTEST * out
)

Parses TPM2B_ATTEST and populates the data in TPMS_ATTEST structure.

Parameters:

Return:

  • TPM_RC_SUCCESS: successful
  • BAD_FUNC_ARG: check the provided arguments

Note: This is public API of the helper function TPM2_Packet_ParseAttest

Example

TPM2B_ATTEST in; //for example, as part of a TPM2_Quote
TPMS_ATTEST out

rc = TPM2_GetNonce(&in, &out);
if (rc != TPM_RC_SUCCESS) {
    //TPM2_ParseAttest failed
}

function TPM2_HashNvPublic

WOLFTPM_API int TPM2_HashNvPublic(
    TPMS_NV_PUBLIC * nvPublic,
    byte * buffer,
    UINT16 * size
)

Computes fresh NV Index name based on a nvPublic structure.

Parameters:

  • nvPublic
  • buffer pointer to a structure of a TPMS_ATTEST type
  • size pointer to a variable of UINT16 type to store the size of the nvIndex

Return:

  • TPM_RC_SUCCESS: successful
  • negative integer value in case of an error
  • BAD_FUNC_ARG: check the provided arguments
  • NOT_COMPILED_IN: check if wolfcrypt is enabled

Example

TPMS_NV_PUBLIC nvPublic;
BYTE buffer[TPM_MAX_DIGEST_SIZE];
UINT16 size;

rc = TPM2_HashNvPublic(&nvPublic, &buffer, &size);
if (rc != TPM_RC_SUCCESS) {
    //TPM2_HashNvPublic failed
}

function TPM2_AppendPublic

WOLFTPM_API int TPM2_AppendPublic(
    byte * buf,
    word32 size,
    int * sizeUsed,
    TPM2B_PUBLIC * pub
)

Populates TPM2B_PUBLIC structure based on a user provided buffer.

Parameters:

  • buf pointer to a user buffer
  • size integer value of word32 type, specifying the size of the user buffer
  • sizeUsed pointer to an integer variable, stores the used size of pub->buffer
  • pub pointer to an empty structure of TPM2B_PUBLIC type

See: TPM2_ParsePublic

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: insufficient buffer size
  • BAD_FUNC_ARG: check the provided arguments

Note: Public API of the helper function TPM2_Packet_AppendPublic

Example

TPM2B_PUBLIC pub; //empty
int sizeUsed, rc;
BYTE buffer[sizeof(TPM2B_PUBLIC)];
word32 size = sizeof(buffer);

rc = TPM2_AppendPublic(&buffer, size, &sizeUsed, &pub);
if (rc != TPM_RC_SUCCESS) {
    //TPM2_AppendPublic failed
}

function TPM2_ParsePublic

WOLFTPM_API int TPM2_ParsePublic(
    TPM2B_PUBLIC * pub,
    byte * buf,
    word32 size,
    int * sizeUsed
)

Parses TPM2B_PUBLIC structure and stores in a user provided buffer.

Parameters:

  • pub pointer to a populated structure of TPM2B_PUBLIC type
  • buf pointer to an empty user buffer
  • size integer value of word32 type, specifying the available size of the user buffer
  • sizeUsed pointer to an integer variable, stores the used size of the user buffer

See: TPM2_AppendPublic

Return:

  • TPM_RC_SUCCESS: successful
  • TPM_RC_FAILURE: insufficient buffer size
  • BAD_FUNC_ARG: check the provided arguments

Note: Public API of the helper function TPM2_Packet_ParsePublic

Example

TPM2B_PUBLIC pub; //populated
int sizeUsed, rc;
BYTE buffer[sizeof(TPM2B_PUBLIC)];
word32 size = sizeof(buffer);

rc = TPM2_ParsePublic(&pub, buffer, size, &sizeUsed);
if (rc != TPM_RC_SUCCESS) {
    //TPM2_ParsePublic failed
}

function TPM2_GetName

WOLFTPM_LOCAL int TPM2_GetName(
    TPM2_CTX * ctx,
    UINT32 handleValue,
    int handleCnt,
    int idx,
    TPM2B_NAME * name
)

Provides the Name of a TPM object.

Parameters:

  • ctx pointer to a TPM2 context
  • handleValue value of UINT32 type, specifying a valid TPM handle
  • handleCnt total number of handles used in the current TPM command/session
  • idx index value, between one and three, specifying a valid TPM Authorization session
  • name pointer to an empty structure of TPM2B_NAME type

Return:

  • TPM_RC_SUCCESS: successful
  • BAD_FUNC_ARG: check the provided arguments

Note: The object is reference by its TPM handle and session index

Example

int rc;
UINT32 handleValue = TRANSIENT_FIRST;
handleCount = 1;
sessionIdx = 0;
TPM2B_NAME name;

rc = TPM2_GetName(ctx, handleValue, handleCount, sessionIdx, &name);
if (rc != TPM_RC_SUCCESS) {
    //TPM2_GetName failed
}

function TPM2_GetVendorID

WOLFTPM_API UINT16 TPM2_GetVendorID(
    void 
)

Provides the vendorID of the active TPM2 context.

See:

  • TPM2_GetCapabilities
  • TPM2_GetTpmDevId
  • TPM2_Init

Return:

  • integer value of UINT16 type, specifying the vendor ID
  • 0 if TPM2 context is invalid or NULL

Note: Depends on correctly read TPM device info during TPM Init

Example

TPM2_CTX *tpm2Ctx;

tpm2Ctx = TPM2_GetActiveCtx();

function TPM2_PrintBin

WOLFTPM_API void TPM2_PrintBin(
    const byte * buffer,
    word32 length
)

Helper function to print a binary buffer in a formatted way.

Parameters:

  • buffer pointer to a buffer of BYTE type
  • length integer value of word32 type, containing the size of the buffer

See:

Note: Requires DEBUG_WOLFTPM to be defined

Example

BYTE buffer[] = {0x01,0x02,0x03,0x04};
length = sizeof(buffer);

TPM2_PrintBin(&buffer, length);

function TPM2_PrintAuth

WOLFTPM_API void TPM2_PrintAuth(
    const TPMS_AUTH_COMMAND * authCmd
)

Helper function to print a structure of TPMS_AUTH_COMMAND type in a human readable way.

Parameters:

See:

Note: Requires DEBUG_WOLFTPM to be defined

Example

TPMS_AUTH_COMMAND authCmd; //for example, part of a TPM Authorization session

TPM2_PrintAuthCmd(&authCmd);

function TPM2_PrintPublicArea

WOLFTPM_API void TPM2_PrintPublicArea(
    const TPM2B_PUBLIC * pub
)

Helper function to print a structure of TPM2B_PUBLIC type in a human readable way.

Parameters:

See:

Note: Requires DEBUG_WOLFTPM to be defined

Example

TPM2B_PUBLIC pub; //for example, part of the output of a successful TPM2_Create

TPM2_PrintPublicArea(&pub);

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