commit c8054b91203181baee9dc6d8ed665dd4730a3e25 Author: Heiko Schaefer Date: Thu Sep 14 21:30:43 2023 +0200 Initial outline and old notes (Rough merge of two precursor projects by Heiko, and outline notes by Paul) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..df84cb6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.idea +book/build/ + diff --git a/book/Makefile b/book/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/book/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/book/make.bat b/book/make.bat new file mode 100644 index 0000000..dc1312a --- /dev/null +++ b/book/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/book/source/01-intro.md b/book/source/01-intro.md new file mode 100644 index 0000000..3b4a0d0 --- /dev/null +++ b/book/source/01-intro.md @@ -0,0 +1,82 @@ +# OpenPGP: what is it, history + +This document is intended as an introduction to the inner workings of OpenPGP, +aimed mainly at technical readers. + +It is *not* a guide for *use* of OpenPGP by end-users. + +## What is OpenPGP? + +OpenPGP is an open standard that was developed based on the +["Pretty Good Privacy (PGP)"](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) +software. + +The standard has evolved over time, and there is ongoing work to improve it. +[RFC 4880](https://datatracker.ietf.org/doc/html/rfc4880) is the most recent +published version of the standard (describing OpenPGP version 4). + +An IETF working group is currently finalizing a +[new revision](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/), +of the OpenPGP standard (which will describe OpenPGP version 6). +The current standardization work focuses on updating the cryptographic +mechanisms in OpenPGP. + +There are multiple [interoperable](https://tests.sequoia-pgp.org/) +implementations with significant use. + +## A very brief history (dramatis personae) + +### PGP + +*"Pretty Good Privacy (PGP)"* is a software program, initially by Phil +Zimmermann, first released in 1991. + +The 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 https://en.wikipedia.org/wiki/Crypto_(book) for some of that history, +including about the history of PGP). + +The "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). + + +### OpenPGP + +While the PGP software was developed as a commercial product, the owner at the time, +"PGP Inc." started a standardization effort with the IETF in July 1997. +The resulting open standard was named +[OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP). + +The result of this first round of standardization work under the "OpenPGP" +name is [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440), +published November 1998. + +The name "OpenPGP" can be used freely by implementations (unlike the name +"PGP", which is a [registered trademark](https://uspto.report/TM/74685229)). + +### GnuPG + +[First released 1997-12-20](https://gnupg.org/download/release_notes.html#sec-2-70), +GnuPG is an implementation of the OpenPGP standard. + +GnuPG has been the major Free Software implementation of OpenPGP for a period +of time. It has played a role in the release of NSA documents by +[Edward Snowden](https://theintercept.com/2014/10/28/smuggling-snowden-secrets/) + +## Multiple major implementations + +Today, multiple implementations of OpenPGP play an important role: + +- Protonmail, who serve a large number of users, use (and maintain) +[OpenPGP.js](https://openpgpjs.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. diff --git a/book/source/02-goals.md b/book/source/02-goals.md new file mode 100644 index 0000000..bd8e151 --- /dev/null +++ b/book/source/02-goals.md @@ -0,0 +1,40 @@ +# Goals of this document + +``` +Target audience: developers (not end users) + +Prior knowledge of the reader? +- Software development +- Basics of encryption + +Entry point to writing software that uses OpenPGP + +Help to getting started as a user of any implementation (OpenPGP JS, Sequoia PGP, ...) + +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." +``` + +## 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"*. + +This chapter is intended as a companion to the RFC. It does not aim to teach +cryptographic concepts. + +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. + +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 +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. diff --git a/book/source/03-highlevel.md b/book/source/03-highlevel.md new file mode 100644 index 0000000..1a073ec --- /dev/null +++ b/book/source/03-highlevel.md @@ -0,0 +1,6 @@ +# A high-level view + +``` +- ? +- Introduce Packet/Subpacket concepts (?) +``` diff --git a/book/source/04-certs.md b/book/source/04-certs.md new file mode 100644 index 0000000..13fb794 --- /dev/null +++ b/book/source/04-certs.md @@ -0,0 +1,759 @@ +# Certificates / Keys + +``` +## What is in a certificate (Structure) + +### Subkeys + +### User IDs / attributes + - Primary UserID and its implications + +### Third party signatures + - Metadata Leak of Social Graph + - How to generate "minimized" certificate? + +### Bindings + +### Signature Subpackets + +- (key-) expiration +- flags + +## Certificate Management + +### Merging + - How to merge two copies of the same certificate? + - Canonicalization + +### Best Practices regarding Key Freshness + - Expiry + - Subkey rotation +``` + +One central (and non-trivial) element of OpenPGP are certificates/keys. +OpenPGP keys are relatively complex data structures, so it's good to have +a clear mental model of them. + +## Terminology: on the various meanings of "key" + +In the OpenPGP space, the term "key" has historically been used for three +distinct concepts, at three layers, all related to each other: + +- (Bare) "cryptographic keys" (without additional metadata). +- OpenPGP *component keys*: "OpenPGP primary keys" and "OpenPGP subkeys". + Those are building blocks of OpenPGP certificates, + they consist of a (bare) cryptographic keypair, plus metadata. +- "OpenPGP key" (or "OpenPGP certificate"): + These consist of a number of component keys plus additional elements, + such as identity information. + (OpenPGP key servers serve this type of object). + +In the following section we'll look more closely at these three layers. + +## "OpenPGP keys/certificates": collections of cryptographic keys, identity information and other metadata + +A complete "OpenPGP certificate" or "OpenPGP key" is composed of an +arbitrary number of elements. + +All elements of an OpenPGP certificate are structured around one central +cryptographic key: the *primary key*. +The primary key acts like a personal CA for the key's owner: +It can make cryptographic statements about subkeys, identities, +expiration times, revocation, ... + +OpenPGP keys are often long-lived and may be changed (typically by their +owner), over time. + +### OpenPGP component keys + +An OpenPGP component key (either the "primary key", or a "subkey") +consists mainly of a cryptographic keypair: + +![Image](diag/cryptographic_keys.png "A cryptographic keypair") + +A cryptographic keypair consists of a private and a public part. +In this document we'll show the public part of a cryptographic key in green, +and the private part in red. + +We'll visualize cryptographic keypairs in a more compact form: + +![Image](diag/keypair.png "A cryptographic keypair") + +(In some contexts, instead of the full cryptographic keypair, only the +public part is present. More on that later.) + +An OpenPGP component key consists of + +- a cryptographic keypair, and +- additional metadata (including a creation timestamp). + +![Image](diag/primary_key.png "An OpenPGP component key") + +For each OpenPGP component key, an *OpenPGP fingerprint* can be derived +from the combination of key material and metadata: + +![Image](diag/fingerprint.png "Each OpenPGP component key has a fingerprint") + +The fingerprint of our example component OpenPGP key is +`B3D2 7B09 FBA4 1235 2B41 8972 C8B8 6AC4 2455 4239` [^keyid]. + +The fingerprint of the primary key has a central role. +It is used as the unique identifier for the full OpenPGP certificate. + + +## Components of an OpenPGP key/certificate + +In addition to the primary key, OpenPGP keys/certificates can contain a +number of other components: + +### Subkeys + +Modern OpenPGP keys/certificates contain "subkeys" in addition to the primary key. + +![Image](diag/with_subkeys.png "OpenPGP certificates can contain any number of subkeys") + +A component key consists of a cryptographic keypair, plus some additional metadata. + +Each component key (this includes the primary key, and all subkeys) has a +marker that specifies which operations the component key can perform. + +#### Excursion, "Key Flags": defining what operations a component key can perform + +Each component key has +["Key Flags"](https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.21) +that specify which types of operation the key can perform. + +The commonly used flags are: + +- **C**ertification +- **S**igning +- **E**ncryption +- **A**uthentication + +Only the primary key can perform "certification" operations. +All other operations can technically be performed by either the primary +key or subkeys. + +It is considered good practice to have separate component keys for each +type of operation (specifically: to allow only *Certification* operations +for the primary key, and to have separate *Signing*, *Encryption* and +*Authentication* subkeys). + + +### User IDs + +An OpenPGP certificate can contain any number of User IDs. +Each user ID associates the certificate with an identity. + +Typically, these identities are composed of a name and an email address. + +![Image](diag/user_id.png "OpenPGP certificates can contain any number of User IDs") + +### User attributes + +User attributes are similar to User IDs, but less commonly used. + + +## Linking the components of an OpenPGP certificate together + +Technically, an OpenPGP certificate consists of a sequence of OpenPGP packets. +These packets are just stringed together, one after the other. +When you have a file that contains a copy of someone's certificate, +it's easy to remove some of these packets, or add new ones. + +However, as the owner of a certificate, I don't want a third party to +add additional subkeys (or identity claims) to my certificate. I don't want +third parties to pretend that those components were put there by me. + +To prevent such malicious addition of components, OpenPGP uses cryptographic +signatures. These signatures show the cryptographic identity that has linked +a component to an OpenPGP certificate (in many cases, the linking is done +by the primary key of the certificate in question). + +So while anyone can still unilaterally put subkeys and identity claims +into a file with my OpenPGP certificate, OpenPGP implementations that +read the file are expected to discard components that aren't +cryptographically linked to my certificate. + +### "Binding" subkeys to an OpenPGP certificate + +Linking a subkey to an OpenPGP certificate is done with a +["Subkey Binding Signature"](https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.1). +Such a signature signals that the "primary key wants to be associated with the subkey". + +The subkey binding signature also adds metadata. + +![Image](diag/subkey_binding.png "Linking an OpenPGP subkey to the primary key with a binding signature") + +#### Binding signing subkeys + +When binding a signing subkey to a primary key, it is not sufficient that the "primary +key wants to be associated with the subkey". In addition, the subkey must signal that +it wants to be associated with that primary key. + +Otherwise, Alice could "adopt" Bob's signing subkey and convincingly claim +that she made signatures that were in fact issued by Bob. + +This additional "Primary Key Binding Signature" is informally called +a "back signature" (because the subkey uses the signature to point "back" +to the primary key). + + +### Certifying identity claims + +OpenPGP certificate often contain identity markers. Typically in the form +of "User ID"s (however, User Attributes are analogous for the purpose of +this section). + +For example, above, we saw the User ID "Alice Adams " +associated with Alice's key `B3D2 7B09 FBA4 1235 2B41 8972 C8B8 6AC4 2455 4239`. + +Alice can link a User ID to her OpenPGP certificate with a cryptographic +signature. To link a User ID, a signature of the type `PositiveCertification` +is created. The signature is issued using the primary (secret) key. + +![Image](diag/user_id_certification.png "Linking a User ID to an OpenPGP certificate") + + +## Evolution of a certificate over time + +Minimized versions, merging, effective "append only" semantics, ... + +## Third party (identity) certifications + +## Revocations + +[^keyid]: Sometimes, a shortened (64 bit) version of the fingerprint is used instead +of the full fingerprint, like this: `C8B8 6AC4 2455 4239` (the rightmost +64 bit of the fingerprint). This type of identifier is called a "Key ID". +Historically, 32 bit shorthand identifiers have been used with PGP, +like this: `2455 4239`. You may still see such identifiers in very old +documents about PGP, but 32 bit identifiers have +[been unfit for purpose for a long time](https://evil32.com/). +At some point, 32 bit identifiers were called "short Key ID", while +64 bit identifiers were called "long Key ID". + +## Looking at the internal details + +To use OpenPGP, we need "(OpenPGP) keys". + +There is an ongoing effort to establish new terminology around "keys". In +particular to use the term "certificate" instead of "(OpenPGP) public key". + +Note: there is also the related, but distinct, concept of +[cryptographic "keys"](https://en.wikipedia.org/wiki/Key_(cryptography)). +OpenPGP certificates/keys contain one or more cryptographic key(s), among +many other components. + +An OpenPGP certificate/key consists of a number of elements, many of them +optional. OpenPGP certificates/keys always make use of +[Public-key cryptography (asymmetric cryptography)](https://en.wikipedia.org/wiki/Public-key_cryptography). + +As a consequence, some elements of OpenPGP certificates/keys represent +"private" (sometimes referred to as "secret") key material, while other +elements represent "public" key material. +Yet other elements contain metadata, and finally there are elements that +serve as glue ("binding") between the various other elements of a +certificate. + +To hand out copies of one's OpenPGP key to third parties, +implementations can generate a "certificate" / "public key" representation +([Transferable Public Keys](https://tools.ietf.org/html/rfc4880#section-11.1) +in the RFC), +which consists of all the elements of the certificate, except for +the private key material (and the optional +[S2K configuration](https://tools.ietf.org/html/rfc4880#section-3.7.2.1)). + +The counterpart is called +[Transferable Secret Keys](https://tools.ietf.org/html/rfc4880#section-11.2) +in the RFC. That is, an OpenPGP key that includes private key +material. + + +### A minimal OpenPGP key + +A minimal key can be made with Sequoia-PGP like this: + +`let (cert, _) = CertBuilder::new().generate()?;` + +#### Seen as a private OpenPGP key + +Viewed as a private key (in ASCII-armored representation), such a minimal key +looks like this: + +``` +-----BEGIN PGP PRIVATE KEY BLOCK----- +Comment: 6D10 0EB0 444D 1648 DAD9 A0EE DE83 CCF4 A204 F957 + +xVgEX7Kj9hYJKwYBBAHaRw8BAQdAztZjmUk3IUgnKwR9rfukVUt7UaVsvk+AoBtO +ZNbVqDcAAP4nrycHrmWHT8g454H/tr/19rT0nuPkYxMCUH9z5Atx/xLYwoMEHxYK +ADUFgl+yo/YDCwkHCRDeg8z0ogT5VwMVCggCmwECHgEWIQRtEA6wRE0WSNrZoO7e +g8z0ogT5VwAAbFgBAO1OYraoaDmFMZ7JWbLoTKW7xpDUNKB+kh+bdC6HjYpcAP9q +HhhgNE7noeQEsJmR0yW7tTYT8RyrJF6o2xZENlXdCw== +=/8Os +-----END PGP PRIVATE KEY BLOCK----- +``` + +Looking into the internals of this key with `sq packet dump --hex`, +or https://dump.sequoia-pgp.org/, we see that it is made up of a sequence +of "Packets": + +``` +Secret-Key Packet, new CTB, 2 header bytes + 88 bytes + Version: 4 + Creation time: 2020-11-16 16:08:22 UTC + Pk algo: EdDSA Edwards-curve Digital Signature Algorithm + Pk size: 256 bits + Fingerprint: 6D10 0EB0 444D 1648 DAD9 A0EE DE83 CCF4 A204 F957 + KeyID: DE83 CCF4 A204 F957 + + Secret Key: + + Unencrypted + + 00000000 c5 CTB + 00000001 58 length + 00000002 04 version + 00000003 5f b2 a3 f6 creation_time + 00000007 16 pk_algo + 00000008 09 curve_len + 00000009 2b 06 01 04 01 da 47 curve + 00000010 0f 01 + 00000012 01 07 eddsa_public_len + 00000014 40 ce d6 63 99 49 37 21 48 27 2b 04 eddsa_public + 00000020 7d ad fb a4 55 4b 7b 51 a5 6c be 4f 80 a0 1b 4e + 00000030 64 d6 d5 a8 37 + 00000035 00 s2k_usage + 00000036 00 fe eddsa_secret_len + 00000038 27 af 27 07 ae 65 87 4f eddsa_secret + 00000040 c8 38 e7 81 ff b6 bf f5 f6 b4 f4 9e e3 e4 63 13 + 00000050 02 50 7f 73 e4 0b 71 ff + 00000058 12 d8 checksum + +Signature Packet, new CTB, 2 header bytes + 131 bytes + Version: 4 + Type: DirectKey + Pk algo: EdDSA Edwards-curve Digital Signature Algorithm + Hash algo: SHA512 + Hashed area: + Signature creation time: 2020-11-16 16:08:22 UTC (critical) + Symmetric algo preferences: AES256, AES128 + Issuer: DE83 CCF4 A204 F957 + Hash preferences: SHA512, SHA256 + Key flags: C (critical) + Features: MDC + Issuer Fingerprint: 6D10 0EB0 444D 1648 DAD9 A0EE DE83 CCF4 A204 F957 + Digest prefix: 6C58 + Level: 0 (signature over data) + + 00000000 c2 CTB + 00000001 83 length + 00000002 04 version + 00000003 1f type + 00000004 16 pk_algo + 00000005 0a hash_algo + 00000006 00 35 hashed_area_len + 00000008 05 subpacket length + 00000009 82 subpacket tag + 0000000a 5f b2 a3 f6 sig creation time + 0000000e 03 subpacket length + 0000000f 0b subpacket tag + 00000010 09 07 pref sym algos + 00000012 09 subpacket length + 00000013 10 subpacket tag + 00000014 de 83 cc f4 a2 04 f9 57 issuer + 0000001c 03 subpacket length + 0000001d 15 subpacket tag + 0000001e 0a 08 pref hash algos + 00000020 02 subpacket length + 00000021 9b subpacket tag + 00000022 01 key flags + 00000023 02 subpacket length + 00000024 1e subpacket tag + 00000025 01 features + 00000026 16 subpacket length + 00000027 21 subpacket tag + 00000028 04 version + 00000029 6d 10 0e b0 44 4d 16 issuer fp + 00000030 48 da d9 a0 ee de 83 cc f4 a2 04 f9 57 + 0000003d 00 00 unhashed_area_len + 0000003f 6c digest_prefix1 + 00000040 58 digest_prefix2 + 00000041 01 00 eddsa_sig_r_len + 00000043 ed 4e 62 b6 a8 68 39 85 31 9e c9 59 b2 eddsa_sig_r + 00000050 e8 4c a5 bb c6 90 d4 34 a0 7e 92 1f 9b 74 2e 87 + 00000060 8d 8a 5c + 00000063 00 ff eddsa_sig_s_len + 00000065 6a 1e 18 60 34 4e e7 a1 e4 04 b0 eddsa_sig_s + 00000070 99 91 d3 25 bb b5 36 13 f1 1c ab 24 5e a8 db 16 + 00000080 44 36 55 dd 0b +``` + +We see that the key consists of two packets: + +* First a + [*"Secret-Key Packet"*](https://tools.ietf.org/html/rfc4880#section-5.5.1.3), + which contains the actual cryptographic key data. Note: the "Secret-Key" + Packet contains both the private and the public part of the key. + We also see in the output that this packet is "Unencrypted" (i.e. not + password-protected). +* Second a + [*"Signature Packet"*](https://tools.ietf.org/html/rfc4880#section-5.2) + of type 0x1F, *"Signature directly on a key"*. + This packet *"binds the information in the Signature subpackets to the key"*. + Each entry under "Signature Packet -> Hashed area" is one Signature + subpacket, + including for example information about algorithm preferences (*"Symmetric + algo preferences"* and *"Hash preferences"*). + +![Image](diag/key-minimal.png "A minimal OpenPGP key, visualized") + + +#### Seen as a public certificate + +Let's compare this with the same certificate seen as an armored "public" +certificate (that is, a variant of the key above, but without the private key +material. An OpenPGP user might give such a certificate to a +communication partner, so that the remote party could send encrypted +messages to the user): + +``` +-----BEGIN PGP PUBLIC KEY BLOCK----- +Comment: 6D10 0EB0 444D 1648 DAD9 A0EE DE83 CCF4 A204 F957 + +xjMEX7Kj9hYJKwYBBAHaRw8BAQdAztZjmUk3IUgnKwR9rfukVUt7UaVsvk+AoBtO +ZNbVqDfCgwQfFgoANQWCX7Kj9gMLCQcJEN6DzPSiBPlXAxUKCAKbAQIeARYhBG0Q +DrBETRZI2tmg7t6DzPSiBPlXAABsWAEA7U5itqhoOYUxnslZsuhMpbvGkNQ0oH6S +H5t0LoeNilwA/2oeGGA0Tueh5ASwmZHTJbu1NhPxHKskXqjbFkQ2Vd0L +=ZN14 +-----END PGP PUBLIC KEY BLOCK----- +``` + +``` +Public-Key Packet, new CTB, 2 header bytes + 51 bytes + Version: 4 + Creation time: 2020-11-16 16:08:22 UTC + Pk algo: EdDSA Edwards-curve Digital Signature Algorithm + Pk size: 256 bits + Fingerprint: 6D10 0EB0 444D 1648 DAD9 A0EE DE83 CCF4 A204 F957 + KeyID: DE83 CCF4 A204 F957 + + 00000000 c6 CTB + 00000001 33 length + 00000002 04 version + 00000003 5f b2 a3 f6 creation_time + 00000007 16 pk_algo + 00000008 09 curve_len + 00000009 2b 06 01 04 01 da 47 curve + 00000010 0f 01 + 00000012 01 07 eddsa_public_len + 00000014 40 ce d6 63 99 49 37 21 48 27 2b 04 eddsa_public + 00000020 7d ad fb a4 55 4b 7b 51 a5 6c be 4f 80 a0 1b 4e + 00000030 64 d6 d5 a8 37 + 00000035 s2k_usage + +Signature Packet, new CTB, 2 header bytes + 131 bytes + Version: 4 + Type: DirectKey + Pk algo: EdDSA Edwards-curve Digital Signature Algorithm + Hash algo: SHA512 + Hashed area: + Signature creation time: 2020-11-16 16:08:22 UTC (critical) + Symmetric algo preferences: AES256, AES128 + Issuer: DE83 CCF4 A204 F957 + Hash preferences: SHA512, SHA256 + Key flags: C (critical) + Features: MDC + Issuer Fingerprint: 6D10 0EB0 444D 1648 DAD9 A0EE DE83 CCF4 A204 F957 + Digest prefix: 6C58 + Level: 0 (signature over data) + + 00000000 c2 CTB + 00000001 83 length + 00000002 04 version + 00000003 1f type + 00000004 16 pk_algo + 00000005 0a hash_algo + 00000006 00 35 hashed_area_len + 00000008 05 subpacket length + 00000009 82 subpacket tag + 0000000a 5f b2 a3 f6 sig creation time + 0000000e 03 subpacket length + 0000000f 0b subpacket tag + 00000010 09 07 pref sym algos + 00000012 09 subpacket length + 00000013 10 subpacket tag + 00000014 de 83 cc f4 a2 04 f9 57 issuer + 0000001c 03 subpacket length + 0000001d 15 subpacket tag + 0000001e 0a 08 pref hash algos + 00000020 02 subpacket length + 00000021 9b subpacket tag + 00000022 01 key flags + 00000023 02 subpacket length + 00000024 1e subpacket tag + 00000025 01 features + 00000026 16 subpacket length + 00000027 21 subpacket tag + 00000028 04 version + 00000029 6d 10 0e b0 44 4d 16 issuer fp + 00000030 48 da d9 a0 ee de 83 cc f4 a2 04 f9 57 + 0000003d 00 00 unhashed_area_len + 0000003f 6c digest_prefix1 + 00000040 58 digest_prefix2 + 00000041 01 00 eddsa_sig_r_len + 00000043 ed 4e 62 b6 a8 68 39 85 31 9e c9 59 b2 eddsa_sig_r + 00000050 e8 4c a5 bb c6 90 d4 34 a0 7e 92 1f 9b 74 2e 87 + 00000060 8d 8a 5c + 00000063 00 ff eddsa_sig_s_len + 00000065 6a 1e 18 60 34 4e e7 a1 e4 04 b0 eddsa_sig_s + 00000070 99 91 d3 25 bb b5 36 13 f1 1c ab 24 5e a8 db 16 + 00000080 44 36 55 dd 0b +``` + +Note that the two OpenPGP artifacts (public certificate and private key) +are almost identical. + +The public certificate uses the packet type "Public-Key Packet" +instead of "Secret-Key Packet". The two packet types are very similar. +The "Public-Key Packet" leaves out two types of data + +* the private key material (visualized in red), and +* s2k configuration data, if any (this example doesn't have any). + s2k is used when the secret key material is password-protected. + +![Image](diag/pubcert-minimal.png "A minimal OpenPGP public certificate, visualized") + +In following examples we will look at OpenPGP private keys only. The +corresponding public certificates are easy to imagine (just leave out the +private key material). + + +### User IDs + +User IDs are a mechanism for attaching *identities* to an OpenPGP +certificate. Typically, a User ID will contain a name and an email address. + +To look into these, we'll make a certificate that has one +[User ID](https://tools.ietf.org/html/rfc4880#section-5.11). +User IDs are *"intended to represent the name and email address of the key +holder"*. A certificate can have multiple User IDs associated with it. + +``` + let (cert, _) = CertBuilder::new() + .add_userid("Alice Adams ") + .generate()?; +``` + +Let's look into the details of this key: + +``` +-----BEGIN PGP PRIVATE KEY BLOCK----- +Comment: A3F3 1A57 E400 A77C 2239 24C0 783B 4E35 B4E5 F1BA +Comment: Alice Adams + +xVgEX7LO1RYJKwYBBAHaRw8BAQdAiDI09+r0a4BVBUZCIqdSF9yuC706fRNC6tvZ +zReMlI4AAP0VhUQxbMmXjJgXfiH2p0Zo/1G9WgC2h5HwfluLGONYJQ/+woMEHxYK +ADUFgl+yztUDCwkHCRB4O041tOXxugMVCggCmwECHgEWIQSj8xpX5ACnfCI5JMB4 +O041tOXxugAAfXwBAPkjwkSO5aI3lQUNi/h4OiwPUF/u6AO9rHsg45WURZOwAQDy +8TQHQyFR52QjldVYbevffMaWfBiB4LfmrMeNvoHNC80fQWxpY2UgQWRhbXMgPGFs +aWNlQGV4YW1wbGUub3JnPsKGBBMWCgA4BYJfss7VAwsJBwkQeDtONbTl8boDFQoI +ApkBApsBAh4BFiEEo/MaV+QAp3wiOSTAeDtONbTl8boAALLzAP4oGNBkrnpv7TBi +cucUcQZbAURxRDZLioWmwu/VVqWRQwEAk/3oG5sP327lu73CE7LUjBt5ChtAlDlP +szWqa9TiCw4= +=tnJI +-----END PGP PRIVATE KEY BLOCK----- +``` + +``` +Secret-Key Packet, new CTB, 2 header bytes + 88 bytes + Version: 4 + Creation time: 2020-11-16 19:11:17 UTC + Pk algo: EdDSA Edwards-curve Digital Signature Algorithm + Pk size: 256 bits + Fingerprint: A3F3 1A57 E400 A77C 2239 24C0 783B 4E35 B4E5 F1BA + KeyID: 783B 4E35 B4E5 F1BA + + Secret Key: + + Unencrypted + + 00000000 c5 CTB + 00000001 58 length + 00000002 04 version + 00000003 5f b2 ce d5 creation_time + 00000007 16 pk_algo + 00000008 09 curve_len + 00000009 2b 06 01 04 01 da 47 curve + 00000010 0f 01 + 00000012 01 07 eddsa_public_len + 00000014 40 88 32 34 f7 ea f4 6b 80 55 05 46 eddsa_public + 00000020 42 22 a7 52 17 dc ae 0b bd 3a 7d 13 42 ea db d9 + 00000030 cd 17 8c 94 8e + 00000035 00 s2k_usage + 00000036 00 fd eddsa_secret_len + 00000038 15 85 44 31 6c c9 97 8c eddsa_secret + 00000040 98 17 7e 21 f6 a7 46 68 ff 51 bd 5a 00 b6 87 91 + 00000050 f0 7e 5b 8b 18 e3 58 25 + 00000058 0f fe checksum + +Signature Packet, new CTB, 2 header bytes + 131 bytes + Version: 4 + Type: DirectKey + Pk algo: EdDSA Edwards-curve Digital Signature Algorithm + Hash algo: SHA512 + Hashed area: + Signature creation time: 2020-11-16 19:11:17 UTC (critical) + Symmetric algo preferences: AES256, AES128 + Issuer: 783B 4E35 B4E5 F1BA + Hash preferences: SHA512, SHA256 + Key flags: C (critical) + Features: MDC + Issuer Fingerprint: A3F3 1A57 E400 A77C 2239 24C0 783B 4E35 B4E5 F1BA + Digest prefix: 7D7C + Level: 0 (signature over data) + + 00000000 c2 CTB + 00000001 83 length + 00000002 04 version + 00000003 1f type + 00000004 16 pk_algo + 00000005 0a hash_algo + 00000006 00 35 hashed_area_len + 00000008 05 subpacket length + 00000009 82 subpacket tag + 0000000a 5f b2 ce d5 sig creation time + 0000000e 03 subpacket length + 0000000f 0b subpacket tag + 00000010 09 07 pref sym algos + 00000012 09 subpacket length + 00000013 10 subpacket tag + 00000014 78 3b 4e 35 b4 e5 f1 ba issuer + 0000001c 03 subpacket length + 0000001d 15 subpacket tag + 0000001e 0a 08 pref hash algos + 00000020 02 subpacket length + 00000021 9b subpacket tag + 00000022 01 key flags + 00000023 02 subpacket length + 00000024 1e subpacket tag + 00000025 01 features + 00000026 16 subpacket length + 00000027 21 subpacket tag + 00000028 04 version + 00000029 a3 f3 1a 57 e4 00 a7 issuer fp + 00000030 7c 22 39 24 c0 78 3b 4e 35 b4 e5 f1 ba + 0000003d 00 00 unhashed_area_len + 0000003f 7d digest_prefix1 + 00000040 7c digest_prefix2 + 00000041 01 00 eddsa_sig_r_len + 00000043 f9 23 c2 44 8e e5 a2 37 95 05 0d 8b f8 eddsa_sig_r + 00000050 78 3a 2c 0f 50 5f ee e8 03 bd ac 7b 20 e3 95 94 + 00000060 45 93 b0 + 00000063 01 00 eddsa_sig_s_len + 00000065 f2 f1 34 07 43 21 51 e7 64 23 95 eddsa_sig_s + 00000070 d5 58 6d eb df 7c c6 96 7c 18 81 e0 b7 e6 ac c7 + 00000080 8d be 81 cd 0b + +User ID Packet, new CTB, 2 header bytes + 31 bytes + Value: Alice Adams + + 00000000 cd CTB + 00000001 1f length + 00000002 41 6c 69 63 65 20 41 64 61 6d 73 20 3c 61 value + 00000010 6c 69 63 65 40 65 78 61 6d 70 6c 65 2e 6f 72 67 + 00000020 3e + +Signature Packet, new CTB, 2 header bytes + 134 bytes + Version: 4 + Type: PositiveCertification + Pk algo: EdDSA Edwards-curve Digital Signature Algorithm + Hash algo: SHA512 + Hashed area: + Signature creation time: 2020-11-16 19:11:17 UTC (critical) + Symmetric algo preferences: AES256, AES128 + Issuer: 783B 4E35 B4E5 F1BA + Hash preferences: SHA512, SHA256 + Primary User ID: true (critical) + Key flags: C (critical) + Features: MDC + Issuer Fingerprint: A3F3 1A57 E400 A77C 2239 24C0 783B 4E35 B4E5 F1BA + Digest prefix: B2F3 + Level: 0 (signature over data) + + 00000000 c2 CTB + 00000001 86 length + 00000002 04 version + 00000003 13 type + 00000004 16 pk_algo + 00000005 0a hash_algo + 00000006 00 38 hashed_area_len + 00000008 05 subpacket length + 00000009 82 subpacket tag + 0000000a 5f b2 ce d5 sig creation time + 0000000e 03 subpacket length + 0000000f 0b subpacket tag + 00000010 09 07 pref sym algos + 00000012 09 subpacket length + 00000013 10 subpacket tag + 00000014 78 3b 4e 35 b4 e5 f1 ba issuer + 0000001c 03 subpacket length + 0000001d 15 subpacket tag + 0000001e 0a 08 pref hash algos + 00000020 02 subpacket length + 00000021 99 subpacket tag + 00000022 01 primary user id + 00000023 02 subpacket length + 00000024 9b subpacket tag + 00000025 01 key flags + 00000026 02 subpacket length + 00000027 1e subpacket tag + 00000028 01 features + 00000029 16 subpacket length + 0000002a 21 subpacket tag + 0000002b 04 version + 0000002c a3 f3 1a 57 issuer fp + 00000030 e4 00 a7 7c 22 39 24 c0 78 3b 4e 35 b4 e5 f1 ba + 00000040 00 00 unhashed_area_len + 00000042 b2 digest_prefix1 + 00000043 f3 digest_prefix2 + 00000044 00 fe eddsa_sig_r_len + 00000046 28 18 d0 64 ae 7a 6f ed 30 62 eddsa_sig_r + 00000050 72 e7 14 71 06 5b 01 44 71 44 36 4b 8a 85 a6 c2 + 00000060 ef d5 56 a5 91 43 + 00000066 01 00 eddsa_sig_s_len + 00000068 93 fd e8 1b 9b 0f df 6e eddsa_sig_s + 00000070 e5 bb bd c2 13 b2 d4 8c 1b 79 0a 1b 40 94 39 4f + 00000080 b3 35 aa 6b d4 e2 0b 0e +``` + +Instead of two sections, as before, we see four sections in this certificate: + +* First a "Secret-Key Packet", +* then a "Signature Packet" (these two packets are the same as above). +* Third, a + [*"User ID Packet"*](https://tools.ietf.org/html/rfc4880#section-5.11), + which contains the name and email address we used +* Finally a + [*"Signature Packet"*](https://tools.ietf.org/html/rfc4880#section-5.2) + of type 0x13, *"Positive certification of a User ID and Public-Key packet"*. + This is a cryptographic artifact that "binds the User ID packet and the + Key packet together", i.e. it certifies that the owner of the key wants + this User ID associated with their key. + (Only the person who controls the private part of this key can create this + signature packet. The signature serves as proof that the owner of the key + has added this User ID to the certificate) + + +### Subkeys + + +From here on, we'll look at the dumps in shorter format (you can see more +detail by copying the certificates into the web-dumper at +https://dump.sequoia-pgp.org/ and checking the "HexDump" checkbox). + +### Certifications (Signatures) + + +### Revocations + diff --git a/book/source/05-private.md b/book/source/05-private.md new file mode 100644 index 0000000..bc747c7 --- /dev/null +++ b/book/source/05-private.md @@ -0,0 +1,7 @@ +# Private key material + +``` +- Consistently consider private key material as a separate thing from Certificates? (like in pkcs#11?) +- consider KOpenPGP attack +- For TSKs: Best practices S2K + S2K migration? +``` \ No newline at end of file diff --git a/book/source/06-signatures.md b/book/source/06-signatures.md new file mode 100644 index 0000000..8eaea36 --- /dev/null +++ b/book/source/06-signatures.md @@ -0,0 +1,59 @@ +# Signatures as "statments" + +``` + - Purpose of a signature + - Meaning of different signature types, nuances of subpackets + - Can we have a "catalogue" of statements a user might want to make, mapping these to archetypical signatures? + - Revocation; Hard vs. Soft +``` + +## Certifications (third party signatures on keys) + +A certification is a machine-readable statement about a (public) key, made by a third party. +In OpenPGP, certifications are implemented as +[Signature Packets](https://datatracker.ietf.org/doc/html/rfc4880#section-5.2). + +More specifically, certifications in OpenPGP are usually modelled as "third party binding signatures". + +Typically, certifications in OpenPGP work like this: Alice checks that a key `0x1234...` belongs to Bob, who uses the +email address `bob@example.org`. After making sure that the key `0x1234...` and the digital identity `bob@example.org` +are meaningfully linked, she creates a certification stating that the key and the identity are linked. + +Such a certification can serve two purposes: + +1) Alice's OpenPGP software can now reason about Bob's key, and thus show that `0x1234...` is a good key to use for +interacting with `bob@example.org`. +2) Other parties can observe Alice's certification and derive some amount of confidence in Bob's key from it. +For example, Carol might not easily be able to check if `0x1234...` is Bob's key, but she might consider Alice's +certification for Bob's key sufficient evidence. + +Carol may decide to systematically rely on Alice's certifications. Then we say that Carol uses Alice as a +"trusted introducer". That is, Carol *delegates* part of her authentication decisions to Alice. + + +### Regular certifications + +Are a cryptographic statement that binds a User ID and a Key (via its fingerprint) together. + +Have a SignatureType in `GenericCertification, PersonaCertification, CasualCertification, PositiveCertification`. + +### Trust signatures (using a key as "trusted introducer") + +A "trust signature" has two additional parameters: a `depth` and a `level`. + +#### Alternative model: direct key signatures for pure delegation + +This is useful for using 0xB as a trusted introducer without asserting that 0xB is Bob +(when a tsig is on a User ID, it is necessarily *also* a vouch about the binding). + +The logical place to store a tsig that is not also a vouch about a binding is a direct key signature +(however, GnuPG does probably not respect such tsigs). + +The [OpenPGP Web of Trust](https://sequoia-pgp.gitlab.io/sequoia-wot/) spec allows such direct key signatures. + +SignatureType is `DirectKey` + +In Sequoia, roughly: +``` +SignatureBuilder::new(SignatureType::GenericCertification).set_trust_signature(..).sign_direct_key(&mut your_signer, &signee_cert.primary_key()) +``` diff --git a/book/source/07-signature_internals.md b/book/source/07-signature_internals.md new file mode 100644 index 0000000..bd2337c --- /dev/null +++ b/book/source/07-signature_internals.md @@ -0,0 +1,7 @@ +# Signature "internals" + +``` + - Subpackets and how to make sense of them + - "Negotiating" signature hash algorithm based on recipients preference subpackets + - Explore viability of having multiple signatures, e.g. v4+v6? +``` \ No newline at end of file diff --git a/book/source/08-verification.md b/book/source/08-verification.md new file mode 100644 index 0000000..821f4ab --- /dev/null +++ b/book/source/08-verification.md @@ -0,0 +1,13 @@ +# Verification + +``` + - Self-authenticating data (unhashed subpackets) + +## When are signatures valid? + - Validity as a tree of signatures + +## When are certificates valid? + +Primary revoked, User ID revoked, ... +Which signatures take precendence? +``` \ No newline at end of file diff --git a/book/source/09-encryption.md b/book/source/09-encryption.md new file mode 100644 index 0000000..1794b65 --- /dev/null +++ b/book/source/09-encryption.md @@ -0,0 +1,10 @@ +# Encryption + +``` + - High Level overview of the message encryption process + - SED vs. SEIPD (v1) vs. SEIPD w/ AEAD (v2) + - Encrypt for multiple/single subkey per certificate? + - "Negotiating" algorithms based on recipients preference subpackets + - Prevent "downgrade" -> Policy + - Implications of how a recipient cert is "addressed" (fingerprint/key-ID vs. user-ID) (preferences, expiration, revocation) +``` \ No newline at end of file diff --git a/book/source/10-decryption.md b/book/source/10-decryption.md new file mode 100644 index 0000000..9679fe9 --- /dev/null +++ b/book/source/10-decryption.md @@ -0,0 +1,8 @@ +# Decryption + +``` + - using expired certificate? + - using revoked certificate? + - using expired subkey? + - using revoked subkey? +``` \ No newline at end of file diff --git a/book/source/11-armor.md b/book/source/11-armor.md new file mode 100644 index 0000000..e821169 --- /dev/null +++ b/book/source/11-armor.md @@ -0,0 +1,6 @@ +# ASCII Armor + +``` + - Why? + - CRC and [its deprecation in crypto-refresh](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-optional-checksum) +``` \ No newline at end of file diff --git a/book/source/12-pitfalls.md b/book/source/12-pitfalls.md new file mode 100644 index 0000000..0cd24b2 --- /dev/null +++ b/book/source/12-pitfalls.md @@ -0,0 +1,12 @@ +# Pitfalls / Things to keep in mind + +``` +## Key IDs are really not guaranteed to be unique + +Use fingerprints, or expect duplicates + +## Signature Subpackets can have duplicates + +## Packet Nesting can be unreasonable + - EBNF of allowed packet sequences is complex -> Recommend [stricter](https://mailarchive.ietf.org/arch/msg/openpgp/uepOF6XpSegMO4c59tt9e5H1i4g/) best-practices? +``` \ No newline at end of file diff --git a/book/source/13-policy.md b/book/source/13-policy.md new file mode 100644 index 0000000..60e8177 --- /dev/null +++ b/book/source/13-policy.md @@ -0,0 +1,7 @@ +# Algorithms and Policy + +``` + - What algorithms are trustworthy? -> Depend on regulatory bodies like the BSI? + - How to decide, when to deprecate / reject algorithms (how to be competent) + - Transitioning from one set of algorithms to another (Interoperability) +``` \ No newline at end of file diff --git a/book/source/14-resources.md b/book/source/14-resources.md new file mode 100644 index 0000000..d831d92 --- /dev/null +++ b/book/source/14-resources.md @@ -0,0 +1,14 @@ +# External resources + +[RFC4880](https://www.rfc-editor.org/rfc/rfc4880.html) OpenPGP Message Format [2007] + +[An Advanced Introduction to GnuPG](https://gnupg.org/ftp/people/neal/an-advanced-introduction-to-gnupg/openpgp/openpgp.pdf) [Neal Walfield, 2017] + + +## Web of Trust + +[PGP Web of Trust: Core Concepts Behind Trusted Communication](https://www.linux.com/training-tutorials/pgp-web-trust-core-concepts-behind-trusted-communication/), +[PGP Web of Trust: Delegated Trust and Keyservers](https://web.archive.org/web/20210417113254/https://www.linuxfoundation.org/blog/pgp-web-of-trust-delegated-trust-and-keyservers/) [Konstantin Ryabitsev, 2014] + +[OpenPGP Web of Trust](https://sequoia-pgp.gitlab.io/sequoia-wot/) [Neal Walfield, 2022]; +implementation: . diff --git a/book/source/15-glossary.md b/book/source/15-glossary.md new file mode 100644 index 0000000..5e48a32 --- /dev/null +++ b/book/source/15-glossary.md @@ -0,0 +1,19 @@ +# Glossary + +This document aims to enumerate and clarify alternative terms that have been +used for the same concept in the OpenPGP space, as well as to document +terminology specific to OpenPGP CA. + +- Authentication +- Bridge: Two instances of OpenPGP CA mark each other as (scoped) trusted + introducers, which means that users in both organizations see each other + as authenticated +- Certification ("Signature" on a certificate) +- Key / OpenPGP Key (Certificate) +- Key creation workflow: centralized/decentralized +- OpenPGP +- Revocation certificate +- Trust signature ("tsig"), a speficic type of certification for a + certificate, which marks that key as a "trusted introducer" (i.e. the + party that creates the trust signature signals that they will trust + certifications that the "trusted introducer" makes on certificates) diff --git a/book/source/16-acknowledgements.md b/book/source/16-acknowledgements.md new file mode 100644 index 0000000..de67a3a --- /dev/null +++ b/book/source/16-acknowledgements.md @@ -0,0 +1 @@ +# Acknowledgements diff --git a/book/source/conf.py b/book/source/conf.py new file mode 100644 index 0000000..57ab665 --- /dev/null +++ b/book/source/conf.py @@ -0,0 +1,30 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Notes on OpenPGP' +copyright = '2023, Foo' +author = 'Foo' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'myst_parser', +] +source_suffix = ['.md', '.rst'] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/book/source/diag/cryptographic_keys.png b/book/source/diag/cryptographic_keys.png new file mode 100644 index 0000000..7e6b057 Binary files /dev/null and b/book/source/diag/cryptographic_keys.png differ diff --git a/book/source/diag/cryptographic_keys.svg b/book/source/diag/cryptographic_keys.svg new file mode 100644 index 0000000..df4bc1b --- /dev/null +++ b/book/source/diag/cryptographic_keys.svg @@ -0,0 +1,79 @@ + + + + + + + + + + public cryptographic key + private cryptographic key + + diff --git a/book/source/diag/fingerprint.png b/book/source/diag/fingerprint.png new file mode 100644 index 0000000..6e33499 Binary files /dev/null and b/book/source/diag/fingerprint.png differ diff --git a/book/source/diag/fingerprint.svg b/book/source/diag/fingerprint.svg new file mode 100644 index 0000000..f8c7869 --- /dev/null +++ b/book/source/diag/fingerprint.svg @@ -0,0 +1,133 @@ + + + + + + + + + + + + + OpenPGP Keymetadata + Fingerprint:B3D2 7B09 FBA4 1235 2B418972 C8B8 6AC4 2455 4239 + + + + diff --git a/book/source/diag/id_card.svg b/book/source/diag/id_card.svg new file mode 100644 index 0000000..5cbf1b3 --- /dev/null +++ b/book/source/diag/id_card.svg @@ -0,0 +1,108 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/book/source/diag/key-minimal.png b/book/source/diag/key-minimal.png new file mode 100644 index 0000000..12f62fe Binary files /dev/null and b/book/source/diag/key-minimal.png differ diff --git a/book/source/diag/keypair.png b/book/source/diag/keypair.png new file mode 100644 index 0000000..a4409e6 Binary files /dev/null and b/book/source/diag/keypair.png differ diff --git a/book/source/diag/keypair.svg b/book/source/diag/keypair.svg new file mode 100644 index 0000000..0c75afd --- /dev/null +++ b/book/source/diag/keypair.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + cryptographic keypair + + + diff --git a/book/source/diag/primary_key.png b/book/source/diag/primary_key.png new file mode 100644 index 0000000..51e953c Binary files /dev/null and b/book/source/diag/primary_key.png differ diff --git a/book/source/diag/primary_key.svg b/book/source/diag/primary_key.svg new file mode 100644 index 0000000..a0fb62a --- /dev/null +++ b/book/source/diag/primary_key.svg @@ -0,0 +1,138 @@ + + + + + + + + + + + + + Key metadata:- creation time,- ... + OpenPGP primary (or sub-) key + + + + diff --git a/book/source/diag/pubcert-minimal.png b/book/source/diag/pubcert-minimal.png new file mode 100644 index 0000000..dbee19d Binary files /dev/null and b/book/source/diag/pubcert-minimal.png differ diff --git a/book/source/diag/subkey_binding.png b/book/source/diag/subkey_binding.png new file mode 100644 index 0000000..4b898f4 Binary files /dev/null and b/book/source/diag/subkey_binding.png differ diff --git a/book/source/diag/subkey_binding.svg b/book/source/diag/subkey_binding.svg new file mode 100644 index 0000000..4118dac --- /dev/null +++ b/book/source/diag/subkey_binding.svg @@ -0,0 +1,423 @@ + + + + + + + + + + + + + + + + + + + + + + + Key metadata:- creation time,- ... + OpenPGP primary key(for certification) + This arrow is actually a shorthandfor the subkey binding signature + Primary key creates a signature to associate the subkey with itself + + + + + + + Key metadata:- creation time,- ... + OpenPGP subkey(for encryption) + Subkey binding signature + + + + + + P + + Metadata associatedwith this Signature:- key flags- creation time- key expiration time- ... + + + diff --git a/book/source/diag/user_id.png b/book/source/diag/user_id.png new file mode 100644 index 0000000..b15c883 Binary files /dev/null and b/book/source/diag/user_id.png differ diff --git a/book/source/diag/user_id.svg b/book/source/diag/user_id.svg new file mode 100644 index 0000000..afc9f07 --- /dev/null +++ b/book/source/diag/user_id.svg @@ -0,0 +1,253 @@ + + + + + + + + + + + + + + + + + + + Key metadata:- creation time,- ... + P + OpenPGP primary key(for certification) + + + Alice Adams <alice@example.org> + User ID + + + + + + + + + + + + + diff --git a/book/source/diag/user_id_certification.png b/book/source/diag/user_id_certification.png new file mode 100644 index 0000000..bfa8c06 Binary files /dev/null and b/book/source/diag/user_id_certification.png differ diff --git a/book/source/diag/user_id_certification.svg b/book/source/diag/user_id_certification.svg new file mode 100644 index 0000000..c117885 --- /dev/null +++ b/book/source/diag/user_id_certification.svg @@ -0,0 +1,448 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Key metadata:- creation time,- ... + P + OpenPGP primary key(for certification) + + + + + + + Alice Adams <alice@example.org> + User ID + + + + + + + + + + + Primary key creates a signature to associate the User ID with itself + Certification for User ID + + + + This arrow is actually a shorthand for thecertification signature shown on the right + Metadata associatedwith this Signature:- creation time- algorithm preferences- key expiration time- "Primary User ID" flag- primary key flags- primary key expiration time- ... + + diff --git a/book/source/diag/with_subkeys.png b/book/source/diag/with_subkeys.png new file mode 100644 index 0000000..cf18ecf Binary files /dev/null and b/book/source/diag/with_subkeys.png differ diff --git a/book/source/diag/with_subkeys.svg b/book/source/diag/with_subkeys.svg new file mode 100644 index 0000000..0b8f718 --- /dev/null +++ b/book/source/diag/with_subkeys.svg @@ -0,0 +1,340 @@ + + + + + + + + + + + + + + + + + + + + Key metadata:- creation time,- ... + OpenPGP primary key(for certification) + + + + + + + Key metadata:- creation time,- ... + OpenPGP subkey(for encryption) + + + + + + + Key metadata:- creation time,- ... + OpenPGP subkey(for signing) + + + + + P + + diff --git a/book/source/index.rst b/book/source/index.rst new file mode 100644 index 0000000..871b1e7 --- /dev/null +++ b/book/source/index.rst @@ -0,0 +1,31 @@ +Notes on OpenPGP +================ + +.. toctree:: + :numbered: + :maxdepth: 3 + + 01-intro.md + 02-goals.md + 03-highlevel.md + 04-certs.md + 05-private.md + 06-signatures.md + 07-signature_internals.md + 08-verification.md + 09-encryption.md + 10-decryption.md + 11-armor.md + 12-pitfalls.md + 13-policy.md + 14-resources.md + 15-glossary.md + 16-acknowledgements.md + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`