...
| Code Block |
|---|
#ifndef __SSHSM_HW_PLUGIN_IF_H__
#define __SSHSM_HW_PLUGIN_IF_H__
#define MAX_ID_LENGTH (32)
typedef struct buffer_info_s{
char *did[MAX_ID_LENGTH+1];
int length_of_buffer;
unsigned char *buffer;
}buffer_info_t;
/***
* Init Callback
* Description:
* This function is called by HWPluginInfra as part of C_Initialize to figure
* out whether there is any correspnding HW is present to use this plugin.
* In case of TPM2.0 Plugin,
* it is expected that this function checks
* whether the TPM2.0 is present or not, by checking the capabilities
* using Tss2_Sys_GetCapability with TPM_CAP_TPM_PROPERTIES and
* TPM_PT_MANUFACTURER property. If this function returns SUCCESS,
* TPM plguin can assume that TPM2.0 is presenta nd return success
* In case of SGX Plugin: <To be filled>
* Parameters:
* Inputs: None
* OUtputs; None
* Returns : SUCCESS (if HW is present), FAILURE if HW is not present
*
***/
typedef int (*sshsm_hw_plugin_init)();
/***
* UnInit Callback
* Description: This function is called by HWPluginInfra during C_Finalize().
* This functin is gives chance for any cleanup by plugins.
***/
typedef int (*sshsm_hw_plugin_uninit)();
/***
* Activate Callback
* Description: This callback function is called by HWPluginInfra
* (as part of C_Intialize) to activate the
* HW via HW plugin. SofHSM HWPluginInfra reads set of files required for
* activation (from
* activation directory) and passes them as buffers.
* HWPluginInfra reads the file in 'activate directory'
* as part of C_Initialize and passes the file content as is
* to the activate callback function.
* If there are two files, then num_buffers in in_info would be 2.
* 'id' is name of the file (May not be used by TPM plugin)
* 'length_of_buffer' is the valid length of the buffer.
* 'buffer' contains the file content.
* HWPluginInfra in SoftHSM allocates memory for this structure and internal
* buffers and it frees them up after this function returns. Hence,
* the plugin should not expect that these buffers are valid after the call
* is returned.
*
* In case of TPM Plugin:
* It is expected that activate directory has a file with SRK Handle
* saved in it. Note that SRK is saved in TPM memory (persistence)
* Actiate function of TPM plugin is called with SRK handle.
*
***/
typedef struct sshsm_hw_plugin_activate_in_info_s {
int num_buffers;
buffer_info_t buffer_info[];
}SSHSM_HW_PLUGIN_ACTIVATE_IN_INFO_t;
typedef int (*sshsm_hw_plugin_activate)(
SSHSM_HW_PLUGIN_ACTIVATE_IN_INFO_t *activate_in_info;
);
/***
* Load Key Callback
* Description: This callback function is called by SoftHSM HWPluginInfra
* to load private keys into the HW using HW plugin.
* Each HW plugin expects the keys to be specific to its HW.
* Since SoftHSM HWPluginInfra is expected to be generic, the design
* chosen is that HWPluginInfra reads key content from files and pass
* that information to HW Plugins via this function pointer.
* Yet times, Key information for HW Plugins is exposed as multiple files.
* Hence, HWPluginInfra reads multiple files for each key. Since, there
* could be multiple keys, each set of files that correspond to one key
* is expected to have same file name, but with different extensions. Since
* the directory holding these file may also need to have other files
* related to key, but for PKCS11, it is expected that all HWPlugin related
* files should have its name start with HW.
*
* HWPluginInfra calls this callback function as many timne as number of
* distinct keys. For each distinct key, it reads the HW tagged files, loads
* them into the buffer pointers and calls the HW Plugin -loadkey- function.
* HWPluginInfra also stores the any returned buffers into the SoftHSM key
* object.
*
* In case of TPM Plugin, it does following:
*
* -- Gets the buffers in in_info structure.
* --- Typically, there are two buffers in TPM understandable way
* - public & private key portion
* --- From global variables, it knows SRKHandle, SAPI context.
* --- Using Tss2_Sys_Load(), it loads the key.
*
* -- In both cases, it also expected to return KeyHandle, which is
* keyObjectHandle in case of TPM.
*
*
***/
typedef struct sshsm_hw_plugin_load_key_in_info_s {
int num_buffers;
buffer_info_t buffer_info[];
}SSHSM_HW_PLUGIN_LOAD_KEY_IN_INFO_t;
typedef int (*sshsm_hw_plugin_load_key)(
SSHSM_HW_PLUGIN_LOAD_KEY_IN_INFO_t *loadkey_in_info;
void **keyHandle;
);
/***
* Callback: RSA Sign Init
* Description: This is called by HWPluginInfra as part of C_SignInit function
* for RSA keys
*/
typedef int (*sshsm_hw_plugin_rsa_sign_init)(
void *keyHandle;
unsigned long mechanism;
void *param;
int len;
);
/***
* Callback: RSA Sign Init
* Description: This is called by HWPluginInfra as part of C_Sign function
* for RSA keys. HWPluginInfra get the keyHandle from the key object.
*
* In case of TPM plugin, it does following:
* -- TSS2_Sys_Sing function is called.
*
*
*/
typedef int (*sshsm_hw_plugin_rsa_sign)(
void *keyHandle;
unsigned char *msg;
int msg_len;
unsigned char *outsig;
int *outsiglen;
);
/***
* Function Name: sshsm_hw_plugin_get_plugin_functions
* Descrpiton: Every HW plugin is expected to define this function.
* This function is expected to return its function as pointers to the
* caller.
* SoftHSM calls this function after loading the hw plugin .SO file.
* SoftHSM calls this function as part of C_initialize.
* Arugments:
* Outputs: funcs
* Inputs: None
* Return value: SUCCESS or FAILURE
*
***/
typedef struct sshsm_hw_functions_s
{
sshsm_hw_plugin_init xxx_init;
sshsm_hw_plugin_uninit xxx_uninit;
sshsm_hw_plugin_activate xxx_activate;
sshsm_hw_plugin_load_key xxx_load_key;
sshsm_hw_plugin_load_key xxx_unload_key;
sshsm_hw_plugin_rsa_sign_init xxx_rsa_sign_init;
sshsm_hw_plugin_rsa_sign xxx_rsa_sign;
}SSHSM_HW_FUNCTIONS_t;
int sshsm_hw_plugin_get_plugin_functions(SSHSM_HW_FUNCTIONS_t *funcs);
#endif
|
...