Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

ProtectServer HSM migration

Migrating keys from ProtectServer 2 HSMs to ProtectServer 3 HSMs

search

Migrating keys from ProtectServer 2 HSMs to ProtectServer 3 HSMs

This section describes how to migrate keys from ProtectServer 2 HSMs to ProtectServer 3 HSMs.

You can migrate keys by backing up ProtectServer 2 HSM tokens to a file or smart card and then restoring them on ProtectServer 3 HSMs, or by replicating the ProtectServer 2 HSM tokens onto the ProtectServer 3 HSMs. Backup and restore procedures should be followed if none of the keys that must be migrated have their CKA_EXPORTABLE and CKA_MODIFIABLE attributes set to FALSE, while token replication should be used when some of the keys that must be migrated have their CKA_EXPORTABLE and CKA_MODIFIABLE attributes set to FALSE.

For detailed procedures, refer to the following subsections:

Migrating keys using backup and restore

This subsection describes how to migrate keys from ProtectServer 2 HSMs to ProtectServer 3 HSMs using backup and restore. There are four recommended backup and restore methods. First, refer to the Prerequisites that apply to all of the procedures and then refer to one of the four following procedures:

Note

Smart card migration procedures can be performed with any smart card that is supplied by Thales with a ProtectServer Internal Express/ProtectServer External HSM or ProtectServer Internal Express 2/ProtectServer External 2/ProtectServer External 2+ HSM.

Prerequisites

Before you begin any of the following procedures, you must satisfy the prerequisites described below. Additional procedure-dependent prerequisites, where applicable, are described before each procedure.

  • Consider your existing ProtectToolkit 5 client configuration and how you want to transition to ProtectToolkit 7. Thales recommends migrating by using two separate client machines, so that you can ensure that the migration procedure is complete before transitioning your applications to the new client and HSM:

    • ProtectToolkit 5 client connected to connected to the ProtectServer 2 HSMs.

    • ProtectToolkit 7 client connected to connected to the ProtectServer 3 HSM}s.

    You cannot use ProtectToolkit 5 with ProtectServer 3 HSMs. Thales recommends that you complete the backup portion of the migration procedure first with ProtectToolkit 5, upgrade your client software to ProtectToolkit 7 and provision your ProtectServer 3 HSM (or alternatively use a version of ProtectToolkit 7 that you have installed on another system), and finally perform the restore portion of the migration procedure.

  • Ensure that you have initialized the ProtectServer 3 Admin token and one or more User tokens to accept the migrated keys (For more information about token initialization, see Initial configuration).

  • The following migration scenarios use the key export function, and require all keys being migrated to have the attribute CKA_EXPORTABLE=TRUE. If any of your keys are not exportable, you must first change the attribute using ctkmu m. For more information, refer to ctkmu.

    • If a key has the attributes CKA_EXPORTABLE=FALSE and CKA_MODIFIABLE=FALSE, it cannot be migrated using this procedure. Refer to Migrating keys using token replication instead.

    • If a key has the attributes CKA_EXPORTABLE=TRUE and CKA_EXTRACTABLE=FALSE, you must log on as Security Officer (SO) to perform the migration operation.

Backup to file and restore

In this procedure, you will back up a ProtectServer 2 HSM token to an encrypted file on your ProtectToolkit client machine, and restore it to your new ProtectServer 3 token.

To migrate keys by backing up to a file and restoring to the new HSM

  1. Using the ProtectToolkit 5 client, create a wrapping key on the source token by entering key components. You can assign whatever key attributes you prefer, but sign, verify, wrap, and unwrap are all required (-k SVWU).

    ctkmu c -t<keytype> -n<wrapping_keyname> -a<attributes> -k<#_of_components> -z<keysize>

    ]# ctkmu c -t AES -nAES_WRAP -a EDSVWUXT -u0000 -k 2 -z256
ProtectToolkit C Key Management Utility
Copyright (c) Safenet, Inc. 2009-2020

Enter Key Component 1 (Need to enter 64 HEX chars): 0832240A34365AEB8273A6535EF80FA99CB5FCE8D2A19EE1977CB8D664F86968
Component 1  KCV : 9C1884
Is this correct? [Y/n]: y

