Key Chains

A key chain is EUDIPLO's unified abstraction for managing cryptographic keys and their certificates together as a single entity. This eliminates orphaned keys and simplifies key lifecycle management.

What Is a Key Chain?

A key chain encapsulates:

• Active signing key with its certificate
• Optional root CA key (for internal certificate chains / rotation)
• Previous key (for grace period after rotation)
• Rotation policy (automatic certificate renewal)

┌─────────────────────────────────────────────┐
│               Key Chain                      │
├─────────────────────────────────────────────┤
│  Root CA Key (optional)                      │
│  Root CA Certificate (self-signed)           │
├─────────────────────────────────────────────┤
│  Active Signing Key                          │
│  Active Certificate (CA-signed or self)      │
├─────────────────────────────────────────────┤
│  Previous Key (optional, grace period)       │
│  Previous Certificate                        │
├─────────────────────────────────────────────┤
│  Rotation Policy                             │
└─────────────────────────────────────────────┘

Each tenant can manage multiple key chains simultaneously. Each key chain has a unique ID and is isolated via the tenant_id field.

Usage Types

Key chains are organized by usage type:

Usage	Purpose
access	Access certificates for wallet requests
attestation	Credential signing keys
trustList	Trust list signing keys
statusList	Status list signing keys
encrypt	Encryption keys for response encryption

Creating a Key Chain

Via the Web UI

1. Navigate to Keys in the sidebar
2. Click + Create Key to open the wizard
3. Select the usage type
4. Enter a name for the key chain
5. Click Create

Via the API

curl -X POST https://your-eudiplo-instance/keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-key-chain",
    "usage": "attestation"
  }'

KMS Provider Selection

When creating or importing a key through the API, include the kmsProvider field to select a specific provider by its id. If omitted, the defaultProvider from kms.json is used.

Example with specific provider:

curl -X POST https://your-eudiplo-instance/keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vault-backed-key",
    "usage": "attestation",
    "kmsProvider": "vault"
  }'

Key Rotation

Key chains support automatic rotation based on certificate expiry. When a certificate approaches expiration, EUDIPLO generates a new key and certificate while keeping the previous key available during a grace period.

This ensures uninterrupted service during key transitions.

Where Keys Are Stored

EUDIPLO supports pluggable KMS backends:

• Database (default) — Keys stored encrypted in the database
• HashiCorp Vault — Keys managed via Vault Transit engine
• AWS KMS — Keys managed by AWS Key Management Service
• PKCS#11 (HSM) — Hardware Security Module integration
• HTTP Remote KMS — Delegated to a remote microservice
• CSC — Cloud Signature Consortium remote signing

The choice of KMS backend is configured globally in kms.json. See KMS Configuration for technical details on each provider.

Certificate Types

Key chains can contain different certificate types depending on how they're provisioned:

• Self-signed — Generated by EUDIPLO for development/testing
• CA-issued — Signed by a Certificate Authority
• Imported — Brought in from external PKI systems
• Registrar-obtained — Access certificates from EUDI Wallet registrar

See Certificates for details on certificate management.

Best Practices

• Use separate key chains for different purposes (issuance vs. status lists)
• Enable rotation policies for production key chains
• Use Vault or AWS KMS in production for enhanced security
• Keep backup key material for disaster recovery (database provider only)
• Never expose private keys outside the KMS backend