Merge pull request 'Edits in chapter two; add link anchors to point to' (#14) from heiko/ch2 into draft

Reviewed-on: https://codeberg.org/openpgp/notes/pulls/14

book/source/01-intro.md

@@ -8,10 +8,7 @@ This text is *not* intended as a guide for end-users of OpenPGP-related software
 
 ## What is OpenPGP?
 
-OpenPGP is an open standard for cryptographic operations. It is a system based on well-understood cryptographic building blocks. OpenPGP supports the secure delivery of files and messages between a sender and a recipient as well as verification of the sender. 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.
+OpenPGP is an open standard for cryptographic operations. It is a system based on well-understood cryptographic building blocks. OpenPGP supports the secure delivery of files and messages between a sender and a recipient as well as verification of the sender. 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).
-
-```Heiko, let's be sure to create our own page on interoperability instead of linking to this```
-
 
 
 ## Who is the audience for this document?

book/source/02-highlevel.md

@@ -32,41 +32,65 @@ The name "OpenPGP" can be used freely by implementations (unlike the name "PGP",
 
 GnuPG has been the major Free Software implementation of OpenPGP for a period of time. It has played an important (and successful) role in the release of NSA documents by [Edward Snowden](https://theintercept.com/2014/10/28/smuggling-snowden-secrets/).
 
-Note: The terms "pgp key" and "gpg key" are often used interchangably. Since both PGP and GnuPG are just some out of many existing OpenPGP implementations, the proper term to use is "OpenPGP key".
+Note: The terms "pgp key" and "gpg key" are sometimes used interchangeably. Since both PGP and GnuPG are just some out of many existing OpenPGP implementations, the proper term to use is "OpenPGP key" (or "OpenPGP certificate", more on that later [link]).
 
 ## The present
 
+### OpenPGP version 4
+
+In 2007, [RFC 4880](https://datatracker.ietf.org/doc/html/rfc4880), defining version 4 of OpenPGP, was published.
+This version is currently most commonly used
+
+(major_implementations)=
 ### Multiple major implementations
 
 Today multiple new Free Software implementations of OpenPGP play important roles:
 
-- Protonmail, who provide email encryption services for a large number of users, use (and maintain) [OpenPGP.js](https://openpgpjs.org/)as well as [GopenPGP](https://gopenpgp.org/).
+- Protonmail, who provide email encryption services for a large number of users, use (and maintain) [OpenPGP.js](https://openpgpjs.org/) as well as [GopenPGP](https://gopenpgp.org/).
 - The Thunderbird email software is using the [RNP](https://www.rnpgp.org/) implementation for their built-in OpenPGP support since version 78 (released in mid-2020).
 - The RPM Package Manager software includes an OpenPGP backend based on [Sequoia PGP](https://sequoia-pgp.org/), a modern OpenPGP implementation in Rust. Fedora [uses Sequoia PGP in rpm](https://sequoia-pgp.org/blog/2023/04/27/rpm-sequoia/) since version 38.
 
+## The road ahead
+
 ### OpenPGP version 6
 
-This document mainly describes OpenPGP version 6, which brings many updates of the core cryptographic mechanisms, compared to the previous version 4.
+As of this writing (in 2023), [version 6 of OpenPGP](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/) is approaching publication as an RFC.
+The working group's [charter](https://datatracker.ietf.org/wg/openpgp/about/#autoid-1) centers around updating the cryptographic mechanisms, adding new algorithms, and deprecation of obsolete algorithms.
 
-As of this writing (in 2023), version 4 of OpenPGP is still most commonly used. OpenPGP version 4 is described in [RFC 4880](https://datatracker.ietf.org/doc/html/rfc4880).
+This document mainly describes OpenPGP version 6, while pointing out differences to previous versions that are relevant to application developers.
+
+Multiple implementations have already done significant work on support for version 6.
 
 ## Concepts
 
+Building on the cryptographic building blocks OpenPGP uses, it provides the following high-level functionalities.
+
 ### Certificates/Keys
 
-All uses of OpenPGP are centered around (asymmetric) cryptographic key material. In OpenPGP, cryptographic keys are combined with additional metadata into "OpenPGP Keys", or "OpenPGP Certificates".
+Use of OpenPGP is centered around (asymmetric) cryptographic keys. In OpenPGP, these keys are combined with additional metadata into "OpenPGP certificates" - also often referred to as "OpenPGP keys."
 
-See chapter "certs" (link) for more on OpenPGP Certificates, and "private" for handling of private key material in OpenPGP.
+See the [certificates chapter](certificates_chapter) for more on OpenPGP certificates, and their internal makeup, and the [private key chapter](private_key_chapter) for handling of private key material in OpenPGP.
+
+Other important topics around certificates are their management, authentication, and trust models. We will only touch on those, in this document.
 
 ### Cryptographic operations
 
-- Signatures
+The main operations of OpenPGP are discussed in the following chapters:
-- Encryption
 
-### Internal structure of OpenPGP data
+- [Encryption](encryption_chapter) and [Decryption](decryption_chapter)
+- [Digital signatures](signatures_chapter)
 
-OpenPGP data is structured as "packets" (and sometimes "subpackets"), internally.
+## Zooming in: Internal structure of OpenPGP data
 
+OpenPGP data is internally structured as "packets" (and sometimes "subpackets"). We'll go into some detail about this, throughout the coming chapters.
+
+```
+add a tiny bit more detail here
+```
+
+(interop_section)=
 ## Interoperability
 
-```describe, and link to interop test suite```
+OpenPGP has been defined as a standard with the express goal of enabling multiple parties to build interoperable implementations. This has already been a success early on, but in recent years, there has been [much development of new implementations]((major_implementations)).
+
+While interoperability has been an informal goal in the OpenPGP space since the initial standardization, since 2019 the Sequoia project is maintaining and operating the more formal ["OpenPGP interoperability test suite"](https://tests.sequoia-pgp.org/). This test suite has identified numerous [issues](https://gitlab.com/sequoia-pgp/openpgp-interoperability-test-suite#hall-of-fame).

book/source/04-certs.md

@@ -1,3 +1,4 @@
+(certificates_chapter)=
 # Certificates / Keys
 
 ```

book/source/05-private.md

@@ -1,3 +1,4 @@
+(private_key_chapter)=
 # Private key material
 
 ```

book/source/06-signatures.md

@@ -1,4 +1,5 @@
-# Signatures as "statments"
+(signatures_chapter)=
+# Signatures as "statements"
 
 ```
   - Purpose of a signature

book/source/09-encryption.md

@@ -1,3 +1,4 @@
+(encryption_chapter)=
 # Encryption
 
 ```

book/source/10-decryption.md

@@ -1,3 +1,4 @@
+(decryption_chapter)=
 # Decryption
 
 ```