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 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 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:
Step1 – the Token Wrapping Certificate (TWC) is first obtained from the source token:
CK_RV CA_GetTokenCertificates( CK_SLOT_ID slotID,
CK_ULONG ulCertType,
CK_BYTE_PTR pCertificate,
CK_ULONG_PTR pulCertificateLen );
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
Use the TWC3 macro definition for all Luna firmware 6.x and firmware 4.8.5 and later. For firmware versions earlier than 4.8.5 use theTWC2 definition.
Step2 – obtain the KEV from the target token – this ensures that the tokens are part of the same cloning domain:
CK_RV 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:
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
>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.
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:
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
>hType should always be set to CK_CRYPTOKI_ELEMENT for cloning standard PKCS#11 objects,
>hHandle points to the object to be cloned, and the bReplicate flag is defined as in the previous step.
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:
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,
>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 3.
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.
