Managing Keyrings
The procedures below will allow you to create a new keyring on a cluster, and configure it for use by a Luna HSM Client. Up to 3000 keyrings can be created on the cluster, and each keyring can contain up to 256 objects.
NOTE This feature requires Luna Network HSM Appliance Software 7.8.0 or newer, Luna HSM Firmware 7.8.0 or newer, and each appliance in the cluster must have the cluster secure package installed. Luna HSM Client 10.5.0 or newer is required to access keyrings on a cluster. This feature is currently available on password-authenticated Luna Network HSMs only.
Creating New Keyrings
Use this procedure to create new keyrings on an existing cluster using REST API or LunaSH.
REST API
To create new keyrings
1.Create keyrings on the cluster by specifying a label and initial password, and the label and CO password for the partition that will generate the keyrings. To create multiple keyrings (up to 100 at a time), specify the number to be created (total in --data). Each keyring will be given the specified label with an appended index number. You can use index in --data to specify the starting number for the group of keyrings.
You can currently create up to 3000 keyrings on the cluster.
POST /api/keyrings
curl -X POST "https://1.2.3.4:50070/api/keyrings" --data '{"authentication":[{"type": "CO","partitionLabel": "clusterpar","password": "iamtheCO"}],"keyRingLabel": "newkeyRing","keyRingPassword": "iamtheCO","index": "100","total": "10"}' -H "Content-Type: application/json" -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" --insecure
2.[Optional] List the keyrings available on the cluster. Each individual keyring is listed along with its UUID.
GET /api/keyrings
curl -X GET "https://1.2.3.4:50070/api/keyrings" -H "Content-Type: application/json" -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" --insecure
3.[Optional] Display the attributes for an individual keyring by specifying its UUID.
curl -X GET "https://1.2.3.4:50070/api/keyrings/d533441d-9c3f-403b-9280-6fc6ccaae338" -H "Content-Type: application/json" -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" --insecure
You must now use ckdemo on the Luna HSM Client machine to configure the keyring for cryptographic use. See Configuring Keyring Roles.
LunaSH
To create new keyrings
1.Create keyrings on the cluster by specifying its label and initial password, and the label and CO password for the partition that will generate the keyring. To create multiple keyrings (up to 100 at a time), specify the number to be created using the -total option. Each keyring will be given the specified label with an appended index number. You can use the -index option to specify the starting number for the group of keyrings.
You can currently create up to 3000 keyrings on the cluster.
lunash:> keyring create -label <label> -password <password> -partition <partition_label> -copassword <password> -total <number> -index <number>
2.[Optional] List the keyrings available on the cluster. Each individual keyring is listed along with its UUID.
lunash:> keyring list
3.[Optional] Display the attributes for an individual keyring by specifying its UUID.
lunash:> keyring show -keyringid <UUID>
Configuring Keyring Roles
Use this procedure to initialize the keyring roles required for creating and using objects on the keyring. The keyring has its own administrative roles, analogous to the Partition SO and Crypto Officer roles (see Partition Roles). For clarity, they are referred to here as the Keyring Security Officer (KRSO) and Keyring Crypto Officer (KRCO) roles, although they use the same commands as the partition roles. The procedure is intended to enforce role separation between the Keyring Security Officer and the Keyring Crypto Officer, the same way roles are separated on standard Luna HSM partitions.
This procedure uses LunaCM on a registered Luna HSM Client.
To configure roles on the keyring
1.Run LunaCM and confirm that all your created keyrings are available as slots. Note the slot number and label of the keyring you wish to configure.
2.The initial password you set during keyring creation belongs to the KRSO role (called the PO in LunaCM). Log in as KRSO.
lunacm:> role login -name po
3.The KRSO password must now be changed to enforce role separation between the cluster administrator and the keyring user.
lunacm:> role changepw -name po
NOTE While the KRSO and KRCO roles are separate, they are intended to be held by the same individual and they must therefore use the same password. Consider this when setting your KRSO password.
The KRCO password is what your applications will specify to access the keyring and create and use objects. Thales recommends that you always use the most secure password possible. The length of your KRSO/KRCO password affects the behavior of the keyring as follows:
>If the KRCO password is 16 characters or shorter, the keyring is locked after 10 failed login attempts and must be unlocked before it can be used again:
PATCH /api/keyrings/{keyringid}
lunash:> keyring unlock -copassword <password> {-keyringid <string> | -label <name>}
>If the KRCO password is 17 characters or longer, the lockout counter is not incremented.
Failed login attempts using 6 characters or less never increment the counter.
4.Initialize the KRCO role on the keyring. Ensure that you set the same password for this role that you set for the KRSO.
lunacm:> role init -name co
The KRCO can now log in and use the keyring for key creation and most cryptographic operations, just as you would a standard Luna application partition.
Deleting a Keyring
Use this procedure to delete a keyring using REST API or LunaSH.
REST API
To delete a keyring
1.[Optional] List the keyrings available on the cluster. Each individual keyring is listed along with its UUID.
GET /api/keyrings
curl -X GET "https://1.2.3.4:50070/api/keyrings" -H "Content-Type: application/json" -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" --insecure
2.Delete the keyring by specifying either its label or UUID, and the CO password for the cluster partition.
DELETE /api/keyrings/{keyringid}
curl -X DELETE "https://1.2.3.4:50070/api/keyrings/d533441d-9c3f-403b-9280-6fc6ccaae338" -H "Content-Type: application/json" -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" --insecure
LunaSH
To delete a keyring
1.[Optional] List the keyrings available on the cluster. Each individual keyring is listed along with its UUID.
lunash:> keyring list
2.Delete the keyring by specifying either its label or UUID, and the CO password for the cluster partition.
lunash:> keyring delete -copassword <password> [-label <keyringlabel> | -keyringid <UUID>]
