Luna HSM Cloning API CPv4 Extensions to PKCS#11

Similar to earlier cloning protocols, CPv4 has two sets of APIs; a single top level API that performs the full key migration and a set of low level APIs that can break the protocol into two parts;

>session key establishment
vs

>key extraction/insertion.

The low level APIs can also be used to execute the protocol on two partitions that are not directly accessible by a single client application.

Top-Level API: CA_MigrateKeys

This API clones one-or-more objects from a source session to a target session. The API can clone user objects (a.k.a. CryptokiObjects) or parameters like the SMK (a.k.a. ParamObjects). The API also supports a “flags” field to alter/change the behavior of the API when errors are encountered.

In addition to implementing CPv4, the top level API takes on the behavior that allows it to use existing key migration methods.

CA_MigrateKeys(CK_SESSION_HANDLE            sourceSession, 
               CK_SESSION_HANDLE            targetSession, 
               CK_ULONG                     migrationFlags, 
               CK_ULONG                     numberOfObjects, 
               CK_OBJECT_MIGRATION_DATA_PTR migrationData); 

typedef struct CK_OBJECT_MIGRATION_DATA (
   CK_ULONG   objectType;
   CK_OBJECT_HANDLE sourceHandle;
   CK_OBJECT_HANDLE targetHandle;
   CK_RV  rv
} CK_OBJECT_MIGRATION_DATA;

If an individual object fails to clone, CA_MigrateKeys returns CKR_OK. If an error is encountered in the core logic of CA_MigrateKeys, then the error code for that event is returned by the API, and the value of rv remains CKR_CLONE_NOT_ATTEMPTED for all objects that were not attempted to be cloned.

Low-Level APIs

This section defines the low-level APIs. The low-level APIs map to the internal APIs defined within the client library, that are used by the top level CA_MigrateKeys API.

If an application does not have access (is unable to open a session) to both the target and source HSM, then the low level APIs can be used and the application must propagate the parameters from one device to the other. Essentially, this mimics the exchange implemented by CA_MigrateKeys. The low level APIs should not be used under any other circumstances as their use increases the effort and complexity of maintaining backward compatibility.

Session key negotiation is intended to be an atomic operation. To avoid resource leaking, if the session key negotiation is not completed within 10 minutes the HSM cleans up resources associated with the negotiation. If no other CPv4 related calls have been made, CKR_SESSION_NEGOTIATION_EXPIRED is returned if an attempt is made to continue the negotiation after it has expired. If other CPv4 related calls have been made, the HSM might have already cleaned up the resources and CKR_SESSION_NEGOTIATION_NOT_STARTED is returned. Applications that are using the low-level APIs must be able to handle these error scenarios. The resource clean-up is described later.

Once established, a session expires after 1 hour. Any attempt to use an expired session results in CKR_SESSION_ID_EXPIRED. Applications using the low level API must be able to handle this error and are required to re-negotiate a new session.

Expired sessions are cleaned up by the HSM, as the HSM is not required to maintain expired sessions any longer than it needs for its own internal implementation reasons. Therefore, it is expected that if multiple threads/processes are using the same session, and are not synchronizing during expiry and re-negotiation scenarios, an attempt to use an expired session can result in CKR_SESSION_ID_INVALID as the HSM no longer knows about the session ID. Applications using the low level APIs must be able to handle this error scenario. As one session ID can be used/shared for an entire access, care should be taken so that each thread does not end up re-negotiating their own session ID as this would be extremely inefficient for the application and HSM.

CA_MigrationStartSessionNegotiation

This API starts a session key negotiation with a partition on the source or target HSM.

CA_MigrationStartSessionNegotiation(CK_SESSION_HANDLE hSession, 
                                    CK_ULONG          inputLength, 
                                    CK_BYTE_PTR       input, 
                                    CK_ULONG_PTR      step, 
                                    CK_ULONG_PTR      outputLength, 
                                    CK_BYTE_PTR       output); 

