File syn_tpm2.h

FileList > crypto > syn_tpm2.h

Go to the source code of this file

TCG TPM 2.0 Command Marshaller, Measured Boot, & Hardware Root-of-Trust Engine. More...

• #include "../common/syn_defs.h"
• #include "../net/syn_transport.h"
• #include <stdbool.h>
• #include <stddef.h>
• #include <stdint.h>

Classes

Type	Name
struct	SYN_TPM2_Config TPM 2.0 Context Configuration Descriptor.
struct	SYN_TPM2_Context TPM 2.0 Client Instance Context.
struct	SYN_TPM2_QuoteResult TPM 2.0 Attestation Quote Output Structure.

Public Functions

Type	Name
uint32_t	syn_tpm2_get_last_rc (const SYN_TPM2_Context * ctx) Get last TPM 2.0 response code returned by TPM hardware.
SYN_Status	syn_tpm2_get_random (SYN_TPM2_Context * ctx, uint16_t num_bytes, uint8_t * out_random, uint16_t * out_len) Generate cryptographic true random bytes from TPM TRNG (TPM2_GetRandom).
SYN_Status	syn_tpm2_init (SYN_TPM2_Context * ctx, const SYN_TPM2_Config * cfg) Initialize TPM 2.0 Context.
SYN_Status	syn_tpm2_nv_read (SYN_TPM2_Context * ctx, uint32_t auth_handle, uint32_t nv_index, uint16_t offset, uint16_t size, uint8_t * out_data, uint16_t * out_len) Read data from secure Non-Volatile storage index (TPM2_NV_Read).
SYN_Status	syn_tpm2_nv_write (SYN_TPM2_Context * ctx, uint32_t auth_handle, uint32_t nv_index, uint16_t offset, const uint8_t * in_data, uint16_t size) Write data to secure Non-Volatile storage index (TPM2_NV_Write).
SYN_Status	syn_tpm2_pcr_extend (SYN_TPM2_Context * ctx, uint32_t pcr_index, uint16_t hash_alg, const uint8_t * in_digest, size_t digest_len) Extend Platform Configuration Register with measurement digest (TPM2_PCR_Extend).
SYN_Status	syn_tpm2_pcr_read (SYN_TPM2_Context * ctx, uint32_t pcr_index, uint16_t hash_alg, uint8_t * out_digest, size_t * out_digest_len) Read single Platform Configuration Register (TPM2_PCR_Read).
SYN_Status	syn_tpm2_quote (SYN_TPM2_Context * ctx, uint32_t key_handle, const uint8_t * qualifying_data, size_t qual_len, uint32_t pcr_mask, SYN_TPM2_QuoteResult * out_quote) Generate Remote Attestation Quote over PCR values (TPM2_Quote).
SYN_Status	syn_tpm2_self_test (SYN_TPM2_Context * ctx, bool full_test) Execute TPM2_SelfTest command.
SYN_Status	syn_tpm2_startup (SYN_TPM2_Context * ctx, uint16_t startup_type) Execute TPM2_Startup command.

Macros

Type	Name
define	SYN_TPM2_ALG_NULL 0x0010U
define	SYN_TPM2_ALG_SHA256 0x000BU
define	SYN_TPM2_ALG_SHA384 0x000CU
define	SYN_TPM2_CC_GETRANDOM 0x0000017BU
define	SYN_TPM2_CC_NV_READ 0x0000014EU
define	SYN_TPM2_CC_NV_WRITE 0x00000137U
define	SYN_TPM2_CC_PCR_EXTEND 0x00000182U
define	SYN_TPM2_CC_PCR_READ 0x0000017EU
define	SYN_TPM2_CC_QUOTE 0x00000158U
define	SYN_TPM2_CC_SELFTEST 0x00000143U
define	SYN_TPM2_CC_STARTUP 0x00000144U
define	SYN_TPM2_MAX_DIGEST_LEN 48U
define	SYN_TPM2_MAX_QUOTE_LEN 256U
define	SYN_TPM2_RC_SUCCESS 0x00000000U
define	SYN_TPM2_RH_OWNER 0x40000001U
define	SYN_TPM2_RH_PLATFORM 0x4000000CU
define	SYN_TPM2_RS_PW 0x40000009U
define	SYN_TPM2_ST_NO_SESSIONS 0x8001U
define	SYN_TPM2_ST_SESSIONS 0x8002U
define	SYN_TPM2_SU_CLEAR 0x0000U
define	SYN_TPM2_SU_STATE 0x0001U

Detailed Description

