1 /* Copyright 2018 Intel Corporation, Inc
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
7 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
16 #ifndef __SSHSM_HW_PLUGIN_IF_H__
17 #define __SSHSM_HW_PLUGIN_IF_H__
20 #if defined(__cplusplus)
24 #define MAX_ID_LENGTH (32)
26 typedef struct buffer_info_s{
27 char id[MAX_ID_LENGTH+1];
29 unsigned char *buffer;
35 * This function is called by HWPluginInfra as part of C_Initialize to figure
36 * out whether there is any correspnding HW is present to use this plugin.
37 * In case of TPM2.0 Plugin,
38 * it is expected that this function checks
39 * whether the TPM2.0 is present or not, by checking the capabilities
40 * using Tss2_Sys_GetCapability with TPM_CAP_TPM_PROPERTIES and
41 * TPM_PT_MANUFACTURER property. If this function returns SUCCESS,
42 * TPM plguin can assume that TPM2.0 is presenta nd return success
43 * In case of SGX Plugin: <To be filled>
47 * Returns : SUCCESS (if HW is present), FAILURE if HW is not present
50 typedef int (*sshsm_hw_plugin_init)();
54 * Description: This function is called by HWPluginInfra during C_Finalize().
55 * This functin is gives chance for any cleanup by plugins.
57 typedef int (*sshsm_hw_plugin_uninit)();
61 * Description: This callback function is called by HWPluginInfra
62 * (as part of C_Intialize) to activate the
63 * HW via HW plugin. SofHSM HWPluginInfra reads set of files required for
65 * activation directory) and passes them as buffers.
66 * HWPluginInfra reads the file in 'activate directory'
67 * as part of C_Initialize and passes the file content as is
68 * to the activate callback function.
69 * If there are two files, then num_buffers in in_info would be 2.
70 * 'id' is name of the file (May not be used by TPM plugin)
71 * 'length_of_buffer' is the valid length of the buffer.
72 * 'buffer' contains the file content.
73 * HWPluginInfra in SoftHSM allocates memory for this structure and internal
74 * buffers and it frees them up after this function returns. Hence,
75 * the plugin should not expect that these buffers are valid after the call
78 * In case of TPM Plugin:
79 * It is expected that activate directory has a file with SRK Handle
80 * saved in it. Note that SRK is saved in TPM memory (persistence)
81 * Actiate function of TPM plugin is called with SRK handle.
85 #define MAX_BUFFER_SEGMENTS 8
86 typedef struct sshsm_hw_plugin_activate_in_info_s {
88 buffer_info_t *buffer_info[MAX_BUFFER_SEGMENTS];
89 }SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t;
91 typedef struct sshsm_hw_plugin_import_public_key_info_s {
92 unsigned long modulus_size;
93 unsigned char *modulus;
94 unsigned long exponent_size;
95 //unsigned char *exponent;
96 unsigned int *exponent;
97 }SSHSM_HW_PLUGIN_IMPORT_PUBLIC_KEY_INFO_t;
99 typedef int (*sshsm_hw_plugin_activate)(
100 SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t *activate_in_info
105 * Description: This callback function is called by SoftHSM HWPluginInfra
106 * to load private keys into the HW using HW plugin.
107 * Each HW plugin expects the keys to be specific to its HW.
108 * Since SoftHSM HWPluginInfra is expected to be generic, the design
109 * chosen is that HWPluginInfra reads key content from files and pass
110 * that information to HW Plugins via this function pointer.
111 * Yet times, Key information for HW Plugins is exposed as multiple files.
112 * Hence, HWPluginInfra reads multiple files for each key. Since, there
113 * could be multiple keys, each set of files that correspond to one key
114 * is expected to have same file name, but with different extensions. Since
115 * the directory holding these file may also need to have other files
116 * related to key, but for PKCS11, it is expected that all HWPlugin related
117 * files should have its name start with HW.
119 * HWPluginInfra calls this callback function as many timne as number of
120 * distinct keys. For each distinct key, it reads the HW tagged files, loads
121 * them into the buffer pointers and calls the HW Plugin -loadkey- function.
122 * HWPluginInfra also stores the any returned buffers into the SoftHSM key
125 * In case of TPM Plugin, it does following:
127 * -- Gets the buffers in in_info structure.
128 * --- Typically, there are two buffers in TPM understandable way
129 * - public & private key portion
130 * --- From global variables, it knows SRKHandle, SAPI context.
131 * --- Using Tss2_Sys_Load(), it loads the key.
133 * -- In both cases, it also expected to return KeyHandle, which is
134 * keyObjectHandle in case of TPM.
139 typedef int (*sshsm_hw_plugin_load_key)(
140 SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t *loadkey_in_info,
142 SSHSM_HW_PLUGIN_IMPORT_PUBLIC_KEY_INFO_t *importkey_info
145 typedef int (*sshsm_hw_plugin_unload_key)(
150 * Callback: RSA Sign Init
151 * Description: This is called by HWPluginInfra as part of C_SignInit function
155 typedef int (*sshsm_hw_plugin_rsa_sign_init)(
157 unsigned long mechanism,
160 void **plugin_data_ref
164 * Callback: RSA Sign Init
165 * Description: This is called by HWPluginInfra as part of C_Sign function
166 * for RSA keys. HWPluginInfra get the keyHandle from the key object.
168 * In case of TPM plugin, it does following:
169 * -- TSS2_Sys_Sing function is called.
174 typedef int (*sshsm_hw_plugin_rsa_sign)(
176 unsigned long mechanism,
179 void *plugin_data_ref,
180 unsigned char *outsig,
184 typedef int (*sshsm_hw_plugin_rsa_sign_update)(
186 unsigned long mechnaism,
189 void *plugin_data_ref
192 typedef int (*sshsm_hw_plugin_rsa_sign_final)(
194 unsigned long mechnaism,
195 void *plugin_data_ref,
196 unsigned char *outsig,
200 /** This function is called by SSHSM only if there sign_final function is not called.
201 If sign_final function is called, it is assumed that plugin would have cleaned this up.
204 typedef int (*sshsm_hw_plugin_rsa_sign_cleanup)(
206 unsigned long mechnaism,
207 void *plugin_data_ref
211 * Function Name: sshsm_hw_plugin_get_plugin_functions
212 * Descrpiton: Every HW plugin is expected to define this function.
213 * This function is expected to return its function as pointers to the
215 * SoftHSM calls this function after loading the hw plugin .SO file.
216 * SoftHSM calls this function as part of C_initialize.
220 * Return value: SUCCESS or FAILURE
224 typedef struct sshsm_hw_functions_s
226 sshsm_hw_plugin_init xxx_init;
227 sshsm_hw_plugin_uninit xxx_uninit;
228 sshsm_hw_plugin_activate xxx_activate;
229 sshsm_hw_plugin_load_key xxx_load_key;
230 sshsm_hw_plugin_unload_key xxx_unload_key;
231 sshsm_hw_plugin_rsa_sign_init xxx_rsa_sign_init;
232 sshsm_hw_plugin_rsa_sign xxx_rsa_sign;
233 sshsm_hw_plugin_rsa_sign_update xxx_rsa_sign_update;
234 sshsm_hw_plugin_rsa_sign_final xxx_rsa_sign_final;
235 sshsm_hw_plugin_rsa_sign_cleanup xxx_rsa_sign_cleanup;
236 }SSHSM_HW_FUNCTIONS_t;
238 int sshsm_hw_plugin_get_plugin_functions(SSHSM_HW_FUNCTIONS_t *funcs);
240 #if defined(__cplusplus)