---
aliases: ["PGP", "GnuPG", "OpenPGP"]
website: https://www.gnupg.org
obj: application
rev: 2024-09-17
---

# GPG
gpg is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a tool to provide digital encryption and signing services using the OpenPGP standard. gpg features complete key management and all the bells and whistles you would expect from a full OpenPGP implementation.

## Commands

**Sign:**
- `--sign`, `-s`: Sign a message. This command may be combined with `--encrypt` (to sign and encrypt a message), `--symmetric` (to sign and symmetrically encrypt a message), or both `--encrypt` and `--symmetric` (to sign and encrypt a message that can be decrypted using a secret key or a passphrase). The signing key is chosen by default or can be set explicitly using the `--local-user` and `--default-key` options.
- `--clear-sign`, `--clearsign`: Make a cleartext signature. The content in a cleartext signature is readable without any special software. OpenPGP software is only needed to verify the signature. cleartext signatures may modify end-of-line whitespace for platform independence and are not intended to be reversible. The signing key is chosen by default or can be set explicitly using the `--local-user` and `--default-key` options.
- `--detach-sign`, `-b`: Make a detached signature.

**Encrypt:**
- `--encrypt`, `-e`: Encrypt data to one or more public keys. This command may be combined with `--sign` (to sign and encrypt a message), `--symmetric` (to encrypt a message that can be decrypted using a secret key or a passphrase), or `--sign` and `--symmetric` together (for a signed message that can be decrypted using a secret key or a passphrase). `--recipient` and related options specify which public keys to use for encryption.
- `--store`: Store only (make a simple literal data packet).

**Symmetric Encryption:**
- `--symmetric`, `-c`: Encrypt with a symmetric cipher using a passphrase. The default symmetric cipher used is AES-128, but may be chosen with the `--cipher-algo` option. This command may be combined with `--sign` (for a signed and symmetrically encrypted message), `--encrypt` (for a message that may be decrypted via a secret key or a passphrase), or `--sign` and `--encrypt` together (for a signed message that may be decrypted via a secret key or a passphrase). gpg caches the passphrase used for symmetric encryption so that a decrypt operation may not require that the user needs to enter the passphrase. The option `--no-symkey-cache` can be used to disable this feature.

**Decrypt:**
- `--decrypt`, `-d`: Decrypt the file given on the command line (or `STDIN` if no file is specified) and write it to `STDOUT` (or the file specified with `--output`). If the decrypted file is signed, the signature is also verified. This command differs from the default operation, as it never writes to the filename which is included in the file and it rejects files that don't begin with an encrypted message.

**Verify:**
- `--verify`: Assume that the first argument is a signed file and verify it without generating any output. With no arguments, the signature packet is read from `STDIN`. If only one argument is given, the specified file is expected to include a complete signature. With more than one argument, the first argument should specify a file with a detached signature and the remaining files should contain the signed data. To read the signed data from `STDIN`, use `-` as the second filename. For security reasons, a detached signature will not read the signed material from `STDIN` if not explicitly specified. Note: If the option `--batch` is not used, gpg may assume that a single argument is a file with a detached signature, and it will try to find a matching data file by stripping certain suffixes. Using this historical feature to verify a detached signature is strongly discouraged; you should always specify the data file explicitly. Note: When verifying a cleartext signature, gpg verifies only what makes up the cleartext signed data and not any extra data outside of the cleartext signature or the header lines directly following the dash marker line. The option `--output` may be used to write out the actual signed data, but there are other pitfalls with this format as well. It is suggested to avoid cleartext signatures in favor of detached signatures. Note: With option `--batch` he verification of signatures stops at the first bad signature. This is a safe default for unattended processing but sometimes a status for all signatures is needed. To override this early bailout use the option `--proc-all-sigs`. Note: To check whether a file was signed by a certain key the option `--assert-signer` can be used. As an alternative the gpgv tool can be used. gpgv is designed to compare signed data against a list of trusted keys and returns with success only for a good signature.

**Multiple files:**
- `--multifile`: This modifies certain other commands to accept multiple files for processing on the command line or read from `STDIN` with each filename on a separate line. This allows for many files to be processed at once. `--multifile` may currently be used along with `--verify`, `--encrypt`, and `--decrypt`. Note that `--multifile --verify` may not be used with detached signatures.
- `--verify-files` Identical to `--multifile --verify`.
- `--encrypt-files` Identical to `--multifile --encrypt`.
- `--decrypt-files` Identical to `--multifile --decrypt`.

## Keys

