The CryptoScript SDK is based on a variant of the Lua scripting language. Your custom code will run sandboxed; only certain access is granted by the sandbox, and there is no arbitrary access of the outside context.
The primary usecase for CryptoScript is performance enhancement.
Whether they are Utimaco standard modules, or SDK-derived custom firmware modules, each module is identified by a module name and ID (mID).
Module IDs from 0x000 to 0x0FF are reserved for Utimaco use. Module IDs from 0x100 to 0x17F are available for SDK user use.
A module is limited to 256 SFC methods.
The maximum communications buffer length is 256 Kilobytes, including overhead.
If you have to send more than 256 Kilobytes of data to a custom firmware module, you will need to develop a protocol for doing so (either store it, or process it inline and return 'state' that allows you to pick up where you left off).
The file size limit for Se Gen2 is 8Mb. The file size limit for Se, and CSe is 4Mb. The row length limit for the database module is 24Kb. In all these cases, assume "less overhead".
The example module shipped with the full SDK is 'exmp', it's mID is 0x100. The exmp module supplies 15-20 different example 'Sub-function' methods for reference purposes, as well as a c++ host application that exercises them.
Collectively referred to as a module's sub-function codes (SFCs), the SFCs represent the external interface of a custom module.
A module may provide up to three different type of methods (described below). For convenience, and depending on the mix of these method types, a module may be referred to as an external interface module, or as a utility module, however there is nothing stopping a utility module from having an external interface, or an external interface module from providing utility methods to other modules.
A module with an external interface provides mID+SFC access to one or more methods. The host application uses one of the APIs to "exec" the SFC, by providing a correctly structured byte buffer. "Correctly structured" here depends on what the SFC is expecting, and will be probably be different for every SFC.
A utility module provides access to its public methods via a 'shared object' paradigm. A utility module does not necessarily provide an external interface, rather its focus is on providing a public interface to its methods. Public interfaces are accessable from other modules, but not from a host application.
All modules will have an internal interface, but this interface is only visible to and used within the compiled module.
An external interface module may also provide public methods, indeed it may simply be providing an external interface to its own public methods, or even to some other modules' public methods! For an example of an external interface module that simply provides access to other modules' public methods, see <install>\SDK\doc\mdl_CXI.pdf.
Every SFC will have what amounts to a unique input or output structure (these are not, however, method signatures as understood at the function or method level.) You might refer to these as interface patterns.
The Utimaco host libraries pass byte-buffers between the host application and the mID+SFC external method. This can be demonstrated using the csadm 'cmd' command:
'csadm cmd=0x83,1,'abc''
The above csadm command will send the byte buffer `+[0x61 || 0x62 || 0x63]+` to module ID 0x083 (module 'cmds'), sub-function 1 ('reverse echo').
Example csadm 'cmd' call
|
|
At the enterprise level, the technical term for this type of behavior is Remote Procedure Call ('RPC') and this is generally provided using some form of middleware. RPC is generally implemented for parallel or distributed applications. Additionally, it is usually found in the medium or large scale, enterprise-level application space. RPC middleware packages also tend to add a lot of processing and bandwidth requirements, as they will provide for different quality of service, different platform support, etc. They are traditionally designed for support in "big iron" environments.
Because of the bandwidth and processing requirements, or 'footprint' of an RPC, Utimaco does not support any of the standard tools or middleware for RPC (CORBA, SOAP, RESTful, OMG-DDS, etc), as they add too much of a bandwidth requirement, or the HSMs embedded environment fails to provide the necessary prerequisites. A full-blown RPC also is not generally targeting embedded systems and their limited throughput. This, more than anything, is probably the reason that communication with modules on the HSMs relies on the simplest byte-buffer command/response protocol.
Utimaco provides low-level libraries that handle the passing of secure data between the host and the HSM, but these libraries are only interested in the data at a protocol (secure messaging) and physical (PCIe, Ethernet) levels. The libraries themselves treat the data being passed as opaque. This means that your host application is responsible for format, and formatting, of the underlying data being passed.
When you target a Utimaco-provided SFC, within a Utimaco-provided module, using a Utimaco-provided cryptosystem implementation (ie, like CXI or PKCS#11), the libraries _do_ provide a higher level API method. These higher-level methods are called with simple parameters, and the method will reformat those parameters into the specific, byte-oriented stream that the target SFC will be able to consume.
In the APIs, the requirement for a "correctly structured byte stream" is abstracted away from the host application.
When writing custom firmware, no such API exists, and must be designed and written at the same time as the firmware itself. The supplied DLLs provide methods to send and receive the byte buffers, but are not aware of how the buffers are structured, or what they contain.