How to work with GnuPG

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).
Read more at 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 <[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

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.
- 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 <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

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

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 <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:

Import your public key if you not longer have access to the keypair.

Import your revocation certificate:

gpg --import revocation_certificate.asc

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

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 <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.