Tspi_Context_RegisterKey(3)

1Tspi_Context_RegisterKey(3)Library Functions ManualTspi_Context_RegisterKey(3)
2
3
4
5                   TCG Software Stack Developers Reference
6

NAME

8       Tspi_Context_RegisterKey - register a key in the TSS Persistent Storage
9       database
10

SYNOPSIS

12       #include <tss/platform.h>
13       #include <tss/tcpa_defines.h>
14       #include <tss/tcpa_typedef.h>
15       #include <tss/tcpa_struct.h>
16       #include <tss/tss_typedef.h>
17       #include <tss/tss_structs.h>
18       #include <tss/tspi.h>
19
20       TSS_RESULT Tspi_Context_RegisterKey(TSS_HCONTEXT hContext,                    TSS_HKEY hKey,
21                                           TSS_FLAG     persistentStorageType,       TSS_UUID uuidKey,
22                                           TSS_FLAG     persistentStorageTypeParent, TSS_UUID uuidParentKey);
23
24
25

DESCRIPTION

27       Tspi_Context_RegisterKey is the API that registers a key with  the  TSS
28       Persistent  Storage  database so that it can be loaded as necessary. It
29       also includes all information required for loading the key, as well  as
30       information about its parent key.
31
32

PARAMETERS

34   hContext
35       The hContext parameter is the handle of the context object.
36
37   hKey
38       The  hKey  parameter is the handle of the key object addressing the key
39       to be registered.
40
41   persistentStorageType
42       The persistentStorageType parameter indicates  the  persistent  storage
43       the key is registered in.
44
45   uuidKey
46       The  uuidKey  parameter  is  the UUID by which the key is registered in
47       persistent storage.
48
49   persistentStorageTypeParent
50       The  persistentStorageTypeParent  parameter  indicates  the  persistent
51       storage that the parent key is registered in.
52
53   uuidParentKey
54       The uuidParentKey parameter is the UUID by which the parent key is reg‐
55       istered in persistent storage.
56
57

RETURN CODES

59       Tspi_Context_RegisterKey returns TSS_SUCCESS on success, otherwise  one
60       of the following values is returned:
61
62       TSS_E_INVALID_HANDLE
63              hContext is not a valid handle.
64
65
66       TSS_E_PS_KEY_NOTFOUND
67              The key cannot be found in the persistent storage database.
68
69
70       TSS_E_INTERNAL_ERROR
71              An internal SW error has been detected.
72
73
74       TSS_E_BAD_PARAMETER
75              One or more parameters is bad.
76
77

EXAMPLE

79       #include <trousers/tss.h>
80
81       int
82       main(void)
83       {
84            TSS_FLAGS initFlags = ...;
85            TSS_HKEY  hKey, hSRK;
86            TSS_UUID  keyUUID = {...};
87
88            // Create a TSP handle
89            result = Tspi_Context_Create(&hContext);
90            if (result != TSS_SUCCESS)
91                 Error_Path();
92
93            // Connect to the TCSD
94            result = Tspi_Context_Connect(hContext, GLOBALSERVER);
95            if (result != TSS_SUCCESS)
96                 Error_Path();
97
98            // Create the Key Object
99            result = Tspi_Context_CreateObject(hContext,
100                           TSS_OBJECT_TYPE_RSAKEY,
101                           initFlags, &hKey);
102            if (result != TSS_SUCCESS)
103                 Error_Path();
104
105            // Load parent Key by UUID
106            result = Tspi_Context_LoadKeyByUUID(hContext, TSS_PS_TYPE_SYSTEM,
107                                     SRK_UUID, &hSRK);
108            if (result != TSS_SUCCESS)
109                 Error_Path();
110
111            // Do policy/secret handling here
112
113            result = Tspi_Key_CreateKey(hKey, hSRK, 0);
114            if (result != TSS_SUCCESS)
115                 Error_Path();
116
117            // Register the Key in System PS (on the TCSD's platform)
118               result = Tspi_Context_RegisterKey(hContext, hKey, TSS_PS_TYPE_SYSTEM,
119                                keyUUID, TSS_PS_TYPE_SYSTEM,
120                                SRK_UUID);
121            if (result != TSS_SUCCESS)
122                 Error_Path();
123
124            /* ...
125             *
126             * Use the key as needed, exiting the program if necessary, reloading
127             * the key using Tspi_Context_LoadKeyByUUID() after each restart. Once
128             * the key is no longer useful, unregister it from system PS as part
129             * of clean up.
130             */
131
132               // Unregister the Key
133            result = Tspi_Context_UnregisterKey(hContext, TSS_PS_TYPE_SYSTEM,
134                                migratableSignUUID, &hKey);
135            if (result != TSS_SUCCESS)
136                 Error_Path();
137
138            // exit, discarding hKey
139       }
140
141

CONFORMING TO

143       Tspi_Context_RegisterKey  conforms to the Trusted Computing Group Soft‐
144       ware Specification version 1.1 Golden
145
146