Quick-start guide to GPG
GnuPG supports both symmetric key encryption and public key encryption:
Symmetric key encryption: The same key is used for both encryption and decryption. Two parties communicating using a symmetric cipher must agree on the key beforehand. Once they agree, the sender encrypts a document using the key, sends it to the receiver, and the receiver decrypts it using the same key. The primary problem with symmetric key encryption is the key exchange. If there are n people who need to communicate, then n(n-1)/2 keys are needed for each pair of people to communicate privately.
Public key encryption: This involves creation of a public and private key pair. The private key should never be shared with anyone, while the public key is supposed to be shared with people who want to send you encrypted data. Documents are encrypted using the public key. Later the encrypted file is decrypted with the private key and a passphrase that was set during key generation. As opposed to symmetric key encryption, only n keypairs are needed for n people to communicate privately.
For a more thorough discussion see for instance The GNU Privacy Handbook.
In the following we will primarily discuss public key encryption. A brief introduction to symmetric key encryption is given in the last section.
GPG configuration files
The home directory where GnuPG and its helper tools look for configuration
files defaults to
~/.gnupg/ (see also
--homedir option). By default the
directory has its permissions set to
700, and the files it contains have their
permissions set to
600. It is very important to keep
~/.gnupg/ private and
have a secure backup stored on a seperate disk as it contains all files
generated by the
gpg command including the private keys.
For most users the following files are sufficient:
gpg.conf: standard configuration file read by
gpgon startup. It may contain any long options that are available for
gpg. A skeleton configuration file is generated on the very first run of
gpg-agent.conf: standard configuration file read by
gpg-agenton startup. The
gpg-agentis a daemon to request and cache passphrases used by
dirmngr.conf: standard configuration file read by
dirmngrtakes care of accessing the OpenPGP keyservers and is also used for managing and downloading certificate revocation lists. A skeleton configuration file is generated on the very first run of
Example configuration files are included in this repository.
Creating new keys
First create a new keypair (private and public key):
$ gpg --full-gen-key
The user will be prompted to answer several questions:
- Keypair: The default is
RSA and RSA. This means there will be one master key for signing and one subkey for encryption.
- Keysize: A keysize of 2048 is usually enough.
- Expiration date: A period of a year is enough most of the time. See Editing keys on how to change it afterwards.
- Name and email address.
- Comment: Add a comment for the key's purpose.
List all public keys:
$ gpg --list-keys $ gpg --list-sigs # list signatures $ gpg --fingerprint # list fingerprints
List private (secret) keys:
$ gpg --list-secret-keys
Delete a public key:
$ gpg --delete-key <key-id>
Delete a private key:
$ gpg --delete-secret-key <key-id>
<key-id> refers to a key by the name of its owner, email address,
the key's fingerprint, by its 8-digit hex ID or similar. For more details, see
man gpg, section "HOW TO SPECIFY A USER ID".
Backup a private key
It is recommended to make backups of private keys and save them on a separate and secured medium.
Backup a private key:
$ gpg --export-secret-keys --output private-key.asc --armor <key-id>
By default GnuPG writes to STDOUT if no file is specified with the
--output <file> option.
Import backup of a private key:
$ gpg --allow-secret-key-import --import private-key.asc
To open a menu for editing key related tasks, run:
$ gpg --edit-key <key-id>
help: display all commands
passwd: change passphrase
clean: compact any user ID that is no longer usable (revoked or expired)
revkey: revoke a key
addkey: add a subkey to this key
expire: change expiration date of key
adduid: add email addresses to this key
Example: renew an expired key
The expiration date of a key can be changed any time, even after it expired:
$ gpg --edit-key <key-id> # gpg> key 1 (only if you need to update a sub-key, by default primary key is selected) # gpg> expire # (follow prompts) # gpg> save
Example: add additional UID
Additional email addresses can be added to the key:
$ gpg --edit-key <key-id> # gpg> adduid # Real name: Red Dragon # Email address: firstname.lastname@example.org # ... insert passphrase to unlock secret key ... # gpg> save
If more UIDs were added to a key, we can set a primary UID:
$ gpg --edit-key <key-id> # gpg> uid 2 # gpg> primary # ... insert passphrase to unlock secret key ... # gpg> save
Export and import public keys
Export a public key to a 7-bit ASCII file:
$ gpg --armor --output some-public.key --export <key-id>
<key-id> has been entered, all present keys will be exported.
The public key can be freely distributed by sending it to friends, publishing on websites or registering it with public key servers.
In order to encrypt a documents for another user as well as to verify their signatures, we need their public key.
Import someone else's public key:
$ gpg --import some-public.key
Revoke a key
If for instance the private key bas been stolen, the UID has been changed or you forget the passphrase, it is immportant to notify others that the public key should no longer be used. After generating a new key it is recommended to immediately generate a revocation certificate:
$ gpg --output revoke.asc --gen-revoke <key-id>
Store the file
revoke.asc somewhere safe. It can be used to revoke the key
later when the private key is compromised.
To revoke your key, import the revocation certificate:
$ gpg --import revoke.asc
If a key server is used, update the key server as well:
$ gpg --keyserver subkeys.pgp.net --send <key-id>
--keyserver option is not required, when the keyserver is specified
Encrypting and decrypting
After a public key has been imported, we can encrypt a file or message to that recipient:
$ gpg [--output <outfile>] --recipient <key-id> --encrypt <some-file>
By default the encrypted file will be appended a
.gpg suffix. This can be
changed with the
--output <outfile> option.
To encrypt a file for personal use,
<key-id> is simply the name or email
address (or anything else) that was used during key generation.
When encrypting or decrypting a document, it is possible to have more than one
private key in use. In this case, we need to select the active key with the
--local-user <key-id>. Otherwise the default key is used.
Decrypt a file that has been encrypted with our own public key:
$ gpg --output somefile.txt --decrypt somefile.txt.gpg
gpg will prompt for the passphrase and then decrypt and write the data to the
file specified with the
--armor, -a: encrypt file using ASCII text
--hidden-recipient <user-id>, -R <user-id>: put recipient key IDs in the encrypted message to hide receivers of message against traffic analysis
--no-emit-version: avoid printing version number in ASCII armored output
Signing and checking signatures
To avoid the risk that someone else claims to be you, it's useful to sign every document that is encrypted. If the encrypted document is modified in any way, a verification of the signature will fail.
Sign a file with your own key:
$ gpg --sign <file> --output <file.sig>
Note that the file is compressed before being signed. The output will be in binary format and thus won't be human-readable. To make a clear text signature, run:
$ gpg --clearsign <file> --output <file.sig>
This causes the document to be wrapped in an ASCII-armored signature but otherwise does not modify the document. Hence, the content in a clear text signature is readable w/o any special software. OpenPGP software is only required to verify the signature.
A disadvantage of above methods is that users who received the signed documents must edit the files to recover the original (since signature is now part of document). It is also possible to make a detached signature to a file:
$ gpg --armor --output <file.sig> --detach-sign <file>
This is highly recommended when signing binary files (like tar archives).
Sign and encrypt a file:
$ gpg --sign <file> [--armor] --encrypt --recipient <user-id> [--local-user <key-id>]
--local-user <key-id> specifies the key to sign with, it overrides
--default-key <key-id> option, which is usually specified in
When an encrypted file has been signed, the signature is usually checked when
the file is decrypted using the
$ gpg --output <file> --decrypt <file.gpg>
To just check the signature use the
$ gpg --verify <pgp-file/sig-file>
This assumes the signer's public key has already been imported.
Assuming we downloaded a file
archive.tar.gz and a corresponding detached
archive.tar.gz.asc, we can verify the signature after downloading
the signer's public key as follows:
$ gpg --verify archive.tar.gz.asc archive.tar.gz
Send public key to key server, so that others can retrieve the key:
$ gpg --keyserver <keyserver-name> --send-keys <key-id>
Find details about a key on the key server w/o importing it:
$ gpg --search-keys <key-id> --keyserver <keyserver-name>
Import key from key server:
$ gpg --recv-keys <key-id>
The sks keyservers pool is often recommended. The communication with the key server is established using a protocol called hkps.
To fetch keys automatically from a key server as needed, add the following to
More details on how to setup a key server, see GPG Best
Practices. Note that since GnuPG 2.1 some options have been
dirmngr and must be added to
Symmetric key encryption
Documents can be encrypted with a symmetric cipher using a passphrase. The
default cipher used is AES-128 but can be changed with the
Encrypt a file using a symmetric key:
$ gpg --symmetric <file>
This will create an encrypted file with a .gpg appended to the old file name.
Decrypt the encrypted file:
$ gpg file.txt.gpg [--output file.txt]
The user will be prompted to enter the passphrase used to encrypt.