Enter Key Component 2 (Need to enter 64 HEX chars): 263FF91EE9C7A5ECC58AFFA35B4F6A5443F0DA3B5ABE60FB45260AEA8C9458F7
Component 2  KCV : 62A639
Is this correct? [Y/n]: Y

Key 'AES_256' KCV : 97498B
Is this correct? [Y/n]: Y

Key "AES_256" was created

  2. Export all objects stored on the token to an encrypted file on the ProtectToolkit 5 client, using the new wrapping key.

    Note

    If you are migrating DH_PARAM or DSA_PARAM objects, include the -4 option when exporting the stored objects.

    ctkmu x -s<slotnum> -w<wrapping_keyname> <backup_filename> [-4]

  3. Securely transfer the wrapped file to the ProtectToolkit 7 client machine.

  4. Using the ProtectToolkit 7 client, recreate the wrapping key on the destination token by entering the same key components.

    ctkmu c -t<keytype> -n<wrapping_keyname> -a <attributes> -k<#_of_components> -z<keysize> [-4]

  5. Import the wrapped file to the ProtectToolkit 7 token using the new wrapping key.

    ctkmu i -s<slotnum> -w<wrapping_keyname> <backup_filename>

Backup to single-custodian smart card and restore

In this procedure, you will back up a ProtectServer 2 HSM token to a smart card and restore it to your new ProtectServer 3 token. The single-custodian scheme requires you to create and specify a wrapping key to encrypt the cryptographic objects.

Prerequisites

  • Ensure that both the source and destination HSMs have a smart card reader installed.

  • Ensure that you have enough blank smart cards available to store all objects on the token.

To migrate keys by backing up to a single-custodian smart card

  1. Using the ProtectToolkit 5 client, create a wrapping key on the source token by entering key components. You can assign whatever key attributes you prefer, but sign, verify, wrap, and unwrap are all required (-k SVWU).

    ctkmu c -t<keytype> -n<wrapping_keyname> -a<attributes> -k<#_of_components> -z<keysize>

  2. Insert a blank smart card into the ProtectServer 2 HSM reader, and export all objects stored on the token to the smart card, using the new wrapping key.

    Note

    If you are migrating DH_PARAM or DSA_PARAM objects, include the -4 option when exporting the stored objects.

    ctkmu x -s<slotnum> -w<wrapping_keyname> -c<SC_reader_slotnum> [-4]

  3. Using the ProtectToolkit 7 client, recreate the wrapping key on the destination token by entering the same key components.

    ctkmu c -t<keytype> -n<wrapping_keyname> -a<attributes> -k<#_of_components> -z<keysize>

  4. Restore the contents of the smart card(s) to the destination ProtectServer 3 token by specifying the unwrapping key.

    ctkmu i -s<slotnum> -w<wrapping_keyname> -c<SC_reader_slotnum>

Backup to multiple-custodian smart cards and restore

In this procedure, you will back up a ProtectServer 2 HSM token to smart cards held by multiple custodians in a standard key-splitting scheme, and restore it to your new ProtectServer 3 token.

Prerequisites

  • Ensure that both the source and destination HSMs have a smart card reader installed.

  • Ensure that you have enough blank smart cards available to store all objects on the token.

  • You require a minimum of two custodians to use the standard key-splitting scheme.

  • You must set the Weak Mechanisms flag to ON to use this backup method (For more information about this security flag, see Security Flags).

To migrate keys by backing up to multiple-custodian smart cards

  1. Insert a blank smart card into the ProtectServer 2 HSM reader, and use the ProtectToolkit 5 client to export splits of all objects stored on the source token to the smart card.

    Note

    If you are migrating DH_PARAM or DSA_PARAM objects, include the -4 option when exporting the stored objects.

    ctkmu x -s<slotnum> -c<SC_reader_slotnum> [-4]

  2. Follow the prompts to complete the backup using the multiple-custodian scheme.

  3. Use the ProtectToolkit 7 client to restore the contents of the smart cards to the destination ProtectServer 3 token.

    ctkmu i -s<slotnum> -c<SC_reader_slotnum>

