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

Adjust

Browse source 
to updated RFC terminology

Fixes #52
This commit is contained in:
Tammi L. Coles 2023-10-07 13:29:31 +02:00 committed by Heiko Schaefer
parent 32c9d36c19
commit f0959a2b0f
No known key found for this signature in database
GPG key ID: 4A849A1904CCBD7D
1 changed files with 13 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -454,17 +454,17 @@ Secret-Key Packet, new CTB, 2 header bytes + 75 bytes
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 type ID](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 type IDs](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 type id 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
This means that the next part of the packet follows the structure of [Version 6 Public Keys](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-version-6-public-keys) This means that the next part of the packet follows the structure of [Version 6 Public Keys](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-version-6-public-keys)
- `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)) - `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)) - `pk_algo: 0x1b`: "The public-key algorithm ID 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) - `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 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
@ -473,7 +473,7 @@ This concludes the Public Key section of the packet. The remaining data follows
- `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 type ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-packet-headers). Previously, the RFC called this field "Packet Tag".
```{tip} ```{tip}
@ -559,22 +559,22 @@ Signature Packet, new CTB, 2 header bytes + 182 bytes
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 type ID 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 type ID’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 type ID 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)
- `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 ID (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)) - `hash_algo: 0x0a`: Hash algorithm ID (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). The following subpacket data consists of sets of "subpacket length, subpacket type ID, 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 type ID). Note that bit 7 of the subpacket type ID 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).
```{note} ```{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. 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.
@ -592,7 +592,7 @@ The next part of this packet contains "unhashed subpacket data":
- `unhashed_area_len: 0x0000000a`: Length of the following unhashed subpacket data (value: 10 bytes). - `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: As above, the following subpacket data consists of sets of "subpacket length, subpacket type id, 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)
@ -654,7 +654,7 @@ Public-Key Packet, new CTB, 2 header bytes + 42 bytes
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) 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 packet type ID (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 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. 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.
@ -723,7 +723,7 @@ Secret-Subkey Packet, new CTB, 2 header bytes + 75 bytes
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: 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 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 packet type ID (`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). - 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.) - 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.)
@ -977,7 +977,7 @@ User ID Packet, new CTB, 2 header bytes + 19 bytes
00000010 2e 6f 72 67 3e 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). - `CTB: 0xcd`: The Packet type ID 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 type ID’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). - `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 `<alice@example.org>`. 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. - `value`: 19 bytes of data that contain UTF-8 encoded text. The value corresponds to the string `<alice@example.org>`. 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.