Sign git commits and tags with an OpenPGP key kept in Bitwarden.
README.md

bwgpg #

bwgpg signs git commits and tags with an OpenPGP key that is kept in Bitwarden rather than on disk. Set it as git's gpg.program and it stands in for gpg:

  • Detached signatures, which is what git commit -S and git tag -s ask for, bwgpg makes itself. The key comes from a Bitwarden Secure Note by way of a small agent that asks for the master password once.
  • Everything else, including git verify-commit and git log --show-signature, it passes to the real gpg unchanged.

The secret key is never written to disk, and it is never imported into a GnuPG keyring. It is decrypted into locked memory in the agent, and the agent signs digests with it and nothing else.

It runs on Linux and Windows. It is written in Zig 0.16. The API documentation is generated from the doc comments and published at https://jeff.jcollie.page/zig-bwgpg/.

$ git clone https://git.jcollie.dev/jeff/zig-bwgpg.git
$ cd zig-bwgpg
$ nix develop -c zig build

How it works #

git ──(gpg.program=bwgpg --status-fd=2 -bsau KEY, data on stdin)──► bwgpg
    not a detached signature ──► the real gpg, same arguments, same exit status
    detached signature ──► agent: "which key is KEY?" ──► fingerprint, algorithm
                           hash (data ‖ signature trailer) with SHA-512, locally
                           agent: "sign this digest"  ──► signature
                           write the armored signature, and SIG_CREATED for git

bwgpg agent
    pinentry ──► master password ──► PBKDF2 or Argon2id ──► user key
    personal API key ──► access token ──► /api/sync ──► every personal Secure Note
    notes holding "-----BEGIN PGP PRIVATE KEY BLOCK-----" ──► parsed, kept in locked memory

The data being signed never goes to the agent, and the key never leaves it. The agent is started automatically the first time it is needed. It detaches, and it forgets everything after lock_timeout_secs (an hour by default) without a signature.

What it signs with #

Key OpenPGP algorithm Implementation
Ed25519 as GnuPG 2.2 to 2.4 make it 22, EdDSALegacy [1] std.crypto.sign.Ed25519
Ed25519 as RFC 9580 defines it 27 [1] std.crypto.sign.Ed25519
RSA, 512 to 4096 bits 1 or 3 [1] rsa.pkcs1v1_5 from zig-std-crypto-ext

Signatures are version 4, over SHA-512, carrying the issuer fingerprint and key ID [1][2]. A primary key that cannot sign is passed over for its newest signing subkey, as gpg does. The key has to be exported without a passphrase: Bitwarden's encryption is what protects it.

Setting it up #

1. Put the key in Bitwarden #

Export the secret key without a passphrase. If it has one, remove it in a throwaway copy of the keyring rather than in the real one:

$ export GNUPGHOME=$(mktemp -d)
$ cp -r ~/.gnupg/. "$GNUPGHOME"
$ gpg --passwd YOURFINGERPRINT          # set an empty passphrase
$ gpg --armor --export-options export-minimal \
      --export-secret-keys YOURFINGERPRINT > key.asc
$ gpg --list-packets key.asc | grep -iE 'protect|s2k'   # no output: no passphrase
$ wc -c key.asc

Bitwarden limits a note to 10,000 characters after encryption, and encryption adds about a third, so key.asc has to be under about 7,400 characters. export-minimal does most of the work: it keeps only the key's own latest self-signatures and drops the certifications other people have made on it. bwgpg never reads those, and they stay on the published public key. An Ed25519 key comes to well under 2,000 characters.

A large RSA key can still be too big after that, because the secret half of each 4096-bit key or subkey adds about 1,800 characters. Subkeys that do not sign, such as encryption or authentication (e or a in gpg -K), can be left out: an exclamation mark after a fingerprint tells gpg to export exactly that key, and none of its other subkeys.

$ gpg --armor --export-options export-minimal \
      --export-secret-keys 'PRIMARYFINGERPRINT!' > key.asc          # the primary alone
$ gpg --armor --export-options export-minimal \
      --export-secret-keys 'PRIMARYFINGERPRINT!' 'SIGNINGSUBKEY!' > key.asc

The quotes keep the shell from reading ! as history expansion. Use the first form when the primary key signs (s in its capabilities). Use the second when signing is done by a subkey. The primary key's secret has to be included either way: bwgpg does not read the stubs gpg writes for a primary key held elsewhere.

