Directory content for CCA, ICA, EP11, and Soft tokens

Changes from old to new data store format

In the old format, the multiple-byte-width data types were not serialized before stored to disk, so NVTOK_DAT could not be used on little endian (LE) and big endian (BE) platforms. The new format serializes those data types from host to BE byte order. The AES Key Wrap algorithm is used to wrap a token’s master key (MK) with the KEKs. The token’s master key is randomly generated at token initialization. In the old format, the master key was a 3DES CBC key. The KEK was a 2TDEA CBC key. CBC was used with a per token (fixed) initialization vector (IV). Integrity was intended to be provided by a SHA1 hash of the unencrypted key. The MK master key object had the following format:

struct MK {
    u8 MK [24];
    u8 sha1 [20];
    u8 padding[4];
};

It was wrapped by the SO KEK and stored to MK_SO and was also wrapped by the user KEK and stored to MK_USER. The new format defines the MK to be an AES-256 key. Its unencrypted format is just the 32 key bytes. Its encrypted format is a 40 byte key blob output by the AES Key Wrap algorithm (wrapped with the SO or user KEK). The file names MK_SO and MK_USER are unchanged.

The old format stored non-private token objects unencrypted in the following format:

struct OBJECT_PUB {
    u32 total_len;
    u8 private_flag;
    u8 object[object_len];
};

The new format is:

struct OBJECT_PUB {
    //--------------        <--+
    u32 tokversion;            | 16-byte header
    u8 private_flag;           |
    u8 reserved[7];            |
    u32 object_len;            |
    //--------------        <--+
    u8 object[object_len];     | body
    //--------------        <--+
};

The old format encrypted all private token objects under the MK. The unencrypted format was:

struct OBJECT_PRIV {
    u32 total_len;
    u8 private_flag;
    //--- enc ---
    u32 object_len;
    u8 object[object_len];
    u8 sha1[20];
    u8 padding[padding_len];
};

The new format features authenticated encryption via AES-256-GCM. To avoid initialization vector (IV) uniqueness , instead of using the MK to encrypt all token objects, the MK is used to wrap a per-object key using the AES Key Wrap algorithm. The wrapped per-object key is stored together with the IV and other meta-data as additional authenticated data (AAD) in the authenticated object header. The 16 byte GMAC tag is appended to the authenticated and encrypted object body which holds the private token object’s data:

struct OBJECT_PRIV {
    u32 total_len;
    //- auth -------        <--+
    u32 tokversion;            | 64-byte header
    u8 private_flag;           |
    u8 reserved[3];            |
    u8 key_wrapped[40];        |
    u8 iv[12];                 |
    u32 object_len;            |
    //- auth+enc ---        <--+
    u8 object[object_len];     | body
    //--------------        <--+
    u8 tag[16];                | 16-byte footer
    //--------------        <--+
};

In the old format, the multiple-byte-width data types were not serialized before stored to disk, so the token objects could not be moved between LE and BE platforms. The new format serializes all header and footer data from host to BE byte order, so all object data can always be encrypted and decrypted. However, the decrypted object data itself (body) must still be interpreted in host byte order.

So the new format should only be used with fresh setups. The new format can be used by specifying the new tokversion keyword in the token’s slot configuration in opencryptoki.conf. For a value of equal or grater 3.12 the new format is used.

Here is a table of all key material that is used per version 3.12 token: