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 /***
  99  * Load Key  Callback
 100  * Description: This callback function is called by SoftHSM HWPluginInfra
 101  * to load private keys into the HW using HW plugin.
 102  * Each HW plugin expects the keys to be specific to its HW.
 103  * Since SoftHSM HWPluginInfra is expected to be generic, the design
 104  * chosen is that HWPluginInfra reads key content from files and pass
 105  * that information to HW Plugins via this function pointer.
 106  * Yet times, Key information for HW Plugins is exposed as multiple files.
 107  * Hence, HWPluginInfra reads multiple files for each key.  Since, there
 108  * could be multiple keys, each set of files that correspond to one key
 109  * is expected to have same file name, but with different extensions. Since
 110  * the directory holding these file may also need to have other files
 111  * related to key, but for PKCS11, it is expected that all HWPlugin related
 112  * files should have its name start with HW.
 113  *
 114  * HWPluginInfra calls this callback function as many timne as number of
 115  * distinct keys.  For each distinct key, it reads the HW tagged files, loads
 116  * them into the buffer pointers and calls the HW Plugin -loadkey- function.
 117  * HWPluginInfra also stores the any returned buffers into the SoftHSM key
 118  * object.
 119  *
 120  * In case of TPM Plugin, it does following:
 121  *
 122  * -- Gets the buffers in in_info structure.
 123  *    --- Typically, there are two buffers in TPM understandable way
 124  *    - public & private key portion
 125  *    --- From global variables, it knows SRKHandle, SAPI context.
 126  *    --- Using Tss2_Sys_Load(), it loads the key.
 127  *
 128  * -- In both cases, it also expected to return KeyHandle, which is
 129  *    keyObjectHandle in case of TPM.
 130  *
 131  *
 132  ***/
 133
 134 /***
 135 typedef struct sshsm_hw_plugin_load_key_in_info_s {
 136     int num_buffers;
 137     buffer_info_t buffer_info[];
 138 }SSHSM_HW_PLUGIN_LOAD_KEY_IN_INFO_t;
 139 ***/
 140
 141
 142 typedef int (*sshsm_hw_plugin_load_key)(
 143            SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t *loadkey_in_info,
 144            void **keyHandle
 145         );
 146
 147 typedef int (*sshsm_hw_plugin_unload_key)(
 148            void **keyHandle
 149         );
 150
 151
 152
 153 /***
 154  * Callback:  RSA Sign Init
 155  * Description: This is called by HWPluginInfra as part of C_SignInit function
 156  * for RSA keys
 157  */
 158
 159 typedef int (*sshsm_hw_plugin_rsa_sign_init)(
 160          void *keyHandle,
 161          unsigned long mechanism,
 162          void *param,
 163          int len
 164         );
 165
 166
 167
 168 /***
 169  * Callback:  RSA Sign Init
 170  * Description: This is called by HWPluginInfra as part of C_Sign function
 171  * for RSA keys. HWPluginInfra get the keyHandle from the key object.
 172  *
 173  * In case of TPM plugin, it does following:
 174  * -- TSS2_Sys_Sing function is called.
 175  *
 176  *
 177  */
 178
 179 typedef int (*sshsm_hw_plugin_rsa_sign)(
 180          void *keyHandle,
 181          unsigned long mechanism,
 182          unsigned char *msg,
 183          int msg_len,
 184          unsigned char *outsig,
 185          int *outsiglen
 186         );
 187
 188 /***
 189  * Function Name: sshsm_hw_plugin_get_plugin_functions
 190  * Descrpiton:  Every HW plugin is expected to define this function.
 191  * This function is expected to return its function as pointers to the
 192  * caller.
 193  * SoftHSM calls this function after loading the hw plugin .SO file.
 194  * SoftHSM calls this function as part of C_initialize.
 195  * Arugments:
 196  *  Outputs: funcs
 197  *  Inputs: None
 198  *  Return value:  SUCCESS or FAILURE
 199  *
 200  ***/
 201
 202 typedef struct sshsm_hw_functions_s
 203 {
 204     sshsm_hw_plugin_init  xxx_init;
 205     sshsm_hw_plugin_uninit  xxx_uninit;
 206     sshsm_hw_plugin_activate xxx_activate;
 207     sshsm_hw_plugin_load_key xxx_load_key;
 208     sshsm_hw_plugin_unload_key xxx_unload_key;
 209     sshsm_hw_plugin_rsa_sign_init  xxx_rsa_sign_init;
 210     sshsm_hw_plugin_rsa_sign xxx_rsa_sign;
 211
 212 }SSHSM_HW_FUNCTIONS_t;
 213
 214
 215 int sshsm_hw_plugin_get_plugin_functions(SSHSM_HW_FUNCTIONS_t *funcs);
 216
 217
 218 #if defined(__cplusplus)
 219 }
 220 #endif
 221
 222 #endif
 223