vault-plugin-secrets-gpg/README.md

vault-plugin-secrets-gpg

A HashiCorp Vault / OpenBao secrets engine that manages GPG / OpenPGP keys and performs signing, verification, encryption and decryption with them — the transit engine, but the key material is OpenPGP.

Keys are generated and stored inside Vault's own barrier storage (seal-wrapped under key/) and the private key never leaves Vault unless a key is explicitly marked exportable. Each named key is versioned: rotating adds a new OpenPGP entity, while older versions are retained so archived signatures still verify and old ciphertext still decrypts.

The armored public key the engine hands back is a standard, importable OpenPGP key, so gpg, pass and friends can encrypt to it while the private key stays in Vault and decryption is delegated back to decrypt/<name>.

gpg / pass  ──encrypt to public key──▶  binary .gpg
    │                                       │
    │ import public key                     │ decrypt/<name>
    ▼                                       ▼
export/public-key/<name>  ◀── Vault ──▶  private key (never leaves the barrier)

Paths

Path	Purpose
keys/<name> (write/read/delete, list keys/)	generate a key (rsa-2048, rsa-3072, rsa-4096, ed25519); read metadata + armored public key
keys/<name>/config	set min_decryption_version, deletion_allowed, exportable
keys/<name>/rotate	add a new version (older versions kept for decrypt/verify)
keys/<name>/import	import an existing armored private key
export/<public-key|private-key>/<name>[/<version>]	export armored key material
sign/<name> / verify/<name>	detached OpenPGP signature over base64 input
encrypt/<name> / decrypt/<name>	OpenPGP encrypt to / decrypt with the key

Creating a key is idempotent — writing keys/<name> again returns the existing key rather than regenerating it. Deletion is refused unless deletion_allowed=true is set via keys/<name>/config.

Usage

# register + enable (the plugin_directory must contain the binary)
sha=$(sha256sum /opt/vault-plugins/vault-plugin-secrets-gpg | cut -d' ' -f1)
vault plugin register -sha256=$sha secret vault-plugin-secrets-gpg
vault secrets enable -path=gpg vault-plugin-secrets-gpg

# generate a key
vault write gpg/keys/app algorithm=rsa-4096 identity="App <app@unkin.net>"
vault read  gpg/keys/app                       # metadata + armored public key

# sign / verify (input and output are base64 / armored)
sig=$(vault write -field=signature gpg/sign/app input=$(base64 <<<"ship it"))
vault write -field=valid gpg/verify/app input=$(base64 <<<"ship it") signature="$sig"

# encrypt / decrypt
ct=$(vault write -field=ciphertext gpg/encrypt/app plaintext=$(base64 <<<"secret"))
vault write -field=plaintext gpg/decrypt/app ciphertext="$ct" | base64 -d

# rotate; old ciphertext still decrypts
vault write gpg/keys/app/rotate

Using it with pass

The engine holds the private key; pass/gpg only need the public key to encrypt, and delegate decryption back to Vault.

# import the engine's public key into your gpg keyring
vault read -field=public_key gpg/keys/app | gpg --import
fpr=$(vault read -field=fingerprint gpg/keys/app)

# initialise a password store against it
pass init "$fpr"
pass insert email/example          # writes ~/.password-store/email/example.gpg (binary OpenPGP)

# decrypt an entry through Vault (decrypt accepts binary ciphertext directly)
vault write -field=plaintext gpg/decrypt/app \
  ciphertext=$(base64 -w0 ~/.password-store/email/example.gpg) | base64 -d

decrypt/<name> auto-detects ASCII-armored vs raw-binary input, so the binary .gpg files pass writes work without conversion. A thin gpg/pass wrapper that routes decryption to Vault automatically can be layered on top.

Build

make build      # -> dist/vault-plugin-secrets-gpg
make test lint  # go test -race / go vet
make e2e        # full lifecycle against Vault + OpenBao in Docker
make rpm        # vault + openbao RPM flavours

CI (Woodpecker) runs pre-commit/build/lint/test on PRs and builds+publishes the RPMs on a v* tag. The unit tests include real-gpg and real-pass interop checks (skipped automatically when those binaries are absent).