From bf41637c05cf520c2af4fc86e822f161efff253e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 6 Nov 2023 23:22:03 +0100 Subject: [PATCH 01/41] Restructure opening --- book/source/08-signing_components.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 526be8b..885295b 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -6,22 +6,28 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (component_signatures_chapter)= # Signatures on components -In this chapter, we'll consider OpenPGP signatures that apply to components. That is, signatures that apply to: +In this chapter, we'll look into OpenPGP signatures that apply to components of certificates. That is, signatures that apply to: -- Component keys (primary keys or subkeys), or +- Component keys (primary keys or subkeys) and - Identity components (User IDs or User attributes). -This chapter adds a lot of detail to the material we discussed in the {ref}`certificates_chapter` chapter. Signatures on components are a crucial mechanism for forming OpenPGP certificates (which combine component keys and identities, via signatures on those components). +This chapter adds detail to material we discussed in the {ref}`certificates_chapter` chapter. Signatures on components are a crucial mechanism for forming OpenPGP certificates and . -Additionally, signatures on components play a crucial role for authentication of identities. Mechanisms for decentralized authentication are one of OpenPGP's core strengths, we'll look into how they work. +## Self-signatures: Forming certificates and life-cycle management -Finally, signatures on components are also a central mechanism for life-cycle management of OpenPGP certificates and their components. This includes defining or changing expiration dates, or issuing revocations, for certificates or their components. +*Self-signatures* are issued by the certificate's owner, using the primary key of the same certificate. + +Signatures on components are also a central mechanism for life-cycle management of OpenPGP certificates and their components. This includes defining or changing expiration dates, or issuing revocations, for certificates or their components. + +## Third-party certifications: Encoding authentication + +Additionally, signatures on components play a crucial role in the authentication of identities. Mechanisms for decentralized authentication are one of OpenPGP's core strengths, we'll look into how they work. ## Self-signatures and third-party signatures There are two important scenarios to distinguish: -- *Self-signatures*: Issued by the certificate's owner, using the primary key of the same certificate. + - *Third-party signatures*: Issued by a key that is part of a different certificate. ### Meaning differs between self- and third-party signatures From 0039afd7fd6e1652a9b18e6ca6e3a8dbad864487 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 7 Nov 2023 19:09:39 +0100 Subject: [PATCH 02/41] edits --- book/source/08-signing_components.md | 47 +++++++++++++--------------- 1 file changed, 21 insertions(+), 26 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 885295b..73f07b7 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -11,7 +11,9 @@ In this chapter, we'll look into OpenPGP signatures that apply to components of - Component keys (primary keys or subkeys) and - Identity components (User IDs or User attributes). -This chapter adds detail to material we discussed in the {ref}`certificates_chapter` chapter. Signatures on components are a crucial mechanism for forming OpenPGP certificates and . +This chapter adds detail to material we discussed in the {ref}`certificates_chapter` chapter. Signatures on components are a crucial mechanism for forming OpenPGP certificates, as well as for life-cycle management of certificates. + +Separately, signatures on components serve as a central building block for OpenPGP's decentralized authentication functionality. ## Self-signatures: Forming certificates and life-cycle management @@ -19,20 +21,19 @@ This chapter adds detail to material we discussed in the {ref}`certificates_chap Signatures on components are also a central mechanism for life-cycle management of OpenPGP certificates and their components. This includes defining or changing expiration dates, or issuing revocations, for certificates or their components. +```{note} +The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is not required in order to issue certifying self-signatures. This key flag is only necessary to issue valid third-party certifications. +``` + ## Third-party certifications: Encoding authentication -Additionally, signatures on components play a crucial role in the authentication of identities. Mechanisms for decentralized authentication are one of OpenPGP's core strengths, we'll look into how they work. +Mechanisms for decentralized authentication of identities are one of OpenPGP’s core strengths: Signatures on components by third parties can be used for the authentication of identities. -## Self-signatures and third-party signatures +Using OpenPGP signatures, identity claims can be certified by third parties. Similarly, authentication decisions can be delegated using signatures. -There are two important scenarios to distinguish: +## Meaning differs between self- and third-party signatures - -- *Third-party signatures*: Issued by a key that is part of a different certificate. - -### Meaning differs between self- and third-party signatures - -The meaning of a signature depends in part on who issued it. A self-signature often has a different meaning from a signature issued by a third party. +The meaning of a signature depends in part on who issued it. A self-signature performs a different function than the same type of signature issued by a third party. For example: @@ -44,13 +45,11 @@ Or: - Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a certificate, while - the same signature type IDs issued by a third party are statements by the signer that they endorse the authenticity of the signed User ID to some degree. -There are further signature types for signatures on data, as well as designated types to bind and revoke subkeys. - ## Signatures on components -A typical use-case for a self-signature is to attach a User ID, such as a name and email address to a certificate. -This is done by calculating the signature over the User ID and the public primary key. -The resulting User ID certification (typically type 0x13, potentially type 0x10-0x12) can then be inserted into the certificate, right after the User ID packet. +A typical use-case for a self-signature is to link a User ID, such as a name and email address to a certificate. +This is done by calculating a signature over the User ID and the public primary key. +The resulting certification (typically signature type 0x13, potentially type 0x10-0x12) is then stored as part of the certificate, right after the User ID packet. Other examples for self-signatures are binding signatures for subkeys. To add an OpenPGP subkey to a certificate, a subkey binding signature is calculated over the public primary key, followed by the public subkey. The resulting subkey binding signature (type 0x18) can then be inserted into the certificate right after the subkey. @@ -62,11 +61,6 @@ If Alice is certain that `Bob Baker ` controls the key `0xB0B`, Bob can then add this signature to his certificate. TODO: More WoT. -```{note} -The **certify others** key flag is not required in order to issue certifying self-signatures. -This key flag is only necessary to issue valid third-party certifications. -``` - ### Revocations One important class of self-signatures are revocations. @@ -85,13 +79,15 @@ 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 components](identity_components)) 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 [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 components](identity_components) in an OpenPGP certificate dataset, OpenPGP implementations that read this certificate 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.) +```{note} +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. +``` Note, though, that there are some cases where third parties legitimately add "unbound" packets to certificates (that is: packets that are not signed by the certificate's owner): @@ -262,8 +258,7 @@ It is recommended to issue User ID certifications using a reason code `32` and t (binding_subkeys)= #### Add a Subkey -For the purpose of key freshness, a user might want to add a new subkey to their certificate. - +A user might want to add a new subkey to their certificate, for example to replace an old subkey with one that uses a newer cryptographic algorithm. The structure is as follows: @@ -331,11 +326,11 @@ Since the issuer fingerprint subpacket is self-authenticating, it can either be Since the hashed and unhashed areas of a signature are just lists of subpackets, in principle they allow duplicates of the same subpacket, which might lead to conflicts. Therefore, packets in the hashed area take precedence over the unhashed area. However, there may still be conflicts between packets in the same area, e.g., two conflicting expiration dates, etc. -The [specification recommends](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-subpackets) that implementations favor the last occurrence of a conflicting packet in the hashed area. +The [specification recommends](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-subpackets) that implementations favor the last occurrence of a conflicting packet in the hashed area (that is, the last entry for that subpacket type in the sequence of subpackets in the hashed area). In some cases, duplicate packets with conflicting content even make sense, e.g., if a signature was made by a version 4 issuer key whose key material was migrated from an older OpenPGP version such as v3. In this case, either the v3 or v4 key could be used to validate the v4 signature, but since the key ID calculation scheme was changed between v3 and v4, these identifiers would differ. -Therefore, the signature could contain two isuer key ID subpackets with conflicting, but correct values. +Therefore, the signature could contain two issuer key ID subpackets with conflicting, but correct values. ```{admonition} TODO :class: warning From b73789d1c8e4c831841196c69287a83478f25f54 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 7 Nov 2023 20:59:53 +0100 Subject: [PATCH 03/41] adjust structure --- book/source/08-signing_components.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 73f07b7..d3b0746 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -15,7 +15,9 @@ This chapter adds detail to material we discussed in the {ref}`certificates_chap Separately, signatures on components serve as a central building block for OpenPGP's decentralized authentication functionality. -## Self-signatures: Forming certificates and life-cycle management +## Who signs? + +### Self-signatures: Forming certificates and life-cycle management *Self-signatures* are issued by the certificate's owner, using the primary key of the same certificate. @@ -25,13 +27,13 @@ Signatures on components are also a central mechanism for life-cycle management The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is not required in order to issue certifying self-signatures. This key flag is only necessary to issue valid third-party certifications. ``` -## Third-party certifications: Encoding authentication +### Third-party certifications: Encoding authentication Mechanisms for decentralized authentication of identities are one of OpenPGP’s core strengths: Signatures on components by third parties can be used for the authentication of identities. Using OpenPGP signatures, identity claims can be certified by third parties. Similarly, authentication decisions can be delegated using signatures. -## Meaning differs between self- and third-party signatures +### Meaning differs between self- and third-party signatures The meaning of a signature depends in part on who issued it. A self-signature performs a different function than the same type of signature issued by a third party. From 1335d5568fa1ace6b4e22cc5b469b7a74dcbf51e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 7 Nov 2023 21:13:34 +0100 Subject: [PATCH 04/41] edits --- book/source/08-signing_components.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index d3b0746..298844e 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -73,6 +73,12 @@ Typical use-cases for revocations are marking certificates or individual subkeys A revocation signature can either be hard or soft. A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material. +```{note} +OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures. + +Revocations are used as a mechanism to mark components or signatures as invalid. +``` + ## Self-signatures: Linking the components of a certificate So far we've looked at the components in an OpenPGP certificate, but certificates actually contain another set of elements, which bind the components together, and add metadata to them. @@ -113,9 +119,15 @@ Linking an OpenPGP subkey to the primary key with a binding signature The [Signature packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-packet-tag-2) that binds the subkey to the primary key has the signature type [SubkeyBinding](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-subkey-binding-signature-si). -In order to specify an expiration time for the subkey, a key expiration time subpacket can be included. Note, that the validity of the subkey is bounded by that of the primary key, meaning an expired primary key causes the subkey to be invalidated, no matter the subkey expiration time. +In order to specify an expiration time for the subkey, a key expiration time subpacket can be included. -Note, that a subkey cannot be "older" than the primary key. The value of the subkeys creation date MUST be greater than that of the primary key. +```{note} +The validity of a subkey is bounded by that of the primary key, meaning an expired primary key causes the subkey to be invalidated, no matter the subkey expiration time. + +It's legal for a subkey to not have an explicit expiry time. In that case, its expiration date is implicitly the same as the expiration date of the primary key. + +A subkey cannot be "older" than the primary key. The value of the subkeys creation date MUST be greater than that of the primary key. +``` ### Special case: Binding signing subkeys to a certificate @@ -181,7 +193,9 @@ A soft revocation invalidates the target certificate beginning with the revocati Contrary, a hard revocation cannot be re-validated. Furthermore, a hard-revoked certificate is invalidated retroactively. +```{note} A missing revocation reason subpacket is equivalent with a hard revocation reason. +``` (third_party_cert)= ## Third-party certifications: Making statements about other people's certificates and identities @@ -290,12 +304,12 @@ The structure of such a signature is rather minimal: | Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | | Reason for Revocation | Hashed | True | False | Decides over soft / hard revocation | -In `SubkeyRevocation` signatures, the reason subpacket cannot have value `32`, but instead may be from the range of `0-3`. +In `SubkeyRevocation` signatures, the [reason subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) cannot have value `32`, but instead may be from the range of `0-3`. Values `1` (key superseded) and `3` (key retired and no longer used) are soft reasons, while `0` (no reason) and `2` (key compromised) are considered hard. #### Revoke a Certificate -A user might want to revoke their whole certificate, rendering it unusable. +A user might want to revoke their entire certificate, rendering it unusable. Depending on the circumstances, they might either want to revoke it softly, e.g. in case of migration to a new certificate, or they want to issue a hard revocation, e.g. in case of secret key material compromise. A soft-revoked certificate can be re-validated at a later point in time, by issuing a new certification, while a hard revocation is typically permanent. The recommended way to revoke a certificate is by issuing a `KeyRevocation` signature (type 0x20). @@ -307,11 +321,11 @@ The structure of a key revocation signature is similar to that of a `Certificati | Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | | Reason for Revocation | Hashed | True | False | Decides over soft / hard revocation | -For `KeyRevocation` signatures, the same constraints as for `SubkeyRevocation` signatures apply to the reason subpacket. +For `KeyRevocation` signatures, the same constraints as for `SubkeyRevocation` signatures apply to the [reason subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation). #### Common Subpackets -There are some subpackets that are expected to be included in any type of signature. +There are some subpackets that are expected to be included in all types of signatures. * **Signature Creation Time**: Every OpenPGP signature MUST contain a Signature Creation Time subpacket (2) containing the timestamp at which the signature was made. This packet MUST be present in the hashed area of the signature and SHOULD be marked as critical. From 420e15e8c8965261d28d15bdaab9069a3b270170 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 7 Nov 2023 21:35:09 +0100 Subject: [PATCH 05/41] remove seemingly stray text --- book/source/08-signing_components.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 298844e..3963f83 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -269,7 +269,7 @@ The structure of a certification revocation is as follows: For User ID revocations, the value of the reason subpacket can either be `0` (no reason specified) or `32`, signaling that the User ID is no longer valid. The latter would result in a soft revocation, while a reason code of `0` is considered a hard revocation. Omitting the reason packet altogether is also equivalent to a hard revocation. -It is recommended to issue User ID certifications using a reason code `32` and to do certificate revocations using a direct-key signature. +It is recommended to issue User ID revocations using a reason code `32`. (binding_subkeys)= #### Add a Subkey @@ -310,6 +310,7 @@ Values `1` (key superseded) and `3` (key retired and no longer used) are soft re #### Revoke a Certificate A user might want to revoke their entire certificate, rendering it unusable. + Depending on the circumstances, they might either want to revoke it softly, e.g. in case of migration to a new certificate, or they want to issue a hard revocation, e.g. in case of secret key material compromise. A soft-revoked certificate can be re-validated at a later point in time, by issuing a new certification, while a hard revocation is typically permanent. The recommended way to revoke a certificate is by issuing a `KeyRevocation` signature (type 0x20). From 7f9aba28fa602f86bffa165b45047d0ee6d93bd6 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 9 Nov 2023 01:43:56 +0100 Subject: [PATCH 06/41] restructure text blocks --- book/source/08-signing_components.md | 91 +++++++++++++--------------- 1 file changed, 43 insertions(+), 48 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 3963f83..3580ba5 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -11,11 +11,13 @@ In this chapter, we'll look into OpenPGP signatures that apply to components of - Component keys (primary keys or subkeys) and - Identity components (User IDs or User attributes). -This chapter adds detail to material we discussed in the {ref}`certificates_chapter` chapter. Signatures on components are a crucial mechanism for forming OpenPGP certificates, as well as for life-cycle management of certificates. +This chapter adds detail to material we discussed in the {ref}`certificates_chapter` chapter. -Separately, signatures on components serve as a central building block for OpenPGP's decentralized authentication functionality. +## Two flavors of signatures on components: first party vs third party -## Who signs? +Signatures on components are a crucial mechanism for forming OpenPGP certificates, as well as for life-cycle management of certificates, when issued by the certificate holder. + +Separately, signatures on components can serve as a building block for OpenPGP's decentralized authentication functionality. Signatures for this functionality are issued by third parties. ### Self-signatures: Forming certificates and life-cycle management @@ -47,38 +49,6 @@ Or: - Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a certificate, while - the same signature type IDs issued by a third party are statements by the signer that they endorse the authenticity of the signed User ID to some degree. -## Signatures on components - -A typical use-case for a self-signature is to link a User ID, such as a name and email address to a certificate. -This is done by calculating a signature over the User ID and the public primary key. -The resulting certification (typically signature type 0x13, potentially type 0x10-0x12) is then stored as part of the certificate, right after the User ID packet. - -Other examples for self-signatures are binding signatures for subkeys. To add an OpenPGP subkey to a certificate, a subkey binding signature is calculated over the public primary key, followed by the public subkey. -The resulting subkey binding signature (type 0x18) can then be inserted into the certificate right after the subkey. -If the subkey itself is intended to be used as a **S**igning key, an extra step is required. -To prevent an attacker from being able to "adopt" a victims signing subkey and then being able to claim to be the origin of signatures in fact made by victim, subkey binding signatures for signing subkeys need to include an embedded "back signature" (formally known as [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding)) made by the signing key itself. - -Certifications over User IDs can also be used to certify certificates of third-parties. -If Alice is certain that `Bob Baker ` controls the key `0xB0B`, she can create a User ID certification signature for that identity and send it to Bob. -Bob can then add this signature to his certificate. -TODO: More WoT. - -### Revocations - -One important class of self-signatures are revocations. - -A revocation signature is used to retract the statement formed by a prior signature. -A subkey revocation signature revokes a prior subkey binding signature, while a certification revocation revokes a certification signature. -Typical use-cases for revocations are marking certificates or individual subkeys as unusable (for example, when the private key has been compromised or superseded), or marking User IDs as no longer used. - -A revocation signature can either be hard or soft. A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material. - -```{note} -OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures. - -Revocations are used as a mechanism to mark components or signatures as invalid. -``` - ## Self-signatures: Linking the components of a certificate So far we've looked at the components in an OpenPGP certificate, but certificates actually contain another set of elements, which bind the components together, and add metadata to them. @@ -107,19 +77,18 @@ Note, though, that there are some cases where third parties legitimately add "un (bind_subkey)= ### Binding subkeys to a 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". +A subkey is linked to an OpenPGP certificate using a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID 0x18). This signature type effectively signals that the "primary key wants to be associated with the subkey". -The subkey binding signature also adds metadata. +A subkey binding signature binds the public primary key and the public subkey, and additionally metadata in the signature packet. Once generated, the subkey binding signature packet is stored in the certificate right after the subkey. + +(Note that subkeys that have the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) are a special case, see {numref}`bind_subkey_sign`.) ```{figure} diag/subkey_binding_signature.png Linking an OpenPGP subkey to the primary key with a binding signature ``` -The [Signature packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-packet-tag-2) that binds the subkey to the primary key has the signature type [SubkeyBinding](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-subkey-binding-signature-si). - - -In order to specify an expiration time for the subkey, a key expiration time subpacket can be included. +In order to specify an expiration time for the subkey, a key expiration time subpacket can be included in the subkey binding signature packet. ```{note} The validity of a subkey is bounded by that of the primary key, meaning an expired primary key causes the subkey to be invalidated, no matter the subkey expiration time. @@ -129,15 +98,16 @@ It's legal for a subkey to not have an explicit expiry time. In that case, its e A subkey cannot be "older" than the primary key. The value of the subkeys creation date MUST be greater than that of the primary key. ``` +(bind_subkey_sign)= ### Special case: Binding signing subkeys to a certificate -Binding subkeys with the "signing" key flag is a special case. For the most part, it works the same as binding other types of subkeys, but there is an additional requirement: +To bind subkeys with the "signing" key flag to a certificate is a special case. For the most part, it works the same as binding other types of subkeys, but there is an additional requirement: When binding a signing subkey to a primary key, it is not sufficient that the "primary key wants to be associated with the subkey." In addition, the subkey must signal that it "wants to be associated with that primary key." Otherwise, Alice could "adopt" Bob's signing subkey and convincingly claim that she made signatures that were in fact issued by Bob. This is to prevent an attack where the attacker "adopts" the victims signing subkey as their own in order to claim ownership over documents which were in fact signed by the victim. -Contrary to the `SubkeyBinding` signature, which is issued by the certificate's primary key, the `PrimaryKeyBinding` signature is instead created by the subkey. +In contrast to the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID 0x18), which is issued by the certificate's primary key, the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID 0x19) is instead created by the subkey (informally also called an embedded "back signature"). ```{figure} diag/subkey_binding_signatur_for_signing_sk.png @@ -150,11 +120,15 @@ The *primary key binding signature* is "embedded" as subpacket data in the *subk ### Binding identities to a certificate -"User ID" identity components are bound to an OpenPGP certificate by issuing a self-signature ("User Attributes" work analogously). +Another use-case for a self-signature is to link an identity component (such as a User ID that specifies a name and email address) to a certificate. + +User ID components are bound to an OpenPGP certificate by issuing a self-signature ("User Attributes" work analogously). For example, the User ID `Alice Adams ` may be associated with Alice's certificate `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. -Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a self-signature is created (usually with the signature type [PositiveCertification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert)). This signature is issued by the primary key. +Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a "certifying self-signature" is created (usually with the signature type [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID 0x13, or sometimes with type ID 0x10, 0x11 or 0x12)). This signature is issued by the primary key. + +The resulting certification is stored as part of the certificate, right after the User ID packet. ```{figure} diag/user_id_certification.png --- @@ -176,10 +150,18 @@ explain metadata associated with this signature, and that c-r prefers this over ### Revocations: Invalidating components of a certificate -```{admonition} TODO -:class: warning +One important class of self-signatures are revocations. -This section only contains notes and still needs to be written +A revocation signature is used to retract the statement formed by a prior signature. +A subkey revocation signature revokes a prior subkey binding signature, while a certification revocation revokes a certification signature. +Typical use-cases for revocations are marking certificates or individual subkeys as unusable (for example, when the private key has been compromised or superseded), or marking User IDs as no longer used. + +A revocation signature can either be hard or soft. A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material. + +```{note} +OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures. + +Revocations are used as a mechanism to mark components or signatures as invalid. ``` Note: certification signatures [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-revocable). @@ -206,6 +188,19 @@ A missing revocation reason subpacket is equivalent with a hard revocation reaso write ``` +### Certifying identities + +Certifications over User IDs can also be used to certify certificates of third-parties. +If Alice is certain that `Bob Baker ` controls the key `0xB0B`, she can create a User ID certification signature for that identity and send it to Bob. +Bob can then add this signature to his certificate. + +TODO: More WoT. + +### Delegating authentication: trust signatures + +### Revocations: Undoing previous statements + + ## Advanced topics ### Certification Recipes From 2445b2f41420453d37a7205f33b7f99e38a6b773 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 10 Nov 2023 01:59:20 +0100 Subject: [PATCH 07/41] ch7: edits for clarity --- book/source/07-signing_data.md | 109 ++++++++++++++++++++++----------- 1 file changed, 73 insertions(+), 36 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 1741fb2..7331a3a 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -6,71 +6,88 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (signing_data)= # Signatures over data -A data signature guarantees the authenticity (and implicitly also the integrity) of a message, e.g., an email or a file. +A *data signature* guarantees the authenticity (and implicitly also the integrity) of some data. Typical use cases for data signatures in OpenPGP are signatures for software packages or emails. -More specifically, when we say "authenticity", we mean that the signature guarantees that whoever controls the signing key material has issued that signature. The question of who controls that key material is a separate concern. We might independently want to verify that our intended communication partner uses the cryptographic identity in question. +When we say "authenticity," here, we mean that the signature guarantees that whoever controls the signing key material has issued the signature. -Note that signatures over data are different from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate. +It is a separate question if the party we expect indeed controls the signer certificate. OpenPGP does offer mechanisms for *strong authentication* of the connection between certificates and identities. So, if necessary, we can also verify that our intended communication partner really uses the cryptographic identity that issued the signature[^sign-auth]. -Typical use cases for signatures over data in OpenPGP are signatures for software packages or emails. +[^sign-auth]: Other signing solutions, such as [signify](https://flak.tedunangst.com/post/signify), typically only offer a solution for pure signing, without offering a mechanism for strong authentication of the identity of the signer. -When signing data, OpenPGP offers mechanisms for strong authentication, based on bindings between certificates and identities, and the option to verify those bindings. +Data signatures can only be issued by component keys that carry the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags). -Other signing solutions, such as [signify](https://flak.tedunangst.com/post/signify), typically only offer a solution for pure signing, without offering -a mechanism for authentication. +Note that signatures over data are distinct from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate. ## Signature types -Two OpenPGP [signature types](signature_types) apply to data signatures: +Data signatures use one of two OpenPGP [signature types](signature_types): -- Signature of a binary document (*Binary Signature*, type ID `0x00`): a universal signature type for binary data. This signature type is typically used for files or data streams. +- "Signature of a binary document" (*Binary Signature*, type ID `0x00`): A universal signature type for binary data. Binary signatures are typically used for files or data streams. Binary signatures are calculated over the data "as is", without performing any transformations. -- Signature of a canonical text document (*Text Signature*, type ID `0x01`): used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). This normalization mitigates issues caused by platform-specific default text encodings. - (This can be useful for detached signatures, when the message file may get re-encoded between signature generation and validation) +- "Signature of a canonical text document" (*Text Signature*, type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). The normalization mitigates issues caused by platform-specific text encodings, for example with detached signatures, where the message file may get re-encoded between signature generation and validation. -Data signatures are always calculated by a component key that carries the *signing* key flag. +Data signatures are generated by hashing the message content, plus the metadata in the signature packet, and calculating a cryptographic signature over that hash. The resulting cryptographic signature is stored in an OpenPGP signature packet. -Data signatures are created by hashing the message content and calculating a cryptographic signature over the hash. -The resulting cryptographic signature is stored in an OpenPGP signature packet, which can be used in different ways. We'll discuss these in the following sections. +Data signature packets can be used in three different forms. We'll discuss these in the following section. ## Forms of OpenPGP data signatures -OpenPGP signatures over data can be generated and distributed in three forms[^sign-modes-gpg]: +OpenPGP signatures over data can be used in three different forms[^sign-modes-gpg]: - *Detached*: The signature is a standalone artifact, separate from the signed data. -- *Inline*: The original data and the signature over the data are stored in an OpenPGP container. -- *Cleartext signature*: A method to sign text while leaving the original message in a human-readable format. +- *Inline*: The original data and the signature over the data are collectively stored in an OpenPGP container. +- *Cleartext signature*: A message in text format and a signature over this message are stored in a combined text-format, which leaves the original message in a human-readable representation. -[^sign-modes-gpg]: These signature forms correspond with GnuPG's `--detach-sign`, `--sign` and `--clear-sign` modes. +[^sign-modes-gpg]: These three signature forms correspond with GnuPG's `--detach-sign`, `--sign` and `--clear-sign` modes. ### Detached signatures -This method is especially useful for signing software releases and other files that must not be modified by the signing process. +A detached signature is produced by calculating an OpenPGP signature over the signed data. The original data is left as is, while the OpenPGP signature is stored as a standalone file. A detached signature can be distributed alongside or independent of the original data. The authenticity and integrity of the original data file can be verified using the detached signature file. -A detached signature is produced by calculating an OpenPGP signature over a piece of data. -The resulting OpenPGP signature packet can then be distributed alongside or independent of the original data. +This signature format is especially useful for signing software releases and other files that must not be modified by the signing process. ### Inline signatures -This method is usually used with signed and/or encrypted emails. +An inline signature joins the signed data and a signature over this data into one combined OpenPGP message. -Most clients that support OpenPGP for encrypted and/or signed messages make use of inline-signatures. -To produce a signature, the entirety of the data needs to be processed by the producer. This has the consequence that an application that efficiently emits signed data can only append the signature at the end of the data stream. -On the other hand, an application that needs to efficiently verify signed data needs to know the signer's public key and used hash algorithm before processing the data. -To solve this issue, so-called One-Pass Signature packets are prefixed to the signed data. Those are small packets containing the fingerprint of the signing key, as well as the used hash algorithm. This is all the information a receiving application needs to know to initiate the verification process. +This method is usually used with signed and/or encrypted emails. Most software that supports OpenPGP for encrypted and/or signed messages uses inline-signatures. -To produce an inline-signed message, the original data is first wrapped in a [Literal Data packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit), which is prefixed with one or more [One-Pass Signature packets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig), and affixed with the corresponding signature packets. -The verifying application can read the One-Pass Signature packets and initiate the verification process. -The literal data can then be processed, such that the signatures at the end of the message can be verified in *one pass*. +#### Structure -TODO: explain nesting of OPSs. +An inline-signed OpenPGP message consists of three segments: + +- One or more [One-Pass Signature packets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig), +- the original data, wrapped in a [Literal Data packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit), +- the corresponding Data Signature packets. + +#### Creation + +To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into am output OpenPGP message file. The signer calculates a cryptographic signature over the course of this process. Therefore, an efficient signer can only emit the resulting data signature packet at the end of this process, and thus store it at the end of the data stream. + +On the other hand, an efficient verifying application needs to know how to process the literal data before reading it. This is the purpose of the so-called One-Pass Signature packets in the first segment of inline-signed messages. One-Pass Signature packets contain the fingerprint of the signing key, as well as the hash algorithm used to calculate the hash digest for the signature. + +```{admonition} TODO +:class: warning + +Is the signer keyid/fingerprint in the OPS important for the verifier to be able to verify the signature efficiently? Or is it (only?) there to be hashed and signed, along with the literal data? +``` + +#### Verification + +This structure allows verifying applications to verify inline-signed messages in *one pass*: + +- The One-Pass Signature packets initiate the verification process, +- the literal data can then be processed (which means: it gets hashed), +- the signature packets at the end of the message can be verified against the hash digest that the previous step calculated. + +Note that the final step of verifying the cryptographic signature requires access to the signer's public key material. This public key material is not included in the signed message. The verifier must obtain the signer's public key data out-of-band (e.g. by obtaining the signer's certificate from a key server). ### Cleartext signatures -The *Cleartext Signature Framework* (CSF) is a mechanism that combines two goals: +The *Cleartext Signature Framework* (CSF) is an OpenPGP mechanism that combines two goals: - It leaves the message in clear text format, so that it can be viewed directly by a human in a program that knows nothing about OpenPGP. -- At the same time it adds an OpenPGP signature that allows verification of that message by users whose software supports OpenPGP. +- At the same time, it adds an OpenPGP signature that allows verification of that message by users whose software supports OpenPGP. #### Example @@ -91,21 +108,31 @@ r13/eqMN8kfCDw== -----END PGP SIGNATURE----- ``` -The cleartext signature consists of two blocks, which contain the message and a signature, respectively. In this case the message consists of the text "hello world". +The cleartext signature consists of two blocks, which contain the message and a signature, respectively. In this case, the message consists of the text "hello world". Notice that this message is readable by a human reader, without requiring additional software tools, as long as the reader understands which elements to ignore. -The message is followed by a block that contains an OpenPGP signature for the message, in ASCII armored form. Using OpenPGP software, this signature can be verified. +The message is followed by a block that contains an ASCII-armored OpenPGP signature for the message. Using this signature, OpenPGP software can verify the authenticity of the message in the first block. #### Use-case One use-case for cleartext signatures is: Asking someone to sign some piece of data. The person who is asked to sign the data can easily inspect it with simple commandline tools, such as `cat`, and verify that they agree with the data they are asked to sign. +```{admonition} TODO +:class: warning + +(Ask David for details:) + We use this for example to verify User ID and primary key of Arch Linux packagers before signing the User IDs on their keys with the main signing keys and to verify the data claims when introducing new packagers (i.e. already established packagers vouch for the data of a new packager). +``` #### Text transformations for cleartext signatures -TODO: explain text transforms for cleartext signatures (LF->CRLF etc) +```{admonition} TODO +:class: warning + +explain text transformations for cleartext signatures (LF->CRLF and additional escaping) +``` #### Pitfalls @@ -115,4 +142,14 @@ At the same time, they are considered a "legacy method"[^csf-gnupg] by some. [^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html -The RFC points out a number of [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), and advises that in many cases, the inline and detached signature forms are preferable. +The RFC points out a number of specific [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), and how to avoid them. It advises that in many cases, the inline and detached signature forms are preferable. + +## Advanced topics + +### Nesting of one-pass signatures + +```{admonition} TODO +:class: warning + +Write +``` \ No newline at end of file From 51ba91910605a9e8a67e5be67a6642b14df06fd5 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Fri, 10 Nov 2023 17:28:26 +0100 Subject: [PATCH 08/41] edit ch7 signatures over data --- book/source/07-signing_data.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 7331a3a..adbf0db 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -6,15 +6,14 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (signing_data)= # Signatures over data -A *data signature* guarantees the authenticity (and implicitly also the integrity) of some data. Typical use cases for data signatures in OpenPGP are signatures for software packages or emails. +In OpenPGP, a *data signature* guarantees the authenticity and, implicitly, the integrity of certain data. Typical use cases include the authentication of software packages and emails. -When we say "authenticity," here, we mean that the signature guarantees that whoever controls the signing key material has issued the signature. +"Authenticity" in this context means that the data signature was issued by the entity controlling the signing key material. However, +it does not automatically signal if the expected party indeed controls the signer certificate. OpenPGP does offer mechanisms for *strong authentication*, connecting certificates to specific identities. This verifies that the intended communication partner is indeed associated with the cryptographic identity behind the signature[^sign-auth]. -It is a separate question if the party we expect indeed controls the signer certificate. OpenPGP does offer mechanisms for *strong authentication* of the connection between certificates and identities. So, if necessary, we can also verify that our intended communication partner really uses the cryptographic identity that issued the signature[^sign-auth]. +[^sign-auth]: Other signing solutions, like [signify](https://flak.tedunangst.com/post/signify), focus on pure signing without strong authentication of the signer's identity. -[^sign-auth]: Other signing solutions, such as [signify](https://flak.tedunangst.com/post/signify), typically only offer a solution for pure signing, without offering a mechanism for strong authentication of the identity of the signer. - -Data signatures can only be issued by component keys that carry the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags). +Data signatures can only be issued by component keys with the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags). Note that signatures over data are distinct from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate. From f7ea1b115e60bb1e3592e20d27fbcef46551a416 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Fri, 10 Nov 2023 17:45:36 +0100 Subject: [PATCH 09/41] edit ch7 ## Signature types --- book/source/07-signing_data.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index adbf0db..8f3bdfa 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -19,15 +19,14 @@ Note that signatures over data are distinct from {ref}`component_signatures_chap ## Signature types -Data signatures use one of two OpenPGP [signature types](signature_types): +OpenPGP data signatures use one of two [signature types](signature_types): -- "Signature of a binary document" (*Binary Signature*, type ID `0x00`): A universal signature type for binary data. Binary signatures are typically used for files or data streams. -Binary signatures are calculated over the data "as is", without performing any transformations. -- "Signature of a canonical text document" (*Text Signature*, type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). The normalization mitigates issues caused by platform-specific text encodings, for example with detached signatures, where the message file may get re-encoded between signature generation and validation. +- **Binary signature** (type ID `0x00`): This is the standard signature type for binary data and is typically used for files or data streams. Binary signatures are calculated over the data without any modifications or transformations. +- **Text signature** (type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). This mitigates issues caused by platform-specific text encodings, which is particularly important for detached signatures where the message file might be re-encoded between signature creation and verification. -Data signatures are generated by hashing the message content, plus the metadata in the signature packet, and calculating a cryptographic signature over that hash. The resulting cryptographic signature is stored in an OpenPGP signature packet. +Data signatures are generated by hashing the message content along with the metadata in the signature packet, and calculating a cryptographic signature over that hash. The resulting cryptographic signature is stored in an OpenPGP signature packet. -Data signature packets can be used in three different forms. We'll discuss these in the following section. +Data signature packets manifest in three distinct forms, which will be detailed in the subsequent section. ## Forms of OpenPGP data signatures From 4fd97868e8f4f13488003a571b820ffa09aeb45c Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Fri, 10 Nov 2023 17:53:52 +0100 Subject: [PATCH 10/41] edit ch7 forms of data signatures --- book/source/07-signing_data.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 8f3bdfa..6d9b541 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -33,8 +33,8 @@ Data signature packets manifest in three distinct forms, which will be detailed OpenPGP signatures over data can be used in three different forms[^sign-modes-gpg]: - *Detached*: The signature is a standalone artifact, separate from the signed data. -- *Inline*: The original data and the signature over the data are collectively stored in an OpenPGP container. -- *Cleartext signature*: A message in text format and a signature over this message are stored in a combined text-format, which leaves the original message in a human-readable representation. +- *Inline*: The original data and the signature over data are enclosed within an OpenPGP container. +- *Cleartext signature*: A plaintext message and a signature over this message are stored in a combined text-format, maintaining the original message's readability. [^sign-modes-gpg]: These three signature forms correspond with GnuPG's `--detach-sign`, `--sign` and `--clear-sign` modes. From 1b5edc1774ae3ca1891cd35148fc0d0c9281eeff Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 11 Nov 2023 18:37:14 +0100 Subject: [PATCH 11/41] ch7: clarify CSF and its use --- book/source/07-signing_data.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 6d9b541..cc0385c 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -106,23 +106,22 @@ r13/eqMN8kfCDw== -----END PGP SIGNATURE----- ``` -The cleartext signature consists of two blocks, which contain the message and a signature, respectively. In this case, the message consists of the text "hello world". +A cleartext signature consists of two blocks. These blocks contain the message and a signature, respectively. In this case, the message consists of the text `hello world`. -Notice that this message is readable by a human reader, without requiring additional software tools, as long as the reader understands which elements to ignore. +Notice that the message in the first block is readable by a human reader, without requiring additional software tools, as long as the reader knows where to look, and which elements to ignore. -The message is followed by a block that contains an ASCII-armored OpenPGP signature for the message. Using this signature, OpenPGP software can verify the authenticity of the message in the first block. +The second block contains an ASCII-armored OpenPGP signature for the message. Using this signature, OpenPGP software can verify the authenticity of the message. -#### Use-case +#### Use-cases -One use-case for cleartext signatures is: Asking someone to sign some piece of data. The person who is asked to sign the data can easily inspect it with simple commandline tools, such as `cat`, and verify that they agree with the data they are asked to sign. +Clear text signatures combine two of the benefits of detached and inline-signatures: -```{admonition} TODO -:class: warning +- They are self-contained, the message and signature can be stored as a single file +- The message remains human-readable, without requiring additional software tooling -(Ask David for details:) +This combination can be attractive for processes where signed messages are handled in a partially manual manner, and stored in a system that doesn't have strong support for OpenPGP in that particular workflow[^arch-certifications]. -We use this for example to verify User ID and primary key of Arch Linux packagers before signing the User IDs on their keys with the main signing keys and to verify the data claims when introducing new packagers (i.e. already established packagers vouch for the data of a new packager). -``` +[^arch-certifications]: For example, Arch Linux uses a workflow to certify User IDs of new packagers that relies on [cleartext signed statements by established packagers](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/blob/master/.gitlab/issue_templates/New%20Packager%20Key.md?ref_type=heads&plain=1#L33-46). These signed statements are stored in an issue tracker system, as attachments, for later inspection. In this use case, it is convenient that the message and the signature are stored as one combined file (not as separate ones which would be more tedious to handle manually), and that the message is easy to read. Based on the vouches in these cleartext signed messages, and an [email confirmation by the new packager](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/wikis/workflows/verify-a-packager-key), main signing key operators issue OpenPGP third-party certifications. #### Text transformations for cleartext signatures From 6dc243de9820fc170018cfc2c6cb43609dd97c05 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 11 Nov 2023 18:45:18 +0100 Subject: [PATCH 12/41] ch7: Write "transformations" section about CSF --- book/source/07-signing_data.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index cc0385c..ef18212 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -17,6 +17,7 @@ Data signatures can only be issued by component keys with the *signing* [key fla Note that signatures over data are distinct from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate. +(data_signature_types)= ## Signature types OpenPGP data signatures use one of two [signature types](signature_types): @@ -125,11 +126,9 @@ This combination can be attractive for processes where signed messages are handl #### Text transformations for cleartext signatures -```{admonition} TODO -:class: warning +In the cleartext signature framework, the message text is normalized by [escaping dashes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text), to prevent parsing problems where message content and armor headers are confused. -explain text transformations for cleartext signatures (LF->CRLF and additional escaping) -``` +Additionally, as usual for [text signatures](data_signature_types), the signature is calculated on the text with normalized line endings (``). #### Pitfalls From 7706df1cc987d7cb81c725ba759e61f45d011b5c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 13 Nov 2023 01:28:11 +0100 Subject: [PATCH 13/41] ch4: fix typos --- book/source/04-certificates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index d1f435c..7b0b456 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -165,9 +165,9 @@ Heiko, please clarify what the value is of this proposal or remove it. ``` (primary_user_id)= -### Implimations of the Primary User ID +### Implications of the Primary User ID -Within a certificate, a specific User ID is desginated as the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-primary-user-id). +Within a certificate, a specific User ID is designated as the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-primary-user-id). Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). The preferences associated with the Primary User ID take precedence by default. From 6bbef95d219d7011030290113b9fbdbf3c8f72eb Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 13 Nov 2023 01:29:37 +0100 Subject: [PATCH 14/41] ch4: add todo --- book/source/04-certificates.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 7b0b456..771f39b 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -135,6 +135,11 @@ Instead, key flags, along with other metadata about that component key, such as - For the primary key, its key flags and other metadata can be defined in two ways: they can be linked with the [Primary User ID](primary_user_id) or through a [direct key signature](direct_key_signature). - For subkeys, the key flags and other metadata are set using the mechanism that binds the subkey to the certificate, specifically through the primary key. Further details on [binding subkeys](binding_subkeys) are below. +```{admonition} TODO +:class: warning + +Write a section about algorithm preference/feature signaling +``` (identity_components)= ## Identity components From 06da358f9917de536295886c5658842e6e6ac8bf Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sun, 12 Nov 2023 20:46:38 +0100 Subject: [PATCH 15/41] ch8: write missing "signatures for primary key metadata" section --- book/source/08-signing_components.md | 29 +++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 3580ba5..8063d33 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -139,14 +139,33 @@ Linking a User ID to an OpenPGP certificate This signature is calculated over the primary key and User ID. +### Adding metadata to the primary key + +The signatures that bind subkeys and identity components to a certificate serve two different purposes: Linking components to the certificate and adding metadata to a component. + +The primary key in a certificate doesn't need to be linked to the certificate. It acts as the anchor for linking, itself and thus doesn't require being linked. However, there is nevertheless a need to associate metadata with the primary key. + +There are two mechanisms for adding metadata to the primary key: + +- Via a direct key signature on the primary key, or +- via a "primary User ID" binding signature. + +Relevant metadata for the primary key that is defined the above mechanisms includes: + +- Key expiration, +- key flags, +- algorithm preference signaling. + (direct_key_signature)= -### Direct key signature: Adding metadata to the primary key +#### Direct key signature -```{admonition} TODO -:class: warning +A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) is one mechanism to store information about the primary key, and about the entire certificate. -explain metadata associated with this signature, and that c-r prefers this over primary user id. -``` +In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-9). + +#### Primary User ID binding self-signature + +In a certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the primary key of the certificate. ### Revocations: Invalidating components of a certificate From 2346c346c2d82e9954cc8aecb7e7ab7685e1e893 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sun, 12 Nov 2023 18:44:48 +0100 Subject: [PATCH 16/41] ch8: edits for clarity and flow --- book/source/08-signing_components.md | 119 +++++++++++++++------------ 1 file changed, 65 insertions(+), 54 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 8063d33..b3f5786 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -6,70 +6,87 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (component_signatures_chapter)= # Signatures on components -In this chapter, we'll look into OpenPGP signatures that apply to components of certificates. That is, signatures that apply to: +In this chapter, we'll look at OpenPGP signatures that apply to components of certificates. That is, signatures that apply to: - Component keys (primary keys or subkeys) and - Identity components (User IDs or User attributes). -This chapter adds detail to material we discussed in the {ref}`certificates_chapter` chapter. +Signatures on components are used to construct and maintain certificates, and to model the authentication of identities. -## Two flavors of signatures on components: first party vs third party +This chapter expands on topics we introduced in the {ref}`certificates_chapter` chapter. -Signatures on components are a crucial mechanism for forming OpenPGP certificates, as well as for life-cycle management of certificates, when issued by the certificate holder. +## Self-signatures vs third-party signatures -Separately, signatures on components can serve as a building block for OpenPGP's decentralized authentication functionality. Signatures for this functionality are issued by third parties. +There are two fundamentally different flavors of signatures on components: -### Self-signatures: Forming certificates and life-cycle management +- *Self-signatures*, which are issued by the certificate holder themselves using the primary key of the certificate, and +- *third-party signatures*, which are issued by a third party. -*Self-signatures* are issued by the certificate's owner, using the primary key of the same certificate. +### Self-signatures + +*Self-signatures* on components are a crucial mechanism for forming OpenPGP certificates (by binding the certificate's components into one combined data structure), as well as for life-cycle management of certificates (that is: performing changes to the certificate, over time). + +Life-cycle management operations on OpenPGP certificates and their components include: + +- binding additional components to a certificate, +- changing the expiration date, or other metadata, of a component, and +- invalidating components or existing self-signatures using revocations. + +Self-signatures are issued by the certificate's owner, using the primary key of the same certificate. -Signatures on components are also a central mechanism for life-cycle management of OpenPGP certificates and their components. This includes defining or changing expiration dates, or issuing revocations, for certificates or their components. - ```{note} -The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is not required in order to issue certifying self-signatures. This key flag is only necessary to issue valid third-party certifications. +No [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) is required to issue self-signatures. An OpenPGP primary key can issue self-signatures by default. ``` -### Third-party certifications: Encoding authentication +### Third-party signatures -Mechanisms for decentralized authentication of identities are one of OpenPGP’s core strengths: Signatures on components by third parties can be used for the authentication of identities. +Third-party signatures on components form the basis for OpenPGP's decentralized authentication functionality (also known as the *Web of Trust*). They encode authentication-related statements about certificates and their associated identities. -Using OpenPGP signatures, identity claims can be certified by third parties. Similarly, authentication decisions can be delegated using signatures. +Third-party OpenPGP signatures can be used to make the following types of statements: -### Meaning differs between self- and third-party signatures +- Certification of identity claims, +- Delegation of authentication decisions, +- Invalidating previous third-party signature statements using revocations. + +```{note} +The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue third-party signatures. Only the primary key of a certificate may hold this key flag. +``` + +### Self-signatures and third-party signatures convey different meanings The meaning of a signature depends in part on who issued it. A self-signature performs a different function than the same type of signature issued by a third party. For example: -- A [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued as a self-signature can be used to set preferences and advertise features that apply to the whole certificate, while -- A similar [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued by a third party, which carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket, acts as a statement by the issuer that they delegate trust to the signed certificate (the issuer thereby uses the remote certificate as a trust root in the *Web of Trust*). +- Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a certificate, while +- third-party signatures of the same type IDs indicate that the signer endorses the authenticity of a User ID. Or: -- Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a certificate, while -- the same signature type IDs issued by a third party are statements by the signer that they endorse the authenticity of the signed User ID to some degree. +- A [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued as a self-signature can be used to set preferences and advertise features that apply to the whole certificate, while +- a similar [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued by a third party delegates trust to the signed certificate, when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket. The issuer thereby configures the signed certificate as a trust root in the *Web of Trust*, for themselves. -## Self-signatures: Linking the components of a certificate +## Self-signatures: Forming certificates and life-cycle management -So far we've looked at the components in an OpenPGP certificate, but certificates actually contain another set of elements, which bind the components together, and add metadata to them. +The components in an OpenPGP certificate are bound together using signatures. These *binding signatures* join the components together, while also adding metadata to them. -Internally, an OpenPGP certificate consists of a sequence of OpenPGP packets. These packets are just stringed together, one after the other. When a certificate is stored in a file[^tpk], it's easy to remove some of these packets, or add new ones. +Internally, an OpenPGP certificate consists of a sequence of OpenPGP packets. These packets are just strung together, one after the other. When a certificate is stored in a file[^tpk], it's easy to remove some of these packets, or add new ones. [^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 [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). +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. They are issued by the primary key of 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 certificate 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 load a certificate can (and usually should) discard components that don't have a valid cryptographic connection with the certificate. ```{note} -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. +Conversely, it's easy for a third party to leave out packets, while handling an OpenPGP certificate dataset. An attacker can, for example, simply choose to omit revocation packets. The recipient of such a partial copy has no way to notice this omission, without access to a different source for the certificate that contains the revocation packet. ``` -Note, though, that there are some cases where third parties legitimately add "unbound" packets to certificates (that is: packets that are not signed by the certificate's owner): +Note that there are some cases where third parties legitimately add "unbound" packets (that is: packets that are not signed by the certificate's owner) to a certificate: -- [Third-party certifications](third_party_cert) are traditionally added to the certificate that they make a statement about (this can cause problems in systems that unconditionally accept and include such certifications[^flooding]), +- [Third-party certifications](third_party_cert) are traditionally stored as part of the packet data of the certificate that they make a statement about (in systems that unconditionally accept and include such certifications, this can cause problems[^flooding]), - OpenPGP software may add [unbound identity data](unbound_user_ids), locally. [^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). @@ -77,21 +94,21 @@ Note, though, that there are some cases where third parties legitimately add "un (bind_subkey)= ### Binding subkeys to a certificate -A subkey is linked to an OpenPGP certificate using a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID 0x18). This signature type effectively signals that the "primary key wants to be associated with the subkey". +Subkeys is linked to an OpenPGP certificate using a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`). This signature type effectively signals that the "primary key wants to be associated with the subkey". -A subkey binding signature binds the public primary key and the public subkey, and additionally metadata in the signature packet. Once generated, the subkey binding signature packet is stored in the certificate right after the subkey. +A subkey binding signature binds a subkey to a primary key, and adds metadata in the signature packet. Once generated, the subkey binding signature packet is stored in the certificate, directly following the subkey it binds. -(Note that subkeys that have the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) are a special case, see {numref}`bind_subkey_sign`.) +(Note that subkeys that have the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) are a special case, and are handled slightly differently. See {numref}`bind_subkey_sign`.) ```{figure} diag/subkey_binding_signature.png Linking an OpenPGP subkey to the primary key with a binding signature ``` -In order to specify an expiration time for the subkey, a key expiration time subpacket can be included in the subkey binding signature packet. +To specify metadata for the subkey, such as the [*key expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket), or the capabilities that are set using [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags), subpackets are included in the subkey binding signature packet. ```{note} -The validity of a subkey is bounded by that of the primary key, meaning an expired primary key causes the subkey to be invalidated, no matter the subkey expiration time. +The validity of a subkey is bounded by that of the primary key, meaning that an expired primary key causes the subkey to be invalid, no matter the subkey expiration time. It's legal for a subkey to not have an explicit expiry time. In that case, its expiration date is implicitly the same as the expiration date of the primary key. @@ -101,42 +118,41 @@ A subkey cannot be "older" than the primary key. The value of the subkeys creati (bind_subkey_sign)= ### Special case: Binding signing subkeys to a certificate -To bind subkeys with the "signing" key flag to a certificate is a special case. For the most part, it works the same as binding other types of subkeys, but there is an additional requirement: +To bind subkeys with the "signing" key flag to a certificate is a special case. For the most part, it works the same as binding other types of subkeys, but there is one additional requirement: -When binding a signing subkey to a primary key, it is not sufficient that the "primary key wants to be associated with the subkey." In addition, the subkey must signal that it "wants to be associated with that primary key." +To bind a signing-capable subkey to a primary key, it is not sufficient that the "primary key wants to be associated with the subkey." In addition, the subkey must signal that it "wants to be associated with that primary key." Otherwise, Alice could "adopt" Bob's signing subkey and convincingly claim that she made signatures that were in fact issued by Bob. This is to prevent an attack where the attacker "adopts" the victims signing subkey as their own in order to claim ownership over documents which were in fact signed by the victim. -In contrast to the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID 0x18), which is issued by the certificate's primary key, the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID 0x19) is instead created by the subkey (informally also called an embedded "back signature"). +In contrast to the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`), which is issued by the certificate's primary key, the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID `0x19`) is instead created by the subkey (informally also called an embedded "back signature"). ```{figure} diag/subkey_binding_signatur_for_signing_sk.png Linking an OpenPGP signing subkey to the primary key with a binding signature, and an embedded primary key binding signature ``` -This additional "Primary Key Binding" Signature is informally called a "back signature" (because the subkey uses the signature to point "back" to the primary key) is an embedded `PrimaryKeyBinding` "back signature" (type 0x19). +The additional [*primary key binding*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) signature (type 0x19) is informally called a "back signature" (because the subkey uses the signature to point "back" to the primary key). -The *primary key binding signature* is "embedded" as subpacket data in the *subkey binding signature* that connects the signing subkey to the primary key. +The *primary key binding signature* is "embedded" as subpacket data in the *subkey binding signature* which connects the signing subkey to the primary key. ### Binding identities to a certificate Another use-case for a self-signature is to link an identity component (such as a User ID that specifies a name and email address) to a certificate. -User ID components are bound to an OpenPGP certificate by issuing a self-signature ("User Attributes" work analogously). +User ID components are bound to an OpenPGP certificate by issuing a certifying self-signature. "User Attributes" work analogously. For example, the User ID `Alice Adams ` may be associated with Alice's certificate `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. -Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a "certifying self-signature" is created (usually with the signature type [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID 0x13, or sometimes with type ID 0x10, 0x11 or 0x12)). This signature is issued by the primary key. +Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a *certifying self-signature* is created. There are four variant certifying self-signature types. Usually the signature type [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID `0x13`) is used to bind User IDs to one's certificate (sometimes, type ID `0x10`, `0x11` or `0x12` may be used instead). This binding signature must be issued by the primary key. -The resulting certification is stored as part of the certificate, right after the User ID packet. +The resulting certifying self-signature packet is stored as part of the certificate, directly following the User ID packet. ```{figure} diag/user_id_certification.png ---- ---- + Linking a User ID to an OpenPGP certificate ``` -This signature is calculated over the primary key and User ID. +This signature is calculated over the primary key, User ID and the metadata of the signature packet. ### Adding metadata to the primary key @@ -175,7 +191,12 @@ A revocation signature is used to retract the statement formed by a prior signat A subkey revocation signature revokes a prior subkey binding signature, while a certification revocation revokes a certification signature. Typical use-cases for revocations are marking certificates or individual subkeys as unusable (for example, when the private key has been compromised or superseded), or marking User IDs as no longer used. -A revocation signature can either be hard or soft. A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material. +A revocation signature can either be *hard* or *soft*: + +- A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. +- A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. + +Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material. ```{note} OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures. @@ -199,7 +220,7 @@ A missing revocation reason subpacket is equivalent with a hard revocation reaso ``` (third_party_cert)= -## Third-party certifications: Making statements about other people's certificates and identities +## Third-party certifications: Encoding authentication statements ```{admonition} TODO :class: warning @@ -362,13 +383,3 @@ The [specification recommends](https://www.ietf.org/archive/id/draft-ietf-openpg In some cases, duplicate packets with conflicting content even make sense, e.g., if a signature was made by a version 4 issuer key whose key material was migrated from an older OpenPGP version such as v3. In this case, either the v3 or v4 key could be used to validate the v4 signature, but since the key ID calculation scheme was changed between v3 and v4, these identifiers would differ. Therefore, the signature could contain two issuer key ID subpackets with conflicting, but correct values. - -```{admonition} TODO -:class: warning - -- Key Flags -- Preferences -- Embedded Signature (back sig) -- Trust Signatures (amount, depth) -- Direct key signatures -``` From 61d664f0b09dbd98a9dc10ef4129b4ece449cf0c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sun, 12 Nov 2023 23:30:13 +0100 Subject: [PATCH 17/41] ch8: edit and expand "revocations" section --- book/source/08-signing_components.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index b3f5786..cca65a4 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -183,21 +183,18 @@ In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.i In a certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the primary key of the certificate. -### Revocations: Invalidating components of a certificate +### Revocation self-signatures: Invalidating components of a certificate One important class of self-signatures are revocations. -A revocation signature is used to retract the statement formed by a prior signature. -A subkey revocation signature revokes a prior subkey binding signature, while a certification revocation revokes a certification signature. +A revocation signature is used to invalidate a component, or retract the statement formed by a prior signature. + +- A [*key revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-revocation-signature-ty) (type ID `0x20`) marks a primary key as revoked. +- a [*subkey revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature) (type ID `0x28`) revokes a prior subkey binding signature, while +- a [*certification revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`) revokes a certification signature. + Typical use-cases for revocations are marking certificates or individual subkeys as unusable (for example, when the private key has been compromised or superseded), or marking User IDs as no longer used. -A revocation signature can either be *hard* or *soft*: - -- A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. -- A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. - -Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material. - ```{note} OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures. @@ -208,15 +205,15 @@ Note: certification signatures [can be made irrevocable](https://www.ietf.org/ar #### Hard vs. soft revocations -A revocation signature may contain a subpacket indicating the reason for revocation. This subpacket contains a code which specifies why the revocation was issued. This code determines, whether the revocation is hard or soft. +A revocation signature can contain a subpacket indicating the [*reason for revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation). The value of this subpacket contains a code that specifies why the revocation was issued. This code determines whether the revocation is considered a *soft revocation* or a *hard revocation*: -A soft revocation is typically used for graceful or planned revocations. A soft revocation can be reverted by re-validating the certificate, User ID or subkey with a fresh binding signature. -A soft revocation invalidates the target certificate beginning with the revocations creation time. +- A *soft revocation* is typically used for graceful or planned invalidation. Soft revocation of a component invalidates it from the revocation signature's creation time onwards. Uses of the component before the revocation time remain intact. Soft revocations can be reverted by re-validating the invalidated component with a new self-signature. +- A *hard revocation*, by contrast, invalidates the component retroactively, rendering all past and future uses invalid. Hard revocation of a component cannot be undone by re-validating the component. -Contrary, a hard revocation cannot be re-validated. Furthermore, a hard-revoked certificate is invalidated retroactively. +Soft revocations are typically used when a certificate, subkey or User ID is retired or superseded gracefully, while hard revocations are typically used to signal compromise of secret key material. ```{note} -A missing revocation reason subpacket is equivalent with a hard revocation reason. +A revocation signature that has no *reason for revocation* subpacket is interpreted as a hard revocation. ``` (third_party_cert)= From 6812b29d23ee43e0fdd297259b35254f50bea0d2 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 13 Nov 2023 01:07:32 +0100 Subject: [PATCH 18/41] ch8: third-party signatures --- book/source/08-signing_components.md | 67 ++++++++++++++++++++++------ 1 file changed, 54 insertions(+), 13 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index cca65a4..9b3aa82 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -217,7 +217,59 @@ A revocation signature that has no *reason for revocation* subpacket is interpre ``` (third_party_cert)= -## Third-party certifications: Encoding authentication statements +## Third-party signatures: Authentication statements + +Signatures on components by third parties mainly encode authentication of identities and delegations of trust decisions. + +Third party signatures can be inspected and reasoned about manually by humans. More powerfully, though, they can also be used as machine-readable artifacts, by OpenPGP software, which can reason about the authenticity of certificates on behalf of its users, based on trust roots that the user has specified. + +### Certifying identity components + +By issuing a certifying signature on an identity, the signer expresses that he has verified that the identity and the certificate are meaningfully linked. The signer vouches for the connection between the certificate and the identity. + +If Alice is certain that the identity `Bob Baker ` controls the certificate `0xB0B`, she can create a certification signature that binds Bob's User ID and Bob's certificate. Bob will usually distribute this certifying signature from Alice as part of his certificate. + +Effectively, this is a way for Alice to broadcast the statement "I, Alice, have checked that `Bob Baker ` controls the certificate `0xB0B`." Other users may or may not decide to rely on this statement by Alice. + +### Delegating authentication: Trust signatures + +The OpenPGP standard specifies primitives to delegate authentication decisions to certificates. The standard uses the (somewhat confusing) term "trust" for this mechanism. Delegating authentication decisions to a certificate, using a [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpacket makes the target certificate a "trusted introducer." + +A "trusted introducer" acts as a trust root for the user. + +OpenPGP's delegation mechanism allows specifying transitive delegation of trust: delegating authentication decisions across more than one hop. The standard refers to certificates as a "meta-introducer," when a "trust signature" subpacket defines it as a trusted introducer with a "level" of two or more. + +A "level 2" trust signature suboacket means that the target certificate may delegate to a second, intermediate, introducer, which in turn has issued a certification signature for an identity. + +[*Trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpackets can be used in two types of signatures: + +- On an identity certification signature (type ID `0x10` - `0x13`), or on a +- [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) (type ID `0x1F`) + + +```{admonition} TODO +:class: warning + +Write about amount +``` + +#### Limiting the scope of delegations with regular expressions + +When using *trust signature* subpackets, a delegation can be limited to identities that match a [*regular expression*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#regex-subpacket), for example, to limit the email address in a User ID to a specific domain name. + +With this mechanism, it is possible to delegate authentication decisions only for User IDs that match the email domain of an organization. + +For example, Alice could delegate trust decisions only for email addresses in the domain `bob.com` to Bob, if she considers Bob to be a reasonable source of identity certifications for that domain. + +### Decentralized automated trust decisions; or, the "Web of Trust" + +```{admonition} TODO +:class: warning + +More WoT. +``` + +### Revoking third-party signatures: Undoing previous statements ```{admonition} TODO :class: warning @@ -225,18 +277,7 @@ A revocation signature that has no *reason for revocation* subpacket is interpre write ``` -### Certifying identities - -Certifications over User IDs can also be used to certify certificates of third-parties. -If Alice is certain that `Bob Baker ` controls the key `0xB0B`, she can create a User ID certification signature for that identity and send it to Bob. -Bob can then add this signature to his certificate. - -TODO: More WoT. - -### Delegating authentication: trust signatures - -### Revocations: Undoing previous statements - +- [*Certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`) ## Advanced topics From 42eb52e95ced75018359936586289105f66d5dd6 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 13 Nov 2023 20:52:08 +0100 Subject: [PATCH 19/41] ch8: some more text about delegating trust and WoT --- book/source/08-signing_components.md | 63 ++++++++++++++++++++-------- book/source/21-resources.md | 2 +- 2 files changed, 46 insertions(+), 19 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 9b3aa82..8a9f3f1 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -233,24 +233,49 @@ Effectively, this is a way for Alice to broadcast the statement "I, Alice, have ### Delegating authentication: Trust signatures -The OpenPGP standard specifies primitives to delegate authentication decisions to certificates. The standard uses the (somewhat confusing) term "trust" for this mechanism. Delegating authentication decisions to a certificate, using a [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpacket makes the target certificate a "trusted introducer." +The OpenPGP standard specifies primitives to delegate authentication decisions to certificates. The standard uses the (somewhat confusing) term "trust" for this mechanism. Delegating authentication decisions to a certificate, using a [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpacket, makes the target certificate a "trusted introducer." A "trusted introducer" acts as a trust root for the user. -OpenPGP's delegation mechanism allows specifying transitive delegation of trust: delegating authentication decisions across more than one hop. The standard refers to certificates as a "meta-introducer," when a "trust signature" subpacket defines it as a trusted introducer with a "level" of two or more. - -A "level 2" trust signature suboacket means that the target certificate may delegate to a second, intermediate, introducer, which in turn has issued a certification signature for an identity. - [*Trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpackets can be used in two types of signatures: - On an identity certification signature (type ID `0x10` - `0x13`), or on a - [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) (type ID `0x1F`) +#### Trust depth (or "level") -```{admonition} TODO +OpenPGP's delegation mechanism allows specifying transitive delegation of trust: delegating authentication decisions across more than one hop. The standard refers to certificates as a "meta-introducer," when a "trust signature" subpacket defines it as a trusted introducer with a depth (or "level") of two or more. + +A trust signature subpacket with means that the target certificate may delegate to a second, intermediate, introducer, which in turn has issued a certification signature for an identity. + +**Examples** + +When Alice delegates trust decisions to Trent, designating Trent as a trusted introducer with a *trust depth* of 1, then Alice's OpenPGP implementation will only accept direct certifications by Trent. For example, Trent may have certified that Bob's certificate with the fingerprint `0xB0B` is legitimately connected to Bob's User ID `Bob `. If Alice tries to communicate with Bob using his identity `Bob `, then Alice's OpenPGP software can automatically determine that the certificate `0xB0B` is appropriate to use. + +However, Alice's OpenPGP software wouldn't accept a series of delegations from Trent via Tristan to a certification of Carol's identity (let's imagine that Trent has designated Tristan a trusted introducer). For Alice's OpenPGP software to accept such a path, she needs to designate Trent as a trusted introducer with the `level` set to 2 or more. + +```{admonition} VISUAL :class: warning -Write about amount +add diagrams? +``` + +#### Trust amount + +A trust signature can quantify the degree to which the issuer wants to rely on a delegation. This "trust amount" has a numerical value between 0 and 255. + +A trust amount of 120 indicates "complete trust," which means that a certification by that trusted introducer is considered sufficient to consider authentications by that introducer as sufficient. + +**Examples** + +If Alice designates Trent as a trusted introducer at a trust amount of 120, then Alice's OpenPGP software will consider Bob's identity fully authenticated if Trent has certified it. + +However, if Alice only assigns a trust amount of 60 (which indicates "partial trust") to Trent, then her software would not consider Bob's identity fully authenticated. Now let's imagine that Alice additionall assigns a trust amount of 60 to Tristan (a second, independent introducer), and Tristan also certified Bob's identity. In this case, Alice's OpenPGP software will consider Bob's identity fully authenticated, based on the combination of both delegations, and the certifications the two trusted introducers issued. + +```{admonition} VISUAL +:class: warning + +add diagrams? ``` #### Limiting the scope of delegations with regular expressions @@ -259,25 +284,27 @@ When using *trust signature* subpackets, a delegation can be limited to identiti With this mechanism, it is possible to delegate authentication decisions only for User IDs that match the email domain of an organization. +**Example** + For example, Alice could delegate trust decisions only for email addresses in the domain `bob.com` to Bob, if she considers Bob to be a reasonable source of identity certifications for that domain. +```{admonition} VISUAL +:class: warning + +add diagrams? +``` + ### Decentralized automated trust decisions; or, the "Web of Trust" -```{admonition} TODO -:class: warning +The OpenPGP, the "Web of Trust" is a trust model that performs authentication decisions on a set of certifications and delegations. -More WoT. -``` +The OpenPGP "Web of Trust" model assumes that every user makes their own choice about who they delegate authentication decisions to. Based on the available certificates and third-party signatures, the user's OpenPGP software uses the Web of Trust mechanism to determine which certificates are considered reliable for an identity. + +The OpenPGP RFC doesn't specify how exactly Web of Trust calculations are performed. It only defines the data formats that these calculations can be performed on. See external resources in {numref}`wot-resources`. ### Revoking third-party signatures: Undoing previous statements -```{admonition} TODO -:class: warning - -write -``` - -- [*Certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`) +The issuer of a third-party signature can undo such a signature by issuing a [*certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`). ## Advanced topics diff --git a/book/source/21-resources.md b/book/source/21-resources.md index ada1327..0364d0f 100644 --- a/book/source/21-resources.md +++ b/book/source/21-resources.md @@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 [RFC4880](https://www.rfc-editor.org/rfc/rfc4880.html) OpenPGP Message Format [2007], specifies OpenPGP version 4 - +(wot-resources)= ## Web of Trust [PGP Web of Trust: Core Concepts Behind Trusted Communication](https://www.linux.com/training-tutorials/pgp-web-trust-core-concepts-behind-trusted-communication/), From f0052e23c246f8ea45ae74f1eb2c8ea7dc61d600 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Mon, 13 Nov 2023 20:57:44 +0100 Subject: [PATCH 20/41] edits to data signature forms --- book/source/07-signing_data.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 6d9b541..c28a887 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -30,13 +30,14 @@ Data signature packets manifest in three distinct forms, which will be detailed ## Forms of OpenPGP data signatures -OpenPGP signatures over data can be used in three different forms[^sign-modes-gpg]: +OpenPGP data signatures can be applied in three distinct methods[^sign-modes-gpg]: -- *Detached*: The signature is a standalone artifact, separate from the signed data. -- *Inline*: The original data and the signature over data are enclosed within an OpenPGP container. -- *Cleartext signature*: A plaintext message and a signature over this message are stored in a combined text-format, maintaining the original message's readability. +- **Detached**: The OpenPGP signature exists as a separate entity, independent from the signed data. +- **Inline**: Both the original data and its corresponding OpenPGP signature are encapsulated within an OpenPGP container. +- **Cleartext signature**: A plaintext message and its OpenPGP signature coexist in a combined text format, preserving the readability of the original message. -[^sign-modes-gpg]: These three signature forms correspond with GnuPG's `--detach-sign`, `--sign` and `--clear-sign` modes. + +[^sign-modes-gpg]: These three methods of signature application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options. ### Detached signatures From a76acf950b6278b7b8a977277dcd815c046f52c6 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Mon, 13 Nov 2023 20:57:56 +0100 Subject: [PATCH 21/41] edits to data signature forms --- book/source/07-signing_data.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index c28a887..4ef4aa8 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -30,14 +30,14 @@ Data signature packets manifest in three distinct forms, which will be detailed ## Forms of OpenPGP data signatures -OpenPGP data signatures can be applied in three distinct methods[^sign-modes-gpg]: +OpenPGP data signatures can be applied in three distinct forms[^sign-modes-gpg]: - **Detached**: The OpenPGP signature exists as a separate entity, independent from the signed data. - **Inline**: Both the original data and its corresponding OpenPGP signature are encapsulated within an OpenPGP container. - **Cleartext signature**: A plaintext message and its OpenPGP signature coexist in a combined text format, preserving the readability of the original message. -[^sign-modes-gpg]: These three methods of signature application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options. +[^sign-modes-gpg]: These three forms of signature application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options. ### Detached signatures From 7e89a9f11f4224eba727e30b45309f43069a42a3 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Mon, 13 Nov 2023 21:18:15 +0100 Subject: [PATCH 22/41] remove blank line --- book/source/07-signing_data.md | 1 - 1 file changed, 1 deletion(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 4ef4aa8..28dcaba 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -36,7 +36,6 @@ OpenPGP data signatures can be applied in three distinct forms[^sign-modes-gpg]: - **Inline**: Both the original data and its corresponding OpenPGP signature are encapsulated within an OpenPGP container. - **Cleartext signature**: A plaintext message and its OpenPGP signature coexist in a combined text format, preserving the readability of the original message. - [^sign-modes-gpg]: These three forms of signature application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options. ### Detached signatures From ee65b80bc7eebd5a2171df9e8b9ba96b1ba23b25 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Mon, 13 Nov 2023 21:20:09 +0100 Subject: [PATCH 23/41] default to data signatures not signature over data --- book/source/07-signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 28dcaba..f6c2b7b 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -15,7 +15,7 @@ it does not automatically signal if the expected party indeed controls the signe Data signatures can only be issued by component keys with the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags). -Note that signatures over data are distinct from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate. +Note that data signatures are distinct from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate. ## Signature types From 62af0cb83b8ede55913fa7dad98825157c5d3514 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Mon, 13 Nov 2023 21:27:37 +0100 Subject: [PATCH 24/41] edit ch7 detached signatures --- book/source/07-signing_data.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index f6c2b7b..eb4a596 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -40,9 +40,9 @@ OpenPGP data signatures can be applied in three distinct forms[^sign-modes-gpg]: ### Detached signatures -A detached signature is produced by calculating an OpenPGP signature over the signed data. The original data is left as is, while the OpenPGP signature is stored as a standalone file. A detached signature can be distributed alongside or independent of the original data. The authenticity and integrity of the original data file can be verified using the detached signature file. +A detached signature is produced by calculating an OpenPGP signature over the data intended for signing. The original data remains unchanged, and the OpenPGP signature is stored as a standalone file. A detached signature file can be distributed alongside or independent of the original data. The authenticity and integrity of the original data file can be verified by using the detached signature file. -This signature format is especially useful for signing software releases and other files that must not be modified by the signing process. +This signature format is especially useful for signing software releases and other files where it is imperative that the content remains unaltered during the signing process. ### Inline signatures From 17d43e0e91485e44c127a2f6b62ea1505e08f70d Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Mon, 13 Nov 2023 21:33:03 +0100 Subject: [PATCH 25/41] edit ch7 inline signatures --- book/source/07-signing_data.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index eb4a596..3fd5d5e 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -46,9 +46,9 @@ This signature format is especially useful for signing software releases and oth ### Inline signatures -An inline signature joins the signed data and a signature over this data into one combined OpenPGP message. +An inline signature joins the signed data and its corresponding data signature into a single OpenPGP message. -This method is usually used with signed and/or encrypted emails. Most software that supports OpenPGP for encrypted and/or signed messages uses inline-signatures. +This method is commonly used for signing or encrypting emails. Most email software capable of handling OpenPGP communications typically uses inline signatures. #### Structure From e6b9c11a3dabce9564b0c9732be731c70e6f53be Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Mon, 13 Nov 2023 22:06:35 +0100 Subject: [PATCH 26/41] edit ch7 inline signatures --- book/source/07-signing_data.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 3fd5d5e..618e80f 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -54,15 +54,18 @@ This method is commonly used for signing or encrypting emails. Most email softwa An inline-signed OpenPGP message consists of three segments: -- One or more [One-Pass Signature packets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig), -- the original data, wrapped in a [Literal Data packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit), -- the corresponding Data Signature packets. +1. **One-pass signature packets**: These one or more packets precede the signed data and enable signature computation in one pass. See[One-Pass Signature Packet (Type ID 4)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) of the RFC. + +2. **Literal data**: This is the original data (e.g., the body of a message) that the user wishes to encrypt or sign, without additional interpretation or conversion. [Literal Data Packet (Type ID 11)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit). + +3. **Data signature packets**: These contain the cryptographic signature corresponding to the original data. + #### Creation -To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into am output OpenPGP message file. The signer calculates a cryptographic signature over the course of this process. Therefore, an efficient signer can only emit the resulting data signature packet at the end of this process, and thus store it at the end of the data stream. +To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into am output OpenPGP message file. As the data is processed, the signer simultaneously calculates a cryptographic signature. This procedure results in a data signature packet being appended to the output OpenPGP message file, an essential step for efficient signing. -On the other hand, an efficient verifying application needs to know how to process the literal data before reading it. This is the purpose of the so-called One-Pass Signature packets in the first segment of inline-signed messages. One-Pass Signature packets contain the fingerprint of the signing key, as well as the hash algorithm used to calculate the hash digest for the signature. +For efficient verification, an application must understand how to handle the literal data prior to its reading. This requirement is addressed by the One-Pass Signature packets located at the beginning of inline-signed messages. These packets include essential information such as the fingerprint of the signing key and the hash algorithm used for computing the signature's hash digest. This setup enables the verifier to process the data correctly and efficiently. ```{admonition} TODO :class: warning @@ -72,13 +75,15 @@ Is the signer keyid/fingerprint in the OPS important for the verifier to be able #### Verification -This structure allows verifying applications to verify inline-signed messages in *one pass*: +Inline-signed messages enable efficient verification in *one pass*, structured as follows: -- The One-Pass Signature packets initiate the verification process, -- the literal data can then be processed (which means: it gets hashed), -- the signature packets at the end of the message can be verified against the hash digest that the previous step calculated. +1. **Initiation with One-Pass Signature packets**: These packets begin the verification process. They include the signer's key ID/fingerprint, essential for identifying the appropriate public key for signature validation. + +2. **Processing the literal data**: This step involves hashing the literal data, preparing it for signature verification. -Note that the final step of verifying the cryptographic signature requires access to the signer's public key material. This public key material is not included in the signed message. The verifier must obtain the signer's public key data out-of-band (e.g. by obtaining the signer's certificate from a key server). +3. **Verifying signature packets**: Located at the end of the message, these packets are checked against the previously calculated hash digest. + +Important to note, the signer's public key, critical for the final verification step, is not embedded in the message. Verifiers must acquire this key externally (e.g., from a key server) to authenticate the signature successfully. ### Cleartext signatures From 78c8327733438d3f16bec731a926701dec7be062 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Mon, 13 Nov 2023 22:36:05 +0100 Subject: [PATCH 27/41] edit ch7 cleartext signature --- book/source/07-signing_data.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 618e80f..0c342a5 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -87,14 +87,14 @@ Important to note, the signer's public key, critical for the final verification ### Cleartext signatures -The *Cleartext Signature Framework* (CSF) is an OpenPGP mechanism that combines two goals: +The *Cleartext Signature Framework* (CSF) in OpenPGP accomplishes two primary objectives: -- It leaves the message in clear text format, so that it can be viewed directly by a human in a program that knows nothing about OpenPGP. -- At the same time, it adds an OpenPGP signature that allows verification of that message by users whose software supports OpenPGP. +- maintaining the message in a human-readable cleartext format, accessible without OpenPGP-specific software +- incorporating an OpenPGP signature for authentication by users with OpenPGP-compatible software #### Example -In {numref}`cleartext` we inspect an example of a cleartext signature in detail. Let's have a brief look at this example, here, to get a sense of what a cleartext signature looks like: +Below is a detailed example of a {numref}`cleartext` signature: ```text -----BEGIN PGP SIGNED MESSAGE----- @@ -111,15 +111,11 @@ r13/eqMN8kfCDw== -----END PGP SIGNATURE----- ``` -The cleartext signature consists of two blocks, which contain the message and a signature, respectively. In this case, the message consists of the text "hello world". +This signature is split into two parts: a message ("hello world") and an ASCII-armored OpenPGP signature. The message is immediately comprehensible to a human reader, while the signature block allows for the message's authenticity verification via OpenPGP software. -Notice that this message is readable by a human reader, without requiring additional software tools, as long as the reader understands which elements to ignore. +#### Use case -The message is followed by a block that contains an ASCII-armored OpenPGP signature for the message. Using this signature, OpenPGP software can verify the authenticity of the message in the first block. - -#### Use-case - -One use-case for cleartext signatures is: Asking someone to sign some piece of data. The person who is asked to sign the data can easily inspect it with simple commandline tools, such as `cat`, and verify that they agree with the data they are asked to sign. +A common use case is requesting someone to sign data. The signer can easily inspect the data using simple command line tools (e.g., `cat`) to verify that they agree with the content of the data before deciding to sign it. ```{admonition} TODO :class: warning @@ -139,14 +135,10 @@ explain text transformations for cleartext signatures (LF->CRLF and additional e #### Pitfalls -Cleartext signatures are popular and have useful applications. - -At the same time, they are considered a "legacy method"[^csf-gnupg] by some. +While widely used, cleartext signatures are sometimes considered a "legacy method"[^csf-gnupg]. The RFC outlines [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s) and advises that inline and detached signature forms are often preferable. [^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html -The RFC points out a number of specific [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), and how to avoid them. It advises that in many cases, the inline and detached signature forms are preferable. - ## Advanced topics ### Nesting of one-pass signatures From 94eb58070b4ff18d93ec24ff61361aa88c376827 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 11:33:26 +0100 Subject: [PATCH 28/41] Attempt at clearer description --- book/source/07-signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index cc2a757..1d0bb34 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -15,7 +15,7 @@ it does not automatically signal if the expected party indeed controls the signe Data signatures can only be issued by component keys with the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags). -Note that data signatures are distinct from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate. +Note that data signatures are distinct from {ref}`component_signatures_chapter`, which are used to form and maintain certificates, as well as to certify identities on certificates. (data_signature_types)= ## Signature types From 029e517b84190a4afbf0186230d29b653202d6d4 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 13:20:14 +0100 Subject: [PATCH 29/41] removed "particularly", because for inline signatures, this issue doesn't exist at all. added the "cleartext" case, which is equivalent here. --- book/source/07-signing_data.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 1d0bb34..9b010d2 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -22,8 +22,8 @@ Note that data signatures are distinct from {ref}`component_signatures_chapter`, OpenPGP data signatures use one of two [signature types](signature_types): -- **Binary signature** (type ID `0x00`): This is the standard signature type for binary data and is typically used for files or data streams. Binary signatures are calculated over the data without any modifications or transformations. -- **Text signature** (type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). This mitigates issues caused by platform-specific text encodings, which is particularly important for detached signatures where the message file might be re-encoded between signature creation and verification. +- [**Binary signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-binary) (type ID `0x00`): This is the standard signature type for binary data and is typically used for files or data streams. Binary signatures are calculated over the data without any modifications or transformations. +- [**Text signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-of-a-canonical-te) (type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). This mitigates issues caused by platform-specific text encodings, which is important for detached and cleartext signatures where the message file might be re-encoded between signature creation and verification. Data signatures are generated by hashing the message content along with the metadata in the signature packet, and calculating a cryptographic signature over that hash. The resulting cryptographic signature is stored in an OpenPGP signature packet. From ad7b58ce7192c9a0547cc360717c85cc9f47b2ac Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 13:35:11 +0100 Subject: [PATCH 30/41] clarify/tighten: there is just *one* signature packet in this paragraph. --- book/source/07-signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 9b010d2..712852c 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -25,7 +25,7 @@ OpenPGP data signatures use one of two [signature types](signature_types): - [**Binary signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-binary) (type ID `0x00`): This is the standard signature type for binary data and is typically used for files or data streams. Binary signatures are calculated over the data without any modifications or transformations. - [**Text signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-of-a-canonical-te) (type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). This mitigates issues caused by platform-specific text encodings, which is important for detached and cleartext signatures where the message file might be re-encoded between signature creation and verification. -Data signatures are generated by hashing the message content along with the metadata in the signature packet, and calculating a cryptographic signature over that hash. The resulting cryptographic signature is stored in an OpenPGP signature packet. +Data signatures are generated by hashing the message content along with the metadata in the OpenPGP signature packet, and calculating a cryptographic signature over that hash. The resulting cryptographic signature is stored in the signature packet. Data signature packets manifest in three distinct forms, which will be detailed in the subsequent section. From 1e231b0f4539c6ab789981f9758a83cdf1f7f5d0 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 17:33:46 +0100 Subject: [PATCH 31/41] adjust RFC linking, minor tweaks. I removed the "type IDs" here, because these are *packet type* IDs. The only IDs we're using in the text are *signature types*. I believe signature type IDs are the only IDs that application developers sometimes think about in numerical terms. --- book/source/07-signing_data.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 712852c..b8ce38d 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -55,13 +55,12 @@ This method is commonly used for signing or encrypting emails. Most email softwa An inline-signed OpenPGP message consists of three segments: -1. **One-pass signature packets**: These one or more packets precede the signed data and enable signature computation in one pass. See[One-Pass Signature Packet (Type ID 4)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) of the RFC. +1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more packets precede the signed data and enable signature computation in one pass. -2. **Literal data**: This is the original data (e.g., the body of a message) that the user wishes to encrypt or sign, without additional interpretation or conversion. [Literal Data Packet (Type ID 11)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit). +2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. 3. **Data signature packets**: These contain the cryptographic signature corresponding to the original data. - #### Creation To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into am output OpenPGP message file. As the data is processed, the signer simultaneously calculates a cryptographic signature. This procedure results in a data signature packet being appended to the output OpenPGP message file, an essential step for efficient signing. From 77d056702a63885732d890fa8d6a0572cf8664e8 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 18:10:06 +0100 Subject: [PATCH 32/41] clarity, fix typo, normalize capitalization --- book/source/07-signing_data.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index b8ce38d..6a5458b 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -63,9 +63,9 @@ An inline-signed OpenPGP message consists of three segments: #### Creation -To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into am output OpenPGP message file. As the data is processed, the signer simultaneously calculates a cryptographic signature. This procedure results in a data signature packet being appended to the output OpenPGP message file, an essential step for efficient signing. +To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into an output OpenPGP message file. As the data is processed, the signer simultaneously calculates a cryptographic signature. This procedure results in a data signature packet being appended to the output OpenPGP message file, where it can be efficiently stored. -For efficient verification, an application must understand how to handle the literal data prior to its reading. This requirement is addressed by the One-Pass Signature packets located at the beginning of inline-signed messages. These packets include essential information such as the fingerprint of the signing key and the hash algorithm used for computing the signature's hash digest. This setup enables the verifier to process the data correctly and efficiently. +For efficient verification, an application must understand how to handle the literal data prior to its reading. This requirement is addressed by the one-pass signature packets located at the beginning of inline-signed messages. These packets include essential information such as the fingerprint of the signing key and the hash algorithm used for computing the signature's hash digest. This setup enables the verifier to process the data correctly and efficiently. ```{admonition} TODO :class: warning @@ -77,9 +77,9 @@ Is the signer keyid/fingerprint in the OPS important for the verifier to be able Inline-signed messages enable efficient verification in *one pass*, structured as follows: -1. **Initiation with One-Pass Signature packets**: These packets begin the verification process. They include the signer's key ID/fingerprint, essential for identifying the appropriate public key for signature validation. +1. **Initiation with one-pass signature packets**: These packets begin the verification process. They include the signer's key ID/fingerprint, essential for identifying the appropriate public key for signature validation. -2. **Processing the literal data**: This step involves hashing the literal data, preparing it for signature verification. +2. **Processing the literal data packet**: This step involves hashing the literal data, preparing it for signature verification. 3. **Verifying signature packets**: Located at the end of the message, these packets are checked against the previously calculated hash digest. From 5a454e85e7d0bd4ac801804fcf1ccb492883b0eb Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 19:46:23 +0100 Subject: [PATCH 33/41] extend todo-note --- book/source/07-signing_data.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 6a5458b..787e9fc 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -71,6 +71,8 @@ For efficient verification, an application must understand how to handle the lit :class: warning Is the signer keyid/fingerprint in the OPS important for the verifier to be able to verify the signature efficiently? Or is it (only?) there to be hashed and signed, along with the literal data? + +Realization: It's probably useful to know the fingerprints right away, to first go find the public key material, before calculating the hash of a huge file. ``` #### Verification From d47d9fdd5341303a1269355d1c688af43d34222d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 19:50:13 +0100 Subject: [PATCH 34/41] clarify --- book/source/07-signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 787e9fc..335c7c6 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -113,7 +113,7 @@ r13/eqMN8kfCDw== -----END PGP SIGNATURE----- ``` -This signature is split into two parts: a message ("hello world") and an ASCII-armored OpenPGP signature. The message is immediately comprehensible to a human reader, while the signature block allows for the message's authenticity verification via OpenPGP software. +This signature consists of two parts: a message ("hello world") and an ASCII-armored OpenPGP signature. The message is immediately comprehensible to a human reader, while the signature block allows for the message's authenticity verification via OpenPGP software. #### Use case From c410108a67fca98d68dfd975739b3d80fda2c275 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 22:05:48 +0100 Subject: [PATCH 35/41] ch8: add link anchor --- book/source/08-signing_components.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 8a9f3f1..0b899c8 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -135,6 +135,7 @@ The additional [*primary key binding*](https://www.ietf.org/archive/id/draft-iet The *primary key binding signature* is "embedded" as subpacket data in the *subkey binding signature* which connects the signing subkey to the primary key. +(bind_ident)= ### Binding identities to a certificate Another use-case for a self-signature is to link an identity component (such as a User ID that specifies a name and email address) to a certificate. From 7ed65cc02ce884d6f41ebd23634c1a2389940307 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 16 Nov 2023 09:48:07 +0100 Subject: [PATCH 36/41] make second-pass edits to ch7 --- book/source/07-signing_data.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 335c7c6..495dda4 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -6,7 +6,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (signing_data)= # Signatures over data -In OpenPGP, a *data signature* guarantees the authenticity and, implicitly, the integrity of certain data. Typical use cases include the authentication of software packages and emails. +In OpenPGP, a *data signature* guarantees the authenticity and, implicitly, the integrity of certain data. Typical use cases of data signatures include the authentication of software packages and emails. "Authenticity" in this context means that the data signature was issued by the entity controlling the signing key material. However, it does not automatically signal if the expected party indeed controls the signer certificate. OpenPGP does offer mechanisms for *strong authentication*, connecting certificates to specific identities. This verifies that the intended communication partner is indeed associated with the cryptographic identity behind the signature[^sign-auth]. @@ -23,7 +23,7 @@ Note that data signatures are distinct from {ref}`component_signatures_chapter`, OpenPGP data signatures use one of two [signature types](signature_types): - [**Binary signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-binary) (type ID `0x00`): This is the standard signature type for binary data and is typically used for files or data streams. Binary signatures are calculated over the data without any modifications or transformations. -- [**Text signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-of-a-canonical-te) (type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). This mitigates issues caused by platform-specific text encodings, which is important for detached and cleartext signatures where the message file might be re-encoded between signature creation and verification. +- [**Text signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-of-a-canonical-te) (type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (``). This approach mitigates issues caused by platform-specific text encodings. This is especially important for detached and cleartext signatures, where the message file might undergo re-encoding between the creation and verification of the signature. Data signatures are generated by hashing the message content along with the metadata in the OpenPGP signature packet, and calculating a cryptographic signature over that hash. The resulting cryptographic signature is stored in the signature packet. @@ -33,7 +33,7 @@ Data signature packets manifest in three distinct forms, which will be detailed OpenPGP data signatures can be applied in three distinct forms[^sign-modes-gpg]: -- **Detached**: The OpenPGP signature exists as a separate entity, independent from the signed data. +- **Detached**: The OpenPGP signature exists as a separate entity, independent of the signed data. - **Inline**: Both the original data and its corresponding OpenPGP signature are encapsulated within an OpenPGP container. - **Cleartext signature**: A plaintext message and its OpenPGP signature coexist in a combined text format, preserving the readability of the original message. @@ -63,7 +63,7 @@ An inline-signed OpenPGP message consists of three segments: #### Creation -To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into an output OpenPGP message file. As the data is processed, the signer simultaneously calculates a cryptographic signature. This procedure results in a data signature packet being appended to the output OpenPGP message file, where it can be efficiently stored. +To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into an output OpenPGP message file. As the data is processed, the signer simultaneously calculates a cryptographic signature. This procedure results in the appending of a data signature packet to the output OpenPGP message file, where it can be efficiently stored. For efficient verification, an application must understand how to handle the literal data prior to its reading. This requirement is addressed by the one-pass signature packets located at the beginning of inline-signed messages. These packets include essential information such as the fingerprint of the signing key and the hash algorithm used for computing the signature's hash digest. This setup enables the verifier to process the data correctly and efficiently. @@ -96,7 +96,7 @@ The *Cleartext Signature Framework* (CSF) in OpenPGP accomplishes two primary ob #### Example -Below is a detailed example of a {numref}`cleartext` signature: +The following is a detailed example of a {numref}`cleartext` signature: ```text -----BEGIN PGP SIGNED MESSAGE----- From 2f44224974bb92871191ff7ab0b3bebb28208e72 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 16 Nov 2023 11:14:16 +0100 Subject: [PATCH 37/41] edit ch7 section on use case --- book/source/07-signing_data.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 495dda4..eada683 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -117,14 +117,15 @@ This signature consists of two parts: a message ("hello world") and an ASCII-arm #### Use case -Clear text signatures combine two of the benefits of detached and inline-signatures: +Clear text signatures combine the advantages of both detached and inline signatures: -- They are self-contained, the message and signature can be stored as a single file -- The message remains human-readable, without requiring additional software tooling +- **Self-contained format**: Cleartext signatures enable the message and its signature to be stored as a single file. -This combination can be attractive for processes where signed messages are handled in a partially manual manner, and stored in a system that doesn't have strong support for OpenPGP in that particular workflow[^arch-certifications]. +- **Human readability**: The message within a cleartext signature remains accessible in a plain text format. This eliminates the need for specialized software to read the message content. -[^arch-certifications]: For example, Arch Linux uses a workflow to certify User IDs of new packagers that relies on [cleartext signed statements by established packagers](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/blob/master/.gitlab/issue_templates/New%20Packager%20Key.md?ref_type=heads&plain=1#L33-46). These signed statements are stored in an issue tracker system, as attachments, for later inspection. In this use case, it is convenient that the message and the signature are stored as one combined file (not as separate ones which would be more tedious to handle manually), and that the message is easy to read. Based on the vouches in these cleartext signed messages, and an [email confirmation by the new packager](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/wikis/workflows/verify-a-packager-key), main signing key operators issue OpenPGP third-party certifications. +These features are particularly beneficial in scenarios where signed messages are managed semi-manually and where existing system infrastructure offers limited or no native support for OpenPGP in the workflow[^arch-certifications]. + +[^arch-certifications]: An illustrative example is the workflow adopted by Arch Linux to certify User IDs of new packagers. This process relies on [cleartext signed statements from existing packagers](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/blob/master/.gitlab/issue_templates/New%20Packager%20Key.md?ref_type=heads&plain=1#L33-46). These signed statements are stored as attachments in an issue tracking system for later inspection. The advantage of this approach lies in the convenience of having the message and signature in a single file, which simplifies manual handling. Based on the vouches in these cleartext signed messages and an [email confirmation from the new packager](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/wikis/workflows/verify-a-packager-key), the main key operators can issue OpenPGP third-party certifications. #### Text transformations for cleartext signatures From 58340c97a1e959e638f6a821ea0b985e177b69a1 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 16 Nov 2023 11:57:46 +0100 Subject: [PATCH 38/41] edit ch7 cleartext transformations subsection --- book/source/07-signing_data.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index eada683..53fe87f 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -129,13 +129,15 @@ These features are particularly beneficial in scenarios where signed messages ar #### Text transformations for cleartext signatures -In the cleartext signature framework, the message text is normalized by [escaping dashes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text), to prevent parsing problems where message content and armor headers are confused. +The cleartext signature framework includes specific text normalization procedures to ensure the integrity and clarity of the message: -Additionally, as usual for [text signatures](data_signature_types), the signature is calculated on the text with normalized line endings (``). +_ **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the signature's structure, and any lines in the message that happen to start with a dash. + +- **Normalization of line endings**: Consistent with the approach for binary [text signatures](data_signature_types), the cleartext signature is calculated on the text with normalized line endings (``). This ensures that the signature remains valid regardless of the text format of the receiving implementation. #### Pitfalls -While widely used, cleartext signatures are sometimes considered a "legacy method"[^csf-gnupg]. The RFC outlines [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s) and advises that inline and detached signature forms are often preferable. +While widely used, cleartext signatures are sometimes viewed as a "legacy method"[^csf-gnupg]. The RFC outlines [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s) and advises that inline and detached signature forms are often preferable. [^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html From 32b5e0cfe0939c82d0d9087d742a82939d3d80d4 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 19:11:59 +0100 Subject: [PATCH 39/41] Align wording with https://gitlab.com/openpgp-wg/rfc4880bis/-/merge_requests/354/diffs --- book/source/07-signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 53fe87f..4d373d5 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -133,7 +133,7 @@ The cleartext signature framework includes specific text normalization procedure _ **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the signature's structure, and any lines in the message that happen to start with a dash. -- **Normalization of line endings**: Consistent with the approach for binary [text signatures](data_signature_types), the cleartext signature is calculated on the text with normalized line endings (``). This ensures that the signature remains valid regardless of the text format of the receiving implementation. +- **Normalization of line endings**: Consistent with the approach for any other [text signature](data_signature_types), a cleartext signature is calculated on the text with normalized line endings (``). This ensures that the signature remains valid regardless of the text format of the receiving implementation. #### Pitfalls From 1b1e918a0190e23acdec0bd94949b91dd68e5d3a Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 16 Nov 2023 15:16:05 +0100 Subject: [PATCH 40/41] add detail to ch7 pitfalls section of cleartext signatures --- book/source/07-signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 4d373d5..5163be4 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -137,7 +137,7 @@ _ **Escaping dashes**: The framework implements a method of [dash-escaped text]( #### Pitfalls -While widely used, cleartext signatures are sometimes viewed as a "legacy method"[^csf-gnupg]. The RFC outlines [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s) and advises that inline and detached signature forms are often preferable. +Despite their widespread adoption, cleartext signatures have their limitations and are sometimes viewed as a "legacy method"[^csf-gnupg]. The RFC details the [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), such as incompatibility with semantically meaningful whitespace, challenges with large messages, and security vulnerabilities related to misleading Hash header manipulations. Given these issues, safer alternatives like inline and detached signature forms are advised. [^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html From 4277942114343207502fd424cbb6120bd740f3f6 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 16 Nov 2023 17:31:16 +0100 Subject: [PATCH 41/41] ch8: typo fix --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 0b899c8..e3d0ace 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -271,7 +271,7 @@ A trust amount of 120 indicates "complete trust," which means that a certificati If Alice designates Trent as a trusted introducer at a trust amount of 120, then Alice's OpenPGP software will consider Bob's identity fully authenticated if Trent has certified it. -However, if Alice only assigns a trust amount of 60 (which indicates "partial trust") to Trent, then her software would not consider Bob's identity fully authenticated. Now let's imagine that Alice additionall assigns a trust amount of 60 to Tristan (a second, independent introducer), and Tristan also certified Bob's identity. In this case, Alice's OpenPGP software will consider Bob's identity fully authenticated, based on the combination of both delegations, and the certifications the two trusted introducers issued. +However, if Alice only assigns a trust amount of 60 (which indicates "partial trust") to Trent, then her software would not consider Bob's identity fully authenticated. Now let's imagine that Alice additionally assigns a trust amount of 60 to Tristan (a second, independent introducer), and Tristan also certified Bob's identity. In this case, Alice's OpenPGP software will consider Bob's identity fully authenticated, based on the combination of both delegations, and the certifications the two trusted introducers issued. ```{admonition} VISUAL :class: warning