Search Results for

    Show / Hide Table of Contents

    Intel® Trust Authority TPM API Reference

    · 07/22/2024 ·

    This article provides an API reference for the Intel® Trust Authority Go TPM adapter. The adapter provides a set of APIs for interacting with a TPM. The adapter can be used to read and write NV indexes, read PCRs, and get quotes from the TPM.

    In this preview release the adapter supports Microsoft Azure* confidential virtual machines with Intel® Trust Domain Extensions (Intel® TDX) and vTPM 2.0. Future releases may support physical TPMs and other platforms.

    The preview TPM adapter supports composite attestation only. That is, vTPM + Intel TDX. You can't attest the vTPM by itself. The TPM adapter is used to get evidence from the vTPM. The evidence is endorsed by the Azure-provided AK, which is contained in the Intel TDX quote's runtime data. The Azure CVM with Intel TDX adapter is used to get evidence from the Intel TDX trust domain TEE. The evidence from the vTPM and the Intel TDX is combined for composite attestation.

    Prerequisites

    • Go 1.22 or later
    • Tpm2-tools must be installed on the confidential VM.

    Terms and definitions

    The following acronyms and terms are used in this article. For more information about TPM terms, see the Trusted Computing Group TPM 2.0 Library. Part 1: Architecture, Section 4: Terms and Definitions.

    Term Definition
    AK Attestation Key. The public AK is used to sign evidence quotes collected from the TPM. The AK for a physical TPM is normally provisioned by the user and written to the TPM. In the case of a vTPM, the Azure "paravisor" provisions an AK for you.
    EK Endorsement Key. The EK is unique for every TPM. The public EK is used by verifiers and relying parties to establish trust in the TPM. The EK is not used to sign quotes.
    Handle A 32-bit reference to an object in the TPM. Handles are assigned by the TPM and are used to reference objects in the TPM. For more information, see Registry of Reserved TPM 2.0 Handles and Localities, published by the Trusted Computing Group.
    NV Non-volatile data storage. NV memory stores persistent state associated with the TPM. Some storage is allocated for use by the platform.
    NV index A reference to a location in NV memory. For more information see TPM 2.0 Library Part 2: Structures , section 13 "NV Storage Structures."
    PCR Platform Configuration Register.
    TPM A physical Trusted Platform Module, which can be either a discrete device or a component of the CPU.
    vTPM A virtual Trusted Platform Module. A vTPM exists in software but provides functions and security similar to a physical TPM. In this document, TPM is used as a catch-all term. vTPM is used only when the distinction between a physical and virtual TPM is important.

    TPM adapter APIs

    The following APIs are provided by the Intel Trust Authority Go TPM adapter. This list is loosely grouped by functional area.

    Certificates and keys

    ReadPublic
    Reads the public key for an AK in the TPM.

    GetEKCertificate
    Gets the EK certificate from the TPM.

    Evidence and quotes

    GetEvidence
    Collects evidence from the TPM.

    GetEvidenceIdentifier
    Gets the evidence identifier for the TPM.

    GetPcrs
    Reads the PCRs from the TPM.

    GetQuote
    Gets a quote from the TPM. The quote is signed by the AK.

    WithOwnerAuth
    Sets the owner authorization value (password) to use when communicating with the TPM.

    WithDeviceType
    Sets the type of TPM device to use.

    WithAkHandle
    Sets the AK handle to use for quote generation.

    WithPcrSelections
    Sets the PCR selections to include in the quote.

    NV functions

    NVExists
    Checks if an NV index exists in the TPM.

    NVDefine
    Defines an NV index in the TPM.

    NVDelete
    Deletes an NV index and associated data from the TPM.

    NVRead
    Reads data from an NV index in the TPM.

    NVWrite
    Writes data to an NV index in the TPM.

    TPM adapter

    NewEvidenceAdapter
    Creates a new evidence adapter for the TPM.

    NewEvidenceAdapterWithOptions
    Creates a new evidence adapter for the TPM with options.

    Close
    Closes the connection to the TPM.

    Utility functions

    HandleExists
    Checks to see if the specified handle exists in the TPM.


    NVRead

    NVRead reads the bytes from the location specified by the NV handle.

    func (tpm *canonicalTpm) NVRead(nvHandle int) ([]byte, error)
    

    Parameters

    Parameter Description
    nvHandle The handle of the NV index to read.

    Return value

    A byte array containing the data read from the NV index. It returns an error if the handle isn't within the range of valid NV RAM or if the index doesn't exist.

    NVWrite

    Writes data to an NV index in the TPM.

    func (tpm *canonicalTpm) NVWrite(nvHandle int, data []byte) error 
    

    Parameters

    Parameter Description
    nvHandle The handle of the NV index to write to.
    data The data to write to the NV index. The maximum data size is 8192.

    Return value

    Returns an error if the handle isn't within the range of valid NV RAM or if the index doesn't exist.

    NVExists

    Checks if an NV index exists in the TPM.

    NVExists(nvHandle int) bool
    

    Parameters

    Parameter Description
    nvHandle The handle of the NV index to check.

    Return value

    Returns true if the NV index exists, or false if the handle isn't within the range of valid NV RAM or if the index doesn't exist.

    NVDefine

    Defines an NV index in the TPM with the specified handle and length.

    func (tpm *canonicalTpm) NVDefine(nvHandle int, len int) error 
    

    Parameters

    Parameter Description
    nvHandle The handle of the NV index to define.
    len The length in bytes of the NV index. The maximum length is 8192.

    Return value

    Returns an error if the handle isn't within the range of valid NV RAM or if the index already exists.

    NVDelete

    Deletes an NV index and associated data from the TPM.

    func (tpm *canonicalTpm) NVDelete(nvHandle int) error
    

    Parameters

    Parameter Description
    nvHandle The handle of the NV index to delete.

    Return value

    Returns an error if the handle isn't within the range of valid NV RAM or if the index doesn't exist.

    ReadPublic

    Reads the public key for an AK in the TPM.

    func (tpm *canonicalTpm) ReadPublic(handle int) (crypto.PublicKey, []byte, []byte, error)
    

    Parameters

    Parameter Description
    handle The handle of the AK to read.

    Return value

    Return value Description
    crypto.PublicKey The public key for the AK.
    []byte The AK name.
    []byte The AK qualified name.

    It returns an error if the handle isn't persistent or doesn't exist.

    Usage

    GetEKCertificate

    Gets the EK certificate from the TPM.

    func (tpm *canonicalTpm) GetEKCertificate(nvIndex int) (*x509.Certificate, error)
    

    Parameters

    Parameter Description
    nvIndex The NV index of the EK certificate.

    Return value

    Return value Description
    *x509.Certificate A pointer to the EK certificate.

    Returns an error if the certificate doesn't exist or if the TPM is unable to read the certificate. Not all TPMs have a certificate for the EK.

    GetQuote

    Gets a quote from the TPM. The quote is signed by the AK.

    func (tpm *canonicalTpm) GetQuote(akHandle int, nonce []byte, selection ...PcrSelection) ([]byte, []byte, error)
    

    Parameters

    Parameter Description
    akHandle The handle of the AK to use for signing the quote.
    nonce An array of nonce bytes to include in the quote.
    selection Optional. The PCR selections to include in the quote. If selection isn't provided, all SHA-1 and SHA-256 PCRs will be included in the quote.
    type PcrSelection struct {
    	Hash crypto.Hash
    	Pcrs []int
    }
    

    PcrSelection.Hash is the hash algorithm to use (SHA-1 or SHA-256), and PcrSelection.Pcrs is a list of comma-separated PCR index numbers.

    Return value

    Return value Description
    []byte The quote data.
    []byte The signature of the quote. The quote is signed with the public AK.

    Returns an error if the AK handle is invalid or if the TPM is unable to get the quote.

    GetPcrs

    Reads the PCRs from the TPM.

    func (tpm *canonicalTpm) GetPcrs(selection ...PcrSelection) ([]byte, error) 
    

    Parameters

    Parameter Description
    selection Optional. The PCR selections to include in the quote. If selection isn't provided, all SHA-1 and SHA-256 PCRs will be included in the quote. See GetQuote for a definition of PcrSelection.

    Return value

    GetPcrs returns the "flattened", concatenated, contiguous PCR measurements for SHA-256 banks 0-23 (in index order). This is similar to the PCR values returned by tpm2_quote when -F values options are provided.

    HandleExists

    Checks to see if the specified handle exists in the TPM.

    HandleExists(handle int) bool  
    

    Parameters

    Return value

    Returns true if the specified handle exists in the TPM, or false if the handle doesn't exist.

    Close

    Closes the connection to the TPM. This should be called when the TPM is no longer needed.

    func (tpm *canonicalTpm) Close()
    

    Parameters

    None.

    Return value

    None.

    NewEvidenceAdapter

    Creates a new evidence adapter for the TPM.

    func NewEvidenceAdapter(akHandle int, pcrSelections string, ownerAuth string) (connector.EvidenceAdapter2, error)
    

    Parameters

    Parameter Description
    akHandle The handle of the AK to use for signing the quote.
    pcrSelections A list of PCRs in tpm2-tools PCR Bank Selection format. For more information, see PCR Bank Specifiers in the tpm2-tools documentation.
    ownerAuth The owner authorization value (password) to use when communicating with the TPM. The default password is blank ("").

    Return value

    A new evidence adapter for the TPM, or an error if the adapter can't be created.

    NewEvidenceAdapterWithOptions

    Creates a new evidence adapter for the TPM with options.

    func NewEvidenceAdapterWithOptions(opts ...TpmAdapterOptions) (connector.EvidenceAdapter2, error) 
    

    Parameters

    Parameter Description
    opts A list of options to use when creating the adapter.

    Return value

    A new evidence adapter for the TPM with the specified options, or an error if the adapter can't be created.

    WithOwnerAuth

    Sets the owner authorization value (password) to use when communicating with the TPM.

    func WithOwnerAuth(ownerAuth string) TpmAdapterOptions
    

    Parameters

    Parameter Description
    ownerAuth The owner authorization value (password) to use when communicating with the TPM. The default password is blank ("").

    Return value

    None.

    WithDeviceType

    Sets the type of TPM device to use. By default, the Linux device is used (/dev/tpmrm0).

    func WithDeviceType(deviceType TpmDeviceType) TpmAdapterOptions
    

    Parameters

    Parameter Description
    deviceType The type of TPM device to use.

    Return value

    None.

    WithAkHandle

    Sets the AK handle to use for quote generation.

    func WithAkHandle(akHandle int) TpmAdapterOptions
    

    Parameters

    Parameter Description
    akHandle The handle of the AK to use for signing the quote.

    Return value

    WithPcrSelections

    Sets the PCR selections to include in the quote.

    func WithPcrSelections(selections string) TpmAdapterOptions
    

    Parameters

    Parameter Description
    selections A list of PCRs in tpm2-tools PCR Bank Selection format. For more information, see PCR Bank Specifiers in the tpm2-tools documentation.

    Return value

    GetEvidenceIdentifier

    Gets the evidence identifier for the TPM.

    func (tca *tpmCompositeAdapter) GetEvidenceIdentifier() string
    

    Parameters

    None.

    Return value

    "tpm" is returned as the evidence identifier for the TPM.

    GetEvidence

    Collects evidence from the TPM.

    func (tca *tpmCompositeAdapter) GetEvidence(verifierNonce *connector.VerifierNonce, userData []byte) (interface{}, error)
    

    Parameters

    Parameter Description
    verifierNonce The Intel Trust Authority verifier nonce to include in the evidence.
    userData Optional. User data to include in the evidence.

    Return value

    Return value Description
    interface{} The evidence data.



    * Other names and brands may be claimed as the property of others.

    In this article
    Back to top Notice & Disclaimer