aboutsummaryrefslogtreecommitdiffstats
path: root/TPM2-Plugin/lib/include/hwpluginif.h
diff options
context:
space:
mode:
Diffstat (limited to 'TPM2-Plugin/lib/include/hwpluginif.h')
-rw-r--r--TPM2-Plugin/lib/include/hwpluginif.h205
1 files changed, 205 insertions, 0 deletions
diff --git a/TPM2-Plugin/lib/include/hwpluginif.h b/TPM2-Plugin/lib/include/hwpluginif.h
new file mode 100644
index 0000000..57c5e07
--- /dev/null
+++ b/TPM2-Plugin/lib/include/hwpluginif.h
@@ -0,0 +1,205 @@
+/* Copyright 2018 Intel Corporation, Inc
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+#ifndef __SSHSM_HW_PLUGIN_IF_H__
+#define __SSHSM_HW_PLUGIN_IF_H__
+
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#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.
+ *
+ ***/
+
+#define MAX_BUFFER_SEGMENTS 8
+typedef struct sshsm_hw_plugin_activate_in_info_s {
+ int num_buffers;
+ buffer_info_t *buffer_info[MAX_BUFFER_SEGMENTS];
+}SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t;
+
+typedef int (*sshsm_hw_plugin_activate)(
+ SSHSM_HW_PLUGIN_ACTIVATE_LOAD_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 int (*sshsm_hw_plugin_load_key)(
+ SSHSM_HW_PLUGIN_ACTIVATE_LOAD_IN_INFO_t *loadkey_in_info,
+ void **keyHandle
+ );
+
+typedef int (*sshsm_hw_plugin_unload_key)(
+ 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 long mechanism,
+ 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_unload_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);
+
+#if defined(__cplusplus)
+}
+#endif
+
+#endif
+