Migrating Keys From Application Partitions to Keyrings
Use the following procedures to migrate keys from standard Luna application partitions to Luna keyrings on a cluster using REST API or LunaSH. Ensure that all the Prerequisites are met before you begin. This procedure requires the involvement of the following security roles:
>For the cluster partition (see The Cluster Partition):
•Partition SO
•Crypto Officer
>For the migrating partition:
•Partition SO
•Crypto Officer
>For the target keyring:
•Keyring Crypto Officer (KRCO)
NOTE You must have 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.
Prerequisites
The following prerequisites apply to both the REST API and LunaSH procedures:
>The Luna Network HSM 7 that hosts the migrating partition must be ready to host a cluster configured in dual-identity mode (see Installing and Configuring the Cluster Package).
>The Luna Network HSM 7 that hosts the migrating partition must be an authorized member of a cluster (see Creating a Cluster or Joining a New Member to an Existing Cluster).
>The Cryptographic Module time must be synchronized to the appliance time (lunash:> hsm time sync).
>Key objects to be migrated may not have Per-Key Authorization attributes defined.
NOTE If your organization uses Per-Key Authorization, you cannot migrate to keyrings in this release.
>If the migrating partition was initialized with a different domain than the cluster partition, both partitions must have partition policy 44: Allow Extended Domain Management set to 1.
>A Luna HSM Client must be registered to the cluster member (see Connecting Luna HSM Client to a Cluster).
>The keyring(s) that will receive the migrated objects must exist (see Creating New Keyrings), with the KRSO and KRCO roles initialized and the initial passwords changed (see Configuring Keyring Roles).
>All client applications using the migrating partition must be stopped.
>If the partition is part of an HA group (see High-Availability Groups), Thales recommends removing it from the group and verifying that it contains everything you want to migrate before proceeding.
CAUTION! During the migration procedure, Cluster Backup and Restore is not supported. Do not attempt to back up or restore the cluster until migration is complete.
REST API
In addition to the prerequisites listed above, there may be additional steps required to prepare the partition for migration. These requirements depend on the partition type (V0 and V1 Partitions) and the state of partition policy 40: Require Per-Key Authorization Data:
>Migrating From a V0 Partition
>Migrating From a V1 Partition with Policy 40 On
>If the migrating partition is a V1 partition with policy 40 turned off, proceed directly to Migrating From a Luna Partition to Keyrings.
Migrating From a V0 Partition
To migrate keys from a V0 partition, you must first convert the partition to V1.
CAUTION! Since this policy is destructive ON-to-OFF, this change is reversible only by restoring keys from backup. Thales recommends that you back up the partition before proceeding (see Partition Backup and Restore).
To prepare the partition to migrate keys to a Luna keyring using REST API
1.Convert the migrating partition to V1 by setting partition policy 41: Partition Version to 1 (policyid: 41).
PATCH /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/{policyid})
2.Log in as Partition SO once to complete the V0 to V1 conversion.
POST /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/login
3.Restart the cluster service on the appliance (serviceid: cluster, actionid: restart)
POST /api/lunasa/services/{serviceid}/actions/{actionid}
4.Check the status of the cluster service ("status": "running"). It may take several minutes for the cluster service to start, and the next step will fail if it is still starting up. This resource reports "status": "stopped" until the cluster service startup has finished.
GET /api/lunasa/services/{serviceid}
5.You may now begin the migration using the procedure for Migrating From a Luna Partition to Keyrings.
Migrating From a V1 Partition with Policy 40 On
To migrate keys from a V1 partition with partition policy 40: Require Per-Key Authorization Data set to 1, you must first back up the keys to a Luna Backup HSM, and restore them after setting this policy to 0.
To prepare the partition to migrate keys to a Luna keyring using REST API
1.Back up the contents of the migrating partition to a Luna Backup HSM. This step must be done using LunaCM at the client. Refer to the appropriate procedure for your hardware/client configuration (see Backup HSM Connected to the Client Workstation for options).
2.Change partition policy 40:Require Per-Key Authorization Data to 0 (policyid: 40).
PATCH /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/{policyid})
3.Restore the partition from the backup you made in step 1. This step must be done using LunaCM at the client. Refer to the appropriate procedure for your hardware/client configuration (see Backup HSM Connected to the Client Workstation for options).
4.You may now begin the migration using the procedure for Migrating From a Luna Partition to Keyrings.
Migrating From a Luna Partition to Keyrings
To migrate all objects from a Luna application partition to a Luna keyring using REST API
1.[Optional] Display a list of the partitions on the Luna Network HSM 7 and their UUIDs.
GET /api/cluster/member/partitions
2.Begin the migration process by providing the Partition SO and Crypto Officer credentials for the cluster partition and the migrating partition. This command copies the cluster SMK to the migrating partition.
PUT /api/clusters/{clusterID}/member/partitions/{partitionID}/migration
{
"migratingAuthentication": [
{
"type": "PO",
"password": "IamtheMigratingPO"
},
{
"type": "CO",
"password": "IamtheMigratingCO"
}
],
"clusterAuthentication": [
{
"type": "PO",
"password": "IamtheClusterPO"
},
{
"type": "CO",
"password": "IamtheClusterCO"
}
],
"action": "begin"
}
3.[Optional] Display a list of keyrings on the cluster and their UUIDs.
4.[Optional] Display a list of objects stored on the migrating partition and their OUIDs.
GET /api/cluster/member/partitions/{partitionID}/objects
{
"authentication":[
{
"type": "CO",
"password": "IamtheMigratingCO"
}
]
}
5.Migrate objects to the target keyring by specifying the migrating partition CO credential, the target keyring UUID and KRCO credential, and a list of the object OUIDs to be migrated to the keyring. You can include up to 1000 objects in a single request.
PUT /api/cluster/member/partitions/{partitionID}/objects
{
"migratingPartitionCoAuth": [
{
"type": "CO",
"password": "IamtheCO"
}
],
"keyringCoAuth": [
{
"type": "CO",
"password": "IamtheKRCO"
}
],
"keyringId": "2e5b8419-7a78-43d8-891f-fbe03cb085ff",
"objectID": [
"5e1a00001d0000011b030100",
"5d1a00001d0000011b030100",
"5c1a00001d0000011b030100",
"5b1a00001d0000011b030100",
"301a00001d0000011b030100",
"2f1a00001d0000011b030100"
],
"action": "assign"
}
6.[Optional] Display a list of objects stored on the migrating partition and their OUIDs. Entries for objects that have been migrated are now returned with the label of the keyring they migrated to ("keyringLabel": "<target_keyring_label>").
GET /api/cluster/member/partitions/{partitionID}/objects
{
"authentication":[
{
"type": "CO",
"password": "IamtheMigratingCO"
}
]
}
7.End the migration process by providing the Partition SO and Crypto Officer credentials for the migrating partition. This command deletes the cluster SMK from the migrating partition. This step is important for security reasons; do not leave copies of the cluster SMK on partitions unnecessarily.
PUT /api/clusters/{clusterID}/member/partitions/{partitionID}/migration
{
"migratingAuthentication": [
{
"type": "PO",
"password": "IamtheMigratingPO"
},
{
"type": "CO",
"password": "IamtheMigratingCO"
}
],
"action": "end"
}
LunaSH
In addition to the prerequisites listed above, there may be additional steps required to prepare the partition for migration. These requirements depend on the partition type (V0 and V1 Partitions) and the state of partition policy 40: Require Per-Key Authorization Data:
>Migrating From a V0 Partition
>Migrating From a V1 Partition with Policy 40 On
>If the migrating partition is a V1 partition with policy 40 turned off, proceed directly to Migrating From a Luna Partition to Keyrings.
Migrating From a V0 Partition
To migrate keys from a V0 partition, you must first convert the partition to V1.
CAUTION! Since this policy is destructive ON-to-OFF, this change is reversible only by restoring keys from backup. Thales recommends that you back up the partition before proceeding (see Partition Backup and Restore).
To prepare the partition to migrate keys to a Luna keyring using LunaSH
1.Convert the migrating partition to V1 by setting partition policy 41: Partition Version to 1.
lunash:> partition changePolicy -partition <name> -policy 41 -value 1
2.Log in to the migrating partition as Partition SO once to complete the V0 to V1 conversion. You must use LunaCM at the client for this step.
lunacm:> role login -name po
3.Restart the cluster service on the appliance.
lunash:> service restart cluster
4.Check the status of the cluster service (running). It can take up to 1-2 minutes for the cluster service to start. Until startup is complete, the status is reported as starting.
lunash:> cluster status
5.You may now begin the migration using the procedure for Migrating From a Luna Partition to Keyrings.
Migrating From a V1 Partition with Policy 40 On
To migrate keys from a V1 partition with partition policy 40: Require Per-Key Authorization Data set to 1, you must first back up the keys to a Luna Backup HSM, and restore them after setting this policy to 0.
To prepare the partition to migrate keys to a Luna keyring using LunaSH
1.Back up the contents of the migrating partition to a Luna Backup HSM. This step must be done using LunaCM at the client. Refer to the appropriate procedure for your hardware/client configuration (see Backup HSM Connected to the Client Workstation for options).
2.Change partition policy 40: Require Per-Key Authorization Data to 0.
lunash:> partition changePolicy -partition <name> -policy 40 -value 0
3.Restore the partition from the backup you made in step 1. This step must be done using LunaCM at the client. Refer to the appropriate procedure for your hardware/client configuration (see Backup HSM Connected to the Client Workstation for options).
4.You may now begin the migration using the procedure for Migrating From a Luna Partition to Keyrings.
Migrating From a Luna Partition to Keyrings
To migrate objects from a Luna application partition to a Luna keyring using LunaSH
1.[Optional] Display a list of the partitions on the Luna Network HSM 7 and their UUIDs. To list partitions on a different cluster member, specify its member UUID.
lunash:> cluster member partition list [-memberid <UUID>]
2.Begin the migration process, specifying the UUID of the migrating partition. This command copies the cluster's SMK to the migrating partition. This step must be completed using LunaSH on the local cluster member, and then the migration process can be completed from any member of the cluster.
lunash:> cluster member partition migration begin -partitionid <UUID> [-copassword <password>] [-popassword <password>] [-clusterco <password>] [-clusterpo <password>]
If you did not specify them in the command line, you are prompted for the following credentials:
a.The Crypto Officer credential for the migrating partition
b.The Partition SO credential for the migrating partition
c.The Crypto Officer credential for the cluster partition
d.The Partition SO credential for the cluster partition
3.[Optional] Display a list of keyrings on the cluster and their UUIDs.
lunash: keyring list
4.[Optional] Display a list of objects stored on the migrating partition and their OUIDs.
lunash:> cluster member partition object list -partitionid <UUID>
5.Migrate objects to the target keyring by specifying the migrating partition UUID, the keyring UUID, and the object OUIDs. The object OUIDs can be specified in either:
• a colon-separated (:) list of up to 10 objects at a time, using the -objectid option
•a file with one OUID per line, using the -filename option
lunash:> cluster member partition object assign -partitionid <UUID> -keyringid <UUID> {-objectid <OUID(s)> | -filename <filename>} [-copassword <password>] [-keyringcopassword <password>]
If you did not specify them in the command line, you are prompted for the following credentials:
a.The Crypto Officer credential for the migrating partition
b.The KRCO password for the target keyring
6.[Optional] Display a list of objects stored on the migrating partition and their OUIDs. Entries for objects that have been migrated now include the Keyring Label field.
lunash:> cluster member partition object list -partitionid <UUID>
7.End the migration process, specifying the UUID of the migrating partition. This command deletes the cluster's SMK from the migrating partition. This step is important for security reasons; do not leave copies of the cluster SMK on partitions unnecessarily.
lunash:> cluster member partition migration end -partitionid <UUID> [-copassword <password>]
If you did not specify it in the command line, you are prompted for the migrating partition's Crypto Officer credential.
