vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2025-09-10 03:39:41 +02:00
Code Issues Projects Releases Packages Wiki Activity

Standardize on kebab case for explicit targets

Browse source 
Signed-off-by: David Runge <dave@sleepmap.de>
This commit is contained in:
David Runge 2023-12-12 16:12:57 +01:00
parent 76c70d85ec
commit 144f10a526
No known key found for this signature in database
GPG key ID: 90D4B9641E092971
23 changed files with 140 additions and 140 deletions
Download patch file Download diff file Expand all files Collapse all files

36
book/source/certificates.md
View file

@ -25,12 +25,12 @@ The term "{term}`(cryptographic) keys<Cryptographic Key>`" is central to graspin
The term "{term}`key`," without additional context, can refer to either public or private {term}`asymmetric<Asymmetric Cryptography>` key material. Additionally, {term}`symmetric<Symmetric Cryptography>` keys may be used in OpenPGP to encrypt {term}`private key material`, adding a layer of security and complexity.
(layers_of_keys_in_openpgp)=
(layers-of-keys-in-openpgp)=
### Layers of keys in OpenPGP
In OpenPGP, the term "{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 {term}`private key<Transferable Secret Key>`, the key consists of the exponent `d` along with the prime numbers `p` and `q`.
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 {term}`private key<Transferable Secret Key>`, the key consists of the exponent `d` along with the prime numbers `p` and `q`.
2. An OpenPGP *{term}`component key<OpenPGP Component Key>`* includes either an "{term}`OpenPGP primary key`" or an "{term}`OpenPGP subkey`." It is a building block of an {term}`OpenPGP certificate`, consisting of a cryptographic keypair coupled with some invariant {term}`metadata`, such as key {term}`creation time`.
3. An "{term}`OpenPGP certificate`" (or "OpenPGP key") consists of several {term}`component keys<OpenPGP Component Key>`, {term}`identity components<Identity Component>`, and other elements. These {term}`certificates<Certificate>` are dynamic, evolving over time as {term}`components<Component>` are added, {term}`expire<Expiration>`, or are marked as {term}`invalid<Validation>`.
@ -61,12 +61,12 @@ Every element in an {term}`OpenPGP certificate` revolves around a central {term}
{term}`OpenPGP certificates<OpenPGP Certificate>` tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. {term}`Components<Component>` may be added or {term}`invalidated<Validation>` throughout a {term}`certificate<OpenPGP Certificate>`'s lifetime. However, once published, {term}`components<Component>` [cannot be removed](append-only) from {term}`certificates<OpenPGP Certificate>`.
```
(component_keys)=
(component-keys)=
## Component keys
An {term}`OpenPGP certificate` usually contains multiple {term}`component keys<OpenPGP Component Key>`. {term}`Component keys<OpenPGP Component Key>` serve in one of two roles: either as an "{term}`OpenPGP primary key`" or as an "{term}`OpenPGP subkey`."
{term}`OpenPGP component keys<OpenPGP Component Key>` logically consist of an [asymmetric cryptographic keypair](asymmetric_key_pair) and a creation timestamp. Once created, these attributes of a {term}`component key<OpenPGP Component Key>` remain fixed (for ECDH keys, two additional parameters are part of a {term}`component key`'s constitutive data[^ecdh-parameters]).
{term}`OpenPGP component keys<OpenPGP Component Key>` logically consist of an [asymmetric cryptographic keypair](asymmetric-key-pair) and a creation timestamp. Once created, these attributes of a {term}`component key<OpenPGP Component Key>` remain fixed (for ECDH keys, two additional parameters are part of a {term}`component key`'s constitutive data[^ecdh-parameters]).
[^ecdh-parameters]: For [ECDH](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-part-for-ecd) {term}`component keys<OpenPGP Component Key>`, two additional algorithm parameters are integral to the {term}`component key<OpenPGP Component Key>`'s constitutive and immutable properties. Those parameters specify a hash function and a {term}`symmetric<Symmetric Cryptography>` encryption algorithm.
@ -103,7 +103,7 @@ In practice, the {term}`fingerprint<OpenPGP Fingerprint>` of a {term}`component
[^finger-unique]: For both {term}`OpenPGP version 6<RFC>` and version 4, the likelihood of accidental occurrence of duplicate {term}`fingerprints<OpenPGP Fingerprint>` is negligible when {term}`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 {term}`fingerprint<OpenPGP Fingerprint>` as a given pre-existing {term}`component key<OpenPGP 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 {term}`fingerprints<OpenPGP Fingerprint>` of OpenPGP version 4 are considered insufficiently strong at protecting against the generation of pairs of {term}`key material` with the same {term}`fingerprint<OpenPGP Fingerprint>`.
(primary_key)=
(primary-key)=
### Primary key
The {term}`OpenPGP primary key` is a {term}`component key<OpenPGP Component Key>` that serves a distinct, central role in an {term}`OpenPGP certificate`:
@ -122,7 +122,7 @@ In the {term}`RFC`, the {term}`OpenPGP primary key` is occasionally referred to
Modern {term}`OpenPGP certificates<OpenPGP Certificate>` typically include several {term}`subkeys<OpenPGP Subkey>` in addition to the {term}`primary key<OpenPGP Primary Key>`, although these {term}`subkeys<OpenPGP Subkey>` are optional.
While {term}`subkeys<OpenPGP Subkey>` have the same structural attributes as the {term}`primary key<OpenPGP Primary Key>`, they fulfill different roles. {term}`Subkeys<OpenPGP Subkey>` are cryptographically linked with the {term}`primary key<OpenPGP Primary Key>`, a relationship further discussed in {numref}`binding_subkeys`.
While {term}`subkeys<OpenPGP Subkey>` have the same structural attributes as the {term}`primary key<OpenPGP Primary Key>`, they fulfill different roles. {term}`Subkeys<OpenPGP Subkey>` are cryptographically linked with the {term}`primary key<OpenPGP Primary Key>`, a relationship further discussed in {numref}`binding-subkeys`.
```{figure} plain_svg/Binding_Subkeys.svg
:name: fig-subkeys
@ -131,12 +131,12 @@ While {term}`subkeys<OpenPGP Subkey>` have the same structural attributes as the
{term}`OpenPGP certificates<OpenPGP Certificate>` can contain multiple {term}`subkeys<OpenPGP Subkey>`.
```
(identity_components)=
(identity-components)=
## Identity components
{term}`Identity components<Identity Component>` in an {term}`OpenPGP certificate` are used by the {term}`certificate holder` to state that they are known by a certain identifier (like a name, or an email address).
(user_ids_in_openpgp_certificates)=
(user-ids-in-openpgp-certificates)=
### User IDs in OpenPGP certificates
{term}`OpenPGP certificates<OpenPGP Certificate>` can contain multiple [User IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#uid). Each {term}`User ID` associates the {term}`certificate<OpenPGP Certificate>` with an {term}`identity`.
@ -162,16 +162,16 @@ The rationale for split {term}`User IDs<User ID>` lies in the distinction betwee
Consider this scenario: A third party is confident about the email-based {term}`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 {term}`identity` (e.g., `Alice Adams`), so are unwilling to extend the same level of {term}`certification`. Split {term}`User IDs<User ID>` address this dichotomy by allowing distinct {term}`certification` processes for each type of {term}`identity`.
(primary_user_id)=
(primary-user-id)=
### Implications of the Primary User ID
Within a {term}`certificate<OpenPGP Certificate>`, a specific {term}`User ID` is designated as the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id).
Each {term}`User ID` carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). When a {term}`certificate<OpenPGP Certificate>` is used in the context of a specific {term}`identity`, then the preferences associated with that {term}`identity component` are used. When a {term}`certificate<OpenPGP Certificate>` is used without reference to a specific {term}`identity`, the preferences associated with the {term}`direct key signature`, or the {term}`primary User ID` take precedence by default.
Each {term}`User ID` carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming-in-user-id`). When a {term}`certificate<OpenPGP Certificate>` is used in the context of a specific {term}`identity`, then the preferences associated with that {term}`identity component` are used. When a {term}`certificate<OpenPGP Certificate>` is used without reference to a specific {term}`identity`, the preferences associated with the {term}`direct key signature`, or the {term}`primary User ID` take precedence by default.
The {term}`primary User ID` was historically the main store for preferences that apply to the {term}`certificate<OpenPGP Certificate>` as a whole. For more on this, see {ref}`primary-metadata`.
(user_attributes)=
(user-attributes)=
### User attributes in OpenPGP
While
[user attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#user-attribute-packet) are similar to {term}`User IDs<User ID>`, they are less commonly used.
@ -189,18 +189,18 @@ In very abstract terms, the {term}`primary key<OpenPGP Primary Key>` of a {term}
By binding {term}`components<Component>` using digital {term}`signatures<OpenPGP Signature Packet>`, recipients of an {term}`OpenPGP certificate` need only {term}`validate<Validation>` the {term}`authenticity<Authentication>` of the {term}`primary key` to use for their communication partner. Traditionally, this is done by manually verifying the *{term}`fingerprint<OpenPGP Fingerprint>`* of the {term}`primary key<OpenPGP Primary Key>`. Once the {term}`validity<Validation>` of the {term}`primary key<OpenPGP Primary Key>` is confirmed, the {term}`validity<Validation>` of the remaining {term}`components<Component>` can be automatically assessed by the user's OpenPGP software. Generally, {term}`components<Component>` are {term}`valid<Validation>` parts of a {term}`certificate<OpenPGP Certificate>` if there is a statement signed by the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>` endorsing this {term}`validity<Validation>`.
(metadata_in_certificates)=
(metadata-in-certificates)=
## Metadata in certificates
{term}`OpenPGP certificates<OpenPGP Certificate>`, their {term}`component keys<Component Key>`, and {term}`identities<Identity>` possess {term}`metadata` that is not stored within the {term}`components<Component>` it pertains to. Instead, this {term}`metadata` is stored within signature packets, which are integral to the structure of an OpenPGP certificate.
Key attributes, such as {term}`capabilities<Capability>` (like *signing* or *encryption*) and {term}`expiration times<Expiration Time>`, are examples of {term}`metadata` not stored in the {term}`component key` data. How this {term}`metadata` is stored depends on the {term}`component`:
- **{term}`Primary key<OpenPGP Primary Key>` {term}`metadata`** is defined either through a {term}`direct key signature` on the {term}`primary key<OpenPGP Primary Key>` (preferred in OpenPGP version 6), or by associating the {term}`metadata` with the [Primary User ID](primary_user_id).
- **{term}`Primary key<OpenPGP Primary Key>` {term}`metadata`** is defined either through a {term}`direct key signature` on the {term}`primary key<OpenPGP Primary Key>` (preferred in OpenPGP version 6), or by associating the {term}`metadata` with the [Primary User ID](primary-user-id).
- **{term}`Subkey<OpenPGP Subkey>` {term}`metadata`** is defined within the [subkey binding signature](binding_subkeys) that links the {term}`subkey<OpenPGP Subkey>` to the {term}`certificate<OpenPGP Certificate>`.
- **{term}`Subkey<OpenPGP Subkey>` {term}`metadata`** is defined within the [subkey binding signature](binding-subkeys) that links the {term}`subkey<OpenPGP Subkey>` to the {term}`certificate<OpenPGP Certificate>`.
- **{term}`Identity component` {term}`metadata`** is associated via the [certifying self-signature](bind_ident) that links the {term}`identity` (usually in the form of a {term}`User ID`) to the {term}`certificate<OpenPGP Certificate>`.
- **{term}`Identity component` {term}`metadata`** is associated via the [certifying self-signature](bind-ident) that links the {term}`identity` (usually in the form of a {term}`User ID`) to the {term}`certificate<OpenPGP Certificate>`.
It is crucial to note that the {term}`components<Component>` of an {term}`OpenPGP certificate` remain static after their creation. The use of {term}`signatures<OpenPGP Signature Packet>` to store {term}`metadata` allows for subsequent modifications without altering the original {term}`component<Component>`. For instance, a {term}`certificate holder` can update the {term}`expiration time` of a {term}`component` by issuing a new, superseding {term}`signature<OpenPGP Signature Packet>`.
@ -211,7 +211,7 @@ It is crucial to note that the {term}`components<Component>` of an {term}`OpenPG
{term}`Metadata` can be associated with the {term}`primary key<OpenPGP Primary Key>` using a *{term}`direct key signature`*.
```
(capabilities_key_flags)=
(capabilities-key-flags)=
### Defining operational capabilities of component keys with key flags
Each {term}`component key` has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags) that delineate the operations a key can perform.
@ -278,7 +278,7 @@ Notably, {term}`revocations<Revocation>` are not the only means by which {term}`
For more detailed information on {term}`revoking<Revocation>` specific {term}`components<Component>` of a {term}`certificate<OpenPGP Certificate>`, see the section on {ref}`self-revocations`.
(third_party_identity_certifications)=
(third-party-identity-certifications)=
## Third-party (identity) certifications
Since its inception, {term}`third-party identity certifications<Third-party Identity Certification>` have been a cornerstone of the OpenPGP ecosystem. The original PGP designers, starting with Phil Zimmermann, advocated for decentralized {term}`trust models<Trust Model>` over reliance on centralized authorities. This decentralized approach in OpenPGP is known as the ["Web of Trust."](wot)
@ -291,4 +291,4 @@ Take, for instance, a scenario where Bob's OpenPGP software issues a {term}`cert
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 {term}`certificate<OpenPGP Certificate>` his OpenPGP software associates with Alice matches the one Alice uses. In essence, both users must have a {term}`certificate<OpenPGP Certificate>` for Alice with an identical {term}`fingerprint<OpenPGP Fingerprint>`. In OpenPGP version 6, manual {term}`fingerprint<OpenPGP Fingerprint>` comparison by end-users is discouraged, with a replacement {term}`verification` mechanism still under development. The {term}`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 {term}`certifications<Certification>`, see {ref}`third_party_cert`.
For more on third-party {term}`certifications<Certification>`, see {ref}`third-party-cert`.