SoftHSMv2/src/lib/HwInfra/hwpluginif.h

   1 /* Copyright 2018 Intel Corporation, Inc
   2 *
   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
   6 *
   7 *       http://www.apache.org/licenses/LICENSE-2.0
   8 *
   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.
  14 */
  15
  16 #ifndef __SSHSM_HW_PLUGIN_IF_H__
  17 #define __SSHSM_HW_PLUGIN_IF_H__
  18
  19
  20 #if defined(__cplusplus)
  21 extern "C" {
  22 #endif
  23
  24 #define MAX_ID_LENGTH (32)
  25
  26 typedef struct buffer_info_s{
  27        char id[MAX_ID_LENGTH+1];
  28        int length_of_buffer;
  29        unsigned char *buffer;
  30     }buffer_info_t;
  31
  32 /***
  33  * Init Callback
  34  * Description:
  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>
  44  * Parameters:
  45  *    Inputs: None
  46  *    OUtputs; None
  47  *    Returns :  SUCCESS (if HW is present), FAILURE if HW is not present
  48  *
  49  ***/
  50 typedef int (*sshsm_hw_plugin_init)();
  51
  52 /***
  53  * UnInit Callback
  54  * Description: This function is called by HWPluginInfra during C_Finalize().
  55  * This functin is gives chance for any cleanup by plugins.
  56  ***/
  57 typedef int (*sshsm_hw_plugin_uninit)();
  58
  59
  60 /***
  61  * Activate Callback
  62  * Description: This callback function is called by HWPluginInfra
  63  * (as part of C_Intialize)  to activate the
  64  * HW via HW plugin. SofHSM HWPluginInfra reads set of files required for
  65  * activation (from
  66  * activation directory) and passes them as buffers.
  67  * HWPluginInfra reads the file in 'activate directory'
  68  * as part of C_Initialize and passes the file content as is
  69  * to the activate callback function.
  70  * If there are two files, then num_buffers in in_info would be 2.
  71  * 'id' is name of the file (May not be used by TPM plugin)
  72  * 'length_of_buffer' is the valid length of the buffer.
  73  * 'buffer' contains the file content.
  74  * HWPluginInfra in SoftHSM allocates memory for this structure and internal
  75  * buffers and it frees them up after this function returns. Hence,
  76  * the plugin should not expect that these buffers are valid after the call
  77  * is returned.
  78  *
  79  * In case of TPM Plugin:
  80  *    It is expected that activate directory has a file with SRK Handle
  81  *    saved in it. Note that SRK is saved in TPM memory (persistence)
  82  *    Actiate function of TPM plugin is called with SRK handle.
  83  *
  84  ***/
  85 #define MAX_BUFFER_SEGMENTS 8
  86 typedef struct sshsm_hw_plugin_activate_in_info_s {
  87     int num_buffers;
  88     buffer_info_t *buffer_info[MAX_BUFFER_SEGMENTS];
  89 }SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t;
  90
  91
  92 typedef int (*sshsm_hw_plugin_activate)(
  93            SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t *activate_in_info
  94         );
  95
  96
  97 /***
  98  * Import Public Key
  99  * Description: This is called by HWPluginInfra after load key to get the public
 100  * key modulus and exponent.  Plugin to allocate memory for modulus and exponent
 101  * based on size. HwInfra will release the buffers after using them.
 102  */
 103
 104 typedef struct sshsm_hw_plugin_import_public_key_info_s {
 105     unsigned long modulus_size;
 106     unsigned char *modulus;
 107     unsigned long exponent_size;
 108     unsigned char *exponent;
 109 }SSHSM_HW_PLUGIN_IMPORT_PUBLIC_KEY_INFO_t;
 110
 111
 112 /***
 113  * Load Key  Callback
 114  * Description: This callback function is called by SoftHSM HWPluginInfra
 115  * to load private keys into the HW using HW plugin.
 116  * Each HW plugin expects the keys to be specific to its HW.
 117  * Since SoftHSM HWPluginInfra is expected to be generic, the design
 118  * chosen is that HWPluginInfra reads key content from files and pass
 119  * that information to HW Plugins via this function pointer.
 120  * Yet times, Key information for HW Plugins is exposed as multiple files.
 121  * Hence, HWPluginInfra reads multiple files for each key.  Since, there
 122  * could be multiple keys, each set of files that correspond to one key
 123  * is expected to have same file name, but with different extensions. Since
 124  * the directory holding these file may also need to have other files
 125  * related to key, but for PKCS11, it is expected that all HWPlugin related
 126  * files should have its name start with HW.
 127  *
 128  * HWPluginInfra calls this callback function as many timne as number of
 129  * distinct keys.  For each distinct key, it reads the HW tagged files, loads
 130  * them into the buffer pointers and calls the HW Plugin -loadkey- function.
 131  * HWPluginInfra also stores the any returned buffers into the SoftHSM key
 132  * object.
 133  *
 134  * In case of TPM Plugin, it does following:
 135  *
 136  * -- Gets the buffers in in_info structure.
 137  *    --- Typically, there are two buffers in TPM understandable way
 138  *    - public & private key portion
 139  *    --- From global variables, it knows SRKHandle, SAPI context.
 140  *    --- Using Tss2_Sys_Load(), it loads the key.
 141  *
 142  * -- In both cases, it also expected to return KeyHandle, which is
 143  *    keyObjectHandle in case of TPM.
 144  *
 145  *
 146  ***/
 147
 148 /***
 149 typedef struct sshsm_hw_plugin_load_key_in_info_s {
 150     int num_buffers;
 151     buffer_info_t buffer_info[];
 152 }SSHSM_HW_PLUGIN_LOAD_KEY_IN_INFO_t;
 153 ***/
 154
 155
 156 typedef int (*sshsm_hw_plugin_load_key)(
 157            SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t *loadkey_in_info,
 158            void **keyHandle,
 159            SSHSM_HW_PLUGIN_IMPORT_PUBLIC_KEY_INFO_t *import_public_key
 160         );
 161
 162 typedef int (*sshsm_hw_plugin_unload_key)(
 163            void **keyHandle
 164         );
 165 /***
 166  * Callback:  RSA Sign Init
 167  * Description: This is called by HWPluginInfra as part of C_SignInit function
 168  * for RSA keys.  Plugin can allocate memory for any state and can add its reference to
 169  * pluginOutDataRef. This pointer is passed to sign, signupdate and signfinal.
 170  */
 171
 172 typedef int (*sshsm_hw_plugin_rsa_sign_init)(
 173          void *keyHandle,
 174          unsigned long mechanism,
 175          void *param,
 176          int len,
 177          void **pluginOutDataRef
 178         );
 179
 180 /***
 181  * Callback:  RSA Sign
 182  * Description: This is called by HWPluginInfra as part of C_Sign function
 183  * for RSA keys. HWPluginInfra get the keyHandle from the key object.
 184  *
 185  * In case of TPM plugin, it does following:
 186  * -- TSS2_Sys_Sing function is called.
 187  *
 188  *
 189  */
 190
 191 typedef int (*sshsm_hw_plugin_rsa_sign)(
 192          void *keyHandle,
 193          unsigned long mechanism,
 194          unsigned char *msg,
 195          int msg_len,
 196          void *pluginDataRef,
 197          unsigned char *outsig,
 198          int *outsiglen
 199         );
 200
 201 typedef int (*sshsm_hw_plugin_rsa_sign_update)(
 202          void *keyHandle,
 203          unsigned long mechanism,
 204          unsigned char *msg,
 205          int msg_len,
 206          void *pluginDataRef
 207         );
 208
 209 typedef int (*sshsm_hw_plugin_rsa_sign_final)(
 210          void *keyHandle,
 211          unsigned long mechanism,
 212          void *pluginDataRef,
 213          unsigned char *outsig,
 214          int *outsiglen
 215         );
 216
 217 /** This function is called by SSHSM only if there sign_final function is not called.
 218 If sign_final function is called, it is assumed that plugin would have cleaned this up.
 219 ***/
 220
 221 typedef int (*sshsm_hw_plugin_rsa_sign_cleanup)(
 222          void *keyHandle,
 223          unsigned long mechanism,
 224          void *pluginDataRef
 225         );
 226
 227 /***
 228  * Function Name: sshsm_hw_plugin_get_plugin_functions
 229  * Descrpiton:  Every HW plugin is expected to define this function.
 230  * This function is expected to return its function as pointers to the
 231  * caller.
 232  * SoftHSM calls this function after loading the hw plugin .SO file.
 233  * SoftHSM calls this function as part of C_initialize.
 234  * Arugments:
 235  *  Outputs: funcs
 236  *  Inputs: None
 237  *  Return value:  SUCCESS or FAILURE
 238  *
 239  ***/
 240
 241 typedef struct sshsm_hw_functions_s
 242 {
 243     sshsm_hw_plugin_init  xxx_init;
 244     sshsm_hw_plugin_uninit  xxx_uninit;
 245     sshsm_hw_plugin_activate xxx_activate;
 246     sshsm_hw_plugin_load_key xxx_load_key;
 247     sshsm_hw_plugin_unload_key xxx_unload_key;
 248     sshsm_hw_plugin_rsa_sign_init  xxx_rsa_sign_init;
 249     sshsm_hw_plugin_rsa_sign xxx_rsa_sign;
 250     sshsm_hw_plugin_rsa_sign_update xxx_rsa_sign_update;
 251     sshsm_hw_plugin_rsa_sign_final xxx_rsa_sign_final;
 252     sshsm_hw_plugin_rsa_sign_cleanup xxx_rsa_sign_cleanup;
 253
 254 }SSHSM_HW_FUNCTIONS_t;
 255
 256
 257 int sshsm_hw_plugin_get_plugin_functions(SSHSM_HW_FUNCTIONS_t *funcs);
 258
 259
 260 #if defined(__cplusplus)
 261 }
 262 #endif
 263
 264 #endif
 265