From 59026d7e3c5ea5df978177945222c1d7750e527a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 11 Jan 2024 16:51:13 +0100 Subject: [PATCH 1/3] Clarify target-audience --- book/source/about.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/source/about.md b/book/source/about.md index 07ea24c..9d46557 100644 --- a/book/source/about.md +++ b/book/source/about.md @@ -27,9 +27,11 @@ 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 not intended for end-users or implementers of OpenPGP libraries (or other software that directly handles internal OpenPGP data structures). +This document is not intended for end-users. -Instead, 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/)). +Instead, this document is mainly aimed at 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/)). + +The document may also serve as a useful supplement to the RFC for implementers of OpenPGP libraries (or other software that directly handles internal OpenPGP data structures). With the emergence of a new crop of modern, high-quality OpenPGP libraries, and the imminent release of the updated [OpenPGP version 6 specification](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/), we think that now is a great time to implement OpenPGP functionality in applications or to modernize existing OpenPGP subsystems. From 4d70d1647fdb6ab73924f4a0fecfae7dc3e45973 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Fri, 19 Jan 2024 17:57:00 +0100 Subject: [PATCH 2/3] correct to end users --- book/source/about.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/about.md b/book/source/about.md index 9d46557..d585bf3 100644 --- a/book/source/about.md +++ b/book/source/about.md @@ -23,11 +23,11 @@ With OpenPGP, you can: Three groups of people interact with OpenPGP: -1. End-users, who use software that contains OpenPGP functionality (e.g., the Thunderbird email software) +1. End users, who use software that contains OpenPGP functionality (e.g., the Thunderbird email software) 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 not intended for end-users. +This document is not intended for end users. Instead, this document is mainly aimed at 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/)). From d5144400718c0358ab7d97a10ed9929d27a6ef55 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 19 Jan 2024 17:55:08 +0100 Subject: [PATCH 3/3] Fix styling of "end user" (no dash) --- book/source/adv/certificates.md | 2 +- book/source/certificates.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/adv/certificates.md b/book/source/adv/certificates.md index 0f44205..0e2b750 100644 --- a/book/source/adv/certificates.md +++ b/book/source/adv/certificates.md @@ -224,7 +224,7 @@ Disadvantages/risks of minimizing certificates: - As the OpenPGP subsystem on a user's computer learns about more certificates, third-party certifications that were previously unusable may become usable. Dropping third-party certifications by unknown issuers as a part of minimization prevents this mechanism. - An OpenPGP implementation that minimizes a certificate might remove component keys that it cannot use itself (e.g. because it doesn't support the algorithm of that key), even if the *receiving* implementation supports them. - Refreshing certificates from key servers may inflate the certificate again, since OpenPGP certificates tend to act as [append-only structures](append-only). -- Some libraries, such as [anonaddy-sequoia](https://gitlab.com/willbrowning/anonaddy-sequoia/-/blob/master/src/sequoia.rs?ref_type=heads#L125) strip unusable encryption subkeys, but retain at least one subkey, even if all subkeys are expired. Although this may leave only an expired encryption subkey in the certificate, this presents a better UX for the end-user who potentially is still in possession of the private key for decryption. +- Some libraries, such as [anonaddy-sequoia](https://gitlab.com/willbrowning/anonaddy-sequoia/-/blob/master/src/sequoia.rs?ref_type=heads#L125) strip unusable encryption subkeys, but retain at least one subkey, even if all subkeys are expired. Although this may leave only an expired encryption subkey in the certificate, this presents a better UX for the end user who potentially is still in possession of the private key for decryption. ## Guidelines diff --git a/book/source/certificates.md b/book/source/certificates.md index 30e9744..51085dd 100644 --- a/book/source/certificates.md +++ b/book/source/certificates.md @@ -289,6 +289,6 @@ For example, Bob's OpenPGP software may issue a {term}`certification` that Bob h Take, for instance, a scenario where Bob's OpenPGP software issues a {term}`certification` confirming as legitimate the link between the {term}`User ID` `Alice Adams ` and the {term}`certificate` bearing the {term}`fingerprint` `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. -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. +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-certifications`.