openpgp-notes/book/source/04-certificates.md

(certificates_chapter)=
# Certificates

OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," also known as "OpenPGP keys." These certificates are complex data structures essential for identity verification, data encryption, and digital signatures. Understanding their structure and function is pivotal to effectively applying the OpenPGP standard.

## Terminology: Understanding "keys"

The term "(cryptographic) keys" is central to grasping the concept of OpenPGP certificates. However, it can refer to different entities, making it a potentially confusing term. Let's clarify those differences.

### Public vs. private keys

The term "key," without additional context, can refer to either public or private asymmetric key material. Additionally, symmetric keys may be used in OpenPGP to encrypt private key material, adding a layer of security and complexity.

### Layers of keys in OpenPGP

In OpenPGP, the term "key" may refer to three distinct layers, each serving a unique purpose:

1. A (bare) ["cryptographic key"](asymmetric_key_pair) comprises the private and/or public parameters forming a key. For instance, in the case of an RSA private key, the key consists of the exponent `d` along with the prime numbers `p` and `q`.
2. An OpenPGP *component key* includes either an "OpenPGP primary key" or an "OpenPGP subkey." It is a building block of an OpenPGP certificate, consisting of a cryptographic keypair coupled with some invariant metadata, such as key creation time.
3. An "OpenPGP certificate" (or "OpenPGP key") consists of several component keys, identity components, and other elements. These certificates are dynamic, evolving over time as components are added, expire, or are marked as invalid.

In the following section, we'll look at the two OpenPGP-specific layers (2 and 3).


## Structure of OpenPGP certificates

An OpenPGP certificate (or "OpenPGP key") is a collection of an arbitrary number of elements[^packets]:

[^packets]: In technical terms, the elements of an OpenPGP certificate are a collection of "packets." Each component key and identity component is internally represented as a packet. Another common type of packet is the "signature" packet, which connect the components of a certificate.

- Component keys
- Identity components
- Additional metadata, including connections between the certificate's components

We sometimes collectively refer to component keys and identity information as "the components of a certificate."

```{admonition} Warning
Please clarify who "we" is in this statement. 
```

```{figure} diag/OpenPGP_Certificate.png

Typical components in an OpenPGP certificate
```

Every element in an OpenPGP certificate revolves around a central component: the *OpenPGP primary key*. The primary key acts as a personal CA (Certification Authority) for the certificate's owner, enabling cryptographic statements regarding subkeys, identities, expiration, revocation, and more.

```{note}
OpenPGP certificates tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. Components may be added or invalidated throughout a certificate's lifetime.
```

## Component keys

An OpenPGP certificate usually contains multiple OpenPGP component keys.

