GPG keys

Keyguard stores OpenPGP keys in a dedicated GPG key item type and can use them to sign, verify, encrypt, and decrypt. This page is a technical reference for what Keyguard parses, stores, and supports. For daily setup see the GPG agent setup guide.

OpenPGP (the standard behind GnuPG/PGP, defined by RFC 4880 and the newer RFC 9580) describes a certificate — colloquially “a public key” — as a primary key plus zero or more subkeys, one or more user IDs, and metadata bound together by self-signatures.

A GPG key item itself stores three things:

• the armored public key;
• the armored private key, if you provided one;
• the fingerprint of the primary key.

Private keys are stored unencrypted — when you import a passphrase-protected private key, Keyguard asks for the passphrase once, then re-encodes the key without it. The vault’s own encryption is what protects it from then on.

For compatibility with Bitwarden’s fixed data model — see Item types & extras for the exact convention.

Identifiers

Keyguard derives and displays three identifiers per key, all matching what GnuPG shows:

Capabilities

Each key and subkey is inspected for its OpenPGP key flags and shown as one or both of:

• Sign — the key can create signatures;
• Encrypt — the key can be an encryption recipient.

Capabilities are aggregated across the primary key and every subkey, so an item reports what the certificate as a whole can do.

Subkeys, user IDs, and validity

For the primary key and every subkey, Keyguard extracts the fingerprint, keygrip, key ID, algorithm, bit strength, sign/encrypt capabilities, revocation state, and expiration date.

User IDs are parsed in the standard Name (comment) <email> form; the email addresses are pulled out for display, with a fallback for bare-email user IDs. Creation and expiration dates are read from the key’s self-signature, and revoked keys and subkeys are marked as such.

Algorithms

Keyguard recognises the following public-key algorithms when parsing a key (by their OpenPGP algorithm IDs, so they survive across library versions):

Any other algorithm is shown generically. Algorithm support varies by operation; see GPG agent below for operational limits.

Generating a key

The generator creates a new GPG key in one of two profiles — modern Ed25519 + X25519, or RSA — see the generator’s GPG keys section for what each profile produces and the current limitations.

Importing a key

The add-item flow accepts existing keys in either ASCII-armored or binary form, and both public and private key material:

• A public key is parsed and stored as a certificate.
• A private key is parsed; if it is passphrase-protected, Keyguard prompts for the passphrase, then stores it unencrypted (see the note above). A wrong passphrase is reported as such.

When importing into an item that already contains the same certificate, Keyguard combines its certificate data. Existing secret material, certifications, and revocations are retained. A different certificate or malformed material is rejected without changing the item.

Empty input and unsupported formats are reported distinctly.

Exporting and copying

From a GPG key item you can:

• export the public key (.public.asc), the private key (.private.asc), or both together in a .zip;
• copy the public key, the fingerprint, or the unencrypted private key.

The GPG tools

Keyguard includes standalone OpenPGP tools that operate on text or files using the keys in your vault:

Signatures use SHA-256 over canonical text. Verification reports whether a signature is valid, invalid, or missing the public key, and adds warnings when the signing key is revoked or expired, or when the signature itself has expired.

Using GPG keys from other tools

On desktop Linux, macOS, and Windows, Keyguard can act as a compatible gpg-agent so that a local gpg (for example, when signing Git commits) uses keys from your vault. On Android, compatible apps can use Keyguard as an OpenKeychain-compatible OpenPGP provider for signing, verification, encryption, decryption, and public-key access. In both cases the private key stays inside Keyguard. See the GPG agent setup guide for both connection paths.

Keyservers

Keyguard can look up and publish public keys on a keyserver. Two protocols are supported:

keys.openpgp.org is a verifying keyserver: it serves key material by fingerprint and distributes email identities only after owner confirmation. Keyguard automatically queries VKS by fingerprint or email, and falls back to HKP for free-text queries. Email lookups against VKS are rate-limited.

You can:

• search a keyserver and import a result;
• upload a public key to publish it; on a VKS keyserver you can pick the e-mail addresses that receive a verification e-mail, which makes the key searchable by those addresses once confirmed;
• verify a stored public key against the keyserver, recording whether it is found & verified, found but unverified, not found, or revoked.

A background worker can auto-refresh the published state of your keys on a schedule you set.

Related

• GPG agent setup — use vault keys from desktop gpg or compatible Android apps.
• Generator — create new GPG keys.
• Watchtower — audit keys for weaknesses.
• Item types & extras — other item conventions.