Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bfrg/gpg-guide

Quick-start guide to GPG
https://github.com/bfrg/gpg-guide

Last synced: about 1 month ago
JSON representation

Quick-start guide to GPG

Awesome Lists containing this project

README 

        
# Quick-start guide to GPG



**GnuPG** supports both symmetric key encryption and public key encryption:



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



2. **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][gnu-handbook].



In the following we will primarily discuss **public key encryption**. A brief

introduction to symmetric key encryption is given in the last

[section](#symmetric-key-encryption).



## 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 `gpg` on 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`.

* `gpg-agent.conf`: standard configuration file read by `gpg-agent` on startup.

  The `gpg-agent` is a daemon to request and cache passphrases used by `gpg`.

* `dirmngr.conf`: standard configuration file read by `dirmngr` on startup.

  `dirmngr` takes 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 `gpg`.



Example configuration files are included in this repository.



## Creating new keys



First create a new keypair (private and public key):

```bash

$ gpg --full-gen-key

```



The user will be prompted to answer several questions:

1. Keypair: The default is `RSA and RSA`. This means there will be one master

   key for signing and one subkey for encryption.

2. Keysize: A keysize of 2048 is usually enough.

3. Expiration date: A period of a year is enough most of the time. See

   [Editing keys](#editing-keys) on how to change it afterwards.

4. Name and email address.

5. Comment: Add a comment for the key's purpose.

6. Passphrase.



## Key administration



List all public keys:

```bash

$ gpg --list-keys

$ gpg --list-sigs   # list signatures

$ gpg --fingerprint # list fingerprints

```



List private (secret) keys:

```bash

$ gpg --list-secret-keys

```



Delete a public key:

```bash

$ gpg --delete-key 

```



Delete a private key:

```bash

$ gpg --delete-secret-key 

```



**Note:** `` 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:

```bash

$ gpg --export-secret-keys --output private-key.asc --armor 

```

By default **GnuPG** writes to STDOUT if no file is specified with the

`--output ` option.



Import backup of a private key:

```bash

$ gpg --allow-secret-key-import --import private-key.asc

```



### Editing keys



To open a menu for editing key related tasks, run:

```bash

$ gpg --edit-key 

```



Useful commands:

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

```bash

$ gpg --edit-key 

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

```bash

$ gpg --edit-key 

# gpg> adduid

#   Real name: Red Dragon

#   Email address: [email protected]

#   ... insert passphrase to unlock secret key ...

# gpg> save

```



If more UIDs were added to a key, we can set a primary UID:

```bash

$ gpg --edit-key 

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

```bash

$ gpg --armor --output my-public.key --export 

```

If no `` 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](#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:

```bash

$ gpg --import some-public.key

```



## Revoke a key



If, for instance, the private key bas been stolen, the UID has been changed, or

you forgot the passphrase, it is important 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**:

```bash

$ gpg --output revoke.asc --gen-revoke 

```



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:

```bash

$ gpg --import revoke.asc

```



If a [key server](#key-servers) is used, update the key server as well:

```bash

$ gpg --keyserver subkeys.pgp.net --send 

```

Note: The `--keyserver` option is not required, when the keyserver is specified

in `~/.gnupg/dirmngr.conf`.



## Encrypting and decrypting



After a public key has been imported, we can encrypt a file or message to that

recipient:

```bash

$ gpg [--output ] --recipient  --encrypt 

```



By default the encrypted file will be appended a `.gpg` suffix. This can be

changed with the `--output ` option.



To encrypt a file for personal use, `` 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

option `--local-user `. Otherwise the default key is used.



Decrypt a file that has been encrypted with our own public key:

```bash

$ 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 `--output` option.



Further options:

* `--armor, -a`: encrypt file using ASCII text

* `--hidden-recipient , -R `: 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 is 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:

```bash

$ gpg --sign  --output 

```



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:

```bash

$ gpg --clearsign  --output 

```



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

```bash

$ gpg --armor --output  --detach-sign 

```

This is highly recommended when signing binary files (like tar archives).



Sign and encrypt a file:

```bash

$ gpg --sign  [--armor] --encrypt --recipient  [--local-user ]

```

`--local-user ` specifies the key to sign with, it overrides

`--default-key ` option, which is usually specified in

`~/.gnupg/gpg.conf`.



When an encrypted file has been signed, the signature is usually checked when

the file is decrypted using the `--decrypt` option:

```bash

$ gpg --output  --decrypt 

```



To just check the signature use the `--verify` option:

```bash

$ gpg --verify 

```

This assumes the signer's public key has already been imported.



Assuming we downloaded a file `archive.tar.gz` and a corresponding detached

signature `archive.tar.gz.asc`, we can verify the signature after downloading

the signer's public key as follows:

```bash

$ gpg --verify archive.tar.gz.asc archive.tar.gz

```



## Key servers



Public keys can be registered with a public key server, so that others can

retrieve the key without having to contact you directly.



Send public key to key server, so that others can retrieve the key:

```bash

$ gpg --keyserver  --send-keys 

```



Find details about a key on the key server without importing it:

```bash

$ gpg --keyserver  --search-keys 

```



Locate the key of a user by email address:

```bash

$ gpg --keyserver  --auto-key-locate keyserver --locate-keys [email protected]

```



Import key from key server:

```bash

$ gpg --keyserver  --receive-keys 

```



Update all keys that have already been retrieved from a key server, e.g. with

latest signature, user IDs, etc.:

```

$ gpg --refresh-keys

```



To fetch keys automatically from a key server, add the following to

`~/.gnupg/gpg.conf`:

```

keyserver-options auto-key-retrieve

```



To avoid repeatedly specifying the key server with `--keyserver`, set a default

key server in `~/.gnupg/dirmngr.conf`:

```

keyserver hkps://keys.openpgp.org

```



A list of common key servers can be found in the [ArchWiki][arch-keyservers].



A new way to retrieve public OpenPGP keys is provided through the **Web Key

Directory**. More details can be found in the [GnuPG Wiki][wkd].



## 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 `--cipher-algo`

option.



Encrypt a file using a symmetric key:

```bash

$ gpg --symmetric 

```

This will create an encrypted file with a .gpg appended to the old file name.



Decrypt the encrypted file:

```bash

$ gpg [--output myfile] --decrypt myfile.gpg

```

The user will be prompted to enter the passphrase used to encrypt.



## References and further reading



* [The GNU Privacy Handbook][gnu-handbook]

* [Arch Linux wiki][arch-gpg]

* [OpenPGP best practices][best-practices]

* [LinuxCrypto][linux-crypto]

* [Linux commandline encryption tools][howtoforge]

* [GPG quickstart][madboa]

* [Ana's blog][ana]



[gnu-handbook]: https://www.gnupg.org/gph/en/manual.html

[arch-gpg]: https://wiki.archlinux.org/index.php/GnuPG

[arch-keyservers]: https://wiki.archlinux.org/title/GnuPG#Key_servers

[best-practices]: https://riseup.net/en/gpg-best-practices

[linux-crypto]: https://sanctum.geek.nz/arabesque/series/linux-crypto

[howtoforge]: https://www.howtoforge.com/tutorial/linux-commandline-encryption-tools

[madboa]: https://www.madboa.com/geek/gpg-quickstart

[ana]: https://ekaia.org/blog/2009/05/10/creating-new-gpgkey

[wkd]: https://wiki.gnupg.org/WKD