Tss2_TctiLdr_Initialize(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 de‐
27       sired 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   Tss2_Tc‐
36       tiLdr_Initialize()  function  with the exception that the TCTI name and
37       configuration are passed as separate strings.  The  encoding  of  these
38       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-de‐
44       fault.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 in‐
46       stalled TCTI library.  If attempts to load this shared object fails the
47       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
55       When the name string is neither NULL nor the empty string the implemen‐
56       tation will attempt to dlopen a library with the given  name.  If  this
57       fails  then  the  implementation assumes it has been passed a shortened
58       name and will attempt to load libraries by name with the following per‐
59       mutations:
60
61       • <name>
62
63       • libtss2-tcti-<name>.so.0
64
65       • libtss2-tcti-<name>.so
66
67       The  config string is not interpreted by the TctiLdr init functions and
68       is passed unaltered to the initialization  function  for  the  selected
69       TCTI. The format for this string is TCTI specific.
70
71       The  Tss2_TctiLdr_Initialize  function  is  passed  the  name  and conf
72       strings as a single parameter. In this case the name and  conf  strings
73       are concatinated with a single ':' / colon character separating them.
74
75       For  a more thorough discussion of the TCTILDR API see the “TCG TSS 2.0
76       TPM Command Transmission Interface (TCTI) API Specification”.
77

RETURN VALUE

79       A successful call to this function will return TSS2_RC_SUCCESS.  An un‐
80       successful  call  will produce a response code described in section ER‐
81       RORS.
82

ERRORS

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

EXAMPLE

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

AUTHOR

114       TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>
115

COLOPHON

122       This page is part of release 4.0.1 of Open Source implementation of the
123       TCG TPM2 Software Stack (TSS2). A description of the project,  informa‐
124       tion  about  reporting bugs, and the latest version of this page can be
125       found at https://github.com/tpm2-software/tpm2-tss/.
126
127
128
129TPM2 Software Stack               MARCH 2019        Tss2_TctiLdr_Initialize(3)