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

fold "goals" into ch1

Browse source
This commit is contained in:
Heiko Schaefer 2023-09-15 13:05:07 +02:00
parent 5d5079ccb8
commit 8e63fe49c9
No known key found for this signature in database
GPG key ID: 4A849A1904CCBD7D
3 changed files with 64 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -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.

63
book/source/02-goals.md
View file

@ -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.

1
book/source/index.rst
View file

@ -6,7 +6,6 @@ Notes on OpenPGP
:maxdepth: 3
01-intro.md
02-goals.md
03-highlevel.md
04-certs.md
05-private.md