Overview#

KRATool allows the LDAP contents of the KRA to be migrated during a major system migration. The KRATool offers the following functionalities:

  1. Replacing the storage cert key

  2. Append offset IDs to LDAP entries

  3. Remove offset IDs from LDAP entries

Use Cases#

As KRA admin I want to migrate an existing KRA into a new KRA while replacing the storage key#

Input#

  • Existing KRA’s security database (HSM or NSSDB)

  • Existing KRA’s storage cert nickname

  • Existing KRA’s payload key algorithm name

  • Existing KRA’s storage token name

  • Existing KRA’s naming context

  • New KRA’s storage cert

  • New KRA’s naming context

  • LDIF file from existing KRA

Output#

  • LDIF file for new KRA

As KRA admin I want to merge multiple existing KRAs into a single existing KRA#

Input#

  • LDIF files from existing KRAs

  • Offset for each KRA

Output#

  • LDIF file for the target KRA

As KRA admin, I want to rekey the payload with stronger payload key algorithm (ie) to replace old symmetric key (like DES3) with new stronger algorithms (like AES) [Future]#

Input#

  • Existing KRA’s security database (HSM or NSSDB)

  • Existing KRA’s storage cert nickname

  • Existing KRA’s payload key algorithm name

  • Existing KRA’s storage token name

  • Existing KRA’s naming context

  • New KRA’s storage cert

  • New KRA’s naming context

  • Desired algorithm for rekey

  • LDIF file from existing KRA

Output#

  • LDIF file for the target KRA

Case 1: Simple KRA Migration#

As KRA admin, I want to migrate an existing KRA into a new KRA while replacing the storage key (ie) rewrapping the payload key (eg. from 1024-RSA to 2048-RSA)

The following example is based on migrating from one legacy system to the latest system.

Hostname

Operating System

PKI KRA Version

RSA Storage Key Size

alpha.example.com

Fedora 27 (64-bit)

PKI 10.5

1024-bit

omega.example.com

Fedora 30 (64-bit)

PKI 10.8

2048-bit

Within this deployment, the KRA located on alpha.example.com contains data, while the KRA located on omega.example.com does not yet exist.

The administrator is tasked with installing and configuring a PKI 10.8 KRA on omega.example.com including:

  1. Extracting the data from the old KRA located on alpha.example.com

  2. Rewrapping the private key data stored with the 2048-bit storage key located on omega.example.com

  3. Renaming this data so that it can be consolidated and imported into omega.example.com

Preparing omega#

  1. Login as ‘root’ on omega.example.com

  2. Install and configure a new PKI 10.8 KRA on omega.example.com

NOTE: Select an RSA storage key size of 2048-bits! Also, if TPS data is to be “imported”, be certain to install and configure a TKS and TPS (make certain that the TPS uses this KRA)

3. Shutdown this PKI 10.8 KRA server (and leave it shutdown until instructed otherwise):

``  systemctl stop pki-tomcatd@``

  1. Prepare a place for data:

``  mkdir -p /export/pki``

5. Go to the directory containing the NSS security databases for this PKI 10.8 KRA:

``  cd /var/lib/pki/\ ``/alias

6. Extract the public storage certificate to a flat-file located in the new data area:

`` pki-server cert-export kra_storage –cert-file omega.crt ``

7. Presuming that the Directory Server instance associated with this KRA is located on the same machine, shutdown Directory Server (and leave it shutdown until instructed otherwise):

``  systemctl stop dirsrv@``

  1. Extract the pristine PKI 10.8 KRA LDAP database configuration:

``  /usr/lib64/dirsrv/slapd-omega/db2ldif -n omega.example.com-pki-kra -a /tmp/omega.ldif``
``  mv /tmp/omega.ldif /export/pki/omega.ldif``
Note 1: The db2ldif runs as “nobody” and so, it fails to create the omega.ldif other than /tmp location
Note 2: Be certain that the file ‘omega.ldif’ contains a single blank line at the end of the file!

Exporting contents from alpha#

  1. Login as ‘root’ on alpha.example.com

  2. Prepare a place for data:

``  mkdir -p /export/pki``

  1. Make certain that all PKI 10.5 servers are shut down

  2. Stop the Directory Server

``  systemctl stop dirsrv@``

  1. Generate the LDIF from the KRA LDAP Database

``  /usr/lib64/dirsrv/slapd-alpha/db2ldif -n alpha.example.com-pki-kra -a /tmp/alpha.ldif``
``   ``
  1. Copy the ‘alpha.ldif’ to the data area

``  mv /tmp/alpha.ldif /export/pki/alpha.ldif``

  1. Copy the KRA NSS security databases to the data area:

``   cp -p /var/lib/pki-kra/alias/cert8.db /export/pki``
``   cp -p /var/lib/pki-kra/alias/key3.db /export/pki``
``   cp -p /var/lib/pki-kra/alias/secmod.db /export/pki``
  1. Go to the data area

