Cross-scheme migration allows you to change cryptographic algorithms during key migration:

• RSA wrapping algorithms: Migrate from RSA PKCS#1 v1.5 to RSA-OAEP (or vice versa)

• Payload wrapping algorithms: Migrate from AES/CBC to AES KeyWrap (or vice versa)

• Key sizes: Change session key sizes (e.g., 128-bit to 256-bit AES)

• Session key regeneration: Optionally regenerate session keys during migration

• Security upgrades: Migrate to stronger algorithms (RSA-OAEP, AES-256)

• HSM compatibility: Adapt to different HSM capabilities on source and target

• Compliance requirements: Meet new cryptographic standards

• Hardware migration: Move keys between different HSM vendors with different algorithm support

• PKI KRA 10.13+ or 11.6+ with cross-scheme support

• KRATool standalone package installed

• Source KRA with archived keys

• Target KRA instance configured

• Basic understanding of PKI KRA operations

• Familiarity with NSS databases and certificate management

• Understanding of wrapped key cryptography concepts

Source KRA:

• NSS database: ~/migration/source

• Storage certificate nickname: test KRA Storage Certificate

• Token: Internal Key Storage Token

Target KRA:

• Storage certificate: ~/migration/target/kra_storage.pem

• NSS database for testing: ~/migration/target

First, stop the source KRA instance to ensure data consistency:

Export the KRA data from the Directory Server:

The KRATool configuration file specifies which LDIF fields to process during migration. Copy the standard configuration file from the PKI installation:

Alternatively, create ~/migration/kratool.cfg with the content shown in KRATool Configuration File Reference.

The target storage certificate’s public key is used to wrap session keys for the target KRA:

This example demonstrates migration without changing algorithms:

The -source_kra_naming_context and -target_kra_naming_context parameters specify the LDAP organizational context for the source and target KRA instances.

• Find your KRA naming context with: ldapsearch -LLL -x -H ldap://localhost:3389 -D "cn=Directory Manager" -w "password" -b "" -s base namingContexts

• Common format: o=<instance-name>-<subsystem> (e.g., o=pki-tomcat-KRA, o=topology-02-KRA-KRA)

• Optional but strongly recommended: If not specified, KRATool copies the source naming context to the target LDIF, which will cause DN mismatches if the source and target KRAs have different naming contexts

• Required when: Migrating between KRA instances with different naming contexts in the same or different LDAP directories

Expected output:

This example demonstrates changing algorithms and session key size:

• RSA to RSA-OAEP: More secure padding scheme

• AES/CBC to AES KeyWrap: NIST-recommended key wrapping

• 128-bit to 256-bit: Larger session keys for enhanced security

• -regenerate_session_key: Forces regeneration without prompting

Review the log file to ensure all keys were processed successfully:

Expected log entries:

Prepare the LDIF for import by removing the repository organizational entry:

Import the migrated keys into the target KRA using ldapmodify:

Verify the import:

Alternative: Full backend import (use with caution):

Verify that keys can be recovered from the target KRA:

Source System:

• KRA: rhcs10-kra-source

• HSM: SourceHSM

• Storage cert: storageCert cert-rhcs10-kra-source KRA

Target System:

• KRA: rhcs11-kra-target

• HSM: TargetHSM

• Storage cert: Exported to ~/tmp/target-storage.pem

Create password files for HSM access:

On the source system:

On the target system:

Ensure you export the storage certificate from the TARGET KRA, not the source KRA. Using the wrong storage certificate will cause the target KRA to fail unwrapping session keys, even though KRATool appears to complete successfully.

Symptom of wrong certificate: "Failed to unwrap session key" errors in target KRA when attempting key recovery.

• -source_hsm_token_pwdfile: Password for HSM token (may differ from NSS DB password)

• -split_target_ldif_per_records: Split output into multiple files for large migrations

Copy the migrated LDIF to the target system:

Use -use_nss_for_payload_processing when:

• Source HSM doesn’t support the target payload wrap algorithm

• Target HSM doesn’t support unwrap operations needed for migration

• Performance testing on software before HSM deployment

1. Session key unwrapped from source HSM using source storage private key

2. Session key imported to NSS DB (software token) for payload operations

3. Private key unwrapped in NSS DB using session key

4. New session key generated (if key size changed)

5. Private key rewrapped with new session key in NSS DB

6. Session key wrapped with target storage public key

This allows the HSM to handle RSA operations while NSS handles AES operations that the HSM may not support.

This guide uses the following example topology:

• Host: pki1.example.com

• CA: topology-02-CA (port 20443)

• Source KRA: topology-02-KRA (port 21443, HSM-backed, keys to be migrated out)

• Target KRA: topology-02-KRA-1 (port 26443, receives migrated keys)

• TKS: topology-02-TKS (shared)

• TPS: topology-02-TPS-1 (port 25443, configured for external registration)

• LDAP: port 3389

• HSM: SourceHSM (token: SOURCE-HSM)

Your topology may differ - substitute your actual values throughout this guide.

This complete workflow demonstrates:

1. KRA Migration: Exporting TPS smart card keys from an HSM-backed source KRA and migrating them to a target KRA using KRATool

