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

Merge branch 'draft' into tammi-ch4

Browse source
This commit is contained in:
Tammi L. Coles 2023-10-12 12:07:20 +00:00
commit e5625f43db
4 changed files with 77 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -10,6 +10,13 @@ This text is *not* intended as a guide for end-users of OpenPGP-related software
OpenPGP is an open standard for cryptographic operations. It is a system based on well-understood cryptographic building blocks. OpenPGP supports the secure delivery of files and messages between a sender and a recipient as well as verification of the sender. OpenPGP is an outgrowth of the ["Pretty Good Privacy (PGP)"](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) encryption program and has many widely used and [interoperable implementations](interop_section).
With OpenPGP, you can:
- [Encrypt](encryption_chapter) and [decrypt](decryption_chapter) messages
- [Sign](signing_data) and [verify](verification_chapter) data
- [Issue certifications and examine statements](certifications_chapter) about keys and identities, similar to the role of a Certificate Authority in validating identities.
To enable these operations, OpenPGP utilizes a set of [established cryptographic mechanisms](cyrptography_chapter). These building blocks are integrated into OpenPGP's standard, which also addresses identities and their verification.
## Who is the audience for this document?
@ -25,6 +32,15 @@ This document is focused on the second group, application developers, who use Op
:class: warning
Heiko, we should elaborate a bit on why here
arguments:
- standardized cryptographic system
- long history, broard support
- lately: many high-quality, modern, library implementations (in the past there were no good ways to integrate openpgp into applications)
- the new version of the standard is almost ready, defining a modernized version 6 of the protocol
- all of this together: it's now easier than ever to add openpgp functionality to applications, and the updated standard brings the cryptographic building blocks up to the state of the art
```
This document is not intended for end-users. It is also not for implementers of OpenPGP libraries (or other software that directly handles internal OpenPGP data structures).

125
book/source/02-highlevel.md
View file

@ -2,14 +2,17 @@
## Why OpenPGP?
OpenPGP is an IETF-standardized set of cryptographic operations. OpenPGP defines mechanisms for authentication of cryptographic identities with a decentralized trust model.
OpenPGP is a widely recognized, IETF-standardized set of cryptographic operations. It is broadly used in securing communications, for example, in encrypted text messages and email, and enjoys a vast ecosystem of libraries, tools, and community support forums. Moreover, its robustness and versatility has made OpenPGP a security choice for other use cases in which encryption is important. These include file transfer applications, password managers, and secure data storage.
```{admonition} TODO
:class: warning
There are other compelling reasons for why you might consider using OpenPGP in your project:
David points out: this section does not yet constitute a compelling endorsement.
(-> more/better text needed)
```
1. **Decentralized trust model**: OpenPGP's decentralization defines mechanisms for authentication that allow individuals and entities to create and manage their own cryptographic identities. Unlike centralized trust models, decentralized trust models empower individuals and entities to manage their own identities, fostering a community-driven web of trust instead of relying on a centralized authority, thus reducing single points of failure.
2. **End-to-end encryption**: OpenPGP provides a robust framework for implementing end-to-end encryption. Content remains confidential, verifiable, authenticated, and protected against unauthorized access, even when the communication channel itself might be otherwise compromised. Encryption is crucial in a myriad of scenarios, particularly when transmitting sensitive information such as financial data, personally identifiable information (PII), or proprietary business data.
3. **Anonymity and pseudonymity**: In sensitive and volatile situations where identity protection is crucial, OpenPGP can be used to provide a level of anonymity or pseudonymity that helps protect user identities. For example, OpenPGP has been used alongside other privacy tools, such as Tor and VPNs, to provide secure and anonymous communication for whistleblowers, human rights lawyers, activists in repressive regimes, and journalists, reducing their risks for retaliation and state violence.
4. **Interoperability**: OpenPGP is a well-structured and standardized protocol, widely adopted by various public and private entities but not tied to any particular vendor's technology. It supports all major operating systems, such as Windows, macOS, GNU/Linux, Android, and iOS. Because of standardization, wide adoption, cross-platform compatibility, and adaptability, OpenPGP's interoperability significantly contributes to reducing development time, costs, and technical hurdles.
## A very brief history
@ -17,103 +20,77 @@ The OpenPGP standard has evolved over time, and remains under active development
(Also see [https://www.openpgp.org/about/history/](https://www.openpgp.org/about/history/))
### "Pretty Good Privacy (PGP)"
### Pretty Good Privacy (PGP)
The earliest roots of OpenPGP trace back to *"Pretty Good Privacy (PGP)"*, a software program written by [Phil Zimmermann](https://en.wikipedia.org/wiki/Phil_Zimmermann) and first released in 1991.
The origins of OpenPGP can be traced back to *Pretty Good Privacy (PGP)*, a software program written by [Phil Zimmermann](https://en.wikipedia.org/wiki/Phil_Zimmermann) and first released in 1991.
The original PGP software has played a role in the political struggles sometimes referred to as the ["Crypto Wars"](https://en.wikipedia.org/wiki/Crypto_Wars) (also see ["Crypto: How the Code Rebels Beat the Government Saving Privacy in the Digital" (2002)](https://en.wikipedia.org/wiki/Crypto_(book)) for some of that history, including part of the history of PGP).
The original PGP software played a role in the political struggles sometimes referred to as the ["Crypto Wars"](https://en.wikipedia.org/wiki/Crypto_Wars) (also see ["Crypto: How the Code Rebels Beat the Government Saving Privacy in the Digital" (2002)](https://en.wikipedia.org/wiki/Crypto_(book)), which includes some of PGP's history).
The original "PGP" software was never under a Free Software license, even though its source code has at one point been widely published.
The ownership and branding of the product has [changed over the years](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#PGP_Corporation_and_Symantec). The software enjoys a continued existence, albeit with [changing name and scope](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#PGP_Corporation_encryption_applications).
The original PGP software was never under a Free Software license, despite its source code being widely published by its author. [PGP's ownership has changed over the years](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#PGP_Corporation_and_Symantec), and [PGP's scope and suite of products have expanded] (https://en.wikipedia.org/wiki/Pretty_Good_Privacy#PGP_Corporation_encryption_applications).
### Standardizing OpenPGP
While the original PGP software was developed as a commercial product, the owner at the time, "PGP Inc." started a standardization effort with the IETF, first publishing [RFC 1991 "PGP Message Exchange Formats"](https://datatracker.ietf.org/doc/html/rfc1991) in August 1996.
While PGP was first developed as commercial software, the owner at the time, PGP Inc., started a standardization effort with the IETF, first publishing [RFC 1991 "PGP Message Exchange Formats"](https://datatracker.ietf.org/doc/html/rfc1991) in August 1996.
In July 1997, a process to produce an open standard under the then new name [OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) was started, resulting in [RFC 2440 "OpenPGP Message Format"](https://datatracker.ietf.org/doc/html/rfc2440), published November 1998. RFC 2440 describes OpenPGP version 3.
In July 1997, a process to produce an open standard under the then new name [OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) was started, resulting in [RFC 2440 "OpenPGP Message Format"](https://datatracker.ietf.org/doc/html/rfc2440), published in November 1998. RFC 2440 describes OpenPGP version 3.
The name "OpenPGP" can be used freely by implementations (unlike the name "PGP", which is a [registered trademark](https://uspto.report/TM/74685229)).
The name OpenPGP can be used freely by implementations, unlike the name PGP, which is a [registered trademark](https://uspto.report/TM/74685229)).
### GnuPG, an early Free Software implementation
[First released 1997-12-20](https://gnupg.org/download/release_notes.html#sec-2-70), GnuPG (the "GNU Privacy Guard") is an implementation of the OpenPGP standard.
[First released 1997-12-20](https://gnupg.org/download/release_notes.html#sec-2-70) by Werner Koch, a German computer programmer, GNU Privacy Guard (GnuPG) is a free and open-source implementation of the OpenPGP standard.
GnuPG has been a major early Free Software implementation of OpenPGP. It has played an important (and successful) role in the [release of NSA documents](https://theintercept.com/2014/10/28/smuggling-snowden-secrets/) by [Edward Snowden](https://en.wikipedia.org/wiki/Edward_Snowden).
GnuPG was a major early implementation of OpenPGP. Over the years, the importance of GnuPG has grown significantly as it became a foundational tool for email security, software signing, and more. It played an important (and successful) role in the [release of NSA documents](https://theintercept.com/2014/10/28/smuggling-snowden-secrets/) by [Edward Snowden](https://en.wikipedia.org/wiki/Edward_Snowden).
The GnuPG program binary is called `gpg`, thus the names "GnuPG" and "gpg" are often used interchangeably.
Note: The terms "pgp key" and "gpg key" are sometimes used. Since PGP and GnuPG are just two of many existing OpenPGP implementations, the proper term is "OpenPGP key" (or "OpenPGP certificate", more on that [later](certificates_chapter)).
Because the GnuPG program binary is called "gpg," "GnuPG" and "gpg" are often used interchangeably.
## The OpenPGP version 4 era
### OpenPGP version 4
In 2007, [RFC 4880](https://datatracker.ietf.org/doc/html/rfc4880), defining version 4 of OpenPGP, was published. This version is currently most commonly used in the wild.
In 2007, the IETF published [RFC 4880](https://datatracker.ietf.org/doc/html/rfc4880), which defined version 4 of the OpenPGP standard. As of late 2023, version 4 is the most commonly used version.
(major_implementations)=
### Multiple major implementations
Today multiple new Free Software implementations of OpenPGP play important roles:
### Major implementations of OpenPGP
- Proton Mail, who provide email encryption services for a large number of users, use (and maintain) [OpenPGP.js](https://openpgpjs.org/) as well as [GopenPGP](https://gopenpgp.org/).
- The Thunderbird email software is using the [RNP](https://www.rnpgp.org/) implementation for their built-in OpenPGP support since version 78 (released in mid-2020).
- The RPM Package Manager software includes an OpenPGP backend based on [Sequoia PGP](https://sequoia-pgp.org/), a modern OpenPGP implementation in Rust. Fedora [uses Sequoia PGP in rpm](https://sequoia-pgp.org/blog/2023/04/27/rpm-sequoia/) since version 38.
Today, multiple implementations of OpenPGP play important roles:
## The road ahead
### OpenPGP version 6
As of this writing (in 2023), [version 6 of OpenPGP](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/) is approaching publication as an RFC.
The IETF working group's [charter](https://datatracker.ietf.org/wg/openpgp/about/#autoid-1) centers around updating the cryptographic mechanisms, adding new algorithms, and deprecation of obsolete algorithms.
This document describes OpenPGP version 6, while pointing out differences to previous versions that are relevant to application developers.
Significant work on support for OpenPGP version 6 has already been done for multiple implementations, including:
- [GOpenPGP](https://github.com/ProtonMail/gopenpgp/tree/v3),
- [OpenPGP.js](https://github.com/openpgpjs/openpgpjs/tree/v6),
- [PGPainless](https://github.com/pgpainless/pgpainless/milestone/6),
- [PGPy](https://github.com/dkg/PGPy/tree/dkg/crypto-refresh),
- [Sequoia-PGP](https://gitlab.com/sequoia-pgp/sequoia/-/tree/crypto-refresh).
### Post-Quantum Cryptography in OpenPGP
There is [ongoing work](https://datatracker.ietf.org/doc/draft-wussler-openpgp-pqc/) to standardize and add support for post-quantum public-key algorithms in OpenPGP. This project is funded by the [german "BSI"](https://en.wikipedia.org/wiki/Federal_Office_for_Information_Security). Goals include adding support for post-quantum cryptography to Thunderbird and GnuPG. A [presentation](https://datatracker.ietf.org/meeting/113/materials/slides-113-openpgp-a-post-quantum-approach-for-openpgp-00) was given at [IETF 113](https://datatracker.ietf.org/meeting/113/session/openpgp/).
## Concepts
### Certificates/Keys
Use of OpenPGP is centered around cryptographic keys.
In OpenPGP, bare cryptographic keys are combined with additional metadata into "OpenPGP certificates," which are a relatively complex data structure (OpenPGP certificates are also often called "OpenPGP keys").
An OpenPGP certificate can evolve over time, with components being added, expiring, or being marked as invalid.
See the chapter about [OpenPGP certificates](certificates_chapter) for details, and internal structure, and the chapter about [private keys](private_key_chapter) for handling of private key material in OpenPGP.
Other important topics around certificates are their management, authentication, and trust models. We will only touch on those, in this document.
### High-Level operations
With OpenPGP it's possible to:
- [Encrypt](encryption_chapter) and [Decrypt](decryption_chapter) Messages
- [Sign](signing_data) and [Verify](verification_chapter) Data
- [Issue and examine Statements](certifications_chapter) about Keys and Identities (to perform CA-like functionality)
### Building blocks
To perform these high-level operations, a set of [established cryptographic mechanisms](cyrptography_chapter) are used as building blocks, and combined into OpenPGP's format, which additionally deals with identities and their verification.
- Proton Mail, which provides email encryption services for a large number of users, uses and maintains [OpenPGP.js](https://openpgpjs.org/) as well as [GopenPGP](https://gopenpgp.org/), an OpenPGP wrapper library written in golang.
- The Mozilla Thunderbird email software uses [RNP](https://www.rnpgp.org/), its C++ implementation of OpenPGP.
- The RPM Package Manager software includes an OpenPGP backend based on [Sequoia PGP](https://sequoia-pgp.org/), a modern OpenPGP implementation written in Rust. The Fedora operating system, Fedora Linux 38, [uses Sequoia PGP in rpm](https://sequoia-pgp.org/blog/2023/04/27/rpm-sequoia/).
(interop_section)=
## Interoperability
### Interoperability
OpenPGP was standardized in 1997 to encourage development of interoperable implementations. This has already been a success early on, but in recent years, there has been [much development of new implementations](major_implementations).
Historically, interoperability has only been tested in an adhoc manner. Since 2019, the Sequoia project is maintaining and operating the ["OpenPGP interoperability test suite"](https://tests.sequoia-pgp.org/), for more rigorous and systematic testing. The test suite has identified numerous [issues](https://gitlab.com/sequoia-pgp/openpgp-interoperability-test-suite#hall-of-fame).
## The road ahead
```{note}
Software and protocol development sometimes skips version numbers due to reasons like internal testing, significant changes, avoiding confusion, marketing decisions, or technical issues. The official successor to OpenPGP version 4 is OpenPGP version 6, detailed below.
```
### OpenPGP version 6
As of this writing (in 2023), [version 6 of OpenPGP](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/) is approaching publication as an RFC.
The [IETF OpenPGP working group](https://datatracker.ietf.org/wg/openpgp/about/#autoid-1) is focused on updating the cryptographic mechanisms, adding new algorithms, and the deprecation of obsolete algorithms.
This document describes OpenPGP version 6, while pointing out differences to previous versions that are relevant to application developers.
Significant support for OpenPGP version 6 has already been achieved for multiple implementations, including:
- [Bouncy Castle Java](https://github.com/bcgit/bc-java/issues/1421),
- [GopenPGP](https://github.com/ProtonMail/gopenpgp/tree/v3),
- [OpenPGP.js](https://github.com/openpgpjs/openpgpjs/tree/v6),
- [PGPy](https://github.com/dkg/PGPy/tree/dkg/crypto-refresh),
- [Sequoia PGP](https://gitlab.com/sequoia-pgp/sequoia/-/tree/crypto-refresh).
### Post-quantum cryptography in OpenPGP
There is [ongoing work](https://datatracker.ietf.org/doc/draft-wussler-openpgp-pqc/) to standardize and add support for post-quantum public-key algorithms in OpenPGP. This project is funded by the [german "BSI"](https://en.wikipedia.org/wiki/Federal_Office_for_Information_Security). Goals include adding support for post-quantum cryptography to Thunderbird and GnuPG. A [presentation](https://datatracker.ietf.org/meeting/113/materials/slides-113-openpgp-a-post-quantum-approach-for-openpgp-00) was given at [IETF 113](https://datatracker.ietf.org/meeting/113/session/openpgp/).
## Zooming in: Internal structure of OpenPGP data
OpenPGP data is internally structured as "packets." We'll look into examples of this internal structure throughout the following chapters.

6
book/source/03-cryptography.md
View file

@ -95,9 +95,13 @@ Only the public part of an asymmetric key pair
OpenPGP makes heavy use of public-key cryptography, both for encryption and signing operations.
Note that, for historical reasons, the OpenPGP RFC and other documentation often use the non-standard term "secret key" instead of the more common "private key."
```{admonition} Terminology
:class: note
For historical reasons, the OpenPGP RFC and other documentation often use the non-standard term "secret key" instead of the more common "private key."
So in OpenPGP, the pair of terms "public/secret key" is sometimes used instead of the more common "public/private key."
```
### Cryptographic digital signatures

5
book/source/conf.py
View file

@ -29,8 +29,13 @@ exclude_patterns = []
html_theme = 'alabaster'
html_static_path = ['_static']
html_show_sphinx = False
html_show_copyright = False
html_show_sourcelink = False
# https://github.com/sphinx-doc/alabaster/blob/0.x/alabaster/theme.conf
html_theme_options = {
'code_font_size': '9pt',
'show_relbars': 'yes',
'show_powered_by': False,
}