KRATool Examples

KRATool Cross-Scheme Migration Guide

Table of Contents

• 1. Overview
  • 1.1. What is Cross-Scheme Migration?
  • 1.2. Use Cases
• 2. Prerequisites
  • 2.1. Software Requirements
  • 2.2. Knowledge Requirements
• 3. Migration Scenarios
• 4. Scenario 1: Software Token Migration (NSS DB to NSS DB)
  • 4.1. Environment Setup
  • 4.2. Step 1: Export Source KRA Keys to LDIF
  • 4.3. Step 2: Create KRATool Configuration File
  • 4.4. Step 3: Extract Target Storage Certificate
  • 4.5. Step 4: Run KRATool - Basic Same-Algorithm Migration
  • 4.6. Step 5: Run KRATool - Algorithm Migration with Session Key Regeneration
  • 4.7. Step 6: Verify Migration Results
  • 4.8. Step 7: Import Target LDIF to Target KRA
  • 4.9. Step 8: Test Key Recovery
• 5. Scenario 2: HSM-to-HSM Migration
  • 5.1. Environment Setup
  • 5.2. Step 1: Prepare HSM Credentials
  • 5.3. Step 2: Export Source KRA LDIF
  • 5.4. Step 3: Extract Target Storage Certificate
  • 5.5. Step 4: Run KRATool on Source System
  • 5.6. Step 5: Transfer and Import to Target
• 6. Scenario 3: Algorithm Migration with Software Token Fallback
  • 6.1. When to Use Software Token Fallback
  • 6.2. Example: AES/CBC to AES KeyWrap Migration
• 7. Command-Line Options Reference
  • 7.1. Mandatory Options
  • 7.2. Cross-Scheme Options
• 8. Troubleshooting
  • 8.1. Common Issues
    • 8.1.1. "publicKeyData is null or empty"
    • 8.1.2. "Unsupported payload wrap algorithm"
    • 8.1.3. "Failed to unwrap session key"
    • 8.1.4. "Target LDIF file ALREADY exists"
  • 8.2. Debugging Tips
• 9. Performance Considerations
  • 9.1. Large Migrations
  • 9.2. Expected Performance
• 10. Security Considerations
  • 10.1. Password Files
  • 10.2. LDIF Files
  • 10.3. Migration Environment
  • 10.4. Session Key Regeneration
• 11. Appendix
  • 11.1. Sample LDIF Record Structure
  • 11.2. Algorithm Compatibility Matrix
  • 11.3. References

1. Overview

This guide demonstrates how to use KRATool to migrate archived keys between PKI Key Recovery Authority (KRA) instances, including cross-scheme cryptographic migration scenarios.

1.1. What is Cross-Scheme Migration?

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

1.2. Use Cases

• 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

2. Prerequisites

2.1. Software Requirements

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

• KRATool standalone package installed

• Source KRA with archived keys

• Target KRA instance configured

2.2. Knowledge Requirements

• Basic understanding of PKI KRA operations

• Familiarity with NSS databases and certificate management

• Understanding of wrapped key cryptography concepts

3. Migration Scenarios

This guide covers three common migration scenarios:

1. Software Token Migration (NSS DB to NSS DB): Testing and development

2. HSM-to-HSM Migration: Production key migration between hardware security modules

3. Algorithm Migration: Changing cryptographic algorithms during migration

4. Scenario 1: Software Token Migration (NSS DB to NSS DB)

This scenario demonstrates migration using NSS databases on a single system, ideal for testing and understanding the migration process.

4.1. Environment Setup

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

4.2. Step 1: Export Source KRA Keys to LDIF

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

sudo systemctl stop pki-tomcatd@pki-tomcat.service

Export the KRA data from the LDAP database:

# Create output directory
mkdir -p ~/migration/source

# Export KRA data using ldapsearch
ldapsearch -x -D "cn=Directory Manager" -W \
    -b "ou=kra,ou=requests,dc=example,dc=com" \
    -s sub "(objectClass=*)" > ~/migration/source/kra-archived-keys.ldif

Tip	For production systems, use db2ldif.pl or dsconf to export the entire KRA backend:

# RHEL 8 (389 DS 1.4)
sudo db2ldif.pl -Z instance_name -n kra-db \
    -a /var/lib/dirsrv/slapd-instance_name/ldif/kra-export.ldif

# RHEL 9+ (389 DS 2.x)
sudo dsconf localhost backend export kra-db \
    /var/lib/dirsrv/slapd-localhost/ldif/kra-export.ldif

4.3. Step 2: Create KRATool Configuration File

Create a configuration file that specifies which LDIF fields to process:

