Luna HSM Cloning API CPv3 - Extensions to PKCS #11

This section provides details of the Thales Luna HSM Cloning API 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 CPv3 APIs are based on Luna HSM Firmware 7.7.0 Cloning Protocol version 3.

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 the following function used:

CA_Clone_Object

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);
I/O Argument Description
In hTargetSession

The handle of the open session on the target token.
hSourceSession

The handle of the open session on the source token.
ulObjectType

Always specify CK_CRYPTOKI_ELEMENT for cloning standard PKCS#11 objects.
hObjectHandle

The handle of the object on the source token to be cloned.
Out phClonedObject

The object handle of the newly cloned object on the target token.

Cloning between Host Systems

When cloning between two HSMs that are visible only 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 system dependent, and beyond the scope of this document. However, below is the sequence of PKCS#11 extension functions to direct to the source and target HSMs (or slots) in order to complete the cloning operation:

Diagram of CPv3 cloning flow

Step 1 – Initialize the cloning operation on the source HSM, obtaining initialization data from the source HSM:

Initialize the cloning operation on the source token. Requires minimum Luna HSM Firmware 7.7.0 and Luna HSM Client 10.3.0. 

CA_CloneAsSourceInit(CK_SESSION_HANDLE hSession, 
                     CK_BYTE_PTR       pInParameter, 
                     CK_ULONG          ulInParameterSize, 
                     CK_BYTE_PTR       pOutParameter, 
                     CK_ULONG_PTR      pulOutParameterSize, 
                     CK_BBOOL          bReplicate);
I/O Argument Description
In hSession The authenticated session handle.
pInParameter

Always NULL.
ulInParameterSize

Always 0.
Out pOutParameter

The output of the initialization data (TWC).
pulOutParameterSize

The size of the initialization data (TWC).
bReplicate

Boolean indicates whether this is a pure cloning operation, or uses network replication:

>Cloning to/from Luna PCIe HSM 7 or Luna USB HSM 7: FALSE

>Cloning to/from Luna Network HSM 7: TRUE

Step 2 – Initialize the cloning operation on the target HSM, passing in the TWC data obtained from the first step:

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);
I/O Argument Description
In hSession The authenticated session handle.
pTWC

The Token Wrapping Certificate (TWC) -- output of pOutParameter from the source HSM.
ulTWCSize

The size of the TWC -- output of pulOutParameterSize from the source HSM.
pKEV Always NULL -- for compatibility with legacy HSMs.
ulKEVSize Always 0 -- for compatibility with legacy HSMs.
bReplicate

Boolean indicates whether this is a pure cloning operation, or uses network replication:

>Cloning to/from Luna PCIe HSM 7 or Luna USB HSM 7: FALSE

>Cloning to/from Luna Network HSM 7: TRUE
Out pPart1

The Part1 buffer.
pulPart1Size

The size of the Part1 buffer.

Step 3 – 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);
I/O Argument Description
In hSession The authenticated session handle.
hType

Always specify CK_CRYPTOKI_ELEMENT for cloning standard PKCS#11 objects.
hHandle

The handle of the object being cloned.
pPart1

The Part1 buffer.
ulPart1Size

The size of the Part1 buffer.
bReplicate

Boolean indicates whether this is a pure cloning operation, or uses network replication:

>Cloning to/from Luna PCIe HSM 7 or Luna USB HSM 7: FALSE

>Cloning to/from Luna Network HSM 7: TRUE
Out pPart2

The Part2 buffer.
pulPart2Size

The size of the Part2 buffer.

Step 4 – 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);
I/O Argument Description
In hSession The authenticated session handle.
pKEV Always NULL -- for compatibility with legacy HSMs.
ulKEVSize Always 0 -- for compatibility with legacy HSMs.
pPart2

The Part2 buffer.
ulPart2Size

The size of the Part2 buffer.
hType

Always specify CK_CRYPTOKI_ELEMENT for cloning standard PKCS#11 objects.
hHandle Not required for standard crypto objects; specify 0.
bReplicate

Boolean indicates whether this is a pure cloning operation, or uses network replication:

>Cloning to/from Luna PCIe HSM 7 or Luna USB HSM 7: FALSE

>Cloning to/from Luna Network HSM 7: TRUE
Out phClonedHandle

The handle of the cloned object on the target token.

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 2 and 4 above.

2.The crypto officer (CO) must have already logged in both the source and target HSMs.

3.In general, when creating buffers for the various data items passed back from the function, an 8KB 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.

4.The whole cloning process must be repeated for each object.

5.The source HSM and the target HSM must be in the same domain for the cloning operation to be successful.