AxlTpm — TPM 2.0 presence + capability

TPM 2.0 presence and capability via EFI_TCG2_PROTOCOL.

Header: <axl/axl-tpm.h>. Unlike the other platform readers there is nothing to enumerate — the TCG2 protocol is a singleton — so this is a presence check plus one typed capability struct. Scope is the boot-service capability fields a diagnostic/inventory view reports; measurement, the event log, and PCR extension are out of scope.

The protocol is located lazily and cached (like the CPU-arch / MP-services helpers). axl_tpm_present() reports whether the TCG2 protocol is published; axl_tpm_get_capability() calls GetCapability and projects EFI_TCG2_BOOT_SERVICE_CAPABILITY into AxlTpmCapability.

if (axl_tpm_present()) {
    AxlTpmCapability cap;
    if (axl_tpm_get_capability(&cap) == AXL_OK && cap.present) {
        axl_printf("TPM mfr=0x%08x banks=%u active=0x%x\n",
                   cap.manufacturer_id, cap.number_of_pcr_banks,
                   cap.active_pcr_banks);
    }
}

Two presence concepts: axl_tpm_present() is “the TCG2 protocol is published” (a stack is available to query); AxlTpmCapability.present is the firmware’s TPMPresentFlag (“a chip is installed and responding”). When the protocol is absent axl_tpm_get_capability returns AXL_ERR and the consumer reports the TPM as not present (the QEMU-default golden, {"tpm":{"present":false}}).

active_pcr_banks is a hash-algorithm bitmask (EFI_TCG2_BOOT_HASH_ALG_*, consumer decodes names); number_of_pcr_banks is a count. Both are valid only when the capability structure version is >= 1.1.

API Reference

TPM 2.0 presence and capability readout.

Reads the platform’s TPM 2.0 capability via the firmware’s TCG2 protocol (EFI_TCG2_PROTOCOL.GetCapability). Unlike the other platform readers there is nothing to enumerate — the TCG2 protocol is a singleton — so this is a presence check plus one typed capability struct.

if (axl_tpm_present()) {
    AxlTpmCapability cap;
    if (axl_tpm_get_capability(&cap) == AXL_OK) {
        // ... report manufacturer, banks, sizes ...
    }
}

Scope is the boot-service capability fields a diagnostic/inventory view reports. Measurement, the event log, and PCR extension are out of scope.

Enums

enum AxlTpmEkAlg

EK public-key algorithm.

Values:

enumerator AXL_TPM_EK_RSA2048: RSA-2048 EK (TCG template L-1). The returned bytes are the modulus.

enumerator AXL_TPM_EK_ECC_P256: ECC NIST P-256 EK (TCG template L-2). The returned bytes are the uncompressed point X||Y (64 bytes).

Functions

bool axl_tpm_present(void)

Report whether the firmware publishes the TCG2 protocol.

A cheap presence gate: true means a TPM 2.0 software stack is available to query (call axl_tpm_get_capability for the details). It does not by itself guarantee a physical TPM is responding — that is AxlTpmCapability.present (TPMPresentFlag). Result is cached after the first call.

Returns:: true if the TCG2 protocol is published, false otherwise.

int axl_tpm_get_capability(AxlTpmCapability *out)

Read the TPM 2.0 boot-service capability.

Parameters:

out – [out] populated on success

Returns:

AXL_OK on success, AXL_ERR if the TCG2 protocol is not published, the GetCapability call fails, or out is NULL. A present-but-wedged TPM (protocol published, GetCapability fails) reports the same AXL_ERR as an absent protocol — the consumer reports the TPM as not present in both cases (the axl_tpm_present() == false case).

bool axl_tpm_ek_available(void)

Whether a TPM 2.0 with a readable Endorsement Key is present.

A consumer can branch on this to fall back to a weaker machine id (e.g. the SMBIOS UUID) when no TPM is available. Returns false immediately when the TCG2 protocol is absent; otherwise it confirms the EK can actually be derived. The result is cached after the first call.

Returns:: true if axl_tpm_read_ek_pub() will succeed.

int axl_tpm_read_ek_pub(uint8_t *buf, size_t buf_size, size_t *out_len, AxlTpmEkAlg *out_alg)

Read the TPM 2.0 Endorsement Key public part.

Derives the EK with TPM2_CreatePrimary in the endorsement hierarchy using the standard TCG EK template — ECC P-256 first, falling back to RSA-2048 — and returns the public key’s canonical bytes: for ECC the uncompressed point X||Y (64 bytes for P-256); for RSA the modulus (256 bytes for RSA-2048). Bytes are in their natural big-endian order, so they are deterministic for a given TPM across boots — hash them for a stable machine id. Derivation is transient (the primary handle is flushed); nothing is persisted in the TPM.

Output-buffer protocol: call with buf == NULL to query the required size (written to *out_len). Otherwise buf_size is the capacity; on success *out_len is the byte count and *out_alg the key type. If buf_size is too small, returns AXL_ERR with *out_len set to the required size and buf untouched.

Parameters:

buf – [out] EK public bytes, or NULL to size-query
buf_size – capacity of buf in bytes
out_len – [out] bytes written / required size
out_alg – [out] EK algorithm (may be NULL)

Returns:

AXL_OK on success; AXL_ERR if no TPM / no TCG2 protocol, the EK could not be derived, the buffer is too small, or out_len is NULL.

struct AxlTpmCapability

#include <axl-tpm.h>

TPM 2.0 boot-service capability.

Typed projection of the firmware’s EFI_TCG2_BOOT_SERVICE_CAPABILITY. present is the firmware’s own TPMPresentFlag — a TPM chip is installed and responding — which is distinct from axl_tpm_present() reporting that the TCG2 protocol is published.

Note the two PCR fields are different kinds of value: number_of_pcr_banks is a count, active_pcr_banks is a hash-algorithm bitmask (not a count). Both are meaningful only when the structure version is >= 1.1; on older firmware they read 0 — and since a present TPM always has at least one bank, number_of_pcr_banks == 0 on a present TPM means the firmware predates struct ver 1.1, not a bankless TPM.

The event-log format flags (SupportedEventLogs) are omitted — the event log is measurement-domain (out of scope). The two hash-algorithm bitmasks below are the supported/active pair an inventory view reports.

Public Members

bool present: TPMPresentFlag: a TPM is installed and responding.

uint8_t structure_version_major: capability structure version major

uint8_t structure_version_minor: capability structure version minor

uint8_t protocol_version_major: TCG2 protocol version major.

uint8_t protocol_version_minor: TCG2 protocol version minor.

uint32_t manufacturer_id: TPM manufacturer ID (TCG vendor ID, 4 packed ASCII bytes)

uint32_t max_command_size: max supported command buffer size in bytes

uint32_t max_response_size: max supported response buffer size in bytes

uint32_t number_of_pcr_banks: COUNT of PCR banks the TPM supports (struct ver >= 1.1)

uint32_t supported_hash_algorithms: hash algorithms the TCG2 stack supports, EFI_TCG2_BOOT_HASH_ALG_* BITMASK (HashAlgorithmBitmap; superset of active_pcr_banks; consumer decodes names)

uint32_t active_pcr_banks: active PCR-bank hash-algorithm BITMASK, EFI_TCG2_BOOT_HASH_ALG_* (struct ver >= 1.1; consumer decodes names)