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.
126 lines
3.8 KiB
126 lines
3.8 KiB
.\" Process this file with
|
|
.\" groff -man -Tascii foo.1
|
|
.\"
|
|
.TH Tss2_Tcti_Device_Init 3 "MARCH 2018" Intel "TPM2 Software Stack"
|
|
.SH NAME
|
|
Tss2_Tcti_Device_init \- Initialization function for the device TCTI library.
|
|
.SH SYNOPSIS
|
|
.B #include <tcti/tcti_device.h>
|
|
.sp
|
|
.sp
|
|
.BI "TSS2_RC Tss2_Tcti_Device_Init (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*size" ", const char " "*conf" ");"
|
|
.sp
|
|
The
|
|
.BR Tss2_Tcti_Device_Init ()
|
|
function initializes a TCTI context used to communicate with the TPM device
|
|
driver.
|
|
.SH DESCRIPTION
|
|
.BR Tss2_Tcti_Device_Init ()
|
|
attempts to initialize a caller allocated
|
|
.I tctiContext
|
|
of size
|
|
.I size
|
|
\&. Since the
|
|
.I tctiContext
|
|
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 tctiContext
|
|
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 tctiContext
|
|
buffer. The caller must then allocate a buffer of this size (or larger) and
|
|
call
|
|
.B Tss2_Tcti_Device_Init ()
|
|
again providing the newly allocated
|
|
.I tctiContext
|
|
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_Device_Init ()
|
|
function in the section titled
|
|
.B EXAMPLE.
|
|
.sp
|
|
The
|
|
.I conf
|
|
parameter is a C string. If this string is
|
|
.BR NULL
|
|
then the library will use a default configuration string for the caller.
|
|
Alternatively, the caller may provide a configuration string that must
|
|
contain the path to the device node exposed by the TPM device driver.
|
|
.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 TPM device driver. 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
|
|
TCG TSS 2.0 TPM Command
|
|
Transmission Interface (TCTI) API
|
|
Specification
|
|
|
|
For a more thorough discussion of the TCTI API see the \*(lqTCG TSS 2.0 TPM Command
|
|
Transmission Interface (TCTI) API Specification\*(rq as published by
|
|
the TCG:
|
|
\%https://trustedcomputinggroup.org/wp-content/uploads/TSS_TCTI_Version-1.0_Revision-05_Review_END030918.pdf
|
|
.SH RETURN VALUE
|
|
A successful call to
|
|
.BR Tss2_Tcti_Device_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 any parameters contain unexpected values.
|
|
.B TSS2_TCTI_RC_BAD_REFERENCE
|
|
is returned if any parameters are NULL when they should not be.
|
|
.B TSS2_TCTI_RC_BAD_CONTEXT
|
|
is returned if the size of the provided
|
|
.i tctiContext
|
|
is insufficient.
|
|
.SH EXAMPLE
|
|
TCTI initialization fragment:
|
|
.sp
|
|
.nf
|
|
#include <inttypes.h>
|
|
#include <stdlib.h>
|
|
#include <stdio.h>
|
|
#include <tcti/tcti_device.h>
|
|
|
|
TSS2_RC rc;
|
|
TSS2_TCTI_CONTEXT *tcti_context;
|
|
size_t size;
|
|
char *conf = "/dev/tpm0",
|
|
|
|
rc = Tss2_Tcti_Device_Init (NULL, &size, NULL);
|
|
if (rc != TSS2_RC_SUCCESS) {
|
|
fprintf (stderr, "Failed to get allocation size for device 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_Device_Init (&tcti_context, &size, &conf);
|
|
if (rc != TSS2_RC_SUCCESS) {
|
|
fprintf (stderr, "Failed to initialize device TCTI context: "
|
|
"0x%" PRIx32 "\n", rc);
|
|
free (tcti_context);
|
|
exit (EXIT_FAILURE);
|
|
}
|
|
exit (EXIT_SUCCESS);
|
|
.fi
|