diff --git a/book/source/06-certifications.md b/book/source/06-certifications.md index 67763dc..d68bc9b 100644 --- a/book/source/06-certifications.md +++ b/book/source/06-certifications.md @@ -12,6 +12,28 @@ They act as the syntax that allows forming and interpreting complex statements a Without signatures there would only be loose keys, impossible to associate with their owner. Signatures are the glue that allows for keys, subkeys and identities to be assembled into hierarchical certificates and for messages to gain authenticity. +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. + +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. + +[^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. + +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, 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): + +- [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]), +- 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). + + ```{admonition} :class: warning @@ -107,72 +129,6 @@ By marking the expiration date subpacket as critical, the user can indicate, tha Sections 5.2.3.11 - 5.2.3.36 give guidance on which subpackets are usually marked as critical. -### Linking the components of an OpenPGP 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. - -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. - -[^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. - -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, 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): - -- [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]), -- 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). - -(binding_subkeys)= -#### Binding subkeys to an OpenPGP certificate - -Linking a subkey to an OpenPGP certificate is done with a ["Subkey Binding Signature"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding). Such a signature signals that the "primary key wants to be associated with the subkey". - -The subkey binding signature also adds metadata. - -```{figure} diag/subkey_binding.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). - -##### Binding signing subkeys to an OpenPGP certificate - -Binding subkeys with the "signing" key flag is a special case: - -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. - -```{figure} diag/subkey_binding_backsig.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). - - -#### Binding identities with certifying self-signatures - -"User ID" identity 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. - -```{figure} diag/user_id_certification.png ---- ---- -Linking a User ID to an OpenPGP certificate -``` (direct_key_signature)= #### Direct key signature @@ -222,7 +178,20 @@ The structure of such a signature is the same as in the section above. It is also possible to change the expiration date of individual User IDs (see section below) or separate subkeys (see [section X](#add_subkey)). #### Add User ID -To add (or re-bind) a User ID to a certificate, a signature of type `PositiveCertification` (0x13) is calculated over the primary key and User ID. + +"User ID" identity 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. + +```{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. The signature should have the following structure: | Subpacket | Area | Critical | Mandatory | Notes | @@ -255,9 +224,22 @@ The latter would result in a soft revocation, while a reason code of `0` is cons 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. +(binding_subkeys)= #### Add a Subkey For the purpose of key freshness, a user might want to add a new subkey to their certificate. -This can be accomplished by issuing a `SubkeyBinding` signature (type 0x18). The structure is as follows: + +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". + +The subkey binding signature also adds metadata. + +```{figure} diag/subkey_binding.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). + + The structure is as follows: | Subpacket | Area | Critical | Mandatory | Notes | |-----------|------|----------|-----------|-------| @@ -275,9 +257,21 @@ Optional algorithm preference subpackets can be used to signal per-subkey prefer 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. -If the subkey is intended to be used as a signing key (that is if the Key Flags subpacket contains the **S**ign Data flag), it is required to also include an embedded `PrimaryKeyBinding` "back signature" (type 0x19). 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. +Binding subkeys with the "signing" key flag is a special case: + +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 certificates primary key, the `PrimaryKeyBinding` signature is instead created by the subkey. +```{figure} diag/subkey_binding_backsig.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). + 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. #### Revoke a Subkey