Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration Encryption Quick Reference

Setup (One-time)

# 1. Initialize encryption
provisioning config init-encryption --kms age

# 2. Set environment variables (add to ~/.zshrc or ~/.bashrc)
export SOPS_AGE_RECIPIENTS="age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"
export PROVISIONING_KAGE="$HOME/.config/sops/age/keys.txt"

# 3. Validate setup
provisioning config validate-encryption

Common Commands

TaskCommand
Encrypt fileprovisioning config encrypt secrets.yaml --in-place
Decrypt fileprovisioning config decrypt secrets.enc.yaml
Edit encryptedprovisioning config edit-secure secrets.enc.yaml
Check if encryptedprovisioning config is-encrypted secrets.yaml
Scan for unencryptedprovisioning config scan-sensitive workspace --recursive
Encrypt all sensitiveprovisioning config encrypt-all workspace/config --kms age
Validate setupprovisioning config validate-encryption
Show encryption infoprovisioning config encryption-info secrets.yaml

File Naming Conventions

Automatically encrypted by SOPS:

  • workspace/*/config/secure.yaml ← Auto-encrypted
  • *.enc.yaml ← Auto-encrypted
  • *.enc.yml ← Auto-encrypted
  • *.enc.toml ← Auto-encrypted
  • workspace/*/config/providers/*credentials*.toml ← Auto-encrypted

Quick Workflow

# Create config with secrets
cat > workspace/config/secure.yaml <<EOF
database:
  password: supersecret
api_key: secret_key_123
EOF

# Encrypt in-place
provisioning config encrypt workspace/config/secure.yaml --in-place

# Verify encrypted
provisioning config is-encrypted workspace/config/secure.yaml

# Edit securely (decrypt -> edit -> re-encrypt)
provisioning config edit-secure workspace/config/secure.yaml

# Configs are auto-decrypted when loaded
provisioning env  # Automatically decrypts secure.yaml

KMS Backends

BackendUse CaseSetup Command
AgeDevelopment, simple setupprovisioning config init-encryption --kms age
AWS KMSProduction, AWS environmentsConfigure in .sops.yaml
VaultEnterprise, dynamic secretsSet VAULT_ADDR and VAULT_TOKEN
CosmianConfidential computingConfigure in config.toml

Security Checklist

  • ✅ Encrypt all files with passwords, API keys, secrets
  • ✅ Never commit unencrypted secrets to git
  • ✅ Set file permissions: chmod 600 ~/.config/sops/age/keys.txt
  • ✅ Add plaintext files to .gitignore: *.dec.yaml, secrets.yaml
  • ✅ Regular key rotation (quarterly for production)
  • ✅ Separate keys per environment (dev/staging/prod)
  • ✅ Backup Age keys securely (encrypted backup)

Troubleshooting

ProblemSolution
SOPS binary not foundbrew install sops
Age key file not foundprovisioning config init-encryption --kms age
SOPS_AGE_RECIPIENTS not setexport SOPS_AGE_RECIPIENTS="age1..."
Decryption failedCheck key file: provisioning config validate-encryption
AWS KMS Access DeniedVerify IAM permissions: aws sts get-caller-identity

Testing

# Run all encryption tests
nu provisioning/core/nulib/lib_provisioning/config/encryption_tests.nu

# Run specific test
nu provisioning/core/nulib/lib_provisioning/config/encryption_tests.nu --test roundtrip

# Test full workflow
nu provisioning/core/nulib/lib_provisioning/config/encryption_tests.nu test-full-encryption-workflow

# Test KMS backend
use lib_provisioning/kms/client.nu
kms-test --backend age

Integration

Configs are automatically decrypted when loaded:

# Nushell code - encryption is transparent
use lib_provisioning/config/loader.nu

# Auto-decrypts encrypted files in memory
let config = (load-provisioning-config)

# Access secrets normally
let db_password = ($config | get database.password)

Emergency Key Recovery

If you lose your Age key:

  1. Check backups: ~/.config/sops/age/keys.txt.backup
  2. Check other systems: Keys might be on other dev machines
  3. Contact team: Team members with access can re-encrypt for you
  4. Rotate secrets: If keys are lost, rotate all secrets

Advanced

Multiple Recipients (Team Access)

# .sops.yaml
creation_rules:
  - path_regex: .*\.enc\.yaml$
    age: >-
      age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p,
      age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8q

Key Rotation

# Generate new key
age-keygen -o ~/.config/sops/age/keys-new.txt

# Update .sops.yaml with new recipient

# Rotate keys for file
provisioning config rotate-keys workspace/config/secure.yaml <new-key-id>

Scan and Encrypt All

# Find all unencrypted sensitive configs
provisioning config scan-sensitive workspace --recursive

# Encrypt them all
provisioning config encrypt-all workspace --kms age --recursive

# Verify
provisioning config scan-sensitive workspace --recursive

Documentation

  • Full Guide: docs/user/CONFIG_ENCRYPTION_GUIDE.md
  • SOPS Docs: https://github.com/mozilla/sops
  • Age Docs: https://age-encryption.org/

Last Updated: 2025-10-08