cat > ~/migration/kratool.cfg << 'EOF'
kratool.ldif.ca_AgentSigningCert=true
kratool.ldif.ca_AuditSigningCert=true
kratool.ldif.ca_CrossCertificatePair=true
kratool.ldif.ca_OCSPSigningCert=true
kratool.ldif.ca_ServerCert=true
kratool.ldif.ca_SubsystemCert=true
kratool.ldif.ca_TransportCert=true
kratool.ldif.ca_UserCertificate=true

kratool.ldif.kra_PrivateKey=true
kratool.ldif.kra_ExtData_Request=true
kratool.ldif.kra_ExtData_KeyRecord=true
kratool.ldif.kra_TransportCert=true
kratool.ldif.kra_StorageToken=true
kratool.ldif.kra_UpdateTime=true
EOF

Note	The configuration file tells KRATool which LDIF attributes to process. Setting kratool.ldif.kra_PrivateKey=true is essential for rewrapping archived keys.

4.4. Step 3: Extract Target Storage Certificate

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

# If target is also NSS DB (for testing)
certutil -L -d ~/migration/target \
    -n "test KRA Storage Certificate" -a > ~/migration/target/kra_storage.pem

# If target is production KRA
# Extract from target KRA's certificate file
cp /var/lib/pki/pki-tomcat/kra/alias/kra_storage.cert \
    ~/migration/target/kra_storage.pem

4.5. Step 4: Run KRATool - Basic Same-Algorithm Migration

This example demonstrates migration without changing algorithms:

KRATool \
    -use_cross_scheme \
    -kratool_config_file ~/migration/kratool.cfg \
    -source_ldif_file ~/migration/source/kra-archived-keys.ldif \
    -target_ldif_file ~/migration/target/kra-archived-keys-target.ldif \
    -log_file ~/migration/KRATool.log \
    -source_pki_security_database_path ~/migration/source \
    -source_storage_token_name "Internal Key Storage Token" \
    -source_storage_certificate_nickname "test KRA Storage Certificate" \
    -target_storage_certificate_file ~/migration/target/kra_storage.pem \
    -source_pki_security_database_pwdfile ~/migration/source/passwd \
    -verbose

Expected output:

Source RSA wrap algorithm: RSA (default)
Target RSA wrap algorithm: RSA-OAEP (default)
Source payload wrap algorithm: Auto-detected from source LDIF
Target payload wrap algorithm: Auto-detected from source LDIF

BEGIN "KRATool -use_cross_scheme ..."

PROCESSING KRATOOL CONFIG FILE: ................................... FINISHED.

SUCCESSFULLY processed kratool config file!

Initializing source PKI security databases in '~/migration/source'.
...
PROCESSING: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Summary: 60 key record(s) processed successfully, 0 failed.

Target LDIF file: ~/migration/target/kra-archived-keys-target.ldif
Debug log file:   ~/migration/KRATool.log

4.6. Step 5: Run KRATool - Algorithm Migration with Session Key Regeneration

This example demonstrates changing algorithms and session key size:

KRATool \
    -use_cross_scheme \
    -kratool_config_file ~/migration/kratool.cfg \
    -source_ldif_file ~/migration/source/kra-archived-keys.ldif \
    -target_ldif_file ~/migration/target/kra-keys-upgraded.ldif \
    -log_file ~/migration/KRATool-upgrade.log \
    -source_pki_security_database_path ~/migration/source \
    -source_storage_token_name "Internal Key Storage Token" \
    -source_storage_certificate_nickname "test KRA Storage Certificate" \
    -target_storage_certificate_file ~/migration/target/kra_storage.pem \
    -source_pki_security_database_pwdfile ~/migration/source/passwd \
    -source_rsa_wrap_algorithm RSA \
    -target_rsa_wrap_algorithm RSA-OAEP \
    -source_payload_wrap_algorithm "AES/CBC/PKCS5Padding" \
    -target_payload_wrap_algorithm "AES KeyWrap/Wrapped" \
    -source_payload_wrap_keysize 128 \
    -target_payload_wrap_keysize 256 \
    -regenerate_session_key \
    -verbose

Important

Algorithm Migration Notes:

• 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

4.7. Step 6: Verify Migration Results

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

# Check summary
tail -20 ~/migration/KRATool.log

# Count successful vs failed records
grep "Successfully" ~/migration/KRATool.log

Expected log entries:

[2026-03-19 14:30:15]:  Successfully converted source LDIF file --> target LDIF file!
[2026-03-19 14:30:15]:
[2026-03-19 14:30:15]:  Summary: 60 key record(s) processed successfully, 0 failed.
[2026-03-19 14:30:15]:
[2026-03-19 14:30:15]:  Target LDIF file: ~/migration/target/kra-keys-upgraded.ldif
[2026-03-19 14:30:15]:  Debug log file:   ~/migration/KRATool.log

4.8. Step 7: Import Target LDIF to Target KRA

Stop the target KRA:

sudo systemctl stop pki-tomcatd@pki-tomcat.service

Import the migrated keys:

# RHEL 8 (389 DS 1.4)
sudo ldif2db.pl -Z instance_name -n kra-db \
    -i ~/migration/target/kra-keys-upgraded.ldif

# RHEL 9+ (389 DS 2.x)
sudo dsconf localhost backend import kra-db \
    ~/migration/target/kra-keys-upgraded.ldif

Start the target KRA:

sudo systemctl start pki-tomcatd@pki-tomcat.service

4.9. Step 8: Test Key Recovery

Verify that keys can be recovered from the target KRA:

# List archived keys
pki -n caadmin kra-key-find

# Test recovery of a specific key
pki -n kra-agent kra-key-retrieve --keyID 0x1

Tip	For automated testing, use the KRA REST API to recover multiple keys and verify the decrypted data matches the original.

5. Scenario 2: HSM-to-HSM Migration

This scenario demonstrates migrating keys between hardware security modules.

5.1. Environment Setup

Source System:

• KRA: rhcs10-kra-source

• HSM: Luna SA (token name: SourceHSM)

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

Target System:

• KRA: rhcs11-kra-target

• HSM: nCipher nShield (token name: TargetHSM)

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

5.2. Step 1: Prepare HSM Credentials

Create password files for HSM access:

# Create tmp directory
mkdir -p ~/tmp

# Source HSM password
echo "SourceHSMPassword123" > ~/tmp/source-hsm-passwd
chmod 600 ~/tmp/source-hsm-passwd

# Target system will need its own HSM password file

5.3. Step 2: Export Source KRA LDIF

On the source system:

sudo systemctl stop pki-tomcatd@pki-tomcat.service

# Export KRA database
sudo dsconf localhost backend export kra-db \
    /var/lib/dirsrv/slapd-localhost/ldif/kra-export.ldif

# Copy to migration directory
mkdir -p ~/migration
cp /var/lib/dirsrv/slapd-localhost/ldif/kra-export.ldif \
    ~/migration/source-kra.ldif

5.4. Step 3: Extract Target Storage Certificate

On the target system:

# Create tmp directory
mkdir -p ~/tmp

# Export target KRA storage certificate
certutil -L -d /var/lib/pki/pki-tomcat/alias \
    -n "storageCert cert-rhcs11-kra-target KRA" -a \
    > ~/tmp/target-storage.pem

# Copy to source system for migration
scp ~/tmp/target-storage.pem root@source-system:~/migration/

5.5. Step 4: Run KRATool on Source System

KRATool \
    -use_cross_scheme \
    -kratool_config_file ~/migration/kratool.cfg \
    -source_ldif_file ~/migration/source-kra.ldif \
    -target_ldif_file ~/migration/target-kra.ldif \
    -log_file ~/migration/KRATool.log \
    -source_pki_security_database_path /var/lib/pki/pki-tomcat/alias \
    -source_storage_token_name "SourceHSM" \
    -source_storage_certificate_nickname "storageCert cert-rhcs10-kra-source KRA" \
    -target_storage_certificate_file ~/migration/target-storage.pem \
    -source_pki_security_database_pwdfile ~/tmp/source-hsm-passwd \
    -source_hsm_token_pwdfile ~/tmp/source-hsm-passwd \
    -source_rsa_wrap_algorithm RSA-OAEP \
    -target_rsa_wrap_algorithm RSA-OAEP \
    -source_payload_wrap_algorithm "AES KeyWrap/Wrapped" \
    -target_payload_wrap_algorithm "AES KeyWrap/Wrapped" \
    -split_target_ldif_per_records 1000 \
    -verbose

Note	HSM-Specific Options:

• -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

5.6. Step 5: Transfer and Import to Target

Copy the migrated LDIF to the target system:

# On source system
scp ~/migration/target-kra.ldif* root@target-system:~/migration/

# On target system
sudo systemctl stop pki-tomcatd@pki-tomcat.service

# If split into multiple files, combine them
cat ~/migration/target-kra.ldif.* > ~/migration/target-kra-combined.ldif

# Import
sudo dsconf localhost backend import kra-db \
    ~/migration/target-kra-combined.ldif

sudo systemctl start pki-tomcatd@pki-tomcat.service

6. Scenario 3: Algorithm Migration with Software Token Fallback

Some HSMs don’t support certain payload wrapping algorithms. This scenario shows how to use NSS DB for payload operations.

