| .\" Process this file with |
| .\" groff -man -Tascii foo.1 |
| .\" |
| .TH InitSocketTcti 3 "JUNE 2017" Intel "TPM2 Software Stack" |
| .SH NAME |
| InitSocketTcti \- Initialization function for the Microsoft TPM simulator TCTI library. |
| .SH SYNOPSIS |
| .B #include <tcti/tcti_socket.h> |
| .sp |
| .nf |
| typedef struct { |
| const char *hostname; |
| uint16_t port; |
| } TCTI_SOCKET_CONF; |
| .fi |
| .sp |
| .BI "TSS2_RC InitSocketTcti (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*contextSize" ", const TCTI_SOCKET_CONF " "*config" ", const uint8_t " "serverSockets" ");" |
| |
| .sp |
| The |
| .BR InitSocketTcti () |
| function initializes a TCTI context used to communicate with the Microsoft TPM |
| simulator. |
| .SH DESCRIPTION |
| .BR InitSocketTcti () |
| attempts to initialize a caller allocated |
| .I tcti_context |
| of size |
| .I size |
| using caller provided configuration information from |
| .I config |
| \&. Since the |
| .I 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 |
| .BR NULL |
| for the |
| .I tcti_context |
| and a non- |
| .BR NULL |
| .I size |
| parameter. The initialization function will then populate the |
| .I size |
| parameter with the minimum size of the |
| .I tcti_context |
| buffer. The caller must then allocate a buffer of this size (or larger) and |
| call |
| .B InitSocketTcti () |
| again providing the newly allocated |
| .I tcti_context |
| and the size of this context in the |
| .I size |
| parameter. This patterm is common to all TCTI initialization functions. We |
| provide an example of this pattern using the |
| .BR InitSocketTcti () |
| function in the section titled |
| .B EXAMPLE. |
| .sp |
| The |
| .I config |
| parameter is a reference to an instance of the |
| .B TCTI_SOCKET_CONF |
| structure. The |
| .I hostname |
| member of this structure is a C string that contains the hostname or IPv4 |
| address of the Microsoft TPM simulator. The |
| .I port |
| member is an unsigned 16 bit integer containing the port number for the |
| simulator command / response port. The simulator listens for \*(lqplatform |
| commands\*(rq on |
| .I port+1 |
| and so an additional connection will be made to this port. |
| .sp |
| The |
| .I serverSockets |
| parameter should always be 0 for client code. |
| .sp |
| 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. |
| .sp |
| For a more thorough discussion of the TCTI API see the \*(lqTSS System Level |
| API and TPM Command Transmission Interface Specification\*(rq as published by |
| the TCG: |
| \%https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/ |
| .SH RETURN VALUE |
| A successful call to |
| .BR InitSocketTcti () |
| will return |
| .B TSS2_RC_SUCCESS. |
| An unsuccessful call will produce a response code described in section |
| .B ERRORS. |
| .SH ERRORS |
| .B TSS2_TCTI_RC_BAD_VALUE |
| is returned if both the |
| .I tcti_context |
| and the |
| .I size |
| parameters are NULL, or if the |
| .I config |
| parameter is NULL. |
| .SH EXAMPLE |
| .sp |
| TCTI initialization fragment: |
| .sp |
| .nf |
| #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, |
| }; |
| |
| rc = InitSocketTcti (NULL, &size, NULL, 0); |
| if (rc != TSS2_RC_SUCCESS) { |
| fprintf (stderr, "Failed to get allocation size for socket TCTI " |
| " context: 0x%" PRIx32 "\n", rc); |
| exit (EXIT_FAILURE); |
| } |
| tcti_context = calloc (1, size); |
| if (tcti_context == NULL) { |
| fprintf (stderr, "Allocation for TCTI context failed: %s\n", |
| strerror (errno)); |
| exit (EXIT_FAILURE); |
| } |
| rc = InitSocketTcti (&tcti_context, &size, &conf, 0); |
| if (rc != TSS2_RC_SUCCESS) { |
| fprintf (stderr, "Failed to initialize socket TCTI context: " |
| "0x%" PRIx32 "\n", rc); |
| free (tcti_context); |
| exit (EXIT_FAILURE); |
| } |
| .fi |