Skip to main content
This dotfiles setup uses age for encrypting sensitive files before committing them to git. The encryption key is managed through Bitwarden for secure backup and retrieval.

​
How It Works

Age encryption allows you to:
  • Store encrypted files in your public dotfiles repository
  • Decrypt them automatically when applying dotfiles
  • Keep your encryption key secure in Bitwarden

​
Installation

Age is installed during bootstrap:
bootstrap.sh:16-18
# 1. Update and install basic dependencies
sudo apt-get update
sudo apt-get install -y curl git age gnupg software-properties-common snapd

​
Key Retrieval and Generation

The bootstrap script handles age key setup automatically:
bootstrap.sh:64-79
# 6. Retrieve or Initialize age key
mkdir -p "$HOME/.config/chezmoi"
if [ ! -f "$HOME/.config/chezmoi/key.txt" ]; then
    echo "Checking for age key in Bitwarden..."
    if bw get notes "chezmoi-age-key" > "$HOME/.config/chezmoi/key.txt" 2>/dev/null; then
        echo "Successfully retrieved age key from Bitwarden."
    else
        echo "Could not find 'chezmoi-age-key' in Bitwarden."
        echo "Generating a new one instead..."
        age-keygen -o "$HOME/.config/chezmoi/key.txt"
        echo "IMPORTANT: Save the following content as a Secure Note named 'chezmoi-age-key' in Bitwarden:"
        cat "$HOME/.config/chezmoi/key.txt"
    fi
fi
sudo chown -R "$(id -u):$(id -g)" "$HOME/.config/chezmoi"
chmod 600 "$HOME/.config/chezmoi/key.txt"

​
Process Flow

  1. Check for existing key: Looks in ~/.config/chezmoi/key.txt
  2. Try Bitwarden: Attempts to retrieve from Secure Note named chezmoi-age-key
  3. Generate if missing: Creates new key if not in Bitwarden
  4. Prompt for backup: Displays key content to save in Bitwarden
  5. Set permissions: Ensures key file is only readable by owner (600)

​
Chezmoi Configuration

Age encryption is configured in chezmoi’s config:
.chezmoi.toml.tmpl:16
encryption = "age"
.chezmoi.toml.tmpl:45-47
[age]
    identity = "~/.config/chezmoi/key.txt"
    recipient = {{ output "age-keygen" "-y" (joinPath .chezmoi.homeDir ".config/chezmoi/key.txt") | trim | quote }}

​
Configuration Details

  • encryption = "age" - Enables age encryption globally
  • identity - Path to your private key for decryption
  • recipient - Public key derived from identity for encryption

​
Encrypting Files

​
Add Encrypted File to Chezmoi

chezmoi add --encrypt ~/.ssh/config
This creates an .age encrypted file in your source directory: 
private_dot_ssh/encrypted_config.tmpl.age

​
File Naming Convention

  • encrypted_ prefix indicates age encryption
  • .age suffix marks the file as encrypted
  • .tmpl indicates it’s a template (if templating is also used)
Example: encrypted_config.tmpl.age

​
Encrypted Files in This Repo

​
SSH Config

private_dot_ssh/encrypted_config.tmpl.age
Contains SSH client configuration with host aliases and connection settings.
Always use --encrypt flag when adding sensitive files containing:
  • Connection strings
  • API endpoints
  • Server addresses
  • Any configuration that might reveal infrastructure details

​
Decryption Process

When you run chezmoi apply, encrypted files are:
  1. Decrypted using your age identity (~/.config/chezmoi/key.txt)
  2. Processed as templates (if .tmpl suffix exists)
  3. Written to target location with proper permissions

​
Security Table

SecretStorageHow it’s used
SSH private keyBitwarden Secure NotePulled via bitwarden template function
AWS credentialsBitwarden Custom FieldsPulled via bitwardenFields template function
age private keyBitwarden Secure NoteRetrieved during bootstrap, stored at ~/.config/chezmoi/key.txt
Encrypted filesGit repo (.age)Decrypted by chezmoi using the age identity

​
Manual Age Operations

​
Encrypt a File

age -r $(age-keygen -y ~/.config/chezmoi/key.txt) -o secret.txt.age secret.txt

​
Decrypt a File

age -d -i ~/.config/chezmoi/key.txt secret.txt.age > secret.txt

​
View Public Key

age-keygen -y ~/.config/chezmoi/key.txt
Outputs: 
age1qlz7y0...your-public-key

​
Key Rotation

To rotate your age key:
  1. Generate new key: 
    age-keygen -o ~/.config/chezmoi/key-new.txt
  2. Re-encrypt all files: 
    chezmoi re-add
  3. Update Bitwarden:
    • Save new key as chezmoi-age-key Secure Note
    • Delete old key securely
  4. Replace key file: 
    mv ~/.config/chezmoi/key-new.txt ~/.config/chezmoi/key.txt
chmod 600 ~/.config/chezmoi/key.txt

​
Best Practices

  • Keep your age key in Bitwarden as chezmoi-age-key Secure Note
  • Never commit unencrypted key.txt to git
  • Set restrictive permissions (600) on the key file
  • Encrypt any file containing secrets before adding to chezmoi
  • Test decryption on new machines to ensure key backup works

​
Troubleshooting

​
Decryption Failed

If chezmoi apply fails with decryption errors: 
# Verify key exists
ls -la ~/.config/chezmoi/key.txt

# Check permissions
chmod 600 ~/.config/chezmoi/key.txt

# Verify it's a valid age key
age-keygen -y ~/.config/chezmoi/key.txt

​
Missing Key

If key is missing, retrieve from Bitwarden: 
bw_unlock
bw get notes "chezmoi-age-key" > ~/.config/chezmoi/key.txt
chmod 600 ~/.config/chezmoi/key.txt

Build docs developers (and LLMs) love

Get started for freeTalk to us