Scalable Key Storage (formerly SIM) APIs

Home >	SDK Reference Guide > Design Considerations > Secure Identity Management (SIM) APIs

Scalable Key Storage (formerly SIM) APIs

Note: The SafeNet Network HSM HA feature and Scalable Key Storage can be used simultaneously in SafeNet Network HSM release 3.0 and later.

Applications use the following APIs to extract/insert keys under Scalable Key Storage. The multisign function call is an optimization that allows you to insert and sign (potentially) many objects at once.

CK_RV CK_ENTRY CA_ExtractMaskedObject(CK_SESSION_HANDLE hSession,

CK_ULONG ulObjectHandle,

CK_BYTE_PTR pMaskedKey,

CK_USHORT_PTR pusMaskedKeyLen);

CK_RV CK_ENTRY CA_InsertMaskedObject( CK_SESSION_HANDLE hSession,

CK_ULONG_PTR pulObjectHandle,

CK_BYTE_PTR pMaskedKey,

CK_USHORT usMaskedKeyLen);

CK_RV CK_ENTRY CA_MultisignValue( CK_SESSION_HANDLE hSession,

CK_MECHANISM_PTR pMechanism,

CK_ULONG ulMaskedKeyLen,

CK_BYTE_PTR pMaskedKey,

CK_ULONG_PTR pulBlobCount,

CK_ULONG_PTR pulBlobLens,

CK_BYTE_PTR CK_PTR ppBlobs,

CK_ULONG_PTR pulSignatureLens,

CK_BYTE_PTR CK_PTR ppSignatures);

The SafeNet Software Developers Kit contains example code in our ckdemo example program that shows how to use this API.

In general, the normal life cycle of a key pair is assumed to consist of the following steps:

•the key pair is generated

•the public exponent and modulus are extracted for the creation of a certificate (CA_ExtractMaskedObject)

•the keys are used (some number of times, over a period of years) for cryptographic operations

You can use CA_MultisignValue to perform signing operations on multiple objects at one time. CA_MultisignValue is a self-contained call that cleans up after itself by destroying the inserted key before exiting.

You can use CA_InsertMaskedObject to use the inserted key for other operations (such as encryption) that you would invoke via standard cryptoki calls. You must clean up by deleting the object when you have finished, to free the volatile memory that was used.

The external keys are destroyed (wiped from the database) when no longer needed.

SIM II (Enhancements to SIM)

SIM II provides enhancements to SIM for the Cyptoki API and the Java API, as described in the following sections:

Cryptoki API

Three forms of authorization data are supported:

•text-based PINs

•a challenge/response mechanism similar to the one used in SafeNet HSM (with Trusted Path Authentication) login

•a PED key mechanism similar to our legacy M-of-N activation for the HSM.

The form of authorization data is identified using the following definitions:

typedef CK_ULONG SIM_AUTHORIZATION_FORM;

#define SIM_AUTHORIZATION_PIN 0

#define SIM_AUTHORIZATION_CHALLENGE 1

#define SIM_AUTHORIZATION_PED 2

Three new API functions are added to cryptoki.h, as follows:

The CK_RV CA_SIMExtract function

CK_RV CA_SIMExtract(CK_ULONG handleCount, CK_ULONG *handleList,

   CK_ULONG authForm, CK_ULONG authDataCount, CK_ULONG subsetRequired,

   CK_BYTE **authDataList,

   CK_BOOL deleteAfterExtract,

   CK_ULONG *pBlobSize, CK_BYTE *pBlob );

This function takes a list of object handles, extracts them using the given 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.

For an authorization data form of PED or challenge/response, authDataList parameter is null – values are defined through the PED.

The CK_RV SIMInsert function

CK_RV SIMInsert( CK_ULONG blobSize, CK_BYTE *pBlob,

   CK_ULONG authForm, CK_ULONG authDataCount, CK_BYTE **authDataList,

   CK_ULONG *pHandleListSize, CK_ULONG *pHandleList );

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

For an authorization data form of PED, the authDataCount and authDataList parameters are not used. For other authorization data forms, the authDataCount value should equal M, and the authDataList should have M elements in it.

The CK_RV SIMMultiSign function