**List keys:**
- `--list-keys`, `-k`, `--list-public-keys`: List the specified keys. If no keys are specified, then all keys from the configured public keyrings are listed. Never use the output of this command in scripts or other programs. The output is intended only for humans and its format is likely to change. The `--with-colons` option emits the output in a stable, machine-parseable format, which is intended for use by scripts and other programs.
- `--list-secret-keys`, `-K`: List the specified secret keys. If no keys are specified, then all known secret keys are listed. A `#` after the initial tags sec or ssb means that the secret key or subkey is currently not usable. We also say that this key has been taken offline (for example, a primary key can be taken offline by exporting the key using the command `--export-secret-subkeys`). A `>` after these tags indicate that the key is stored on a smartcard.
- `--check-signatures`, `--check-sigs`:  Same as `--list-keys`, but the key signatures are verified and listed too. Note that for performance reasons the revocation status of a signing key is not shown. This command has the same effect as using `--list-keys` with `--with-sig-check`. The status of the verification is indicated by a flag directly following the "sig" tag (and thus before the flags described below. A `!` indicates that the signature has been successfully verified, a `-` denotes a bad signature and a `%` is used if an error occurred while checking the signature (e.g., a non supported algorithm). Signatures where the public key is not available are not listed; to see their keyids the command `--list-sigs` can be used. For each signature listed, there are several flags in between the signature status flag and keyid. These flags give additional information about each key signature. From left to right, they are the numbers 1--3 for certificate check level, `L` for a local or non-exportable signature, `R` for a nonRevocable signature, `P` for a signature that contains a policy URL, `N` for a signature that contains a notation, `X` for an eXpired signature, and the numbers 1--9 or `T` for 10 and above to indicate trust signature levels.
- `--locate-keys`, `--locate-external-keys`: Locate the keys given as arguments. This command basically uses the same algorithm as used when locating keys for encryption and may thus be used to see what keys gpg might use. In particular external methods as defined by `--auto-key-locate` are used to locate a key if the arguments comain valid mail addresses. Only public keys are listed. The variant `--locate-external-keys` does not consider a locally existing key and can thus be used to force the refresh of a key via the defined external methods. If a fingerprint is given and and the methods defined by `--auto-key-locate` define LDAP servers, the key is fetched from these resources; defined non-LDAP keyservers are skipped.
- `--show-keys`: This commands takes OpenPGP keys as input and prints information about them in the same way the command `--list-keys` does for locally stored key. In addition the list options show-unusable-uids, show-unusable-subkeys, show-notations and show-policy-urls are also enabled. As usual for automated processing, this command should be combined with the option `--with-colons`.
- `--fingerprint`: List all keys (or the specified ones) along with their fingerprints. This is the same output as `--list-keys` but with the additional output of a line with the fingerprint. May also be combined with `--check-signatures`. If this command is given twice, the fingerprints of all secondary keys are listed too. This command also forces pretty printing of fingerprints if the keyid format has been set to "none".

**Manage keys:**
- `--delete-keys name`:  Remove key from the public keyring. In batch mode either `--yes` is required or the key must be specified by fingerprint. This is a safeguard against accidental deletion of multiple keys. If the exclamation mark syntax is used with the fingerprint of a subkey only that subkey is deleted; if the exclamation mark is used with the fingerprint of the primary key the entire public key is deleted.
- `--delete-secret-keys name`: Remove key from the secret keyring. In batch mode the key must be specified by fingerprint. The option ``--yes` can be used to advise gpg-agent not to request a confirmation. This extra pre-caution is done because gpg can't be sure that the secret key (as controlled by gpg-agent) is only used for the given OpenPGP public key. If the exclamation mark syntax is used with the fingerprint of a subkey only the secret part of that subkey is deleted; if the exclamation mark is used with the fingerprint of the primary key only the secret part of the primary key is deleted.
- `--delete-secret-and-public-key name`: Same as `--delete-key`, but if a secret key exists, it will be removed first. In batch mode the key must be specified by fingerprint. The option `--yes` can be used to advise gpg-agent not to request a confirmation.
- `--send-keys keyIDs`: Similar to `--export` but sends the keys to a keyserver. Fingerprints may be used instead of key IDs. Don't send your complete keyring to a keyserver --- select only those keys which are new or changed by you. If no keyIDs are given, gpg does nothing. Take care: Keyservers are by design write only systems and thus it is not possible to ever delete keys once they have been send to a keyserver.
- `--receive-keys keyIDs`, `--recv-keys keyIDs`: Import the keys with the given keyIDs from a keyserver.
- `--refresh-keys`: Request updates from a keyserver for keys that already exist on the local keyring. This is useful for updating a key with the latest signatures, user IDs, etc. Calling this with no arguments will refresh the entire keyring.
- `--search-keys names`: Search the keyserver for the given names. Multiple names given here will be joined together to create the search string for the keyserver. Note that keyservers search for names in a different and simpler way than gpg does. The best choice is to use a mail address. Due to data privacy reasons keyservers may even not even allow searching by user id or mail address and thus may only return results when being used with the `--recv-key` command to search by key fingerprint or keyid.
- `--fetch-keys URIs`: Retrieve keys located at the specified URIs. Note that different installations of GnuPG may support different protocols (HTTP, FTP, LDAP, etc.). When using HTTPS the system provided root certificates are used by this command.
- `--update-trustdb`: Do trust database maintenance. This command iterates over all keys and builds the Web of Trust. This is an interactive command because it may have to ask for the "ownertrust" values for keys. The user has to give an estimation of how far she trusts the owner of the displayed key to correctly certify (sign) other keys. GnuPG only asks for the ownertrust value if it has not yet been assigned to a key. Using the --edit-key menu, the assigned value can be changed at any time.
- `--check-trustdb`: Do trust database maintenance without user interaction. From time to time the trust database must be updated so that expired keys or signatures and the resulting changes in the Web of Trust can be tracked. Normally, GnuPG will calculate when this is required and do it automatically unless `--no-auto-check-trustd` is set. This command can be used to force a trust database check at any time. The processing is identical to that of `--update-trustdb` but it skips keys with a not yet defined "ownertrust". For use with cron jobs, this command can be used together with --batch in which case the trust database check is done only if a check is needed. To force a run even in batch mode add the option `--yes`.
- `--export-ownertrust`: Send the ownertrust values to `STDOUT`. This is useful for backup purposes as these values are the only ones which can't be re-created from a corrupted trustdb.
- `--import-ownertrust`: Update the trustdb with the ownertrust values stored in files (or `STDIN` if not given); existing values will be overwritten.
- `--sign-key name`: Signs a public key with your secret key. This is a shortcut version of the subcommand `sign` from `--edit-key`.
- `--change-passphrase user-id`, `--passwd user-id`: Change the passphrase of the secret key belonging to the certificate specified as user-id. This is a shortcut for the sub-command `passwd` of the `--edit-key` menu. When using together with the option `--dry-run` this will not actually change the passphrase but check that the current passphrase is correct.

**Generate key:**
- `--generate-key`, `--gen-key`: Generate a new key pair using the current default parameters. This is the standard command to create a new key. In addition to the key a revocation certificate is created and stored in the openpgp-revocs.d directory below the GnuPG home directory.
- `--full-generate-key`, `--full-gen-key`: Generate a new key pair with dialogs for all options. This is an extended version of `--generate-key`. 

**Import & export keys:**
- `--import`, `--fast-import`: Import/merge keys. This adds the given keys to the keyring. The fast version is currently just a synonym. There are a few other options which control how this command works. Most notable here is the --import-options merge-only option which does not insert new keys but does only the merging of new signatures, user-IDs and subkeys.
- `--export`: Either export all keys from all keyrings (default keyring and those registered via option `--keyring`), or if at least one name is given, those of the given name. The exported keys are written to `STDOUT` or to the file given with option `--output`. Use together with `--armor` to mail those keys.
- `--export-secret-keys`, `--export-secret-subkeys`: Same as `--export`, but exports the secret keys instead. The exported keys are written to `STDOUT` or to the file given with option `--output`. This command is often used along with the option `--armor` to allow for easy printing of the key for paper backup; however the external tool paperkey does a better job of creating backups on paper. Note that exporting a secret key can be a security risk if the exported keys are sent over an insecure channel. The second form of the command has the special property to render the secret part of the primary key useless; this is a GNU extension to OpenPGP and other implementations can not be expected to successfully import such a key. Its intended use is in generating a full key with an additional signing subkey on a dedicated machine. This command then exports the key without the primary key to the main machine. GnuPG may ask you to enter the passphrase for the key. This is required, because the internal protection method of the secret key is different from the one specified by the OpenPGP protocol.
- `--export-ssh-key`: This command is used to export a key in the OpenSSH public key format. It requires the specification of one key by the usual means and exports the latest valid subkey which has an authentication capability to STDOUT or to the file given with option --output. That output can directly be added to ssh's authorized_key file. By specifying the key to export using a key ID or a fingerprint suffixed with an exclamation mark (!), a specific subkey or the primary key can be exported. This does not even require that the key has the authentication capability flag set.

**Key selection:**
```shell
 -r, --recipient KEY # Encrypt for key
 -u, --local-user KEY # Use this key
```

## Options
gpg features a bunch of options to control the exact behaviour and to change the default configuration.

Long options can be put in an options file (default `~/.gnupg/gpg.conf`). Short option names will not work --- for example, `armor` is a valid option for the options file, while `a` is not. Do not write the 2 dashes, but simply the name of the option and any required arguments. Lines with a hash (`#`) as the first non-white-space character are ignored. Commands may be put in this file too, but that is not generally useful as the command will execute automatically with every execution of gpg.

Please remember that option parsing stops as soon as a non-option is encountered, you can explicitly stop parsing by using the special option `--`.

| Option                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------ |   |
| f                                    | `--default-key name`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Use `name` as the default key to sign with. It is suggested to use a fingerprint or at least a long keyID for name. If this option is not used, the default key is the first key found in the secret keyring. Note that `-u` or `--local-user` overrides this option. This option may be given multiple times. In this case, the last key for which a secret key is available is used. If there is no secret key available for any of the specified values, GnuPG will not emit an error message but continue as if this option wasn't given. |
| `--default-recipient name`           | Use `name` as default recipient if option `--recipient` is not used and don't ask if this is a valid one. name must be non-empty and it is suggested to use a fingerprint for name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--default-recipient-self`           | Use the default key as default recipient if option `--recipient` is not used and don't ask if this is a valid one. The default key is the first one from the secret keyring or the one set with `--default-key`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--batch`, `--no-batch`              | Use batch mode. Never ask, do not allow interactive commands. `--no-batch` disables this option. Note that even with a filename given on the command line, gpg might still need to read from ` STDIN` (in particular if gpg figures that the input is a detached signature and no data file has been specified). Thus if you do not want to feed data via `STDIN`, you should connect `STDIN` to `/dev/null`. It is highly recommended to use this option along with the options `--status-fd` and `--with-colons` for any unattended use of gpg. Should not be used in an option file.                                                                                                      |
| `--no-tty`                           | Make sure that the TTY (terminal) is never used for any output. This option is needed in some cases because GnuPG sometimes prints warnings to the TTY even if `--batch` is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--yes`                              | Assume "yes" on most questions. Should not be used in an option file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--no`                               | Assume "no" on most questions. Should not be used in an option file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--proc-all-sigs`                    | This option overrides the behaviour of the `--batch` option to stop signature verification at the first bad signatures.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--keyring file`                     | Add file to the current list of keyrings. If file begins with a tilde and a slash, these are replaced by the `$HOME` directory. If the filename does not contain a slash, it is assumed to be in the GnuPG home directory (`~/.gnupg` unless `--homedir` or `$GNUPGHOME` is used). Note that this adds a keyring to the current list. If the intent is to use the specified keyring alone, use `--keyring` along with `--no-default-keyring`. If the option `--no-keyring` has been used no keyrings will be used at all. Note that if the option use-keyboxd is enabled in common.conf, no keyrings are used at all and keys are all maintained by the keyboxd process in its own database. |
| `--primary-keyring file`             | This is a variant of `--keyring` and designates file as the primary public keyring. This means that newly imported keys (via `--import` or keyserver `--recv-from`) will go to this keyring.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--homedir dir`                      | Set the name of the home directory to dir. If this option is not used, the home directory defaults to `~/.gnupg`. It is only recognized when given on the command line. It also overrides any home directory stated through the environment variable `$GNUPGHOME` or (on Windows systems) by means of the Registry entry HKCU\Software\GNU\GnuPG:HomeDir. On Windows systems it is possible to install GnuPG as a portable application. In this case only this command line option is considered, all other ways to set a home directory are ignored.                                                                                                                                        |
| `--recipient name`, `-r`             | Encrypt for user id name. If this option or `--hidden-recipient` is not specified, GnuPG asks for the user-id unless `--default-recipient` is given.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--hidden-recipient name`, `-R`      | Encrypt for user ID name, but hide the key ID of this user's key. This option helps to hide the receiver of the message and is a limited countermeasure against traffic analysis. If this option or `--recipient` is not specified, GnuPG asks for the user ID unless `--default-recipient` is given.                                                                                                                                                                                                                                                                                                                                                                                        |
| `--recipient-file file`, `-f`        | This option is similar to `--recipient` except that it encrypts to a key stored in the given file. file must be the name of a file containing exactly one key. gpg assumes that the key in this file is fully valid.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--hidden-recipient-file file`, `-F` | This option is similar to `--hidden-recipient` except that it encrypts to a key stored in the given file. file must be the name of a file containing exactly one key. gpg assumes that the key in this file is fully valid.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--local-user name`, `-u`            | Use name as the key to sign with. Note that this option overrides `--default-key`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--armor`, `-a`                      | Create ASCII armored output. The default is to create the binary OpenPGP format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--no-armor`                         | Assume the input data is not in ASCII armored format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--output file`, `-o file`           | Write output to file. To write to stdout use `-` as the filename.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--with-colons`                      | Print key listings delimited by colons. Note that the output will be encoded in UTF-8 regardless of any `--display-charset` setting. This format is useful when GnuPG is called from scripts and other programs as it is easily machine parsed. The details of this format are documented in the file `doc/DETAILS`, which is included in the GnuPG source distribution.                                                                                                                                                                                                                                                                                                                     |
