Keeping Dotfiles Cloud-Ready With GPG

A recent upgrade scare was a good reminder to audit backups. Most important data was covered, but dotfiles were a weak point: years of standard program usage had left plain-text passwords and keys scattered across many config files. The goal became eradicating secrets from disk entirely so dotfiles could be backed up to the cloud without a second thought.

The obvious tool for this is GnuPG, but getting it to work across the typical Unix toolchain is not straightforward. Most programs expect secrets in plain text files, and integration with GPG varies widely in design and difficulty. Assuming you already have a GPG key generated, here's how to assemble the supporting infrastructure and start wiring your tools to it.

Setting Up gpg-agent

The core problem with encrypting secrets is that you'd be entering your passphrase constantly. gpg-agent solves this by caching your passphrase for a set period. Like ssh-agent, it needs some bootstrap code in your shell configuration so that gpg can always locate a running instance.

A standard bootstrap script launches an agent when none is running, or exports the environment settings from the existing one:

#!/bin/sh

# start-gpg-agent

gnupginf="$HOME/.gpg-agent-info"
gnupglog="$HOME/.gpg-agent.log"

if pgrep -x -u "$USER" gpg-agent >/dev/null 2>&1; then
    eval `cat $gnupginf`
    eval `cut -d= -f1 $gnupginf | xargs echo export`
else
    eval `gpg-agent -s --daemon --write-env-file "$gnupginf" \
      --log-file "$gnupglog"`
fi

Source it from your appropriate *rc file (note the leading .):

. start-gpg-agent

Open a new shell and verify the agent is running:

$ gpg-agent
gpg-agent: gpg-agent running and available

The first GPG command will prompt for the passphrase; subsequent commands within the cache window will use the cached value:

$ echo "encrypt me" | gpg --armor --encrypt -
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.13 (Darwin)

hQEMA1XJl0SO//WLAQf/QsLhIqOSgfKtA3EwiIw290aNhpa1gl6rLXXPw3N66zuH
...

#
# CACHED! A passphrase is no longer necessary ...
#

$ echo "encrypt me" | gpg --armor --encrypt -
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.13 (Darwin)

hQEMA1XJl0SO//WLAQf/eBsnpMMoTZIBYEboXmdZcs73EaKD/HDcglQM9k7wyvt3
...

With the right configuration, gpg-agent can also serve as an ssh-agent replacement by duplicating its interface. That setup is optional; gpg-agent insists on managing keys with its own passphrases, which can feel invasive, but it's a viable option.

Integrating the Ecosystem

The real work starts after the agent is running: getting your programs to read secrets from encrypted files instead of plain text. There's no universal standard here, and many programs won't natively cooperate. Still, because of strong Unix conventions, a surprising number of tools can be backpatched for GPG support using simple shell primitives.

The most straightforward case is Curl, which normally reads from a plain .netrc file. Using a stdin pipe trick, it can read from an encrypted .netrc.gpg instead. Some programs, like the Heroku toolbelt, will automatically prefer .netrc.gpg when present, but that's rare.

Converted tools can be curated per use case as they are covered: