Tss2_Tcti_Libtpms_Init(3)

NAME
Tss2_Tcti_Libtpms_Init - Initialization function for the libtpms TPM simulator TCTI library.

SYNOPSIS
#include <tcti/tcti_libtpms.h>

TSS2_RC Tss2_Tcti_Libtpms_Init (TSS2_TCTI_CONTEXT *tctiContext, size_t *contextSize, const char *conf);

The Tss2_Tcti_Libtpms_Init() function initializes a TCTI context used to communicate with the libtpms TPM2 simulator.

DESCRIPTION
Tss2_Tcti_Libtpms_Init() attempts to dynamically load the libtpms library and initialize a caller allocated tcti_context of size size . Since the tcti_context must be a caller allocated buffer, the caller needs to know the buffer size required by the TCTI library. The minimum size of this context can be discovered by providing NULL for the tcti_context and a non- NULL size parameter. The initialization function will then populate the size parameter with the minimum size of the tcti_context buffer. The caller must then allocate a buffer of this size (or larger) and call Tss2_Tcti_Libtpms_Init () again providing the newly allocated tcti_context and the size of this context in the size parameter. This pattern is common to all TCTI initialization functions. We provide an example of this pattern using the Tss2_Tcti_Libtpms_Init() function in the section titled EXAMPLE.

The conf parameter can be used to specify the path to a state file (or NULL for none).

Once initialized, the TCTI context returned exposes the Trusted Computing Group (TCG) defined API for the lowest level communication with the TPM. Using this API the caller can exchange (send / receive) TPM2 command and response buffers with the libtpms TPM simulator. In nearly all cases however, the caller will initialize a context using this function before passing the context to a higher level API like the System API (SAPI), and then never touch it again.

For a more thorough discussion of the TCTI API see the “TSS System Level API and TPM Command Transmission Interface Specification” as published by the TCG: https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/

RETURN VALUE
A successful call to Tss2_Tcti_Libtpms_Init() will return TSS2_RC_SUCCESS. An unsuccessful call will produce a response code described in section ERRORS.

ERRORS
TSS2_TCTI_RC_BAD_VALUE is returned if both the tcti_context and the size parameters are NULL.

EXAMPLE

TCTI initialization fragment:

#include <inttypes.h>
#include <stdlib.h>
#include <stdio.h>
#include <tcti/tcti_libtpms.h>
TSS2_RC rc;
TSS2_TCTI_CONTEXT *tcti_context;
size_t size;
rc = Tss2_Tcti_Libtpms_Init (NULL, &size, NULL);
if (rc != TSS2_RC_SUCCESS) {
    fprintf (stderr, "Failed to get allocation size for libtpms TCTI "
             " context: 0x%" PRIx32 ", rc);
    exit (EXIT_FAILURE);
}
tcti_context = calloc (1, size);
if (tcti_context == NULL) {
    fprintf (stderr, "Allocation for TCTI context failed: %s,
             strerror (errno));
    exit (EXIT_FAILURE);
}
rc = Tss2_Tcti_Libtpms_Init (&tcti_context, &size, "tpm2-state.bin");
if (rc != TSS2_RC_SUCCESS) {
    fprintf (stderr, "Failed to initialize libtpms TCTI context: "
             "0x%" PRIx32 ", rc);
    free (tcti_context);
    exit (EXIT_FAILURE);
}