FM Architecture
FM Support within the HSM Hardware
NOTE For Luna Network HSMs, the Client accesses application partitions via NTLS or STC connection, causing the registered application partitions to appear as slots in the lunacm slot list, just as if they were slots on Luna PCIe HSM cards installed locally in the LunaClient host computer.
>For local Luna PCIe HSMs, the HSM Admin (SO) partition (a.k.a. the HSM Admin "Token" in deference to Cryptoki terminology) also appears in the slot list and is directly accessible.
>Be aware that for Luna Network HSMs the HSM Admin partition (HSM Admin token) must be accessed over SSH via the appliance's Lunash administrative interface, and is not visible or accessible via the Client. Use hsm fm commands.
FMs allow application developers to design security sensitive program code that can be loaded into the HSM and operate as part of the HSM firmware. The Luna FM SDK package also provides application developers with APIs to develop applications on a host to interface to the HSM.
The FM may contain custom-designed functions that are in addition to the native command set of the HSM.
The following diagram shows the various components of the FM system, relevant to the host and HSM.
The 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 Luna FM SDK package.
The notation adopted to identify the data flows utilized in the diagram is
API (Function Type)
API refers to the API used to interface between the two components and function type indicates the type of function.
A more detailed discussion detailing the components and their interactions follows the diagram.
Custom Functions
The following figure details 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 is then responsible for implementing 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 Access Provider (ethsm library), via the Message Dispatch API.
In the HSM, the message request/response is processed via modules collectively referred to here as the Message Processing Modules. Any message request/response which contains a custom function is passed to the FM for processing. The custom function can access the native PKCS#11 function calls plus the extra commands specified in this document.
FM Support in Emulation Mode
At this stage no emulation mode is supported.
Multiple FMs
The Luna HSMs can support more than one FM loaded at the same time.
Concept
A developer will use more than one FM because each FM is implementing a different solution and operates with different applications.
Features
The total number of FMs that the HSM can hold depends on the storage limits. Each FM image is placed in a reserved area of persistent memory which has a fixed size. So the HSM can only hold as many FM images as will fit in this space. The current size of the FM store is 8 megabytes.
Each FM loaded into a HSM must have a unique ID number. The FM ID is an integer value that is set in the FM image through the use of the DEFINE_FM_HEADER macro.
The FMs behaviour is dependent on multiple factors:
>If a new FM is loaded with the same ID value as a FM already loaded then the new FM will replace the existing FM.
>If a new FM is loaded with a ID value different to any FM already loaded then the new FM is stored and all existing FMs are untouched.
The order in which the FM images are initialized is set by the FM ID values. The HSM will call the Startup() in the FMs starting with the lowest FM ID value and finishing with the highest ID number.
Memory for FMs
The Luna HSM provides the FM developer with several memory types to use.
- Fixed Read Only memory including executable – 8 MB
- SMFS persistent tamper protected memory – 4 MB
- Partition storage using Cryptoki function to manage objects on a partition
- RAM available with malloc() – about 100 MB
Message Handling
Custom commands are always directed to a particular FM identified by the unique FM ID.
The MD_SendReceive function on the host allows the caller to specify the HSM index and the FM ID values. The host side software and HSM FW will ensure that the message is sent to the correct FM
