How to work with GnuPG This note was created on 2020-04-12 This note was last edited on 2024-04-02 GnuPG ("gpg") is a complete and free implementation of the OpenPGP (https://www.openpgp.org/about) standard as defined by RFC4880 (https://tools.ietf.org/html/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"). Read more at project's website: https://www.gnupg.org === 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 "). 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 === Note: The name and email address you enter will be seen by anybody who imports your key. - 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. - Choose for how long the key should be valid. - 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 keypair with ed25519 === $ gpg --expert --full-gen-key In this case, you'll be asked to: - Choose key type. You want "(9) ECC and ECC". - Choose elliptic curve. Choose "(1) Curve 25519". - Choose for how long the key should be valid. - 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 === Note: This step is optional. Revocation certificates are automatically generated for newly created keys in "~/.gnupg/openpgp-revocs.d/". - Generate a revocation certificate for a key with your "": $ gpg --gen-revoke --armor --output=revocation_certificate.asc 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 - Export your public key as text (ASCII) to file: $ gpg --output=mypublic.key --armor --export - Export your public key in binary file: $ gpg --output=mypublic.key --export === 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 "", which can be a full fingerprint or long key ID. - Search a key, without importing it: $ gpg --search-keys - Import a key from a key server: $ gpg --recv-keys - Upload your public key to key server, so that others can retrieve your key without having to contact you directly: $ gpg --send-keys - Upload your public key to specific keyserver: $ gpg --keyserver --send-keys - 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 --encrypt file.txt Use "-o" or "--output" to specify name and path to encrypted file (optionally). - To encrypt file for multiple recipients, you need just to specify them all: $ gpg -r -r --encrypt file.txt - 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 === 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 --clearsign file.txt If you use "--clearsign" both the content of the file.txt and 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 file.txt === Backing up private key === Warning: The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse. - Export private key: $ gpg --export-secret-keys --armor > myprivatkey.asc - Import private key: $ gpg --import myprivatkey.asc === Edit the key === - To edit your key simply run: $ gpg --edit-key If you have several UIDs, which are listed when you start editing a key, you can select one using "uid" command: > uid 3 Here's some commands to edit your key: - "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). - "help" - list all commands. - To set trust level for public key: $ gpg --edit-key > trust > 5 Instead of "5" you can set any level of trust. Here's a list of them: 1 = I don't know or won't say 2 = I do NOT trust 3 = I trust marginally 4 = I trust fully 5 = I trust ultimately m = back to the main menu === GPG configuration === GPG can be configured by editing "~/.gnupg/gpg.conf" configuration file. - Set default key: ~~~ default-key 0xYOURKEYID ~~~ - Always show full key IDs: ~~~ keyid-format 0xlong ~~~ - Disable inclusion of the version string in ASCII armored output: ~~~ no-emit-version ~~~ - Disable comment string in clear text signatures and ASCII armored messages: ~~~ no-comments ~~~ - Try to use the GnuPG-Agent: ~~~ use-agent ~~~ With this option, GnuPG first tries to connect to the agent before it asks for a passphrase. === 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 $ passwd $ save - Export subkey with new password: $ gpg --homedir /tmp/gpg -a --export-secret-subkeys ! > /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 === Warning: Never delete your expired or revoked keys or subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please only delete expired or revoked keys from other users to clean your keyring. - Delete a public key: $ gpg --delete-keys - Delete a private key: $ gpg --delete-secret-keys - Delete both, a private and a public key: $ gpg --delete-secret-and-public-key === 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 "or "--hidden-recipient " 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 "" as recipient or by using the "--default-recipient-self" flag instead.