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

Merge branch 'draft' into tammi-heiko-ch7

Browse source
This commit is contained in:
heiko 2023-11-16 16:25:43 +00:00
commit a02c7562f0
3 changed files with 181 additions and 80 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -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 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. - 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)=
## Identity components ## Identity components
@ -165,9 +170,9 @@ Heiko, please clarify what the value is of this proposal or remove it.
``` ```
(primary_user_id)= (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. 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.

250
book/source/08-signing_components.md
View file

@ -6,70 +6,87 @@ SPDX-License-Identifier: CC-BY-SA-4.0
(component_signatures_chapter)= (component_signatures_chapter)=
# Signatures on components # 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 - Component keys (primary keys or subkeys) and
- Identity components (User IDs or User attributes). - 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} ```{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. 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: 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 - Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a 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*). - third-party signatures of the same type IDs indicate that the signer endorses the authenticity of a User ID.
Or: Or:
- Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a certificate, while - 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
- 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 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). [^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. 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} ```{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. - 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). [^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)= (bind_subkey)=
### Binding subkeys to a certificate ### 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 ```{figure} diag/subkey_binding_signature.png
Linking an OpenPGP subkey to the primary key with a binding signature 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} ```{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. 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,62 +118,83 @@ A subkey cannot be "older" than the primary key. The value of the subkeys creati
(bind_subkey_sign)= (bind_subkey_sign)=
### Special case: Binding signing subkeys to a certificate ### 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. 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. 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 ```{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 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.
(bind_ident)=
### Binding identities to a certificate ### 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. 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 <alice@example.org>` may be associated with Alice's certificate `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. For example, the User ID `Alice Adams <alice@example.org>` 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 ```{figure} diag/user_id_certification.png
---
---
Linking a User ID to an OpenPGP certificate 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
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)=
### Direct key signature: Adding metadata to the primary key #### Direct key signature
```{admonition} TODO 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.
:class: warning
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).
```
### Revocations: Invalidating components of a certificate #### 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.
### Revocation self-signatures: Invalidating components of a certificate
One important class of self-signatures are revocations. One important class of self-signatures are revocations.
A revocation signature is used to retract the statement formed by a prior signature. A revocation signature is used to invalidate a component, or 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. - 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.
```{note} ```{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. 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.
@ -168,38 +206,106 @@ Note: certification signatures [can be made irrevocable](https://www.ietf.org/ar
#### Hard vs. soft revocations #### 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* 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 soft revocation invalidates the target certificate beginning with the revocations creation time. - 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} ```{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)= (third_party_cert)=
## Third-party certifications: Making statements about other people's certificates and identities ## Third-party signatures: Authentication statements
```{admonition} TODO 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 <bob@example.com>` 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 <bob@example.com>` 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.
[*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")
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 <bob@example.org>`. If Alice tries to communicate with Bob using his identity `Bob <bob@example.org>`, 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 :class: warning
write add diagrams?
``` ```
### Certifying identities #### Trust amount
Certifications over User IDs can also be used to certify certificates of third-parties. 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.
If Alice is certain that `Bob Baker <bob@example.com>` 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. 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.
### Delegating authentication: trust signatures **Examples**
### Revocations: Undoing previous statements 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
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.
**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"
The OpenPGP, the "Web of Trust" is a trust model that performs authentication decisions on a set of certifications and delegations.
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
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 ## Advanced topics
@ -343,13 +449,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 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. 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. 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
```

2
book/source/21-resources.md
View file

@ -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 [RFC4880](https://www.rfc-editor.org/rfc/rfc4880.html) OpenPGP Message Format [2007], specifies OpenPGP version 4
(wot-resources)=
## Web of Trust ## 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/), [PGP Web of Trust: Core Concepts Behind Trusted Communication](https://www.linux.com/training-tutorials/pgp-web-trust-core-concepts-behind-trusted-communication/),