Guide 5 of 7 · Keys and 1Password

Keys, 1Password and a fingerprint

There is no private key file anywhere on these Macs. Logging in to servers, signing commits and running sudo all end at the same place: a Touch ID prompt.

The key never leaves the vault

An SSH key proves who you are to a server, and to GitHub. The usual setup keeps that key as a file in ~/.ssh, where any program running as you can read it. This repository's rule is stricter: no private keys on disk, ever.

In plain words

Most people keep the house key under the doormat. Here the key is locked in a safe (1Password) with a guard beside it (the 1Password agent). When something needs the key, the guard does not hand it over. The guard walks to the door, unlocks it, and comes back, after checking your fingerprint.

Three jobs, one fingerprint

Logging in to a server · ssh, git push

sshYou connect to a server, or push to GitHub.
ssh/config“For every host, ask the 1Password agent.”
1PasswordAsks you to approve, with Touch ID where it is set up, then answers the server's challenge with the key.
The serverSees proof that you hold the key. Never sees the key.

Signing a commit · git commit

git commitSigning is switched on for every commit.
git config“Sign with SSH, using 1Password's signing program.”
1PasswordSigns with the key named in ~/.gitconfig-user.
The commitCarries a signature anyone can check.

Becoming administrator · sudo

sudoA command needs administrator rights.
sudo_localApple's own hook for local sudo rules, written by script/macos.
pam_reattachReaches out of tmux to the screen, so the prompt can appear.
Touch IDA fingerprint instead of typing the password.
Three different commands. Each one is routed to something that asks for your fingerprint.

Logging in: two doors to the same guard

Programs find the agent in two different ways, so the repository sets both. Each covers programs the other misses.

WhereWhat it setsWho it is for
ssh/configIdentityAgent, for every hostAnything that runs ssh, including apps that were never started from a shell.
config/zsh/lib/1password.zshThe SSH_AUTH_SOCK variableTools that talk to an agent directly and never read the SSH config file.

One exception

When you connect to one of these Macs over SSH, nobody is sitting at it to touch the sensor. Both settings notice the incoming session and step back, so the keys you brought with you from the other computer are used instead.

The rest of the SSH settings

Signing: proof a commit is yours

Anyone can type any name into a commit. A signature is what proves a commit really came from you, and it is what puts the “Verified” badge on GitHub.

Signing is switched on for every commit in config/git/config. The one piece that differs per Mac is which key to sign with, and that lives in ~/.gitconfig-user, the file you create by hand.

# config/git/config, shared by every Mac
[gpg]
  format = ssh
[gpg "ssh"]
  program = "/Applications/1Password.app/Contents/MacOS/op-ssh-sign"
  allowedSignersFile = ~/.config/git/allowed_signers
[commit]
  gpgsign = true

# ~/.gitconfig-user, private to one Mac
[user]
  signingkey = ssh-ed25519 AAAA...   # the public half

The one thing to remember

If ~/.gitconfig-user is missing, git has no key to sign with and commits cannot be signed. It is the only file a new Mac has to be given by hand.

Checking works the other way round. config/git/allowed_signers lists the public keys this repository trusts, so git log --show-signature can say whether each commit was signed by one of them. Public keys are safe to publish, which is why that file is tracked.

Touch ID for sudo

script/macos sets sudo up to accept a fingerprint. This replaces the password prompt. It does not remove the check: you still have to approve every time.

A public repository with nothing to hide

The repository is public, so three rules keep private things out of it.