InitDeviceTcti(3)

1InitDeviceTcti(3)             TPM2 Software Stack            InitDeviceTcti(3)
2
3
4

NAME

6       InitDeviceTcti - Initialization function for the device TCTI library.
7

SYNOPSIS

9       #include <tcti/tcti_device.h>
10
11       typedef  int  (*TCTI_LOG_CALLBACK)(  void *data, printf_typetype, const
12       char *format, ...");
13
14       typedef struct {
15           const char *device_path;
16           TCTI_LOG_CALLBACK logCallback;
17           void *logData;
18       } TCTI_DEVICE_CONF;
19
20       TSS2_RC InitDeviceTcti (TSS2_TCTI_CONTEXT  *tctiContext,  size_t  *con‐
21       textSize, const TCTI_DEVICE_CONF *config);
22
23       The InitDeviceTcti() function initializes a TCTI context used to commu‐
24       nicate with the TPM device driver.
25

DESCRIPTION

27       InitDeviceTcti() attempts to initialize a caller allocated tcti_context
28       of  size  size . Since the tcti_context must be a caller allocated buf‐
29       fer, the caller needs to know the size required by  the  TCTI  library.
30       The  minimum  size  of this context can be discovered by providing NULL
31       for the tcti_context and a non- NULL size parameter. The initialization
32       function will then populate the size parameter with the minimum size of
33       the tcti_context buffer. The caller must then allocate a buffer of this
34       size  (or  larger) and call InitDeviceTcti () again providing the newly
35       allocated tcti_context and the size of this context in the size parame‐
36       ter.  This  patterm  is common to all TCTI initialization functions. We
37       provide an example of this pattern using the InitDeviceTcti()  function
38       in the section titled EXAMPLE.
39
40       The   config   parameter   is   a  reference  to  an  instance  of  the
41       TCTI_DEVICE_CONF structure. The device_path member of this structure is
42       a C string that contains the path to the device node exposed by the TPM
43       device driver.
44
45       The logCallback parameter is a pointer to a callback function that will
46       be  called  by  the  device  TCTI. This is expected to be a printf like
47       function.
48
49       The logData member is a void pointer to user data that will be supplied
50       to the logCallback function on each invocation.
51
52       Once initialized, the TCTI context returned exposes the Trusted Comput‐
53       ing Group (TCG) defined API for the lowest level communication with the
54       TPM.  Using this API the caller can exchange (send / receive) TPM2 com‐
55       mand and respons buffers with the TPM  device  driver.  In  nearly  all
56       cases  however,  the caller will initialize a context using this funnc‐
57       tion before passing the context to a higher level API like  the  System
58       API (SAPI), and then never touch it again.
59
60       For  a  more  thorough  discussion  of the TCTI API see the “TSS System
61       Level API and TPM Command Transmission Interface Specification” as pub‐
62       lished                   by                   the                  TCG:
63       https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/
64

RETURN VALUE

66       A  successful call to InitDeviceTcti() will return TSS2_RC_SUCCESS.  An
67       unsuccessful call will produce a response  code  described  in  section
68       ERRORS.
69

ERRORS

71       TSS2_TCTI_RC_BAD_VALUE  is  returned  if  both the tcti_context and the
72       size parameters are NULL, or if the config parameter is NULL.
73

EXAMPLE

75       Logging function:
76
77       int DebugPrintfCallback( void *data, printf_type type, const char *format, ...)
78       {
79           va_list args;
80           int rval = 0;
81
82           va_start( args, format );
83           rval = vprintf( format, args );
84           va_end (args);
85
86           return rval;
87       }
88
89       TCTI initialization fragment:
90
91       #include <inttypes.h>
92       #include <stdlib.h>
93       #include <stdio.h>
94       #include <tcti/tcti_device.h>
95
96       TSS2_RC rc;
97       TSS2_TCTI_CONTEXT *tcti_context;
98       size_t size;
99       TCTI_DEVICE_CONF conf = {
100           .device_path = "/dev/tpm0",
101           .logCallback = DebugPrintfCallback,
102           .logData     = NULL,
103       };
104
105       rc = InitDeviceTcti (NULL, &size, NULL);
106       if (rc != TSS2_RC_SUCCESS) {
107           fprintf (stderr, "Failed to get allocation size for tabrmd TCTI "
108                    " context: 0x%" PRIx32 "0, rc);
109           exit (EXIT_FAILURE);
110       }
111       tcti_context = calloc (1, size);
112       if (tcti_context == NULL) {
113           fprintf (stderr, "Allocation for TCTI context failed: %s0,
114                    strerror (errno));
115           exit (EXIT_FAILURE);
116       }
117       rc = InitDeviceTcti (&tcti_context, &size, &conf);
118       if (rc != TSS2_RC_SUCCESS) {
119           fprintf (stderr, "Failed to initialize tabrmd TCTI context: "
120                    "0x%" PRIx32 "0, rc);
121           free (tcti_context);
122           exit (EXIT_FAILURE);
123       }
124       exit (EXIT_SUCCESS);
125

AUTHOR

127       Philip Tricca <philip.b.tricca@intel.com>
128

COLOPHON

134       This page is part of release 1.4.0 of Intel's implementation of the TCG
135       TPM2 Software Stack (TSS2). A description of the  project,  information
136       about  reporting bugs, and the latest version of this page can be found
137       at https://github.com/01org/tpm2.0-tss/.
138
139
140
141Intel                              JUNE 2017                 InitDeviceTcti(3)