FM Architecture
This chapter describes the basic architecture of your FM SDK, and includes the following sections:
>FM Support within the HSM Hardware
FM Support within the HSM Hardware
FMs allow application developers to design security-sensitive program code, which is uploaded into the HSM and operates as part of the HSM firmware. The SafeNet ProtectToolkit FM SDK also provides application developers with APIs to develop applications on a host to interface to the HSM.
The FM may contain custom-designed functions which then access the Cryptoki library to perform cryptographic operations. Alternatively, the FM may contain functions that conform to the PKCS#11 standard and contain additional operations that are performed prior to passing the request to the Cryptoki library. The former are referred to as custom functions and the latter are referred to as patched PKCS#11 functions.
Starting with SafeNet ProtectToolkit version 5.4, you can upload multiple custom FMs to an HSM and use them simultaneously. Only one PKCS#11 patched FM can be loaded and used at a time. If a patched FM is already loaded, it is overwritten by the new FM. Refer to
The following diagrams show the various components of the FM system, relevant to the host and HSM:
>The components and interfaces in a system using Functionality Modules for Custom Functions
>The components and interfaces in a system using Functionality Modules for Patched Functions
The diagrams are presented this way for ease of illustration, and because FMs tend to be used in environments where either only custom functions or only PKCS#11 functions are utilized. However, there is no constraint that prevents a FM from containing a mixture of both custom and patched PKCS#11 functions.
Each figure marks the boundaries of the host system and the adapter in order to clarify where each component resides. The boxes represent components and the arrows represent the interaction or data flow between the components. Only the message request path is shown in the diagrams, as this method allows illustration of which component originates the interaction. The message response follows the same path but in the opposite direction and is not shown on the diagram. The names given to these interfaces are directly, or indirectly related to the libraries provided in the SafeNet ProtectToolkit FM SDK.
The data flows in the diagrams are depicted using the notation:
API (Function Type)
For example, in The components and interfaces in a system using Functionality Modules for Custom Functions, the arrow labeled MD (custom functions) indicates the flow of custom function request packages passed between components via the Message Dispatch (MD) API (refer to Message Dispatch API Reference for details). EPP (custom functions) refers to Custom function request packages passed from the host across the PCI bus (in the case of local HSMs) or across a TCP/IP link (in the case of remote HSMs), via an unpublished Gemalto-proprietary protocol.
Custom Functions
The components and interfaces in a system using Functionality Modules for Custom Functions depicts the components contained in the Host system and the HSM when using custom functions. The custom application is executed on the host system. A user-defined protocol specifying the message response and request packages for each function must be defined by the application developer. This protocol is used to access the FM’s custom functions. The host requests are transparently communicated directly to the FM module, which implements the protocol.
Figure 1: The components and interfaces in a system using Functionality Modules for Custom Functions
These message response and request packages are transferred between the application and the PCIe or Network HSM Access Provider, via the Message Dispatch (MD) API. The legacy FM Host API has been deprecated since Version 2.0 of ProtectProcessing Orange (legacy name of the FM SDK). As of FM SDK 5, the Host API functions are no longer supported nor maintained. Since the previous Host API library makes use of MD API to communicate with the HSM, existing binaries using the the old API should continue to function, but support will no longer be provided for developers not using the MD API.
The PCI driver provides the interface to the PCIe bus and is used in systems deploying local HSMs. The NetServer Driver provides the interface to the WAN/LAN network and is used in systems which deploy remote HSMs. It is not possible for a system to utilize remote and local HSMs at the same time. At configuration time, either the PCIe or Network HSM Access Provider is specified as appropriate to the installation (refer to the SafeNet HSM Access Provider Installation Guide for details).
In the HSM, the message request/response is processed via modules, collectively referred to here as the Message Processing Modules. Any message request/response containing a custom function is passed to the FM for processing. The custom function can access the cryptographic functionality provided in the firmware via PKCS#11 function calls. FM functions have access to any of the Serial, C Runtime and original PKCS#11 functions from HSM firmware.
PKCS#11 Patched Functions
Figure 2: The components and interfaces in a system using Functionality Modules for Patched Functions
FM Architecture depicts the components contained in the Host system and the HSM when using PKCS#11 functions. The custom application is executed on the host system. The application accesses patched PKCS#11 functions in the FM and the standard PKCS#11 functionality of the Cryptoki library provided in the firmware module via a standard PKCS#11 interface provided by the Cryptoki library on the host system.
The Message Processing Modules contain a list of patched PKCS#11 functions, to which the incoming function is compared. The Message Processing Modules call the PKCS#11 function from HSM firmware if the function isn’t patched or gives control to an FM version of same function if it is patched. FM implementations of patched functions can call any of the Serial, C Run Time and original PKCS#11 functions from the HSM firmware. The PKCS#11 functions called from within the FM call the firmware implementation directly, bypassing the Message Processing Modules.
An FM can implement both Custom functions and PKCS#11 patched functions simultaneously.
FM Support in Emulation Mode
In emulation mode, all components run on the host system. The diagram below shows the various components when the FM is executed in emulation mode.
Figure 3: The components of a system emulating Functionality Modules
The figure above depicts the components of the FM emulation system. The Functionality Module is combined into a DLL with emulation libraries to provide FM SDK features such as the Cprov function-patching and serial port access.
Applications that need to observe the effects of the FM, via PKCS#11 patching or custom functions, are run against emulation wrappers for cryptoki and ethsm. These wrapper libraries are built from source as part of the emulation FM build and result in dynamic libraries. This allows existing applications to run against the emulation FM.
The emulation wrapper libraries load the emulated FM, which loads the SafeNet ProtectToolkit Software Emulation Cryptoki library. Messages are routed by the emulation libraries the FM is linked against, as shown in the diagram above.
Emulation Mode Limitations
Supported Platforms
FM Emulation using the SafeNet ProtectToolkit FM SDK is supported on Windows and Linux.
Applications being run against an emulation FM must be run locally. NetServer cannot be used to allow remote applications to connect to the emulated FM and cryptoki wrapper.
Supported C APIs
Emulation mode uses the standard C library installed on the host. The SafeNet ProtectToolkit FM SDK is C99 compliant, extended to support the following non-standard APIs:
ctype.h
isascii, toascii
string.h
strdup, strsep
Any code written using these APIs will fail in emulation mode, unless you explicitly instruct your compiler to allow them. The example below illustrates how to allow these non-standard APIs in emulation mode using GCC.
If your emulation environment uses glibc, such as the standard gcc environment on Red Hat, you may define the following to enable these non-standard libc functions in emulation mode:
Note that we test for gcc, not glibc, because the compile time glibc flag is set in features.h, but OVERRIDE_GNU_SOURCE must be set before features.h is included.
NOTE Important: Since every GNU header includes features.h, you must put this at the top of any source files in which you wish to use the extended functions, or it will not be applied.
#if defined(EMUL) && defined (__GNUC__)
/*
* Define _GNU_SOURCE flag to enable non-standard API's that are supported in the FM LIBC
* but not necessarily by all EMUL environments:
* ctype.h: isascii, toascii
* string.h: strdup,strsep
*/
#define _GNU_SOURCE
#define EXTENDED_OK
#endif
Source Level Debugging
When debugging an emulation FM, you will be able to step through the application and into the message encoding function.
The emulation versions of the MD_Initialize and C_Initialize function call the FM’s Startup function. The Startup function will only be executed once.
The emulation version of the MD_SendReceive function calls the FM’s Dispatch entry function via the ethsm emulation layer.
However, when the message encoding function calls the MD_Initialize or MD_SendReceive functions you will not be able to step into these functions because no symbols or source code is supplied.
The best method to step through your FM code is to set a break point at the start of the Startup and Dispatch entry point functions.
Random Number Generator
The emulation Cryptoki library does not provide true random numbers. Although the FIPS 140-approved Pseudo Random Number Generator is implemented in the emulation version, there is insufficient entropy to make good quality random numbers.
Do not use the emulation to create production-grade keys.
Tampering the Secure Memory
The emulation Cryptoki library does not support the concept of a hardware tamper event.
You may delete the emulation Cryptoki data directory to simulate a total loss of secure memory. However you should only do this when the Cryptoki library is not running.
The emulation Cryptoki data directory default location is
Windows: c:\cryptoki
Linux: ~/.cryptoki/cryptoki
The emulation data directory can be changed via the ET_PTKC_SW_DATAPATH entry in the SafeNet ProtectToolkit configuration file. See the SafeNet ProtectToolkit-C Administration Guide for more information.
Cryptoki Function Patching
The emulation is capable of supporting Cryptoki function patching of any application run against the emulated cryptoki wrapper built with the emulated FM. Unlike Protect Processing 3.0 and earlier releases, applications do not have to be recompiled with the emulated libraries; they must have the emucprov and emumdapiwrapper libraries in the library search path ahead of the real Cryptoki library.
ETHSM
The timeout parameter of MD_SendReceive() is ignored in emulation mode.
Cryptoki FM Object
Due to the way the emulated FM is linked with the application and Cryptoki libraries, it does not appear as an object via cryptoki.
