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:
CK_RV CA_CloneObject( CK_SESSION_HANDLE hTargetSession,
CK_SESSION_HANDLE hSourceSession,
CK_ULONG ulObjectType,
CK_OBJECT_HANDLE hObjectHandle,
CK_OBJECT_HANDLE_PTR phClonedObject );
Where ulObjectType is CK_CRYPTOKI_ELEMENT, hObjectHandle is the handle of the object on the source token to be cloned, and phCloned Object will contain 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:
Step1 – Initialize the cloning operation on the source HSM, obtaining initialization data from the source HSM:
CK_RV CA_CloneAsSourceInit( CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pInParameter,
CK_ULONG ulInParameterSize,
CK_BYTE_PTR pOutParameter,
CK_ULONG_PTR pulOutParameterSize,
CK_BBOOL bReplicate);
Where
>hSession is the session handle to the source HSM,
>pInParameter is NULL,
>ulInParameterSize is 0,
>pOutParameter is the output of the initialization data (which is the cloning certificate, also known as TWC, in the current protocol), and
>pulOutParameterSize is the size of the initialization data
>bReplicate boolean indicates whether this is a pure cloning operation, or it involves network replication; for the Luna PCIe HSM 7, this flag should be FALSE, whereas for cloning objects to/from the Luna Network HSM 7, this flag should be set to TRUE.
Step 2 – Initialize the cloning operation on the target HSM, passing in the TWC data obtained from the first step:
CK_RV 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);
Where
>hSession is the session handle to the target HSM,
>pTWC and ulTWCSize are the initialization data (i.e., pOutParameter and pulOutParameterSize) from the source HSM in step 1,
>the pKEV and ulKEVSize parameters are for backward compatibility with older HSMs, set to NULL and 0,
>the bReplicate flag is defined as in step 1.
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 3 – Clone the desired HSM object from the source token:
CK_RV 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);
Where
>hSession is the session handle to the source HSM,
>hType should always be set to CK_CRYPTOKI_ELEMENT for cloning standard PKCS#11 objects,
>hHandle points to the object to be cloned, and
>bReplicate flag is defined as in the previous step,
>pPart1 and ulPart1Size parameters are from the target HSM in step 2.
Pass the Part2 buffer and size variable back to the target host system to be used in the next function call.
Step 4 – Clone the HSM object to the target token:
CK_RV 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);
Again,
>pKEV and ulKEVSize parameters are for backward compatibility with older HSMs, set to NULL and 0,
>hType should be set to CK_CRYPTOKI_ELEMENT,
>hHandle is not required for standard crypto objects (set to 0), and
>bReplicate flag is set as defined in Step 1,
>phClonedHandle is returned as the cloned object handle.
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.