2. TPS Configuration: Configuring TPS for external registration recovery

3. Testing: Verifying that migrated keys can be successfully recovered to smart cards

TPS external registration allows you to recover a previously issued certificate and its associated archived private key onto a smart card or hardware token. This is essential for:

• Re-issuing lost or damaged smart cards

• Migrating users to new tokens after KRA migration

• Verifying end-to-end key recovery workflow after cross-scheme migration

• Migrating TPS/TMS (Token Management System) smart card enrollments

• Source KRA uses HSM for storage key protection

• Target KRA may use HSM or software token

• Must preserve ability to recover keys to replacement smart cards via TPS external registration

• PKI KRA instances (source and target) configured

• Source KRA contains TPS-archived keys from smart card enrollments

• HSM access credentials (if using HSM)

• TPS instance configured and connected to target KRA

• User LDAP directory with user entries

• Smart card or hardware token for testing

• ESC (Enterprise Security Client) or compatible enrollment tool

Source KRA (topology-02-KRA):

• HSM token: SOURCE-HSM (SourceHSM)

• Storage certificate nickname: storageCert cert-topology-02-KRA KRA

• RSA wrapping: RSA-OAEP

• Session key regeneration: enabled

• Contains TPS-archived keys from smart card enrollments

Target KRA (topology-02-KRA-1):

• Storage certificate: exported to target_kra_storage.pem

• RSA wrapping: RSA-OAEP (matching source)

• Will receive migrated TPS keys

Get the target KRA’s storage certificate from the CA (only the certificate is needed, not the private key).

Using CA End-Entity Interface:

1. Navigate to https://pki1.example.com:20443/ca/ee/ca/

2. Click "Retrieval" tab

3. Enter the serial number of the target KRA storage certificate (or search by subject DN)

4. Click "Submit"

5. Copy the certificate in Base64 encoded format

6. Save to ~/migration/target_kra_storage.pem:

   cat > ~/migration/target_kra_storage.pem << 'EOF'
   -----BEGIN CERTIFICATE-----
   <paste Base64 certificate here>
   -----END CERTIFICATE-----
   EOF
   
   # Verify the certificate
   openssl x509 -in ~/migration/target_kra_storage.pem -noout -subject -serial

The KRATool configuration file specifies which LDIF fields to process during migration. Copy the standard configuration file from the PKI installation:

Alternatively, create ~/migration/kratool.cfg with the content shown in KRATool Configuration File Reference.

• -source_storage_token_name "SOURCE-HSM" - Specifies HSM token containing storage private key

• -source_hsm_token_pwdfile - Separate password file for HSM (if different from NSS DB password)

• -source_storage_certificate_nickname - Full nickname with token prefix

• -regenerate_session_key - Forces regeneration of session keys (needed when changing key sizes or payload algorithms)

• -use_nss_for_payload_processing - Performs payload unwrap/rewrap in NSS DB instead of HSM (use when HSM doesn’t support the payload algorithm)

• Naming contexts must match source and target KRA LDAP suffixes

Check KRATool output:

The "13 key record(s) processed successfully" indicates all TPS smart card keys were migrated.

Now that the TPS keys have been migrated to the target KRA, configure TPS to recover these keys to smart cards via external registration.

Add the following configuration to TPS CS.cfg:

Restart TPS after configuration changes:

Use ESC (Enterprise Security Client) or compatible smart card tool to:

1. Format the token

2. Enroll using the externalRegAddToToken profile

3. Verify the recovered certificate and key are loaded onto the token

Check TPS debug log (/var/lib/pki/pki-tomcat/logs/tps/debug.<date>) for successful key recovery:

Key indicators of success: * sw1: 0x90 sw2: 0x0 - Smart card accepted the key import * using RSA-OAEP for session key unwrap - Shows cross-scheme migration worked * unwrap the priv key with AES KWP - Confirms modern wrapping algorithm * ExternalRegRecoverOp: certificate and key successfully recovered to token - Final success

The successful enrollment shown in the TPS debug log (sw1: 0x90 sw2: 0x0 and certificate and key successfully recovered to token) confirms that:

• The HSM-migrated key was successfully recovered from the KRA

• The private key was unwrapped and imported to the smart card

• Cross-scheme migration (including any algorithm changes) is working correctly

View certificate on smart card:

Use ESC (Enterprise Security Client) to view the enrolled certificate:

1. Launch ESC

2. Select the smart card

3. View enrolled certificates - should show the recovered certificate with user’s subject DN

Alternatively, use Firefox to view the certificate:

1. Insert smart card

2. Open Firefox → Settings → Privacy & Security → Security Devices

3. Load the smart card module if not already loaded

4. Go to Settings → Privacy & Security → Certificates → View Certificates

5. Select "Your Certificates" tab

6. The recovered certificate should appear with the smart card token name

If the certificate appears in ESC or Firefox, the HSM-migrated key is fully functional on the token.

-use_cross_scheme

Enables cross-scheme migration mode with enhanced algorithm support.

-kratool_config_file <file>

Path to KRATool configuration file specifying which LDIF fields to process.

-source_ldif_file <file>

Input LDIF file exported from source KRA.

