From 3ef4f265d16b18811fd8878ca26a0789b702f690 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 28 Sep 2023 11:16:05 +0200 Subject: [PATCH] ch1/2: add/improve links Tighten "Building blocks" section. (Processing input from Wiktor) --- book/source/01-intro.md | 2 +- book/source/02-highlevel.md | 30 ++++++++++++------------------ book/source/03-cryptography.md | 1 + book/source/09-verification.md | 1 + 4 files changed, 15 insertions(+), 19 deletions(-) diff --git a/book/source/01-intro.md b/book/source/01-intro.md index c2caf18..e9d7cbb 100644 --- a/book/source/01-intro.md +++ b/book/source/01-intro.md @@ -19,7 +19,7 @@ Three groups of people interact with OpenPGP: 2. Software developers who build applications that contain OpenPGP functionality 3. Implementers of OpenPGP libraries (or other software that directly handles the processing of internal OpenPGP data structures) -This document is focused on the second group, application developers, who use OpenPGP functionality in their software projects. It describes the properties of the OpenPGP system and its uses. It presupposes solid knowledge of software development concepts and of general cryptographic concepts. Thus, this text describes OpenPGP at the "library-level," teaching concepts that will help software developers get started as a user of any implementation (e.g., OpenPGP JS, Sequoia PGP). +This document is focused on the second group, application developers, who use OpenPGP functionality in their software projects. It describes the properties of the OpenPGP system and its uses. It presupposes solid knowledge of software development concepts and of general cryptographic concepts. Thus, this text describes OpenPGP at the "library-level," teaching concepts that will help software developers get started as a user of any implementation (e.g., [OpenPGP.JS](https://openpgpjs.org/), [Sequoia-PGP](https://sequoia-pgp.org/)). ```{admonition} TODO :class: warning diff --git a/book/source/02-highlevel.md b/book/source/02-highlevel.md index 71dc5c5..f50ad80 100644 --- a/book/source/02-highlevel.md +++ b/book/source/02-highlevel.md @@ -8,13 +8,13 @@ OpenPGP is an IETF-standardized set of cryptographic operations. OpenPGP defines The OpenPGP standard has evolved over time, and remains under active development. -(Also see https://www.openpgp.org/about/history/) +(Also see [https://www.openpgp.org/about/history/](https://www.openpgp.org/about/history/)) ### "Pretty Good Privacy (PGP)" The earliest roots of OpenPGP trace back to *"Pretty Good Privacy (PGP)"*, a software program written by [Phil Zimmermann](https://en.wikipedia.org/wiki/Phil_Zimmermann) and first released in 1991. -The original PGP software has played a role in the political struggles sometimes referred to as the ["Crypto Wars"](https://en.wikipedia.org/wiki/Crypto_Wars) (also see https://en.wikipedia.org/wiki/Crypto_(book) for some of that history, including about the history of PGP). +The original PGP software has played a role in the political struggles sometimes referred to as the ["Crypto Wars"](https://en.wikipedia.org/wiki/Crypto_Wars) (also see ["Crypto: How the Code Rebels Beat the Government Saving Privacy in the Digital" (2002)](https://en.wikipedia.org/wiki/Crypto_(book)) for some of that history, including part of the history of PGP). The original "PGP" software was never under a Free Software license, even though its source code has at one point been widely published. @@ -32,7 +32,7 @@ The name "OpenPGP" can be used freely by implementations (unlike the name "PGP", [First released 1997-12-20](https://gnupg.org/download/release_notes.html#sec-2-70), GnuPG (the "GNU Privacy Guard") is an implementation of the OpenPGP standard. -GnuPG has been a major early Free Software implementation of OpenPGP. 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/). +GnuPG has been a major early Free Software implementation of OpenPGP. It has played an important (and successful) role in the [release of NSA documents](https://theintercept.com/2014/10/28/smuggling-snowden-secrets/) by [Edward Snowden](https://en.wikipedia.org/wiki/Edward_Snowden). The GnuPG program binary is called `gpg`, thus the names "GnuPG" and "gpg" are often used interchangeably. @@ -64,11 +64,11 @@ This document describes OpenPGP version 6, while pointing out differences to pre Significant work on support for OpenPGP version 6 has already been done for multiple implementations, including: -- GOpenPGP, -- OpenPGP.js, -- PGPainless, -- PGPy, -- Sequoia PGP. +- [GOpenPGP](https://github.com/ProtonMail/gopenpgp/tree/v3), +- [OpenPGP.js](https://github.com/openpgpjs/openpgpjs/tree/v6), +- [PGPainless](https://github.com/pgpainless/pgpainless/milestone/6), +- [PGPy](https://github.com/dkg/PGPy/tree/dkg/crypto-refresh), +- [Sequoia-PGP](https://gitlab.com/sequoia-pgp/sequoia/-/tree/crypto-refresh). ## Concepts @@ -76,7 +76,7 @@ Significant work on support for OpenPGP version 6 has already been done for mult Use of OpenPGP is centered around (asymmetric) cryptographic keys. -In OpenPGP, bare cryptographic keys are combined with additional metadata into "OpenPGP certificates", which are a relatively complex data structure (OpenPGP certificates are also often called "OpenPGP keys"). +In OpenPGP, bare cryptographic keys are combined with additional metadata into "OpenPGP certificates," which are a relatively complex data structure (OpenPGP certificates are also often called "OpenPGP keys"). An OpenPGP certificate can evolve over time, with components being added, expiring, or being marked as invalid. @@ -89,18 +89,12 @@ Other important topics around certificates are their management, authentication, With OpenPGP it's possible to: - [Encrypt](encryption_chapter) and [Decrypt](decryption_chapter) Messages -- Sign Data -- Issue and examine Statements about Keys and Identities (to perform CA-like functionality) +- [Sign](signing_data) and [Verify](verification_chapter) Data +- [Issue and examine Statements](signatures_chapter) about Keys and Identities (to perform CA-like functionality) ### Building blocks -To perform these high-level operations, the following building blocks are used: - -- Encryption -- Signature Algorithms -- OpenPGP Signatures (made from raw signatures; Certifications, Data Signatures) -- Keys, Subkeys -- User IDs +To perform these high-level operations, a set of [established cryptographic mechanisms](cyrptography_chapter) are used as building blocks, and combined into OpenPGP's format, which additionally deals with identities and their verification. ## Zooming in: Internal structure of OpenPGP data diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index ee968a5..f979703 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -1,3 +1,4 @@ +(cyrptography_chapter)= # Cryptographic concepts/terms ```{admonition} TODO diff --git a/book/source/09-verification.md b/book/source/09-verification.md index 5223ac5..bee54ba 100644 --- a/book/source/09-verification.md +++ b/book/source/09-verification.md @@ -1,3 +1,4 @@ +(verification_chapter)= # Verification - Self-authenticating data (unhashed subpackets)