XRPL validators use a two-tier key architecture:

Validator Key Architecture:

┌─────────────────────────────────────────────┐
│              MASTER KEY PAIR                │
│  (Permanent Validator Identity)             │
│                                             │
│  • Generated once                           │
│  • Never changes                            │
│  • Stored securely OFFLINE                  │
│  • Used only to sign tokens                 │
│  • Public key = Validator identity          │
└─────────────────────────────────────────────┘
                    │
                    │ Signs
                    ▼
┌─────────────────────────────────────────────┐
│              VALIDATOR TOKEN                │
│  (Rotatable Credential)                     │
│                                             │
│  • Can be regenerated from master key       │
│  • Stored in rippled.cfg                    │
│  • Can be rotated without identity change   │
│  • What rippled uses for validation         │
└─────────────────────────────────────────────┘

Security Benefits:

1. Master Key Protection

1. Token Rotation

1. Key Ceremony Separation

- You generate master key on air-gapped machine
- Store master key in secure location (safe, HSM)
- Generate token, deploy to server
- If server compromised: Generate new token from master
- Identity and reputation intact

Public Key Format:
nEd25519... (Base58-encoded Ed25519 public key)
This is how other validators identify you
```

Key generation is a one-time, high-security operation. Take it seriously.

Minimum Security Requirements:

Environment:
□ Dedicated machine or live OS (Tails, etc.)
□ Disconnected from network (air-gapped preferred)
□ No unnecessary software running
□ Clean, recently installed OS

Physical:
□ Private location (no observers)
□ No cameras or recording devices
□ Secure disposal of any written notes

Process:
□ Document each step as you perform it
□ Verify outputs match expectations
□ Multiple backup copies before leaving secure environment

The most secure approach uses a machine that never connects to the internet:

# On an air-gapped machine with Linux:

# 1. Copy validator-keys tool via USB
# From your server (internet-connected):
scp /opt/ripple/bin/validator-keys /media/usb/

# On air-gapped machine:
cp /media/usb/validator-keys ~/
chmod +x ~/validator-keys

# 2. Generate keys (see Section 3)

# 3. Copy keys to USB for secure storage
# DO NOT connect air-gapped machine to network

If air-gapped isn't feasible, use a live OS that leaves no traces:

Using Tails OS:

1. Download Tails from tails.net (verify signature)
2. Create bootable USB
3. Boot computer from Tails USB
4. Disconnect from network (don't connect WiFi)
5. Copy validator-keys tool from another USB
6. Generate keys
7. Save keys to encrypted USB storage
8. Shut down (Tails leaves no traces)

If neither option above is feasible, generate on your server with precautions:

# Least preferred but acceptable if done carefully

# 1. Ensure no one else has server access
# Check active sessions:
who
w

# 2. Disable command history temporarily
set +o history
unset HISTFILE

# 3. Generate keys (see Section 3)

# 4. Immediately copy key file to secure storage
# Then securely delete from server

# 5. Re-enable history
set -o history

# 6. Clear terminal
clear
history -c

# Navigate to the validator-keys tool
cd /opt/ripple/bin/

Generate validator key pair

./validator-keys create_keys

Expected output:

Validator keys stored in /home/[user]/.ripple/validator-keys.json

This file should be stored securely and not shared.

Example output:

Field Explanations:

• Cryptographic algorithm used

• Ed25519 is current standard

• Your validator's PUBLIC identity

• Safe to share

• This identifies your validator to the network

• Key revocation status

• Should be false for active keys

• Your validator's PRIVATE key

• NEVER share

• Must be stored securely

• Losing this = losing validator identity

Example output:

Understanding the Token:

• A signed authorization to validate

• Contains an ephemeral signing key

• Signed by your master key

• What you put in rippled.cfg

• Can be regenerated anytime (with master key)

• Safe to deploy on server

• If compromised, generate new token

• Original master key identity preserved

MUST STORE SECURELY:

1. validator-keys.json file

1. Paper backup of secret_key

1. Documentation of public key

OPTIONAL BUT RECOMMENDED:

1. Token backup

2. Generation procedure documentation

Recommended Storage Strategy:

- Hardware-encrypted or software-encrypted
- Stored in secure location (safe, safety deposit)
- Contains validator-keys.json

- Written secret_key
- Different physical location than USB
- Survives electronic failures

- Different physical location
- Backup of primary

DO NOT store master keys:
✗ On the server (token only)
✗ In cloud storage (Google Drive, Dropbox)
✗ In password managers (most aren't designed for this)
✗ In email
✗ On networked computers

# Create encrypted container for key storage
# Using LUKS (Linux Unified Key Setup)

On a Linux machine:

1. Insert USB drive

2. Identify device (BE CAREFUL - wrong device = data loss)

lsblk

3. Create encrypted partition (DESTROYS DATA)

sudo cryptsetup luksFormat /dev/sdX1

Enter strong passphrase when prompted

4. Open encrypted partition

sudo cryptsetup luksOpen /dev/sdX1 validator-keys

Enter passphrase

5. Create filesystem

sudo mkfs.ext4 /dev/mapper/validator-keys

6. Mount

sudo mount /dev/mapper/validator-keys /mnt/keys

7. Copy key file

sudo cp ~/.ripple/validator-keys.json /mnt/keys/

8. Unmount and close

sudo umount /mnt/keys
sudo cryptsetup luksClose validator-keys

Store USB securely

Paper Backup Procedure:

1. Write by hand on durable paper:

1. Verify by reading back carefully

1. Store in:

1. Consider:

---

Transfer only the TOKEN (not master keys) to your server:

# Generate token (if not already done)
./validator-keys create_token --keyfile ~/.ripple/validator-keys.json

# Copy the token output (everything from [validator_token] to end)
# Transfer via secure method:

# Option 1: Type manually (most secure for short operations)
# Option 2: Secure copy via encrypted channel
# Option 3: Encrypted USB (if physical access)

# DO NOT transfer validator-keys.json to the server
# Only the token goes on the server

# Edit rippled configuration
sudo nano /opt/ripple/etc/rippled.cfg

Add at the end of the file:

[validator_token]
eyJ2YWxpZGF0aW9uX3NlY3JldF9rZXkiOiI5ZWQ0NWY4NjY...
[paste complete token - it's one long line]

Save and exit

# Set restrictive permissions on configuration file
sudo chmod 600 /opt/ripple/etc/rippled.cfg

Verify permissions

ls -la /opt/ripple/etc/rippled.cfg

Should show: -rw------- (only root can read)

Configuration file contains sensitive token

Should not be world-readable

We've added the token to configuration, but we won't restart yet. Lesson 8 covers the full enablement process with verification steps. For now, understand that:

Token rotation scenarios:

- Server compromise suspected
- Token exposed accidentally
- Leaving organization (if shared access existed)
- Security policy requires periodic rotation

- After infrastructure changes
- Annually as preventive measure
- After security incidents on network (not your server)

- Routine maintenance
- Software updates
- Configuration changes
- Just for the sake of change

# Token rotation preserves your validator identity
# Only the token changes, not the master key

1. Access your secure master key storage

(air-gapped machine or secure environment)

2. Generate new token

./validator-keys create_token --keyfile /path/to/validator-keys.json

3. On your server, update configuration

sudo nano /opt/ripple/etc/rippled.cfg

Replace old [validator_token] section with new token

4. Restart rippled

sudo systemctl restart rippled

5. Verify validation is working

/opt/ripple/bin/rippled server_info | grep server_state

Should show "proposing" after sync

6. Your validator identity (public key) is unchanged

Reputation intact

Important distinction:

- New token, same identity
- Reputation preserved
- Minimal disruption
- Done with master key

- New identity entirely
- Reputation lost
- Start from zero
- Only if master key compromised

- You CANNOT continue with same identity
- Attacker could impersonate you
- Must generate completely new key pair
- Must rebuild reputation from scratch

---

Signs of potential compromise:

- Unexpected login attempts
- Modified files
- Unusual processes
- Changed configurations

- Validation messages you didn't send
- Agreement percentage anomalies
- Reports from other validators
- Unexpected amendment votes

- Discussion of validator misbehavior
- UNL removal notifications
- Community reports

Token Compromise (master key secure):

Response - Token Compromised:

1. Stop rippled service

1. Generate new token (from secure master key)

1. Update configuration with new token

1. Investigate how token was exposed

1. Fix vulnerability before restarting

1. Restart with new token

Result: Same identity, new token, reputation preserved

Master Key Compromise:

Response - Master Key Compromised:

1. Stop rippled service

1. Notify community (if on UNLs)

1. Generate completely NEW key pair

1. This creates NEW validator identity

1. Deploy new token from new keys

1. Investigate root cause

1. Improve security for new keys

Result: New identity, zero reputation, lessons learned

# Validator Key Compromise Response Plan

For enterprise deployments, consider HSM storage:

• Keys never leave secure hardware

• Tamper-evident/resistant

• Audit logging of all operations

• Compliance requirements often mandate HSM

• AWS CloudHSM

• Azure Dedicated HSM

• On-premise HSM (Thales, Safenet, etc.)

• YubiHSM for smaller deployments

• Master key generated in HSM

• Token signing operations use HSM

• rippled token deployed normally

• Master key never exported

For high-security requirements:

Multi-Person Key Generation:

- Key generator (performs generation)
- Witness (observes, verifies)
- Security officer (supervises)

1. Secure room, no devices
2. Air-gapped laptop provided
3. Generator performs key creation
4. Witness verifies each step
5. Multiple backup copies created
6. Each copy goes to different secure storage
7. Documentation signed by all parties

- Auditable key generation
- No single point of compromise
- Compliance evidence

---

✅ Two-tier architecture protects long-term identity - Token compromise doesn't require abandoning validator identity if master key is secure

✅ Air-gapped key generation is most secure - Keys generated offline cannot be intercepted during creation

✅ Multiple backup locations prevent key loss - Geographic distribution protects against localized disasters

✅ Token rotation preserves reputation - Operational security incident doesn't require reputation rebuild

⚠️ Optimal backup storage strategy - Depends on your threat model, resources, and compliance requirements

⚠️ HSM necessity for non-enterprise operators - Cost/benefit depends on your security requirements

⚠️ Rotation frequency - No consensus on optimal rotation schedule; depends on operational context

📌 Storing master keys on the server - Defeats the purpose of two-tier architecture; server compromise = identity compromise

📌 Single backup location - Fire, theft, or disaster destroys your identity permanently

📌 Weak backup encryption - Encrypted backups with weak passwords are vulnerable

📌 No documented recovery procedure - In crisis, documented procedures prevent mistakes

Key management is the most critical security responsibility for validator operators. The time investment in proper key generation and storage seems excessive until you need it—then it's the difference between a minor incident and losing years of reputation building.

The two-tier architecture exists specifically to protect you. Use it properly: master keys offline, only tokens on servers. If you store master keys on your server "for convenience," you've eliminated the security benefit entirely.

Assignment: Generate validator keys securely and document the process.

Requirements:

• Document the security environment used (air-gapped, live OS, or server with precautions)

• Record the date, time, and location of generation

• Confirm successful key generation (screenshot or output, with secret key redacted)

• Record your validator public key (safe to document)

• Document primary storage method and location

• Document secondary (paper) backup creation

• Document tertiary backup if created

• Verify you can access and read the backed up key file

• Generate validator token from master key

• Document token generation (output with partial redaction)

• Add token to rippled.cfg (but don't restart yet)

• Verify configuration file permissions (600)

• Complete the Key Compromise Response Plan template

• Document contacts and procedures

• Identify your specific secure storage locations

• Note any security improvements for your situation

• PDF or Markdown document

• Screenshots with appropriate redaction

• Completed response plan

• NEVER submit actual secret keys or complete tokens

• Redact sensitive values in screenshots

• Document the process, not the secrets

• Secure generation environment (30%)

• Proper storage implementation (30%)

• Token generation and configuration (20%)

• Complete response planning (20%)

Time investment: 2-4 hours
Value: Secure validator identity that can survive incidents

1. Key Architecture (Tests Technical Understanding):

What is the relationship between the master key and the validator token?

A) They are the same thing with different names
B) The master key signs tokens, which contain ephemeral signing keys; tokens can be rotated while preserving identity
C) The token is the public key and the master key is the private key
D) Tokens are used for backup and master keys for daily operation

Correct Answer: B
Explanation: The master key pair is your permanent identity. Tokens are signed by the master key and contain ephemeral signing credentials that rippled uses for validation. If a token is compromised, you generate a new one from the master key—your identity (public key) is unchanged. This architecture allows recovery from server compromise without losing reputation.

2. Key Storage (Tests Security Knowledge):

Why should the master key (validator-keys.json) NOT be stored on the running validator server?

A) It takes up too much disk space
B) If the server is compromised, an attacker gains complete control of your validator identity
C) rippled doesn't need it—only the token is required
D) Both B and C are correct

Correct Answer: D
Explanation: rippled only needs the token to validate, not the master key—so there's no operational reason for the master key to be on the server. More importantly, if an attacker compromises the server and obtains the master key, they can impersonate your validator permanently. With only the token on the server, an attacker can impersonate temporarily, but you can rotate the token and regain control.

3. Key Compromise (Tests Incident Response):

Your server was compromised and the attacker accessed /opt/ripple/etc/rippled.cfg. Your master key is stored on an encrypted USB in a safe. What's the appropriate response?

A) Generate completely new keys—the identity is lost
B) Generate a new token from the master key, fix the server vulnerability, and deploy the new token
C) No action needed—tokens can't be used without the master key
D) Report to Ripple and wait for instructions

Correct Answer: B
Explanation: Since only the token was on the server and the master key is secure, you can recover by generating a new token. The attacker has the old token but cannot generate new ones or impersonate you indefinitely once you rotate. Fix the server vulnerability, generate a new token from your secure master key, and deploy it. Your validator identity and reputation are preserved.

4. Backup Strategy (Tests Risk Management):

Why is a paper backup of the secret key recommended in addition to encrypted USB storage?

A) Paper is more secure than electronic storage
B) It survives electronic failures, corruption, and encryption password loss
C) Regulations require paper backups
D) It's easier to transport across borders

Correct Answer: B
Explanation: Paper backup provides redundancy against electronic failure modes: USB drives fail, encryption software changes, passwords are forgotten. With a paper backup stored separately, you can recover your validator identity even if all electronic copies are lost. The paper backup should be stored securely (safe, safety deposit box) in a different location than electronic backups.

5. Token Rotation (Tests Operational Knowledge):

After rotating your validator token, what changes and what stays the same?

A) Both public identity and token change; reputation restarts
B) Token changes; public identity and reputation are preserved
C) Public identity changes; token stays the same
D) Everything stays the same—rotation is just verification

Correct Answer: B
Explanation: Token rotation replaces the operational credential (token) while preserving your validator identity (master key pair). Other validators still identify you by the same public key. Your agreement history, uptime statistics, and reputation all remain intact. This is the key benefit of the two-tier architecture—operational incidents don't destroy reputation.

For Next Lesson:
With keys generated and securely stored, Lesson 8 will enable validation—the moment your server begins participating in consensus. We'll cover the enablement process, verification of validation activity, and monitoring for correct operation.

End of Lesson 7

Total words: ~5,600
Estimated completion time: 60 minutes reading + 2-4 hours for secure key generation