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