Secure External Scalable Key Storage Extensions

The extensions on this page are used for Scalable Key Storage.

CA_SIMExtract

Takes a list of object handles, extracts the objects using the given blob (binary large object) authorization data for protection and returns the extracted set of objects as a single data blob. Requires minimum Luna HSM Firmware 7.7.0 and Luna HSM Client 10.3.0.

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

I/O	Argument	Description
In	hSession	The authenticated session handle.
	ulHandleCount	The number of objects specified in pHandleList.
	pHandleList	Pointer to an array of object handles to be extracted.
	ulAuthSecretCount	The N value -- the total number of accepted authentication passwords.
	ulAuthSubsetCount	The M value -- the minimum number of acceptable passwords required to decrypt the blob.
	authForm	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. >0: no authentication >1: M of N passwords
	pulAuthSecretSizes	Pointer to an array of M string lengths for the passwords supplied in ppbAuthSecretList. NULL when 0 is specified for authForm.
	*ppbAuthSecretList	Pointer to an array of M password strings to use to authenticate the blob. NULL when 0 is specified for authForm.
	deleteAfterExtract	Boolean determining whether to delete the keys from the partition after extracting the blob.
Out	pulBlobSize	The size of the extracted blob.
	pBlob	The encrypted blob.

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. Requires minimum Luna HSM Firmware 7.7.0 and Luna HSM Client 10.3.0.

CA_SIMInsert(CK_SESSION_HANDLE    hSession, 
             CK_ULONG             ulAuthSecretCount, 
             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); 

I/O	Argument	Description
In	hSession	The authenticated session handle.
	ulAuthSecretCount	The number of authentication passwords supplied. Must be equal to M as defined during blob extraction.
	authForm	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. >0: no authentication >1: M of N passwords
	pulAuthSecretSizes	Pointer to an array of M string lengths for the passwords supplied in ppbAuthSecretList.
	*ppbAuthSecretList	Pointer to an array of M password strings to use to authenticate the blob.
	ulBlobSize	The size of the encrypted blob.
	pBlob	The encrypted blob.
Out	pulHandleCount	Pointer to the number of objects that were inserted.
	pHandleList	Pointer to an array of object handles assigned to the inserted objects.

CA_SIMInsertExtended

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. Requires Luna HSM Client 10.6.0 or newer.

CA_SIMInsertExtended(CK_SESSION_HANDLE    hSession, 
                     CK_ULONG             ulAuthSecretCount, 
                     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, 
                     CK_ULONG             ulStorageType, 
                     CK_ULONG             ulInsertMode); 

I/O	Argument	Description
In	hSession	The authenticated session handle.
	ulAuthSecretCount	The N value -- the total number of accepted authentication passwords.
	authForm	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. >0: no authentication >1: M of N passwords
	pulAuthSecretSizes	Pointer to an array of M string lengths for the passwords supplied in ppbAuthSecretList.
	*ppbAuthSecretList	Pointer to an array of M password strings to use to authenticate the blob.
	pulHandleCount	Pointer to the number of objects that were inserted.
	pHandleList	Pointer to an array of object handles to be extracted.
	ulStorageType
	ulInsertMode
Out	ulBlobSize	The size of the encrypted blob.
	pBlob	The encrypted blob.

CA_SIMMultiSign

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 exists on the HSM only during the processing of the command and does not persist afterward. Requires minimum Luna HSM Firmware 7.7.0 and Luna HSM Client 10.3.0.

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.

CA_SIMMultiSign(CK_SESSION_HANDLE hSession, 
                CK_MECHANISM_PTR  pMechanism, 
                CK_ULONG          ulAuthSecretCount, 
                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); 

I/O	Argument	Description
In	hSession	The authenticated session handle.
	pMechanism	Specifies the mechanism to use for the operation.
	ulAuthSecretCount	The N value -- the total number of accepted authentication passwords.
	authForm	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. >0: no authentication >1: M of N passwords NOTE   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.
	pulAuthSecretSizes	Pointer to an array of M string lengths for the passwords supplied in ppbAuthSecretList.
	*ppbAuthSecretList	Pointer to an array of M password strings to use to authenticate the blob.
	ulBlobSize	The size of the encrypted blob.
	pBlob	The encrypted blob.
	ulInputDataCount	The number of objects to be signed, specified in ppbInputDataList.
	pulInputDataLengths	Pointer to an array of lengths of the data objects specified in ppbInputDataList.
	*ppbInputDataList	Pointer to an array of data objects to be signed.
Out	pulSignatureLengths	Pointer to the lengths of the signed data objects.
	*ppbSignatureList	Pointer to the signed data objects.

CA_SMKRollover

Move the current SMK to the RolloverSMK slot and creates a new Primary SMK - this allows insertion/decrypting of existing blobs with Rollover SMK and re-encryption/extraction with the new Primary. Use again to end the operation and complete the rollover. Requires minimum Luna HSM Firmware 7.7.0 and Luna HSM Client 10.3.0.

CA_SMKRollover(CK_SESSION_HANDLE ulSessionNumber, 
               CK_ULONG          ulValue); 

I/O	Argument	Description
In	ulSessionNumber	The session handle.
	ulValue	Specifies whether to begin or end the rollover process, as described below: >1: Begin the rollover process. Moves the current SMK to the RolloverSMK location, and creates a new Primary SMK. Blobs that were encrypted with the old SMK can still be inserted, decrypted (see CA_SIMInsert), and then re-extracted with the new SMK (see CA_SIMExtract). >0: End the rollover process by deleting the RolloverSMK. Any blobs that are encrypted by this SMK are unrecoverable. Ensure that all important blobs have been re-inserted and re-extracted before using this option.