Tss2_TctiLdr_Initialize_Ex(3)

1Tss2_TctiLdr_Initialize(3) Library Functions Manual Tss2_TctiLdr_Initialize(3)
2
3
4

NAME

6       Tss2_TctiLdr_Initialize,  Tss2_TctiLdr_Initialize_Ex  - Instantiate and
7       initialize a TCTI context.
8

SYNOPSIS

10       #include <tss2/tss2_tctildr.h>
11
12
13       TSS2_RC Tss2_TctiLdr_Initialize (const char  *nameConf,  TSS2_TCTI_CON‐
14       TEXT **context);
15
16       TSS2_RC Tss2_TctiLdr_Initialize_Ex (const char *name, const char *conf,
17       TSS2_TCTI_CONTEXT **context);
18
19

DESCRIPTION

21       The Tss2_TctiLdr_Initialize()  and  Tss2_TctiLdr_Initialize_Ex()  func‐
22       tions  initialize  a  TCTI context used to communicate with the TPM2 or
23       some intermediate component in the TCG TPM2 software stack.
24
25       Tss2_TctiLdr_Initialize() takes a single string that encodes  both  the
26       name  of  the  TCTI  library  the  caller wishes to instantiate and its
27       desired configuration in the nameConf parameter.  nameConf is a  string
28       comprised  of  two  substrings:  name and conf parameters respectively.
29       These substrings are combined with name first, separated  by  a  single
30       ':'  /  colon  character:  'name:conf'. Consult the section titled TCTI
31       CONFIG for information about the encoding of these strings.   The  con‐
32       text  parameter  is used to return a reference to the TCTI context cre‐
33       ated by the function.
34
35       Tss2_TctiLdr_Initialize_Ex()     behaves     identically     to     the
36       Tss2_TctiLdr_Initialize()  function  with  the  exception that the TCTI
37       name and configuration are passed as separate strings. The encoding  of
38       these strings is described in section TCTI_CONFIG.
39

TCTI CONFIG

41       If the name string is NULL or the emptry string then the initialization
42       functions will select a default TCTI appropriate for the  platform.  On
43       Linux  this  means  first  trying to load a library named libtss2-tcti-
44       default.so.  This is a placeholder for distros to provide a distro spe‐
45       cific  default.  It  is  recommended  that this be a symlink to another
46       installed TCTI library.  If attempts to load this shared  object  fails
47       the implementation will attempt known TCTIs in the following order:
48
49       · libtss2-tcti-tabrmd.so.0
50
51       · libtss2-tcti-device.so.0
52
53       · libtss2-tcti-mssim.so.0
54
55When  the  name string is neither NULL nor the empty string the implementation
56will attempt to dlopen a library with the given name. If this fails  then  the
57implementation assumes it has been passed a shortened name and will attempt to
58load libraries by name with the following permutations:
59
60· <name>
61
62· libtss2-tcti-<name>.so.0
63
64· libtss2-tcti-<name>.so
65
66The config string is not interpreted by the  TctiLdr  init  functions  and  is
67passed  unaltered  to  the  initialization function for the selected TCTI. The
68format for this string is TCTI specific.
69
70The Tss2_TctiLdr_Initialize function is passed the name and conf strings as  a
71single parameter. In this case the name and conf strings are concatinated with
72a single ':' / colon character separating them.
73
74For a more thorough discussion of the TCTILDR API see the  “TCG  TSS  2.0  TPM
75Command Transmission Interface (TCTI) API Specification”.
76

RETURN VALUE

78       A  successful  call  to  this function will return TSS2_RC_SUCCESS.  An
79       unsuccessful call will produce a response  code  described  in  section
80       ERRORS.
81

ERRORS

83       TSS2_TCTI_RC_MEMORY is returned if memory allocation fails
84
85       TSS2_TCTI_RC_NOT_SUPPORTED  is  returned  when  the loader is unable to
86       locate a TCTI library with the provided name
87
88       TSS2_TCTI_RC_IO_ERROR is returned if a failure occurs in the underlying
89       library loading mechanism
90
91       TSS2_TCTI_RC_BAD_REFERENCE  is returned if the tctiContext parameter is
92       NULL
93
94

EXAMPLE

96       Example code.
97
98       #include <inttypes.h>
99       #include <stdlib.h>
100       #include <stdio.h>
101       #include <tss2/tss2_tctildr.h>
102
103       TSS2_TCTI_CONTEXT *ctx = NULL;
104       TSS2_RC rc = Tss2_TctiLdr_Initialize (NULL, &ctx);
105       if (rc != TSS2_RC_SUCCESS) {
106           fprintf (stderr, "Initialization of default TCTI context failed with "
107                    "response code: 0x%" PRIx32 "0, rc);
108           exit (EXIT_FAILURE);
109       }
110       exit (EXIT_SUCCESS);
111

AUTHOR

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

COLOPHON

121       This page is part of release 2.4.0 of Intel's implementation of the TCG
122       TPM2  Software  Stack (TSS2). A description of the project, information
123       about reporting bugs, and the latest version of this page can be  found
124       at https://github.com/tpm2-software/tpm2-tss/.
125
126
127
128TPM2 Software Stack               MARCH 2019        Tss2_TctiLdr_Initialize(3)