From c592c6c02d52f5e3814ac1037f287d324c73c3aa Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 6 Oct 2023 20:41:18 +0200 Subject: [PATCH 01/22] ch4: don't use title case --- book/source/04-certificates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 29b2fef..52f6026 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -102,7 +102,7 @@ Subkeys have the same structure as the primary key, but they are used in a diffe OpenPGP certificates can contain a number of subkeys ``` -#### Key Flags: defining which operations a component key can perform +#### Key flags: defining which operations a component key can perform Each component key has a set of ["Key Flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) that specify which operations that key can perform. @@ -245,7 +245,7 @@ Note: certification signatures [can be made irrevocable](https://www.ietf.org/ar This section only contains notes and still needs to be written ``` -### Certificate Management / Evolution of a certificate over time +### Certificate management / Evolution of a certificate over time Minimized versions, merging, effective "append only" semantics, ... @@ -262,7 +262,7 @@ Minimized versions, merging, effective "append only" semantics, ... - Subkey: Revoked/key expired/binding signature expired - User ID: revoked, binding expired, ... -### Best Practices regarding Key Freshness +### Best practices regarding Key Freshness ```{admonition} TODO :class: warning @@ -273,7 +273,7 @@ Minimized versions, merging, effective "append only" semantics, ... Wiktor suggests to check: https://blogs.gentoo.org/mgorny/2018/08/13/openpgp-key-expiration-is-not-a-security-measure/ for important material ``` -### Metadata Leak of Social Graph +### Metadata leak of Social Graph (unbound_user_ids)= ### Adding unbound User IDs to a certificate From ac070e52296d7c9b65adea9ead4ec411bf9cf57a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 6 Oct 2023 20:39:54 +0200 Subject: [PATCH 02/22] ch4 "zooming in": fix capitalizations/styling - Don't use quotation marks for RFC terms. Use italics, when appropriate. - The word "packet" isn't capitalized when referring to a specific packet. --- book/source/04-certificates.md | 64 +++++++++++++++++----------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 52f6026..4af313d 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -284,9 +284,9 @@ Some OpenPGP subsystems may add User IDs to a certificate, which are not bound t Now that we've established the concepts of the components that OpenPGP certificates consist of, let's look at the internal details of our example certificate. -### A very minimal OpenPGP "Transferrable Secret Key" +### A very minimal OpenPGP transferable secret key -We'll start with a very minimal version of [](alice_priv), stored as a "Transferrable Secret Key" (that is, including private key material). +We'll start with a very minimal version of [](alice_priv), stored as a *transferable secret key* ([RFC 10.2.](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#transferable-secret-keys)) (that is, including private key material). In this section, we use the Sequoia-PGP tool `sq` to handle and transform our example OpenPGP key, and to inspect internal OpenPGP packet data. @@ -319,8 +319,8 @@ $ sq packet join alice.priv-0--SecretKey alice.priv-1--Signature --output alice_ This version of Alice's key contains just two packets: -- The [*"Secret-Key Packet"*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats) for the primary key, and -- A [*"Direct Key Signature"*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-direct-key) (a self-signature that binds metadata to the primary key). +- The [*Secret-Key packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats) for the primary key, and +- A [*Direct Key Signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-direct-key) (a self-signature that binds metadata to the primary key). In the real world, you won't usually encounter an OpenPGP key that is quite this minimal. However, this is technically a valid OpenPGP key (and we'll add more components to it, later in this section). @@ -350,7 +350,7 @@ $ sq packet dump --hex alice_minimal.priv #### Secret-Key Packet -The output starts with the (primary) [Secret-Key Packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats) (the file `alice.priv-0--SecretKey` contains this packet): +The output starts with the (primary) [Secret-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats) (the file `alice.priv-0--SecretKey` contains this packet): ```text Secret-Key Packet, new CTB, 2 header bytes + 75 bytes @@ -380,12 +380,12 @@ KeyID: AAA18CBB254685C5 00000040 bd 42 dd 4b e9 a3 36 81 3b a5 cc cf fb ``` -The Secret-Key Packet consists in large part of the actual cryptographic key data. Let's look at the packet field by field: +The Secret-Key packet consists in large part of the actual cryptographic key data. Let's look at the packet field by field: -- `CTB: 0xc5`[^CTB]: The [Packet Tag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-headers) for this packet. The binary representation of the value `0xc5` is `11000101`. Bits 7 and 6 show that the packet is in "OpenPGP packet format" (as opposed to in "Legacy packet format"). The remaining 6 bits encode the Tag's value: "5". This is the value for a Secret-Key Packet, as shown in the list of [Packet Tags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-tags). +- `CTB: 0xc5`[^CTB]: The [Packet Tag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-headers) for this packet. The binary representation of the value `0xc5` is `11000101`. Bits 7 and 6 show that the packet is in *OpenPGP packet format* (as opposed to in *Legacy packet format*). The remaining 6 bits encode the Tag's value: "5". This is the value for a Secret-Key packet, as shown in the list of [Packet Tags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-tags). - `length: 0x4b`: The remaining length of this packet. -The packet tag defines the semantics of the remaining data in the packet. We're looking at a Secret-Key Packet, which is a kind of [Key Material Packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-material-packets). +The packet tag defines the semantics of the remaining data in the packet. We're looking at a Secret-Key packet, which is a kind of [Key Material Packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-material-packets). - `version: 0x06`: The key material is in version 6 format @@ -396,25 +396,25 @@ This means that the next part of the packet follows the structure of [Version 6 - `public_len: 0x00000020`: "Octet count for the following public key material" (in this case, the length of the following `ed25519_public` field) - `ed25519_public`: [Algorithm-specific representation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-algorithm-specific-part-for-ed2) of the public key material (the format is based on the value of `pk_algo`), in this case 32 bytes of the Ed25519 public key -This concludes the Public Key section of the packet. The remaining data follows the [Secret-Key Packet Format](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats): +This concludes the Public Key section of the packet. The remaining data follows the [Secret-Key packet format](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats): -- `s2k_usage: 0x00`: [This "S2K usage" value](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-encryption-s2k-u) specifies that the secret-key data is not encrypted +- `s2k_usage: 0x00`: [This *S2K usage* value](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-encryption-s2k-u) specifies that the secret-key data is not encrypted - `ed25519_secret`: [Algorithm-specific representation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-algorithm-specific-part-for-ed2) of the secret key data (the format is based on the value of `pk_algo`) -[^CTB]: Sequoia uses the term "CTB" (Cipher Type Byte) to refer to the RFC's ["Packet Tag"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-headers) +[^CTB]: Sequoia uses the term CTB (Cipher Type Byte) to refer to the RFC's [Packet Tag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-headers) ```{tip} The overall structure of OpenPGP packets is described in the [Packet Syntax](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-syntax) chapter of the RFC. ``` -Note that the "Secret-Key" Packet contains both the private and the public part of the key. +Note that the *Secret-Key packet* contains both the private and the public part of the key. #### Direct Key Signature -The next packet is a [*"Direct Key Signature"*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-direct-key), which is bound to the primary key (the file `alice.priv-1--Signature` contains this packet). +The next packet is a [*Direct Key Signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-direct-key), which is bound to the primary key (the file `alice.priv-1--Signature` contains this packet). -This packet "binds the information in the Signature subpackets to the key". Each entry under "Signature Packet -> Hashed area" is one Signature subpacket, for example, including information about algorithm preferences (*"Symmetric algo preferences"* and *"Hash preferences"*). +This packet "binds the information in the signature subpackets to the key". Each entry under "Signature Packet -> Hashed area" is one signature subpacket, for example, including information about algorithm preferences (*symmetric algorithm preference* and *hash algorithm preferences*). ```text Signature Packet, new CTB, 2 header bytes + 182 bytes @@ -486,10 +486,10 @@ Level: 0 (signature over data) Let’s look at the packet field by field: -- `CTB: 0xc2`: The Packet Tag for this packet. Bits 7 and 6 show that the packet is in “OpenPGP packet format” (as opposed to in “Legacy packet format”). The remaining 6 bits encode the Tag’s value: “2”. This is the value for a Signature Packet. +- `CTB: 0xc2`: The Packet Tag for this packet. Bits 7 and 6 show that the packet is in “OpenPGP packet format” (as opposed to in “Legacy packet format”). The remaining 6 bits encode the Tag’s value: “2.” This is the value for a Signature packet. - `length: 0xb6`: The remaining length of this packet. -The packet tag defines the semantics of the remaining data in the packet. We're looking at a [Signature Packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-packet), so the following data is interpreted accordingly. +The packet tag defines the semantics of the remaining data in the packet. We're looking at a [Signature packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-packet), so the following data is interpreted accordingly. - `version: 0x06`: This is a version 6 signature (some of the following packet format is specific to this signature version). - `type: 0x1f`: The [Signature Type](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-types) @@ -497,29 +497,29 @@ The packet tag defines the semantics of the remaining data in the packet. We're - `hash_algo: 0x0a`: Hash algorithm (decimal 10, corresponds to [SHA2-512](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-hash-algorithms)) - `hashed_area_len: 0x0000003d`: Length of the following hashed subpacket data -The next part of this packet contains "hashed subpacket data." A "subpacket data set" in an OpenPGP Signature contains a list of zero or more "Signature subpackets." +The next part of this packet contains hashed subpacket data. A subpacket data set in an OpenPGP Signature contains a list of zero or more Signature subpackets. -There are two sets of "subpacket data" in a Signature: "hashed," and "unhashed." The difference is that the hashed subpackets are protected by the digital signature of this packet, while the unhashed subpackets are not. +There are two sets of subpacket data in a Signature: hashed, and unhashed. The difference is that the hashed subpackets are protected by the digital signature of this packet, while the unhashed subpackets are not. The following subpacket data consists of sets of "subpacket length, subpacket tag, data." We'll show the information for each subpacket as one line, starting with the [subpacket type description](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-subpacket-specifi) (based on the subpacket tag). Note that bit 7 of the subpacket tag signals if that subpacket is ["critical"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#section-5.2.3.7-10)[^critical]. -[^critical]: "Critical" here means: the receiver must be able to interpret the subpacket and is expected to fail, otherwise. non-critical subpackets may be ignored by the receiver +[^critical]: Critical here means: the receiver must be able to interpret the subpacket and is expected to fail, otherwise. non-critical subpackets may be ignored by the receiver -- [Signature Creation Time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-creation-subpacket) (subpacket type 2) *critical*: `0x6516eaa6` -- [Key Expiration Time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9) *critical*: `0x05a48fbd` -- [Preferred Symmetric Ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-v1-seipd) (type 11): `0x09 0x07`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#symmetric-algos): "AES with 256-bit key" and "AES with 128-bit key") -- [Preferred Hash Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-hashes-subpacket) (subpacket type 21): `0x0a 0x08`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-hash-algorithms): "SHA2-512" and "SHA2-256") -- [Key Flags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) (subpacket type 27) *critical*: `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-flags) to the "certifications" key flag) +- [Signature creation time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-creation-subpacket) (subpacket type 2) *critical*: `0x6516eaa6` +- [Key expiration time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9) *critical*: `0x05a48fbd` +- [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-v1-seipd) (type 11): `0x09 0x07`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#symmetric-algos): "AES with 256-bit key" and "AES with 128-bit key") +- [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-hashes-subpacket) (subpacket type 21): `0x0a 0x08`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-hash-algorithms): "SHA2-512" and "SHA2-256") +- [Key flags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) (subpacket type 27) *critical*: `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-flags) to the "certifications" key flag) - [Features](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#features-subpacket) (subpacket type 30): `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-features) to: "Symmetrically Encrypted Integrity Protected Data packet version 1") -- [Issuer Fingerprint](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#issuer-fingerprint-subpacket) (subpacket type 33): `aaa18cbb254685c58358320563fd37b67f3300f9fb0ec457378cd29f102698b3` (this is the fingerprint of the component key that issued the signature in this packet. Not that here, the value is the primary key fingerprint of the certificate we're looking at.) +- [Issuer fingerprint](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#issuer-fingerprint-subpacket) (subpacket type 33): `aaa18cbb254685c58358320563fd37b67f3300f9fb0ec457378cd29f102698b3` (this is the fingerprint of the component key that issued the signature in this packet. Not that here, the value is the primary key fingerprint of the certificate we're looking at.) The next part of this packet contains "unhashed subpacket data": - `unhashed_area_len: 0x0000000a`: Length of the following unhashed subpacket data. -As above, the following subpacket data consists of sets of "length, tag, data." In this case, only subpacket follows: +As above, the following subpacket data consists of sets of "subpacket length, subpacket tag, data." In this case, only subpacket follows: -- [Issuer Key ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#issuer-keyid-subpacket) (subpacket type 16): `aaa18cbb254685c5` (this is the shortened version 6 "Key ID" of the fingerprint of this certificate's primary key) +- [Issuer Key ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#issuer-keyid-subpacket) (subpacket type 16): `aaa18cbb254685c5` (this is the shortened version 6 *Key ID* of the fingerprint of this certificate's primary key) This concludes the unhashed subpacket data. @@ -557,7 +557,7 @@ gAIl6FM5SWuQxg12j0S07ExCOI5NPRDCrSnAV85mAXOzeIGeiVLPQ40oEal3CX/L $ sq packet dump --hex alice_minimal.pub ``` -The output now starts with a (primary) [Public-Key Packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-packet-formats): +The output now starts with a (primary) [Public-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-packet-formats): ```text Public-Key Packet, new CTB, 2 header bytes + 42 bytes @@ -579,11 +579,11 @@ Public-Key Packet, new CTB, 2 header bytes + 42 bytes 00000020 eb e7 42 e2 ab 47 f4 86 b3 ae 65 3e ``` -Note that the packet is almost identical to the Secret Key Packet seen above. +Note that the packet is almost identical to the Secret-Key packet seen above. -The packet tag (called `CTB` in the output) has changed to the packet type ["Public-Key Packet"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-packet-tag-6) instead of "Secret-Key Packet." +The packet tag (called `CTB` in the output) has changed to the packet type [*Public-Key packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-packet-tag-6) instead of *Secret-Key packet*. -The two packet types are very similar. Compared to the "Secret-Key Packet" packet shown above, this "Public-Key Packet" just leaves out the last section, which contained the private-key related fields `s2k_usage` and `ed25519_secret`. +The two packet types are very similar. Compared to the *Secret-Key packet* shown above, this *Public-Key packet* just leaves out the last section, which contained the private-key related fields `s2k_usage` and `ed25519_secret`. The second packet in the certificate (the Direct Key Signature) is bit-for-bit identical as in the previous section. So we omit showing it again, here. @@ -605,7 +605,7 @@ The following text is unfinished and still needs processing/writing. **This point marks the end of the material that should be read/edited.** ``` -From here on, we'll look at the dumps in shorter format (you can see more detail by copying the certificates into the ["Sequoia OpenPGP Packet dumper"](https://dump.sequoia-pgp.org/) and checking the "HexDump" checkbox). +From here on, we'll look at the dumps in shorter format (you can see more detail by copying the certificates into the [Sequoia OpenPGP Packet dumper](https://dump.sequoia-pgp.org/) and checking the "HexDump" checkbox). ### User IDs From 5fdb9be451f628918b139c7ada15cbe9b20b23db Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 6 Oct 2023 22:11:21 +0200 Subject: [PATCH 03/22] ch4: minor edits to "Seen as an OpenPGP certificate" --- book/source/04-certificates.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 4af313d..5900b85 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -581,11 +581,9 @@ Public-Key Packet, new CTB, 2 header bytes + 42 bytes Note that the packet is almost identical to the Secret-Key packet seen above. -The packet tag (called `CTB` in the output) has changed to the packet type [*Public-Key packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-packet-tag-6) instead of *Secret-Key packet*. +The packet tag (called `CTB` in the output) shows the packet type is now [*Public-Key packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-packet-tag-6), instead of *Secret-Key packet*, above. Besides this change, this *Public-Key packet* only leaves out the last section, which contained the private-key related fields `s2k_usage` and `ed25519_secret`. -The two packet types are very similar. Compared to the *Secret-Key packet* shown above, this *Public-Key packet* just leaves out the last section, which contained the private-key related fields `s2k_usage` and `ed25519_secret`. - -The second packet in the certificate (the Direct Key Signature) is bit-for-bit identical as in the previous section. So we omit showing it again, here. +The following, second packet in the certificate (the Direct Key Signature) is bit-for-bit identical as in the previous section. So we omit showing it again, here. ```{figure} diag/pubcert-minimal.png :width: 40% @@ -593,7 +591,7 @@ The second packet in the certificate (the Direct Key Signature) is bit-for-bit i A minimal OpenPGP public certificate, visualized ``` -In the following examples, we will only look at OpenPGP keys that include the private key material. The corresponding "certificate" variants, which only contain the public key material, are easy to imagine: like here, they just leave out the private key material. +In the following examples, we will only look at OpenPGP keys that include the private key material. The corresponding "certificate" variants, which only contain the public key material, are easy to imagine: like here, their packet type is changed from a Secret-Key to a Public-Key variant, and they leave out the private key material. ### Subkeys From b1acb31ed0595f7421a67fcb526b7065e7a290ae Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 6 Oct 2023 23:59:23 +0200 Subject: [PATCH 04/22] ch4: zooming in, add subkey dumps --- book/source/04-certificates.md | 208 ++++++++++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 6 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 5900b85..7105b53 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -593,17 +593,213 @@ A minimal OpenPGP public certificate, visualized In the following examples, we will only look at OpenPGP keys that include the private key material. The corresponding "certificate" variants, which only contain the public key material, are easy to imagine: like here, their packet type is changed from a Secret-Key to a Public-Key variant, and they leave out the private key material. -### Subkeys +### Encryption subkey -```{admonition} TODO -:class: warning +Now we'll look at a subkey in Alice's key. In the split version of Alice's key, the encryption subkey is in `alice.priv-4--SecretSubkey`, and the binding self-signature for the subkey in `alice.priv-5--Signature`. -The following text is unfinished and still needs processing/writing. +```text +$ sq packet dump --hex alice.priv-4--SecretSubkey +Secret-Subkey Packet, new CTB, 2 header bytes + 75 bytes + Version: 6 + Creation time: 2023-09-29 15:17:58 UTC + Pk algo: X25519 + Pk size: 256 bits + Fingerprint: C0A58384A438E5A14F73712426A4D45DBAEEF4A39E6B30B09D5513F978ACCA94 + KeyID: C0A58384A438E5A1 -**This point marks the end of the material that should be read/edited.** + Secret Key: + + Unencrypted + + 00000000 c7 CTB + 00000001 4b length + 00000002 06 version + 00000003 65 16 ea a6 creation_time + 00000007 19 pk_algo + 00000008 00 00 00 20 public_len + 0000000c d1 ae 87 d7 x25519_public + 00000010 cc 42 af 99 34 c5 c2 5c ca fa b7 4a c8 43 fc 86 + 00000020 35 2a 46 01 f3 cc 00 f5 4a 09 3e 3f + 0000002c 00 s2k_usage + 0000002d 28 7d cd x25519_secret + 00000030 da 26 16 37 8d ea 24 c7 ce e7 70 c7 9b e5 6f 0a + 00000040 c9 77 fb bd 23 41 73 c9 57 5a bf 7c 4c ``` -From here on, we'll look at the dumps in shorter format (you can see more detail by copying the certificates into the [Sequoia OpenPGP Packet dumper](https://dump.sequoia-pgp.org/) and checking the "HexDump" checkbox). +Notice that the structure of this *Secret-Subkey packet* is exactly the same as the *Secret-Key Packet*, above. The packet tag (`CTB`) is set to packet type 7, here (*Secret-Subkey packet*). + +The `pk_algo` value is set to 0x19 (or decimal) 25, which [corresponds to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-algorithms) X25519. + + +```text +$ sq packet dump --hex alice.priv-5--Signature +Signature Packet, new CTB, 2 header bytes + 171 bytes + Version: 6 + Type: SubkeyBinding + Pk algo: Ed25519 + Hash algo: SHA512 + Hashed area: + Signature creation time: 2023-09-29 15:17:58 UTC (critical) + Key expiration time: P1095DT62781S (critical) + Key flags: EtEr (critical) + Issuer Fingerprint: AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3 + Unhashed area: + Issuer: AAA18CBB254685C5 + Digest prefix: 2289 + Level: 0 (signature over data) + + 00000000 c2 CTB + 00000001 ab length + 00000002 06 version + 00000003 18 type + 00000004 1b pk_algo + 00000005 0a hash_algo + 00000006 00 00 00 32 hashed_area_len + 0000000a 05 subpacket length + 0000000b 82 subpacket tag + 0000000c 65 16 ea a6 sig creation time + 00000010 05 subpacket length + 00000011 89 subpacket tag + 00000012 05 a4 8f bd key expiry time + 00000016 02 subpacket length + 00000017 9b subpacket tag + 00000018 0c key flags + 00000019 22 subpacket length + 0000001a 21 subpacket tag + 0000001b 06 version + 0000001c aa a1 8c bb issuer fp + 00000020 25 46 85 c5 83 58 32 05 63 fd 37 b6 7f 33 00 f9 + 00000030 fb 0e c4 57 37 8c d2 9f 10 26 98 b3 + 0000003c 00 00 00 0a unhashed_area_len + 00000040 09 subpacket length + 00000041 10 subpacket tag + 00000042 aa a1 8c bb 25 46 85 c5 issuer + 0000004a 22 digest_prefix1 + 0000004b 89 digest_prefix2 + 0000004c 20 salt_len + 0000004d 0b 0c 89 salt + 00000050 b5 ab 15 e3 7f e4 4d b9 a7 ef 71 48 14 3b ab 26 + 00000060 5f 34 7f 6d 48 2e 9f 78 48 58 6d 9a fb + 0000006d 6d b2 db ed25519_sig + 00000070 2f 97 8e c8 12 fc 57 7f 85 aa d1 59 bc 80 40 0b + 00000080 be 2e f0 e1 23 2d bf 4b 71 7e d0 e4 c0 36 e4 d2 + 00000090 cf b2 9f b4 a8 4f 3e 2a 21 89 74 c2 33 55 af ac + 000000a0 41 36 1b 2b 60 09 f2 d9 19 f4 41 12 0b +``` + +### Signing subkey + +```text +$ sq packet dump --hex alice.priv-6--SecretSubkey +Secret-Subkey Packet, new CTB, 2 header bytes + 75 bytes + Version: 6 + Creation time: 2023-09-29 15:17:58 UTC + Pk algo: Ed25519 + Pk size: 256 bits + Fingerprint: D07B24EC91A14DD240AC2D53E6C8A9E054949A41222EA738576ED19CAEA3DC99 + KeyID: D07B24EC91A14DD2 + + Secret Key: + + Unencrypted + + 00000000 c7 CTB + 00000001 4b length + 00000002 06 version + 00000003 65 16 ea a6 creation_time + 00000007 1b pk_algo + 00000008 00 00 00 20 public_len + 0000000c 33 8c d4 f5 ed25519_public + 00000010 1a 73 39 ef ce d6 0f 21 8d a0 58 a2 3c 3d 44 a8 + 00000020 59 e9 13 1f 12 9c 6f 19 d0 3d 40 a0 + 0000002c 00 s2k_usage + 0000002d 0e cb d1 ed25519_secret + 00000030 c9 bc 81 82 aa 77 1f a8 12 a6 2a 74 a4 20 c1 74 + 00000040 76 f3 86 24 fb a8 25 a5 62 dd d6 a2 91 +``` + +```text +$ sq packet dump --hex alice.priv-7--Signature +Signature Packet, new CTB, 3 header bytes + 325 bytes + Version: 6 + Type: SubkeyBinding + Pk algo: Ed25519 + Hash algo: SHA512 + Hashed area: + Signature creation time: 2023-09-29 15:17:58 UTC (critical) + Key expiration time: P1095DT62781S (critical) + Key flags: S (critical) + Embedded signature: (critical) + Signature Packet + Version: 6 + Type: PrimaryKeyBinding + Pk algo: Ed25519 + Hash algo: SHA512 + Hashed area: + Signature creation time: 2023-09-29 15:17:58 UTC (critical) + Issuer Fingerprint: D07B24EC91A14DD240AC2D53E6C8A9E054949A41222EA738576ED19CAEA3DC99 + Digest prefix: 5365 + Level: 0 (signature over data) + + Issuer Fingerprint: AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3 + Unhashed area: + Issuer: AAA18CBB254685C5 + Digest prefix: 841C + Level: 0 (signature over data) + + 00000000 c2 CTB + 00000001 c0 85 length + 00000003 06 version + 00000004 18 type + 00000005 1b pk_algo + 00000006 0a hash_algo + 00000007 00 00 00 cc hashed_area_len + 0000000b 05 subpacket length + 0000000c 82 subpacket tag + 0000000d 65 16 ea sig creation time + 00000010 a6 + 00000011 05 subpacket length + 00000012 89 subpacket tag + 00000013 05 a4 8f bd key expiry time + 00000017 02 subpacket length + 00000018 9b subpacket tag + 00000019 02 key flags + 0000001a 99 subpacket length + 0000001b a0 subpacket tag + 0000001c 06 19 1b 0a embedded sig + 00000020 00 00 00 29 05 82 65 16 ea a6 22 21 06 d0 7b 24 + 00000030 ec 91 a1 4d d2 40 ac 2d 53 e6 c8 a9 e0 54 94 9a + 00000040 41 22 2e a7 38 57 6e d1 9c ae a3 dc 99 00 00 00 + 00000050 00 53 65 20 42 03 ad 0c db fc b5 9a 98 a6 15 27 + 00000060 e4 11 5e f5 f2 a0 3d bc ed 8d 94 27 41 09 f6 3c + 00000070 4b f8 8a e5 af 73 e1 7d 54 07 40 3f f3 29 34 c2 + 00000080 e7 60 56 a5 e1 43 cb 08 ba 66 fe 8b 26 ce e7 cb + 00000090 a5 3a 46 bb a5 c8 5d e4 6a de ae 49 e1 3e 07 bf + 000000a0 c4 9e 98 14 2f 3e c5 f7 01 3e 3e 4f f6 18 2a ac + 000000b0 bd ed 52 0c + 000000b4 22 subpacket length + 000000b5 21 subpacket tag + 000000b6 06 version + 000000b7 aa a1 8c bb 25 46 85 c5 83 issuer fp + 000000c0 58 32 05 63 fd 37 b6 7f 33 00 f9 fb 0e c4 57 37 + 000000d0 8c d2 9f 10 26 98 b3 + 000000d7 00 00 00 0a unhashed_area_len + 000000db 09 subpacket length + 000000dc 10 subpacket tag + 000000dd aa a1 8c issuer + 000000e0 bb 25 46 85 c5 + 000000e5 84 digest_prefix1 + 000000e6 1c digest_prefix2 + 000000e7 20 salt_len + 000000e8 23 3d b2 49 f3 02 4b 08 salt + 000000f0 93 af ba 08 89 f0 e0 91 0f ab 22 26 aa b3 56 57 + 00000100 30 ea 95 29 06 60 6f 00 + 00000108 be 44 a1 95 38 a9 6b 3a ed25519_sig + 00000110 3e 51 f0 55 09 b1 e2 91 a9 17 86 fa f5 1e 3f d0 + 00000120 28 46 3c ce 6e 88 14 37 32 ec 3d fa c6 01 ca e5 + 00000130 a9 4b b7 63 94 c3 0d 92 ab dc fa 23 50 71 60 31 + 00000140 a6 73 c8 33 5a 9c d9 0a +``` ### User IDs From 96d9eff25f1ae9eb93ae09320c59d9b0b560a746 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 7 Oct 2023 15:31:30 +0200 Subject: [PATCH 05/22] ch4: zooming in, fix indentation of sq dump output --- book/source/04-certificates.md | 44 +++++++++++++++++----------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 7105b53..aec87b6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -354,12 +354,12 @@ The output starts with the (primary) [Secret-Key packet](https://www.ietf.org/ar ```text Secret-Key Packet, new CTB, 2 header bytes + 75 bytes -Version: 6 -Creation time: 2023-09-29 15:17:58 UTC -Pk algo: Ed25519 -Pk size: 256 bits -Fingerprint: AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3 -KeyID: AAA18CBB254685C5 + Version: 6 + Creation time: 2023-09-29 15:17:58 UTC + Pk algo: Ed25519 + Pk size: 256 bits + Fingerprint: AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3 + KeyID: AAA18CBB254685C5 Secret Key: @@ -418,22 +418,22 @@ This packet "binds the information in the signature subpackets to the key". Each ```text Signature Packet, new CTB, 2 header bytes + 182 bytes -Version: 6 -Type: DirectKey -Pk algo: Ed25519 -Hash algo: SHA512 -Hashed area: -Signature creation time: 2023-09-29 15:17:58 UTC (critical) -Key expiration time: P1095DT62781S (critical) -Symmetric algo preferences: AES256, AES128 -Hash preferences: SHA512, SHA256 -Key flags: C (critical) -Features: MDC -Issuer Fingerprint: AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3 -Unhashed area: -Issuer: AAA18CBB254685C5 -Digest prefix: 6747 -Level: 0 (signature over data) + Version: 6 + Type: DirectKey + Pk algo: Ed25519 + Hash algo: SHA512 + Hashed area: + Signature creation time: 2023-09-29 15:17:58 UTC (critical) + Key expiration time: P1095DT62781S (critical) + Symmetric algo preferences: AES256, AES128 + Hash preferences: SHA512, SHA256 + Key flags: C (critical) + Features: MDC + Issuer Fingerprint: AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3 + Unhashed area: + Issuer: AAA18CBB254685C5 + Digest prefix: 6747 + Level: 0 (signature over data) 00000000 c2 CTB 00000001 b6 length From 74e3810e8452cfdb51aff6027d9d2a0380f38b6d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 7 Oct 2023 15:34:49 +0200 Subject: [PATCH 06/22] ch4: zooming in, edits --- book/source/04-certificates.md | 40 +++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index aec87b6..5f51224 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -342,7 +342,7 @@ ECaYswAAAAoJEKqhjLslRoXFZ0cgouNjgeNr0E9W18g4gAIl6FM5SWuQxg12j0S0 We'll now decode this OpenPGP data, and inspect the two packets in detail. -To generate the output, we run the Sequoia-PGP tool `sq`, using the `packet dump` subcommand. The output of `sq` is one block of text, but we'll break the output up into sections here, to discuss the content of each packet: +To inspect the internal structure of the OpenPGP data, we run the Sequoia-PGP tool `sq`, using the `packet dump` subcommand. The output of `sq` is one block of text, but to discuss the content of each packet we'll break the output up into sections here: ```text $ sq packet dump --hex alice_minimal.priv @@ -394,11 +394,11 @@ This means that the next part of the packet follows the structure of [Version 6 - `creation_time: 0x6516eaa6`: "The time that the key was created" (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) - `pk_algo: 0x1b`: "The public-key algorithm of this key" (decimal value 27, see the list of [Public-Key Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-algorithms)) - `public_len: 0x00000020`: "Octet count for the following public key material" (in this case, the length of the following `ed25519_public` field) -- `ed25519_public`: [Algorithm-specific representation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-algorithm-specific-part-for-ed2) of the public key material (the format is based on the value of `pk_algo`), in this case 32 bytes of the Ed25519 public key +- `ed25519_public`: [Algorithm-specific representation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-algorithm-specific-part-for-ed2) of the public key material (the format is based on the value of `pk_algo`), in this case 32 bytes of Ed25519 public key This concludes the Public Key section of the packet. The remaining data follows the [Secret-Key packet format](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats): -- `s2k_usage: 0x00`: [This *S2K usage* value](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-encryption-s2k-u) specifies that the secret-key data is not encrypted +- `s2k_usage: 0x00`: This [*S2K usage* value](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-encryption-s2k-u) specifies that the secret-key data is not encrypted - `ed25519_secret`: [Algorithm-specific representation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-algorithm-specific-part-for-ed2) of the secret key data (the format is based on the value of `pk_algo`) [^CTB]: Sequoia uses the term CTB (Cipher Type Byte) to refer to the RFC's [Packet Tag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-headers) @@ -493,7 +493,7 @@ The packet tag defines the semantics of the remaining data in the packet. We're - `version: 0x06`: This is a version 6 signature (some of the following packet format is specific to this signature version). - `type: 0x1f`: The [Signature Type](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-types) -- `pk_algo: 0x1b`: Public-key algorithm (decimal 27 corresponds, to [Ed25519](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-algorithms)) +- `pk_algo: 0x1b`: Public-key algorithm (decimal 27, corresponds to [Ed25519](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-algorithms)) - `hash_algo: 0x0a`: Hash algorithm (decimal 10, corresponds to [SHA2-512](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-hash-algorithms)) - `hashed_area_len: 0x0000003d`: Length of the following hashed subpacket data @@ -503,19 +503,19 @@ There are two sets of subpacket data in a Signature: hashed, and unhashed. The d The following subpacket data consists of sets of "subpacket length, subpacket tag, data." We'll show the information for each subpacket as one line, starting with the [subpacket type description](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-subpacket-specifi) (based on the subpacket tag). Note that bit 7 of the subpacket tag signals if that subpacket is ["critical"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#section-5.2.3.7-10)[^critical]. -[^critical]: Critical here means: the receiver must be able to interpret the subpacket and is expected to fail, otherwise. non-critical subpackets may be ignored by the receiver +[^critical]: Critical here means: the receiver must be able to interpret the subpacket and is expected to fail, otherwise. Non-critical subpackets may be ignored by the receiver -- [Signature creation time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-creation-subpacket) (subpacket type 2) *critical*: `0x6516eaa6` -- [Key expiration time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9) *critical*: `0x05a48fbd` -- [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-v1-seipd) (type 11): `0x09 0x07`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#symmetric-algos): "AES with 256-bit key" and "AES with 128-bit key") -- [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-hashes-subpacket) (subpacket type 21): `0x0a 0x08`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-hash-algorithms): "SHA2-512" and "SHA2-256") -- [Key flags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) (subpacket type 27) *critical*: `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-flags) to the "certifications" key flag) -- [Features](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#features-subpacket) (subpacket type 30): `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-features) to: "Symmetrically Encrypted Integrity Protected Data packet version 1") +- [Signature creation time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-creation-subpacket) (subpacket type 2) *critical*: `0x6516eaa6` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) +- [Key expiration time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9) *critical*: `0x05a48fbd` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) +- [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-v1-seipd) (type 11): `0x09 0x07`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#symmetric-algos): *AES with 256-bit key* and *AES with 128-bit key*) +- [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-hashes-subpacket) (subpacket type 21): `0x0a 0x08`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-hash-algorithms): *SHA2-512* and *SHA2-256*) +- [Key flags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) (subpacket type 27) *critical*: `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-flags) to the *certifications* key flag) +- [Features](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#features-subpacket) (subpacket type 30): `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-features) to: *Symmetrically Encrypted Integrity Protected Data packet version 1*) - [Issuer fingerprint](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#issuer-fingerprint-subpacket) (subpacket type 33): `aaa18cbb254685c58358320563fd37b67f3300f9fb0ec457378cd29f102698b3` (this is the fingerprint of the component key that issued the signature in this packet. Not that here, the value is the primary key fingerprint of the certificate we're looking at.) The next part of this packet contains "unhashed subpacket data": -- `unhashed_area_len: 0x0000000a`: Length of the following unhashed subpacket data. +- `unhashed_area_len: 0x0000000a`: Length of the following unhashed subpacket data (value: 10 bytes). As above, the following subpacket data consists of sets of "subpacket length, subpacket tag, data." In this case, only subpacket follows: @@ -527,17 +527,21 @@ This concludes the unhashed subpacket data. - `salt_len, salt`: A random [salt value](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-advantages-of-salted-signat) (the size must be [matching for the hash algorithm](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#hash-algorithms-registry)) - `ed25519_sig`: [Algorithm-specific](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-algorithm-specific-fields-for-ed2) representation of the signature (in this case: 64 bytes of Ed25519 signature) +The signature is calculated over a hash. The hash, in this case, is calculated over the following data (for details, see [Computing Signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-computing-signatures) in the RFC): + +- The signature's salt +- A serialized form of the primary key's public data +- A serialized form of this direct key signature packet (up to, but excluding the unhashed area) + ```{figure} diag/key-minimal.png :width: 40% A minimal OpenPGP key, visualized ``` -### Seen as an OpenPGP certificate +### Seen as a very minimal OpenPGP certificate -Let's now look at a "public key" view of the (very minimal) OpenPGP key above. That is, the same data, but without the private key material parts. - -An OpenPGP user might give such a certificate to a communication partner, or upload it to a key server: +Let's now look at a "public key" view of the (very minimal) OpenPGP key above. That is, the same data, but without the private key material parts. An OpenPGP user might give such a certificate to a communication partner, or upload it to a key server: ```text $ sq key extract-cert alice_minimal.priv @@ -801,9 +805,9 @@ Signature Packet, new CTB, 3 header bytes + 325 bytes 00000140 a6 73 c8 33 5a 9c d9 0a ``` -### User IDs +### User ID -User IDs are a mechanism for attaching *identities* to an OpenPGP certificate. Typically, a User ID will contain a name and an email address. +User IDs are a mechanism for attaching *identities* to an OpenPGP certificate. Traditionally, User IDs contain a string that combines a name and an email address. To look into these, we'll make a certificate that has one [User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#uid). 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. From 8bf3440373819db24aaf288fc615a51655f33d9b Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 7 Oct 2023 16:14:02 +0200 Subject: [PATCH 07/22] ch4: zooming in, write subkey sections --- book/source/04-certificates.md | 53 ++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 5f51224..8d2ae8c 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -599,7 +599,18 @@ In the following examples, we will only look at OpenPGP keys that include the pr ### Encryption subkey -Now we'll look at a subkey in Alice's key. In the split version of Alice's key, the encryption subkey is in `alice.priv-4--SecretSubkey`, and the binding self-signature for the subkey in `alice.priv-5--Signature`. +Now we'll look at a subkey in Alice's key. An OpenPGP subkey, when it is linked to an OpenPGP certificate, effectively consists of two elements: + +- a key packet that contains the component key itself, and +- a signature packet that links this component key to the primary key (and thus implicitly to the full OpenPGP certificate). + +In this section, we'll use the files that contain individual packets of Alice's key, which we generated above. In this split representation of Alice's key, the encryption subkey happens to be stored in `alice.priv-4--SecretSubkey`, and the associated binding self-signature for the subkey in `alice.priv-5--Signature`. + +If we were looking at a regular (not split apart) OpenPGP key, we would look at the output of something like `$ sq packet dump --hex alice.priv`, and would be shown a longer series of packets. That series would contain the two packets we'll now look at, with the exact same content. They would just be slightly harder to locate, in the larger context of a full OpenPGP key. + +#### Secret-Subkey packet + +First, we'll look at the *Secret-Subkey packet* that contains the component key data of this subkey: ```text $ sq packet dump --hex alice.priv-4--SecretSubkey @@ -630,10 +641,21 @@ Secret-Subkey Packet, new CTB, 2 header bytes + 75 bytes 00000040 c9 77 fb bd 23 41 73 c9 57 5a bf 7c 4c ``` -Notice that the structure of this *Secret-Subkey packet* is exactly the same as the *Secret-Key Packet*, above. The packet tag (`CTB`) is set to packet type 7, here (*Secret-Subkey packet*). +Notice that the structure of this *Secret-Subkey packet* is the same as the *Secret-Key Packet* of the primary key, above. Only the content of the two packets differs in some points: -The `pk_algo` value is set to 0x19 (or decimal) 25, which [corresponds to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-algorithms) X25519. +- The packet tag (`CTB`) in this packet shows type 7 ([*Secret-Subkey packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-subkey-packet-tag-7)). +- The `pk_algo` value is set to `0x19` (decimal 25), which [corresponds to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-public-key-algorithms) X25519. Note that even though both the primary key and this subkey use a cryptographic mechanism based on Curve25519, this encryption key uses Curve 25519 in a different way (X25519 is a Diffie–Hellman function built out of Curve25519). +- Accordingly, both parts of the cryptographic key pair are labeled with the corresponding names `x25519_public` and `x25519_secret` (however, note that this difference only reflects the semantics of the fields, which are implied by the value of `pk_algo`. The actual data in both fields consists of just 32 bytes of cryptographic key material, without any type information.) +#### Subkey binding signature + +The subkey packet above by itself is disconnected from the OpenPGP certificate that it is a part of. The link between the subkey and the full OpenPGP key is made with a cryptographic signature, which is issued by the OpenPGP key's primary key. + +The type of signature that is used for this is called a *subkey binding signature*, because it "binds" (as in "connects") the subkey to the rest of the key. + +In addition to its core purpose of making the connection, this signature also contains additional metadata about the subkey. One reason why this metadata is in a binding signature (and not in the subkey packet) is that it may change over time. The subkey packet itself may not change over time. So metadata about the subkey that can change is stored in self-signatures: if the key holder wants to change some metadata (for example, the key's expiration time), they can issue a newer version of the same kind of signature. Receiving OpenPGP software will then understand that the newer self-signature supercedes the older signature, and that the metadata in the newer signature reflects the most current intent of the key holder. + +Note that this subkey binding signature packet is quite similar to the Direct Key Signature we discussed packet above. Both signatures perform the same function in terms of adding metadata to a component key. In particular, the hashed subpacket data contains many of the same pieces of metadata. ```text $ sq packet dump --hex alice.priv-5--Signature @@ -691,6 +713,31 @@ Signature Packet, new CTB, 2 header bytes + 171 bytes 000000a0 41 36 1b 2b 60 09 f2 d9 19 f4 41 12 0b ``` +We'll go over this packet dump in less detail, since its structure mirrors the *Direct Key Signature* (described above) very closely. + +The first difference is in the `type` field, showing that this signature is of type `0x18` ([Subkey Binding Signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-subkey-binding-signature-si)). + +The `pk_algo` of this signature is informed by the algorithm of the primary key (`0x1b`, corresponding to Ed25519). The signature in this packet is issued by the primary key, so by definition it uses the signing algorithm of the primary key (that is: the algorithm used to produce the cryptographic signature in this packet is entire independent of the `pk_algo` of the key material of this subkey itself, which uses the X25519 mechanism). + +As shown in the header of this packet dump, the hashed subpacket data contains four pieces of information: + +- Signature creation time: `2023-09-29 15:17:58 UTC` (**critical**) +- Key expiration time: `P1095DT62781S` (**critical**) +- Key flags: `EtEr` (**critical**) (encryption for communication, encryption for storage) +- Issuer Fingerprint: `AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3` + +The remainder of the packet has the same content as the *Direct Key Signature* above: +- A 16 bit digest prefix +- A salt value +- The cryptographic signature itself + +The signature is calculated over a hash. The hash, in this case, is calculated over the following data (for details, see [Computing Signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-computing-signatures) in the RFC): + +- The signature's salt +- A serialized form of the primary key's public data +- A serialized form of the subkey's public data +- A serialized form of this subkey binding signature packet (up to, but excluding the unhashed area) + ### Signing subkey ```text From fd2469e0e4762b4d969077edac1b61258a0aa4a1 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 9 Oct 2023 18:57:56 +0200 Subject: [PATCH 08/22] ch4: make links for "more on this below" pointers --- book/source/04-certificates.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 8d2ae8c..e80769b 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -93,7 +93,7 @@ In the RFC, the OpenPGP primary key is also sometimes referred to as "top-level In addition to the primary key, modern OpenPGP certificates usually contain a number of "subkeys" (however, it's not technically necessary for a certificate to contain subkeys). -Subkeys have the same structure as the primary key, but they are used in a different role. Subkeys are cryptographically linked with the primary key (more on this below). +Subkeys have the same structure as the primary key, but they are used in a different role. Subkeys are cryptographically linked with the primary key (more on this in {numref}`binding_subkeys`). ```{figure} diag/Subkeys.png :name: Certificate with Subkeys @@ -140,8 +140,14 @@ OpenPGP certificates can contain any number of User IDs One User ID in a certificate has the special property of being the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-primary-user-id). -User IDs are associated with preference settings (such as preferred encryption algorithms, more on this below). The preferences associated with the Primary User ID are used by default. +User IDs are associated with preference settings (such as preferred encryption algorithms, more on this in {numref}`zooming_in_user_id`). The preferences associated with the Primary User ID are used by default. +```{admonition} TODO +:class: warning + +i think crypto-refresh suggests that the direct key signature should hold the default preferences? +we might need to write a more nuanced text here, about how DKS and primary user id interact in v6, and mention the differences to v4? +``` #### User attributes @@ -172,6 +178,7 @@ Note, though, that there are some cases where third parties legitimately add "un [^flooding]: Storing third-party identity certifications in the target OpenPGP certificate is convenient for consumers: it is easy to find all relevant certifications in one central location. However, when third parties can unilaterally add certifications, this opens an avenue for denial-of-service attacks by flooding. The SKS network of OpenPGP key servers [allowed and experienced this problem](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html). +(binding_subkeys)= #### Binding subkeys to an OpenPGP certificate Linking a subkey to an OpenPGP certificate is done with a ["Subkey Binding Signature"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding). Such a signature signals that the "primary key wants to be associated with the subkey". @@ -852,6 +859,7 @@ Signature Packet, new CTB, 3 header bytes + 325 bytes 00000140 a6 73 c8 33 5a 9c d9 0a ``` +(zooming_in_user_id)= ### User ID User IDs are a mechanism for attaching *identities* to an OpenPGP certificate. Traditionally, User IDs contain a string that combines a name and an email address. From 74710d804a84934900c5259cb77f5605b02d9d62 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 9 Oct 2023 19:19:30 +0200 Subject: [PATCH 09/22] ch4: clarify the primary key can't confer validity beyond its own --- book/source/04-certificates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index e80769b..8d5e787 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -83,6 +83,8 @@ The "OpenPGP primary key" is a component key that serves a central role in an Op - Its fingerprint is used as the unique identifier for the full OpenPGP certificate. - It is used for lifecycle operations, such as adding or invalidating subkeys or identities in a certificate. +The validity of the primary key limits its capacity to confer validity to other components. E.g.: The primary key cannot confer an expiration time beyond its own expiration to a subkey. It can also not confer validity to components after it has been revoked. + ```{admonition} Terminology :class: note From 1f89d39740cde88c91f90056deeab21a045841eb Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 9 Oct 2023 19:30:16 +0200 Subject: [PATCH 10/22] ch4: link to glossary for "CA" --- book/source/04-certificates.md | 2 +- book/source/18-glossary.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 8d5e787..3f442ae 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -40,7 +40,7 @@ We sometimes collectively refer to component keys and identity information as "t Typical components in an OpenPGP certificate ``` -All elements in an OpenPGP certificate are structured around one central component: the *OpenPGP primary key*. The primary key acts as a personal CA for the certificate's owner: It can make cryptographic statements about subkeys, identities, expiration, revocation, ... +All elements in an OpenPGP certificate are structured around one central component: the *OpenPGP primary key*. The primary key acts as a personal {term}`CA` for the certificate's owner: It can make cryptographic statements about subkeys, identities, expiration, revocation, ... ```{note} OpenPGP certificates are typically long-lived and may be changed (typically by their owner), over time. Components can be added and invalidated, over the lifetime of a certificate diff --git a/book/source/18-glossary.md b/book/source/18-glossary.md index 8c69f3b..31d8674 100644 --- a/book/source/18-glossary.md +++ b/book/source/18-glossary.md @@ -9,6 +9,9 @@ Authentication Certification "Third party Signature" on a certificate, making a statement about that certificate, or an identity in the certificate +CA + [Certificate authority](https://en.wikipedia.org/wiki/Certificate_authority) or certification authority. An entity that handles digital certificates, especially by signing or issuing them. + Delegation See {term}`Trust signature` From 66087b3ec93167d2b2f62c3607c225a8c1020d3c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 9 Oct 2023 19:31:31 +0200 Subject: [PATCH 11/22] ch4: clarify terms, use "identity components" --- book/source/04-certificates.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 3f442ae..bc1335a 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -125,8 +125,11 @@ It is considered good practice to have separate component keys for each type of [^key-flag-sharing]: With ECC algorithms, it's actually not possible to share encryption functionality with the signing-based functionalities, e.g.: ed25519 used for signing; cv25519 used for encryption. +(identity_components)= ### Identity components +Identity components in an OpenPGP certificate are used by the certificate holder to state that they are known by a certain identifier (like a name, or an email address). + #### User IDs An OpenPGP certificate can contain any number of [User IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-id-packet-tag-13). Each User ID associates the certificate with an identity. @@ -165,11 +168,11 @@ Internally, an OpenPGP certificate consists of a sequence of OpenPGP packets. Th [^tpk]: When stored in a file, OpenPGP certificates are in a format called [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-public-keys). -However, the owner of a certificate doesn't want a third party to add subkeys (or add identity claims) to their certificate, pretending that the certificate owner put those components there. +However, the owner of a certificate doesn't want a third party to add subkeys (or add [identity components](identity_components)) to their certificate, pretending that the certificate owner put those components there. To prevent malicious addition of components, OpenPGP uses cryptographic signatures. These signatures show that components have been added by the owner of the OpenPGP certificate (these linking signatures are issued by the primary key of the certificate). -So while anyone can still unilaterally store unrelated subkeys and identity claims in an OpenPGP certificate dataset, OpenPGP implementations that read this file should discard components that don't have a valid cryptographic connection with the certificate. +So while anyone can still unilaterally store unrelated subkeys and [identity components](identity_components) in an OpenPGP certificate dataset, OpenPGP implementations that read this file should discard components that don't have a valid cryptographic connection with the certificate. (Conversely, it's easy for a third party to leave out packets when passing on an OpenPGP certificate. An attacker can, for example, choose to omit revocation packets. The recipient of such a partial copy has no way to notice the omission, without access to a different source for the certificate that contains the revocation packet.) From 134407ee2f232feecc59ac806ce47c2184be8164 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 12:53:23 +0200 Subject: [PATCH 12/22] ch4: add a TODO note --- book/source/04-certificates.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index bc1335a..9f88ca0 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -290,6 +290,12 @@ Wiktor suggests to check: https://blogs.gentoo.org/mgorny/2018/08/13/openpgp-key (unbound_user_ids)= ### Adding unbound User IDs to a certificate +```{admonition} TODO +:class: warning + +references/links missing +``` + Some OpenPGP subsystems may add User IDs to a certificate, which are not bound to the primary key by the certificate's owner. This can be useful to store local identity information (e.g., Sequoia's public store attaches "pet-names" to certificates, in this way). ## Zooming in: Packet structure From a1fe545e884db81a469fa3950c1ef82aa4d04b47 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 12:52:14 +0200 Subject: [PATCH 13/22] ch4: add a note that the example key isn't password protected Add link to ch5 for discussion of encrypted private key material. --- book/source/04-certificates.md | 3 +++ book/source/05-private.md | 10 ++++++++++ 2 files changed, 13 insertions(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 9f88ca0..7790c74 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -306,6 +306,9 @@ Now that we've established the concepts of the components that OpenPGP certifica We'll start with a very minimal version of [](alice_priv), stored as a *transferable secret key* ([RFC 10.2.](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#transferable-secret-keys)) (that is, including private key material). +Note that the secret key material we're using in this chapter is not password protected. To learn more about encrypting private key material with passwords in OpenPGP, see +{numref}`encrypted_secrets`. + In this section, we use the Sequoia-PGP tool `sq` to handle and transform our example OpenPGP key, and to inspect internal OpenPGP packet data. One way to produce this minimal version of Alice's key is: diff --git a/book/source/05-private.md b/book/source/05-private.md index ae4d001..a0bf8de 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -12,6 +12,16 @@ https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-secret-keys +(encrypted_secrets)= +## Password protecting secret key material + +```{admonition} TODO +:class: warning + +S2K, symmetric encryption +``` + + ## Private key operations The core of private key operations doesn't require access to the whole certificate. A private key subsystem only needs to handle the cryptographic key material. From c1acc328d0234adf559681b4a2e9c21f9939a31c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 13:23:52 +0200 Subject: [PATCH 14/22] ch4: move "criticality" footnote into a more visible note block --- book/source/04-certificates.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 7790c74..841a49e 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -522,9 +522,11 @@ The next part of this packet contains hashed subpacket data. A subpacket data se There are two sets of subpacket data in a Signature: hashed, and unhashed. The difference is that the hashed subpackets are protected by the digital signature of this packet, while the unhashed subpackets are not. -The following subpacket data consists of sets of "subpacket length, subpacket tag, data." We'll show the information for each subpacket as one line, starting with the [subpacket type description](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-subpacket-specifi) (based on the subpacket tag). Note that bit 7 of the subpacket tag signals if that subpacket is ["critical"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#section-5.2.3.7-10)[^critical]. +The following subpacket data consists of sets of "subpacket length, subpacket tag, data." We'll show the information for each subpacket as one line, starting with the [subpacket type description](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-subpacket-specifi) (based on the subpacket tag). Note that bit 7 of the subpacket tag signals if that subpacket is ["critical"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#section-5.2.3.7-10). -[^critical]: Critical here means: the receiver must be able to interpret the subpacket and is expected to fail, otherwise. Non-critical subpackets may be ignored by the receiver +```{note} +Critical here means: the receiver must be able to interpret the subpacket and is expected to fail, otherwise. Non-critical subpackets may be ignored by the receiver. +``` - [Signature creation time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-creation-subpacket) (subpacket type 2) *critical*: `0x6516eaa6` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) - [Key expiration time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9) *critical*: `0x05a48fbd` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) From af355ae81e257fde789904536f2d4c419e1ecade Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 13:24:12 +0200 Subject: [PATCH 15/22] ch4: adjust markup/styling of critical flags --- book/source/04-certificates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 841a49e..370f04f 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -528,11 +528,11 @@ The following subpacket data consists of sets of "subpacket length, subpacket ta Critical here means: the receiver must be able to interpret the subpacket and is expected to fail, otherwise. Non-critical subpackets may be ignored by the receiver. ``` -- [Signature creation time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-creation-subpacket) (subpacket type 2) *critical*: `0x6516eaa6` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) -- [Key expiration time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9) *critical*: `0x05a48fbd` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) +- [Signature creation time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-creation-subpacket) (subpacket type 2, **critical**): `0x6516eaa6` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) +- [Key expiration time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9, **critical**): `0x05a48fbd` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) - [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-v1-seipd) (type 11): `0x09 0x07`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#symmetric-algos): *AES with 256-bit key* and *AES with 128-bit key*) - [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-hashes-subpacket) (subpacket type 21): `0x0a 0x08`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-hash-algorithms): *SHA2-512* and *SHA2-256*) -- [Key flags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) (subpacket type 27) *critical*: `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-flags) to the *certifications* key flag) +- [Key flags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) (subpacket type 27, **critical**): `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-flags) to the *certifications* key flag) - [Features](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#features-subpacket) (subpacket type 30): `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-features) to: *Symmetrically Encrypted Integrity Protected Data packet version 1*) - [Issuer fingerprint](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#issuer-fingerprint-subpacket) (subpacket type 33): `aaa18cbb254685c58358320563fd37b67f3300f9fb0ec457378cd29f102698b3` (this is the fingerprint of the component key that issued the signature in this packet. Not that here, the value is the primary key fingerprint of the certificate we're looking at.) From 2a3605f7318e1115e8ba820bf1c3c76e081ea220 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 13:51:57 +0200 Subject: [PATCH 16/22] ch4: move diagram up --- book/source/04-certificates.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 370f04f..408ccfb 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -343,6 +343,24 @@ This version of Alice's key contains just two packets: - The [*Secret-Key packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats) for the primary key, and - A [*Direct Key Signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-direct-key) (a self-signature that binds metadata to the primary key). +This is the shape of the packets we'll be looking at, in the following two sections: + +```{figure} diag/key-minimal.png +:width: 40% + +A minimal OpenPGP key, visualized +``` + +```{admonition} VISUAL +:class: warning + +This diagram needs adjustments about + - what exactly is signed + - fix naming of fields? + +We could show repeat-copies of the individual packet visualization again, below for each packet-related section. +``` + In the real world, you won't usually encounter an OpenPGP key that is quite this minimal. However, this is technically a valid OpenPGP key (and we'll add more components to it, later in this section). In ASCII-armored representation, this very minimal key looks like this: @@ -556,12 +574,6 @@ The signature is calculated over a hash. The hash, in this case, is calculated o - A serialized form of the primary key's public data - A serialized form of this direct key signature packet (up to, but excluding the unhashed area) -```{figure} diag/key-minimal.png -:width: 40% - -A minimal OpenPGP key, visualized -``` - ### Seen as a very minimal OpenPGP certificate Let's now look at a "public key" view of the (very minimal) OpenPGP key above. That is, the same data, but without the private key material parts. An OpenPGP user might give such a certificate to a communication partner, or upload it to a key server: From bab5e427e97f6ebd18b471841c937bf84ad10f5d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 13:55:33 +0200 Subject: [PATCH 17/22] ch4: add a section to talk about "no more user facing hex fingerprints in v6" --- book/source/04-certificates.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 408ccfb..60da4d6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -261,6 +261,16 @@ This section only contains notes and still needs to be written Minimized versions, merging, effective "append only" semantics, ... +### "Naming" a certificate in user-facing contexts - fingerprints and beyond + +```{admonition} TODO +:class: warning + +In v4, a 20 byte fingerprint in hex representation was used to name certificates, even in user-facing contexts. + +For v6, this type of approach is discouraged, but a replacement mechanism is still pending. +``` + ### Merging - How to merge two copies of the same certificate? From 69f7eb60e5fd9c057e85f4da93a1b313aab8f918 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 14:46:15 +0200 Subject: [PATCH 18/22] ch4: clarify linking --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 60da4d6..c024a47 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -644,7 +644,7 @@ In the following examples, we will only look at OpenPGP keys that include the pr ### Encryption subkey -Now we'll look at a subkey in Alice's key. An OpenPGP subkey, when it is linked to an OpenPGP certificate, effectively consists of two elements: +Now we'll look at a subkey in Alice's key. An OpenPGP subkey, when it is linked to an OpenPGP certificate (via its primary key), effectively consists of two elements: - a key packet that contains the component key itself, and - a signature packet that links this component key to the primary key (and thus implicitly to the full OpenPGP certificate). From d1203075d1a8091dfd9eb0e2c11a08114b5a3467 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 15:03:09 +0200 Subject: [PATCH 19/22] ch4: move text into a "note" block And add a remark that a visualization would help. --- book/source/04-certificates.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index c024a47..ea794d7 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -651,7 +651,30 @@ Now we'll look at a subkey in Alice's key. An OpenPGP subkey, when it is linked In this section, we'll use the files that contain individual packets of Alice's key, which we generated above. In this split representation of Alice's key, the encryption subkey happens to be stored in `alice.priv-4--SecretSubkey`, and the associated binding self-signature for the subkey in `alice.priv-5--Signature`. -If we were looking at a regular (not split apart) OpenPGP key, we would look at the output of something like `$ sq packet dump --hex alice.priv`, and would be shown a longer series of packets. That series would contain the two packets we'll now look at, with the exact same content. They would just be slightly harder to locate, in the larger context of a full OpenPGP key. + +````{note} +It's common to look at a packet dump for a full OpenPGP key (not split apart), like this: + +```text +$ sq packet dump --hex alice.priv +``` + +That output shows a much longer series of packets (as shown in the diagram below). This output will contain the two packets we now look at, with the exact same data, but they would be a bit harder to locate visually. + +```{admonition} VISUAL +:class: warning + +Show a very abstract diagram of packets in a typical full OpenPGP key: +- Secret-Key packet +- Direct Key Signature +- User ID +- Certifying self-signature for User ID +- Secret-Subkey packet +- Subkey binding signature +- Secret-Subkey packet +- Subkey binding signature +``` +```` #### Secret-Subkey packet From 1aa4696f3eb5b603c55bd0d01d2dfd9f7b08d643 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 10 Oct 2023 16:26:31 +0200 Subject: [PATCH 20/22] ch4: add todo notes --- book/source/04-certificates.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ea794d7..32e2e31 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -721,7 +721,22 @@ The subkey packet above by itself is disconnected from the OpenPGP certificate t The type of signature that is used for this is called a *subkey binding signature*, because it "binds" (as in "connects") the subkey to the rest of the key. -In addition to its core purpose of making the connection, this signature also contains additional metadata about the subkey. One reason why this metadata is in a binding signature (and not in the subkey packet) is that it may change over time. The subkey packet itself may not change over time. So metadata about the subkey that can change is stored in self-signatures: if the key holder wants to change some metadata (for example, the key's expiration time), they can issue a newer version of the same kind of signature. Receiving OpenPGP software will then understand that the newer self-signature supercedes the older signature, and that the metadata in the newer signature reflects the most current intent of the key holder. +```{admonition} VISUAL +:class: warning + +Add detailed packet diagram analogous to 4.6.1 +``` + +```{admonition} TODO +:class: warning + +david points out: "The information on metadata in binding signatures may also make sense in other contexts (direct key signature)?" + +Should this text go elsewhere? +- 4.2.3? +- ch 6? +``` +In addition to its core purpose of making the connection, this signature also contains additional metadata about the subkey. One reason why this metadata is in a binding signature (and not in the subkey packet) is that it may change over time. The subkey packet itself may not change over time. So metadata about the subkey that can change is stored in self-signatures: if the key holder wants to change some metadata (for example, the key's expiration time), they can issue a newer version of the same kind of signature. Receiving OpenPGP software will then understand that the newer self-signature supersedes the older signature, and that the metadata in the newer signature reflects the most current intent of the key holder. Note that this subkey binding signature packet is quite similar to the Direct Key Signature we discussed packet above. Both signatures perform the same function in terms of adding metadata to a component key. In particular, the hashed subpacket data contains many of the same pieces of metadata. @@ -808,6 +823,12 @@ The signature is calculated over a hash. The hash, in this case, is calculated o ### Signing subkey +```{admonition} TODO +:class: warning + +write +``` + ```text $ sq packet dump --hex alice.priv-6--SecretSubkey Secret-Subkey Packet, new CTB, 2 header bytes + 75 bytes From 3688054f4fe8259d23779f7ef6c21dfcc526d18a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 11 Oct 2023 20:37:31 +0200 Subject: [PATCH 21/22] ch4: restructure packet splitting text sections --- book/source/04-certificates.md | 48 ++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 32e2e31..83c5e22 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -321,13 +321,16 @@ Note that the secret key material we're using in this chapter is not password pr In this section, we use the Sequoia-PGP tool `sq` to handle and transform our example OpenPGP key, and to inspect internal OpenPGP packet data. -One way to produce this minimal version of Alice's key is: +(split_alice)= +#### Splitting an OpenPGP key into packets + +One way to produce a very minimal version of Alice's key is to split her full key into its component packets, and join only the relevant ones back together into a variant of the key. ```text $ sq packet split alice.priv ``` -With this command, `sq` generates a set of files, one for each packet in `alice.priv`: +With this command, `sq` generates a set of files, each containing an individual OpenPGP packet of the original full key in `alice.priv`: ```text alice.priv-0--SecretKey @@ -342,12 +345,32 @@ alice.priv-8--SecretSubkey alice.priv-9--Signature ``` +```{admonition} VISUAL +:class: warning + +Show a very abstract diagram of the packets of Alice's OpenPGP key (above): +- Secret-Key packet +- Direct Key Signature +- User ID +- Certifying self-signature for User ID +- Secret-Subkey packet +- Subkey binding signature +- Secret-Subkey packet +- Subkey binding signature +- Secret-Subkey packet +- Subkey binding signature +``` + +#### Joining packets into an OpenPGP key + For our first step, we'll use just the first two of these packets, and join them together as a private key: ```text $ sq packet join alice.priv-0--SecretKey alice.priv-1--Signature --output alice_minimal.priv ``` +#### Inspecting this key + This version of Alice's key contains just two packets: - The [*Secret-Key packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-packet-formats) for the primary key, and @@ -649,31 +672,18 @@ Now we'll look at a subkey in Alice's key. An OpenPGP subkey, when it is linked - a key packet that contains the component key itself, and - a signature packet that links this component key to the primary key (and thus implicitly to the full OpenPGP certificate). -In this section, we'll use the files that contain individual packets of Alice's key, which we generated above. In this split representation of Alice's key, the encryption subkey happens to be stored in `alice.priv-4--SecretSubkey`, and the associated binding self-signature for the subkey in `alice.priv-5--Signature`. - +In this section, we'll use the files that contain individual packets of Alice's key, which we split apart above. In this split representation of Alice's key, the encryption subkey happens to be stored in `alice.priv-4--SecretSubkey`, and the associated binding self-signature for the subkey in `alice.priv-5--Signature`. ````{note} -It's common to look at a packet dump for a full OpenPGP key (not split apart), like this: +It's common to look at a packet dump for a full OpenPGP key, like this: ```text $ sq packet dump --hex alice.priv ``` -That output shows a much longer series of packets (as shown in the diagram below). This output will contain the two packets we now look at, with the exact same data, but they would be a bit harder to locate visually. +That command shows the details for the full series of packets in an OpenPGP certificate (recall the list of [packets of Alice's key](split_alice)). Finding a particular packet in that list can take a moment. -```{admonition} VISUAL -:class: warning - -Show a very abstract diagram of packets in a typical full OpenPGP key: -- Secret-Key packet -- Direct Key Signature -- User ID -- Certifying self-signature for User ID -- Secret-Subkey packet -- Subkey binding signature -- Secret-Subkey packet -- Subkey binding signature -``` +In the following sections we're making it a bit easier for ourselves, and directly look at individual packets, from the files we created with `sq packet split`, above. ```` #### Secret-Subkey packet From 7617d7eea66ba0e2956b6e4640d0acb92c7510fa Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 11 Oct 2023 17:59:06 +0200 Subject: [PATCH 22/22] ch4: write "user id" zooming in section --- book/source/04-certificates.md | 195 ++++++++++++--------------------- 1 file changed, 72 insertions(+), 123 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 83c5e22..b1367a6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -482,6 +482,7 @@ The overall structure of OpenPGP packets is described in the [Packet Syntax](htt Note that the *Secret-Key packet* contains both the private and the public part of the key. +(zooming_in_dks)= #### Direct Key Signature The next packet is a [*Direct Key Signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-direct-key), which is bound to the primary key (the file `alice.priv-1--Signature` contains this packet). @@ -580,7 +581,7 @@ Critical here means: the receiver must be able to interpret the subpacket and is ``` - [Signature creation time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#signature-creation-subpacket) (subpacket type 2, **critical**): `0x6516eaa6` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) -- [Key expiration time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9, **critical**): `0x05a48fbd` (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-time-fields)) +- [Key expiration time](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-expiration-subpacket) (subpacket type 9, **critical**): `0x05a48fbd` (defined as number of seconds after the key creation time) - [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-v1-seipd) (type 11): `0x09 0x07`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#symmetric-algos): *AES with 256-bit key* and *AES with 128-bit key*) - [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#preferred-hashes-subpacket) (subpacket type 21): `0x0a 0x08`. (These values [correspond to](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-hash-algorithms): *SHA2-512* and *SHA2-256*) - [Key flags](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) (subpacket type 27, **critical**): `0x01`. (This value [corresponds](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-key-flags) to the *certifications* key flag) @@ -665,6 +666,7 @@ A minimal OpenPGP public certificate, visualized In the following examples, we will only look at OpenPGP keys that include the private key material. The corresponding "certificate" variants, which only contain the public key material, are easy to imagine: like here, their packet type is changed from a Secret-Key to a Public-Key variant, and they leave out the private key material. +(zoom_enc_subkey)= ### Encryption subkey Now we'll look at a subkey in Alice's key. An OpenPGP subkey, when it is linked to an OpenPGP certificate (via its primary key), effectively consists of two elements: @@ -812,7 +814,7 @@ The first difference is in the `type` field, showing that this signature is of t The `pk_algo` of this signature is informed by the algorithm of the primary key (`0x1b`, corresponding to Ed25519). The signature in this packet is issued by the primary key, so by definition it uses the signing algorithm of the primary key (that is: the algorithm used to produce the cryptographic signature in this packet is entire independent of the `pk_algo` of the key material of this subkey itself, which uses the X25519 mechanism). -As shown in the header of this packet dump, the hashed subpacket data contains four pieces of information: +As shown in the text at the top of this packet dump, the hashed subpacket data contains four pieces of information: - Signature creation time: `2023-09-29 15:17:58 UTC` (**critical**) - Key expiration time: `P1095DT62781S` (**critical**) @@ -952,127 +954,20 @@ Signature Packet, new CTB, 3 header bytes + 325 bytes ``` (zooming_in_user_id)= -### User ID +### Adding an identity component -User IDs are a mechanism for attaching *identities* to an OpenPGP certificate. Traditionally, User IDs contain a string that combines a name and an email address. +Now we'll look at an identity that is associated with Alice's certificate. -To look into these, we'll make a certificate that has one [User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#uid). 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. +User IDs are a mechanism for connecting [identities](identity_components) with an OpenPGP certificate. Traditionally, User IDs contain a string that combines a name and an email address. -Let's look into the details of this key: +Like [above](zoom_enc_subkey), to look at the internal packet structure of this identity and its connection the OpenPGP certificate, we'll inspect the two individual packets that constitute the identity component, the [User ID packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-id-packet-tag-13), in the file `alice.priv-2--UserID`, and the certifying self-signature a [Positive certification of a User ID and Public-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-positive-certification-of-a) in `alice.priv-3--Signature` (these packets are an excerpt of Alice's full OpenPGP private key). + +#### User ID packet + +First, let's look at the User ID packet, which encodes an identity that Alice has connected to her OpenPGP certificate: ```text ------BEGIN PGP PRIVATE KEY BLOCK----- -Comment: AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3 -Comment: - -xUsGZRbqphsAAAAgUyTpQ6+rFfdu1bUSmHlpzRtdEGXr50Liq0f0hrOuZT4A7+GZ -tV8R+6qT6CadO7ItciB9/71C3UvpozaBO6XMz/vCtgYfGwoAAAA9BYJlFuqmBYkF -pI+9AwsJBwMVCggCmwECHgEiIQaqoYy7JUaFxYNYMgVj/Te2fzMA+fsOxFc3jNKf -ECaYswAAAAoJEKqhjLslRoXFZ0cgouNjgeNr0E9W18g4gAIl6FM5SWuQxg12j0S0 -7ExCOI5NPRDCrSnAV85mAXOzeIGeiVLPQ40oEal3CX/L+BXIoY2sIEQrLd4TAEEy -0BA8aQZTPEmMdiOCM1QB+V+BQZAOzRM8YWxpY2VAZXhhbXBsZS5vcmc+wrkGExsK -AAAAQAWCZRbqpgWJBaSPvQMLCQcDFQoIApkBApsBAh4BIiEGqqGMuyVGhcWDWDIF -Y/03tn8zAPn7DsRXN4zSnxAmmLMAAAAKCRCqoYy7JUaFxdu4IIotb9pnNbxdBHe0 -nWeobsXWiFNf4u/5Zgi/wuDbwFYN69QspRkBD7om0IKiz1zreqly2fOyZgeLsro9 -t4nkdgRuNSQrJymDvpGceGrMtNVpR3YsKdZUv0MZBP9TmMDVCw== -=bgQM ------END PGP PRIVATE KEY BLOCK----- -``` - -```text -$ sq packet dump --hex alice_userid.priv -Secret-Key Packet, new CTB, 2 header bytes + 75 bytes - Version: 6 - Creation time: 2023-09-29 15:17:58 UTC - Pk algo: Ed25519 - Pk size: 256 bits - Fingerprint: AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3 - KeyID: AAA18CBB254685C5 - - Secret Key: - - Unencrypted - - 00000000 c5 CTB - 00000001 4b length - 00000002 06 version - 00000003 65 16 ea a6 creation_time - 00000007 1b pk_algo - 00000008 00 00 00 20 public_len - 0000000c 53 24 e9 43 ed25519_public - 00000010 af ab 15 f7 6e d5 b5 12 98 79 69 cd 1b 5d 10 65 - 00000020 eb e7 42 e2 ab 47 f4 86 b3 ae 65 3e - 0000002c 00 s2k_usage - 0000002d ef e1 99 ed25519_secret - 00000030 b5 5f 11 fb aa 93 e8 26 9d 3b b2 2d 72 20 7d ff - 00000040 bd 42 dd 4b e9 a3 36 81 3b a5 cc cf fb - -Signature Packet, new CTB, 2 header bytes + 182 bytes - Version: 6 - Type: DirectKey - Pk algo: Ed25519 - Hash algo: SHA512 - Hashed area: - Signature creation time: 2023-09-29 15:17:58 UTC (critical) - Key expiration time: P1095DT62781S (critical) - Symmetric algo preferences: AES256, AES128 - Hash preferences: SHA512, SHA256 - Key flags: C (critical) - Features: MDC - Issuer Fingerprint: AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3 - Unhashed area: - Issuer: AAA18CBB254685C5 - Digest prefix: 6747 - Level: 0 (signature over data) - - 00000000 c2 CTB - 00000001 b6 length - 00000002 06 version - 00000003 1f type - 00000004 1b pk_algo - 00000005 0a hash_algo - 00000006 00 00 00 3d hashed_area_len - 0000000a 05 subpacket length - 0000000b 82 subpacket tag - 0000000c 65 16 ea a6 sig creation time - 00000010 05 subpacket length - 00000011 89 subpacket tag - 00000012 05 a4 8f bd key expiry time - 00000016 03 subpacket length - 00000017 0b subpacket tag - 00000018 09 07 pref sym algos - 0000001a 03 subpacket length - 0000001b 15 subpacket tag - 0000001c 0a 08 pref hash algos - 0000001e 02 subpacket length - 0000001f 9b subpacket tag - 00000020 01 key flags - 00000021 02 subpacket length - 00000022 1e subpacket tag - 00000023 01 features - 00000024 22 subpacket length - 00000025 21 subpacket tag - 00000026 06 version - 00000027 aa a1 8c bb 25 46 85 c5 83 issuer fp - 00000030 58 32 05 63 fd 37 b6 7f 33 00 f9 fb 0e c4 57 37 - 00000040 8c d2 9f 10 26 98 b3 - 00000047 00 00 00 0a unhashed_area_len - 0000004b 09 subpacket length - 0000004c 10 subpacket tag - 0000004d aa a1 8c issuer - 00000050 bb 25 46 85 c5 - 00000055 67 digest_prefix1 - 00000056 47 digest_prefix2 - 00000057 20 salt_len - 00000058 a2 e3 63 81 e3 6b d0 4f salt - 00000060 56 d7 c8 38 80 02 25 e8 53 39 49 6b 90 c6 0d 76 - 00000070 8f 44 b4 ec 4c 42 38 8e - 00000078 4d 3d 10 c2 ad 29 c0 57 ed25519_sig - 00000080 ce 66 01 73 b3 78 81 9e 89 52 cf 43 8d 28 11 a9 - 00000090 77 09 7f cb f8 15 c8 a1 8d ac 20 44 2b 2d de 13 - 000000a0 00 41 32 d0 10 3c 69 06 53 3c 49 8c 76 23 82 33 - 000000b0 54 01 f9 5f 81 41 90 0e - +$ sq packet dump --hex alice.priv-2--UserID User ID Packet, new CTB, 2 header bytes + 19 bytes Value: @@ -1080,7 +975,22 @@ User ID Packet, new CTB, 2 header bytes + 19 bytes 00000001 13 length 00000002 3c 61 6c 69 63 65 40 65 78 61 6d 70 6c 65 value 00000010 2e 6f 72 67 3e +``` +- `CTB: 0xcd`: The Packet Tag for this packet. Bits 7 and 6 show that the packet is in “OpenPGP packet format” (as opposed to in “Legacy packet format”). The remaining 6 bits encode the Tag’s value: “13.” This is the value for a [User ID packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-id-packet-tag-13). +- `length: 0x13`: The remaining length of this packet (here: 19 bytes). +- `value`: 19 bytes of data that contain UTF-8 encoded text. The value corresponds to the string ``. With this identity component, Alice states that she uses (and has control of) this email address. Note that the email address is enclosed in `<` and `>` characters, following [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822) conventions. + +So, a User ID packet is really just a string, marked as a User ID by the packet type id. + +#### Linking the User ID with a certification self-signature + +As above, when [linking a subkey](zoom_enc_subkey) to the OpenPGP certificate, a self-signature is used to connect this new component to the certificate. + +To bind identities to a certificate with a self-signature, one of the signature types `0x10` - `0x13` can be used. Here, the signature type `0x13` (*positive certification*) is used. + +```text +$ sq packet dump --hex alice.priv-3--Signature Signature Packet, new CTB, 2 header bytes + 185 bytes Version: 6 Type: PositiveCertification @@ -1151,13 +1061,52 @@ Signature Packet, new CTB, 2 header bytes + 185 bytes 000000b0 54 bf 43 19 04 ff 53 98 c0 d5 0b ``` -Instead of two packets, as before, we see four packets 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://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#uid), which contains the name and email address we used -* Finally, a [*"Positive Certification Signature"*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (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) +We'll go over this packet dump in less detail, since its structure closely mirrors the [Direct Key Signature](zooming_in_dks) discussed above. +We're again looking at a Signature packet. Its `type` is `0x13` ([corresponding](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-types) to a *positive certification* signature). + +The public key algorithm and hash function used for this signature are Ed25519 and SHA512. + +As shown in the text at the top of this packet dump, the hashed subpacket data contains the following metadata: + +- Signature creation time: `2023-09-29 15:17:58 UTC` (**critical**) +- Key expiration time: `P1095DT62781S` (**critical**) +- Symmetric algo preferences: `AES256, AES128` +- Hash preferences: `SHA512, SHA256` +- Primary User ID: `true` (**critical**) +- Key flags: `C` (**critical**) +- Features: `MDC` +- Issuer Fingerprint: `AAA18CBB254685C58358320563FD37B67F3300F9FB0EC457378CD29F102698B3` + +This is a combination of metadata about the User ID itself (including defining this User ID as the *primary User ID* of this certificate), algorithm preferences that are associated with this identity, and settings that apply to the primary key. + +````{note} +For historical reasons, the self-signature that binds the primary User ID to the certificate also contains subpackets that apply not to the User ID, but to the primary key itself. + +Setting key expiration time and key flags on the primary User ID self-signature is one mechanism to configure the primary key. + +The interaction between metadata on direct key signatures and User ID binding self-signatures [is subtle](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-notes-on-self-signatures), and there are changes between version 6 and version 4. + + +```{admonition} TODO +:class: warning + +- link to a section that goes into more depth about "#name-notes-on-self-signatures"? +``` + +```` + +Followed, again, by the (informational) unhashed subpacket area. + +And finally, a salt value for the signature and the signature itself. + +The signature is calculated over a hash. The hash, in this case, is calculated over the following data (for details, see [Computing Signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-computing-signatures) in the RFC): + +- The signature's salt +- A serialized form of the primary key's public data +- A serialized form of the User ID +- A serialized form of this self-signature packet (up to, but excluding the unhashed area) ### Certifications (Third Party Signatures)