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. Each Luna HSM Client can manage up to 3500 keyrings, which can be spread across multiple clusters. Using lnh_cluster-1.0.4 or older, keyrings can contain up to 256 objects; newer versions do not have this limitation.
>Assigning Keyrings to a Registered Client
>Changing Client Assignment Mode on the Cluster
>Unassigning Keyrings From a Registered Client
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, or minimum Luna Appliance Software 7.9.0 with the lnh_cluster-1.0.5 package, Luna HSM Firmware 7.8.4, and Luna HSM Client 10.8.0 to migrate keys from Luna application partitions.
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 using REST API
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 cluster partition. 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. Each Luna HSM Client can manage up to 3500 keyrings, which can be spread across multiple clusters. Using lnh_cluster-1.0.4 or older, keyrings can contain up to 256 objects; newer versions do not have this limitation.
{
"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 using LunaSH
1.Create keyrings on the cluster by specifying its label and initial password, and the label and CO password/PED key for the cluster partition. 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. Each Luna HSM Client can manage up to 3500 keyrings, which can be spread across multiple clusters. Using lnh_cluster-1.0.4 or older, keyrings can contain up to 256 objects; newer versions do not have this limitation.
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>
Assigning Keyrings to a Registered Client
Use this procedure to assign keyrings to a registered client using REST API or LunaSH. The cluster must be configured in manual assignment mode. Refer to Client Assignment Modes for more information. You can assign a keyring to multiple clients; only clients that have been assigned the keyring will be able to see it as a slot in LunaCM.
NOTE This feature requires Luna Appliance Software 7.9.0 or newer with the lnh_cluster-1.0.5 package or newer installed.
REST API
To assign keyrings to a registered client using REST API
1.[Optional] List the keyrings available on the cluster. Each individual keyring is listed along with its UUID.
2.[Optional] List the clients registered to the cluster. Each client is listed along with its UUID.
GET /api/clusters/{clusterID}/clients
3.Assign keyrings to a client by specifying the client's UUID, and a list of up to 6 keyring UUID strings.
PATCH /api/cluster/client/{clientID}
{
"action": "assign",
"keyringList": [
"27aac110-f185-4f58-a5e4-929a68fda572",
"44f8d5f5-db53-4e0c-892b-3167f0648960",
"56271eb0-8a0d-4d7c-b739-02cd65ff6c42"
]
}
Log in to LunaCM on the client to see the newly-assigned keyring slots. The client can now proceed with Configuring Keyring Roles.
4.[Optional] Display a list of keyrings assigned to the client by specifying the cluster UUID and the client UUID.
GET /api/clusters/{clusterID}/clients/{clientID}?detail=true
LunaSH
To assign a keyring to a registered client using LunaSH
1.[Optional] Display the cluster's UUID.
lunash:> cluster list
2.[Optional] List the keyrings available on the cluster. Each individual keyring is listed along with its UUID.
lunash:> keyring list
3.[Optional] List the clients registered to the cluster. Each client is listed along with its UUID.
lunash:> cluster client list -clusterid <UUID>
4.Assign keyrings to a client by specifying the client's UUID, and a colon-separated list of up to 6 keyring UUIDs.
lunash:> cluster client assign -clientid <UUID> -keyringlist <string>
NOTE To assign or unassign more than 6 keyrings at a time, use the cluster REST API (see PATCH /api/cluster/client/{clientID}).
Log in to LunaCM on the client to see the newly-assigned keyring slots. The client can now proceed with Configuring Keyring Roles.
5.[Optional] Display information about the client, including the -detail option to see a list of keyrings assigned to the client.
lunash:> cluster client show -clusterid <UUID> -clientid <UUID> -detail
Changing Client Assignment Mode on the Cluster
When configuring the Luna Network HSM 7 to host or join a cluster, you selected the client assignment mode:
>Auto-Assignment Mode (default): In this mode, keyrings are automatically assigned to all registered clients; all keyrings on the cluster are visible in LunaCM on any registered client.
>Manual Assignment Mode: In this mode, keyrings must be manually assigned to or unassigned from registered clients. Clients are only able to see keyrings which have been assigned to them. Keyrings can be assigned to multiple clients.
If you want to change this setting later, you can do so using REST API or LunaSH.
REST API
To change the client assignment mode using REST API
1.On the primary cluster member, set the new mode by specifying the core service and either manual or auto for the client assignment mode.
{
"service": "core",
"clientAssignment": "<manual/auto>"
}
2.Restart the cluster service on any member of the cluster to apply the change (serviceid: cluster, actionid: restart). To prevent a temporary read/write service interruption, Thales recommends restarting the service on a non-primary member. The change is automatically synchronized to the other members of the cluster.
POST /api/lunasa/services/{serviceid}/actions/{actionid}
NOTE After the cluster service is restarted:
>If you changed from manual to auto mode, all keyrings become available to all registered clients. If you do not restart the cluster service, the original client assignments remain and only new keyrings will be automatically assigned to all clients.
>If you changed from auto to manual mode, all keyrings keep their previous client assignments. You must manually unassign keyrings from clients that should not have access to them (see Unassigning Keyrings From a Registered Client). New keyrings must be manually assigned (see Assigning Keyrings to a Registered Client).
LunaSH
To change the client assignment mode using LunaSH
1.On the primary cluster member, set the new mode by specifying the core service and either manual or auto for the client assignment mode.
lunash:> cluster config set -service core -clientAssignment <mode>
2.Restart the cluster service on any member of the cluster to apply the change. To prevent a temporary read/write service interruption, Thales recommends restarting the service on a non-primary member. The change is automatically synchronized to the other members of the cluster.
lunash:> service restart cluster
NOTE After the cluster service is restarted:
>If you changed from manual to auto mode, all keyrings become available to all registered clients. If you do not restart the cluster service, the original client assignments remain and only new keyrings will be automatically assigned to all clients.
>If you changed from auto to manual mode, all keyrings keep their previous client assignments. You must manually unassign keyrings from clients that should not have access to them (see Unassigning Keyrings From a Registered Client). New keyrings must be manually assigned (see Assigning Keyrings to a Registered Client).
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 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. If you configured the cluster in single-identity mode, ensure that you set the same password for this role that you set for the KRSO (see Keyring Roles and Identity Modes for more information).
lunacm:> role init -name co
5.Using lnh_cluster-1.0.5 or newer, if you have configured the cluster for dual-identity mode, the KRSO password must now be changed to enforce role separation between the KRSO and the KRCO.
lunacm:> role login -name co
lunacm:> role changepw -name co
The KRCO can now use the keyring for key creation and most cryptographic operations, just as you would a standard Luna application partition.
Unassigning Keyrings From a Registered Client
Use this procedure to unassign keyrings from a registered client using REST API or LunaSH. The cluster must be configured in manual assignment mode. Refer to Client Assignment Modes for more information.
NOTE This feature requires Luna Appliance Software 7.9.0 or newer with the lnh_cluster-1.0.5 package or newer installed.
REST API
Prerequisites
>Ensure that none of this client's applications are running operations on the keyring(s) you unassign. Client requests will be interrupted.
To unassign keyrings from a registered client using REST API
1.[Optional] Display a list of keyrings assigned to the specified client by specifying the cluster UUID and the client UUID.
GET /api/clusters/{clusterID}/clients/{clientID}?detail=true
2.Unassign keyrings from the client by specifying the client's UUID, and a list of up to 6 keyring UUID strings.
PATCH /api/cluster/client/{clientID}
{
"action": "unassign",
"keyringList": [
"27aac110-f185-4f58-a5e4-929a68fda572",
"44f8d5f5-db53-4e0c-892b-3167f0648960",
"56271eb0-8a0d-4d7c-b739-02cd65ff6c42"
]
}
The client can no longer access the specified keyring(s).
3.[Optional] Display a list of keyrings assigned to the client.
GET /api/clusters/{clusterID}/clients/{clientID}?detail=true
LunaSH
Prerequisites
>Ensure that none of this client's applications are running operations on the keyring(s) you unassign. Client requests will be interrupted.
To unassign keyrings from a registered client using LunaSH
1.[Optional] Display a list of keyrings assigned to the specified client.
lunash:> cluster client show -clusterid <UUID> -clientid <UUID> -detail
2.Unassign keyrings from the client by specifying the client's UUID, and a colon-separated list of up to 6 keyring UUIDs.
lunash:> cluster client unassign -clientid <UUID> -keyringlist <string>
NOTE To assign or unassign more than 6 keyrings at a time, use the cluster REST API (see PATCH /api/cluster/client/{clientID}).
The client can no longer access the specified keyring(s).
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 using REST API
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 using LunaSH
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>]
