Add / revoke subkeys

book/source/06-certifications.md

@@ -162,6 +162,11 @@ This signature should have the following structure:
 | Symm. Alg. Pref. | Hashed | False | False | New preferences |
 | AEAD Alg. Pref. | Hashed | False | False | New preferences |
 
+#### Change Expiration Time
+The recommended way to change the expiration time of a certificate is by issuing a new `DirectKey` signature (type 0x1F) with an adjusted Key Expiration Time subpacket.
+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.
 The signature should have the following structure:
@@ -196,11 +201,50 @@ 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.
 
+#### 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:
+
+| Subpacket | Area | Critical | Mandatory | Notes |
+|-----------|------|----------|-----------|-------|
+| Signature Creation Time | Hashed | True | True | Current time |
+| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer |
+| Key Flags | Hashed | True | Strongly Recommended | Determine the usage of the key |
+| Key Expiration Time | Hashed | True | False | Specifies the expiration date of the subkey |
+| Embedded Signature | Hashed | True | If Key Flags contains **S** | Signing subkeys require embedded `PrimaryKeyBinding` signature |
+| Hash Alg. Pref. | Hashed | False | False | Per key preferences |
+| Comp. Alg. Pref. | Hashed | False | False | Per key preferences |
+| Symm. Alg. Pref. | Hashed | False | False | Per key preferences |
+| AEAD Alg. Pref. | Hashed | False | False | Per key preferences |
+
+Optional algorithm preference subpackets can be used to signal per-subkey preferences that deviate from those set in the certificates `DirectKey` signature.
+
+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.
+Contrary to the `SubkeyBinding` signature, which is issued by the certificates primary key, the `PrimaryKeyBinding` signature is instead created by the subkey.
+
+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
+Analogous to User IDs, subkeys can be revoked individually.
+This is done by issuing a `SubkeyRevocation` signature (type 0x28) using the primary key.
+The structure of such a signature is rather minimal:
+
+| Subpacket | Area | Critical | Mandatory | Notes |
+|-----------|------|----------|-----------|-------|
+| Signature Creation Time | Hashed | True | True | Current time |
+| 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`.
+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.
 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 key revocation signature (type 0x20).
+The recommended way to revoke a certificate is by issuing a `KeyRevocation` signature (type 0x20).
 The structure of a key revocation signature is similar to that of a `CertificationRevocation` signature.
 
 | Subpacket | Area | Critical | Mandatory | Notes |
@@ -209,8 +253,7 @@ 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 |
 
-One difference is, that the reason subpacket cannot have value `32`, but instead may be from the range of `0-3`.
+For `KeyRevocation` signatures, the same constraints as for `SubkeyRevocation` signatures apply to the reason subpacket.
-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.
 
 #### Common Subpackets