> For the complete documentation index, see [llms.txt](https://yubico.gitbook.io/yubikey5/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yubico.gitbook.io/yubikey5/gpg/generate-keys/introduction.md).

# Introduction

<figure><img src="/files/yqOEJykb2fSv6wvdNEFi" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Before getting started, make sure you have configured your Yubikey with PINs that you have assigned and not the default PINs that come with the Yubikey.

\
[**Read about configuring your GPG PINs here.**](/yubikey5/gpg/getting-started/2.-pins.md)
{% endhint %}

## <mark style="color:red;">❊ What are GPG Keys?</mark>

When you generate a pair of GPG keys, you are generating a <mark style="color:red;">**public key**</mark>, and a <mark style="color:red;">**private key**</mark>.

The <mark style="color:orange;">**private key**</mark> should only be used by you, keep it safe.&#x20;

The <mark style="color:orange;">**public key**</mark> is used by other people in order to do things such as send you encrypted messages, encrypted files. You can share your public key with people by sending it to them or by uploading your public key to a keyserver service like [**Ubuntu Keyserver** ](https://keyserver.ubuntu.com/)or [**OpenPGP Keyserver**](https://keys.openpgp.org/).

Think of it as someone sending mail to your mailbox. The mailman can only place letters in your mailbox through a slot. However, you have a private key that can open the mailbox to take the letters out.

The public key contains your "ID", which allows a person to encrypt messages or files to you.&#x20;

The private key is what allows you to open those encrypted messages / files and view them.

### <mark style="color:blue;">SUBKEYS</mark>

Whenever you generate a private and public key, the first one is known as the master key. Under the master key, are subkeys, which all have jobs to do depending on what you assign for them. These jobs are called "capabilities".

*But why subkeys?*&#x20;

Subkeys are a great way to keep your master key protected. If you create a subkey which later gets lost, you can revoke that subkey without your entire keyring being compromised. Your master key will be safe and sound, and you just need to use your master key to generate a new subkey for whatever capability your lost one had.

### <mark style="color:blue;">KEY CAPABILITIES</mark>

Now that you're aware of what keys and subjeys are, the last big thing to know is the capabilities you can assign to your subkeys.

There are **four total capabilities** for keys:

<table><thead><tr><th width="234"></th><th></th></tr></thead><tbody><tr><td><mark style="color:red;"><strong><code>[C]</code></strong><strong>ertify</strong></mark></td><td>Used to sign / certify other keys that you generate. <br>This capability is assigned to your master key and cannot be removed.</td></tr><tr><td><mark style="color:red;"><strong><code>[S]</code></strong><strong>ignature</strong></mark></td><td>Used for signing data such as files or code<br>This capability is assigned to your master key by default, but can be removed and placed on a subkey.</td></tr><tr><td><mark style="color:red;"><strong><code>[E]</code></strong><strong>ncryption</strong></mark></td><td>Used to encrypting communications such as emails</td></tr><tr><td><mark style="color:red;"><strong><code>[A]</code></strong><strong>uthentication</strong></mark></td><td>Used for signing a challenge, tasks such as authenticating with protocols such as SSH.</td></tr></tbody></table>

<mark style="color:red;">**Encryption**</mark> and <mark style="color:red;">**signing**</mark> capabilities are the two that you are most likely to use in your every day life, and the names are pretty self-explanatory.

The <mark style="color:red;">**authentication**</mark> capability is not used as often, but there are implementations of SSH and other protocols that can use GPG keys for extra security.

The master key has the <mark style="color:red;">**certify**</mark> capability, which allows you to create subkeys with `E`, `S`, or `A` capabilities. The permission exists on the master key so that subkeys can't create an infinite number of subkeys themselves. Since the master key has the `[C]`ertify capapbility. This key must be kept the most secure..

By default, GPG assigns the `[C]`certify and `[S]`ign capability to your master key. Which means you can create more subkeys and also sign documents or code with the exact same master key.

However, if your master key has the `[S]`ign capability, that means you need to use it any time you want to sign something. If that master key gets lost, you'll have no way to sign files, and you won't be able to create new subkeys to replace lost/stolen subkeys.

For this reason is why it's recommended that you only allow your master key to have the `[C]`erify capability. Then you can generate subkeys with the `[S]`ign, `[A]`uthenticate, and `[E]`ncryption capabilities, and then put your master key somewhere safe offline, such as a USB drive.

With your master key having only the `[C]`ertify capability, now your subkeys can be assigned the remaining capabilities, which creates a setup like the following:

```n1ql


    PRIVATE KEY         PUBLIC KEY 
                 DEFAULT

┌─────────────────┐ ┌─────────────────┐
       ┌─────────────────┐
│    MASTER [C]   │ │    MASTER [C]   │
       │  MASTER [S][C]  │
└────────┬────────┘ └────────┬────────┘
       └────────┬────────┘
         │                   │
                         │
  ┌──────┴──────┐     ┌──────┴──────┐
           ┌──────┴──────┐
  │  SUBKEY [S] │     │  SUBKEY [S] │
           │  SUBKEY [E] │
  └──────┬──────┘     └──────┬──────┘
           └─────────────┘
         │                   │
  ┌──────┴──────┐     ┌──────┴──────┐
  │  SUBKEY [E] │     │  SUBKEY [E] │
  └──────┬──────┘     └──────┬──────┘
         │                   │
  ┌──────┴──────┐     ┌──────┴──────┐
  │  SUBKEY [A] │     │  SUBKEY [A] │
  └─────────────┘     └─────────────┘
```

With the above structure, you have one Master Private and Public keys, and then three subkeys of each capability which all have different roles to play.

If you lose your subkey assigned to `[E]`ncryption, you can revoke your lost subkey and then use your master key with the `[C]`ertify capability to generate another subkey and then re-assign that new subkey the `[E]`ncrpytion capability.

Once you view the guide on generating GPG keys, you'll understand where these keys and capabilities come into play.

### <mark style="color:blue;">SCENARIO</mark>

To illustrate an example; we'll use two fake people named <mark style="color:yellow;">**Brian**</mark> and <mark style="color:orange;">**Peter**</mark> :

* <mark style="color:yellow;">**Brian**</mark> and <mark style="color:orange;">**Peter**</mark> both create their own key pair, and publish their respective public keys to a keyserver.
* <mark style="color:yellow;">**Brian**</mark> wants to send <mark style="color:orange;">**Peter**</mark> an encrypted message.&#x20;

To do that:

* <mark style="color:yellow;">**Brian**</mark> looks for <mark style="color:orange;">**Peter**</mark>'s public key on a public keyservers.
* <mark style="color:yellow;">**Brian**</mark> *<mark style="color:green;">encrypts</mark>* a message using <mark style="color:orange;">**Peter**</mark>'s public key.
* <mark style="color:yellow;">**Brian**</mark> *<mark style="color:green;">signs</mark>* the encrypted message with his own private key.
* <mark style="color:orange;">**Peter**</mark> receives the encrypted and signed message.

The untrusted email header says it is from <mark style="color:yellow;">**Brian**</mark>.

* <mark style="color:orange;">**Peter**</mark> looks for <mark style="color:yellow;">**Brian**</mark>'s public key on the public keyservers.
* <mark style="color:orange;">**Peter**</mark> *verifies* the signature using Brian's public key.&#x20;
* <mark style="color:orange;">**Peter**</mark> is sure the message is from <mark style="color:yellow;">**Brian**</mark>.
* <mark style="color:orange;">**Peter**</mark> *decrypts* message using his own private key.
* <mark style="color:orange;">**Peter**</mark> finds out his sipment of drugs were lost in a traffic stop.

The process in general comes down to:

* <mark style="color:yellow;">**Brian**</mark> has used <mark style="color:orange;">**Peter**</mark> 's public key to encrypt the message.
* <mark style="color:yellow;">**Brian**</mark> has used his own private key to sign the message.
* <mark style="color:orange;">**Peter**</mark> has used <mark style="color:yellow;">**Brian**</mark>'s public key to verify the signature on the message.
* <mark style="color:orange;">**Peter**</mark> has used his own private key to decrypt the message.

## <mark style="color:red;">GPG vs PGP vs OpenGPG.... which one?</mark>

There's one more point of confusion to address. If you've spent any time Googling GPG, you'll realize very quickly that there's multiple terms for GPG, including PGP and OpenPGP. The question is <mark style="color:red;">**What's the difference?**</mark>

If you want the short version, PGP is paid, and GPG is free / open-source, which is why GPG has become more popular. But anything generated using PGP works with GPG.

Consider them all the same thing, just different words. But I'll break them down so you are aware.

<mark style="color:yellow;">**PGP**</mark>**&#x20;->** <mark style="color:yellow;">**Pretty Good Privacy:**</mark> Was first to release in 1991 by Phil Zimmermann & Associates and was used to protect files that people posted on the internet such as bulletin boards and old-school ways of sharing files before P2P (peer-2-peer) was a thing. PGP was then sold several times. Symantec bought PGP in 2010, and then Broadcom bought Symantec in 2019. So in short, Symantec as a company is no more, and Broadcom owns Symantec and PGP now. PGP has a program called PGP Desktop, however, it is paid software. Whereas the open-source version of GPG has many free software titles you can use.

<mark style="color:yellow;">**OpenPGP**</mark> **->** <mark style="color:yellow;">**Open-source PGP:**</mark> Created by one of the original PGP developers, Phil Zimmermann, as a way to employ encryption algorithms without the patent issues PGP had. In 1997, Zimmermann submitted an Open-source PGP standards proposal to the IETF (Internet Engineering Task Force). The acceptance of this standard allowed companies and encryption vendors to provide solutions that were compatible with other OpenPGP software. OpenPGP can be used to describe any software that supports, or is compliant with, the OpenPGP standard.

<mark style="color:yellow;">**GPG**</mark>**&#x20;->** <mark style="color:yellow;">**GNU Privacy Guard:**</mark> Developed in 1999 as an alternative to PGP encryption. The difference between GPG and PGP is that <mark style="color:red;">**GPG is completely free and open-source**</mark>. It is free to download, use, modify, distribute, throw on a bottle rocket and launch into space, and even free to burn onto a CD and toss in some bath water. It allows users to decrypt any PGP or OpenPGP file. GPG is a spinoff of PGP, but free to do whatever you wish.&#x20;

Hooray for Open-source!

## <mark style="color:red;">❊ Generating on Yubikey vs Software</mark>

Your Yubikey has the ability to generate a private and public keypair directly on your security device. Whereas, certain types of software have this same ability with the option to save (export) both your private and public keys as files you can use anywhere.

When you generate your keypair on the Yubikey itself, you are only allowed to save / export the public key. The private key will never leave the device. It ensures that only that device can decrypt messages or files that are sent to you. Only the public key can be exported and given to other people in order to send you encrypted things.

Software on the other hand, allows you to generate a private and public keypair, and lets you export both the private and public key to store somewhere on your device. You can take the exported private key and import it onto your Yubikey or any other device/software. This gives you the ability to set up multiple Yubikeys / other devices that can decrypt things addressed to you instead of only one device having the private key and ability to decrypt.

The question becomes ***"If I can't export my private key generated on a Yubikey, how can I make a backup?"***.

You will need to generate your keypairs on all the Yubikeys you want to be able to decrypt a file. When the person encrypts a file / message to send to you; they'll add multiple "recipients" / public keys to the file that is being encrypted. You will then be able to decrypt the file using any one of multiple Yubikeys. In short, you'll have multiple public keys you must send to people instead of just one public key.

## <mark style="color:red;">❊ What is a Keyserver?</mark>

First mentioned in the section above called [**What are GPG Keys?**](#what-are-gpg-keys) **->** Keyservers are services hosted by other companies / organizations that allow you to upload your GPG public key to an online directory / search engine that is made specifically for finding other people's public keys.

Think of it as a phone book *(you remember those, right?)*

You generate your private / public keypairs, and then use an online keyserver to upload your public key for others to find. People can search for your public key via email, name, or by the key id itself.

### <mark style="color:blue;">POPULAR KEYSERVERS</mark>

Some of the keyserver hosts available are:

{% hint style="info" %}
Be aware that some keyserver hosts do not allow you to delete your key from their server once it's uploaded. Your email address and name will be available for others to search. Some hosts do allow you to delete any uploaded keys.
{% endhint %}

* [**keyserver.ubuntu.com**](https://keyserver.ubuntu.com/)
* [**keys.openpgp.org**](https://keys.openpgp.org/)
* [**pgp.mit.edu**](http://pgp.mit.edu/)
* [**keyserver.pgp.com**](https://keyserver.pgp.com/vkd/GetWelcomeScreen.event)
* [**pgp.surfnet.nl**](https://pgp.surfnet.nl/)
* [**keys.mailvelope.com**](https://keys.mailvelope.com/)

### <mark style="color:blue;">SELF-HOSTED KEYSERVERS</mark>

You must also launch your own keyserver by using available open-source applications on the market:

* [**keyoxide.org**](https://keyoxide.org/)
* [**pks.sourceforge.net**](https://pks.sourceforge.net/)
* [**SKS Keyserver**](https://github.com/cmars/sks-keyserver)
* [**HockeyPuck**](https://launchpad.net/hockeypuck)

### <mark style="color:blue;">MAIL CLIENTS WITH KEYSERVER INTEGRATION</mark>

If you're looking for email applications that support GPG encryption you can try the following:

* [**EM Mail Client**](https://www.emclient.com/)
* [**Thunderbird**](https://www.thunderbird.net/en-US/)
* [**ProtonMail**](https://proton.me/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yubico.gitbook.io/yubikey5/gpg/generate-keys/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.