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         );
 135
 136 typedef int (*sshsm_hw_plugin_unload_key)(
 137            void **keyHandle
 138         );
 139
 140 /***
 141  * Callback:  RSA Sign Init
 142  * Description: This is called by HWPluginInfra as part of C_SignInit function
 143  * for RSA keys
 144  */
 145
 146 typedef int (*sshsm_hw_plugin_rsa_sign_init)(
 147          void *keyHandle,
 148          unsigned long mechanism,
 149          void *param,
 150          int len
 151         );
 152
 153 /***
 154  * Callback:  RSA Sign Init
 155  * Description: This is called by HWPluginInfra as part of C_Sign function
 156  * for RSA keys. HWPluginInfra get the keyHandle from the key object.
 157  *
 158  * In case of TPM plugin, it does following:
 159  * -- TSS2_Sys_Sing function is called.
 160  *
 161  *
 162  */
 163
 164 typedef int (*sshsm_hw_plugin_rsa_sign)(
 165          void *keyHandle,
 166          unsigned long mechanism,
 167          unsigned char *msg,
 168          int msg_len,
 169          unsigned char *outsig,
 170          int *outsiglen
 171         );
 172
 173 /***
 174  * Function Name: sshsm_hw_plugin_get_plugin_functions
 175  * Descrpiton:  Every HW plugin is expected to define this function.
 176  * This function is expected to return its function as pointers to the
 177  * caller.
 178  * SoftHSM calls this function after loading the hw plugin .SO file.
 179  * SoftHSM calls this function as part of C_initialize.
 180  * Arugments:
 181  *  Outputs: funcs
 182  *  Inputs: None
 183  *  Return value:  SUCCESS or FAILURE
 184  *
 185  ***/
 186
 187 typedef struct sshsm_hw_functions_s
 188 {
 189     sshsm_hw_plugin_init  xxx_init;
 190     sshsm_hw_plugin_uninit  xxx_uninit;
 191     sshsm_hw_plugin_activate xxx_activate;
 192     sshsm_hw_plugin_load_key xxx_load_key;
 193     sshsm_hw_plugin_unload_key xxx_unload_key;
 194     sshsm_hw_plugin_rsa_sign_init  xxx_rsa_sign_init;
 195     sshsm_hw_plugin_rsa_sign xxx_rsa_sign;
 196 }SSHSM_HW_FUNCTIONS_t;
 197
 198 int sshsm_hw_plugin_get_plugin_functions(SSHSM_HW_FUNCTIONS_t *funcs);
 199
 200 #if defined(__cplusplus)
 201 }
 202 #endif
 203
 204 #endif
 205