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.
146 lines
4.0 KiB
146 lines
4.0 KiB
.\" Process this file with
|
|
.\" groff -man -Tascii foo.1
|
|
.\"
|
|
.TH Tss2_TctiLdr_Initialize 3 "MARCH 2019" "TPM2 Software Stack"
|
|
.SH NAME
|
|
Tss2_TctiLdr_Initialize, Tss2_TctiLdr_Initialize_Ex \- Instantiate and
|
|
initialize a TCTI context.
|
|
.SH SYNOPSIS
|
|
.B #include <tss2/tss2_tctildr.h>
|
|
.sp
|
|
.sp
|
|
.BI "TSS2_RC Tss2_TctiLdr_Initialize (const char " "*nameConf" ", TSS2_TCTI_CONTEXT " "**context" ");"
|
|
.sp
|
|
.BI "TSS2_RC Tss2_TctiLdr_Initialize_Ex (const char " "*name" ", const char " "*conf" ", TSS2_TCTI_CONTEXT " "**context" ");"
|
|
.sp
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR Tss2_TctiLdr_Initialize ()
|
|
and
|
|
.BR Tss2_TctiLdr_Initialize_Ex ()
|
|
functions initialize a TCTI context used to communicate with the TPM2 or
|
|
some intermediate component in the TCG TPM2 software stack.
|
|
.sp
|
|
.BR Tss2_TctiLdr_Initialize ()
|
|
takes a single string that encodes both the name of the TCTI library the
|
|
caller wishes to instantiate and its desired configuration in the
|
|
.I nameConf
|
|
parameter.
|
|
.I nameConf
|
|
is a string comprised of two substrings:
|
|
.I name
|
|
and
|
|
.I conf
|
|
parameters respectively.
|
|
These substrings are combined with
|
|
.I name
|
|
first, separated by a single ':' / colon character: 'name:conf'. Consult
|
|
the section titled TCTI CONFIG for information about the encoding of these
|
|
strings.
|
|
The
|
|
.I context
|
|
parameter is used to return a reference to the TCTI context created by
|
|
the function.
|
|
.sp
|
|
.BR Tss2_TctiLdr_Initialize_Ex ()
|
|
behaves identically to the
|
|
.BR Tss2_TctiLdr_Initialize ()
|
|
function with the exception that the TCTI name and configuration are passed
|
|
as separate strings. The encoding of these strings is described in section
|
|
TCTI_CONFIG.
|
|
.SH TCTI CONFIG
|
|
If the
|
|
.I name
|
|
string is NULL or the emptry string then the initialization functions will
|
|
select a default TCTI appropriate for the platform. On Linux this means
|
|
first trying to load a library named
|
|
.I libtss2-tcti-default.so.
|
|
This is a placeholder for distros to provide a distro specific default. It
|
|
is recommended that this be a symlink to another installed TCTI library.
|
|
If attempts to load this shared object fails the implementation will
|
|
attempt known TCTIs in the following order:
|
|
.IP \[bu] 2
|
|
libtss2-tcti-tabrmd.so.0
|
|
.IP \[bu]
|
|
libtss2-tcti-device.so.0
|
|
.IP \[bu]
|
|
libtss2-tcti-mssim.so.0
|
|
.RE
|
|
.sp
|
|
When the
|
|
.I name
|
|
string is neither NULL nor the empty string the implementation will attempt
|
|
to
|
|
.I dlopen
|
|
a library with the given name. If this fails then the implementation assumes
|
|
it has been passed a shortened name and will attempt to load libraries by
|
|
name with the following permutations:
|
|
.IP \[bu] 2
|
|
<name>
|
|
.IP \[bu]
|
|
libtss2-tcti-<name>.so.0
|
|
.IP \[bu]
|
|
libtss2-tcti-<name>.so
|
|
.RE
|
|
.sp
|
|
The
|
|
.I config
|
|
string is not interpreted by the TctiLdr init functions and is passed
|
|
unaltered to the initialization function for the selected TCTI. The
|
|
format for this string is TCTI specific.
|
|
.sp
|
|
The
|
|
.BR Tss2_TctiLdr_Initialize
|
|
function is passed the
|
|
.I name
|
|
and
|
|
.I conf
|
|
strings as a single parameter. In this case the
|
|
.I name
|
|
and
|
|
.I conf
|
|
strings are concatinated with a single ':' / colon character separating them.
|
|
.sp
|
|
For a more thorough discussion of the TCTILDR API see the \*(lqTCG TSS 2.0 TPM Command
|
|
Transmission Interface (TCTI) API Specification\*(rq.
|
|
.SH RETURN VALUE
|
|
A successful call to this function 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_MEMORY
|
|
is returned if memory allocation fails
|
|
.sp
|
|
.B TSS2_TCTI_RC_NOT_SUPPORTED
|
|
is returned when the loader is unable to locate a TCTI library with the
|
|
provided
|
|
.I name
|
|
.sp
|
|
.B TSS2_TCTI_RC_IO_ERROR
|
|
is returned if a failure occurs in the underlying library loading mechanism
|
|
.sp
|
|
.B TSS2_TCTI_RC_BAD_REFERENCE
|
|
is returned if the
|
|
.I tctiContext
|
|
parameter is NULL
|
|
.sp
|
|
.SH EXAMPLE
|
|
Example code.
|
|
.sp
|
|
.nf
|
|
#include <inttypes.h>
|
|
#include <stdlib.h>
|
|
#include <stdio.h>
|
|
#include <tss2/tss2_tctildr.h>
|
|
|
|
TSS2_TCTI_CONTEXT *ctx = NULL;
|
|
TSS2_RC rc = Tss2_TctiLdr_Initialize (NULL, &ctx);
|
|
if (rc != TSS2_RC_SUCCESS) {
|
|
fprintf (stderr, "Initialization of default TCTI context failed with "
|
|
"response code: 0x%" PRIx32 "\n", rc);
|
|
exit (EXIT_FAILURE);
|
|
}
|
|
exit (EXIT_SUCCESS);
|
|
.fi
|