From ae29cdc0c8112a6f592567e284cc319418d5d8f5 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 12 Dec 2023 13:02:55 +0100 Subject: [PATCH] remove top-level anchors in chapters --- book/source/about.md | 8 ++++---- book/source/adv/certificates.md | 2 +- book/source/certificates.md | 9 ++++----- book/source/compression.md | 2 +- book/source/cryptography.md | 5 ++--- book/source/decryption.md | 1 - book/source/encryption.md | 3 +-- book/source/glossary.md | 4 ++-- book/source/private.md | 5 ++--- book/source/signatures.md | 4 ++-- book/source/signing_components.md | 3 +-- book/source/signing_data.md | 2 +- book/source/verification.md | 1 - book/source/versions.md | 1 - 14 files changed, 21 insertions(+), 29 deletions(-) diff --git a/book/source/about.md b/book/source/about.md index fd01f53..81a3e6e 100644 --- a/book/source/about.md +++ b/book/source/about.md @@ -11,13 +11,13 @@ 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_chapter). 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: -- [Encrypt](encryption_chapter) and [decrypt](decryption_chapter) messages to preserve confidentiality -- [Sign](signing_data) and [verify](verification_chapter) data to ensure {term}`authenticity` -- [Issue and validate certifications](component_signatures_chapter) about {term}`keys` and {term}`identities`, similar to the role of a {term}`Certificate Authority` ({term}`CA`) in validating {term}`identities`. +- [Encrypt](/encryption) and [decrypt](/decryption) messages to preserve confidentiality +- [Sign](/signing_data) and [verify](/verification) data to ensure {term}`authenticity` +- [Issue and validate certifications](/signing_components) about {term}`keys` and {term}`identities`, similar to the role of a {term}`Certificate Authority` ({term}`CA`) in validating {term}`identities`. ## Who is the audience for this document? diff --git a/book/source/adv/certificates.md b/book/source/adv/certificates.md index abfd54b..f91f79a 100644 --- a/book/source/adv/certificates.md +++ b/book/source/adv/certificates.md @@ -11,7 +11,7 @@ Certificates are composites of components that are linked together using [signat A certificate can be valid or invalid as a whole. However, even when a certificate is valid, individual components (subkeys or identities) of it can be invalid. -In this section, we discuss the validity of certificates and their components. This discussion is closely related to [signature validity](verification_chapter), and builds on that concept. +In this section, we discuss the validity of certificates and their components. This discussion is closely related to [signature validity](/verification), and builds on that concept. The validity of the signatures that link a certificate is a necessary precondition. Two concepts are particularly central to the validity of certificates and components: diff --git a/book/source/certificates.md b/book/source/certificates.md index 72c55be..ba4d54e 100644 --- a/book/source/certificates.md +++ b/book/source/certificates.md @@ -3,7 +3,6 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> -(certificates_chapter)= # Certificates OpenPGP fundamentally hinges on the concept of "{term}`OpenPGP certificates`," also known as "{term}`OpenPGP public keys`." These {term}`certificates` are complex data structures essential for {term}`identity verification`, data encryption, and {term}`digital signatures`. Understanding their structure and function is pivotal to effectively applying the OpenPGP standard. @@ -12,9 +11,9 @@ An {term}`OpenPGP certificate`, by definition, does not contain {term}`private k Fundamentally, the effective management of {term}`certificates` and a thorough grasp of their {term}`authentication` and {term}`trust models` are crucial for proficient OpenPGP usage. Although this document offers just a brief overview of these aspects, they form a fundamental part of the broader OpenPGP framework and warrant further study. -- For an in-depth exploration of OpenPGP's {term}`private key material`, refer to {ref}`private_key_chapter`. This chapter provides essential insights into {term}`private key` management and security practices. +- For an in-depth exploration of OpenPGP's {term}`private key material`, refer to [](/private). This chapter provides essential insights into {term}`private key` management and security practices. -- The bindings that link the {term}`components` of a {term}`certificate` are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of {term}`certificate` structure and integrity. +- The bindings that link the {term}`components` of a {term}`certificate` are comprehensively discussed in [](/signing_components), offering a deeper understanding of {term}`certificate` structure and integrity. - Finally, our chapter {ref}`zoom_certificates` discusses the internal structure of {term}`certificates` in detail. @@ -78,7 +77,7 @@ An {term}`OpenPGP certificate` usually contains multiple {term}`component keys` containing {term}`private key material` also include {term}`metadata` specifying the password protection scheme. This is another facet of {term}`metadata`, akin to the aforementioned creation timestamp and additional parameters for certain algorithms. However, this discussion focuses on {term}`OpenPGP certificates`, in which the {term}`component keys` contain only the public part of its cryptographic key data. For information on {term}`private keys` in OpenPGP, see {numref}`private_key_chapter`. +{term}`Component keys` containing {term}`private key material` also include {term}`metadata` specifying the password protection scheme. This is another facet of {term}`metadata`, akin to the aforementioned creation timestamp and additional parameters for certain algorithms. However, this discussion focuses on {term}`OpenPGP certificates`, in which the {term}`component keys` contain only the public part of its cryptographic key data. For information on {term}`private keys` in OpenPGP, see [](private). (fingerprint)= ### Fingerprint @@ -181,7 +180,7 @@ Currently, the OpenPGP standard prescribes only one format to be stored in user ## Linking the components -To form an {term}`OpenPGP certificate`, individual {term}`components` are interconnected by the {term}`certificate holder` using their OpenPGP software. Within OpenPGP, this process is termed "binding", as in "a {term}`subkey` is bound to the {term}`primary key`." These bindings are realized using cryptographic {term}`signatures`. An in-depth discussion of this topic can be found in {ref}`component_signatures_chapter`. +To form an {term}`OpenPGP certificate`, individual {term}`components` are interconnected by the {term}`certificate holder` using their OpenPGP software. Within OpenPGP, this process is termed "binding", as in "a {term}`subkey` is bound to the {term}`primary key`." These bindings are realized using cryptographic {term}`signatures`. An in-depth discussion of this topic can be found in [](signing_components). In very abstract terms, the {term}`primary key` of a {term}`certificate` acts as a root of trust or "{term}`certification authority`." It is responsible for: diff --git a/book/source/compression.md b/book/source/compression.md index c53e379..7346c1e 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_chapter), 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 2cbb453..f2b1e3b 100644 --- a/book/source/cryptography.md +++ b/book/source/cryptography.md @@ -3,7 +3,6 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> -(cryptography_chapter)= # Cryptographic concepts and terms (crypto-hash)= @@ -133,7 +132,7 @@ In OpenPGP, digital signatures have diverse applications, extending beyond mere {term}`Digital signatures` in OpenPGP are used in two primary contexts: - [Data signatures](signing_data) -- [Signatures on components](component_signatures_chapter) +- [Signatures on components](/signing_components) (hybrid_cryptosystems)= ## Hybrid cryptosystems @@ -142,4 +141,4 @@ In OpenPGP, digital signatures have diverse applications, extending beyond mere ### Usage and terminology in OpenPGP -OpenPGP uses a {term}`hybrid cryptosystem` for encryption. This approach involves generating unique shared secrets, known as "session keys," for each session. For detailed information on this topic, please refer to the chapters {ref}`encryption_chapter` and {ref}`decryption_chapter`. +OpenPGP uses a {term}`hybrid cryptosystem` for encryption. This approach involves generating unique shared secrets, known as "session keys," for each session. For detailed information on this topic, please refer to the chapters [](encryption) and [](decryption). diff --git a/book/source/decryption.md b/book/source/decryption.md index d823cd7..3ccba55 100644 --- a/book/source/decryption.md +++ b/book/source/decryption.md @@ -3,7 +3,6 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> -(decryption_chapter)= # Decryption Message decryption is the process of taking an encrypted message and recovering its plaintext. diff --git a/book/source/encryption.md b/book/source/encryption.md index 2eda81d..3122d46 100644 --- a/book/source/encryption.md +++ b/book/source/encryption.md @@ -3,7 +3,6 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> -(encryption_chapter)= # Encryption [Encryption](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-confidentiality-via-encrypt) is one of the core facilities of OpenPGP. It provides confidentiality. @@ -48,7 +47,7 @@ Two generations of encryption mechanisms are currently relevant in OpenPGP, and The main difference between these lies in the symmetric part of the encryption mechanism, represented by versions 1 and 2 of the *Symmetrically Encrypted and Integrity Protected Data* packets (abbreviated as "SEIPD"). The two versions use different mechanisms to provide non-malleability. More on these below. -Older, legacy encryption mechanisms exist in OpenPGP. However, those must not be used for encryption anymore. Messages encrypted using these legacy mechanisms may still be decrypted, although with caution. For more information, see the [decryption](decryption_chapter) chapter. +Older, legacy encryption mechanisms exist in OpenPGP. However, those must not be used for encryption anymore. Messages encrypted using these legacy mechanisms may still be decrypted, although with caution. For more information, see the [decryption](/decryption) chapter. SEIPD packets are used in combination with two mechanisms that store *session keys*: diff --git a/book/source/glossary.md b/book/source/glossary.md index 837349a..2b1d0a4 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -240,7 +240,7 @@ Issuer Key Key In OpenPGP, and cryptography more generally, the term "key" holds different meanings. - First, it can apply to different [cryptographic primitives](cryptography_chapter): + First, it can apply to different [cryptographic primitives](/cryptography): - asymmetric public key - asymmetric private key @@ -510,7 +510,7 @@ Self-signature An {term}`OpenPGP Signature Packet` by the {term}`Certificate Holder` on a {term}`Component` of their own {term}`Certificate`. Session Key - A unique shared secret used in encryption in a {term}`Hybrid Cryptosystem`. See {ref}`encryption_chapter` and {ref}`decryption_chapter`. + A unique shared secret used in encryption in a {term}`Hybrid Cryptosystem`. See [](encryption) and [](decryption). 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`). diff --git a/book/source/private.md b/book/source/private.md index 5a7fb81..5c21d18 100644 --- a/book/source/private.md +++ b/book/source/private.md @@ -3,19 +3,18 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> -(private_key_chapter)= # Managing private key material in OpenPGP ## Overview of private keys This chapter discusses the handling of private key material within OpenPGP. -Private key material is associated with component keys, which are integral parts of [OpenPGP certificates](certificates_chapter). For a discussion of packet structure internals, see the chapter {ref}`zoom_private`. +Private key material is associated with component keys, which are integral parts of [OpenPGP certificates](/certificates). For a discussion of packet structure internals, see the chapter {ref}`zoom_private`. ## Terminology: "certificates" and "private keys" Recall that in this document, the term *OpenPGP certificate* refers to what are commonly known as "OpenPGP public keys." OpenPGP certificates are the combination of component public keys, identity components, binding self-signatures, and third-party certifications, -as discussed in the previous chapter ({ref}`certificates_chapter`). +as discussed in the previous chapter ([](/certificates)). This chapter focuses on the corresponding counterpart to the elements of certificates: the *private key material* of component keys. diff --git a/book/source/signatures.md b/book/source/signatures.md index 6e10ec8..43836ea 100644 --- a/book/source/signatures.md +++ b/book/source/signatures.md @@ -43,7 +43,7 @@ The OpenPGP standard defines a set of [Signature types](https://www.ietf.org/arc - **{term}`Signatures over data`**: These signatures are denoted by {term}`type IDs` `0x00` for binary documents and `0x01` for canonical text documents. The {term}`signer` uses these {term}`signatures` to claim ownership, assert creation, or certify the immutability of the document. - **{term}`Signatures on components`**: These are {term}`signatures` that are associated with {term}`component keys` or {term}`identity components` of a {term}`certificate`. -{term}`Signatures on components` are a complex topic, and we discuss them in depth in {ref}`component_signatures_chapter`. They are grouped based on two criteria: +{term}`Signatures on components` are a complex topic, and we discuss them in depth in [](/signing_components). They are grouped based on two criteria: - the origin of the {term}`signature`, distinguishing between a {term}`self-signature` and a {term}`third-party signature` - the nature of the statement made by the {term}`signature`, such as certifying an {term}`identity` or binding {term}`component keys` into a {term}`certificate` @@ -57,7 +57,7 @@ An overview of {term}`signature types` in OpenPGP This chapter will cover the overarching principles applicable to all {term}`OpenPGP signature types`. -For more detail about specific {term}`types of signatures`, see the chapters on [](/signing_data) and {ref}`component_signatures_chapter`, respectively. +For more detail about specific {term}`types of signatures`, see the chapters on [](/signing_data) and [](/signing_components), respectively. ## Structure of an OpenPGP signature packet diff --git a/book/source/signing_components.md b/book/source/signing_components.md index 4808319..ada0107 100644 --- a/book/source/signing_components.md +++ b/book/source/signing_components.md @@ -3,7 +3,6 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> -(component_signatures_chapter)= # Signatures on components This chapter examines {term}`OpenPGP signatures` associated with {term}`certificate components`, applying to: @@ -13,7 +12,7 @@ This chapter examines {term}`OpenPGP signatures` assoc {term}`Signatures on components` are used to construct and maintain {term}`certificates`, and to model the {term}`authentication` of {term}`identities`. -This chapter expands on topics introduced in the {ref}`certificates_chapter` chapter. +This chapter expands on topics introduced in the [](certificates) chapter. ## Self-signatures vs third-party signatures diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 65d063f..a4c5943 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -14,7 +14,7 @@ it does not automatically signal if the expected party indeed controls the {term {term}`Data signatures` can only be issued by {term}`component keys` with the *{term}`signing`* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags). -Note that {term}`data signatures` are distinct from {ref}`component_signatures_chapter`, which are used to form and maintain {term}`certificates`, as well as to {term}`certify` {term}`identities` on {term}`certificates`. +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)= ## Signature types diff --git a/book/source/verification.md b/book/source/verification.md index 8f74908..67de536 100644 --- a/book/source/verification.md +++ b/book/source/verification.md @@ -3,7 +3,6 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> -(verification_chapter)= # Signature verification Signature verification in the OpenPGP protocol is a complex process. diff --git a/book/source/versions.md b/book/source/versions.md index 98db81e..ff7d46f 100644 --- a/book/source/versions.md +++ b/book/source/versions.md @@ -3,7 +3,6 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> -(versions)= # OpenPGP versions ## Differences between OpenPGP versions