OpenPGP component keys consist of an [asymmetric cryptographic keypair](asymmetric_key_pair) and a creation timestamp. These attributes of a component key cannot be changed after creation (in the case of ECDH keys, two additional parameters are part of a component key's constituting data[^ecdh-paramters]).

[^ecdh-parameters]: For [ECDH](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-algorithm-specific-part-for-ecd) component keys, two additional algorithm parameters are integral to the component key's constitutive and immutable properties. Those parameters specify a hash function and a symmetric encryption algorithm.

```{figure} diag/Component_Key.svg

An OpenPGP component key
```

Component key representations that include private key material also contain metadata that specifies the password protection scheme for the private key material.

For each OpenPGP component key, an *OpenPGP fingerprint* can be generated. This fingerprint is derived from the combination of the public key material and creation timestamp (and ECDH parameters, if applicable).

```{figure} diag/Fingerprint.png

Every OpenPGP component key is identifiable by a unique fingerprint.
```

The fingerprint of our example component OpenPGP key is `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6  7F33 00F9 FB0E C457 378C D29F 1026 98B3` [^keyid].

[^keyid]: In OpenPGP version 4, the rightmost 64 bit were sometimes used as a shorter identifier, called "Key ID".
E.g., an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FBA4 1235 2B41  8972 C8B8 6AC4 2455 4239` might be referred to by the 64 bit Key ID `C8B8 6AC4 2455 4239` or styled as `0xC8B86AC424554239`.  
Historically, even shorter 32 bit identifiers have sometimes been used, like this: `2455 4239`, or `0x24554239`. You may still see such identifiers in very old documents about PGP. However, 32 bit identifiers have [been unfit for purpose for a long time](https://evil32.com/). At some point, 32 bit identifiers were called "short Key ID", while 64 bit identifiers were called "long Key ID".

Component keys are used in one of two roles: either as "OpenPGP primary key," or as an "OpenPGP subkey".

#### Primary key

The OpenPGP primary key is a distinct component key that serves a central role in an OpenPGP certificate:

- Its fingerprint is used as the unique identifier for the full OpenPGP certificate.
- It is used for lifecycle operations, such as adding or invalidating subkeys or identities in a certificate.

```{admonition} Terminology
:class: note

In the RFC, the OpenPGP primary key is occasionally referred to as "top-level key." Informally, it has also been termed the "master key."
```

### Subkeys

In addition to the primary key, modern OpenPGP certificates usually contain several subkeys, although they are not technically required.

Subkeys have the same structure as the primary key, but they are used in a different role. Subkeys are cryptographically linked with the primary key (more on this below).

```{figure} diag/Subkeys.png
:name: Certificate with subkeys
:alt: Three component keys depicted. The primary key is positioned at the top, designated for certification. Below it, linked by arrows, are two more component keys, used as subkeys. They are labeled as "for encryption" and "for signing," respectively.

OpenPGP certificates can contain multiple subkeys.
```

#### Defining operational capabilities with Key Flags

```{admonition} Warning
Let's decide whether the capitalization of F is necessary.
```

Each component key has a set of ["Key Flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) that delineate the operations a key can perform.

Commonly used key flags are:

- **C**ertification (issuing third-party certifications)
- **S**igning (signing data)
- **E**ncryption (encrypting data)
- **A**uthentication (commonly used for OpenPGP authentication)

```{admonition} Warning
Accessibility. Is the bolding of C, S, E, A compatible with screenreaders? Is it worth the effort?
```

By convention, only the primary key is allowed to perform "certification" operations. All other operations can be configured on either the primary key or a subkey.

```{note}

It is considered good practice to have separate component keys for each type of operation: to allow only *Certification* operations with the primary key, and to use separate *Signing*, *Encryption* and *Authentication* subkeys (independently: with most algorithms, encryption can't be shared with the other capabilities[^key-flag-sharing]).
```

[^key-flag-sharing]: With ECC algorithms, it's actually not possible to share encryption functionality with the signing-based functionalities, e.g.: ed25519 used for signing; cv25519 used for encryption.

### Component key metadata, including key flags

The key flags for a component key are actually not defined *inside* that component key itself.

Instead, key flags, together with other metadata about that component key (such as the key expiration time), are stored using mechanisms that join components together as an OpenPGP certificate:

- For the primary key, two different mechanisms can be used to define its key flags (as well as other metadata): That configuration can be associated with the [Primary User ID](primary_user_id), or via a [direct key signature](direct_key_signature).
- For subkeys, their key flags (and other metadata) are defined with the mechanism that connects the subkey with the certificate (via the primary key). More on that [below](binding_subkeys).


(identity_components)=
## Identity components

Identity components in an OpenPGP certificate are used by the certificate holder to state that they are known by a certain identifier (like a name, or an email address).

### User IDs

An OpenPGP certificate can contain any number of [User IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-id-packet-tag-13). Each User ID associates the certificate with an identity.

```{figure} diag/user_ids.png

OpenPGP certificates can contain any number of User IDs
```

Often, identities in a User ID consist of a UTF-8 encoded string that is composed of a name and an email address. By convention, User IDs typically consist of an [RFC2822](https://www.rfc-editor.org/rfc/rfc2822) *name-addr*.

Also see [draft-dkg-openpgp-userid-conventions-00](https://datatracker.ietf.org/doc/draft-dkg-openpgp-userid-conventions/), 25 August 2023.

One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). 

(primary_user_id)=
### Primary User ID and its implications

One User ID in a certificate has the special property of being the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-primary-user-id).

User IDs are associated with preference settings (such as preferred encryption algorithms, more on this in {numref}`zooming_in_user_id`). The preferences associated with the Primary User ID are used by default.

```{admonition} TODO
:class: warning

i think crypto-refresh suggests that the direct key signature should hold the default preferences?
we might need to write a more nuanced text here, about how DKS and primary user id interact in v6, and mention the differences to v4? 
```

### User attributes

[User attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-attribute-packet-tag-1) are similar to User IDs, but less commonly used.

The OpenPGP standard currently only defines one format to store in User Attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack), "presumably (but not required to be) that of the key owner".

## Linking the components

To form an OpenPGP certificate out of a collection of components, the certificate holder links these components together (using their OpenPGP software).

The OpenPGP term for linking components is "binding," as in: "a subkey is bound to the primary key." The bindings are realized using cryptographic signatures (much more details about this are in {ref}`certifications_chapter`).

In very abstract terms, the primary key of a certificate acts as a root of trust for that certificate (as a kind of "certification authority"):

The primary key issues signatures that express the certificate holder's intent to use subkeys or identity components. It also performs other lifecycle operations, such as setting expiration times, or marking components as invalidated ("revoked").

Binding components together with digital signatures means that recipients of an OpenPGP certificate only need to verify that the primary key is the correct one to use for their communication partner (traditionally, this has often been done by manually verifying the *fingerprint* of the primary key). Once the validity of the primary key is established, the validity of all other components can be automatically determined by the user's OpenPGP software. To a first estimation, components are valid parts of a certificate if there is a statement signed with the certificate's primary key that expresses this validity.

## Revocations

```{admonition} TODO
:class: warning

This section needs to be written
```

## Third party (identity) certifications

```{admonition} TODO
:class: warning

This section needs writing
```


In the past, the SKS keyserver network has accepted third party signatures and added them to certificates without any limitations. This has caused problems: anyone can add a large number of certifications to some certificates, which opens the door to a type of "vandalism", by growing certificates unreasonably, and making them annoying to use[^flooding].

[^flooding]: Storing third-party identity certifications in the target OpenPGP certificate is convenient for consumers: it is easy to find all relevant certifications in one central location. However, when third parties can unilaterally add certifications, this opens an avenue for denial-of-service attacks by flooding. The SKS network of OpenPGP key servers [allowed and experienced this problem](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html).


## Advanced topics

```{admonition} TODO
:class: warning

This section only contains notes and still needs to be written
```

### Certificate management / Evolution of a certificate over time

Minimized versions, merging, effective "append only" semantics, ...

### "Naming" a certificate in user-facing contexts - fingerprints and beyond

```{admonition} TODO
:class: warning

In v4, a 20 byte fingerprint in hex representation was used to name certificates, even in user-facing contexts.

For v6, this type of approach is discouraged, but a replacement mechanism is still pending.
```

### Merging

- How to merge two copies of the same certificate?
- Canonicalization

### How to generate "minimized" certificate?

### When are certificates valid?

- Full certificate: Primary revoked/key expired/binding signature expired,
- Subkey: Revoked/key expired/binding signature expired
- User ID: revoked, binding expired, ...

### Best practices regarding Key Freshness

```{admonition} TODO
:class: warning

- Expiry
- Subkey rotation

Wiktor suggests to check: https://blogs.gentoo.org/mgorny/2018/08/13/openpgp-key-expiration-is-not-a-security-measure/ for important material
```

### Metadata about the primary key: In Direct Key Signature vs. in Primary User ID, in v4 and v6

```{admonition} TODO
:class: warning

write
```

### Metadata leak of Social Graph

(unbound_user_ids)=
### Adding unbound User IDs to a certificate

```{admonition} TODO
:class: warning

references/links missing
```

Some OpenPGP subsystems may add User IDs to a certificate, which are not bound to the primary key by the certificate's owner. This can be useful to store local identity information (e.g., Sequoia's public store attaches "pet-names" to certificates, in this way).