You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
139 lines
4.1 KiB
139 lines
4.1 KiB
.\" Process this file with
|
|
.\" groff -man -Tascii foo.1
|
|
.\"
|
|
.TH Tss2_Tcti_Mssim_Init 3 "JUNE 2017" Intel "TPM2 Software Stack"
|
|
.SH NAME
|
|
Tss2_Tcti_Mssim_Init \- Initialization function for the Microsoft TPM simulator TCTI library.
|
|
.SH SYNOPSIS
|
|
.B #include <tcti/tcti_mssim.h>
|
|
.sp
|
|
.BI "TSS2_RC Tss2_Tcti_Mssim_Init (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*contextSize" ", const char " "*conf" ");"
|
|
.sp
|
|
The
|
|
.BR Tss2_Tcti_Mssim_Init ()
|
|
function initializes a TCTI context used to communicate with the Microsoft TPM2
|
|
simulator.
|
|
.SH DESCRIPTION
|
|
.BR Tss2_Tcti_Mssim_Init ()
|
|
attempts to initialize a caller allocated
|
|
.I tcti_context
|
|
of size
|
|
.I size
|
|
using caller provided configuration string
|
|
.I conf
|
|
\&. Since the
|
|
.I 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
|
|
.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 Tss2_Tcti_Mssim_Init ()
|
|
again providing the newly allocated
|
|
.I tcti_context
|
|
and the size of this context in the
|
|
.I size
|
|
parameter. This pattern is common to all TCTI initialization functions. We
|
|
provide an example of this pattern using the
|
|
.BR Tss2_Tcti_Mssim_Init ()
|
|
function in the section titled
|
|
.B EXAMPLE.
|
|
.sp
|
|
The
|
|
.I conf
|
|
parameter is a C string used to configure the TCTI context. This
|
|
configuration string is a series of key / value pairs that specify the host
|
|
and port used to connect to an instance of the Microsoft TPM2 simulator. The
|
|
keys and values are separated by the '=' character, while each key / value
|
|
pair is separated by the ',' character.
|
|
|
|
The only keys supported in the
|
|
.I conf
|
|
string are
|
|
.B host
|
|
and
|
|
.B port.
|
|
The host may be an IPv4 address, an IPv6 address, or a host name. The port
|
|
must be a valid uint16_t in string form. If a NULL
|
|
.I conf
|
|
string is provided by the caller then the default of
|
|
"host=localhost,port=2321" is used. If either
|
|
.B host
|
|
or
|
|
.B port
|
|
are omitted then their respective default value will be used.
|
|
.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
|
|
response buffers with the Microsoft 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.
|
|
.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 Tss2_Tcti_Mssim_Init ()
|
|
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_mssim.h>
|
|
|
|
TSS2_RC rc;
|
|
TSS2_TCTI_CONTEXT *tcti_context;
|
|
size_t size;
|
|
const char *conf = "host=localhost,port=2321"
|
|
|
|
rc = Tss2_Tcti_Mssim_Init (NULL, &size, NULL);
|
|
if (rc != TSS2_RC_SUCCESS) {
|
|
fprintf (stderr, "Failed to get allocation size for mssim 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 = Tss2_Tcti_Mssim_Init (&tcti_context, &size, conf);
|
|
if (rc != TSS2_RC_SUCCESS) {
|
|
fprintf (stderr, "Failed to initialize mssim TCTI context: "
|
|
"0x%" PRIx32 "\n", rc);
|
|
free (tcti_context);
|
|
exit (EXIT_FAILURE);
|
|
}
|
|
.fi
|