Sign git commits and tags with an OpenPGP key kept in Bitwarden.
zig-bwgpg GLOSSARY.md
3.9 kB · 120 lines
Markdown
at main

bwgpg #

bwgpg signs git commits and tags with an OpenPGP key kept in Bitwarden, standing in for gpg. This glossary fixes the words for bwgpg's own concepts; terms that Bitwarden or OpenPGP define and bwgpg uses unchanged are left to them.

Language #

Keys #

Vault: The user's Bitwarden vault. bwgpg reads only its personal Secure Notes. Avoid: vault (for the keys the agent holds)

Secure Note: A personal Bitwarden vault entry whose notes field holds an armored OpenPGP secret key. Avoid: item, note, cipher

Unreadable note: A Secure Note that looks like it holds a key but cannot be parsed as one. Avoid: problem

Key: The OpenPGP transferable secret key held in one Secure Note: a primary key with its subkeys and user IDs. Avoid: keyring

Signing key: The primary key or subkey of a key that is chosen to make a signature.

Key selector: The string that picks a key: a fingerprint, a key ID, or text from a user ID. Avoid: key (for the string), local user, match

Keyring: GnuPG's keyring on disk, which bwgpg never reads or writes.

The agent #

Agent: The long-running bwgpg agent process that holds the decrypted keys and signs digests with them.

Real gpg: The GnuPG program that bwgpg hands every invocation it does not handle itself; handing one over unchanged is passthrough.

Lock / Unlock: The agent's state of not holding / holding the decrypted keys from the vault. Avoid: lock (for locked memory)

Confirmation: The dialog on the key machine that asks whether to make one remote signature, showing its summary. The user signs or denies it. Avoid: approval, refusal

Allowed: Said of an SSH session whose remote signatures skip confirmation until it ends. Revoke returns it to confirmation. Avoid: revoke (for unpairing)

Summary: What the remote machine says it is signing: the commit or tag subject and author. Nothing verifies it. Avoid: claim

Remote signing #

Key machine: The machine whose agent holds the keys and makes the signature. Avoid: agent's machine, peer, A (outside examples)

Remote machine: The machine where git runs and asks the key machine for a signature. Avoid: peer, far end, requesting machine, node, host, B (outside examples)

Remote signing: Signing on the key machine at the remote machine's request. It takes one of two routes: the forward or the tailnet. Avoid: remote (for either route alone)

The forward: The route that carries the extra socket to the remote machine over SSH.

The tailnet: The route on which the remote machine reaches the agent directly over a Tailscale network, during an SSH session.

Extra socket: The agent's restricted socket, the one that is forwarded over SSH. Avoid: remote socket

Forwarded socket: The extra socket as it appears on the remote machine. Avoid: remote socket, extra socket

SSH session: One ssh process on the key machine, carrying a connection to a remote machine, which sees the same connection as its SSH_CONNECTION. A bare "session" means this. Avoid: session (for login, systemd or D-Bus sessions)

Pairing: The standing permission a key machine gives one remote machine to reach its agent over the tailnet. Each side holds its half: the key machine the pairing token's hash bound to the remote machine's node, the remote machine the token and where to reach the agent. Pair makes one from the key machine, join is the remote machine accepting it, and unpair ends it. Avoid: peer (for the key machine's half), agent (for the remote machine's half), revoke (for unpairing)

Pairing token: The secret that admits a remote machine to the agent over the tailnet. Avoid: token