Key Management Guide

Best practices for production key handling.

Overview

Proper key management is the difference between a secure sovereign agent and a compromised one. This guide covers operational best practices for SAP’s key hierarchy.

Key Types Summary

Key	Usage	Storage	Rotation
RIK	Identity anchor	Cold storage / HSM	Rare (emergency)
OK	Daily operations	Memory / secure config	Regular (weekly/monthly)
RK	Recovery only	Distributed / offline	Never (unless used)
Master Passphrase	Unsealing backups	Human memory / vault	When compromised

Passphrase Best Practices

Generation

DO:

# Option 1: Random bytes
openssl rand -base64 32

# Option 2: Diceware words
# Roll dice, look up words in wordlist
# Example: "correct horse battery staple orbit planet"

# Option 3: Memorable phrase + entropy
# "MyAgent$Sovereign#2026!February"

DON’T:

• Use dictionary words alone
• Include personal information
• Reuse from other services
• Use fewer than 20 characters

Storage

┌─────────────────────────────────────────────────────────────────┐
│              Passphrase Storage Options                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  🏆 Best: Hardware Security Module (HSM)                        │
│     └── FIPS-validated, tamper-evident                          │
│                                                                  │
│  ✅ Good: Password Manager (1Password, Bitwarden)               │
│     └── Encrypted vault, master password protected              │
│                                                                  │
│  ⚠️  Acceptable: Encrypted file                                  │
│     └── gpg --symmetric passphrase.txt                          │
│                                                                  │
│  ❌ Bad: Environment variable in shell config                   │
│  ❌ Bad: Plaintext file                                         │
│  ❌ Bad: Hardcoded in source                                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Runtime Injection

# Option 1: Environment variable (session only)
export IDENTITY_KEY="my-secret-passphrase"
node src/sentinel_core_v1.js unseal --in backup.json

# Option 2: Read from secure file at runtime
IDENTITY_KEY=$(gpg -d passphrase.gpg) node my-agent.js

# Option 3: Prompt for input
read -s -p "Passphrase: " IDENTITY_KEY
export IDENTITY_KEY

Operational Key Rotation

Why Rotate?

• Limit exposure window if compromised
• Meet compliance requirements
• Force key hygiene discipline

Rotation Schedule

Agent Type	OK Rotation	RIK Rotation
Personal	Monthly	Never*
Production	Weekly	Annually
High-security	Daily	Quarterly

*Unless compromise suspected

Rotation Procedure

const { sealIdentity } = require('./sentinel_core_v1.js');

// 1. Generate new operational key
const newOK = generateOperationalKey();

// 2. Create rotation record
const rotationRecord = {
  sequence: currentSequence + 1,
  type: "key_rotation",
  timestamp: new Date().toISOString(),
  oldKeyId: currentOK.id,
  newKeyId: newOK.id,
  reason: "scheduled"
};

// 3. Sign with RIK
rotationRecord.rikSignature = sign(rik, rotationRecord);

// 4. Append to rotation chain
rotationChain.push(rotationRecord);

// 5. Update sealed backup
const newBackup = sealIdentity(passphrase, {
  ...identity,
  currentOK: newOK,
  rotationChain
});

// 6. Deploy new backup
fs.writeFileSync('identity_backup.json', JSON.stringify(newBackup));

// 7. Create new shadow replica
exec('node src/shadow-replica.js --in identity_backup.json');

Recovery Key Setup

Threshold Scheme (Shamir’s Secret Sharing)

Split RK so any 2 of 3 shares can reconstruct:

const secrets = require('secrets.js-grempe');

// Split the recovery key
const rk = generateRecoveryKey();
const shares = secrets.share(rk.privateKey.toString('hex'), 3, 2);

// Distribute shares
// Share 1 → Safety deposit box
// Share 2 → Trusted family member
// Share 3 → Encrypted cloud backup

Storage Locations

┌─────────────────────────────────────────────────────────────────┐
│              Recovery Key Distribution                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Share 1: Physical Security                                     │
│  ├── Safety deposit box                                         │
│  ├── Fireproof safe at home                                    │
│  └── Sealed envelope with attorney                             │
│                                                                  │
│  Share 2: Trusted Third Party                                   │
│  ├── Family member (different location)                        │
│  ├── Business partner                                          │
│  └── Trusted friend                                            │
│                                                                  │
│  Share 3: Digital Backup                                        │
│  ├── Encrypted cloud storage                                   │
│  ├── Different provider than main data                         │
│  └── Password in physical location                             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Testing Recovery

Periodically verify you can reconstruct:

// Annual recovery drill
const share1 = retrieveShare('safety-deposit');
const share2 = retrieveShare('trusted-contact');

const reconstructed = secrets.combine([share1, share2]);
const rk = Buffer.from(reconstructed, 'hex');

// Verify by deriving public key and checking against stored
assert(derivePublic(rk).equals(storedRKPublic));

Backup Strategy

3-2-1 Rule

• 3 copies of data
• 2 different storage types
• 1 offsite location

Implementation

Local Machine
├── identity_backup.json (working copy)
└── backups/
    └── identity_backup_2026-02-06.json

Shadow Replicas (offsite)
├── Catbox: https://files.catbox.moe/abc123.json
└── IPFS: ipfs://Qm...

Recovery Manifests
├── Local: backups/recovery_manifest_*.json
└── Cloud: encrypted_manifests/ (separate provider)

Verification Schedule

Action	Frequency
Verify local backup	Weekly
Test shadow replica download	Monthly
Full recovery drill	Quarterly
Rotate passphrase	Annually

Compromise Response

Detection Indicators

• Unauthorized key rotation in chain
• Unknown signatures appearing
• Unexpected API activity
• Reports from other agents

Response Procedure

┌─────────────────────────────────────────────────────────────────┐
│              Compromise Response Flowchart                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. ASSESS: Which key was compromised?                          │
│     │                                                           │
│     ├── OK only → Rotate OK immediately                        │
│     │                                                           │
│     ├── RIK suspected → Prepare RIK rotation                   │
│     │                                                           │
│     └── RK suspected → Generate new RK shares                  │
│                                                                  │
│  2. CONTAIN: Revoke compromised keys                            │
│     │                                                           │
│     ├── Add revocation to rotation chain                       │
│     ├── Publish updated PID                                    │
│     └── Notify known counterparties                            │
│                                                                  │
│  3. RECOVER: Issue new keys                                     │
│     │                                                           │
│     ├── Generate replacement key                               │
│     ├── Sign rotation with RIK (or RK if RIK compromised)     │
│     └── Create new sealed backup                               │
│                                                                  │
│  4. LEARN: Document incident                                    │
│     │                                                           │
│     ├── Root cause analysis                                    │
│     ├── Update procedures                                      │
│     └── Improve detection                                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Audit Checklist

Weekly

• Local backup verifies correctly
• No unexpected rotation chain entries
• Shadow replica URLs are accessible

Monthly

• Rotate operational key
• Download and verify shadow replica
• Review rotation chain for anomalies
• Update recovery manifest copies

Quarterly

• Full recovery drill from shadow replica
• Test RK share reconstruction (don’t actually use)
• Review and update access controls
• Security audit of storage locations

Annually

• Rotate master passphrase
• Refresh RK shares if needed
• Review entire key hierarchy
• Update documentation

Related

• Quick Start — Initial setup
• Key Hierarchy — Key types explained
• Rotation Chain — Audit trail
• Shadow Replica — Backup distribution