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
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
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
80       unsuccessful  call  will  produce  a response code described in section
81       ERRORS.
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
87       locate 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       Philip Tricca <philip.b.tricca@intel.com>
115

COLOPHON

122       This page is part of release 3.0.3 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)