-target_ldif_file <file>

Output LDIF file for import to target KRA. Must not exist.

-log_file <file>

Debug log file. Must not exist.

-source_pki_security_database_path <path>

Path to source NSS database containing storage certificate and private key.

-source_storage_token_name <name>

Token name containing source storage certificate (e.g., "Internal Key Storage Token" or "MyHSM").

-source_storage_certificate_nickname <nickname>

Nickname of source KRA storage certificate in NSS database.

-target_storage_certificate_file <file>

Path to target KRA storage certificate in PEM format.

-source_pki_security_database_pwdfile <file>

Password file for source NSS database.

-source_kra_naming_context <context>

LDAP organizational context for the source KRA instance. Optional, but strongly recommended when source and target KRAs have different naming contexts.

Format: "<instance-name>-<subsystem>" (e.g., "pki-tomcat-KRA", "topology-02-KRA-KRA")

Find with: ldapsearch -LLL -x -H ldap://localhost:3389 -D "cn=Directory Manager" -w "password" -b "" -s base namingContexts

If not specified, KRATool will copy the source naming context from the LDIF, which may not match the target KRA’s organizational structure.

-target_kra_naming_context <context>

LDAP organizational context for the target KRA instance. Optional, but strongly recommended when source and target KRAs have different naming contexts.

Format: Same as source (e.g., "pki-tomcat-target-KRA", "topology-02-KRA-1-KRA")

If not specified, target LDIF entries will retain the source naming context in their DNs.

-source_rsa_wrap_algorithm <algorithm>

RSA algorithm used by source KRA. Values: RSA or RSA-OAEP. Default: RSA.

-target_rsa_wrap_algorithm <algorithm>

RSA algorithm for target KRA. Values: RSA or RSA-OAEP. Default: RSA-OAEP.

-source_payload_wrap_algorithm <algorithm>

Payload wrapping algorithm used by source KRA.

Supported values:

• "AES/CBC/PKCS5Padding"

• "AES KeyWrap/Wrapped" (KWP - recommended)

• "AES/KWP/NoPadding" (AES-KWP)

• "AES KeyWrap/Padding"

-target_payload_wrap_algorithm <algorithm>

Payload wrapping algorithm for target KRA. Same values as source.

-source_payload_wrap_keysize <bits>

Source session key size in bits. Values: 128, 192, or 256.

-target_payload_wrap_keysize <bits>

Target session key size in bits. Values: 128, 192, or 256.

-regenerate_session_key

Force session key regeneration without prompting. Use when changing key sizes or algorithms.

-use_nss_for_payload_processing

Perform payload unwrap/rewrap operations in NSS DB instead of HSM. Use when HSM doesn’t support target payload algorithm.

-source_hsm_token_pwdfile <file>

Password file for HSM token (if different from NSS DB password).

-split_target_ldif_per_records <count>

Split output into multiple files with specified number of records each. Useful for large migrations.

-verbose

Enable detailed per-record logging. Recommended for troubleshooting.

Enable verbose mode

Add -verbose flag to see detailed per-record processing information.

Check log file

Review the debug log for specific error messages:

tail -100 ~/migration/KRATool.log | less

Test with small dataset

Extract a small subset of keys for initial testing:

head -500 source-kra.ldif > test-keys.ldif

Verify algorithms

KRATool will log the detected algorithms at startup. Verify they match your source KRA configuration.

For migrations with thousands of keys:

Split output files

Use -split_target_ldif_per_records 1000 to create manageable file sizes.

Disable verbose logging

Remove -verbose flag for production runs to reduce I/O overhead.

HSM session caching

KRATool caches HSM sessions and keys to minimize expensive cryptographic operations.

• Software token: 50-100 keys/second

• HSM with cloneKey support: 20-50 keys/second

• HSM without cloneKey (RSA keypair method): 5-15 keys/second

Protect password files with restrictive permissions:

LDIF files contain sensitive wrapped key data:

• Store in encrypted filesystem

• Delete after successful import

• Restrict access: chmod 600 ldif-file

Run KRATool in a secure, isolated environment:

• Dedicated migration server

• No network access during migration

• Audit all operations

• Secure deletion of intermediate files

When changing key sizes or algorithms, session keys MUST be regenerated:

• Different key sizes: Automatic regeneration

• Same size: Use -regenerate_session_key to force regeneration

The standard KRATool.cfg configuration file specifies which LDIF fields to process during migration. The privateKeyData fields in caKeyRecord and tpsKeyRecord sections are essential for rewrapping archived keys.

A typical archived key record in LDIF format:

The repository organizational entry in LDIF exports contains a serialno field. This field is NOT used by the KRA to determine the last serial number. Instead, the KRA queries actual key records to find the highest serial number in use. The repository organizational entry can be safely removed before importing keys, which is why we use tail -n +8 to strip it from LDIF files.

• Dogtag PKI Documentation

• PKI GitHub Repository

• RFC 3394: AES Key Wrap

• RFC 5649: AES Key Wrap with Padding

• RFC 8017: PKCS #1 v2.2 (RSA-OAEP)

Document Version: 1.0

Last Updated: March 2026