Keystore Version Migration Guide

This guide covers migrating between keystore format versions in ICN.

Version History

Version	Date	Changes	Status
v1	2025-01	Ed25519 keypair only	Legacy
v2	2025-01	+ TLS certificate with DID-TLS binding	Legacy
v2.1	2025-01	+ X25519 keys for end-to-end encryption	Legacy
v3	2026-01	+ DID Document + multi-device metadata	Current

Automatic Migration

ICN automatically migrates your keystore when you unlock it for the first time after upgrading.

What Happens

Unlock with existing passphrase:
```
icnctl id show
# or
icnd
```
Automatic migration:
- Detects old format (v1, v2, or v2.1)
- Generates missing components:
  - v1→v3: TLS certificate + X25519 keys + DID document metadata
  - v2→v3: X25519 keys + DID document metadata (reuses TLS cert)
  - v2.1→v3: DID document metadata
- Saves upgraded keystore immediately
- Overwrites the existing keystore file at {data_dir}/identity.age
Verification:
```
icnctl id show
```
Look for:
- ✅ DID (same as before)
- ✅ TLS certificate persisted
- ✅ X25519 encryption key present

Migration Log

You'll see this in the logs:

✅ Successfully migrated to v3 keystore (multi-device support enabled)

Manual Migration

If automatic migration fails or you want manual control:

Step 1: Backup Current Keystore

CRITICAL: Always backup before manual migration!

cp ~/.icn/identity.age ~/.icn/identity.age.backup-manual
# Or use built-in backup
icnctl backup ~/icn-backup-before-migration.tar.gz.age

Step 2: Check Current Version

# Check keystore format (requires reading the file)
# The version is detected on unlock, so just try to unlock:
icnctl id show

If you see warnings about missing TLS or X25519 keys, you have an old version.

Step 3: Trigger Migration

Simply unlock the keystore:

icnctl id show
# Enter your passphrase when prompted

Migration happens automatically on unlock.

Step 4: Verify Migration

# Check that DID is unchanged
icnctl id show

# Verify keystore file was updated
ls -lh ~/.icn/identity.age

# You should see:
# identity.age              (current format after migration)

Troubleshooting

"Failed to unlock keystore"

Cause: Wrong passphrase or corrupted keystore

Solution:

Double-check your passphrase
Restore from backup:
```
icnctl restore ~/icn-backup.tar.gz.age
```
If still failing, your keystore may be corrupted - restore from backup

"Migration succeeded but TLS/X25519 keys missing"

Cause: Migration didn't save properly

Solution:

Restore from backup

Ensure ~/.icn/ is writable:

ls -ld ~/.icn/
# Should show: drwx------

Re-run migration with debug logging:
```
RUST_LOG=debug icnctl id show
```

"DID changed after migration"

This should NEVER happen! DIDs are derived from Ed25519 public keys, which never change.

If this happens:

STOP IMMEDIATELY

Restore from backup:

icnctl restore ~/icn-backup.tar.gz.age --force

Report bug: https://github.com/InterCooperative-Network/icn/issues

"Backup file is huge"

Cause: Backup includes entire data directory (ledger, trust graph, gossip state)

This is normal. Backups include:

Keystore (~1 KB)
Trust graph (~100 KB for 50 members)
Ledger state (~1 MB for 1000 transactions)
Gossip state (~500 KB)
Snapshots (~500 KB)

To backup only keystore:

tar -czf ~/keystore-only-backup.tar.gz -C ~/.icn identity.age

Version-Specific Details

v1 → v3 Migration

What happens:

Loads Ed25519 keypair (unchanged)
Generates TLS certificate from Ed25519 key
Signs DID-TLS binding proof
Generates X25519 keypair for encryption
Creates v3 bundle
Encrypts with your passphrase
Saves to disk (overwrites identity.age)

Time: < 1 second

Compatibility:

✅ Old nodes can still verify your identity (DID unchanged)
✅ New features (E2E encryption, persistent TLS) now available

v2 → v3 Migration

What happens:

Loads Ed25519 keypair + TLS certificate (unchanged)
Generates X25519 keypair for encryption
Creates v3 bundle
Encrypts with your passphrase
Saves to disk
Stores DID document and device metadata

Time: < 1 second

Compatibility:

✅ TLS certificate reused (no new binding signature needed)
✅ E2E encryption now available

Multi-Device Considerations

If you use multi-device identity:

Migrate primary device first:

# On Device 1 (primary)
icnctl id show  # Triggers migration

Export device credentials:

icnctl device export my-phone > phone-creds.json

Import on other devices:

# On Device 2
icnctl device import phone-creds.json

Verify all devices work:
```
icnctl device list
```

See multi-device-identity-design.md for details.

Downgrading (Not Recommended)

You cannot downgrade keystore versions. v3 keystores cannot be read by older ICN versions.

If you must use an older ICN version:

Restore from pre-migration backup
Use the old ICN version
Do NOT upgrade to new ICN until ready to migrate

Why downgrade is not supported:

Newer formats include more security features (X25519, persistent TLS)
Removing features would compromise security
Old versions lack code to parse new formats

Best Practices

Always backup before upgrading ICN:

icnctl backup ~/icn-backup-before-upgrade.tar.gz.age

Test migration on non-production node first (if possible)
Keep multiple backups:
- Local: ~/icn-backups/
- Off-site: Cloud storage, USB drive, etc.
- Frequency: Weekly for active nodes

Verify migration succeeded:

icnctl id show
icnctl network status  # Ensure peers still connect

Monitor logs during migration:
```
journalctl -u icnd -f
```

FAQ

Q: Will migration change my DID? A: No. DIDs are derived from Ed25519 public keys, which never change during migration.

Q: Will I lose my ledger history? A: No. Migration only affects the keystore. Ledger state is separate.

Q: Do I need to re-establish trust relationships? A: No. Trust graph is unchanged. Peers will recognize your DID.

Q: Can I migrate while icnd is running? A: No. Stop icnd first: sudo systemctl stop icnd

Q: How long does migration take? A: < 1 second. Cryptographic operations are fast.

Q: Can I migrate back to v1/v2/v2.1? A: No. Downgrading is not supported.

Q: What if I have multiple keystores (test/prod)? A: Migrate each separately with explicit data directories:

icnctl --data-dir /path/to/test id show