Using SKS
On this page:
•API
–Replicating the SMK to all group members
–When NOT to address the virtual slot
Logistical considerations for SKS operation include:
> you must create a V1 partition before you can use the SKS functionality;
>creating and logging into an SKS partition (as CO) creates a unique SMK in that partition, at the same time;
>you have the option to use the SMK that is created with the partition, or you can overwrite that SMK with
•an SMK that is restored from an SKS partition on a Backup HSM (with partition archive restore), or
•an SMK that is cloned (with partition smkclone) from another partition (usually for purposes of HA operation);
NOTE Back up the SMK in any partition where that SMK is likely to be overwritten, if that SMK is ever likely to be needed to insert (decrypt) any SKS blobs.
If an SMK is cloned from one partition to another (such as must be done when adding members to an HA group), a pre-existing SMK already in the target partition is overwritten by the incoming SMK. Any blobs still encrypted with it are lost, unless a backup exists.
Using SKS - options
Two approaches are available, to use SKS :
>Use the API, where you have the ability to write or modify your applications:
•Directly access the PKCS#11 C-language extensions that interact with the HSM.
or
•Use the provided Java toolkit.
>Use a commercial, off-the-shelf Windows CNG application, mediated by the provided SKS Client Extension for Luna HSM KSP.
API
Authorization forms currently supported are none, and password.
Export a key from a partition as an SMK-encrypted blob, using SIMExtract function
SIM_AUTH_FORMS = (CKA_SIM_NO_AUTHORIZATION, CKA_SIM_PASSWORD) CK_RV CA_SIMExtract(CK_ULONG handleCount, CK_ULONG *handleList, CK_ULONG authForm, CK_ULONG authDataCount, CK_ULONG subsetRequired, CK_BYTE **authDataList, CK_BOOL deleteAfterExtract, CK_ULONG *pBlobSize, CK_BYTE *pBlob );
Import a previously extracted blob, using the SIMInsert function
CK_RV SIMInsert( CK_ULONG blobSize, CK_BYTE *pBlob, CK_ULONG authForm, CK_ULONG authDataCount, CK_BYTE **authDataList, CK_ULONG *pHandleListSize, CK_ULONG *pHandleList );
For further information, refer to the SDK Guide ( Secure External Scalable Key Storage (SKS) Extensions ).
ckdemo example
1.Start by running ckdemo and executing Open Session (1) to the slot and Login (3) as Crypto Officer, giving the partition password.
2.Generate an AES key using Simple Generate Key (45) and keep track of the object handle for the generated key.
3. Execute SIMExtract (105).
Enter the object handle for Enter handle of object to add to blob and then
Enter 0 to end the list.
Enter 1 for Enter authentication form.
Enter 1 for number of authorization secrets (N value).
Enter 1 for Enter subset size required for key use (M value).
Enter a password.
Enter 1 for Delete after extract.
The masked key is saved to blobfile.sim.
4.List all of the objects in the partition by running Find object (26) with option All Standard Objects (6).
5.Execute SIMInsert (106).
Enter blobfile.sim for Enter filename with object to insert.
Enter 1 for Enter authentication form.
Enter 1 for Enter number of authorization secrets to be provided.
Enter the password that was entered in the previous step.
6.List all of the objects in the partition by running Find object (26) with option All Standard Objects (6). The key that was extracted should now be present in the partition.
NOTE The example above uses the password authentication form. Other authentication forms can be used.
Java Sample
As a prerequisite, ensure that the LunaProvider.jar and libLunaAPI.so has been installed to your JDK.
1.Navigate to the directory that contains the java sample:
cd JavaSample
2.In the SIMExtractInsert.java, modify the slot and hsmPass variables appropriately.
3.Compile the sample using javac:
javac SIMExtractInsert.java
4.Run the sample using java.
High Availability
Replication of objects in HA is accomplished by SIMExtract and SIMInsert in one call, transparently.
TIP Turn off HA synchronization for better performance if the inserted keys are to be used for single operations. An inserted key would be replicated to all HA group members even if it were to be used only by one member for (say) one signing operation.
If inserted keys are likely to be used for multiple load-balanced operations, then the overhead of replicating to all members is unavoidable and would be minimal in that context.
OPTIONS for HA Operation are:
>Use with V0 partitions. The assumption is that you have existing partitions and application(s) that use those partitions in HA. Continue as you already do. Your pre-existing upgraded partitions, as well as any new partitions that you create with the V0 option will work as before.
>Use with V1 partitions - all HA group members must be at V1, and your application must be SKS-aware, because only SMKs are cloned between V1 partitions; all other objects are extracted/inserted as SKS blobs.
Constraints on SKS HA
HA for SKS requires that each member of the HA group must have the same SMK.
NOTE For HA environments, if you perform SMK rollover on a member, then the new SMK must be cloned to all members. However, database / repository update for rollover should be done by directly addressing the primary physical member, and not using the virtual slot (to avoid the performance penalty when keys inserted to the virtual slot during rollover would be propagated to all members before the re-extraction).
Replicating the SMK to all group members
CAUTION! Each SKS partition contains a single SMK, and this operation overwrites the SMK in the target partition. Therefore, always ensure that the SMK in the target partition is not of any use, or that it has been backed up, before you perform partition smkclone.
These steps are performed from the lunacm utility in the client computer.
1.Use slot set to select one of the HSM partitions, with the desired SMK, as the current slot.
lunacm:> slot set -slot 0 Command Result : No Error
2.Log into the current slot as Crypto Officer.
lunacm:> role login -name Crypto Officer
Please attend to the PED.
Command Result : No Error
3.Use the partition smkclone operation to clone the desired SMK from the current slot SKS partition to another SKS partition in a named slot. The SMK from the source slot overwrites the SMK in the target slot. You are logged into the source partition, where you are launching this command, but not to the target partition; specify the password for the target partition.
partition smkclone -slot 1 -password userpin Logging in to target slot 1 Cloning the SMK. The SMK was cloned successfully. Command Result : No Error
To verify that the SMKclone operation was successful, see below.
4.Repeat the previous step for any other HA group members, to ensure that all members share the same SMK.
5.Set HA-only mode for the group, so that your application sees only the HA virtual slot, and not any of the physical slots.
lunacm:> haGroup HAOnly -enable Command Result : No Error
6.Note the number of the HA virtual slot. Your application will direct all operations to that slot.
Verify SMKclone
If necessary, verify the success of the SMKclone operation as follows.
1.Create an object on the original HSM partition (for example, a keypair).
2.SIMExport the object from that original HSM and SIMInsert it into the second (target) HSM, using any of the methods (API, CKDemo, or Java, earlier on this page). If the importation is successful, then the SMK on the second HSM is the same as the SMK on the first, or source HSM.
When NOT to address the virtual slot
As indicated above, blob insertion results in the inserted key being propagated to the other HA members.
However, key external storage database rollover should not be done over the virtual slot as this would cause the inserted keys to be propagated before the re-extraction, affecting performance. Ideally, the database update should be done by direct communication with the primary HA member.
