TPM2-Plugin/lib/include/hwpluginif.h

/* 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