Skip to content

Key Recovery

Jump to bottom
Chris Zinda edited this page Mar 6, 2026 · 1 revision

Key Recovery

Dogtag Key Recovery Authority (KRA) for key archival and recovery across all three PKI hierarchies.

The Key Recovery Authority (KRA) provides key escrow services, allowing private keys to be securely archived at enrollment time and recovered when needed. Each PKI hierarchy has its own dedicated KRA instance with matching cryptographic algorithms.

Overview

Property Value
Subsystem Dogtag PKI KRA
Deployment Full pkispawn -s KRA with dedicated 389 DS
Init Script scripts/pki/init-kra.sh
Configuration configs/pki/kra.cfg, ecc-kra.cfg, pq-kra.cfg
Security Domain Joins the Root CA's domain per hierarchy
Issuing CA Certificates issued by Intermediate CA

KRA Instances

Each PKI hierarchy has a dedicated KRA container and Directory Server:

Hierarchy KRA Container KRA Hostname DS Container Instance Name Network
RSA-4096 dogtag-kra kra.cert-lab.local ds-kra pki-kra 172.26.0.0/24
ECC P-384 dogtag-ecc-kra ecc-kra.cert-lab.local ds-ecc-kra pki-ecc-kra 172.28.0.0/24
ML-DSA-87 dogtag-pq-kra pq-kra.cert-lab.local ds-pq-kra pki-pq-kra 172.27.0.0/24

REST API Endpoints

Each KRA exposes its key management API at:

https://<kra-hostname>:8443/kra/rest/agent/keys

Architecture

┌────────────────────────────────────────────────────────────────┐
│                    KRA in PKI Hierarchy                         │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│   ┌────────────┐                                               │
│   │ Root CA    │◄── Security Domain                            │
│   └─────┬──────┘                                               │
│         │                                                      │
│   ┌─────▼──────┐    issues KRA certs    ┌──────────────────┐  │
│   │Intermediate│ ──────────────────────▶ │ Key Recovery     │  │
│   │    CA      │                         │ Authority (KRA)  │  │
│   └────────────┘                         │                  │  │
│                                          │  Storage Cert    │  │
│   ┌────────────┐                         │  Transport Cert  │  │
│   │  IoT CA    │                         │  Audit Cert      │  │
│   └────────────┘                         │  Subsystem Cert  │  │
│                                          │  SSL Server Cert │  │
│                                          └──────────────────┘  │
│                                                 │              │
│                                          ┌──────▼──────┐       │
│                                          │ 389 DS      │       │
│                                          │ (ds-kra)    │       │
│                                          └─────────────┘       │
│                                                                │
└────────────────────────────────────────────────────────────────┘

KRA Certificates

Each KRA instance requires five certificates, all issued by the Intermediate CA of its hierarchy:

Certificate Purpose Subject DN
Storage Encrypts archived private keys at rest CN=DRM Storage Certificate,OU=Key Recovery Authority,O=Cert-Lab,C=US
Transport Secures key material during transport from CA to KRA CN=DRM Transport Certificate,OU=Key Recovery Authority,O=Cert-Lab,C=US
Audit Signing Signs audit logs for tamper detection CN=Audit Signing Certificate,OU=Key Recovery Authority,O=Cert-Lab,C=US
Subsystem Inter-subsystem authentication within the security domain CN=Subsystem Certificate,OU=Key Recovery Authority,O=Cert-Lab,C=US
SSL Server TLS for the KRA's HTTPS endpoint CN=kra.cert-lab.local,OU=Key Recovery Authority,O=Cert-Lab,C=US

Algorithm Configuration

Each KRA uses cryptographic algorithms matching its hierarchy:

RSA-4096

pki_storage_key_algorithm=SHA512withRSA
pki_storage_key_size=4096
pki_storage_key_type=rsa
pki_transport_key_algorithm=SHA512withRSA
pki_transport_key_size=4096
pki_transport_key_type=rsa

ECC P-384

pki_storage_key_algorithm=SHA384withEC
pki_storage_key_size=nistp384
pki_storage_key_type=ecc
pki_transport_key_algorithm=SHA384withEC
pki_transport_key_size=nistp384
pki_transport_key_type=ecc

ML-DSA-87 (Post-Quantum)

pki_storage_key_algorithm=ML-DSA-87
pki_storage_key_size=87
pki_storage_key_type=mldsa
pki_transport_key_algorithm=ML-DSA-87
pki_transport_key_size=87
pki_transport_key_type=mldsa

Initialization

The KRA is initialized via scripts/pki/init-kra.sh, which performs a single-step pkispawn deployment:

# Initialize RSA KRA (auto-detected from container env)
./scripts/pki/init-kra.sh

# Explicit PKI type
./scripts/pki/init-kra.sh rsa
./scripts/pki/init-kra.sh ecc
./scripts/pki/init-kra.sh pq

Init Sequence

  1. Wait for dependencies — 389 DS, Root CA (security domain), Intermediate CA (issuing CA)
  2. Prepare configuration — Substitute environment variables into the .cfg template
  3. Run pkispawn — pkispawn -s KRA -f /tmp/kra.cfg -v
  4. Export credentials — Transport certificate and admin PKCS#12 for REST API access

Unlike CA deployment (which requires a two-step CSR/sign/import process), KRA deployment is single-step because pkispawn connects directly to the security domain and issuing CA to obtain all required certificates.

Key Archival and Recovery Operations

Key Archival

When a CA is configured to archive keys, the enrollment process wraps the private key with the KRA's transport certificate before sending it to the KRA. The KRA then re-encrypts the key with its storage certificate for long-term archival in the LDAP backend.

Client ──(key wrapped with KRA transport cert)──▶ KRA
                                                    │
                                              Re-encrypt with
                                              storage cert
                                                    │
                                                    ▼
                                               389 DS (LDAP)

Key Recovery

Authorized agents can recover archived keys through the KRA REST API:

# List archived keys
sudo podman exec dogtag-kra \
  pki -d /root/.dogtag/pki-kra/alias \
      -n 'PKI Administrator for pki-kra' \
      -c 'RedHat123' \
      kra-key-find

# Recover a key by key ID
sudo podman exec dogtag-kra \
  pki -d /root/.dogtag/pki-kra/alias \
      -n 'PKI Administrator for pki-kra' \
      -c 'RedHat123' \
      kra-key-retrieve --keyID <key-id>

Use Cases for Key Escrow

Use Case Description
Disaster Recovery Recover encryption keys when hardware fails or is destroyed
Legal Compliance Meet regulatory requirements for key escrow (e.g., financial services)
Employee Departure Recover encryption keys for data encrypted by former employees
Certificate Renewal Reuse archived keys when renewing certificates (same key pair)
Audit Trail Maintain a verifiable record of all key archival and recovery operations

Integration with CA Hierarchy

The KRA integrates with the CA hierarchy through the Dogtag security domain:

  • Security Domain Membership — The KRA joins the Root CA's security domain, enabling trusted inter-subsystem communication
  • Certificate Issuance — All KRA certificates are issued by the Intermediate CA
  • Key Transport — CAs use the KRA's transport certificate to securely send archived keys
  • Connector Configuration — CAs can be configured with a KRA connector to automatically archive keys during enrollment

Enabling Key Archival on a CA

To configure a CA to archive keys with the KRA, the CA needs a KRA connector pointing to the KRA's transport certificate and endpoint. This is configured in the CA's CS.cfg:

ca.connector.KRA.enable=true
ca.connector.KRA.host=kra.cert-lab.local
ca.connector.KRA.port=8443
ca.connector.KRA.transportCertNickname=KRA Transport Certificate

Dependencies

Each KRA depends on:

Dependency Purpose Must Be Running
389 DS (ds-kra) LDAP backend for key storage Yes
Root CA Security domain membership During init only
Intermediate CA Issues KRA certificates During init only

Related Pages

Home

Getting Started
Architecture
PKI Operations
Security & Compliance
Operations & Testing
Key & HSM Management
Monitoring
Advanced Topics

Clone this wiki locally