This page looks best with JavaScript enabled

How to work with GnuPG

 ·  ☕ 8 min read

GnuPG (gpg) is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).

Definition of User-ID and Key-ID

  • The user-id defines a name/e-mail address that is associated with the key certificate. The gpg program store it in RFC2822 format (John Doe <[email protected]>). The key certificate can have more than one user ID. If you want to use the key certificate with more than one email account, multiple user IDs would be needed.
  • The key-id defines a 160-bit fingerprint for a key, which is typically expressed as a hexadecimal string, divided into 10 4-character groups. When validating keys for key signing, the fingerprint is used.
    There’s also a short key-id and long key-id. Short Key-ID is the last 8 characters of the fingerprint. In some contexts this value needs to have 0x prepended (0x123456AB). Long Key-ID is the last 16 characters of the fingerprint.
    Warning: using a short key-id may encounter collisions. To avoid this, use the full fingerprint or long key ID, when receiving a key.

Generate a keypair

  • Generate a keypair with default parameters:

    gpg --gen-key

    You’ll be prompted for your name, e-mail and password. It’s strongly recommended using a strong password.

  • Generate a keypair with custom parameters:

    gpg --full-gen-key

    In this case, you’ll be asked to:

    • Choose key type. In most cases you need “the RSA (sign only) and a RSA (encrypt only) key”.
    • Choose keysize. The default length (3072 Bit) is more than enough.
    • Your name and e-mail address. More addresses can be added later.
    • Comment. Use it only if you need it.
    • Password. It’s strongly recommended using a strong password.

Generate a revocation certificate

  • Generate a revocation certificate for a key with your <user-or-key-id>:
    gpg --gen-revoke --armor --output=revocation_certificate.asc <user-or-key-id>
    This certificate can be used later to revoke your key in case if it has been lost or compromised.

Import a public key

  • Import a public key from file:
    gpg --import public.key

Export your public key

To export your public key, you should use user-id or key-id.

  • Export your public key as text to stdout:

    gpg --armor --export <user-or-key-id>
  • Export your public key as text (ASCII) to file:

    gpg --output=mypublic.key --armor --export <user-or-key-id>
  • Export your public key in binary file:

    gpg --output=mypublic.key --export <user-or-key-id>

List keys

  • To list keys in your public key ring:

    gpg --list-keys
  • To list keys in your secret key ring:

    gpg --list-secret-keys

Use a keyserver

To import or export public key from/to key server, you should know its <key-id>, which can be a full fingerprint or long key ID.

  • Search a key, without importing it:

    gpg --search-keys <user-or-key-id>
  • Import a key from a key server:

    gpg --recv-keys <key-id>
  • Upload your public key to key server, so that others can retrieve your key without having to contact you directly:

    gpg --send-keys <key-id>
  • Upload your public key to specific keyserver:

    gpg --keyserver <keyserver-url> --send-keys <key-id>
  • Refresh keys:

    gpg --refresh-keys

Asymmetric encryption

Before using this type of encryption, you need to import a public key from recipient.

  • To encrypt file use options --encrypt or -e and --recipient or -r to specify recipient:

    gpg --recipient <user-or-key-id> --encrypt file.txt

    Use -o or --output to specify name and path to encrypted file (optionally).

  • To decrypt encrypted file, use -d or --decrypt options

    gpg --output file.txt --decrypt file.gpg

Symmetric encryption

Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase.

  • Simply use --symmetric or -c to encrypt a file:

    gpg -c file.txt

    Use -o or --output to specify name and path to encrypted file (optionally).

  • To decrypt a symmetrically encrypted file.gpg using a passphrase use -d or --decrypt options:

    gpg --output file.txt --decrypt file.gpg


Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user’s private key. The recipient of a signed document then verifies the signature using the sender’s public key.

  • To sign a file use the --sign or -s flag:

    gpg --output file.txt.sig --sign file.txt

    file.txt.sig contains both the compressed content of the original file and the signature in a binary format, but the file is not encrypted.

  • Sign a file using clearsign mode:

    gpg --output file.txt.sig --clearsign file.txt

    If you use --clearsign both the content of the file doc the signature are stored in human-readable form.

  • Make a detached signature:

    gpg --output file.txt.sig --detach-sig file.txt

    The signature will be stored separately from file.txt. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.

  • To verify a signed file containing the signature use the --verify flag:

    gpg --verify file.txt.sig
  • To verify a detached signature, both the signed data file and the signature file must be located in the same directory:

    gpg --verify file.txt.sig
  • While verifying a detached signature, path to signed data file can be specified:

    gpg --verify file.txt.sig /path/to/file.txt

Sign and encrypt

You can combine signing and encryption using --sign --encrypt or just -se flags. In this case, signature verification will be processed automatically on decryption.

  • Sign and encrypt file:
    gpg -se -r <user-or-key-id> file.txt

Backup your private key

  • Export private key:

    gpg --export-secret-keys --armor <user-id> > myprivatkey.asc
  • Import private key:

    gpg --import myprivatkey.asc

Edit your key

  • To edit your key simply run:
    gpg --edit-key <user-id>
    Here’s some commands:
    • passwd - change the passphrase.
    • clean - compact any user ID that is no longer usable (e.g revoked or expired).
    • revkey - revoke a key.
    • addkey - add a subkey to this key.
    • expire - change the key expiration time.
    • adduid - add additional names, comments, and email addresses.
    • addphoto - add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted).

Revoke a key

If you lose your secret key or it is compromised, you’ll need to revoke your key. To revoke your key:

  1. Import your public key if you not longer have access to the keypair.
  2. Import your revocation certificate:
    gpg --import revocation_certificate.asc
  3. Make your now-revoked key public. If you used a keyserver, send the key to the keyserver. Otherwise, distribute the revoked key to your colleagues.

Export subkey

If you’re going to use the same key across multiple devices, you should strip out your master key and only keep the bare minimum encryption subkey on less secure systems.

  • Find out which subkey you want to export:

    gpg --list-secret-keys --with-subkey-fingerprint
  • Export subkey:

    gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg

    Note: If you forget to add the !, all of your subkeys will be exported.

At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder.

  • Import subkey:
    gpg --homedir /tmp/gpg --import /tmp/subkey.gpg
  • Edit subkey:
    gpg --homedir /tmp/gpg --edit-key <user-id>
    > passwd
    > save
  • Export subkey with new password:
    gpg --homedir /tmp/gpg -a --export-secret-subkeys <subkey id>! > /tmp/subkey.altpasswd.gpg
    Note: You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.

At this point, you can now use /tmp/subkey.altpass.gpg on your other devices.

Delete a key

  • Delete a public key:

    gpg --delete-keys <key-id>
  • Delete a private key:

    gpg --delete-secret-keys <key-id>
  • Delete both, a private and a public key:

    gpg --delete-secret-and-public-key <key-id>

Additional options

  • Use -a or --armor to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format).
  • Use -R <user-or-key-id>or --hidden-recipient <user-or-key-id> instead of -r to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.
  • Use GnuPG to encrypt your sensitive documents by using your own <user-or-key-id> as recipient or by using the --default-recipient-self flag instead.
What's on this Page