Backup to N of M custodian smart cards and restore

In this procedure, you will back up a ProtectServer 2 HSM token to smart cards held by multiple custodians in an N of M key-splitting scheme, and restore it to your new ProtectServer 3 token.

Prerequisites

  • Ensure that both the source and destination HSMs have a smart card reader installed.

  • Ensure that you have enough blank smart cards available to store all objects on the token.

  • You require a minimum of three custodians to use the N of M key-splitting scheme, with a minimum of two required to restore keys to the destination token.

To migrate keys by backing up to multiple-custodian smart cards in an N of M scheme

  1. Insert a blank smart card into the ProtectServer 2 HSM reader, and use the ProtectToolkit 5 client to export splits of all objects stored on the source token to the smart card, specifying the N of M scheme.

    Note

    If you are migrating DH_PARAM or DSA_PARAM objects, include the -4 option when exporting the stored objects.

    ctkmu x -s<slotnum> -c<SC_reader_slotnum> -M [-4]

  2. Follow the prompts to complete the backup using the N of M multiple-custodian scheme. N cannot be equal to M.

  3. Use the ProtectToolkit 7 client to restore the contents of the smart cards to the destination ProtectServer 3 token by presenting cards from the minimum (N) number of custodians.

    ctkmu i -s<slotnum> -c<SC_reader_slotnum>

Migrating keys using token replication

This subsection describes how to migrate keys from a ProtectServer 2 HSM to a ProtectServer 3 HSM by using token replication. First, refer to the Prerequisites and then refer to the following procedures in order:

  1. Establish mutual trust between the ProtectServer 2 HSM and ProtectServer 3 HSM

  2. Replicate the token from the source slot on the ProtectServer 2 HSM to the destination slot on the ProtectServer 3 HSM

Prerequisites

Before you migrate keys using token replication, you must satisfy the prerequisites described below.

1. Establish mutual trust between the ProtectServer 2 HSM and ProtectServer 3 HSM

Note

This procedure assumes that tokens on one ProtectServer 2 HSM are being replicated to one ProtectServer 3 HSM. Refer to <targets> and <peers> for information about the values that should be used for these ptk7tokmigration command arguments in migration scenarios that involve multiple ProtectServer 2 HSMs or multiple ProtectServer 3 HSMs.

  1. On the ProtectToolkit 7 client, generate an HSM ID public key for the ProtectServer 3 HSM.

    ptk7tokmigration gen <targets>

    ptk7tokmigration gen sn:5678

  2. On the ProtectToolkit 7 client, copy the newly generated HSM ID public key to a public key file.

    ptk7tokmigration getid <targets> -p<pubkey>

    ptk7tokmigration getid sn:5678 -p/tmp/5678.pem

  3. On the ProtectToolkit 7 client, securely copy the newly created public key file from the ProtectToolkit 7 client machine to the ProtectToolkit 5 client machine.

    scp <ptk7/pem/file/path> <ptk5/pem/file/path>

    scp /tmp/HSMID_5678.pem PTK5client:/tmp/HSMID_5678.pem

  4. On the ProtectToolkit 5 client, instruct the ProtectServer 2 HSM to trust the HSM ID public key of the ProtectServer 3 HSM.

    ptk7tokmigration trust <targets> <peers> -p<pubkey>

    ptk7tokmigration trust sn:1234 sn:5678 -p/tmp/HSMID_5678.pem

  5. On the ProtectToolkit 5 client, verify that HSM ID public key of the ProtectServer 3 HSM is recognized by the ProtectServer 2 HSM.

    ptk7tokmigration list <targets> -tpeer

    ptk7tokmigration list sn:1234 -tpeer

    The preceding command outputs the HSM ID public key of the ProtectServer 3 HSM. Multiple keys are listed if the public key file contains the public keys of multiple ProtectServer 3 HSMs.

  6. On the ProtectToolkit 5 client, copy the HSM ID public key of the ProtectServer 2 HSM to a public key file.

    ptk7tokmigration getid <targets> -p<pubkey>

    ptk7tokmigration getid sn:1234 -p/tmp/HSMID_1234.pem

  7. On the ProtectToolkit 5 client, securely copy the newly created public key file from the ProtectToolkit 5 client machine to the ProtectToolkit 7 client machine.

    scp <ptk5/pem/file/path> <ptk7/pem/file/path>

    scp /tmp/HSMID_1234.pem PTK7client:/tmp/HSMID_1234.pem

  8. On the ProtectToolkit 7 client, instruct the ProtectServer 3 HSM to trust the the HSM ID public key of the ProtectServer 2 HSM.

    ptk7tokmigration trust <targets> <peers> -p<pubkey>

    ptk7tokmigration trust sn:5678 sn:1234 -p/tmp/HSMID_1234.pem

  9. On the ProtectToolkit 7 client, verify that HSM ID public key of the ProtectServer 2 HSM is recognized by the ProtectServer 3 HSM.

    ptk7tokmigration list <targets> -tpeer

    ptk7tokmigration list sn:5678 -tpeer

    The preceding command outputs the HSM ID public key of the ProtectServer 2 HSM. Multiple keys are listed if the public key file contains the public keys of multiple ProtectServer 2 HSMs.

