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 3500 keyrings can be created on the cluster, and each keyring can contain up to 256 objects. Each Luna HSM Client can manage up to 3500 keyrings, which can be spread across multiple clusters.
NOTE Thales requires minimum Luna Appliance Software 7.8.5 with the lnh_cluster-1.0.4 package, Luna HSM Firmware 7.8.4, and Luna HSM Client 10.7.2 to use clusters in production environments.
Creating New Keyrings
Use this procedure to create new keyrings on an existing cluster using REST API or LunaSH.
REST API
Prerequisites
>If you are creating keyrings on a multifactor quorum-authenticated HSM cluster, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.
To create new keyrings
1.Create keyrings on the cluster by specifying a label and initial password, and the label and CO password (or "password": "" and present the CO PED key) 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.
Up to 3500 keyrings can be created on the cluster, and each keyring can contain up to 256 objects. Each Luna HSM Client can manage up to 3500 keyrings, which can be spread across multiple clusters.
{
"authentication": [
{
"type": "CO",
"password": "IamtheCO",
"partitionLabel": "clusterpar"
}
],
"keyRingLabel": "myKeyring",
"keyRingPassword": "keyringpassword",
"total": 10,
"index": 100
}
2.[Optional] List the keyrings available on the cluster. Each individual keyring is listed along with its UUID.
3.[Optional] Display the attributes for an individual keyring by specifying its UUID.
You must now use LunaCM on the Luna HSM Client machine to configure the keyring for cryptographic applications. See Configuring Keyring Roles.
LunaSH
Prerequisites
>If you are creating keyrings on a multifactor quorum-authenticated HSM cluster, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.
To create new keyrings
1.Create keyrings on the cluster by specifying its label and initial password, and the label and CO password/PED key 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.
Up to 3500 keyrings can be created on the cluster, and each keyring can contain up to 256 objects. Each Luna HSM Client can manage up to 3500 keyrings, which can be spread across multiple clusters.
lunash:> keyring create -label <label> -password <password> -partition <partition_label> -total <number> -index <number> [-copassword <password>]
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 Unlike the PSO and CO roles on standard Luna partitions, the KRSO and KRCO roles on each keyring are intended to be held by the same individual, and use the same password. When the password for one role is changed, the change is applied to the other role as well. Consider this distinction when planning your cluster deployment and setting your KRSO passwords.
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 {-keyringid <string> | -label <name>} [-copassword <password>]
>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
Prerequisites
>If you are deleting keyrings on a multifactor quorum-authenticated HSM cluster, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.
To delete a keyring
1.[Optional] List the keyrings available on the cluster. Each individual keyring is listed along with its UUID.
2.Delete the keyring by specifying either its label or UUID, and the CO password (or "password": "" and present the CO PED key) for the cluster partition.
DELETE /api/keyrings/{keyringID}
{
"authentication": [
{
"type": "CO",
"password": "IamtheCO"
}
]
}
LunaSH
Prerequisites
>If you are deleting keyrings on a multifactor quorum-authenticated HSM cluster, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.
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/PED key for the cluster partition.
lunash:> keyring delete {-label <keyringlabel> | -keyringid <UUID>} [-copassword <password>]
