| name | gpg-decrypt |
| description | Decrypt a GPG-encrypted file (.gpg or .asc) using the local keyring. Handles both asymmetric (key-encrypted) and symmetric (passphrase-encrypted) ciphertext — GPG auto-detects which. Use when the user receives an encrypted file or has at-rest encrypted backups they need to read. |
Decrypt with GPG
When to use
The user has a .gpg, .asc, or .pgp file (or armored text) they want to decrypt.
Identify the ciphertext type
gpg --list-packets <file>
Look at the first packet:
pubkey enc packet → asymmetric (encrypted to a public key). You need the matching secret key on the ring.symkey enc packet → symmetric (passphrase-encrypted). You need the passphrase.
If --list-packets shows the encryption was to a key ID you don't have on the keyring (gpg --list-secret-keys doesn't list it), you can't decrypt — surface that explicitly.
Decrypt to a file
gpg --output <plaintext-file> --decrypt <file>.asc
GPG prompts for the passphrase (either your secret-key passphrase for asymmetric, or the symmetric passphrase). The output filename is preserved from the encrypted file's metadata if you omit --output:
gpg --decrypt-files <file>.asc
Decrypt to stdout (for piping)
gpg --decrypt <file>.asc
Useful for streaming (e.g. piping to tar xzf - for an encrypted tarball).
Verify signatures along the way
If the ciphertext was signed-and-encrypted, decryption automatically verifies the signature. Watch for gpg: Good signature from "..." in stderr. A WARNING or BAD signature line means the file is tampered or the signer's key isn't trusted — don't ignore it.
Common errors
- "decryption failed: No secret key" — the file was encrypted to a public key you don't hold the secret half for. Either you're not the intended recipient, or the relevant key is on a different machine / hardware token.
- "public key decryption failed: Bad passphrase" — wrong secret-key passphrase. Reset the agent cache:
gpgconf --reload gpg-agent.
- "WARNING: message was not integrity protected" — old MDC-less ciphertext. Treat output with suspicion; the message may be tampered. Ask the sender to re-send with modern GPG.
Notes
- Don't pass passphrases on the command line. Let
pinentry handle them (graphical or curses, depending on your gpg-agent config).
- Decrypted output is plaintext — write it to a sensible location (the user's choice), not into the plugin install dir.
