vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2024-11-27 01:52:06 +01:00
Code Issues Projects Releases Packages Wiki Activity

edit audience and RFC sections

Browse source
This commit is contained in:
Tammi L. Coles 2023-09-15 15:51:31 +02:00
parent ca6b69897d
commit 82a9aca693
1 changed files with 22 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
book/source/01-intro.md
View file

@ -15,61 +15,38 @@ Heiko, let's be sure to create our own page on interoperability instead of linki
## Who is the audience for this document? ## Who is the audience for this document?
Three groups of people interact with OpenPGP: OpenPGP is a system based on well-understood cryptographic building blocks. 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 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 3. Implementers of libraries or software that handles the processing of internal OpenPGP data structures
This document is focused on software developers who use OpenPGP functionality in their software projects. It is not intended for end-users. This document is focused on the second group, software 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).
{::comment} {::comment}
Heiko, we should elaborate a bit on why here Heiko, we should elaborate a bit on why here
{:/comment} {:/comment}
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).
### Requirements This document is not intended for end-users. It is also not for implementers of libraries or software.
We presuppose solid knowledge of 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 ## Why not just use 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/) The [OpenPGP RFC](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/)
defines *"the message formats used in OpenPGP"* to *"provide encryption with defines *the message formats used in OpenPGP* to *provide encryption with public-key or symmetric cryptographic algorithms, digital signatures, compression and key management.*
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. The RFC explains details (what goes where) that are crucial for implementers of software that handle internal OpenPGP data structures. However, it is not as critical for software developers who use OpenPGP through a library.
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, ignoring much about how OpenPGP artifacts are encoded at the lowest level to address common OpenPGP artifacts as they are
This document describes OpenPGP concepts at the "library" level of abstraction, currently used.
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 ## Which version of OpenPGP does this address?
currently used, to get an overview.
### Covering versions The documentation will mainly cover version 4 of OpenPGP, while occasionally noting differences to previous versions that are relevant to application developers.
We will mainly cover v6 of OpenPGP, but occasionally point out Version 4 of OpenPGP will remain relevant for a number of years;
differences to previous versions. some version 3 artifacts are still in use as of this writing.
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.