Mutual trust has been established between the ProtectServer 2 HSM and ProtectServer 3 HSM. After establishing mutual trust, proceed to 2. Replicate the token from the source slot on ProtectServer 2 HSM to the destination slot on the ProtectServer 3 HSM.

2. Replicate the token from the source slot on the ProtectServer 2 HSM to the destination slot on the ProtectServer 3 HSM

  1. On the ProtectToolkit 5 client, create a token image file for the token that must be replicated.

    ctkmu xt -s<slot> -S<ps3_serial> <token_image_filename>

    ctkmu xt -s0 -S 5678 PSE2-token.bin

    Refer to ctkmu for information about creating a token image file from a ProtectServer 2 HSM token.

    Note

    The serial number of the ProtectServer 3 HSM that will import the token image is specified when creating the token image file.

    Tip

    If you are replicating multiple tokens, create a token image file for each source slot.

    If you are replicating a single token to multiple destination slots, which exist across multiple ProtectServer 3 HSMs, create a token image file for each ProtectServer 3 HSM.

  2. On the ProtectToolkit 5 client, securely copy the newly created token image file from the ProtectToolkit 5 client machine to the ProtectToolkit 7 client machine.

    scp <ptk5/token_image/file/path> <ptk7/token_image/file/path>

    scp /tmp/PSE2-token.bin PTK7client:/tmp/PSE2-token.bin

    Tip

    If you have created multiple token image files, copy every token image file from the ProtectToolkit 5 client machine to the ProtectToolkit 7 client machine.

  3. On the ProtectToolkit 7 client, import the copied token image file onto the ProtectServer 3 HSM.

    ptk7tokmigration it -s<slot> <token_image/file/path>

    ptk7tokmigration it -s1 /tmp/PSE2-token.bin

    Tip

    If you are replicating multiple tokens to one ProtectServer 3 HSM, import each token image file onto the ProtectServer 3 HSM.

    If you are replicating a single token to multiple destination slots, which exist across multiple ProtectServer 3 HSMs, import each token image file onto the ProtectServer 3 HSM that has a serial number that matches the serial number specified when the token image file was created in step 1.

    Note

    Import will fail if the serial number of the ProtectServer 3 HSM that is importing the token does not match the serial number that was specified when the token image file was created in step 1.

  4. Verify that you successfully replicated the token by running the following command on the ProtectToolkit 7 client, to display the contents of the destination slot, and ProtectToolkit 5 client, to display the contents of the source slot:

    ctkmu l -s<slot>

    ctkmu l -s0

    The contents of the destination slot on the ProtectServer 3 HSM should match the contents of the source slot on the ProtectServer 2 HSM.

If the contents of the slots match, you have successfully migrated keys from a ProtectServer 2 HSM to a ProtectServer 3 HSM using token replication.

On this page