Cluster Extensions

The Luna SDK includes the following custom extensions to PKCS#11 for use with keyring slots. See Clusters.

NOTE   Thales requires minimum Luna Appliance Software 7.8.5 with the lnh_cluster-1.0.4 package, Luna HSM Firmware 7.8.4, and Luna HSM Client 10.7.2 to use clusters in production environments.

CA_GetSlotId

Resolve the ID of the token(s) from the given label.

If pSlotId is NULL_PTR then the function just returns the number of slot IDs in the pulCount. If pSlotId is not NULL_PTR then the pointer pulCount contains the size (in terms of CK_SLOT_ID elements) of the buffer pointed to by pSlotId. If that buffer is large enough to hold the lists of slot IDs, then the list is returned in it, and CKR_OK is returned. Otherwise, CKR_BUFFER_TOO_SMALL is returned. In either case, the value of the pulCount is set to hold the number of slot IDs.

CK_RV CA_GetSlotId( 
            CK_UTF8CHAR           label[32] );
            CK_SLOT_ID_PTR        pSlotId,
            CK_ULONG_PTR          pulCount);

Input:

>label: the 32-byte label of the token to be resolved. The label must be padded with blank characters and not be null-terminated.

Return:

>pSlotId:pointer to the list of ID of the matched token(s).

>pulCount: number of slotID entries in the buffer. The size of the buffer is number of entries x sizeof( CK_SLOT_ID)

Return Code Hex Code Description
CKR_OK 0x0000 Successful
CKR_ARGUMENTS_BAD 0x0007  
CKR_DEVICE_ERROR 0x0030  
CKR_BUFFER_TOO_SMALL 0x0150  
CKR_CRYPTOKI_NOT_INITIALIZED 0x0190  

CA_GetUnassignedSlot

Get the ID of the next unassigned token from the unordered list of created tokens in the system.

The token is considered unassigned when its original label matches the current label. Each token has an associated lock which is intended to be held by an application that is in the process of assigning it. Only the application holding a lock on the token should proceed to assign the token. A slot returned by this call will have its lock set on return. The lock can also be directly manipulated via CA_LockClusteredSlot or CA_UnlockClusteredSlot functions (these operations are thread/process safe). The only time the mutex lock will automatically unset itself is when the application is disconnected before it has a chance to execute the CA_UnlockClusteredSlot function. A token’s lock status must be enforced by the client application as the system will not block any operations based on the lock.

CK_RV CK_ENTRY CA_GetUnassignedSlot(const 
            CK_CHAR_PTR                    clusterID,
            CK_UNASSIGNED_SLOT_INFO_PTR    pUnassignedSlot);

where CK_UNASSIGNED_SLOT_INFO_PTR is defined as a pointer of the following structure:

typedef struct CK_UNASSIGNED_SLOT_INFO {
            CK_SLOT_ID                 slotID;
            CK_UTF8CHAR                label[32];           /* blank padded */
} CK_UNASSIGNED_SLOT_INFO;

Returns:

>slotID: the ID of the unassigned token.

>label[32]: the 32-byte label of the unassigned token. It is not null-terminated and is padded with space characters.

Return Code Hex Code Description
CKR_OK 0x0000 Successful
CKR_FUNCTION_FAILED 0x0006 Cannot find any unassigned tokens.
CKR_ARGUMENTS_BAD 0x0007  
CKR_DEVICE_ERROR 0x0030  
CKR_BUFFER_TOO_SMALL 0x0150  
CKR_CRYPTOKI_NOT_INITIALIZED 0x0190  

CA_LockClusteredSlot

Request to put the mutex lock on the token.

CK_RV CA_LockClusteredSlot (
            CK_SLOT_ID               slotID );

Input:

>slotID: ID of the slot that interfaces with the token.

Return Code Hex Code Description
CKR_OK 0x0000 Successful
CKR_SLOT_ID_INVALID 0x0003  
CKR_DEVICE_ERROR 0x0030  

CA_UnlockClusteredSlot

Request to put the mutex unlock on the token.

CK_RV CA_UnlockClusteredSlot (
            CK_SLOT_ID               slotID );

Input:

>slotID: ID of the slot that interfaces with the token.

Return Code Hex Code Description
CKR_OK 0x0000 Successful
CKR_SLOT_ID_INVALID 0x0003  
CKR_DEVICE_ERROR 0x0030