``  cd /export/pki``

17. Obtain the flat-file containing the public storage certificate from omega.example.com

``  sftp root@omega.example.com``
``   sftp> cd /export/pki``
``   sftp> get omega.cert``
``   sftp> quit``
  1. Run KRATool on alpha.example.com:

``  KRATool    ``
``   -kratool_config_file /usr/share/pki/java-tools/KRATool.cfg       ``
:literal:`   -source_ldif_file “pwd/alpha.ldif”                             \`
:literal:`   -target_ldif_file “pwd/alpha2omega.ldif”                                `
``   -log_file /tmp/KRATool.log                                       ``
:literal:`   -source_pki_security_database_path “pwd”                       \`
``   -source_storage_token_name “Internal Key Storage Token”          ``
``   -source_storage_certificate_nickname “storageCert cert-pki-kra”  ``
:literal:`   -target_storage_certificate_file “pwd/omega.cert”                   `
``   -source_kra_naming_context “alpha.example.com-pki-kra”           ``
``   -target_kra_naming_context “omega.example.com-pki-kra”           ``
``   -unwrap_algorithm AES                                            ``
``   -process_requests_and_key_records_only``

NOTE: Obtain the password from /var/lib//conf/password.conf. If the private storage key is stored on an HSM attached to alpha.example.com, change the input parameters appropriately, and select the appropriate password when prompted! Alternatively, create a file that ONLY contains the password to automatically supply the password to include in a certificate or to access a certificate database. This is a plain-text file containing one password. Be sure to prevent unauthorized access to this file. Supply this file to KRATool by adding the -source_pki_security_database_pwdfile command-line option.

  1. Copy ‘alpha2omega.ldif’ to omega.example.com:

``   sftp root@omega.example.com``
``   sftp> cd /export/pki``
``   sftp> put alpha2omega.ldif``
``   sftp> quit``

Importing into omega#

  1. Login as ‘root’ on omega.example.com 22. Go to the data area

``  cd /export/pki``

  1. Concatenate the ldif files:

``  cat omega.ldif alpha2omega.ldif > omega_alpha.ldif``

24. Import the file ‘omega_alpha.ldif’ into the LDAP database associated with the PKI 10.5 KRA:

``  /usr/lib64/dirsrv/slapd-omega/ldif2db -n omega.example.com-pki-kra -i /export/pki/omega_alpha.ldif``

  1. Restart directory server:

``  systemctl start dirsrv@``

  1. Restart the PKI 10.8 KRA:

``  systemctl start pki-tomcatd@``

Case 2: Merging Multiple KRAs#

As KRA admin, I want to merge multiple existing KRAs into a single existing KRA

The following example is based on migrating from two existing KRAs to one existing KRA.

Hostname

Operating System

PKI KRA Version

RSA Storage Key Size

alpha.example.com

Fedora 27 (64-bit)

PKI 10.5

2048-bit

omega.example.com

Fedora 30 (64-bit)

PKI 10.8

2048-bit

Within this deployment, both KRAs contain data.

The administrator is tasked with merging KRAs from alpha.example.com and beta.example.com into omega.example.com including:

  • Extracting the data from the 2 KRAs located on alpha.example.com and beta.example.com

  • Rewrapping the private key data stored with the 2048-bit storage key located on omega.example.com

  • Renumbering the KRA data located on omega.example.com

  • Renaming this data so that it can be consolidated and imported into omega.example.com

Preparing Omega#

  1. Login as ‘root’ on omega.example.com

2. Shutdown this PKI 10.8 KRA server (and leave it shutdown until instructed otherwise):

``  systemctl stop pki-tomcatd@``

  1. Prepare a place for data:

``  mkdir -p /export/pki``

4. Go to the directory containing the NSS security databases for this PKI 10.8 KRA:

``  cd /var/lib/pki/\ ``/alias

5. Extract the public storage certificate to a flat-file located in the new data area:

`` pki-server cert-export kra_storage –cert-file omega.crt ``

  1. Copy the omega.crt to /export/pki

`` cp omega.crt /export/pki``

Exporting contents from alpha#

NOTE: Follow the same steps in all KRA servers after replacing the alpha specific values

  1. Login as ‘root’ on alpha.example.com

  2. Prepare a place for data:

``  mkdir -p /export/pki``

  1. Make certain that all PKI servers are shut down

  2. Stop the Directory Server

``  systemctl stop dirsrv@``

  1. Generate the LDIF from the KRA LDAP Database

``  /usr/lib64/dirsrv/slapd-alpha/db2ldif -n \ ``alpha.example.com-pki-kra`` -a /tmp/alpha.ldif``
``   ``
  1. Copy the ‘alpha.ldif’ to the data area

``  mv /tmp/\ ``alpha.ldif`` /export/pki/\ ``alpha.ldif

  1. Copy the KRA NSS security databases to the data area:

``   cp -p /var/lib/pki-kra/alias/cert8.db /export/pki``
``   cp -p /var/lib/pki-kra/alias/key3.db /export/pki``
``   cp -p /var/lib/pki-kra/alias/secmod.db /export/pki``
  1. Go to the data area

``  cd /export/pki``

9. Obtain the flat-file containing the public storage certificate from omega.example.com

``  sftp root@omega.example.com``
``   sftp> cd /export/pki``
``   sftp> get omega.cert``
``   sftp> quit``
  1. Run KRATool on alpha.example.com:

``  KRATool    ``
``   -kratool_config_file /usr/share/pki/java-tools/KRATool.cfg       ``
:literal:`   -source_ldif_file “pwd/alpha.ldif”                             \`
:literal:`   -target_ldif_file “pwd/alpha2omega.ldif”                                `
``   -log_file /tmp/KRATool.log                                       ``
:literal:`   -source_pki_security_database_path “pwd”                       \`
``   -source_storage_token_name “Internal Key Storage Token”          ``
``   -source_storage_certificate_nickname “storageCert cert-pki-kra”  ``
:literal:`   -target_storage_certificate_file “pwd/omega.cert”                 `
``   -source_kra_naming_context \ ``"alpha.example.com-pki-kra"``           ``
``   -target_kra_naming_context “omega.example.com-pki-kra”           ``
``   -append_id_offset 100000000                     ``
``   -unwrap_algorithm AES                                            ``
``   -process_requests_and_key_records_only``

NOTE:’ Obtain the password from /var/lib//conf/password.conf. If the private storage key is stored on an HSM attached to alpha.example.com, change the input parameters appropriately, and select the appropriate password when prompted! Alternatively, create a file that ONLY contains the password to automatically supply the password to include in a certificate or to access a certificate database. This is a plain-text file containing one password. Be sure to prevent unauthorized access to this file. Supply this file to KRATool by adding the -source_pki_security_database_pwdfile command-line option.

  1. Copy ‘alpha2omega.ldif’ to omega.example.com:

``  sftp root@omega.example.com``
``   sftp> cd /export/pki``
``   sftp> put \ ``alpha2omega.ldif
``   sftp> quit``

Exporting contents from omega#

1. Login to omega.example.com 2. Presuming that the Directory Server instance associated with this KRA is located on the same machine, shutdown Directory Server (and leave it shutdown until instructed otherwise):

``  systemctl stop dirsrv@``

2. Extract the existing contents of PKI 10.8 KRA LDAP database configuration:

``  /usr/lib64/dirsrv/slapd-omega/db2ldif -n omega.example.com-pki-kra -a /tmp/omega.ldif``
``   mv /tmp/omega.ldif /export/pki/omega.ldif``

3. Run the KRATool to renumber the existing records in omega.example.com:

`` KRATool ``
``   -kratool_config_file /usr/share/pki/java-tools/KRATool.cfg ``
``   -source_ldif_file /export/pki/omega.ldif``
``   -target_ldif_file /export/pki/omega_renumbered.ldif``
``   -log_file /export/pki/KRATool.log``
``   -append_id_offset 300000000``

Importing contents into omega#

  1. Login as ‘root’ on omega.example.com

  2. Go to the data area

``  cd /export/pki``

  1. Concatenate the ldif files:

``  cat omega_renumbered.ldif alpha2omega.ldif > omega_alpha_beta.ldif``

Note: cat ldif files from ALL KRAs generated

4. Import the file ‘omega_alpha.ldif’ into the LDAP database associated with the PKI 10.6 KRA:

``  /usr/lib64/dirsrv/slapd-omega/ldif2db -n omega.example.com-pki-kra -i /export/pki/omega_alpha.ldif``

  1. Restart directory server:

``  systemctl start dirsrv@``

  1. Restart the PKI 10.8 KRA:

``  systemctl start pki-tomcatd@``

Case 3: Rekeying the payload entries in existing KRA [FUTURE]#

As a KRA admin, I want to rekey the payload with stronger payload key algorithm (ie) to replace old symmetric key (like DES3) with new stronger algorithms (like AES)

The following example is based on migrating from two existing KRAs to one existing KRA.

Hostname

Operating System

PKI KRA Version

RSA Storage Key Size

Payload key Algorithm

omega. example.com

Fedora 27 (64-bit)

PKI 10.5

2048-bit

DES3

The administrator is tasked with rekeying payload entries in an existing omega.example.com KRA:

  • Extracting the data from the KRA located on omega.example.com

  • Rekeying the payload with a stronger payload key (like AES)

  • Rewrapping the private key data stored with the 2048-bit storage key located on omega.example.com