Secure External Scalable Key Storage Extensions

Two forms of authorization are supported: no authorization, and M-of-N passwords. Note that the password form of authorization does not cryptographically protect the key material, it consists of a comparison between the N encrypted values stored in the header versus M plain-text passwords specified upon insertion. The form of authorization data will continue to be identified using the following definitions.

typedef CK_ULONG CKA_SIM_AUTH_FORM;

#define CKA_SIM_NO_AUTHORIZATION 0  // no authorization needed

#define CKA_SIM_PASSWORD         1  // plain-text passwords

When 0 is chosen for authForm, the pulAuthSecretSizes and ppbAuthSecretList PTRs are both NULL, so no passwords are required.

When 1 is chosen for authForm, then pulAuthSecretSizes is an array of string lengths for each plain-text string password in the array of strings pointed to by ppbAuthSecretList.

The existing extract and insert API functions remain unchanged..

CA_SIMExtract

CK_RV CK_ENTRY CA_SIMExtract( CK_SESSION_HANDLE     hSession,
                              CK_ULONG              ulHandleCount,
                              CK_OBJECT_HANDLE_PTR  pHandleList,
                              CK_ULONG              ulAuthSecretCount, // N value
                              CK_ULONG              ulAuthSubsetCount, // M value
                              CKA_SIM_AUTH_FORM     authForm,
                              CK_ULONG_PTR          pulAuthSecretSizes,
                              CK_BYTE_PTR           *ppbAuthSecretList,
                              CK_BBOOL              deleteAfterExtract,
                              CK_ULONG_PTR          pulBlobSize,
                              CK_BYTE_PTR           pBlob );

CA_SIMExtract takes a list of object handles, extracts them using the given blob (binary large object) authorization data for protection and returns the extracted set of objects as a single data blob. The objects are left on the partition or destroyed, based on the value of the delete-after-extract flag.

The authDataCount parameter defines the N value. The subsetRequired parameter defines the M value. The authDataList parameter should have N entries in it, if it is used.

An empty handle list attempts to extract all the keys on the partition, as long as the size limit is respected.

CA_SIMInsert

CK_RV CK_ENTRY CA_SIMInsert( CK_SESSION_HANDLE     hSession,
                             CK_ULONG              ulAuthSecretCount, // M value
                             CKA_SIM_AUTH_FORM     authForm,
                             CK_ULONG_PTR          pulAuthSecretSizes,
                             CK_BYTE_PTR           *ppbAuthSecretList,
                             CK_ULONG              ulBlobSize,
                             CK_BYTE_PTR           pBlob,
                             CK_ULONG_PTR          pulHandleCount,
                             CK_OBJECT_HANDLE_PTR  pHandleList );

CA_SIMInsert takes a previously extracted blob as input, validates the blob authorization data, inserts the objects contained in the blob into the HSM, and returns the list of handles assigned to the objects.

The authDataCount value should equal M, and the authDataList should have M elements in it.

CA_SIM_MultiSign

CK_RV CK_ENTRY CA_SIMMultiSign( CK_SESSION_HANDLE   hSession,
                                CK_MECHANISM_PTR    pMechanism,
                                CK_ULONG            ulAuthSecretCount, // M value
                                CKA_SIM_AUTH_FORM   authForm,
                                CK_ULONG_PTR        pulAuthSecretSizes,
                                CK_BYTE_PTR         *ppbAuthSecretList,
                                CK_ULONG            ulBlobSize,
                                CK_BYTE_PTR         pBlob,
                                CK_ULONG            ulInputDataCount,
                                CK_ULONG_PTR        pulInputDataLengths,
                                CK_BYTE_PTR         *ppbInputDataList,
                                CK_ULONG_PTR        pulSignatureLengths,
                                CK_BYTE_PTR         *ppbSignatureList );

CA_SIM_MultiSign takes a previously extracted blob as input, validates the authorization data, then uses the key material in the given key blob to sign the various pieces of data in the input data table, returning the signatures through the signature table. Note that the key exists on the HSM only during the processing of the command and does not persist afterward.

If the blob contains more than one key, the key in the blob that is suitable for the requested signature mechanism is used to sign the data. If there are multiple candidates, an error is returned.

The blob authorization data parameters are handled as for the SIMInsert function.

Per-key authorization data is not passed in to the HSM with this call to authorize the inserted key object. If the inserted key has per-key authorization attribute defined, this function is tied to access-based per-key authorization.

CA_SMKRollover

CK_RV CA_SMKRollover( CK_SESSION_HANDLE ulSessionNumber,       
                      CK_ULONG ulValue 
)

This operation moves the current primary SMK to the Rollover SMK location and creates a new primary SMK. It starts with value 1, and ends with value 0. The open time between start and end is intended for inserting any blobs that were encrypted with the old SMK and [re-]extracting them with the new SMK. If no such blobs exist, or have value, then issuing a SMKRollover start (1) followed immediately by a stop (0) just creates a new SMK.