Integration of SoftHSM2 with HW-Plugins

This page will explain the Architectural details of the Integration of SOFTHSM2 with the Hardware plugins (Examples: TPM Plugin, SGX Plugin and TrustZone Plugin etc..)

This page will explain the API Design of the same.

Above picture shows various blocks and interfaces of container that acts as CA for ONAP.

Existing code is shown in green boxes:

AT&T Supplied CA Service acts as proxy to External CA. AT&T supplied Internal CA Service (called develCA) acts on CSR locally and returns the signed certificate using local CA key. CA key is stored in clear in "Internal CA Service". To secure the CA key (While it is stored in file system as well as while it is being used), Internal CA service is being enhanced to take advantage of PKCS11 based HSMs (Hardware based security). "PKCS11 Enablement" logic makes the CA service to talk to external HSM for any private key operations.

Any PKCS11 based HSMs can be attached to the interface. Since PKCS11 is C API standard from OASIS, it is not described here.

SoftHSM is a project from opendnssec that provides some level of security for user keys. It exposes PKCS11 interface on north side. The type of security it provides may not be acceptable for some users. To improve security using HW facilities, SoftHSM (as part of this project) is being enhanced to talk to hardware security entities. "HWPluginInfra" is the logic being developed as part of CSM to plugin various hardware security mechanisms. "HW Plugin I/f" is C API interface to hook various hardware security modules into SoftHSM. As part of this project, we also intend to develop "TPM Plugin" which communicates with local TPM chip. TPM is programmed with the user keys and TPM Plugin uses keys programmed in TPM to realize private key operations.

In summary, CA key security can be realized as follows:

3rd party CA Service - Good if ONAP deployment user already has their own CA for issuing certificates.
3rd party HSM - Good if ONAP deployment user has HSMs, but not CA.
3rd Plugins/ TPM Plugin - Good if ONAP deployment user likes to take advantage of local HW facilities to secure the keys.

Following code block provides API interface between softHSM2 and hardware plugins (HW Plugin I/f)

#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

Bullseye coverage tool is used to measure the codes coverage: