Initial work | Utimaco Integration Guides

When setting up the command interface for use by an `\_ext_` method, the designer will probably start with an idea of what information they need, at a high level. This might be some flags or behavior selection values (passed as an unsigned int with known values), or a hash value, passed as a fixed length byte buffer, or data for encryption or decryption, and/or one or more keys or key handles -- each of which is usually data with no common size from one call to the next.

These data 'fields' will be arranged within a C struct using a format suitable for parsing by `cmds_scanf()`. The `cmds_scanf()` behavior expects unsigned integers, fixed-length and variable-length fields, bit fields, etc.

Here is a complicated input structure, that describes serialized input that contains a flag, a CXI key (by reference or as a blob), a hash value, and some additional data:

A complicated example C Struct

struct { // Command struct for sfc 0

unsigned int flags; // u1

unsigned int mech; // u4

unsigned char * keyName; // c32

unsigned char * keyGroup; // c32

unsigned int spec; // u4

unsigned int l_blob; // v2 (length)

unsigned char * p_blob; // (data)

unsigned int l_hash; // v1 (length)

unsigned char * p_hash; // (data)

unsigned int l_data; // * (length)

unsigned char * p_data; // (data)

} cmd;

The above struct is a programming aid, helpful in parsing what will be received, and processed. When the host application has the above data, it is in whatever form is normal for the host platform. It might be stack variables, a C struct, or a Java class, but on receipt, the CryptoServer implementation is not passed the above data as maintained on the host, rather it is sent as a stream of raw bytes, after serialization by the host application.

There is no standardized method for doing this serialization, however. Macros are provided that will write values to the serialization buffer (the various load_int/store_int macros in each of the APIs). These macros are shortcuts, not automation, and are provided mainly to relieve the necessity of worrying about endianness when building the modules and targeting different platforms (the simulator, vs the hardware). Byte buffer copying is done using the OS- or Language-native methods for copying arrays of bytes, possibly with a prepended length value inserted into the byte stream as a single byte, a short or an integer.

The information available when an SFC is triggered is a char * (p_cmd), which points at the raw bytes of the serialized data, and an unsigned integer (l_cmd), which gives the number of bytes pointed to by p_cmd.

The next section describes `cmds_scanf()`, and how it is used to populate the `cmd` struct with information from, or about, the bytes pointed to by p_cmd.