reorder chapters: 6 is now a general introduction to openpgp signatures

book/source/06-signatures.md

@@ -0,0 +1,85 @@
+<!--
+SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# OpenPGP Signatures
+
+Signatures make up the magic of OpenPGP. They act as the syntax that allows forming and interpreting rich statements about certificates and their components, as well as data.
+
+Without signatures, there would only be loose keys, impossible to associate with a certificate, or their owner. Signatures are the glue that allows for components (component keys and identity components) to be assembled into hierarchical certificates, and for messages to gain authenticity.
+
+## Terminology
+
+The term *signature* can have multiple meanings in the context of OpenPGP:
+
+- Cryptographic keys create raw signatures which are byte sequences calculated according to some signature scheme.
+- OpenPGP packs these raw signatures up into OpenPGP signature packets, which carry additional information in the form of signature subpackets.
+
+For the purpose of this document, the term signature will refer to an OpenPGP [signature packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-packet-type-id-2).
+
+## Types of signatures 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 signature type ID. Signature types define the intent of a signature, and how it needs to be interpreted.
+
+```{figure} mermaid/06-terminology.png
+
+An overview of signature types in OpenPGP
+```
+
+OpenPGP signatures can be classified as either:
+
+- *Signatures on components* (that is: signatures that apply to component keys or identity components), or
+- *Signatures over data*.
+
+The same OpenPGP signature mechanism is used for all of these cases. So at first, we will discuss the general shape of OpenPGP signatures.
+
+In this chapter, we discuss the general principles of OpenPGP signatures.
+
+For more detail about the two classes of signatures, see the chapters {ref}`component_signatures_chapter` and {ref}`signing_data`, respectively.
+
+## Structure of an OpenPGP signature
+
+
+However, there are differences in some details of the signatures for these different cases, which we will also look into. The semantics differ between these types of signatures. We'll discuss all of this in this chapter.
+
+XXX: Todo
+
+- type
+- what is being signed / hashed
+- cryptographic signature co-exists with metadata, in a signature packet
+- some of the metadata is encoded as "subpackets"
+
+## Signature subpackets
+
+A cryptographic signature alone is often not expressive enough to serve certain use-cases.
+For this reason, the OpenPGP protocol introduced signature subpackets with rfc4880.
+These are well-defined data structures that can be placed as subelements into signature packets, which give additional context and meaning to a signature.
+Typical examples are the issuer fingerprint subpacket, which contains the fingerprint of the issuer key, or the key flags subpacket which states, what purpose a component key is intended for.
+
+Signature subpackets can reside in two different areas of a signature packet.
+Subpackets in the *hashed area* are incorporated in the digest calculation that is done during signature calculation and are therefore covered by the cryptographic signature.
+In other words; hashed subpackets are *authenticated*.
+If a subpacket is placed in the *unhashed area* instead, it is not included in the signature calculation procedure and is therefore not protected against tampering.
+The unhashed area can be used to retroactively add, change or remove subpackets from a signature without invalidating it.
+
+Due to the fact that the unhashed area doesn't provide any cryptographic guarantees, it is only intended for advisory packets, or packets that self-authenticate (e.g. the issuer fingerprint subpacket, whose "correctness" can be proven by successfully verifying the signature using the referenced issuer key).
+In most cases, signature subpackets are simply added into the hashed area.
+
+### Criticality of subpackets
+
+Each signature subpacket has a flag that indicates whether or not the subpacket is *critical*.
+Since different OpenPGP implementations might support subsets of the standard, it would be fatal, if for example an implementation did not understand the concept of signature expiration.
+Such an implementation would potentially accept an already expired signature.
+By marking the expiration date subpacket as critical, the user can indicate, that implementations that do not understand this type of subpacket are supposed to reject the signature as invalid.
+
+Sections 5.2.3.11 - 5.2.3.36 give guidance on which subpackets are usually marked as critical.
+
+
+## Advanced topics
+
+### Notations
+
+### "Negotiating" signature hash algorithm based on recipients preference subpackets
+
+### Explore viability of having multiple signatures, e.g. v4+v6?

book/source/07-signing_components.md

@@ -7,50 +7,17 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Signatures on components
 
-Signatures make up the magic of OpenPGP. They act as the syntax that allows forming and interpreting rich statements about certificates and their components, as well as data.
+In this chapter, we'll consider OpenPGP signatures that apply to components. That is, signatures that apply to:
 
