diff --git a/book/source/01-intro.md b/book/source/01-intro.md index ff961af..475982b 100644 --- a/book/source/01-intro.md +++ b/book/source/01-intro.md @@ -18,3 +18,67 @@ software. OpenPGP is an open standard, there are many widely used (and [interoperable](https://tests.sequoia-pgp.org/)) implementations. + +## Goals of this document + +There are three groups of people who interact with OpenPGP: + +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 libraries or software that handles the processing of internal OpenPGP data structures + +This document is focused at the second of these groups: +software developers who use OpenPGP functionality in their software projects. + +It is not intended for end-users who use software that contains OpenPGP functionality. + +This text aims to describe OpenPGP at the "library-level": +we teach the concepts that will help you get started as a user of any implementation +(such as OpenPGP JS, Sequoia PGP, ...) + +### Requirements + +We presuppose solid knowledge in both software development concepts, +and of general cryptographic concepts. + +OpenPGP is a system based on well-understood cryptographic building blocks. +We describe the properties of the OpenPGP system, and how to use it. + +### A companion for the OpenPGP RFC + +``` +The RFC explains lots of details (which bit goes where) that are crucial +for implementers, but unimportant for software developers who use OpenPGP +through a library. +``` + +The [OpenPGP RFC](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/) +defines *"the message formats used in OpenPGP"* to *"provide encryption with +public-key or symmetric cryptographic algorithms, digital signatures, +compression and key management"*. + +The RFC, as a standards document, is mainly aimed at the third group: +Implementers of software that handles internal OpenPGP data structures. +In that context, the nitty-gritty of which bit of data goes where is crucial. + +For software developers using OpenPGP through a library, however, it is not. +This document describes OpenPGP concepts at the "library" level of abstraction, +and ignores most details about how OpenPGP artifacts are encoded at the lowest level. + +The idea is to go over various common OpenPGP artifacts, as they are +currently used, to get an overview. + +### Covering versions + +We will mainly cover v6 of OpenPGP, but occasionally point out +differences to previous versions. + +Version 4 of OpenPGP will remain relevant for a number of years, +and some OpenPGP version 3 artifacts are still in use as of this writing (in 2023). + +For example, the RFC states that implementations MAY accept version 3 signatures. +Handling version 3 artifacts is relevant in some contexts, where dealing with +historical OpenPGP material is required. + +Where differences between versions may be relevant to application developers, +we will point them out. diff --git a/book/source/02-goals.md b/book/source/02-goals.md deleted file mode 100644 index 7c0045f..0000000 --- a/book/source/02-goals.md +++ /dev/null @@ -1,63 +0,0 @@ -# Goals of this document - -There are three groups of people who interact with OpenPGP: - -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 libraries or software that handles the processing of internal OpenPGP data structures - -This document is focused at the second of these groups: -software developers who use OpenPGP functionality in their software projects. - -It is not intended for end-users who use software that contains OpenPGP functionality. - -This text aims to describe OpenPGP at the "library-level": -we teach the concepts that will help you get started as a user of any implementation -(such as OpenPGP JS, Sequoia PGP, ...) - -## Requirements - -We presuppose solid knowledge in both software development concepts, -and of general cryptographic concepts. - -OpenPGP is a system based on well-understood cryptographic building blocks. -We describe the properties of the OpenPGP system, and how to use it. - -## A companion for the OpenPGP RFC - -``` -The RFC explains lots of details (which bit goes where) that are crucial -for implementers, but unimportant for software developers who use OpenPGP -through a library. -``` - -The [OpenPGP RFC](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/) -defines *"the message formats used in OpenPGP"* to *"provide encryption with -public-key or symmetric cryptographic algorithms, digital signatures, -compression and key management"*. - -The RFC, as a standards document, is mainly aimed at the third group: -Implementers of software that handles internal OpenPGP data structures. -In that context, the nitty-gritty of which bit of data goes where is crucial. - -For software developers using OpenPGP through a library, however, it is not. -This document describes OpenPGP concepts at the "library" level of abstraction, -and ignores most details about how OpenPGP artifacts are encoded at the lowest level. - -The idea is to go over various common OpenPGP artifacts, as they are -currently used, to get an overview. - -## Covering versions - -We will mainly cover v6 of OpenPGP, but occasionally point out -differences to previous versions. - -Version 4 of OpenPGP will remain relevant for a number of years, -and some OpenPGP version 3 artifacts are still in use as of this writing (in 2023). - -For example, the RFC states that implementations MAY accept version 3 signatures. -Handling version 3 artifacts is relevant in some contexts, where dealing with -historical OpenPGP material is required. - -Where differences between versions may be relevant to application developers, -we will point them out. diff --git a/book/source/index.rst b/book/source/index.rst index 871b1e7..13b1dde 100644 --- a/book/source/index.rst +++ b/book/source/index.rst @@ -6,7 +6,6 @@ Notes on OpenPGP :maxdepth: 3 01-intro.md - 02-goals.md 03-highlevel.md 04-certs.md 05-private.md