|
Home > |
|---|
Note: The SafeNet Network HSM HA feature and SIM can be used simultaneously in SafeNet Network HSM release 3.0 and later.
Applications use the following APIs to extract/insert keys under SIM. 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 provides enhancements to SIM for the Cyptoki API and the Java API, as described in the following sections:
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:
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.
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.
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.
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 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 SIM masking process.
When a key is stored in this type of keystore, it is extracted using SIM 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.
The following examples show how to use the ckdemo utility to perform SIM operations.
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.
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.