Integration of SoftHSM2 with HW-Plugins

#ifndef __SSHSM_HW_PLUGIN_IF_H__
#define __SSHSM_HW_PLUGIN_IF_H__

#define MAX_ID_LENGTH (32)

typedef	struct buffer_info_s{
	   char id[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