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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
.\" Copyright (C) 2004 International Business Machines Corporation
.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden
.\"
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "Tspi_Context_RegisterKey" 3 "2004-05-25" "TSS 1.1"
.ce 1
TCG Software Stack Developers Reference
.SH NAME
Tspi_Context_RegisterKey \- register a key in the TSS Persistent Storage database
.SH "SYNOPSIS"
.ad l
.hy 0
.nf
.B #include <tss/platform.h>
.B #include <tss/tcpa_defines.h>
.B #include <tss/tcpa_typedef.h>
.B #include <tss/tcpa_struct.h>
.B #include <tss/tss_typedef.h>
.B #include <tss/tss_structs.h>
.B #include <tss/tspi.h>
.sp
.BI "TSS_RESULT Tspi_Context_RegisterKey(TSS_HCONTEXT " hContext ", TSS_HKEY " hKey ","
.BI " TSS_FLAG " persistentStorageType ", TSS_UUID " uuidKey ","
.BI " TSS_FLAG " persistentStorageTypeParent ", TSS_UUID " uuidParentKey "); "
.fi
.sp
.ad
.hy
.SH "DESCRIPTION"
.PP
\fBTspi_Context_RegisterKey\fR is the API that
registers a key with the TSS Persistent Storage database so that it
can be loaded as necessary. It also includes all information required
for loading the key, as well as information about its parent key.
.SH "PARAMETERS"
.PP
.SS hContext
The \fIhContext\fR parameter is the handle of the context object.
.SS hKey
The \fIhKey\fR parameter is the handle of the key object addressing the key
to be registered.
.SS persistentStorageType
The \fIpersistentStorageType\fR parameter indicates the persistent
storage the key is registered in.
.SS uuidKey
The \fIuuidKey\fR parameter is the UUID by which the key is registered in
persistent storage.
.SS persistentStorageTypeParent
The \fIpersistentStorageTypeParent\fR parameter indicates the persistent storage
that the parent key is registered in.
.SS uuidParentKey
The \fIuuidParentKey\fR parameter is the UUID by which the parent key is
registered in persistent storage.
.SH "RETURN CODES"
.PP
\fBTspi_Context_RegisterKey\fR returns TSS_SUCCESS on success, otherwise
one of the following values is returned:
.TP
.SM TSS_E_INVALID_HANDLE
\fIhContext\fR is not a valid handle.
.TP
.SM TSS_E_PS_KEY_NOTFOUND
The key cannot be found in the persistent storage database.
.TP
.SM TSS_E_INTERNAL_ERROR
An internal SW error has been detected.
.TP
.SM TSS_E_BAD_PARAMETER
One or more parameters is bad.
.SH "EXAMPLE"
.nf
#include <trousers/tss.h>
int
main(void)
{
TSS_FLAGS initFlags = ...;
TSS_HKEY hKey, hSRK;
TSS_UUID keyUUID = {...};
// Create a TSP handle
result = Tspi_Context_Create(&hContext);
if (result != TSS_SUCCESS)
Error_Path();
// Connect to the TCSD
result = Tspi_Context_Connect(hContext, GLOBALSERVER);
if (result != TSS_SUCCESS)
Error_Path();
// Create the Key Object
result = Tspi_Context_CreateObject(hContext,
TSS_OBJECT_TYPE_RSAKEY,
initFlags, &hKey);
if (result != TSS_SUCCESS)
Error_Path();
// Load parent Key by UUID
result = Tspi_Context_LoadKeyByUUID(hContext, TSS_PS_TYPE_SYSTEM,
SRK_UUID, &hSRK);
if (result != TSS_SUCCESS)
Error_Path();
// Do policy/secret handling here
result = Tspi_Key_CreateKey(hKey, hSRK, 0);
if (result != TSS_SUCCESS)
Error_Path();
// Register the Key in System PS (on the TCSD's platform)
result = Tspi_Context_RegisterKey(hContext, hKey, TSS_PS_TYPE_SYSTEM,
keyUUID, TSS_PS_TYPE_SYSTEM,
SRK_UUID);
if (result != TSS_SUCCESS)
Error_Path();
/* ...
*
* Use the key as needed, exiting the program if necessary, reloading
* the key using Tspi_Context_LoadKeyByUUID() after each restart. Once
* the key is no longer useful, unregister it from system PS as part
* of clean up.
*/
// Unregister the Key
result = Tspi_Context_UnregisterKey(hContext, TSS_PS_TYPE_SYSTEM,
migratableSignUUID, &hKey);
if (result != TSS_SUCCESS)
Error_Path();
// exit, discarding hKey
}
.fi
.SH "CONFORMING TO"
.PP
\fBTspi_Context_RegisterKey\fR conforms to the Trusted Computing Group
Software Specification version 1.1 Golden
.SH "SEE ALSO"
.PP
\fBTspi_Context_UnregisterKey\fR(3), \fBTspi_Context_LoadKeyByUUID\fR(3),
\fBTspi_Context_GetRegisteredKeyByUUID\fR(3).
|
