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