Make a Secure Note in your personal vault (not an organization's), and paste all of key.asc into its notes. The name can be anything. bwgpg finds keys by looking for the armor header in every Secure Note. Then remove key.asc, the throwaway keyring, and the secret key from your real keyring, keeping the public key so that verification still works:

$ shred -u key.asc; rm -rf "$GNUPGHOME"; unset GNUPGHOME
$ gpg --delete-secret-keys YOURFINGERPRINT

2. Log in #

bwgpg logs in with your personal API key, not your password: in the web vault, go to Settings, Security, Keys, View API key. The API key login needs no second factor. The master password never goes to the server; it is only used to decrypt.

$ bwgpg login
Server URL (e.g. https://vault.bitwarden.com): https://vault.example.org
Account email: you@example.org
API key client_id (user.…): user.0123abcd-…

It asks for the client_secret through pinentry, so it is not echoed. It checks the key with the server, then writes the config file. For Bitwarden's own cloud, the identity and API servers are separate; set identity_url to https://identity.bitwarden.com and api_url to https://api.bitwarden.com in the config.

3. Point git at it #

$ bwgpg git-setup --global                  # every repository
$ bwgpg git-setup --key you@example.org     # or just the one you are in

git-setup asks the agent which key is meant, which may mean asking for the master password, and refuses a key the vault does not hold. It then sets gpg.format, gpg.program, user.signingkey (always the fingerprint), commit.gpgSign and tag.gpgSign. --no-sign-by-default leaves the last two alone, and --dry-run shows what it would set. Without --key, it uses the config's default_key, or the vault's only key.

Commands #

Command Does
bwgpg login Sets up the server, account and API key. --server, --email, --client-id and --client-secret-stdin for scripts.
bwgpg remote Lists the SSH sessions signing with this machine's agent. allow [PID] stops confirming a session's signatures, or every session's without a PID; revoke [PID] starts again.
bwgpg git-setup Configures git to sign with bwgpg, in the current repository (--repo DIR for another) or --globally. --key, --no-sign-by-default, --dry-run.
bwgpg unlock Asks for the master password now rather than at the next signature.
bwgpg status Shows whether the agent is unlocked, the keys it found, and any note that looked like a key but could not be read.
bwgpg sync Fetches the vault again, after a key has been added or changed.
bwgpg lock Forgets the vault and the keys.
bwgpg stop Stops the agent.
bwgpg agent [--foreground] Runs the agent. It is started automatically; --foreground keeps it attached so its log can be watched.
bwgpg <gpg arguments> Acts as gpg.

Configuration #

Linux Windows
Config $XDG_CONFIG_HOME/bwgpg/config.json, else ~/.config/bwgpg/config.json %APPDATA%\bwgpg\config.json
Agent socket $XDG_RUNTIME_DIR/bwgpg/agent.sock %LOCALAPPDATA%\bwgpg\agent.sock
State (device_id) $XDG_STATE_HOME/bwgpg/, else ~/.local/state/bwgpg/ %LOCALAPPDATA%\bwgpg\

The base directories come from known-folders, which on Windows asks the shell for them rather than reading the environment. BWGPG_CONFIG, BWGPG_RUNTIME_DIR and BWGPG_STATE_DIR override the three.

The API key's secret goes in the config as client_secret, or in a file of its own named by client_secret_file. With the secret inline, the config must be mode 0600 on Linux, and the agent refuses it otherwise. With a secret file, that file must be mode 0600 instead, and the config can be readable by anyone. That is how a config written by Home Manager works.

Field Meaning
base_url The server, e.g. https://vault.example.org.
identity_url, api_url For a server that splits them, as Bitwarden's cloud does.
email, client_id The account, and its API key's client_id.
client_secret or client_secret_file The API key's secret, or a file holding it.
device_id Optional: a UUID naming this installation to the server. bwgpg login writes one; without it, one is made once and kept in the state directory.
keys Optional: [{"match": ["FINGERPRINT", "you@example.org"], "item": "note name"}] pins selectors to a particular note.
default_key The key to use when gpg is given no -u.
pinentry The pinentry program. By default, BWGPG_PINENTRY if it is set in the agent's environment, else the first of pinentry, pinentry-gnome3, pinentry-qt, pinentry-gtk-2, pinentry-curses and pinentry-tty on PATH, or Gpg4win's on Windows.
gpg The real gpg. By default, gpg2 or gpg on PATH (never bwgpg itself), or GnuPG's on Windows.
lock_timeout_secs Idle seconds before the agent locks (3600).
remote_confirm Whether each signature asked for over SSH is confirmed first (true).

A terminal pinentry needs GPG_TTY set, as it does for gpg: export GPG_TTY=$(tty).

Running the agent under systemd #

On Linux the agent can be a socket-activated systemd user service. systemd listens on $XDG_RUNTIME_DIR/bwgpg/agent.sock and starts the agent on the first connection, so it is supervised and its log goes to the journal. The units are in contrib/systemd/, and the Nix package installs them in share/systemd/user/ with the path to bwgpg filled in.

$ systemctl --user enable --now bwgpg-agent.socket

Without Nix, copy contrib/systemd/* into ~/.config/systemd/user/, replace @bwgpg@ in the service with the path to bwgpg, and run systemctl --user daemon-reload first. On NixOS, systemd.packages = [ bwgpg ] makes them available; the Home Manager module sets them up by itself.

Under systemd:

  • The agent comes and goes. It exits once it locks after going unused, and bwgpg stop ends it too, but the socket stays and the next signature starts it again. systemctl --user stop bwgpg-agent.socket stops it for good.
  • Its log is in journalctl --user -u bwgpg-agent.
  • Its environment is the user manager's, not the shell's. pinentry still appears where the request came from, because every request carries the display and terminal variables. But BWGPG_CONFIG, BWGPG_RUNTIME_DIR, BWGPG_STATE_DIR and BWGPG_PINENTRY have to be set with systemctl --user set-environment or a drop-in. The same goes for PATH: the agent searches the user manager's PATH for pinentry, not the shell's. So either give pinentry an absolute path in the config, or set BWGPG_PINENTRY, which the Home Manager module does.

Without the units, nothing changes: the first bwgpg command that needs the agent starts it, as it does on Windows.

Signing over SSH #

bwgpg can sign on a machine you have logged in to over SSH with the keys held by the agent on the machine you logged in from, much as ssh-agent and gpg-agent can be forwarded. Call them A, where the vault and the agent are, and B, where git runs.

B: git ──► bwgpg ──► $XDG_RUNTIME_DIR/bwgpg-remote.sock
                          │ RemoteForward, over the ssh connection
A: ssh ──► $XDG_RUNTIME_DIR/bwgpg/agent-extra.sock ──► agent: confirm, then sign
  • Only a digest crosses the connection. The client on B hashes the commit itself and sends the SHA-512 digest; the agent on A signs it; the key stays on A and the commit stays on B.
  • The forwarded socket is a restricted one. The agent listens on a second socket, agent-extra.sock, which answers only "which key is this" and "sign this digest". It will not unlock, lock, sync or stop, and it ignores the environment B sends, since B's display and terminal mean nothing on A. Any prompt appears on A's own screen.
  • Each signature is confirmed on A. A dialog shows the SSH session, the key, and what B says it is signing (for a commit, its subject and author: B's claim, shown to help you recognize it, and not trusted). The answer is Sign or Deny.
  • bwgpg remote allow stops the questions for a session. A session is one ssh process on A, the one carrying the forward, which the agent learns from the socket (SO_PEERCRED). bwgpg remote list shows the sessions, allow with no process ID allows every one listed, and revoke starts asking again. An allowed session lasts until its ssh exits or the agent locks, and a new connection is asked again. Setting remote_confirm to false in the config stops the questions altogether.

Setting it up #

On A, forward the extra socket to B:

# ~/.ssh/config on A
Host B
    RemoteForward /run/user/%i/bwgpg-remote.sock /run/user/%i/bwgpg/agent-extra.sock

%i is A's uid, which assumes the same uid on B; write B's path out if it differs. With Home Manager, programs.bwgpg.remote.hosts = [ "B" ]; writes this line. The agent on A must be listening on the extra socket: under systemd, systemctl --user enable --now bwgpg-agent-extra.socket (Home Manager does this too); an agent bwgpg starts itself always listens on both.

On B:

  • sshd needs StreamLocalBindUnlink yes, so that a socket left behind by an earlier connection is replaced rather than blocking the forward. On NixOS: services.openssh.settings.StreamLocalBindUnlink = true;.
  • /run/user/<uid> has to exist when the forward is set up. A login session makes it; loginctl enable-linger makes it permanent, which matters for ssh -N, which opens no session.
  • bwgpg itself, with git config gpg.program bwgpg and your signing key, and gpg with your public key, so that signatures can be verified there. No config, vault or pinentry.

During an SSH session, bwgpg on B uses the forwarded socket when it is there (SSH_CONNECTION set and $XDG_RUNTIME_DIR/bwgpg-remote.sock present). BWGPG_AGENT_SOCKET names a socket outright, as SSH_AUTH_SOCK does for ssh-agent. Using a forwarded socket, it never starts an agent of its own. When signing through it fails, it says which of two things went wrong:

  • Nothing is listening on the socket. The file was left by an SSH session that has ended. sshd does not remove a forwarded socket when the session closes, so with two sessions to B at once, the newer one takes the socket over and leaves it dead behind it when it exits, under the older one. Logging in again replaces it.
  • The forward answers, but no agent does. ssh reached A and found nothing on the extra socket there: the agent on A is not running, or bwgpg-agent-extra.socket is not enabled.

What this exposes #

While the forward is up and the agent unlocked, anything running as you on B, or as root there, can ask A for signatures. That is the same exposure as forwarding ssh-agent. Confirmation on A is what stands between that and a signature, and allowing a session gives it up for that session. Forward to machines you trust, and allow sessions only on them.

Home Manager #

The flake provides a Home Manager module, homeModules.default (also available as homeManagerModules.default). It installs bwgpg, runs its agent socket-activated under systemd on Linux, and has git sign with it through Home Manager's own programs.git.signing, as bwgpg git-setup --global would. It writes bwgpg's config only when settings is set; otherwise bwgpg login writes it as usual.

{
  inputs.bwgpg.url = "git+https://git.jcollie.dev/jeff/zig-bwgpg";

  # in the Home Manager configuration:
  imports = [ inputs.bwgpg.homeModules.default ];

  programs.git.enable = true;
  programs.bwgpg = {
    enable = true;
    git.signingKey = "0123456789ABCDEF0123456789ABCDEF01234567";
    settings = {
      base_url = "https://vault.example.org";
      email = "you@example.org";
      client_id = "user.01234567-89ab-cdef-0123-456789abcdef";
      # Outside the Nix store: sops-nix, agenix, or a file made by hand.
      client_secret_file = config.sops.secrets."bwgpg/client_secret".path;
    };
  };
}
Option Default Meaning
enable false Install bwgpg.
package this flake's The bwgpg package.
settings null bwgpg's config.json. Any config field may be given. base_url, email, client_id and client_secret_file are required.
pinentry.package pkgs.pinentry-gnome3 The pinentry that asks for the master password, handed to the agent through BWGPG_PINENTRY in the systemd unit and the session. It falls back to a terminal prompt without a desktop; pinentry-qt suits KDE. When null, the agent searches its PATH.
agent.enable true on Linux Run the agent as a socket-activated systemd user service.
remote.hosts [ ] SSH hosts to forward the agent's extra socket to, so git there signs with the keys held here. Needs programs.ssh.enable.
remote.socketPath /run/user/%i/bwgpg-remote.sock Where the forwarded socket appears on those hosts; %i is this machine's uid.
git.enable true Have git sign with bwgpg.
git.signingKey null The key's fingerprint. When null, bwgpg picks from the committer's identity, default_key, or the vault's only key.
git.signByDefault true Sign every commit and tag.

settings.client_secret is refused by an assertion, and so is a client_secret_file inside the Nix store: anything in the store can be read by every user on the machine. The git settings are defaults, and programs.git.signing can still override them.

Windows #

A Windows build is attached to every release, at https://git.jcollie.dev/jeff/zig-bwgpg/releases: a zip holding bwgpg.exe, this README and the license, with its SHA-256 beside it. Put bwgpg.exe somewhere on PATH and follow the setup above.

To build one yourself, build with -Dtarget=x86_64-windows.win10_rs4-gnu. The agent talks over an AF_UNIX socket, which Windows has had since Windows 10 version 1803, and Zig's standard library only provides it for a target that says it is at least that version. The real gpg and pinentry come from Gpg4win. Locked memory uses VirtualLock.

Two things are weaker than on Linux:

  • There is no peer-credential check on the socket. Access rests on the socket file living in %LOCALAPPDATA%, which only the user and administrators can open.
  • The agent is started with CREATE_NO_WINDOW but not detached from a job object. A terminal that kills its whole job on exit stops the agent too, and the next signature starts it again.

Security #

  • The key only exists decrypted in the agent, in pages that are mlocked and excluded from core dumps (MADV_DONTDUMP) on Linux, and VirtualLocked on Windows. They are wiped when freed. The agent also makes itself non-dumpable, which on Linux stops other processes of the same user from attaching to it. If the lock limit is too small for Argon2id's memory, the pages are still wiped.
  • Only digests are signed. A process that can talk to the agent can have anything signed while it is unlocked, as with gpg-agent. On Linux the agent answers only its own user (SO_PEERCRED), and the socket is in a 0700 directory.
  • Every EncString's MAC is checked before anything is decrypted [3]. Only type 2 (AES-256-CBC with HMAC-SHA256) is accepted. The legacy unauthenticated type 0 is refused, and so are the RSA types that organization items need.
  • KDF parameters are checked. PBKDF2 below 5000 iterations or Argon2id below 16 MiB is refused [4][5], so that a hostile server cannot make the password cheap to guess.
  • Plain http:// is refused unless allow_insecure_http is set, which exists for the tests.

Development #

$ nix develop
$ zig build test                    # unit tests
$ zig build interop                 # signatures made here, verified by gpg
$ zig build -Dtarget=x86_64-windows.win10_rs4-gnu
$ zig build test -Dtarget=x86_64-windows.win10_rs4-gnu -fwine
$ nix build .#checks.x86_64-linux.vaultwarden   # the NixOS test
$ nix build .#checks.x86_64-linux.ssh           # signing over SSH, two machines
$ nix build .#checks.x86_64-linux.home-manager  # the Home Manager module
$ zig build docs-serve              # the API documentation, locally
  • The interop step generates Ed25519, RSA 3072, RSA 4096 and signing subkey keys with gpg, signs with bwgpg's signer, and has gpg verify each one.
  • The NixOS test runs Vaultwarden in a virtual machine. bwgpg-fixture (tests/fixture.zig, installed with -Dfixture) registers an account the way a Bitwarden client does, makes an API key, and stores a key in a Secure Note under an item key of its own. An ordinary user then signs commits and tags with git, verifies them, and checks that a wrong password fails. It then signs again with a config shaped like Home Manager's, readable by anyone with the secret in a separate file, and checks that a secret file others can read is refused. Last, it enables the systemd socket and checks that the first signature starts the agent, that bwgpg stop ends it while the socket stays, and that the next signature starts it again. It needs a runner with KVM.
  • The SSH test boots two machines. Alice forwards the agent's extra socket from a to b and commits on b. It checks that a refusal on a fails the commit and an approval signs it, that bwgpg remote allow stops the questions for that session but not the next, and that the forwarded socket will not lock the agent.
  • The Home Manager check builds a Home Manager configuration with the module and checks the git settings and config.json it writes. It then starts the agent with that config, to prove bwgpg accepts it.
  • Releases come from tags. Set the new version in build.zig.zon, which is the only place it is kept, commit it, and push a tag v<version>. The workflow refuses a tag that does not match, builds the Windows zip in ReleaseSafe, and publishes the release with tools/forgejo-release.sh, which uses only the Forgejo API and can be run again for the same tag.
  • The OpenPGP test keys in src/openpgp/testing_keys.zig are throwaway keys made for the purpose.

Where this lives #

Three homes, with the same history in each.

License #

MIT, and REUSE compliant.

References cited #

  1. Wouters, P., Huigens, D., Winter, J., and Y. Niibe, "OpenPGP", RFC 9580, Internet Engineering Task Force (IETF), July 2024. https://www.rfc-editor.org/info/rfc9580
  2. Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. Thayer, "OpenPGP Message Format", RFC 4880, Internet Engineering Task Force (IETF), November 2007. Obsoleted by RFC 9580. https://www.rfc-editor.org/info/rfc4880
  3. Bitwarden, "Bitwarden Security Whitepaper", Bitwarden Help Center. Accessed 29 September 2026. https://bitwarden.com/help/bitwarden-security-white-paper/
  4. Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: Password-Based Cryptography Specification Version 2.1", RFC 8018, Internet Engineering Task Force (IETF), January 2017. https://www.rfc-editor.org/info/rfc8018
  5. Biryukov, A., Dinu, D., Khovratovich, D., and S. Josefsson, "Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications", RFC 9106, Internet Research Task Force (IRTF), September 2021. https://www.rfc-editor.org/info/rfc9106
  6. Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)", RFC 5869, Internet Engineering Task Force (IETF), May 2010. https://www.rfc-editor.org/info/rfc5869
  7. Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, Internet Research Task Force (IRTF), January 2017. https://www.rfc-editor.org/info/rfc8032
  8. The GnuPG Project, "GnuPG Details: Format of the colon listings and status messages" (doc/DETAILS). Accessed 29 September 2026. https://github.com/gpg/gnupg/blob/master/doc/DETAILS