- Zig 84%
- Nix 11%
- Shell 5%
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 -Sandgit tag -sask 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-commitandgit 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 stopends it too, but the socket stays and the next signature starts it again.systemctl --user stop bwgpg-agent.socketstops 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_DIRandBWGPG_PINENTRYhave to be set withsystemctl --user set-environmentor a drop-in. The same goes forPATH: the agent searches the user manager'sPATHfor pinentry, not the shell's. So either givepinentryan absolute path in the config, or setBWGPG_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 allowstops the questions for a session. A session is onesshprocess on A, the one carrying the forward, which the agent learns from the socket (SO_PEERCRED).bwgpg remote listshows the sessions,allowwith no process ID allows every one listed, andrevokestarts asking again. An allowed session lasts until its ssh exits or the agent locks, and a new connection is asked again. Settingremote_confirmto 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-lingermakes it permanent, which matters forssh -N, which opens no session.- bwgpg itself, with
git config gpg.program bwgpgand 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.socketis 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_WINDOWbut 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, andVirtualLocked 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 unlessallow_insecure_httpis 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 withgit, 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, thatbwgpg stopends 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
atoband commits onb. It checks that a refusal onafails the commit and an approval signs it, thatbwgpg remote allowstops 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 tagv<version>. The workflow refuses a tag that does not match, builds the Windows zip in ReleaseSafe, and publishes the release withtools/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.zigare throwaway keys made for the purpose.
Where this lives #
Three homes, with the same history in each.
-
Forgejo, at https://git.jcollie.dev/jeff/zig-bwgpg, which is where the workflow runs and the documentation is published from.
-
Radicle, as
rad:z2hniRQryBHa1hbyPKL9LL7wPQXwQ. A Radicle repository is only findable by its ID, so that string is the whole address:$ rad clone rad:z2hniRQryBHa1hbyPKL9LL7wPQXwQ
License #
MIT, and REUSE compliant.
References cited #
- 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
- 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
- Bitwarden, "Bitwarden Security Whitepaper", Bitwarden Help Center. Accessed 29 September 2026. https://bitwarden.com/help/bitwarden-security-white-paper/
- 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
- 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
- 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
- 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
- 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