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, or minimum Luna Appliance Software 7.9.0 with the lnh_cluster-1.0.5 package, Luna HSM Firmware 7.8.4, and Luna HSM Client 10.8.0 to migrate keys from Luna application partitions.

CA_GetSlotId

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

CA_GetSlotId(CK_UTF8CHAR    label[32], 
             CK_SLOT_ID_PTR pSlotId, 
             CK_ULONG_PTR   pulCount);
I/O Argument Description
In label[32]

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

Pointer to the list of ID of the matched token(s). Can be NULL_PTR.
Out pulCount

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

If pSlotId is NULL_PTR, the number of slot IDs is returned. If pSlotId is not NULL_PTR, 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. The value of the pulCount is set to hold the number of slot IDs.
Return Code Hex Description
CKR_OK 0x0000 Successful
CKR_ARGUMENTS_BAD 0x0007  
CKR_DEVICE_ERROR 0x0030  
CKR_BUFFER_TOO_SMALL 0x0150 The buffer pointed to by pSlotId is not large enough to hold the list of slot IDs.
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.

CA_GetUnassignedSlot(const CK_CHAR_PTR           clusterID, 
                     CK_UNASSIGNED_SLOT_INFO_PTR pUnassignedSlot);
I/O Argument Description
In clusterID

The cluster OUID.
Out pUnassignedSlot

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 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.

CA_LockClusteredSlot(CK_SLOT_ID slotId);
I/O Argument Description
In slotId

The slot number.
Return Code Hex 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.

CA_UnlockClusteredSlot(CK_SLOT_ID slotId);
I/O Argument Description
Input slotId

The slot number.
Return Code Hex Description
CKR_OK 0x0000 Successful
CKR_SLOT_ID_INVALID 0x0003  
CKR_DEVICE_ERROR 0x0030