-Without signatures, there would only be loose keys, impossible to associate with a certificate, or their owner. Signatures are the glue that allows for components (component keys and identity components) to be assembled into hierarchical certificates, and for messages to gain authenticity.
+- Component keys (primary keys or subkeys), or
-
+- Identity components (User IDs or User attributes).
-## Terminology
-
-The term *signature* can have multiple meanings in the context of OpenPGP:
-
-- Cryptographic keys create raw signatures which are byte sequences calculated according to some signature scheme.
-- OpenPGP packs these raw signatures up into OpenPGP signature packets, which carry additional information in the form of signature subpackets.
-
-For the purpose of this document, the term signature will refer to an OpenPGP [signature packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-packet-type-id-2).
-
-## Types of signatures 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 signature type ID. Signature types define the intent of a signature, and how it needs to be interpreted.
-
-```{figure} mermaid/06-terminology.png
-
-An overview of signature types in OpenPGP
-```
-
-OpenPGP signatures can be classified as either:
-
-- *Signatures on components* (that is: signatures that apply to component keys or identity components), or
-- *Data signatures*.
-
-In this chapter, we'll discuss the first class: Signatures that apply to components. For a discussion of the second class, see our chapter {ref}`signing_data`,
 
 ## Different kinds of signatures on components
 
-There are two types of components that signatures can apply to:
+There are two important scenarios to distinguish. Signatures on components can be issued by:
 
-- Component keys (primary keys or subkeys).
+- The certificate's owner, using the primary key of the same certificate. We call these *self-signatures*. Or
-- Identity components (User IDs or User attributes).
+- Using a key that is part of a different certificate. We call these *third-party signatures*.
-
-And there are two important scenarios that we will distinguish. Signatures on components can be issued by:
-
-- The certificate's owner, using the primary key of the certificate (in which case we call them *self-signatures*), or
-- A third party (in which case we call them *third-party signatures*).
-
-The same OpenPGP signature mechanism is used for all of these cases. So at first, we will discuss the general shape of OpenPGP signatures.
-
-However, there are differences in some details of the signatures for these different cases, which we will also look into. The semantics differ between these types of signatures. We'll discuss all of this in this chapter.
 
 ## Context-specific meaning
 
@@ -98,32 +65,6 @@ Typical use-cases for revocations are marking certificates or individual subkeys
 
 A revocation signature can either be hard or soft. A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material.
 
-## Signature subpackets
-
-A cryptographic signature alone is often not expressive enough to serve certain use-cases.
-For this reason, the OpenPGP protocol introduced signature subpackets with rfc4880.
-These are well-defined data structures that can be placed as subelements into signature packets, which give additional context and meaning to a signature.
-Typical examples are the issuer fingerprint subpacket, which contains the fingerprint of the issuer key, or the key flags subpacket which states, what purpose a component key is intended for.
-
-Signature subpackets can reside in two different areas of a signature packet.
-Subpackets in the *hashed area* are incorporated in the digest calculation that is done during signature calculation and are therefore covered by the cryptographic signature.
-In other words; hashed subpackets are *authenticated*.
-If a subpacket is placed in the *unhashed area* instead, it is not included in the signature calculation procedure and is therefore not protected against tampering.
-The unhashed area can be used to retroactively add, change or remove subpackets from a signature without invalidating it.
-
-Due to the fact that the unhashed area doesn't provide any cryptographic guarantees, it is only intended for advisory packets, or packets that self-authenticate (e.g. the issuer fingerprint subpacket, whose "correctness" can be proven by successfully verifying the signature using the referenced issuer key).
-In most cases, signature subpackets are simply added into the hashed area.
-
-### Criticality of subpackets
-
-Each signature subpacket has a flag that indicates whether or not the subpacket is *critical*.
-Since different OpenPGP implementations might support subsets of the standard, it would be fatal, if for example an implementation did not understand the concept of signature expiration.
-Such an implementation would potentially accept an already expired signature.
-By marking the expiration date subpacket as critical, the user can indicate, that implementations that do not understand this type of subpacket are supposed to reject the signature as invalid.
-
-Sections 5.2.3.11 - 5.2.3.36 give guidance on which subpackets are usually marked as critical.
-
-
 ## Self-signatures: Linking the components of a certificate
 
 So far we've looked at the components in an OpenPGP certificate, but certificates actually contain another set of elements, which bind the components together, and add metadata to them.

book/source/08-signature_internals.md

@@ -1,18 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Signature "internals"
-
-```{admonition} TODO
-:class: warning
-
-  - Subpackets and how to make sense of them
-  - "Negotiating" signature hash algorithm based on recipients preference subpackets
-  - Explore viability of having multiple signatures, e.g. v4+v6?
-```
-
-## Notations
-
-## Zooming in: Packet structure