Implements a zero-heap, deterministic TCG TPM 2.0 command serializer and response parser: * Direct interface over SPI / I2C / LPC TCG FIFO hardware interface (SYN_Transport). * Measured Boot PCR Operations (TPM2_PCR_Read, TPM2_PCR_Extend for SHA-256 / SHA-384). * Hardware Cryptographic Entropy (TPM2_GetRandom). * Hardware Identity & Remote Attestation Quotes (TPM2_Quote). * Tamper-Proof Non-Volatile Storage (TPM2_NV_Read, TPM2_NV_Write). * Power & Self-Test Lifecycle (TPM2_Startup, TPM2_SelfTest).

Public Functions Documentation

function syn_tpm2_get_last_rc

Get last TPM 2.0 response code returned by TPM hardware.

uint32_t syn_tpm2_get_last_rc (
    const SYN_TPM2_Context * ctx
) 

Parameters:

• ctx Context instance.

Returns:

32-bit TPM response code (e.g. TPM_RC_SUCCESS = 0).

---

function syn_tpm2_get_random

Generate cryptographic true random bytes from TPM TRNG (TPM2_GetRandom).

SYN_Status syn_tpm2_get_random (
    SYN_TPM2_Context * ctx,
    uint16_t num_bytes,
    uint8_t * out_random,
    uint16_t * out_len
) 

Parameters:

• ctx Context instance.
• num_bytes Number of random bytes requested.
• out_random Buffer to receive random bytes.
• out_len Pointer to receive actual number of bytes returned.

Returns:

SYN_OK on success.

---

function syn_tpm2_init

Initialize TPM 2.0 Context.

SYN_Status syn_tpm2_init (
    SYN_TPM2_Context * ctx,
    const SYN_TPM2_Config * cfg
) 

Parameters:

• ctx Context instance.
• cfg Configuration descriptor.

Returns:

SYN_OK on success, SYN_INVALID_PARAM on invalid parameter.

---

function syn_tpm2_nv_read

Read data from secure Non-Volatile storage index (TPM2_NV_Read).

SYN_Status syn_tpm2_nv_read (
    SYN_TPM2_Context * ctx,
    uint32_t auth_handle,
    uint32_t nv_index,
    uint16_t offset,
    uint16_t size,
    uint8_t * out_data,
    uint16_t * out_len
) 

Parameters:

• ctx Context instance.
• auth_handle Authorization handle (e.g. SYN_TPM2_RH_OWNER).
• nv_index NVRAM index (e.g. 0x01500000).
• offset Byte offset within NV area.
• size Number of bytes to read.
• out_data Output buffer.
• out_len Pointer to receive bytes read.

Returns:

SYN_OK on success.

---

function syn_tpm2_nv_write

Write data to secure Non-Volatile storage index (TPM2_NV_Write).

SYN_Status syn_tpm2_nv_write (
    SYN_TPM2_Context * ctx,
    uint32_t auth_handle,
    uint32_t nv_index,
    uint16_t offset,
    const uint8_t * in_data,
    uint16_t size
) 

Parameters:

• ctx Context instance.
• auth_handle Authorization handle (e.g. SYN_TPM2_RH_OWNER).
• nv_index NVRAM index.
• offset Byte offset within NV area.
• in_data Data buffer to write.
• size Number of bytes to write.

Returns:

SYN_OK on success.

---

function syn_tpm2_pcr_extend

Extend Platform Configuration Register with measurement digest (TPM2_PCR_Extend).

SYN_Status syn_tpm2_pcr_extend (
    SYN_TPM2_Context * ctx,
    uint32_t pcr_index,
    uint16_t hash_alg,
    const uint8_t * in_digest,
    size_t digest_len
) 

Parameters:

• ctx Context instance.
• pcr_index PCR register index (0..23).
• hash_alg Hash algorithm (SYN_TPM2_ALG_SHA256 or SYN_TPM2_ALG_SHA384).
• in_digest Digest bytes to extend PCR with.
• digest_len Length of in_digest (must match hash algorithm).

Returns:

SYN_OK on success.

---

function syn_tpm2_pcr_read

Read single Platform Configuration Register (TPM2_PCR_Read).

SYN_Status syn_tpm2_pcr_read (
    SYN_TPM2_Context * ctx,
    uint32_t pcr_index,
    uint16_t hash_alg,
    uint8_t * out_digest,
    size_t * out_digest_len
) 

Parameters:

• ctx Context instance.
• pcr_index PCR register index (0..23).
• hash_alg Hash algorithm bank (SYN_TPM2_ALG_SHA256 or SYN_TPM2_ALG_SHA384).
• out_digest Output buffer to receive digest.
• out_digest_len Pointer to receive digest length (32 for SHA-256, 48 for SHA-384).

Returns:

SYN_OK on success.

---

function syn_tpm2_quote

Generate Remote Attestation Quote over PCR values (TPM2_Quote).

SYN_Status syn_tpm2_quote (
    SYN_TPM2_Context * ctx,
    uint32_t key_handle,
    const uint8_t * qualifying_data,
    size_t qual_len,
    uint32_t pcr_mask,
    SYN_TPM2_QuoteResult * out_quote
) 

Parameters:

• ctx Context instance.
• key_handle Attestation signing key handle (e.g. AK / EK).
• qualifying_data Nonce / qualifying data to prevent replay.
• qual_len Length of qualifying data.
• pcr_mask 24-bit bitmask of PCRs to include in quote.
• out_quote Pointer to receive quote structure.

Returns:

SYN_OK on success.

---

function syn_tpm2_self_test

Execute TPM2_SelfTest command.

SYN_Status syn_tpm2_self_test (
    SYN_TPM2_Context * ctx,
    bool full_test
) 

Parameters:

• ctx Context instance.
• full_test If true, tests all algorithms; if false, tests incrementally.

Returns:

SYN_OK on success.

---

function syn_tpm2_startup

Execute TPM2_Startup command.

SYN_Status syn_tpm2_startup (
    SYN_TPM2_Context * ctx,
    uint16_t startup_type
) 

Parameters:

• ctx Context instance.
• startup_type Startup mode (SYN_TPM2_SU_CLEAR or SYN_TPM2_SU_STATE).

Returns:

SYN_OK on success, SYN_ERROR on TPM failure.

---

Macro Definition Documentation

define SYN_TPM2_ALG_NULL

#define SYN_TPM2_ALG_NULL `0x0010U`

Null algorithm

---

define SYN_TPM2_ALG_SHA256

#define SYN_TPM2_ALG_SHA256 `0x000BU`

SHA-256 (32 bytes)

---

define SYN_TPM2_ALG_SHA384

#define SYN_TPM2_ALG_SHA384 `0x000CU`

SHA-384 (48 bytes)

---

define SYN_TPM2_CC_GETRANDOM

#define SYN_TPM2_CC_GETRANDOM `0x0000017BU`

TPM2_GetRandom

---

define SYN_TPM2_CC_NV_READ

#define SYN_TPM2_CC_NV_READ `0x0000014EU`

TPM2_NV_Read

---

define SYN_TPM2_CC_NV_WRITE

#define SYN_TPM2_CC_NV_WRITE `0x00000137U`

TPM2_NV_Write

---

define SYN_TPM2_CC_PCR_EXTEND

#define SYN_TPM2_CC_PCR_EXTEND `0x00000182U`

TPM2_PCR_Extend

---

define SYN_TPM2_CC_PCR_READ

#define SYN_TPM2_CC_PCR_READ `0x0000017EU`

TPM2_PCR_Read

---

define SYN_TPM2_CC_QUOTE

#define SYN_TPM2_CC_QUOTE `0x00000158U`

TPM2_Quote

---

define SYN_TPM2_CC_SELFTEST

#define SYN_TPM2_CC_SELFTEST `0x00000143U`

TPM2_SelfTest

---

define SYN_TPM2_CC_STARTUP

#define SYN_TPM2_CC_STARTUP `0x00000144U`

TPM2_Startup

---

define SYN_TPM2_MAX_DIGEST_LEN

#define SYN_TPM2_MAX_DIGEST_LEN `48U`

Max hash digest length (SHA-384)

---

define SYN_TPM2_MAX_QUOTE_LEN

#define SYN_TPM2_MAX_QUOTE_LEN `256U`

Max attest quote signature length

---

define SYN_TPM2_RC_SUCCESS

#define SYN_TPM2_RC_SUCCESS `0x00000000U`

TPM 2.0 Success Return Code

---

define SYN_TPM2_RH_OWNER

#define SYN_TPM2_RH_OWNER `0x40000001U`

Owner hierarchy

---

define SYN_TPM2_RH_PLATFORM

#define SYN_TPM2_RH_PLATFORM `0x4000000CU`

Platform hierarchy

---

define SYN_TPM2_RS_PW

#define SYN_TPM2_RS_PW `0x40000009U`

Empty password authorization session

---

define SYN_TPM2_ST_NO_SESSIONS

#define SYN_TPM2_ST_NO_SESSIONS `0x8001U`

Command/Response Tag: No session authorization

---

define SYN_TPM2_ST_SESSIONS

#define SYN_TPM2_ST_SESSIONS `0x8002U`

Command/Response Tag: With session authorization

---

define SYN_TPM2_SU_CLEAR

#define SYN_TPM2_SU_CLEAR `0x0000U`

Startup clear (cold boot)

---

define SYN_TPM2_SU_STATE

#define SYN_TPM2_SU_STATE `0x0001U`

Startup state (warm sleep resume)

---

---

The documentation for this class was generated from the following file src/syntropic/crypto/syn_tpm2.h