CK_RV SIMMultiSign( CK_ULONG blobSize, CK_BYTE *pBlob,

   CK_ULONG authForm, CK_ULONG authDataCount, CK_BYTE **authDataList,

   CK_ULONG inputDataCount,

   CK_ULONG *inputDataLengths, CK_BYTE **inputDataTable,

   CK_ULONG *signatureLengths, CK_BYTE **signatureTable);

This function 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. The key blob must contain a single key, otherwise an error is returned.

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

Java API

The standard java keystore API supports a single password for each keystore, and a single password for each key in the keystore. We provide a keystore implementation that stores key material in a file, using Scalable Key Storage (formerly SIM) to extract the key material. The password on the keystore is not used, but the password for each key is used as authorization data for the Scalable Key Storage masking process.

When a key is stored in this type of keystore, it is extracted using Scalable Key Storage and the appropriate authorization data, but the key is left on the HSM. When a key is retrieved from this type of keystore, it is inserted onto the HSM.

The standard keystore API supports 1-of-1 authorization inputs of the text form. Different authorization data forms are supported through a custom API. The LunaTokenManager class is enhanced to provide a new method to allow the authorization data for subsequent keystore operations to be defined. If the password parameter of a keystore SetKeyEntry or SetCertificateEntry method call is given a null value, the actual authorization data will be taken from the LunaTokenManager interface.

Note that it is up to application to serialize calls to LunaTokenManager and the keystore object if multiple threads are simultaneously using keystores. That is, each thread must ensure that it sets its authorization data in LunaTokenManager and then performs its keystore operation without being interrupted by another thread changing the LunaTokenManager authorization data.

Example Operations Using CKDemo

The following examples show how to use the ckdemo utility to perform SIM operations.

Multisign Challenge (Trusted Path Authentication Only)

1.Open Ckdemo and login as user.

2.Create a 1024 bit RSA key pair - 45,7,1024,1,1,1,1,1,1,1,1,1

3.Sim Extract (105)
Enter your choice : 105
Enter handle of object to add to blob (0 to end list, -1 to cancel): 10
Enter handle of object to add to blob (0 to end list, -1 to cancel): 0
Enter authentication form:
0 - none
1 - password
2 - challenge response
3 - PED-based
enter “2”
Enter number of authorization secrets (N value): 3
Enter subset size required for key use (M value): 2

4.The SafeNet PED displays your challenge secrets, be sure to record them.
Delete after extract? [0 = false, 1 = true] : 1

5.For every instance of data to sign, enter “12345678”.
The signatures should complete and be placed in a file.

6.Ensure that the private key has been extracted by performing CKDemo command 26,6 . This shows all the objects on the token. The private key handle that you noted earlier should not be there.

7.Now, insert the blobfile back onto the token:
Select Insert masked object (106)
Enter “simkey.blob” as the keyblob to be re-inserted
Input 2 of the 3 challenges that you recorded earlier.

8.CKDemo 26,6 should reveal that the private key has been re-inserted.

SIM2 Multisign PED-based (PED/Trusted Path Configuration Only)

1.Open Ckdemo and login as user.

2.Create a 1024 bit RSA key pair - 45,7,1024,1,1,1,1,1,1,1,1,1. Note the private and public key handles.

3.Sim Extract (105)
Enter your choice : 105
Enter handle of object to add to blob (0 to end list, -1 to cancel): 10
Enter handle of object to add to blob (0 to end list, -1 to cancel): 0
Enter authentication form:
3 - none
4 - password
5 - challenge response
6 - PED-based
Enter “3”

4.Delete after extract? [0 = false, 1 = true] : 1

5.For every instance of data to sign, enter “12345678”.
The signatures should complete and the key should be placed in the file simkey.blob.

6.Ensure that the private key has been extracted by performing a 26,6 . This will show all the objects on the token. The private key handle that you noted earlier should not be there.

7.Now, insert the blobfile back onto the token:
Select Insert masked object (106)
Enter “simkey.blob” as the keyblob to be re-inserted.
Input 2 of the 3 challenges that you recorded earlier.

8.CKDemo command 26,6 should reveal that the private key has been re-inserted.