CA_MigrationContinueSessionNegotiation

This is called to continue the negotiation; when it is first called on the second HSM, it technically starts the negotiation there. As the API is called from one HSM to the next, all of the output values are passed to the “other” HSM as input values.

The first call to CA_MigrationContinueSessionNegotiation invokes a session ID for the session being negotiation. All following calls to this API are required to pass in the same session ID.

When the negotiation is complete, status=2 is returned. The content of the output values must be passed in to the other HSM as input to the first call to either CA_Extract or CA_Insert to complete the negotiation on the other HSM.

CA_MigrationContinueSessionNegotiation(CK_SESSION_HANDLE hSession, 
                                       CK_ULONG          inputStep, 
                                       CK_ULONG          inputLength, 
                                       CK_BYTE_PTR       input, 
                                       CK_ULONG          sessionUidInputLen, 
                                       CK_BYTE_PTR       sessionUidInput, 
                                       CK_ULONG_PTR      outputStep, 
                                       CK_ULONG_PTR      outputLength, 
                                       CK_BYTE_PTR       output, 
                                       CK_ULONG_PTR      status, 
                                       CK_ULONG_PTR      sessionUidOutputLen, 
                                       CK_BYTE_PTR       sessionUidOutput); 

This API can return more than one piece of output data. Simplify the application and the API implementation, when querying the required buffer size, by providing a NULL pointer; all possible output fields must be queried at the same time.

CA_MigrationCloseSession

This API terminates a session. When it is called, the session key and all of its context/state is deleted. If the session key does not exist, no error is returned. This is because some implementations might proactively clean up sessions that have expired, so it is expected that by the time this API is called, the session might no longer exist. In this case, CKR_SESSION_ID_INVALID is returned.

CA_MigrationCloseSession(CK_SESSION_HANDLE hSession, 
                         CK_ULONG          sessionUidLen, 
                         CK_BYTE_PTR       sessionUid); 

CA_Extract

This API extracts objects or internal CSPs using the specified session id. The API functionality is defined by a mechanism and a mechanism parameter which allows for any functionality to be defined on a per-mechanism basis. This makes it ideal for the CPv4 extract/insert operations and is consistent with the PKCS#11 API. Requires minimum Luna HSM Firmware 7.8.0 and Luna HSM Client 10.5.0.

CA_Extract(CK_SESSION_HANDLE hSession, 
           CK_MECHANISM_PTR  pMechanism); 

The parameter CK_CPV4_EXTRACT_PARAMS is structured as follows:

CK_CPV4_EXTRACT_PARAMS {
  CK_ULONG_PTR		sessionIdLength;
  CK_BYTE		sessionId;
  CK_ULONG		inputLength;
  CK_BYTE_PTR		input;
  CK_ULONG		extractionFlags;
  CK_ULONG		numberOfObjects;
  CK_ULONG_PTR		objectType; 
  CK_ULONG_PTR		objectHandle;
  CK_RV_PTR		result;
  CK_ULONG_PTR		keyBlobLength;
  CK_BYTE_PTR_PTR	keyBlob; 
}

CA_Insert

This API inserts objects, or internal CPS, using the specified session id. The API functionality is defined by a mechanism and a mechanism parameter which allows for any functionality to be defined on a per-mechanism basis. This makes it ideal for the CPv4 extract/insert operations and is consistent with the PKCS#11 API. Requires minimum Luna HSM Firmware 7.8.0 and Luna HSM Client 10.5.0.

CA_Insert(CK_SESSION_HANDLE hSession, 
          CK_MECHANISM_PTR  pMechanism); 

The parameter CK_CPV4_INSERT_PARAMS is structured as follows:

CK_CPV4_INSERT_PARAMS {
  CK_ULONG_PTR		sessionIdLength;
  CK_BYTE		sessionId;
  CK_ULONG		insertionFlags;
  CK_ULONG		numberOfObjects;
  CK_ULONG_PTR		storageType;
  CK_ULONG_PTR		objectType;
  CK_ULONG_PTR		keyBlobLength;
  CK_BYTE_PTR_PTR	keyBlob;
  CK_RV_PTR		result;
  CK_ULONG_PTR		objectHandle;
}

CPv4 PKCS#11 Error Code Summary

This section provides a summary of all of the error codes introduced by the CPv4 APIs, and their intended meanings.

When processing parameters, at the API level in the client or in the HSM, error codes defined for operations and features of prior releases might also be returned when invalid parameters are detected.

PSK APIs

This section defines the APIs and ICD commands that are defined to support the domain management functionality.

PKCS#11 Extension APIs

This section defines the PKCS#11 Extension APIs.

PWD vs Local and Remote PED

Similar to existing APIs like C_Login, CA_ResetPIN, etc, these APIs can receive a value (the KCV) as a typed string (like a password) or from a PED key.

When providing a PED key-based KCV, the KCV parameters defined below must be set to NULL and 0. If the KCV is being entered from a local PED, that is all that is required. If the KCV is to be entered via a Remote PED, then a Remote PED connection must be setup and a PED ID defined for the connection. Just like the other APIs that may make use of a Remote PED, the APIs defined in this section will pick up and use whichever PED ID is defined. Setting up Remote PED connections and PEDs is covered elsewhere, in the management/administration sections of these docs.

CA_AddKCV

Allows the Partition Security Officer to add an additional Key Cloning Vector (KCV or cloning domain) to the partition. See also Universal Cloning and Luna HSM Cloning API CPv4 Extensions to PKCS#11.

Requires minimum Luna HSM Firmware 7.8.0 and Luna HSM Client 10.5.0.

CA_AddKCV(CK_SESSION_HANDLE hSession, 
          CK_ULONG          ulKCVLength, 
          CK_BYTE_PTR       pKCV, 
          CK_ULONG          ulLabelLength, 
          CK_BYTE_PTR       pLabel, 
          CK_BBOOL          bMakePrimary); 

CA_ChangeKCVLabel

Allows the Partition Security Officer to change the label of a KCV (cloning domain). The primary use of this API is to add a label to a pre-existing KCV that does not already have a label. It can also be used to change an existing label of a KCV, which may be useful when merging/splitting domains and the same domain label has been used for different KCV values. See also Universal Cloning and Luna HSM Cloning API CPv4 Extensions to PKCS#11.

Requires minimum Luna HSM Firmware 7.8.0 and Luna HSM Client 10.5.0.

CA_ChangeKCVLabel(CK_SESSION_HANDLE hSession, 
                  CK_ULONG          ulOldLabelLength, 
                  CK_BYTE_PTR       pOldLabel, 
                  CK_ULONG          ulNewLabelLength, 
                  CK_BYTE_PTR       pNewLabel); 

CA_DeleteKCV

Allows the Partition Security Officer to delete domains on the partition. See also Universal Cloning and Luna HSM Cloning API CPv4 Extensions to PKCS#11.

Requires minimum Luna HSM Firmware 7.8.0 and Luna HSM Client 10.5.0.

CA_DeleteKCV(CK_SESSION_HANDLE hSession, 
             CK_ULONG          ulLabelLength, 
             CK_BYTE_PTR       pLabel); 

CA_GetKCVLabels

Allows any logged-in role to retrieve the domain labels. See also Universal Cloning and Luna HSM Cloning API CPv4 Extensions to PKCS#11.

Requires minimum Luna HSM Firmware 7.8.0 and Luna HSM Client 10.5.0.

CA_GetKCVLabels(CK_SLOT_ID   slotID, 
                CK_ULONG_PTR ulNumberOfLabels, 
                CK_ULONG_PTR ulFlags, 
                CK_ULONG_PTR ulLabelLengths, 
                CK_BYTE_PTR  pLabels);