7.6.4.2. Case II: Security Databases to HSM Migration

Remove all the security databases in the new Certificate System which will receive migrated data.
```
rm /var/lib/instance_ID/alias/cert8.db

rm /var/lib/instance_ID/alias/key3.db
```
Log into the old server as the Certificate System user for that machine.
To migrate a master key from the old TKS instance, do the following:
1. Open the configuration file for the old server instance being migrated.
  
  If the migration is from Certificate Management System 7.0, this configuration file is the CMS.cfg in the old Certificate System config/ directory. If the migration is from Certificate System 7.1, this file is CS.cfg in the old server config/ directory.
2. Write down or note the exact value for the tks.mk_mappings. line, which has the following format.
```
tks.mk_mappings.#tks_master_key_version_number
 #01=internal:tks_master_key_version_name
```
  A tks.mk_mappings value looks like the following example:
```
tks.mk_mappings.#02#01=internal:tks_master_key_v2
```
  In this example, 02 is the tks_master_key_version_ number, and tks_master_key_v2 is the tks_master_key_version_name.
To migrate symmetric keys from an old TKS instance, two things are necessary:
- A written copy of the original three session key shares to reproduce the symmetric transport key on the old TKS instance.
- Copies of all files (there is at least one) containing the wrapped master keys for the old security database; for example, tks_master_key_v2.txt.
  
  NOTE
  
  These files are created whenever the user generates a new master key using the tksTool -W option.

Copy the certificate and key security databases from the old server to the new server.

cp old_server_root/alias/cert-old_TKS_instance-cert8.db 
/var/lib/instance_ID/alias/cert8.db

cp old_server_root/alias/cert-old_TKS_instance-key3.db 
/var/lib/instance_ID/alias/key3.db

Log into the new server as the Certificate System user, and open the Certificate System alias/ directory.
```
cd /var/lib/instance_ID/alias/
```
Log in as root, and set the file user and group to the Certificate System user and group.
```
su

chown user:group cert8.db

chown user:group key3.db
```
Log out as root. As the Certificate System user, change the permissions on the files.
```
chmod 00600 cert8.db

chmod 00600 key3.db
```

List the certificates stored in the old security databases by using the certutil command. In this example, -L lists the certificates.

certutil -L -d .

Server-Cert cert-old_TKS_instance cu,cu,cu
caSigningCert cert-old_TKS_instance CT,c,
tksTransportCert cert-old_TKS_instance CT,C,C

Export the public/private key pairs of each entry in the Certificate System databases using the pk12util tool; -o exports the key pairs to a PKCS #12 file, and -n sets the name of the certificate and the old database prefix.

pk12util -o ServerCert.p12 -n "Server-Cert cert-old_TKS_instance" -d . 

Enter Password or Pin for "NSS Certificate DB":********
Enter password for PKCS12 file: ********
Re-enter password: ********
pk12util: PKCS12 EXPORT SUCCESSFUL

Export the public key using the certutil tool; -L lists the named certificate, -n sets the name of the file and the old prefix, and -a outputs the information to a base-64 file.

certutil -L -n "caSigningCert cert-old_TKS_instance" -d . -a > caSigningCert.b64

certutil -L -n "tksTransportCert cert-old_TKS_instance" -d . -a > tksTransportCert.b64

Delete the old security databases.
```
rm cert8.db

rm key3.db
```

modutil -nocertdb -dbdir . -add new_HSM_token_name -libfile new_HSM_library_path/new_HSM_library

Identify the new HSM slot name.
```
modutil -dbdir . -nocertdb -list
```
Create new security databases.
```
certutil -N -d . 
```

Import the public/private key pair from the PKCS #12 file into the new HSM.

pk12util -i ServerCert.p12 -d . -h new_HSM_slot_name

Enter Password or Pin for "new_HSM_slot_name":********
Enter password for PKCS12 file: ********
pk12util: PKCS12 IMPORT SUCCESSFUL

Optionally, delete the PKCS #12 file:
```
rm ServerCert.p12
```

Set the trust bits on the public/private key pair that were imported into the new HSM.

certutil -M -n "new_HSM_slot_name:Server-Cert cert-old_TKS_instance" 
-t "cu,cu,cu" -d . -h <new_HSM_token_name

Import the public keys from the base-64 files into the new HSM, and set the trust bits.

certutil -A -n "new_HSM_slot_name:caSigningCert cert-old_TKS_instance"
 -t "CT,c," -d . -h new_HSM_token_name -i caSigningCert.b64

certutil -A -n "new_HSM_slot_name:tksTransportCert cert-old_TKS_instance"
 -t "CT,C,C" -d . -h new_HSM_token_name -i tksTransportCert.b64

Optionally, delete the base-64 files.

rm caSigningCert.b64

rm tksTransportCert.b64

Import the original symmetric transport key into the new HSM.

tksTool -I -d . new_HSM_token_name -n tks_transport_key_name

Type in the original three key session key shares (as prompted) to recreate the original transport key on the new HSM.
Log in as root, and set the file user and group to the Certificate System user and group for each wrapped_tks_master_key_file file.

Unwrap and store all the original master keys in the new HSM.

tksTool -U -d . -h new_HSM_token_name -t tks_transport_key_name
 -n tks_master_key_version_name -i wrapped_tks_master_key_file

Do this for every file containing a wrapped TKS master key.

Open the CS.cfg configuration file.

cd /var/lib/instance_ID/conf/

vi CS.cfg

If server-side keygen has been enabled, edit the tks.drm_transport_cert_nickname to reflect the new TKS information.
```
tks.drm_transport_cert_nickname=
 new_HSM_slot_name:tksTransportCert Cert cert-old_TKS_instance
```
If a master key was migrated from the old TKS instance, then also insert the tks.mk_mappings.#tks_master_key_version_number#01=<new_HSM_slot_name:tks_master_key_version_name line at the end of the CS.cfg. Be certain that the proper values for tks_master_key_version_number, new_HSM_slot_name, and tks_master_key_version_name are set.

NOTE

The caSigningCert is not referenced in the CS.cfg file.
In the same directory, edit the serverCertNick.conf file to contain the old certificate nickname. For example:
```
vi serverCertNick.confnew_HSM_slot_name:Server-Cert cert-old_TKS_instance
```

7.6.4.2. Case II: Security Databases to HSM Migration

NOTE

NOTE