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

ch4 "zooming in": fix capitalizations/styling

Browse source 
- Don't use quotation marks for RFC terms. Use italics, when appropriate.
- The word "packet" isn't capitalized when referring to a specific packet.
This commit is contained in:
Heiko Schaefer 2023-10-06 20:39:54 +02:00
parent c592c6c02d
commit ac070e5229
No known key found for this signature in database
GPG key ID: 4A849A1904CCBD7D
1 changed files with 32 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
book/source/04-certificates.md
View file

@ -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. 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. 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: 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 - 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). - 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). 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 #### 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 ```text
Secret-Key Packet, new CTB, 2 header bytes + 75 bytes 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 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. - `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 - `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) - `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 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`) - `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} ```{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. 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 #### 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 ```text
Signature Packet, new CTB, 2 header bytes + 182 bytes 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: 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. - `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). - `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) - `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)) - `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 - `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]. 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` - [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` - [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 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") - [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") - [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": 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.
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. This concludes the unhashed subpacket data.
@ -557,7 +557,7 @@ gAIl6FM5SWuQxg12j0S07ExCOI5NPRDCrSnAV85mAXOzeIGeiVLPQ40oEal3CX/L
$ sq packet dump --hex alice_minimal.pub $ 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 ```text
Public-Key Packet, new CTB, 2 header bytes + 42 bytes 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 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. 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.** **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 ### User IDs