6.1. When to Use Software Token Fallback

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

6.2. Example: AES/CBC to AES KeyWrap Migration

KRATool \
    -use_cross_scheme \
    -kratool_config_file ~/migration/kratool.cfg \
    -source_ldif_file ~/migration/source-kra.ldif \
    -target_ldif_file ~/migration/target-kra.ldif \
    -log_file ~/migration/KRATool.log \
    -source_pki_security_database_path /var/lib/pki/pki-tomcat/alias \
    -source_storage_token_name "SourceHSM" \
    -source_storage_certificate_nickname "storageCert cert-source-kra KRA" \
    -target_storage_certificate_file ~/migration/target-storage.pem \
    -source_pki_security_database_pwdfile ~/tmp/passwd \
    -source_hsm_token_pwdfile ~/tmp/hsm-passwd \
    -source_rsa_wrap_algorithm RSA \
    -target_rsa_wrap_algorithm RSA-OAEP \
    -source_payload_wrap_algorithm "AES/CBC/PKCS5Padding" \
    -target_payload_wrap_algorithm "AES KeyWrap/Wrapped" \
    -source_payload_wrap_keysize 128 \
    -target_payload_wrap_keysize 256 \
    -use_nss_for_payload_processing \
    -verbose

Important

How Software Token Fallback Works:

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.

7. Command-Line Options Reference

7.1. Mandatory Options

-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.

7.2. Cross-Scheme Options

-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" (recommended)

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

-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.

8. Troubleshooting

8.1. Common Issues

8.1.1. "publicKeyData is null or empty"

Cause: Using baseline rewrap mode instead of cross-scheme mode, or LDIF missing public key data.

Solution: Ensure -use_cross_scheme flag is present and source LDIF contains publicKeyData attributes.

8.1.2. "Unsupported payload wrap algorithm"

Cause: HSM doesn’t support the specified algorithm.

Solution: Add -use_nss_for_payload_processing to use NSS DB for payload operations.

8.1.3. "Failed to unwrap session key"

Cause: Incorrect storage certificate, wrong algorithm specified, or HSM authentication issue.

Solution:

• Verify source storage certificate nickname

• Check HSM password file

• Confirm source RSA wrap algorithm matches what was used to wrap the keys

8.1.4. "Target LDIF file ALREADY exists"

Cause: Previous run left output file.

Solution: Remove the file: rm ~/migration/target.ldif or use a different filename.

8.2. Debugging Tips

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.

9. Performance Considerations

9.1. Large Migrations

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.

9.2. Expected Performance

• Software token: 50-100 keys/second

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

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

10. Security Considerations

10.1. Password Files

Protect password files with restrictive permissions:

chmod 600 ~/tmp/passwd

10.2. LDIF Files

LDIF files contain sensitive wrapped key data:

• Store in encrypted filesystem

• Delete after successful import

• Restrict access: chmod 600 ldif-file

10.3. Migration Environment

Run KRATool in a secure, isolated environment:

• Dedicated migration server

• No network access during migration

• Audit all operations

• Secure deletion of intermediate files

10.4. Session Key Regeneration

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

11. Appendix

11.1. Sample LDIF Record Structure

A typical archived key record in LDIF format:

dn: cn=1,ou=keyRepository,ou=kra,dc=example,dc=com
objectClass: top
objectClass: keyRecord
cn: 1
serialno: 1
algorithm: RSA
privateKeyData:: MIICdQIBADANBgkqhkiG9w0BAQE...
publicKeyData:: MIGfMA0GCSqGSIb3DQEBAQUAA4GN...
dateOfCreate: 20260101120000Z
dateOfModify: 20260101120000Z
keyState: active
ownerName: uid=testuser
privateKeyFormat: PKCS8
publicKeyFormat: X.509

11.2. Algorithm Compatibility Matrix

Source Algorithm	Target Algorithm	Session Key Action	Notes
RSA	RSA	Keep or regenerate	No algorithm change
RSA	RSA-OAEP	Keep or regenerate	Upgrade to more secure padding
RSA-OAEP	RSA	Keep or regenerate	Downgrade (not recommended)
RSA-OAEP	RSA-OAEP	Keep or regenerate	No algorithm change
AES/CBC	AES/CBC	Keep or regenerate	No algorithm change
AES/CBC	AES KeyWrap	Must regenerate	Different wrapping method
AES KeyWrap	AES/CBC	Must regenerate	Different wrapping method
AES KeyWrap	AES KeyWrap	Keep or regenerate	No algorithm change
128-bit	256-bit	Automatic regeneration	Key size change detected

11.3. References

• 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