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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
/* Copyright 2018 Intel Corporation, Inc
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __SSHSM_HW_PLUGIN_IF_H__
#define __SSHSM_HW_PLUGIN_IF_H__
#if defined(__cplusplus)
extern "C" {
#endif
#define MAX_ID_LENGTH (32)
typedef struct buffer_info_s{
char id[MAX_ID_LENGTH+1];
int length_of_buffer;
unsigned char *buffer;
}buffer_info_t;
/***
* Init Callback
* Description:
* This function is called by HWPluginInfra as part of C_Initialize to figure
* out whether there is any correspnding HW is present to use this plugin.
* In case of TPM2.0 Plugin,
* it is expected that this function checks
* whether the TPM2.0 is present or not, by checking the capabilities
* using Tss2_Sys_GetCapability with TPM_CAP_TPM_PROPERTIES and
* TPM_PT_MANUFACTURER property. If this function returns SUCCESS,
* TPM plguin can assume that TPM2.0 is presenta nd return success
* In case of SGX Plugin: <To be filled>
* Parameters:
* Inputs: None
* OUtputs; None
* Returns : SUCCESS (if HW is present), FAILURE if HW is not present
*
***/
typedef int (*sshsm_hw_plugin_init)();
/***
* UnInit Callback
* Description: This function is called by HWPluginInfra during C_Finalize().
* This functin is gives chance for any cleanup by plugins.
***/
typedef int (*sshsm_hw_plugin_uninit)();
/***
* Activate Callback
* Description: This callback function is called by HWPluginInfra
* (as part of C_Intialize) to activate the
* HW via HW plugin. SofHSM HWPluginInfra reads set of files required for
* activation (from
* activation directory) and passes them as buffers.
* HWPluginInfra reads the file in 'activate directory'
* as part of C_Initialize and passes the file content as is
* to the activate callback function.
* If there are two files, then num_buffers in in_info would be 2.
* 'id' is name of the file (May not be used by TPM plugin)
* 'length_of_buffer' is the valid length of the buffer.
* 'buffer' contains the file content.
* HWPluginInfra in SoftHSM allocates memory for this structure and internal
* buffers and it frees them up after this function returns. Hence,
* the plugin should not expect that these buffers are valid after the call
* is returned.
*
* In case of TPM Plugin:
* It is expected that activate directory has a file with SRK Handle
* saved in it. Note that SRK is saved in TPM memory (persistence)
* Actiate function of TPM plugin is called with SRK handle.
*
***/
#define MAX_BUFFER_SEGMENTS 8
typedef struct sshsm_hw_plugin_activate_in_info_s {
int num_buffers;
buffer_info_t *buffer_info[MAX_BUFFER_SEGMENTS];
}SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t;
typedef int (*sshsm_hw_plugin_activate)(
SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t *activate_in_info
);
/***
* Load Key Callback
* Description: This callback function is called by SoftHSM HWPluginInfra
* to load private keys into the HW using HW plugin.
* Each HW plugin expects the keys to be specific to its HW.
* Since SoftHSM HWPluginInfra is expected to be generic, the design
* chosen is that HWPluginInfra reads key content from files and pass
* that information to HW Plugins via this function pointer.
* Yet times, Key information for HW Plugins is exposed as multiple files.
* Hence, HWPluginInfra reads multiple files for each key. Since, there
* could be multiple keys, each set of files that correspond to one key
* is expected to have same file name, but with different extensions. Since
* the directory holding these file may also need to have other files
* related to key, but for PKCS11, it is expected that all HWPlugin related
* files should have its name start with HW.
*
* HWPluginInfra calls this callback function as many timne as number of
* distinct keys. For each distinct key, it reads the HW tagged files, loads
* them into the buffer pointers and calls the HW Plugin -loadkey- function.
* HWPluginInfra also stores the any returned buffers into the SoftHSM key
* object.
*
* In case of TPM Plugin, it does following:
*
* -- Gets the buffers in in_info structure.
* --- Typically, there are two buffers in TPM understandable way
* - public & private key portion
* --- From global variables, it knows SRKHandle, SAPI context.
* --- Using Tss2_Sys_Load(), it loads the key.
*
* -- In both cases, it also expected to return KeyHandle, which is
* keyObjectHandle in case of TPM.
*
*
***/
typedef int (*sshsm_hw_plugin_load_key)(
SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t *loadkey_in_info,
void **keyHandle,
SSHSM_HW_PLUGIN_IMPORT_PUBLIC_KEY_INFO_t *importkey_info
);
typedef int (*sshsm_hw_plugin_unload_key)(
void **keyHandle
);
/***
* Callback: RSA Sign Init
* Description: This is called by HWPluginInfra as part of C_SignInit function
* for RSA keys
*/
typedef int (*sshsm_hw_plugin_rsa_sign_init)(
void *keyHandle,
unsigned long mechanism,
void *param,
int len,
void **plugin_data_ref
);
/***
* Callback: RSA Sign Init
* Description: This is called by HWPluginInfra as part of C_Sign function
* for RSA keys. HWPluginInfra get the keyHandle from the key object.
*
* In case of TPM plugin, it does following:
* -- TSS2_Sys_Sing function is called.
*
*
*/
typedef int (*sshsm_hw_plugin_rsa_sign)(
void *keyHandle,
unsigned long mechanism,
unsigned char *msg,
int msg_len,
void *plugin_data_ref,
unsigned char *outsig,
int *outsiglen
);
typedef int (*sshsm_hw_plugin_rsa_sign_update)(
void *keyHandle,
unsigned long mechnaism,
unsigned char *msg,
int msg_len,
void *plugin_data_ref
);
typedef int (*sshsm_hw_plugin_rsa_sign_final)(
void *keyHandle,
unsigned long mechnaism,
void *plugin_data_ref,
unsigned char *outsig,
int *outsiglen
);
/** This function is called by SSHSM only if there sign_final function is not called.
If sign_final function is called, it is assumed that plugin would have cleaned this up.
***/
typedef int (*sshsm_hw_plugin_rsa_sign_cleanup)(
void *keyHandle,
unsigned long mechnaism,
void *plugin_data_ref
);
/***
* Function Name: sshsm_hw_plugin_get_plugin_functions
* Descrpiton: Every HW plugin is expected to define this function.
* This function is expected to return its function as pointers to the
* caller.
* SoftHSM calls this function after loading the hw plugin .SO file.
* SoftHSM calls this function as part of C_initialize.
* Arugments:
* Outputs: funcs
* Inputs: None
* Return value: SUCCESS or FAILURE
*
***/
typedef struct sshsm_hw_functions_s
{
sshsm_hw_plugin_init xxx_init;
sshsm_hw_plugin_uninit xxx_uninit;
sshsm_hw_plugin_activate xxx_activate;
sshsm_hw_plugin_load_key xxx_load_key;
sshsm_hw_plugin_unload_key xxx_unload_key;
sshsm_hw_plugin_rsa_sign_init xxx_rsa_sign_init;
sshsm_hw_plugin_rsa_sign xxx_rsa_sign;
sshsm_hw_plugin_rsa_sign_update xxx_rsa_sign_update;
sshsm_hw_plugin_rsa_sign_final xxx_rsa_sign_final;
sshsm_hw_plugin_rsa_sign_cleanup xxx_rsa_sign_cleanup;
}SSHSM_HW_FUNCTIONS_t;
int sshsm_hw_plugin_get_plugin_functions(SSHSM_HW_FUNCTIONS_t *funcs);
#if defined(__cplusplus)
}
#endif
#endif
|
