forked from tpm2-software/tpm2-tss
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathTss2_Tcti_Mssim_Init.3.in
138 lines (135 loc) · 4.09 KB
/
Tss2_Tcti_Mssim_Init.3.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH Tss2_Tcti_Mssim_Init 3 "JUNE 2017" Intel "TPM2 Software Stack"
.SH NAME
Tss2_Tcti_Mssim_Init \- Initialization function for the Microsoft TPM simulator TCTI library.
.SH SYNOPSIS
.B #include <tcti/tcti_mssim.h>
.sp
.BI "TSS2_RC Tss2_Tcti_Mssim_Init (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*contextSize" ", const char " "*conf" ");"
.sp
The
.BR Tss2_Tcti_Mssim_Init ()
function initializes a TCTI context used to communicate with the Microsoft TPM2
simulator.
.SH DESCRIPTION
.BR Tss2_Tcti_Mssim_Init ()
attempts to initialize a caller allocated
.I tcti_context
of size
.I size
using caller provided configuration string
.I conf
\&. Since the
.I tcti_context
must be a caller allocated buffer, the caller needs to know the buffer size
required by the TCTI library. The minimum size of this context can be
discovered by providing
.BR NULL
for the
.I tcti_context
and a non-
.BR NULL
.I size
parameter. The initialization function will then populate the
.I size
parameter with the minimum size of the
.I tcti_context
buffer. The caller must then allocate a buffer of this size (or larger) and
call
.B Tss2_Tcti_Mssim_Init ()
again providing the newly allocated
.I tcti_context
and the size of this context in the
.I size
parameter. This pattern is common to all TCTI initialization functions. We
provide an example of this pattern using the
.BR Tss2_Tcti_Mssim_Init ()
function in the section titled
.B EXAMPLE.
.sp
The
.I conf
parameter is a C string used to configure the TCTI context. This
configuration string is a series of key / value pairs that specify the host
and port used to connect to an instance of the Microsoft TPM2 simulator. The
keys and values are separated by the '=' character, while each key / value
pair is separated by the ',' character.
The only keys supported in the
.I conf
string are
.B host
and
.B port.
The host may be an IPv4 address, an IPv6 address, or a host name. The port
must be a valid uint16_t in string form. If a NULL
.I conf
string is provided by the caller then the default of
"host=localhost,port=2321" is used. If either
.B host
or
.B port
are omitted then their respective default value will be used.
.sp
Once initialized, the TCTI context returned exposes the Trusted Computing
Group (TCG) defined API for the lowest level communication with the TPM.
Using this API the caller can exchange (send / receive) TPM2 command and
response buffers with the Microsoft TPM simulator. In nearly all cases however,
the caller will initialize a context using this function before passing the
context to a higher level API like the System API (SAPI), and then never touch
it again.
.sp
For a more thorough discussion of the TCTI API see the \*(lqTSS System Level
API and TPM Command Transmission Interface Specification\*(rq as published by
the TCG:
\%https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/
.SH RETURN VALUE
A successful call to
.BR Tss2_Tcti_Mssim_Init ()
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_BAD_VALUE
is returned if both the
.I tcti_context
and the
.I size
parameters are NULL, or if the
.I config
parameter is NULL.
.SH EXAMPLE
.sp
TCTI initialization fragment:
.sp
.nf
#include <inttypes.h>
#include <stdlib.h>
#include <stdio.h>
#include <tcti/tcti_mssim.h>
TSS2_RC rc;
TSS2_TCTI_CONTEXT *tcti_context;
size_t size;
const char *conf = "host=localhost,port=2321"
rc = Tss2_Tcti_Mssim_Init (NULL, &size, NULL);
if (rc != TSS2_RC_SUCCESS) {
fprintf (stderr, "Failed to get allocation size for mssim TCTI "
" context: 0x%" PRIx32 "\n", rc);
exit (EXIT_FAILURE);
}
tcti_context = calloc (1, size);
if (tcti_context == NULL) {
fprintf (stderr, "Allocation for TCTI context failed: %s\n",
strerror (errno));
exit (EXIT_FAILURE);
}
rc = Tss2_Tcti_Mssim_Init (&tcti_context, &size, conf);
if (rc != TSS2_RC_SUCCESS) {
fprintf (stderr, "Failed to initialize mssim TCTI context: "
"0x%" PRIx32 "\n", rc);
free (tcti_context);
exit (EXIT_FAILURE);
}
.fi