vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2024-11-29 19:12:06 +01:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'heiko-ch4' into draft

Browse source 
# Conflicts:
#	book/source/04-certificates.md
This commit is contained in:
Heiko Schaefer 2023-11-25 19:40:56 +01:00
commit 3130ebee43
No known key found for this signature in database
GPG key ID: DAE9A9050FCCF1EB
3 changed files with 122 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
book/source/03-cryptography.md
View file

@ -6,6 +6,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
(cryptography_chapter)=
# Cryptographic concepts and terms
(crypto-hash)=
## Cryptographic hash functions
[Cryptographic hash functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) take data strings of any length (like a text message or file) and output a fixed-size code, a "hash digest," which is often abbreviated as either "digest" or "hash." A hash digest acts like a unique identifier for the original data.

197
book/source/04-certificates.md
View file

@ -6,7 +6,17 @@ SPDX-License-Identifier: CC-BY-SA-4.0
(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.
OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," also known as "OpenPGP public 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.
An OpenPGP certificate, by definition, does not contain private key material.
Fundamentally, the effective management of certificates and a thorough grasp of their authentication and trust models are crucial for proficient OpenPGP usage. Although this document offers just a brief overview of these aspects, they form a fundamental part of the broader OpenPGP framework and warrant further study.
- For an in-depth exploration of OpenPGP's private key material, refer to {ref}`private_key_chapter`. This chapter provides essential insights into private key management and security practices.
- The bindings that link the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity.
- Finally, our chapter {ref}`zoom_certificates` discusses the internal structure of certificates in detail.
## Terminology: Understanding "keys"
@ -26,8 +36,6 @@ In OpenPGP, the term "key" may refer to three distinct layers, each serving a un
The following section will delve into the OpenPGP-specific layers (2 and 3) to provide a clearer understanding of their roles within OpenPGP certificates.
For a discussion of private key material in OpenPGP, see the chapter {ref}`private_key_chapter`. Bindings that connect the components of a certificate are discussed in our chapter {ref}`component_signatures_chapter`. For much more detail on the internal (packet) structure of certificates and keys refer to our chapter {ref}`zoom_certificates`. Additionally, managing certificates, and understanding their authentication and trust models are vital topics. While this document briefly touches upon these aspects, they are integral to working proficiently with OpenPGP.
## Structure of OpenPGP certificates
An OpenPGP certificate (or "OpenPGP key") is a collection of an arbitrary number of elements[^packets]:
@ -47,10 +55,10 @@ This documentation collectively refers to component keys and identity components
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.
Every element in an OpenPGP certificate revolves around a central component: the *OpenPGP primary key*. The primary key acts as a personal *certification authority* (CA) 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.
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. However, once published, components [cannot be removed](append-only) from certificates.
```
## Component keys
@ -78,7 +86,7 @@ Each OpenPGP component key possesses an *OpenPGP fingerprint*. This fingerprint
:name: fig-fingerprint
:alt: Depicts a box with white background and the title "Fingerprint of an OpenPGP component key". Inside, another box with a green frame, the title "Component Key", the text "key creation time" on the lower left and a the green public key symbol on the lower right is shown. Below the component key box a fingerprint in a box with a light-yellow background and a yellow dotted line is depicted. The word "Fingerprint" is shown left of the box with the fingerprint and both are connected with a yellow dotted line.
Every OpenPGP component key is identifiable by a fingerprint. Although it's technically possible for different keys to share a fingerprint, cryptographic mechanisms make it exceedingly difficult, if not practically impossible with current technology, to find keys that share a fingerprint.
Every OpenPGP component key is identifiable by a fingerprint.
```
The fingerprint of our example OpenPGP component key is `C0A5 8384 A438 E5A1 4F73 7124 26A4 D45D BAEE F4A3 9E6B 30B0 9D55 13F9 78AC CA94`[^keyid].
@ -87,6 +95,12 @@ The fingerprint of our example OpenPGP component key is `C0A5 8384 A438 E5A1 4F7
For example, an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FBA4 1235 2B41 8972 C8B8 6AC4 2455 4239` might be referenced by the 64-bit Key ID `C8B8 6AC4 2455 4239` or formatted as `0xC8B86AC424554239`.
Historically, even shorter 32-bit identifiers were used, like this: `2455 4239`, or `0x24554239`. Such identifiers still appear in very old documents about PGP. However, [32-bit identifiers have been long deemed unfit for purpose](https://evil32.com/). At one point, 32-bit identifiers were called "short Key ID," while 64-bit identifiers were referred to as "long Key ID."
```{note}
In practice, the fingerprint of a component key, while not theoretically unique, functions effectively as a unique identifier. The use of a [cryptographic hash algorithm](crypto-hash) in generating fingerprints makes the occurrence of two different component keys with the same fingerprint extremely unlikely[^finger-unique].
```
[^finger-unique]: For both OpenPGP version 6 and version 4, the likelihood of accidental occurrence of duplicate fingerprints is negligible when key material is generated based on an acceptable source of entropy. A separate question is if an attacker can purposely craft a second key with the same fingerprint as a given pre-existing component key. With the current state of the art, this is not possible for OpenPGP version 6 and version 4 keys. However, at the time of this writing, the SHA-1-based fingerprints of OpenPGP version 4 are considered insufficiently strong at protecting against the generation of pairs of key material with the same fingerprint.
### Primary key
The OpenPGP primary key is a component key that serves a distinct, central role in an OpenPGP certificate:
@ -113,40 +127,6 @@ While subkeys have the same structural attributes as the primary key, they fulfi
OpenPGP certificates can contain multiple subkeys.
```
#### Defining operational capabilities with key flags
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 include:
- **Certification**: enables issuing third-party certifications
- **Signing**: allows the key to sign data
- **Encryption**: allows the key to encrypt data
- **Authentication**: primarily used for OpenPGP authentication
```{note}
Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7).
Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]).
```
[^key-flag-sharing]: With ECC algorithms, it's impossible to combine encryption functions with those intended for signing. For example, ed25519 is specifically used for signing; cv25519 is designated for encryption.
### Component key metadata, including key flags
The key flags for a component key are not stored within the component key directly.
Instead, key flags, along with other metadata about that component key, such as the key expiration time, are stored using mechanisms that bind components into an OpenPGP certificate:
- For the primary key, its key flags and other metadata can be defined in two ways: they can be linked with the [Primary User ID](primary_user_id) or through a [direct key signature](direct_key_signature).
- For subkeys, the key flags and other metadata are set using the mechanism that binds the subkey to the certificate, specifically through the primary key. Further details on [binding subkeys](binding_subkeys) are below.
```{admonition} TODO
:class: warning
Write a section about algorithm preference/feature signaling
```
(identity_components)=
## Identity components
@ -160,44 +140,41 @@ OpenPGP certificates can contain multiple [User IDs](https://www.ietf.org/archiv
:name: fig-user-ids
:alt: Depicts a diagram with white background and the title "User IDs". Inside, a public primary component key for certification and a User ID is shown. A green arrow points from component key to User ID and is annotated with a signature.
OpenPGP certificates can contain any number of User IDs
Relationship of User ID to primary component key in an OpenPGP certificate
```
A typical User ID identity is a UTF-8-encoded string composed of a name and an email address. By convention, User IDs align with the format described in [RFC2822](https://www.rfc-editor.org/rfc/rfc2822) as a *name-addr*.
For further conventions on User IDs, refer to the document [draft-dkg-openpgp-userid-conventions-00](https://datatracker.ietf.org/doc/draft-dkg-openpgp-userid-conventions/), dated 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).
**Split User IDs**
```{admonition} Warning
Heiko, please clarify what the value is of this proposal or remove it.
```
One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split].
[^dkg-split]: Historically, the OpenPGP ecosystem faced challenges in this context. For further details, refer to Daniel Kahn Gillmor's January 2019 article, ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids).
The rationale for split User IDs lies in the distinction between a name and an email address, which represent two separate facets of an individual's identity. Separating these elements simplifies the process for third parties tasked with certifying that an identity is legitimately connected to a certificate.
Consider this scenario: A third party is confident about the email-based identity of an individual (e.g.,`<alice@example.org>`) and is willing to certify it. However, they might not have sufficient knowledge about the person's name-based identity (e.g., `Alice Adams`), so are unwilling to extend the same level of certification. Split User IDs address this dichotomy by allowing distinct certification processes for each type of identity.
(primary_user_id)=
### Implications of the Primary User ID
Within a certificate, a specific User ID is designated as the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-primary-user-id).
Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). The preferences associated with the Primary User ID take precedence by default.
Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). When a certificate is used in the context of a specific identity, then the preferences associated with that identity component are used. When a certificate is used without reference to a specific identity, the preferences associated with the direct key signature, or the primary User ID take precedence 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?
the primary User ID can also specify metadata about the primary key
```
The primary User ID was historically the main store for preferences that apply to the certificate as a whole. For more on this, see {ref}`primary-metadata`.
### User attributes in OpenPGP
While
[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, they are less commonly used.
Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack). Typically, this image represents the key owner, although it is not required.
Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack) in JPEG format. Typically, this image represents the key owner, although it is not required.
## Linking the components
To form an OpenPGP certificate, individual components are interconnected by the certificate holder using their OpenPGP software. Within OpenPGP, this process is termed "binding," as in "a subkey is bound to the primary key." These bindings are realized using cryptographic signatures. An in-depth discussion of this topic can be found in {ref}`component_signatures_chapter`).
To form an OpenPGP certificate, individual components are interconnected by the certificate holder using their OpenPGP software. Within OpenPGP, this process is termed "binding," as in "a subkey is bound to the primary key." These bindings are realized using cryptographic signatures. An in-depth discussion of this topic can be found in {ref}`component_signatures_chapter`.
In very abstract terms, the primary key of a certificate acts as a root of trust or "certification authority." It is responsible for:
@ -206,43 +183,97 @@ In very abstract terms, the primary key of a certificate acts as a root of trust
By binding components using digital signatures, recipients of an OpenPGP certificate need only validate the authenticity of the primary key to use for their communication partner. Traditionally, this is done by manually verifying the *fingerprint* of the primary key. Once the validity of the primary key is confirmed, the validity of the remaining components can be automatically assessed by the user's OpenPGP software. Generally, components are valid parts of a certificate if there is a statement signed by the certificate's primary key endorsing this validity.
## Metadata in certificates
OpenPGP certificates, their component keys, and identities possess metadata that is not stored within the components it pertains to. Instead, this metadata is stored within signature packets, which are integral to the structure of an OpenPGP certificate.
Key attributes, such as capabilities (like *signing* or *encryption*) and expiration times, are examples of metadata not stored in the component key data. How this metadata is stored depends on the component:
- **Primary key metadata** is defined either through a direct key signature on the primary key (preferred in OpenPGP version 6), or by associating the metadata with the [Primary User ID](primary_user_id).
- **Subkey metadata** is defined within the [subkey binding signature](binding_subkeys) that links the subkey to the certificate.
- **Identity component metadata** is associated via the [certifying self-signature](bind_ident) that links the identity (usually in the form of a User ID) to the certificate.
It is crucial to note that the components of an OpenPGP certificate remain static after their creation. The use of signatures to store metadata allows for subsequent modifications without altering the original components. For instance, a certificate holder can update the expiration time of a component by issuing a new, superseding signature.
### Defining operational capabilities of component keys with key flags
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 include:
- **Certification**: enables issuing third-party certifications
- **Signing**: allows the key to sign data
- **Encryption**: allows the key to encrypt data
- **Authentication**: primarily used for SSH authentication[^auth-flag]
[^auth-flag]: It's important to note that the function of the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to the authentication process used in certifying OpenPGP identities and linking them to certificates. Rather, this flag indicates a mechanism that uses cryptographic signatures to confirm control of private key material with a remote system.
```{note}
Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. A component key can technically have multiple capabilities. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7).
Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing].
```
[^key-flag-sharing]: With ECC algorithms, it's impossible to combine encryption functions with those intended for signing. For example, ed25519 is specifically used for signing; cv25519 is designated for encryption.
### Algorithm preferences and feature signaling
OpenPGP incorporates significant ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). It doesn't rely on a single fixed set of algorithms. Instead, it defines a suite of cryptographic primitives from which users (or their applications) can choose.
This agility facilitates the easy adoption of new cryptographic primitives into the standard, allowing for a seamless transition. Users can gradually migrate to new cryptographic mechanisms without disruption.
However, this approach requires that OpenPGP software determine the cryptographic mechanisms that a set of communication partners can handle and prefer. OpenPGP employs several mechanisms for this purpose, which allow negotiation between sender and recipient. It's important to note that OpenPGP is not an online scheme; thus, this negotiation is effectively one-way. The active party interprets the preferences expressed in the certificate of the passive party.
Negotiation mechanisms in OpenPGP include:
- [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket)
- [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd)
- [Preferred AEAD ciphersuites](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v2-seipd)
- [Features subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket)
- [Preferred compression algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-compression-subpacket)
Beyond these explicitly expressed preferences, implementations also deduce capabilities of communication partners based on the version of the OpenPGP certificate they possess.
#### User ID-specific preferences
As a starting point, a certificate has a set of preferences that apply generally. These are defined either in a direct key signature, or via the primary User ID of the certificate.
Additionally, OpenPGP allows modeling User ID-specific preferences. The idea is that a user may prefer a different suite of algorithms on their private email account compared to their work email account. Such identity-specific preferences can be expressed on the certifying signatures that bind User IDs to a certificate.
## Revocations
```{admonition} TODO
:class: warning
When a certificate owner needs to invalidate certain components of their certificate, or even the entire certificate, they accomplish this through "revocation." Revoking the primary key renders the entire certificate invalid.
This section needs to be written
```
Notably, revocations are not the only means by which components can become invalid. Other factors, such as the passing of a component's expiration time, can also render components invalid.
For more detailed information on revoking specific components of a certificate, see the section on {ref}`self-revocations`.
## Third-party (identity) certifications
```{admonition} TODO
:class: warning
Since its inception, third-party identity certifications have been a cornerstone of the OpenPGP ecosystem. The original PGP designers, starting with Phil Zimmermann, advocated for decentralized trust models over reliance on centralized authorities. This decentralized approach in OpenPGP is known as the ["Web of Trust."](wot)
This section needs to be written
```
Third-party certifications are statements by OpenPGP users confirming that a user with a specific identity is the owner of a particular OpenPGP certificate.
Third-party identity certifications have historically played a pivotal role in the OpenPGP ecosystem.
For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams <alice@example.org>` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked.
Take, for instance, a scenario where Bob's OpenPGP software issues a certification confirming as legitimate the link between the User ID `Alice Adams <alice@example.org>` and the certificate bearing the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`.
This process assumes that Bob knows the person known as `Alice Adams` and is confident that `alice@example.org` is indeed Alice's email address. Bob also verifies that the certificate his OpenPGP software associates with Alice matches the one Alice uses. In essence, both users must have a certificate for Alice with an identical fingerprint. In OpenPGP version 6, manual fingerprint comparison by end-users is discouraged, with a replacement verification mechanism still under development. The verification process must occur over a sufficiently secure channel, such as an end-to-end encrypted video call or a face-to-face meeting.
For more on third-party certifications, see {ref}`third_party_cert`.
(cert-flooding)=
### Security considerations
While a convenience for consumers, indiscriminately accepting and integrating third-party identity certifications comes with significant risks.
While a convenience for consumers, indiscriminately accepting and integrating third-party identity certifications comes with significant risks.
Without any restrictions in place, malicious entities can flood a certificate with excessive certifications. Called "certificate flooding," this form of digital vandalism grossly expands the certificate size, making the certificate cumbersome and impractical for users.
Without any restrictions in place, malicious entities can flood a certificate with excessive certifications. Called "certificate flooding," this form of digital vandalism grossly expands the certificate size, making the certificate cumbersome and impractical for users.
It also opens the door to potential denial-of-service attacks, rendering the certificate non-functional or significantly impeding its operation.
The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019.
### Improved mechanisms in OpenPGP v6
```{admonition} TODO
:class: warning
This section needs to be written
```
It also opens the door to potential denial-of-service attacks, rendering the certificate non-functional or significantly impeding its operation.
The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019.
## Advanced topics
@ -310,3 +341,13 @@ 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).
### Third-party certification flooding
While a convenience for consumers, indiscriminately accepting and integrating third-party identity certifications comes with significant risks.
Without any restrictions in place, malicious entities can flood a certificate with excessive certifications. Called "certificate flooding," this form of digital vandalism grossly expands the certificate size, making the certificate cumbersome and impractical for users.
It also opens the door to potential denial-of-service attacks, rendering the certificate non-functional or significantly impeding its operation.
The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019.

2
book/source/08-signing_components.md
View file

@ -190,6 +190,7 @@ In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.i
In a certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the primary key of the certificate.
(self-revocations)=
### Revocation self-signatures: Invalidating components of a certificate
One important class of self-signatures are revocations.
@ -301,6 +302,7 @@ For example, Alice could delegate trust decisions only for email addresses in th
add diagrams?
```
(wot)=
### Decentralized automated trust decisions; or, the "Web of Trust"
The OpenPGP, the "Web of Trust" is a trust model that performs authentication decisions on a set of certifications and delegations.