NAME¶

InitSocketTcti - Initialization function for the Microsoft TPM simulator TCTI library.

SYNOPSIS¶

#include <tcti/tcti_socket.h>

typedef int (*TCTI_LOG_CALLBACK)( void *data, printf_typetype, const char *format, ...");

typedef struct {


    const char *hostname;


    uint16_t port;


    TCTI_LOG_CALLBACK logCallback;


    TCTI_LOG_BUFFER_CALLBACK logBufferCallback;


    void *logData;
} TCTI_SOCKET_CONF;

TSS2_RC InitSocketTcti (TSS2_TCTI_CONTEXT *tctiContext, size_t *contextSize, const TCTI_SOCKET_CONF *config, const uint8_t serverSockets);

The InitSocketTcti() function initializes a TCTI context used to communicate with the Microsoft TPM simulator.

DESCRIPTION¶

InitSocketTcti() attempts to initialize a caller allocated tcti_context of size size using caller provided configuration information from config . Since the tcti_context must be a caller allocated buffer, the caller needs to know the 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 InitSocketTcti () again providing the newly allocated tcti_context and the size of this context in the size parameter. This patterm is common to all TCTI initialization functions. We provide an example of this pattern using the InitSocketTcti() function in the section titled EXAMPLE.

The config parameter is a reference to an instance of the TCTI_SOCKET_CONF structure. The hostname member of this structure is a C string that contains the hostname or IPv4 address of the Microsoft TPM simulator. The port member is an unsigned 16 bit integer containing the port number for the simulator command / response port. The simulator listens for “platform commands” on port+1 and so an additional connection will be made to this port. The logCallback member is a pointer to a callback function that will be called by the socket TCTI. This is expected to be a printf like function. The logBufferCallback mamber is a pointer to a call back function that will be invoked by the socket TCTI before a command buffer is transmitted or after a resposne buffer is received. This is expected to be a printf like function. The logData member is a void pointer that may be used to pass user data to the logCallback and logBufferCallback functions on each invocation.

The serverSockets parameter should always be 0 for client code.

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 respons buffers with the Microsoft TPM simulator. In nearly all cases however, the caller will initialize a context using this funnction 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 InitSocketTcti() 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, or if the config parameter is NULL.

EXAMPLE¶

Logging functions:

int DebugPrintfCallback (void *data, printf_type type, const char *format, ...)
{


    va_list args;


    int rval = 0;


    va_start( args, format );


    rval = vprintf( format, args );


    va_end (args);


    return rval;
}
void DebugPrintBuffer (printf_type type, UINT8 *buffer, UINT32 length)
{


    UINT32  i;


    for( i = 0; i < length; i++ )


    {


        if( ( i % 16 ) == 0 ) {


            printf ("0);


        }


        printf ("%2.2x ", buffer[i] );


    }


    printf ("0);
}

TCTI initialization fragment:

#include <inttypes.h>
#include <stdlib.h>
#include <stdio.h>
#include <tcti/tcti_socket.h>
TSS2_RC rc;
TSS2_TCTI_CONTEXT *tcti_context;
size_t size;
TCTI_SOCKET_CONF conf = {


    .hostname          = "127.0.0.1",


    .port              = 2321,


    .logCallback       = DebugPrintfCallback,


    .logBufferCallback = DebugPrintBuffer,


    .logData           = NULL,
};
rc = InitSocketTcti (NULL, &size, NULL, 0);
if (rc != TSS2_RC_SUCCESS) {


    fprintf (stderr, "Failed to get allocation size for tabrmd TCTI "


             " context: 0x%" PRIx32 "0, rc);


    exit (EXIT_FAILURE);
}
tcti_context = calloc (1, size);
if (tcti_context == NULL) {


    fprintf (stderr, "Allocation for TCTI context failed: %s0,


             strerror (errno));


    exit (EXIT_FAILURE);
}
rc = InitSocketTcti (&tcti_context, &size, &conf, 0);
if (rc != TSS2_RC_SUCCESS) {


    fprintf (stderr, "Failed to initialize tabrmd TCTI context: "


             "0x%" PRIx32 "0, rc);


    free (tcti_context);


    exit (EXIT_FAILURE);
}

AUTHOR¶

Philip Tricca <philip.b.tricca@intel.com>

SEE ALSO¶

InitDeviceTcti(3), InitSocketTcti(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

COLOPHON¶

This page is part of release 1.4.0 of Intel's implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/01org/tpm2.0-tss/.