diff --git a/book/source/about.md b/book/source/about.md index 81a3e6e..00ecf8c 100644 --- a/book/source/about.md +++ b/book/source/about.md @@ -11,7 +11,7 @@ This documentation project seeks to introduce all OpenPGP concepts and functiona ## What is OpenPGP? -OpenPGP is an open standard for cryptographic operations. It is a system based on well-understood [cryptographic building blocks](/cryptography). OpenPGP supports the secure delivery of files and messages between a sender and a recipient. It also addresses identities and their verification. OpenPGP is an outgrowth of the ["Pretty Good Privacy (PGP)"](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) encryption program and has many widely used and [interoperable implementations](interop_section). +OpenPGP is an open standard for cryptographic operations. It is a system based on well-understood [cryptographic building blocks](/cryptography). OpenPGP supports the secure delivery of files and messages between a sender and a recipient. It also addresses identities and their verification. OpenPGP is an outgrowth of the ["Pretty Good Privacy (PGP)"](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) encryption program and has many widely used and [interoperable implementations](interop-section). With OpenPGP, you can: @@ -48,4 +48,4 @@ This documentation encompasses the core aspects of modern OpenPGP practices, app While using version 6 as a reference for current standards, we include insights derived from earlier versions, particularly version 4, which continues to be widely used in ongoing projects. -Where differences between OpenPGP versions are relevant to application development, we provide focused insights to ensure the content remains as version-agnostic as possible and, thus, broadly applicable for developers working with various iterations of OpenPGP. \ No newline at end of file +Where differences between OpenPGP versions are relevant to application development, we provide focused insights to ensure the content remains as version-agnostic as possible and, thus, broadly applicable for developers working with various iterations of OpenPGP. diff --git a/book/source/adv/certificates.md b/book/source/adv/certificates.md index f91f79a..d0b7367 100644 --- a/book/source/adv/certificates.md +++ b/book/source/adv/certificates.md @@ -102,7 +102,7 @@ When thinking about edge cases, it's useful to "assume the worst." For example: Another way to think about this discussion is that different OpenPGP users may have a different view of any certificate. There is a notional "canonical" version of the certificate, but we cannot assume that every user has exactly this copy. Besides propagation of elements that the certificate holder has linked to a certificate, third-party certifications are by design a distributed mechanism. A third-party certification is issued by a third party, and may or may not be distributed widely by them, or by the certificate holder. Not distributing third-party certifications widely is a workflow that may be entirely appropriate for some use cases[^tpc-privacy]. -[^tpc-privacy]: The two parties to a certification (the issuer and the target of the certification) may prefer not to publish their mutual association. Also see {ref}`metadata_graph`. +[^tpc-privacy]: The two parties to a certification (the issuer and the target of the certification) may prefer not to publish their mutual association. Also see {ref}`metadata-graph`. As a general tendency, it is desirable for OpenPGP users to have the most complete possible view of all certificates that they interact with. @@ -290,7 +290,7 @@ Once the expiration time is reached, third parties, or ideally their OpenPGP sof After the update, the updated copy of the certificate will usually have a fresh expiration time. The same procedure will repeat once that new expiration time has been reached. -(metadata_graph)= +(metadata-graph)= ## Metadata leak of Social Graph Third-party certifications are signatures over identity components made by other users. @@ -308,7 +308,7 @@ So, there is some tension between the goals of - a decentralized system where every participant can access certification information and perform analysis on it locally, - privacy related goals (also see {ref}`email-lookup`, for a comparison of certificate distribution mechanisms, which also touches on this theme). -(unbound_user_ids)= +(unbound-user-ids)= ## Adding unbound, local User IDs to a certificate Some OpenPGP software 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"][PET] to certificates, in this way). diff --git a/book/source/adv/decryption.md b/book/source/adv/decryption.md index 101df4c..de2fccb 100644 --- a/book/source/adv/decryption.md +++ b/book/source/adv/decryption.md @@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 # Advanced material: Decryption -(decryption_seipd_quick_check)= +(decryption-seipd-quick-check)= ## Verify successful session key decryption SEIPDv1 packets might make use of a "quick check" mechanism to quickly verify that the correct session key was used without the need to decrypt the whole SEIPD packet. @@ -16,7 +16,7 @@ Since the chance to accidentally end up with matching quick check bytes albeit t The standard [warns against](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-risks-of-a-quick-check-orac) using the quick check mechanism, as it introduces the risk of a decryption oracle. Instead, the use of SEIPDv2 is recommended, as the AEAD mechanism automatically detects use of the wrong session key early on after the first chunk has been decrypted. -(decryption_anonymous_recipient)= +(decryption-anonymous-recipient)= ## Anonymous recipients Having all recipients keys listed as part of the PKESK packets presents a metadata leakage. An observer can easily enumerate recipients of a message by comparing the PKESKs with certificates of potential recipients. diff --git a/book/source/adv/private_keys.md b/book/source/adv/private_keys.md index 40f6bad..66f38de 100644 --- a/book/source/adv/private_keys.md +++ b/book/source/adv/private_keys.md @@ -75,7 +75,7 @@ Understanding KO attacks is crucial due to their potential to compromise the int Private keys that are protected with [S2K usage mode 253 (AEAD)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption), are not vulnerable to KO attacks. This mode ensures the integrity of the private key by using its unencrypted fields (including the algorithm field) as the *authentication tag* for integrity verification in the decryption process. When an attacker alters the unencrypted part of the packet, then decryption of the private key material will fail, and the user is prevented from e.g. accidentally using the key material with an altered attacker-controlled algorithm. -Note that while S2K usage mode 253 (AEAD) has been introduced in the OpenPGP version 6 specification, it can also be applied to OpenPGP version 4 key material (also see {ref}`migration_s2k`). +Note that while S2K usage mode 253 (AEAD) has been introduced in the OpenPGP version 6 specification, it can also be applied to OpenPGP version 4 key material (also see {ref}`migration-s2k`). #### Resources diff --git a/book/source/adv/signatures.md b/book/source/adv/signatures.md index 706077d..2cabf7b 100644 --- a/book/source/adv/signatures.md +++ b/book/source/adv/signatures.md @@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 # Advanced material: Signatures -(notation_signature_subpackets)= +(notation-signature-subpackets)= ## Notation signature subpackets [Notation signature subpackets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#notation-data) can be used to effectively extend the otherwise limited set of {term}`signature subpacket types` in OpenPGP with user-defined {term}`notations`. {term}`Issuers` can use these {term}`notations` to add name-value pairs to an {term}`OpenPGP signature`. @@ -52,4 +52,4 @@ That is: Note that some historical version 3 signature packets may still be relevant for applications that handle old OpenPGP data[^sig-v3]. These version 3 signature packets will have been generated by version 4 keys. -[sig-v3]Version 4 signature packets were introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-5.2) in 1998, which specifies that applications SHOULD generate v4 signature, however generation of v3 signature packets has remained allowed through [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.2). \ No newline at end of file +[sig-v3]Version 4 signature packets were introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-5.2) in 1998, which specifies that applications SHOULD generate v4 signature, however generation of v3 signature packets has remained allowed through [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.2). diff --git a/book/source/adv/signing_components.md b/book/source/adv/signing_components.md index 19b4110..e76cd28 100644 --- a/book/source/adv/signing_components.md +++ b/book/source/adv/signing_components.md @@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 Different {term}`signatures` in OpenPGP serve various specific purposes. This section provides practical guidance on creating these {term}`signatures`, illustrating each with concrete examples. -(change_algorithm_preferences)= +(change-algorithm-preferences)= ### Change algorithm preferences To modify the preferred {term}`symmetric`, compression, {term}`hash`, or {term}`AEAD algorithms` for a {term}`key`, the {term}`key owner` needs to issue a {term}`direct key signature` ({term}`type ID` `0x1F`) on the {term}`primary key`. @@ -32,7 +32,7 @@ This {term}`signature` should have the following struc To adjust the {term}`expiration time` of an {term}`OpenPGP certificate`, a new *{term}`DirectKey`* {term}`signature` ({term}`type ID` `0x1F`) with a modified {term}`Key Expiration Time subpacket` must be issued. The structure of this {term}`signature` is identical to the one outlined in the previous section on changing {term}`algorithm preferences`. -Additionally, the {term}`expiration time` can be altered for individual {term}`User IDs` (detailed below) or separate {term}`subkeys` (see {numref}`bind_subkey`). +Additionally, the {term}`expiration time` can be altered for individual {term}`User IDs` (detailed below) or separate {term}`subkeys` (see {numref}`bind-subkey`). ### Add User ID @@ -73,7 +73,7 @@ For {term}`User ID` {term}`revocations`, the *{term}`Reason for Revo It is generally advisable to use reason code `32` for revoking {term}`User IDs`. -(binding_subkeys)= +(binding-subkeys)= ### Add a subkey As part of {term}`life-cycle management`, users may need to add a new {term}`subkey` to their {term}`OpenPGP certificate`, often for reasons such as upgrading to a {term}`subkey` with more advanced cryptographic algorithms. The process involves creating a specific {term}`signature` structure: diff --git a/book/source/artifacts.md b/book/source/artifacts.md index 460a1b8..e92c03b 100644 --- a/book/source/artifacts.md +++ b/book/source/artifacts.md @@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 # Appendix A: OpenPGP artifacts -(alice_priv)= +(alice-priv)= ## Alice's OpenPGP key ```text @@ -46,7 +46,7 @@ FcsHp6K860qG87pDlk2saQIwzXPmQcQvLokbeQMB -----END PGP PRIVATE KEY BLOCK----- ``` -(bob_priv)= +(bob-priv)= ## Bob's OpenPGP key Bob uses passphrase-protected secret key packets. His passphrase is `password`: @@ -92,4 +92,4 @@ wVXtKDX+MOKJM4xz7RvBWErH2xWyqikNZQVuzz/WqOVH/nT+BcqmLWAe3yjrTE4B hSfrR38Nk23E4Bu4HobVrg7rlMU6SKHRWKeX/iSUmr6GDA== =UZBq -----END PGP PRIVATE KEY BLOCK----- -``` \ No newline at end of file +``` diff --git a/book/source/certificates.md b/book/source/certificates.md index 643c3ba..ec7b374 100644 --- a/book/source/certificates.md +++ b/book/source/certificates.md @@ -25,12 +25,12 @@ The term "{term}`(cryptographic) keys`" is central to graspin The term "{term}`key`," without additional context, can refer to either public or private {term}`asymmetric` key material. Additionally, {term}`symmetric` 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`, 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`, the key consists of the exponent `d` along with the prime numbers `p` and `q`. 2. An OpenPGP *{term}`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`, {term}`identity components`, and other elements. These {term}`certificates` are dynamic, evolving over time as {term}`components` are added, {term}`expire`, or are marked as {term}`invalid`. @@ -61,12 +61,12 @@ Every element in an {term}`OpenPGP certificate` revolves around a central {term} {term}`OpenPGP certificates` tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. {term}`Components` may be added or {term}`invalidated` throughout a {term}`certificate`'s lifetime. However, once published, {term}`components` [cannot be removed](append-only) from {term}`certificates`. ``` -(component_keys)= +(component-keys)= ## Component keys An {term}`OpenPGP certificate` usually contains multiple {term}`component keys`. {term}`Component keys` serve in one of two roles: either as an "{term}`OpenPGP primary key`" or as an "{term}`OpenPGP subkey`." -{term}`OpenPGP component keys` logically consist of an [asymmetric cryptographic keypair](asymmetric_key_pair) and a creation timestamp. Once created, these attributes of a {term}`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` logically consist of an [asymmetric cryptographic keypair](asymmetric-key-pair) and a creation timestamp. Once created, these attributes of a {term}`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`, two additional algorithm parameters are integral to the {term}`component key`'s constitutive and immutable properties. Those parameters specify a hash function and a {term}`symmetric` encryption algorithm. @@ -103,7 +103,7 @@ In practice, the {term}`fingerprint` of a {term}`component [^finger-unique]: For both {term}`OpenPGP version 6` and version 4, the likelihood of accidental occurrence of duplicate {term}`fingerprints` 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` as a given pre-existing {term}`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` of OpenPGP version 4 are considered insufficiently strong at protecting against the generation of pairs of {term}`key material` with the same {term}`fingerprint`. -(primary_key)= +(primary-key)= ### Primary key The {term}`OpenPGP primary key` is a {term}`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` typically include several {term}`subkeys` in addition to the {term}`primary key`, although these {term}`subkeys` are optional. -While {term}`subkeys` have the same structural attributes as the {term}`primary key`, they fulfill different roles. {term}`Subkeys` are cryptographically linked with the {term}`primary key`, a relationship further discussed in {numref}`binding_subkeys`. +While {term}`subkeys` have the same structural attributes as the {term}`primary key`, they fulfill different roles. {term}`Subkeys` are cryptographically linked with the {term}`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` have the same structural attributes as the {term}`OpenPGP certificates` can contain multiple {term}`subkeys`. ``` -(identity_components)= +(identity-components)= ## Identity components {term}`Identity components` 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` 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` with an {term}`identity`. @@ -162,16 +162,16 @@ The rationale for split {term}`User IDs` lies in the distinction betwee Consider this scenario: A third party is confident about the email-based {term}`identity` of an individual (e.g.,``) 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` 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`, 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` 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` 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` 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` 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` 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`, they are less commonly used. @@ -189,18 +189,18 @@ In very abstract terms, the {term}`primary key` of a {term} By binding {term}`components` using digital {term}`signatures`, recipients of an {term}`OpenPGP certificate` need only {term}`validate` the {term}`authenticity` of the {term}`primary key` to use for their communication partner. Traditionally, this is done by manually verifying the *{term}`fingerprint`* of the {term}`primary key`. Once the {term}`validity` of the {term}`primary key` is confirmed, the {term}`validity` of the remaining {term}`components` can be automatically assessed by the user's OpenPGP software. Generally, {term}`components` are {term}`valid` parts of a {term}`certificate` if there is a statement signed by the {term}`certificate`'s {term}`primary key` endorsing this {term}`validity`. -(metadata_in_certificates)= +(metadata-in-certificates)= ## Metadata in certificates {term}`OpenPGP certificates`, their {term}`component keys`, and {term}`identities` possess {term}`metadata` that is not stored within the {term}`components` 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` (like *signing* or *encryption*) and {term}`expiration times`, 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` {term}`metadata`** is defined either through a {term}`direct key signature` on the {term}`primary key` (preferred in OpenPGP version 6), or by associating the {term}`metadata` with the [Primary User ID](primary_user_id). +- **{term}`Primary key` {term}`metadata`** is defined either through a {term}`direct key signature` on the {term}`primary key` (preferred in OpenPGP version 6), or by associating the {term}`metadata` with the [Primary User ID](primary-user-id). -- **{term}`Subkey` {term}`metadata`** is defined within the [subkey binding signature](binding_subkeys) that links the {term}`subkey` to the {term}`certificate`. +- **{term}`Subkey` {term}`metadata`** is defined within the [subkey binding signature](binding-subkeys) that links the {term}`subkey` to the {term}`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`. +- **{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`. It is crucial to note that the {term}`components` of an {term}`OpenPGP certificate` remain static after their creation. The use of {term}`signatures` to store {term}`metadata` allows for subsequent modifications without altering the original {term}`component`. For instance, a {term}`certificate holder` can update the {term}`expiration time` of a {term}`component` by issuing a new, superseding {term}`signature`. @@ -211,7 +211,7 @@ It is crucial to note that the {term}`components` of an {term}`OpenPG {term}`Metadata` can be associated with the {term}`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` are not the only means by which {term}` For more detailed information on {term}`revoking` specific {term}`components` of a {term}`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` have been a cornerstone of the OpenPGP ecosystem. The original PGP designers, starting with Phil Zimmermann, advocated for decentralized {term}`trust models` 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` his OpenPGP software associates with Alice matches the one Alice uses. In essence, both users must have a {term}`certificate` for Alice with an identical {term}`fingerprint`. In OpenPGP version 6, manual {term}`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`, see {ref}`third_party_cert`. +For more on third-party {term}`certifications`, see {ref}`third-party-cert`. diff --git a/book/source/compression.md b/book/source/compression.md index 7346c1e..b7822d6 100644 --- a/book/source/compression.md +++ b/book/source/compression.md @@ -22,7 +22,7 @@ The series of OpenPGP packets inside the Compressed Data packet can be handled l ## Typical usage -Compressed data packets are often used inside [encrypted data packets](/encryption), or wrapping the data of an [inline-signed message](inline_signature). +Compressed data packets are often used inside [encrypted data packets](/encryption), or wrapping the data of an [inline-signed message](inline-signature). --- diff --git a/book/source/cryptography.md b/book/source/cryptography.md index f2b1e3b..4ab4cdc 100644 --- a/book/source/cryptography.md +++ b/book/source/cryptography.md @@ -15,7 +15,7 @@ Cryptographic hash functions have two important properties: - [**Pre-image resistance**](https://en.wikipedia.org/wiki/Preimage_attack): Given a hash digest, it should be very difficult to determine any data that matches this hash digest (including, but not limited to, the original data the hash represents). This property embodies the concept of a [one-way function](https://en.wikipedia.org/wiki/One-way_function) – a calculation that is easy to perform, but very hard to reverse. - [**Collision resistance**](https://en.wikipedia.org/wiki/Collision_resistance): It should be very difficult to find two distinct pieces of data that map to the same hash digest. -(message_authentication_codes)= +(message-authentication-codes)= ## Message authentication codes A [message authentication code](https://en.wikipedia.org/wiki/Message_authentication_code) (MAC), also known as an {term}`authentication tag`, is a small piece of information used to verify the integrity and authenticity of a message. @@ -31,9 +31,9 @@ One application of KDFs is to generate symmetric key material from a password by A notable KDF for the OpenPGP specification is the [HKDF](https://en.wikipedia.org/wiki/HKDF), which is a key derivation function based on the HMAC. -For detailed information on KDFs and their role in the OpenPGP protocol, see the [encrypted secrets](encrypted_secrets) chapter and the [SEIPDv2](SEIPDv2) section of the encryption chapter. +For detailed information on KDFs and their role in the OpenPGP protocol, see the [encrypted secrets](encrypted-secrets) chapter and the [SEIPDv2](SEIPDv2) section of the encryption chapter. -(symmetric_key_cryptography)= +(symmetric-key-cryptography)= ## Symmetric-key cryptography [Symmetric-key cryptography](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) uses the same cryptographic key for both encryption and decryption, unlike asymmetric cryptography where a pair of keys is used: a public key for encryption and a corresponding private key for decryption. Symmetric-key cryptographic systems support *encryption/decryption* operations. @@ -55,7 +55,7 @@ Symmetric-key cryptography has major benefits: It is much faster than public-key However, exchanging the required shared secret is a problem that needs to be solved separately. -[Hybrid cryptosystems](hybrid_cryptosystems) combine the advantages of symmetric-key cryptography with a separate mechanism for managing the shared secret, using public-key cryptography. +[Hybrid cryptosystems](hybrid-cryptosystems) combine the advantages of symmetric-key cryptography with a separate mechanism for managing the shared secret, using public-key cryptography. ### Symmetric-key cryptography in OpenPGP @@ -81,14 +81,14 @@ By addressing the malleability problem, AEAD also counters a variation of the EF [^efail]: A variation of the [EFAIL](https://en.wikipedia.org/wiki/EFAIL) attack can be prevented by both the MDC and AEAD mechanisms. Also see ["No, PGP is not broken, not even with the Efail vulnerabilities,"](https://proton.me/blog/pgp-vulnerability-efail) especially the section "Malleability Gadget Exfiltration Channel Attack." -(public_key_asymmetric_cryptography)= +(public-key-asymmetric-cryptography)= ## Public-key (asymmetric) cryptography [Public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography) uses asymmetric pairs of related keys. Each pair consists of a public key and a private key. These systems support encryption, decryption, and digital signature operations. Unlike symmetric cryptography, participants are not required to pre-arrange a shared secret. In public-key cryptography, the public key material is shared openly for certain cryptographic operations, such as encryption and signature verification, while the private key, kept confidential, is used for operations like decryption and signature creation. -(asymmetric_key_pair)= +(asymmetric-key-pair)= ### Asymmetric cryptographic key pairs Throughout this document, we will frequently reference asymmetric cryptographic key pairs: @@ -134,7 +134,7 @@ In OpenPGP, digital signatures have diverse applications, extending beyond mere - [Data signatures](signing_data) - [Signatures on components](/signing_components) -(hybrid_cryptosystems)= +(hybrid-cryptosystems)= ## Hybrid cryptosystems [Hybrid cryptosystems](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) combine the use of {term}`symmetric` and {term}`asymmetric (public-key)` cryptography to capitalize on the strengths of each, namely {term}`symmetric cryptography`'s speed and efficiency and {term}`public-key cryptography`'s mechanism for secure key exchange. diff --git a/book/source/decryption.md b/book/source/decryption.md index 3316d1b..7286c31 100644 --- a/book/source/decryption.md +++ b/book/source/decryption.md @@ -14,7 +14,7 @@ Typically, all \*ESK packets leading a SEIPD packet contain the same *session ke ```{note} -Anonymous-recipient PKESK packets contain a recipient-Key ID of `0`, so if no suitable non-anonymous PKESK was found, any anonymous PKESKs are tried with any available decryption (sub-) keys (see [](decryption_anonymous_recipient)). +Anonymous-recipient PKESK packets contain a recipient-Key ID of `0`, so if no suitable non-anonymous PKESK was found, any anonymous PKESKs are tried with any available decryption (sub-) keys (see [](decryption-anonymous-recipient)). ``` If no suitable PKESK packets were found, SKESK packets are tried next, meaning the user is typically prompted to enter a decryption passphrase. @@ -64,7 +64,7 @@ When the direct method is used, the symmetric cipher algorithm ID of the SKESK p Otherwise, the cipher algorithm ID to decrypt the SEIPD packet was prefixed to the decrypted session key. -Sanitizing this algorithm ID of the decrypted session key acts as a very early quick check to verify that the used passphrase was correct. For further validation of the session key, see [](decryption_seipd_quick_check). +Sanitizing this algorithm ID of the decrypted session key acts as a very early quick check to verify that the used passphrase was correct. For further validation of the session key, see [](decryption-seipd-quick-check). ### SKESK v6 @@ -92,7 +92,7 @@ More common than SKESK packets are PKESK packets which are used to protect the s ### PKESK v3 With version 3 PKESKs, the recipient's secret encryption (sub-) key is directly used to decrypt the encrypted *session key*. -The Key ID of the subkey to be used is recorded in the PKESKs key-id field. A value of `0` indicates an anonymous recipient (see [](decryption_anonymous_recipient)). +The Key ID of the subkey to be used is recorded in the PKESKs key-id field. A value of `0` indicates an anonymous recipient (see [](decryption-anonymous-recipient)). To detect, which symmetric cipher is used to decrypt the SEIPDv1 packet later on, each public key algorithm uses a slightly different encoding to unpack the symmetric algorithm tag from the decrypted session key. See the respective sections[^rsa-spec] [^elgamal-spec] [^ecdh-spec] [^x25519-spec] [^x448-spec] of the standard. Typically, the cipher algorithm ID is prefixed to the actual session key. diff --git a/book/source/encryption.md b/book/source/encryption.md index 0761e9f..2bbdba6 100644 --- a/book/source/encryption.md +++ b/book/source/encryption.md @@ -54,7 +54,7 @@ SEIPD packets are used in combination with two mechanisms that store *session ke - [Public-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio) (PKESK) packets and - [Symmetric-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#skesk) (SKESK) packets. -The typical combination of mechanisms for encryption in OpenPGP is a [hybrid cryptosystem](hybrid_cryptosystems), consisting of one or more [Public-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio) packets (PKESK), followed by a [Symmetrically Encrypted Integrity Protected Data](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetrically-encrypted-int) (SEIPD) packet. +The typical combination of mechanisms for encryption in OpenPGP is a [hybrid cryptosystem](hybrid-cryptosystems), consisting of one or more [Public-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio) packets (PKESK), followed by a [Symmetrically Encrypted Integrity Protected Data](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetrically-encrypted-int) (SEIPD) packet. In this combination, an asymmetric cryptographic mechanism is used to protect a *session key* inside PKESK packets. The *session key*, in turn, is used to protect the plaintext using symmetric-key encryption in a SEIPD packet. @@ -123,7 +123,7 @@ When communicating with a mix of recipients, some of whose OpenPGP software only With SEIPDv1, the session key is directly used as message key to encrypt the payload ``` -(SEIPDv2)= +(seipdv2)= ### v2 SEIPD, based on AEAD The [version 2 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#version-two-seipd) mechanism was introduced in OpenPGP version 6. Consequently, it can only be used for encryption when all recipients explicitly announce support for it using a *Feature* signature subpacket. diff --git a/book/source/glossary.md b/book/source/glossary.md index d75c97a..f48e688 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -17,10 +17,10 @@ AEAD Algorithm Algorithm Preferences The preferences for {term}`hash algorithms`, {term}`compression algorithms`, {term}`symmetric algorithms` and {term}`AEAD algorithms` are set using {term}`direct key signatures` or {term}`primary User ID` {term}`binding signatures`. - See [](change_algorithm_preferences). + See [](change-algorithm-preferences). Asymmetric Cryptography - Asymmetric cryptography is used in OpenPGP. For a more detailed discussion see [](public_key_asymmetric_cryptography). + Asymmetric cryptography is used in OpenPGP. For a more detailed discussion see [](public-key-asymmetric-cryptography). Authenticated Encryption With Associated Data Short AEAD, refers to an encryption scheme that ensures confidentiality of a message. Additionally, additional data, which is not confidential, may be associated with the message. @@ -32,7 +32,7 @@ Authentication The term "authentication" here is semantically different from the one used in {term}`Authentication Key Flag`. Authentication Key Flag - A {term}`Key Flag`, which indicates that a {term}`Component Key` can be used to confirm control over {term}`private key material` against a remote system. The term "authentication" here is semantically different from {term}`Authentication`. See [](capabilities_key_flags). + A {term}`Key Flag`, which indicates that a {term}`Component Key` can be used to confirm control over {term}`private key material` against a remote system. The term "authentication" here is semantically different from {term}`Authentication`. See [](capabilities-key-flags). Authentication Tag See {term}`Message Authentication Code`. @@ -49,18 +49,18 @@ Binary Signature Binding The process of creating a {term}`Binding Signature` for a {term}`Component`, or the resulting {term}`Binding Signature`. - See {ref}`binding_sigs` for more. + See {ref}`binding-sigs` for more. Binding Signature A {term}`self-signature` on a {term}`component` which associates that {term}`component` to the issuing {term}`component key` in a {term}`certificate`. - See {ref}`binding_sigs` for more. + See {ref}`binding-sigs` for more. CA See {term}`Certification Authority`. Capability - The operations an {term}`OpenPGP Component Key` can perform. See [](capabilities_key_flags). + The operations an {term}`OpenPGP Component Key` can perform. See [](capabilities-key-flags). Certificate See {term}`OpenPGP Certificate` @@ -74,13 +74,13 @@ Certificate Holder Certification A certification, in OpenPGP, is a signature that makes a statement about an {term}`identity` in a {term}`certificate`, or an entire {term}`certificate`. - Most commonly, the term is applied to "[third-party certifications](third_party_cert)," in which an external actor indicates that they have {term}`validated` the link between an {term}`identity` and a {term}`certificate`. However, the term is also used for [self-signatures that bind identity components](bind_ident) to a {term}`certificate`. + Most commonly, the term is applied to "[third-party certifications](third-party-cert)," in which an external actor indicates that they have {term}`validated` the link between an {term}`identity` and a {term}`certificate`. However, the term is also used for [self-signatures that bind identity components](bind-ident) to a {term}`certificate`. Certification Authority Also known as [Certificate authority](https://en.wikipedia.org/wiki/Certificate_authority), this is an entity that handles digital certificates, especially by signing or issuing them. Certification Key Flag - A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for issuing third-party {term}`certifications`. See [](capabilities_key_flags). + A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for issuing third-party {term}`certifications`. See [](capabilities-key-flags). Certification Revocation Signature Packet An {term}`OpenPGP Signature Packet` to {term}`revoke` an earlier {term}`self-certification` of a {term}`User ID`. @@ -122,7 +122,7 @@ Creator See {term}`Issuer`. Criticality Flag - A flag on {term}`Subpacket`s, that defines their criticality, which is used for validation. See [](criticality_of_subpackets). + A flag on {term}`Subpacket`s, that defines their criticality, which is used for validation. See [](criticality-of-subpackets). Cryptographic Key A {term}`symmetric` or {term}`asymmetric` cryptographic key is used for signing and encryption operations. See [](cryptography). @@ -151,10 +151,10 @@ Delegation This kind of delegation involves {term}`certifications` that include the {term}`trust signature` subpacket. Detached Signature - A {term}`Data Signature` which exists as a separate file to the file it was created for. See [](forms_of_openpgp_data_signatures). + A {term}`Data Signature` which exists as a separate file to the file it was created for. See [](forms-of-openpgp-data-signatures). Direct Key Signature - A {term}`Signature` that sets preferences and advertises {term}`features` applicable to an entire {term}`Certificate`. See [](direct_key_signature). + A {term}`Signature` that sets preferences and advertises {term}`features` applicable to an entire {term}`Certificate`. See [](direct-key-signature). Embedded Signature Subpacket An {term}`OpenPGP Signature Subpacket` which contains a complete {term}`OpenPGP Signature Packet`. @@ -162,7 +162,7 @@ Embedded Signature Subpacket See [RFC 5.2.3.34](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-embedded-signature) Encryption Key Flag - A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for encrypting data. See [](capabilities_key_flags). + A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for encrypting data. See [](capabilities-key-flags). Expiration A mechanism by which a {term}`Component` is invalidated due to the {term}`Expiration Time` of its {term}`binding signature` being older than the {term}`Reference Time` by which it is validated. @@ -173,7 +173,7 @@ Expiration Time Features Subpacket A {term}`OpenPGP Signature Subpacket`, which denotes advanced OpenPGP features an {term}`implementation` supports. - For an in-depth view on these {term}`subpackets` see [](zooming_in_dks). + For an in-depth view on these {term}`subpackets` see [](zooming-in-dks). See [RFC 5.2.3.32](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-features) @@ -183,7 +183,7 @@ Fingerprint Hard Revocation A {term}`Revocation Signature Packet` for a {term}`Certification` or a {term}`Component Key`, which either includes a {term}`Reason For Revocation Subpacket` with a {term}`Revocation Code`, that signifies the target being compromised (e.g., `0` or `2`), or has no {term}`Reason For Revocation Subpacket` at all. - See [](hard_vs_soft_revocations). + See [](hard-vs-soft-revocations). See [RFC 5.2.3.31](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation). @@ -197,13 +197,13 @@ Hash Function A function used to map data of arbitrary size to fixed-size values (see {term}`Hash Digest`). Hashed Area - An area in an {term}`OpenPGP Signature Packet` containing {term}`OpenPGP Signature Subpacket`s, that is covered by the {term}`Hash Digest` a {term}`Cryptographic Signature` is created for. See [](hashed_and_unhashed_signature_subpackets). + An area in an {term}`OpenPGP Signature Packet` containing {term}`OpenPGP Signature Subpacket`s, that is covered by the {term}`Hash Digest` a {term}`Cryptographic Signature` is created for. See [](hashed-and-unhashed-signature-subpackets). Hashed Subpacket An {term}`OpenPGP Signature Subpacket` residing in the {term}`Hashed Area` of an {term}`OpenPGP Signature Packet`. Hybrid Cryptosystem - A cryptographic system that employs both {term}`Asymmetric Cryptography` and {term}`Symmetric Cryptography`. See [](hybrid_cryptosystems). + A cryptographic system that employs both {term}`Asymmetric Cryptography` and {term}`Symmetric Cryptography`. See [](hybrid-cryptosystems). Identity An identity of a {term}`Certificate Holder`. It is represented by an {term}`Identity Component`, which may be certified using {term}`third-party identity certifications`, or by a {term}`Notation`. @@ -215,7 +215,7 @@ Identity Claim A {term}`Certificate Holder` may use {term}`Identity Components` or {term}`Notations` to state a claim about their {term}`Identity`. Identity Component - Part of an {term}`OpenPGP Certificate`, that is used to associate data about the {term}`Certificate Holder` with it. See [](identity_components) for further details. + Part of an {term}`OpenPGP Certificate`, that is used to associate data about the {term}`Certificate Holder` with it. See [](identity-components) for further details. Identity Verification A process by which the {term}`Identity Claim` of a {term}`Certificate Holder` is verified. See also {term}`Signature Verification`. @@ -224,7 +224,7 @@ Initial Introducer An {term}`OpenPGP Certificate` explicitly {term}`delegated` to from a {term}`Trust Anchor`. Inline Signature - A {term}`Data Signature` which exists encapsulated alongside the data it was created for in an OpenPGP container. See [](forms_of_openpgp_data_signatures). + A {term}`Data Signature` which exists encapsulated alongside the data it was created for in an OpenPGP container. See [](forms-of-openpgp-data-signatures). Issuer An entity, that created an {term}`OpenPGP Signature Packet` using an {term}`Transferable Secret Key`. @@ -246,7 +246,7 @@ Key - asymmetric private key - {term}`Symmetric Secret Key` - Additionally, in OpenPGP, asymmetric cryptographic keys are used on [three different layers](layers_of_keys_in_openpgp) of abstraction: + Additionally, in OpenPGP, asymmetric cryptographic keys are used on [three different layers](layers-of-keys-in-openpgp) of abstraction: - cryptographic key - OpenPGP component key @@ -258,7 +258,7 @@ Key Expiration Time Subpacket See [RFC 5.2.3.13](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-expiration-time) Key Flag - A preference encoded in an {term}`OpenPGP Signature Subpacket`, that defines the {term}`Capability` a {term}`OpenPGP Component Key` has. See [](signature_subpackets). + A preference encoded in an {term}`OpenPGP Signature Subpacket`, that defines the {term}`Capability` a {term}`OpenPGP Component Key` has. See [](signature-subpackets). Key Holder See {term}`Certificate Holder`. @@ -295,19 +295,19 @@ Master Key See {term}`OpenPGP Primary Key`. Message Authentication Code - A piece of information used for integrity and {term}`authenticity` verification of a message. See [](message_authentication_codes). + A piece of information used for integrity and {term}`authenticity` verification of a message. See [](message-authentication-codes). Meta-Introducer An {term}`OpenPGP Certificate` with a {term}`Trust Depth` greater than one. Metadata - Data related to preferences of an {term}`OpenPGP Certificate` or its {term}`Certificate Holder`, that can be found in {term}`signature` {term}`packets`. See [](metadata_in_certificates). + Data related to preferences of an {term}`OpenPGP Certificate` or its {term}`Certificate Holder`, that can be found in {term}`signature` {term}`packets`. See [](metadata-in-certificates). Notation A mechanism for a {term}`Certificate Holder` to provide user-defined data using a {term}`Notation Signature Subpacket`. Notation Signature Subpacket - An {term}`OpenPGP Signature Subpacket` which is used to add user-defined data to a {term}`Certificate`. See [](notation_signature_subpackets). + An {term}`OpenPGP Signature Subpacket` which is used to add user-defined data to a {term}`Certificate`. See [](notation-signature-subpackets). Notation Tag Part of a {term}`Notation` name. @@ -319,7 +319,7 @@ OpenPGP Certificate An OpenPGP certificate contains public key material, identity claims and third party certifications (but no private key material) OpenPGP Component Key - An {term}`OpenPGP Primary Key` or {term}`OpenPGP Subkey`. For an in-depth discussion see [](component_keys). + An {term}`OpenPGP Primary Key` or {term}`OpenPGP Subkey`. For an in-depth discussion see [](component-keys). OpenPGP Fingerprint An OpenPGP Fingerprint is a shorthand representation of an {term}`OpenPGP Component Key`. Fingerprints effectively act as unique identifiers. See [](fingerprint). @@ -342,7 +342,7 @@ OpenPGP Private Key See {term}`Transferable Secret Key`. OpenPGP Primary Key - An {term}`OpenPGP Component Key` that is used in the primary key role of an {term}`OpenPGP Certificate`. For a more detailed discussion, see [](primary_key). + An {term}`OpenPGP Component Key` that is used in the primary key role of an {term}`OpenPGP Certificate`. For a more detailed discussion, see [](primary-key). OpenPGP Signature See {term}`OpenPGP Signature Packet`. @@ -351,13 +351,13 @@ OpenPGP Signature Packet A {term}`packet` that contains a raw {term}`cryptographic signature`, a {term}`Signature Type ID` and additional {term}`metadata`. See [](/signatures). Basic concepts are introduced in [](/signatures) and more detailed use-cases are explained in [](/signing_data) and [](/signing_components). OpenPGP Signature Subpacket - A data structure in a {term}`Signature Packet`, that describes {term}`metadata` and preferences. See [](signature_subpackets). + A data structure in a {term}`Signature Packet`, that describes {term}`metadata` and preferences. See [](signature-subpackets). OpenPGP Signature Subpacket Type An {term}`OpenPGP Signature Subpacket` type. OpenPGP Signature Type - The type of an {term}`OpenPGP Signature Packet` is defined by its {term}`Signature Type ID`. See [](signature_types). + The type of an {term}`OpenPGP Signature Packet` is defined by its {term}`Signature Type ID`. See [](signature-types). OpenPGP Signing Subkey An {term}`OpenPGP Subkey` with the {term}`Signing Key Flag`. @@ -383,7 +383,7 @@ Packet Type ID Positive Certification An {term}`OpenPGP Signature Type` with the {term}`Signature Type ID` `0x13`, which is used in {term}`binding signatures` for {term}`User IDs`. This {term}`OpenPGP Signature Type` implies that the {term}`issuer` has done substantial {term}`verification` of the {term}`Identity Claim`. - See [](bind_ident). + See [](bind-ident). Preferred Compression Algorithms Subpacket An {term}`OpenPGP Signature Subpacket Type` which defines the preferred {term}`compression algorithms` for an {term}`OpenPGP Signature Packet`. This defines which {term}`algorithms` the {term}`key holder` prefers to use. @@ -418,12 +418,12 @@ Primary Key Primary Key Binding Signature A {term}`Binding Signature`, which is created by a {term}`OpenPGP Signing Subkey` on the {term}`OpenPGP Primary Key` of an {term}`OpenPGP Certificate` and stored in an {term}`Embedded Signature Subpacket` in the {term}`Binding Signature` for the {term}`OpenPGP Signing Subkey`. - This special case is explained in more detail in [](bind_subkey_sign). + This special case is explained in more detail in [](bind-subkey-sign). Primary User ID A {term}`User ID` which carries the default preferences for {term}`identity components` without preferences. - See [](primary_user_id). + See [](primary-user-id). Primary User ID Subpacket An {term}`OpenPGP Signature Subpacket` used in {term}`User ID self-signatures` which allows to signify whether the {term}`User ID` in question is considered a {term}`Primary User ID`. @@ -435,7 +435,7 @@ Primary User ID Binding Signature This {term}`Binding Signature` may carry {term}`metadata` specific to the {term}`User ID` at hand as well as some applicable to the entire {term}`OpenPGP Certificate`. - See [](self_signature_binding_to_primary_user_id). + See [](self-signature-binding-to-primary-user-id). Private Key See {term}`Transferable Secret Key`. @@ -447,7 +447,7 @@ Public Key See {term}`OpenPGP Public Key`. Public Key Algorithm - An {term}`asymmetric cryptographic` algorithm. See [](public_key_asymmetric_cryptography). + An {term}`asymmetric cryptographic` algorithm. See [](public-key-asymmetric-cryptography). Public Key Cryptography See {term}`Asymmetric Cryptography`. @@ -515,7 +515,7 @@ Session Key Soft Revocation A {term}`Revocation Signature Packet` for a {term}`Certification` or a {term}`Component Key`, which includes a {term}`Reason For Revocation Subpacket` with a {term}`Revocation Code`, that does not signify the target being compromised (e.g., `0` or `2`). - See [](hard_vs_soft_revocations). + See [](hard-vs-soft-revocations). See [RFC 5.2.3.31](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation). @@ -563,7 +563,7 @@ Signing-capable See {term}`Signing Key Flag`. Signing Key Flag - A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for signing data. See [](capabilities_key_flags). + A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for signing data. See [](capabilities-key-flags). Signing Subkey See {term}`OpenPGP Signing Subkey`. @@ -581,7 +581,7 @@ Subkey See {term}`OpenPGP Subkey`. Subkey Binding Signature - A {term}`Self-signature` to associate an {term}`OpenPGP Subkey` with an {term}`OpenPGP Primary Key`. See [](bind_subkey). + A {term}`Self-signature` to associate an {term}`OpenPGP Subkey` with an {term}`OpenPGP Primary Key`. See [](bind-subkey). Subkey Revocation Signature Packet A {term}`Self-signature` to {term}`revoke` an {term}`OpenPGP Subkey` in an {term}`OpenPGP Certificate`. @@ -595,7 +595,7 @@ Subpacket Type See {term}`OpenPGP Signature Subpacket Type`. Symmetric Cryptography - Symmetric cryptography is used in OpenPGP. For a more detailed discussion see [](symmetric_key_cryptography). + Symmetric cryptography is used in OpenPGP. For a more detailed discussion see [](symmetric-key-cryptography). Symmetrically Encrypted Integrity Protected Data Short *SEIPD*, this refers to {term}`Symmetric Cryptography` based encrypted data, which is used in a Symmetrically Encrypted Integrity Protected Data Packet. @@ -609,7 +609,7 @@ Text Signature A {term}`signature packet` with the {term}`Signature Type ID` `0x01`, which is used for textual data. Third-party Identity Certification - {term}`Certification` by third-parties to confirm ownership of an {term}`OpenPGP Certificate` by a {term}`Certificate Holder`. See [](third_party_identity_certifications). + {term}`Certification` by third-parties to confirm ownership of an {term}`OpenPGP Certificate` by a {term}`Certificate Holder`. See [](third-party-identity-certifications). Third-party Signature A {term}`Signature` by a third-party on a {term}`Component` of a {term}`Certificate`. @@ -621,7 +621,7 @@ Trust Amount A numerical value between `0` and `255`, stored in {term}`trust signatures` used for indicating the degree of reliance on the {term}`delegation`. Values less than `120` indicate partial trust, values equal to or greater than `120` indicate complete trust. - See [](trust_amounts). + See [](trust-amounts). See [RFC 5.2.3.21](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) Trust Anchor @@ -630,13 +630,13 @@ Trust Anchor Trust Depth This numerical value is part of a {term}`Trust Signature` and describes the extent of trustworthiness of a {term}`Certification`, that the {term}`signer` assigns to it. - See [](trust_depth_level). + See [](trust-depth-level). Trust Level See {term}`Trust Depth`. Trust Model - A model by which trust between {term}`identities` associated with different {term}`OpenPGP Certificates` is created. See [](third_party_identity_certifications). + A model by which trust between {term}`identities` associated with different {term}`OpenPGP Certificates` is created. See [](third-party-identity-certifications). Trust Root See {term}`Trust Anchor`. @@ -661,16 +661,16 @@ Type ID See {term}`Signature Type ID`. Unhashed Area - An area in a {term}`Signature Packet` containing {term}`Signature Subpacket`s, that is *not* covered by the {term}`Hash Digest` a {term}`Cryptographic Signature` is created for. See [](hashed_and_unhashed_signature_subpackets). + An area in a {term}`Signature Packet` containing {term}`Signature Subpacket`s, that is *not* covered by the {term}`Hash Digest` a {term}`Cryptographic Signature` is created for. See [](hashed-and-unhashed-signature-subpackets). Unhashed Subpacket A {term}`Signature Subpacket` residing in the {term}`Unhashed Area` of a {term}`Signature Packet`. User Attribute - An {term}`Identity Component`, which may hold a single JPEG image. See [](user_attributes). + An {term}`Identity Component`, which may hold a single JPEG image. See [](user-attributes). User ID - An {term}`Identity Component`, which describes an {term}`Identity` of a {term}`Certificate Holder`. See [](user_ids_in_openpgp_certificates). + An {term}`Identity Component`, which describes an {term}`Identity` of a {term}`Certificate Holder`. See [](user-ids-in-openpgp-certificates). User ID Binding Signature A {term}`Binding Signature`, which is created by an {term}`OpenPGP Primary Key` to bind a {term}`User ID` to an {term}`OpenPGP Certificate`. diff --git a/book/source/migration.md b/book/source/migration.md index 6471aaa..5d17ce7 100644 --- a/book/source/migration.md +++ b/book/source/migration.md @@ -28,7 +28,7 @@ Existing OpenPGP v4 keys can simply announce support for SEIPD v2 via a *Feature Senders who can produce this new encryption mode can then opt to use it when encrypting to this recipient. -(migration_s2k)= +(migration-s2k)= ### S2K usage mode AEAD Another good example is the S2K mechanism for secret-key encryption. diff --git a/book/source/openpgp.md b/book/source/openpgp.md index 7208fdd..4063d3b 100644 --- a/book/source/openpgp.md +++ b/book/source/openpgp.md @@ -59,7 +59,7 @@ An extension for Elliptic Curve Cryptography was defined in [RFC 6637](https://w Some implementations explored other non-standardized extensions. Notably, algorithms based on Curve 25519 were tentatively defined in the [rfc4880bis](https://www.ietf.org/archive/id/draft-ietf-openpgp-rfc4880bis-10.html#name-elliptic-curve-cryptography) document. These algorithms are widely used, even though rfc4880bis has never been finalized as a new version of the standard. -(major_implementations)= +(major-implementations)= ### Major implementations of OpenPGP Today, multiple implementations of OpenPGP play important roles: @@ -69,10 +69,10 @@ Today, multiple implementations of OpenPGP play important roles: - Proton Mail, which provides email encryption services for a large number of users, uses and maintains [OpenPGP.js](https://openpgpjs.org/) as well as [GopenPGP](https://gopenpgp.org/), an OpenPGP wrapper library written in golang. - The RPM Package Manager software includes an OpenPGP backend based on [Sequoia PGP](https://sequoia-pgp.org/), a modern OpenPGP implementation written in Rust. The Fedora Linux operating system [uses Sequoia PGP in rpm](https://sequoia-pgp.org/blog/2023/04/27/rpm-sequoia/) since version 38. -(interop_section)= +(interop-section)= ### Interoperability -OpenPGP was standardized in 1997 to encourage development of interoperable implementations. This has already been a success early on, but in recent years, there has been [much development of new implementations](major_implementations). +OpenPGP was standardized in 1997 to encourage development of interoperable implementations. This has already been a success early on, but in recent years, there has been [much development of new implementations](major-implementations). Historically, interoperability has only been tested in an adhoc manner. Since 2019, the Sequoia project is maintaining and operating the ["OpenPGP interoperability test suite"](https://tests.sequoia-pgp.org/), for more rigorous and systematic testing. The test suite has identified numerous [issues](https://gitlab.com/sequoia-pgp/openpgp-interoperability-test-suite#hall-of-fame). diff --git a/book/source/private_keys.md b/book/source/private_keys.md index 8b243d1..456220f 100644 --- a/book/source/private_keys.md +++ b/book/source/private_keys.md @@ -54,7 +54,7 @@ Transferable secret keys are sometimes colloquially referred to as "OpenPGP priv Historically, the concept of TSKs, which combine all elements of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, TSKs are primarily a format for storage and transport; it is generally considered inappropriate as a data structure for use in a private keystore. For further details, see {ref}`key-store-design`. -(encrypted_secrets)= +(encrypted-secrets)= ## Protecting keys with passphrases In the OpenPGP format, private key material can be optionally protected with a [passphrase](https://en.wikipedia.org/wiki/Passphrase). diff --git a/book/source/signatures.md b/book/source/signatures.md index b1d82b7..faa2645 100644 --- a/book/source/signatures.md +++ b/book/source/signatures.md @@ -33,7 +33,7 @@ An "{term}`OpenPGP Signature Packet`" In this document, "{term}`signature`" will refer to {term}`OpenPGP signature packets`. -(signature_types)= +(signature-types)= ## Signature types in OpenPGP The OpenPGP standard defines a set of [Signature types](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), each identified by a numerical *{term}`signature type ID`*. {term}`Signature types` define the purpose of a {term}`signature packet` and how it should be interpreted. @@ -64,7 +64,7 @@ For more detail about specific {term}`types of signatures` is a composite data structure, which combines: - **{term}`Signature type ID`**: specifies the {term}`signature`'s intended meaning, as detailed above -- **{term}`Metadata`**: varies based, in part, on the {term}`signature type ID`; mostly encoded as "{term}`subpackets`" (see {ref}`signature_subpackets`) +- **{term}`Metadata`**: varies based, in part, on the {term}`signature type ID`; mostly encoded as "{term}`subpackets`" (see {ref}`signature-subpackets`) - **Raw {term}`cryptographic signature`** ```{figure} plain_svg/OpenPGP_Signature_packet_2.svg @@ -76,8 +76,8 @@ Structure and context of an {term}`OpenPGP signature packet` The input data packets differ between specific signature types. Also see {numref}`fig-signature-types`. For example: -- for a [*binary data signature*](data_signature_types), the input data packet is a *literal data packet*, while -- for a [*subkey binding signature*](bind_subkey), the input data packets consist of a primary and a subkey packet. +- for a [*binary data signature*](data-signature-types), the input data packet is a *literal data packet*, while +- for a [*subkey binding signature*](bind-subkey), the input data packets consist of a primary and a subkey packet. ### Creating an OpenPGP signature packet @@ -122,7 +122,7 @@ After calculating the {term}`hash digest` from the input data, a {term}`signatur Verifying a {term}`signature` in OpenPGP ``` -(signature_subpackets)= +(signature-subpackets)= ## Signature subpackets In the OpenPGP protocol, {term}`signature subpackets` enhance the expressiveness of a {term}`signature` beyond what is conveyed by just the bare {term}`cryptographic signature` and the {term}`signature type ID`. These {term}`subpackets`, introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440), are essential for embedding additional {term}`metadata` within {term}`signature packets`. @@ -134,7 +134,7 @@ They are formatted as key-value pairs, where the keys are defined as [subpacket - The [*issuer fingerprint*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#issuer-fingerprint-subpacket) {term}`subpacket` encodes the {term}`fingerprint` of the {term}`component key` that issued the {term}`signature`. - The [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) {term}`subpacket` defines the {term}`capabilities` that are assigned to a {term}`component key` within a {term}`certificate`. -(hashed_and_unhashed_signature_subpackets)= +(hashed-and-unhashed-signature-subpackets)= ### Hashed and unhashed signature subpackets {term}`Signature subpackets` within OpenPGP can reside in one of two distinct areas of a {term}`signature packet`, each serving a different purpose. @@ -146,7 +146,7 @@ The majority of {term}`signature subpackets` are st For detailed information and specifications, refer to [Hashed vs. Unhashed Subpackets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hashed-vs-unhashed-subpacke) in the OpenPGP {term}`RFC`. -(criticality_of_subpackets)= +(criticality-of-subpackets)= ### Criticality of subpackets In the OpenPGP protocol, each {term}`signature subpacket` can be marked with a *{term}`criticality flag`*. This flag plays a pivotal role in the interpretation and {term}`validation` of the {term}`signature`. When set, it instructs any receiving {term}`implementation` encountering an unrecognized {term}`subpacket type` to treat this as a significant error and to {term}`invalidate` the {term}`signature`. diff --git a/book/source/signing_components.md b/book/source/signing_components.md index ada0107..439b83b 100644 --- a/book/source/signing_components.md +++ b/book/source/signing_components.md @@ -66,14 +66,14 @@ In another instance: - *When issued as a {term}`self-signature`*, a [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) sets {term}`preferences` and advertises {term}`features` applicable to the entire {term}`certificate`. - *When issued by a {term}`third party`*, especially when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) {term}`subpacket`, a similar {term}`direct key signature` {term}`delegates` trust to the signed {term}`certificate`. This may designate the signed {term}`certificate` as a {term}`trust anchor` within the {term}`issuer`'s {term}`Web of Trust`. -(binding_sigs)= +(binding-sigs)= ## Self-signatures in certificate formation and management {term}`Self-signatures` play a crucial role in forming and managing the structure of {term}`OpenPGP certificates`. These act as *{term}`binding signatures`*, joining {term}`components` and embedding {term}`metadata`. Internally, an {term}`OpenPGP certificate` is essentially a series of {term}`packets` strung sequentially. When a {term}`certificate` is stored in a file format known as a [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-transferable-public-keys), {term}`packets` can be easily added or removed. -To safeguard against unauthorized additions or alterations of {term}`components`, OpenPGP uses {term}`cryptographic signatures`. These validate that all {term}`components`, such as {term}`subkeys` or [identity components](identity_components), were linked to the {term}`OpenPGP certificate` by its {term}`owner`, using the {term}`primary key`. While anyone can still store unrelated elements to a {term}`certificate` dataset, {term}`OpenPGP implementations` will reject them if they lack a {term}`valid` cryptographic connection with the {term}`certificate`. +To safeguard against unauthorized additions or alterations of {term}`components`, OpenPGP uses {term}`cryptographic signatures`. These validate that all {term}`components`, such as {term}`subkeys` or [identity components](identity-components), were linked to the {term}`OpenPGP certificate` by its {term}`owner`, using the {term}`primary key`. While anyone can still store unrelated elements to a {term}`certificate` dataset, {term}`OpenPGP implementations` will reject them if they lack a {term}`valid` cryptographic connection with the {term}`certificate`. ```{note} Conversely, omissions of {term}`packets` by third parties can easily occur when handling an {term}`OpenPGP certificate` dataset. This could pose a challenge, for example, when an attacker deliberately omits {term}`revocation` {term}`packets`. Without access to an alternative, complete {term}`certificate` source, recipients might not detect these omissions. @@ -81,17 +81,17 @@ Conversely, omissions of {term}`packets` by third parties can easily occ However, there are legitimate instances in which third parties add "unbound" {term}`packets` (i.e., not signed by the {term}`certificate`'s {term}`owner`) to a {term}`certificate`: -- [Third-party certifications](third_party_cert) are often stored within the {term}`packet` data of the {term}`certificate` to which they are related. This is a standard practice that provides convenience for users by allowing easy access to all relevant {term}`certifications`. (See {ref}`cert-flooding` for discussion of a related pitfall.) -- {term}`OpenPGP software` may locally add [unbound identity data](unbound_user_ids) to a {term}`certificate`. +- [Third-party certifications](third-party-cert) are often stored within the {term}`packet` data of the {term}`certificate` to which they are related. This is a standard practice that provides convenience for users by allowing easy access to all relevant {term}`certifications`. (See {ref}`cert-flooding` for discussion of a related pitfall.) +- {term}`OpenPGP software` may locally add [unbound identity data](unbound-user-ids) to a {term}`certificate`. -(bind_subkey)= +(bind-subkey)= ### Binding subkeys to a certificate {term}`Subkeys` are linked to {term}`OpenPGP certificates` via a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-subkey-binding) ({term}`type ID` `0x18`). This {term}`signature type` indicates the association of the {term}`primary key` with the {term}`subkey`. A {term}`subkey binding signature` binds a {term}`subkey` to a {term}`primary key`, and it embeds {term}`metadata` into the {term}`signature packet`. Once generated, the {term}`subkey binding signature` {term}`packet` is stored in the {term}`certificate` directly after the {term}`subkey` it binds. -{term}`Subkeys` designated for signing purposes, identified by the *{term}`signing`* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags), represent a unique category and are handled differently. See {numref}`bind_subkey_sign`. +{term}`Subkeys` designated for signing purposes, identified by the *{term}`signing`* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags), represent a unique category and are handled differently. See {numref}`bind-subkey-sign`. ```{figure} plain_svg/subkey_binding_signature.svg :name: fig-subkey-binding-signature @@ -108,7 +108,7 @@ The {term}`validity` of a {term}`subkey` is intrinsi Legally, a {term}`subkey` may not have a specified {term}`expiration time`. In such cases, its {term}`expiration` aligns implicitly with that of the {term}`primary key`. Additionally, the {term}`creation time` of a {term}`subkey` must always be more recent than that of the {term}`primary key`. ``` -(bind_subkey_sign)= +(bind-subkey-sign)= ### Special case: Binding signing subkeys {term}`Binding` {term}`subkeys` that possess the *{term}`signing`* {term}`key flag` to a {term}`certificate` represents a unique scenario. While similar to the {term}`binding process` of other {term}`subkeys`, there is an additional, critical requirement: mutual association. @@ -131,7 +131,7 @@ Linking an {term}`OpenPGP signing subkey` to the {term}`primary key` signifies the mutuality of the {term}`subkey`'s association with the {term}`primary key` and is embedded as {term}`subpacket` data within the {term}`subkey binding signature`, reinforcing the {term}`authenticity` of the {term}`binding`. -(bind_ident)= +(bind-ident)= ### Binding identities to a certificate {term}`Self-signatures` also play a vital role in {term}`binding` {term}`identity components`, such as {term}`User IDs` or {term}`User Attributes`, to an {term}`OpenPGP certificate`. @@ -168,12 +168,12 @@ The types of {term}`metadata` typically associated with the {term}`certificate` - {term}`algorithm preferences` signaling -(direct_key_signature)= +(direct-key-signature)= #### Direct key signature A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) serves as the [preferred mechanism](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-9) in OpenPGP v6 for defining {term}`metadata` for the entire {term}`certificate`, by associating it with the {term}`primary key`. -(self_signature_binding_to_primary_user_id)= +(self-signature-binding-to-primary-user-id)= #### Self-signature binding to primary User ID In OpenPGP v4, another mechanism was often used for {term}`metadata` management: integrating global {term}`certificate` {term}`metadata` within a {term}`User ID binding signature`. This is specifically evident in the {term}`binding signature` of the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id) of the {term}`OpenPGP certificate`. @@ -209,7 +209,7 @@ Research, under what circumstances revocations revoke individual signatures, and Note: {term}`certification signatures` [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-revocable). -(hard_vs_soft_revocations)= +(hard-vs-soft-revocations)= #### Hard vs soft revocations {term}`Revocation signatures` often include a [*Reason for Revocation* subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation), with a code specifying *why* the {term}`revocation` was issued. This code determines whether the {term}`revocation` is considered *soft* or *hard*. @@ -221,7 +221,7 @@ Note: {term}`certification signatures` [can be made irrevocable]( A {term}`revocation signature packet` lacking a {term}`Reason for Revocation subpacket` is interpreted as a {term}`hard revocation`. ``` -(third_party_cert)= +(third-party-cert)= ## Authentication and delegation in third-party signatures {term}`Third-party signatures` in OpenPGP primarily encode {term}`authentication` statements for {term}`identities` and {term}`delegate` trust decisions. These {term}`signatures` can be manually inspected or processed as machine-readable artifacts by {term}`OpenPGP software`, which evaluates the {term}`authenticity` of {term}`certificates` based on user-specified {term}`trust anchors`. @@ -244,7 +244,7 @@ OpenPGP uses [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-open - {term}`identity certification signatures` ({term}`type ID` `0x10` - `0x13`) - [direct key signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) ({term}`type ID` `0x1F`) -(trust_depth_level)= +(trust-depth-level)= #### Trust depth/level The "{term}`trust depth`" (or {term}`level`) in OpenPGP signifies the extent of transitive {term}`delegation` within the {term}`authentication` process. It determines how far a {term}`delegation` can be extended from the original {term}`trusted introducer` to subsequent intermediaries. Essentially, a {term}`certificate` with a {term}`trust depth` of more than one acts as a "{term}`meta-introducer`," facilitating {term}`authentication` decisions across multiple levels in the network. @@ -255,14 +255,14 @@ However, when the {term}`trust depth` is set higher, it implies a chain of {term This allows for a more extensive network of trusted {term}`certifications`, enabling a broader and more interconnected {term}`Web of Trust`. -(trust_amounts)= +(trust-amounts)= #### Trust amounts The "{term}`trust amount`," with a numerical value ranging from `0` to `255`, quantifies the degree of reliance on a {term}`delegation`. A higher value indicates greater degree of reliance. This quantification aids {term}`OpenPGP software` in determining an aggregate amount of reliance, based on combined {term}`certifications` from multiple {term}`trusted introducers`. -(limiting_delegation_scope)= +(limiting-delegation-scope)= #### Limiting delegation scope When using *{term}`trust signature`* {term}`subpackets`, a {term}`delegation` can be limited to {term}`identities` that match a [*regular expression*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#regex-subpacket). diff --git a/book/source/signing_data.md b/book/source/signing_data.md index a4c5943..2c3955d 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -16,10 +16,10 @@ it does not automatically signal if the expected party indeed controls the {term Note that {term}`data signatures` are distinct from [](/signing_components), which are used to form and maintain {term}`certificates`, as well as to {term}`certify` {term}`identities` on {term}`certificates`. -(data_signature_types)= +(data-signature-types)= ## Signature types -{term}`OpenPGP data signatures` use one of two [signature types](signature_types): +{term}`OpenPGP data signatures` use one of two [signature types](signature-types): - [**Binary signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-binary) ({term}`type ID` `0x00`): This is the standard {term}`signature type` for binary data and is typically used for files or data streams. {term}`Binary signatures` are calculated over the data without any modifications or transformations. - [**Text signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-of-a-canonical-te) ({term}`type ID` `0x01`): Used for textual data, such as email bodies. When calculating a {term}`text signature`, the data is first normalized by converting line endings into a canonical form (``). This approach mitigates issues caused by platform-specific text encodings. This is especially important for detached and {term}`cleartext signatures`, where the message file might undergo re-encoding between the creation and {term}`verification` of the {term}`signature`. @@ -28,7 +28,7 @@ Note that {term}`data signatures` are distinct from [](/signing_ {term}`Data signature packets` manifest in three distinct forms, which will be detailed in the subsequent section. -(forms_of_openpgp_data_signatures)= +(forms-of-openpgp-data-signatures)= ## Forms of OpenPGP data signatures {term}`OpenPGP data signatures` can be applied in three distinct forms[^sign-modes-gpg]: @@ -45,7 +45,7 @@ A {term}`detached signature` is produced by calculating an {term}`OpenPGP signat This {term}`signature` format is especially useful for signing software releases and other files where it is imperative that the content remains unaltered during the signing process. -(inline_signature)= +(inline-signature)= ### Inline signatures An {term}`inline signature` joins the signed data and its corresponding {term}`data signature` into a single {term}`OpenPGP message`. @@ -129,7 +129,7 @@ The {term}`cleartext signature framework` includes specific text normalization p - **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the {term}`signature`'s structure, and any lines in the message that happen to start with a dash. -- **Normalization of line endings**: Consistent with the approach for any other [text signature](data_signature_types), a {term}`cleartext signature` is calculated on the text with normalized line endings (``). This ensures that the {term}`signature` remains valid regardless of the text format of the receiving {term}`implementation`. +- **Normalization of line endings**: Consistent with the approach for any other [text signature](data-signature-types), a {term}`cleartext signature` is calculated on the text with normalized line endings (``). This ensures that the {term}`signature` remains valid regardless of the text format of the receiving {term}`implementation`. #### Pitfalls diff --git a/book/source/zoom/certificates.md b/book/source/zoom/certificates.md index 31c8101..7f01a40 100644 --- a/book/source/zoom/certificates.md +++ b/book/source/zoom/certificates.md @@ -9,17 +9,17 @@ Now that we've established the concepts and components that make up OpenPGP cert ## A very minimal OpenPGP certificate -In this section, we will examine a very minimal version of a "public key" variant of [Alice's OpenPGP key](alice_priv), specifically an OpenPGP certificate that excludes private key material. +In this section, we will examine a very minimal version of a "public key" variant of [Alice's OpenPGP key](alice-priv), specifically an OpenPGP certificate that excludes private key material. To achieve this, we will use the Sequoia-PGP tool `sq` to handle and transform our example OpenPGP key, as well as to inspect internal OpenPGP packet data. -Starting from [Alice's OpenPGP private key](alice_priv), we first produce the corresponding public key/certificate using the following command: +Starting from [Alice's OpenPGP private key](alice-priv), we first produce the corresponding public key/certificate using the following command: ```text $ sq key extract-cert alice.priv > alice.pub ``` -(split_alice)= +(split-alice)= ### Splitting the OpenPGP certificate into packets To create a very minimal version of Alice's certificate, we will split the data in `alice.pub` into its component packets and reassemble only the relevant ones back into a new variant. @@ -119,7 +119,7 @@ $ sq packet dump --hex alice_minimal.pub This will allow us to gain a detailed understanding of the packet contents. -(public_key)= +(public-key)= ### Public-Key packet The output begins with a (primary) [Public-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-packet-formats): @@ -179,7 +179,7 @@ Note that the *Public-Key packet* contains only the public part of the key. Structure of a Public-Key packet. ``` -(zooming_in_dks)= +(zooming-in-dks)= ### Direct Key Signature The next packet in the certificate is a [*Direct Key Signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-direct-key), which plays a crucial role in binding specific information to the primary key. This signature is contained within the file `alice.pub-1--Signature`. @@ -371,7 +371,7 @@ The signature is calculated from this hash digest. Structure of a direct key signature packet. ``` -(zoom_enc_subkey)= +(zoom-enc-subkey)= ## Encryption subkey Let's now look at a subkey in Alice's OpenPGP certificate. A subkey, when linked to an OpenPGP certificate via its primary key, consists of two elements: @@ -388,7 +388,7 @@ It's common to look at a packet dump for a full OpenPGP certificate as shown bel $ sq packet dump --hex alice.pub ``` -This command shows the details for the full series of packets in an OpenPGP certificate (refer to the list of [packets of Alice's certificate](split_alice)). Finding a particular packet in that list can take a bit of focus and practice though. +This command shows the details for the full series of packets in an OpenPGP certificate (refer to the list of [packets of Alice's certificate](split-alice)). Finding a particular packet in that list can take a bit of focus and practice though. In the following sections,we make it easier for ourselves by directly examining individual packets from the files we created with `sq packet split` above. ```` @@ -418,7 +418,7 @@ Public-Subkey Packet, new CTB, 2 header bytes + 42 bytes 00000020 35 2a 46 01 f3 cc 00 f5 4a 09 3e 3f ``` -Notice that the structure of this *Public-Subkey packet* mirrors the primary key's [*Public-Key packet*](public_key) above. However, there are notable differences between the two packets: +Notice that the structure of this *Public-Subkey packet* mirrors the primary key's [*Public-Key packet*](public-key) above. However, there are notable differences between the two packets: - The packet type ID (`CTB`) in this packet shows type 14 ([*Public-Subkey packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-subkey-packet-type-i)). @@ -646,12 +646,12 @@ Signature Packet, new CTB, 3 header bytes + 325 bytes 00000140 a6 73 c8 33 5a 9c d9 0a ``` -(zooming_in_user_id)= +(zooming-in-user-id)= ## Adding an identity component In this section, we'll look at an identity associated with Alice's certificate. -User IDs are a mechanism for connecting [identities](identity_components) with an OpenPGP certificate. Typically, a User ID is a string combining a name and an email address. +User IDs are a mechanism for connecting [identities](identity-components) with an OpenPGP certificate. Typically, a User ID is a string combining a name and an email address. To understand the internal packet structure of this identity and its connection to the OpenPGP certificate, we'll examine two packets that constitute the identity component. One is the [User ID packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#uid), located in the file `alice.pub-2--UserID`, which contains identity information. The other is a certifying self-signature, specifically a [Positive certification of a User ID and Public-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-positive-certification-of-a) located in the file `alice.pub-3--Signature`. This certification, issued after substantial verification of the identity claim, validates the association between the User ID and the certificate's public key. These packets are snippets from Alice's full OpenPGP certificate. @@ -680,7 +680,7 @@ Essentially, a User ID packet is just a string marked as a User ID by the packet ### Linking the User ID with a certification self-signature -Similar to [linking a subkey](zoom_enc_subkey) to the OpenPGP certificate, a self-signature is used to connect this new component to the certificate. +Similar to [linking a subkey](zoom-enc-subkey) to the OpenPGP certificate, a self-signature is used to connect this new component to the certificate. To bind identities to a certificate with a self-signature, signature types `0x10` - `0x13` can be used. Here, the signature type `0x13` (*positive certification*) is used. @@ -757,7 +757,7 @@ Signature Packet, new CTB, 2 header bytes + 185 bytes ``` -Because this packet structure closely mirrors the [Direct Key Signature](zooming_in_dks) discussed above, we will cover this succinctly. +Because this packet structure closely mirrors the [Direct Key Signature](zooming-in-dks) discussed above, we will cover this succinctly. We're again looking at a Signature packet. Its `type` is `0x13` ([corresponding to a *positive certification* signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types)). diff --git a/book/source/zoom/encryption.md b/book/source/zoom/encryption.md index d58a5a9..7a9feff 100644 --- a/book/source/zoom/encryption.md +++ b/book/source/zoom/encryption.md @@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 ### Encrypt -We encrypt a short message to Alice, using a public certificate version of {ref}`alice_priv`: +We encrypt a short message to Alice, using a public certificate version of {ref}`alice-priv`: ```text $ echo "hello world" | sq encrypt --recipient-file alice.pub diff --git a/book/source/zoom/private_keys.md b/book/source/zoom/private_keys.md index 5172c49..9eeafbb 100644 --- a/book/source/zoom/private_keys.md +++ b/book/source/zoom/private_keys.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 ## A look at Alice's (unencrypted) private key packets -Let's take a look at the key material packets of [Alice's key](alice_priv). +Let's take a look at the key material packets of [Alice's key](alice-priv). To inspect the internal structure of Alice's key, we run the Sequoia-PGP tool `sq` (using the `packet dump` subcommand). The output of `sq` is one big block of text. To discuss the relevant content, we'll only show the output for the packets that contain key data, here: @@ -58,7 +58,7 @@ Secret-Key Packet, new CTB, 2 header bytes + 75 bytes 00000040 bd 42 dd 4b e9 a3 36 81 3b a5 cc cf fb ``` -The Secret-Key packet consists in large part of the actual cryptographic key data. Notice that its content is almost entirely the same as the Public-Key packet [seen in the previous chapter](public_key). Let's look at the packet field by field: +The Secret-Key packet consists in large part of the actual cryptographic key data. Notice that its content is almost entirely the same as the Public-Key packet [seen in the previous chapter](public-key). Let's look at the packet field by field: - `CTB: 0xc5`[^CTB]: The [packet type ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers) for this packet. The binary representation of the value `0xc5` is `11000101`. Bits 7 and 6 show that the packet is in *OpenPGP packet format* (as opposed to in *Legacy packet format*). The remaining 6 bits encode the type ID's value: "5". This is the value for a Secret-Key packet, as shown in the list of [packet type IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-types). - `length: 0x4b`: The remaining length of this packet. @@ -90,7 +90,7 @@ Note that the *Secret-Key packet* contains both the private and the public part ### Secret-Subkey packet -Further down in the "packet dump" of Alice's key, we see the encryption subkey, which we already inspected in its Public-Subkey packet format, [above](zoom_enc_subkey): +Further down in the "packet dump" of Alice's key, we see the encryption subkey, which we already inspected in its Public-Subkey packet format, [above](zoom-enc-subkey): ```text Secret-Subkey Packet, new CTB, 2 header bytes + 75 bytes @@ -129,7 +129,7 @@ As with the public key material, the difference between the format of this subke ## Bob's (encrypted) private key material -Now we look at the primary key material packet of [Bob's key](bob_priv), which uses passphrase protection. +Now we look at the primary key material packet of [Bob's key](bob-priv), which uses passphrase protection. ```text Secret-Key Packet, new CTB, 2 header bytes + 134 bytes diff --git a/book/source/zoom/signatures.md b/book/source/zoom/signatures.md index 306bbe7..c748729 100644 --- a/book/source/zoom/signatures.md +++ b/book/source/zoom/signatures.md @@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 # Zooming in: Packet structure of data signatures -In this chapter, we'll create signatures using [Alice's private key](alice_priv) material, and inspect the packet structure of those signatures. +In this chapter, we'll create signatures using [Alice's private key](alice-priv) material, and inspect the packet structure of those signatures. In some examples, we'll use a test-message that contains the string `hello world` followed by one line feed (`0x0a`) character: