diff --git a/book/source/02-goals.md b/book/source/02-goals.md index bd8e151..18256c5 100644 --- a/book/source/02-goals.md +++ b/book/source/02-goals.md @@ -1,40 +1,63 @@ # Goals of this document -``` -Target audience: developers (not end users) +There are three groups of people who interact with OpenPGP: -Prior knowledge of the reader? -- Software development -- Basics of encryption +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 -Entry point to writing software that uses OpenPGP +This document is focused at the second of these groups: +software developers who use OpenPGP functionality in their software projects. -Help to getting started as a user of any implementation (OpenPGP JS, Sequoia PGP, ...) +It is not intended for end-users who use software that contains OpenPGP functionality. -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. -This text aims to describe OpenPGP at the "library-level." -``` +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 [OpenPGP Standard](https://www.rfc-editor.org/rfc/rfc4880.html) defines -*"format and methods"* to *"provide services including confidentiality, key -management, authentication, and digital signatures"*. +``` +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. +``` -This chapter is intended as a companion to the RFC. It does not aim to teach -cryptographic concepts. +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. The idea is to go over various common OpenPGP artifacts, as they are currently used, to get an overview. -There are lots of details that these notes will not cover. +We will also ignore most details about how OpenPGP artifacts are encoded at the lowest level. -Among these omitted details are differences between current v4 artifacts and -older variants, which were used in previous incarnations of (Open)PGP. -(Note: OpenPGP v3 artifacts are still in use as of this writing, the RFC -requires implementations to accept them. v3 artifacts are still very +## 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 v3 artifacts are still in use as of this writing (in 2023). + +``` +FIXME: fact check the status of v3 and v4 in crytpo refresh: + +the RFC requires implementations to accept them. v3 artifacts are still very much relevant for real world OpenPGP usage and implementations) - -We will also ignore most details about how OpenPGP artifacts are encoded, as -well as how OpenPGP data is arranged to allow for streaming operation. +``` \ No newline at end of file