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.17; the last
release for Zig 0.16 is v0.4.1, and the zig-0.16 branch carries it. 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 locks, forgetting the keys, 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 Secure Note's notes 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.<uuid>): 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. pair HOST lets HOST sign with this agent over the tailnet, and unpair HOST stops it; see Signing over the tailnet. |
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 unreadable note: a Secure 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 |
Locks the agent, which forgets 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 key selectors to a particular Secure Note, by its name or ID. |
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 remote signature, by either route, is confirmed first (true). |
tailnet_port |
The port an agent bwgpg starts itself listens on over the tailnet; off when not set. Under systemd the socket unit listens instead, and this is only what bwgpg remote pair tells the remote machine (7743 when not set). |
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. This is remote signing. The machine you log in from, where the vault and the agent are, is the key machine, A in the examples; the one you log in to, where git runs, is the remote machine, B. It takes one of two routes: the forward, over SSH, described here, or the tailnet.
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, the extra 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 the summary: what B says it is signing (for a commit, its subject and author), shown to help you recognize it, and not trusted. You sign or deny it.
bwgpg remote allowmakes a session allowed, so that its signatures are no longer confirmed. 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.
Signing over the tailnet #
When both machines are on a Tailscale or headscale tailnet, B can reach the agent on A directly, with no forward. It is still for SSH sessions from A to B: B uses it only during one, and A signs only while that session is open.
B: git ──► bwgpg ──► A's tailnet address, port 7743 (from SSH_CONNECTION)
│ TCP over the tailnet
A: bwgpg-agent-tailnet.socket ──► agent: who is it, is it paired, which session? confirm, then sign
That does away with what makes the forward awkward. There is no
StreamLocalBindUnlink, no /run/user/<uid> to have made in advance, and no
socket file for a second session to take over and leave dead.
B finds A from SSH_CONNECTION. When it begins with a tailnet address
(100.64.0.0/10 [9] or fd7a:115c:a1e0::/48 [10]), and B holds a pairing for
that address, B dials it. The agent on A then checks three things before it
answers:
- The address is a node of the tailnet. It asks tailscaled on A who the
address is: the LocalAPI behind
tailscale whois[11]. An address tailscaled does not know gets no answer at all. - The node is paired, and presents its pairing token. The tailnet names machines, not people: any account on B can reach A's port. So pairing gives B a secret that only your account there can read, and A keeps its SHA-256 against the node's stable ID. Another user on B, or a machine that was unpaired, is refused.
- There is an SSH session for it. B sends its
SSH_CONNECTION. A looks up the TCP connection it names, in/proc/net/tcp[12] on Linux and withGetExtendedTcpTableon Windows: from A's address and port to B's, established, and yours. It then finds the process holding it, which is thesshcarrying the session. That process is the session, as the one carrying a forward is. So confirmation,bwgpg remote allow, and everything ending when ssh exits work as they do for the forward.
What it may do once in is what the forwarded socket may do: describe a key and sign a digest, confirmed on A, with B's environment ignored.
On B, the tailnet comes before the forward: with a pairing for the key machine the session came from, bwgpg uses the tailnet and nothing else. A session from a machine B is not paired with, or one that did not come over the tailnet, uses the forward as before.
Setting it up #
On A, have the agent listen on the tailnet. Under systemd:
$ systemctl --user enable --now bwgpg-agent-tailnet.socket
$ bwgpg stop # so the next start picks the new socket up
With Home Manager, programs.bwgpg.tailnet.enable = true; does this. The unit
listens on port 7743 on every interface. It is not bound to tailscale0,
because tailscaled makes that interface again each time it restarts and a
socket bound to it would stop accepting connections. An agent bwgpg starts
itself listens on A's tailnet addresses when the config sets tailnet_port.
Either way, open the port on the tailnet's interface alone; on NixOS:
networking.firewall.interfaces.tailscale0.allowedTCPPorts = [ 7743 ];. The
agent refuses a connection from outside the tailnet's addresses, and answers
only a paired node during an SSH session from A, but the firewall is what
keeps the port off other networks.
On Windows, set tailnet_port in the config (bwgpg stop so that the next
start picks it up), and let the port in on the Tailscale adapter, from an
administrator's PowerShell:
PS> New-NetFirewallRule -DisplayName "bwgpg over the tailnet" -Direction Inbound `
-Protocol TCP -LocalPort 7743 -InterfaceAlias Tailscale -Action Allow
Then pair B, once:
$ bwgpg remote pair B
paired with b.tailnet.example: during an SSH session from here over the tailnet, it signs with this agent
It makes a pairing token, runs bwgpg remote join on B over ssh to hand it
over, and keeps its hash in tailnet-peers.json in A's state directory. On
B, the token is kept in tailnet-agents.json beside the config, mode 0600.
Those are the two halves of the pairing. With --print, it shows the command
to run on B by hand instead, which includes the token. bwgpg remote unpair B ends the pairing.
After that, ssh to B by its tailnet address or MagicDNS name, so that
SSH_CONNECTION there shows A's tailnet address, and commit as usual. bwgpg
on B needs no other setup than for the forward: gpg.program, the signing
key, and gpg with the public key.
When signing this way fails, B says which of these went wrong:
- Nothing answered on the agent's port. The socket is not running on A, or the firewall there drops the port.
- Not paired. A does not know this node, or the pairing token is wrong: pair again.
- No SSH session. A found no SSH connection of yours from it to B that
matches. This happens when the session went through a jump host, or when
SSH_CONNECTIONis stale, as inside atmuxstarted from a session that has since ended.
What this exposes #
Less than the forward. A forward lets anything running as you on B ask A for signatures; this lets only what can read your pairing token there, during a session of yours from A. Confirmation on A is still what stands between that and a signature. The port answers nobody off the tailnet, and nobody on it who is not paired. The pairing token crosses only the tailnet, which WireGuard encrypts.
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. |
tailnet.enable |
false |
Run the agent's tailnet socket, for signing over the tailnet. Needs agent.enable. |
tailnet.port |
7743 |
Its port, also written to the config as tailnet_port when settings is set. |
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. Building on Windows 10 version 1803 or later, the
native target is that already, and -Dtarget can be left out. In
PowerShell, quote it, since PowerShell splits an unquoted argument that
starts with - at a .:
PS> zig build "-Dtarget=x86_64-windows.win10_rs4-gnu" -Doptimize=ReleaseSafe `
--prefix "$env:LOCALAPPDATA\Programs\bwgpg"
The real gpg and pinentry come from Gpg4win, or from GnuPG's own
Windows installer, whose pinentry-basic.exe is a plain password dialog;
bwgpg looks in both places. Locked memory uses VirtualLock.
Signing over the tailnet works in both
directions: Windows can be A, holding the agent that signs, or B, where git
runs. tailscaled's LocalAPI is reached through its named pipe, and the ssh
behind a session is found with GetExtendedTcpTable and checked against your
account by its process token.
Three 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. - Windows cannot be A for signing over SSH: the agent
does not listen on the extra socket there, since without peer credentials
it cannot tell which
ssha forwarded request comes through. Use the tailnet instead. - 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 locked-memory 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. Over the tailnet it answers only a paired node with its pairing token, for a live SSH session of that user's. - 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.tailnet # signing over the tailnet, three 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 denying the confirmation onafails the commit and signing it there 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 tailnet test boots a headscale server and two machines on its
tailnet. Alice pairs
bfroma, ssh's tob's tailnet address with no forward, and commits there. It checks:- that denying the confirmation on
afails the commit and signing it there signs it - that
bwgpg remote allowworks for the session - that the agent will not lock for
b - that a session that has ended is refused even when named from a live one
- that an unpaired machine is refused
- that without a pairing the forward is used
- that the pairing file on
bis alice's alone - that another user there, with a token of her own making and a live session of alice's to name, is refused
- that denying the confirmation on
- 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. - Coding agents read
AGENTS.md. It points them atdocs/agents/, which says where issues are tracked, which triage labels are used, and where the glossary and decision records are kept.
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
Report issues and open pull requests on the Tangled mirror. See CONTRIBUTING.md for what a report should include and what a change should pass.
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 - Weil, J., Kuarsingh, V., Donley, C., Liljenstolpe, C., and M. Azinger, "IANA-Reserved IPv4 Prefix for Shared Address Space", BCP 153, RFC 6598, Internet Engineering Task Force (IETF), April 2012. https://www.rfc-editor.org/info/rfc6598
- Tailscale, "How Tailscale assigns IP addresses", Tailscale Docs. Accessed 7 October 2026. https://tailscale.com/kb/1033/ip-and-dns-addresses
- Tailscale, "Tailscale CLI: whois", Tailscale Docs. Accessed 7 October 2026. https://tailscale.com/kb/1080/cli
- The Linux man-pages project, "proc_net(5): /proc/net", Linux manual page. Accessed 7 October 2026. https://man7.org/linux/man-pages/man5/proc_net.5.html