gpg-decrypt

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.