Luna HSM Cloning API CPv1 - Extensions to PKCS #11

This section provides details of the Thales Luna HSM Cloning API CPv1 for these scenarios

>where the source and target token (or slot) are visible on the same host,

>where the source and target tokens are visible only to separate host systems.

In the latter case, you might need to develop significant logic in order to initiate and synchronize the cloning process between the two host systems. The CPv1 APIs have been in use since before Luna HSM 4.x and continue to be used, where appropriate, alongside the newer CPv3 (since Luna HSM Firmware 7.7.0) and CPv4 (since Luna HSM Firmware 7.8.0).

Use the information in this section, about the low-level APIs, when it is not appropriate to use the high-level CA_MigrateKeys API in your application.

Cloning on the Same Host System

When cloning HSM objects between two tokens that are visible to the same host system, then a session can be opened on each token (slot) and CA_CloneObject used:

Clone an object from one token to another eligible token (matching domains), visible to the same client.

CA_CloneObject(CK_SESSION_HANDLE    hTargetSession, 
               CK_SESSION_HANDLE    hSourceSession, 
               CK_ULONG             ulObjectType, 
               CK_OBJECT_HANDLE     hObjectHandle, 
               CK_OBJECT_HANDLE_PTR phClonedObject); 

Cloning between Host Systems

When cloning between two HSMs that are only visible to separate host systems, additional logic must be created in order to synchronize the cloning process between the systems. How this is initiated or what protocol should be deployed is somewhat system dependent, and beyond the scope of this document. However, below is the sequence of PKCS#11 extension functions that need to be directed to the source and target HSMs (or slots) in order to complete the cloning operation:

Step 1 – the Token Wrapping Certificate (TWC) is first obtained from the source token:

Get a certificate from the source token. Token Wrapping Certificates (TWR) are used for cloning.

CA_GetTokenCertificates(CK_SLOT_ID   slotID, 
                        CK_ULONG     ulCertType, 
                        CK_BYTE_PTR  pCertificate, 
                        CK_ULONG_PTR pulCertificateLen); 

#define CKHSC_CERT_TYPE_TWC3                0x0000000B

The ulCertType parameter is defined in the cryptoki_v2.h header file as follows:

#define CKHSC_CERT_TYPE_TWC                 0x00000009

#define CKHSC_CERT_TYPE_TWC2                0x0000000A

#define CKHSC_CERT_TYPE_TWC3                0x0000000B

Step 2 – obtain the KEV from the target token – this ensures that the tokens are part of the same cloning domain:

Generate a KEV for the token.

CA_GenerateCloningKEV(CK_SESSION_HANDLE hSession, 
                      CK_BYTE_PTR       pKEV, 
                      CK_ULONG_PTR      pulKEVSize); 

The TWC obtained in Step 1 must now be passed to the target host for the next step in the cloning operation.

Step 3 – Initialize the cloning operation on the target HSM, passing in the parameters obtained from the first two steps:

Initializes the cloning operation on the target token.

CA_CloneAsTargetInit(CK_SESSION_HANDLE hSession, 
                     CK_BYTE_PTR       pTWC, 
                     CK_ULONG          ulTWCSize, 
                     CK_BYTE_PTR       pKEV, 
                     CK_ULONG          ulKEVSize, 
                     CK_BBOOL          bReplicate, 
                     CK_BYTE_PTR       pPart1, 
                     CK_ULONG_PTR      pulPart1Size); 

This function fills in the Part1 buffer and return the size of Part1 – these parameters must be returned to the source host system to be used in the next function call.

Step 4 – Clone the desired HSM object from the source token:

Clone an object from the source token.

CA_CloneAsSource(CK_SESSION_HANDLE hSession, 
                 CK_ULONG          hType, 
                 CK_ULONG          hHandle, 
                 CK_BYTE_PTR       pPart1, 
                 CK_ULONG          ulPart1Size, 
                 CK_BBOOL          bReplicate, 
                 CK_BYTE_PTR       pPart2, 
                 CK_ULONG_PTR      pulPart2Size); 

Pass the Part2 buffer and size variable back to the target host system to be used in the next function call.

Step 5 – Clone the HSM object to the target token:

Clone an object to the target token.

CA_CloneAsTarget(CK_SESSION_HANDLE    hSession, 
                 CK_BYTE_PTR          pKEV, 
                 CK_ULONG             ulKEVSize, 
                 CK_BYTE_PTR          pPart2, 
                 CK_ULONG             ulPart2Size, 
                 CK_ULONG             hType, 
                 CK_ULONG             hHandle, 
                 CK_BBOOL             bReplicate, 
                 CK_OBJECT_HANDLE_PTR phClonedHandle); 

hHandle is not required for standard crypto objects (set to 0).

IMPORTANT CONSIDERATIONS

1.The cloning process must be completed in the context of a single session opened on the source token, and one opened on the target token. For example, you must use the same session handle on the target token for Steps 3 and 5 above.

2.In general, when creating buffers for the various data items passed back from the function, a 4k buffer should be sufficient (certificate, part1, part2) but it should be possible to set these pointers to NULL, and the corresponding size parameter to zero – the function then fills the size variable with the size of the data item. The appropriate memory can then be malloc’d and the function called again to retrieve the actual data.

3.Only one HSM object can be cloned for each operation.

4.All macro-definitions indicated in this section can be found in the cryptoki_v2.h header file.