diff --git a/book/source/adv/certificates.md b/book/source/adv/certificates.md index d0b7367..06a9f51 100644 --- a/book/source/adv/certificates.md +++ b/book/source/adv/certificates.md @@ -108,6 +108,7 @@ As a general tendency, it is desirable for OpenPGP users to have the most comple However, there are contexts in which it is preferable to only use a subset of the available elements of a certificate. We discuss this in the section {ref}`cert-mini`. +(certificate-merging)= ## Merging As described above, OpenPGP certificates are effectively [append-only](append-only) data structures. As part of the practical realization of this fact, OpenPGP software needs to *merge* different copies of a certificate. diff --git a/book/source/adv/decryption.md b/book/source/adv/decryption.md index de2fccb..7811240 100644 --- a/book/source/adv/decryption.md +++ b/book/source/adv/decryption.md @@ -27,9 +27,3 @@ This is done by creating a normal PKESK packet for the recipient, but setting th A recipient of such a message that does not find a PKESK addressed specifically to any of their keys, can then try to decrypt any anonymous PKESK packets using any of their encryption subkeys. To reduce the number of keys to try, the recipient can skip all secret keys which do not share the public-key algorithm stated in the PKESK packet. - -```{admonition} TODO -:class: warning - -When did the decryption succeed? Describe quick check of the check sum and decryption of first few bytes of the SEIPD as test strategies. -``` diff --git a/book/source/adv/encryption.md b/book/source/adv/encryption.md index 6b0c249..b2b5631 100644 --- a/book/source/adv/encryption.md +++ b/book/source/adv/encryption.md @@ -26,8 +26,7 @@ If the lowest common denominator of symmetric encryption algorithms preferred by ## AEAD modes in v2 SEIPD: GCM -```{admonition} TODO -:class: warning +```{note} -Produce text around discussion: https://mailarchive.ietf.org/arch/msg/openpgp/ZTYD5VJsG1k2jJBbn5zIAf5o7d4/ +This section is still about to be written. ``` diff --git a/book/source/adv/signing_components.md b/book/source/adv/signing_components.md index e76cd28..721dc85 100644 --- a/book/source/adv/signing_components.md +++ b/book/source/adv/signing_components.md @@ -49,13 +49,7 @@ In addition to these {term}`subpackets`, {term}`sel ### Remove or revoke a User ID -Since {term}`OpenPGP certificates` are often distributed by the means of {term}`key servers`, new {term}`signatures` on a {term}`certificate` are often "merged" into existing copies of the {term}`certificate` locally by the recipient. - -```{admonition} TODO -:class: warning - -Link to the "Merging" section in chapter 4, once merged. -``` +Since {term}`OpenPGP certificates` are often distributed by the means of {term}`key servers`, new {term}`signatures` on a {term}`certificate` are often "[merged](certificate-merging)" into existing copies of the {term}`certificate` locally by the recipient. This integration process means it is practically impossible to directly remove {term}`signatures` or {term}`User IDs` from a {term}`certificate`, as there is no way to communicate the intention of {term}`packet` deletion to the recipient. @@ -110,12 +104,6 @@ In {term}`Subkey Revocation signatures`, the Note that a value of `32` is not applicable in these {term}`signatures`. -```{admonition} TODO -:class: warning - -Research and explain hardness in the context of subkey revocations. What does a hard subkey revocation express concretely? -``` - ### Revoke a certificate Users may find themselves needing to revoke their entire {term}`OpenPGP certificate`, rendering it unusable. This could be for various reasons, such as migrating to a new {term}`certificate` or in response to a compromise of the {term}`certificate`'s {term}`secret key material`. diff --git a/book/source/adv/verification.md b/book/source/adv/verification.md index 1ac8331..dc21217 100644 --- a/book/source/adv/verification.md +++ b/book/source/adv/verification.md @@ -80,12 +80,6 @@ Alternatively, there can be competing qualifying signatures of different types, Depending on how a certificate is "located," different metadata from possible candidate signatures "shadow" one another. The RFC [states](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-self-signatures) that when a certificate is "located" by the OpenPGP software "via an identity", then the metadata associated with that identity takes precedence over more global metadata, such as that associated with the certificate's primary key, with a direct key signature. -```{admonition} TODO -:class: warning - -Replace hash algorithm preferences with AEAD preferences for a more realistic example. -``` - For example, the latest direct key signature could list "SHA512, SHA384" as hash algorithm preferences, while the latest self-certification of the User ID "Bob" could list only "SHA256." For yet another User ID "Bobby," the self-signature could list no hash algorithm preferences at all. If the user wants to compose a signed message using the associated OpenPGP key they need to figure out which preferences to use. @@ -106,22 +100,10 @@ To complicate things further: Algorithm preferences can also be stated on subkey binding signatures, so if the certificate has a dedicated signing subkey, there is yet another signature which could take precedence. Preferences from the subkey binding signature take precedence over the direct key signature, but not over self-certifications on the User ID. -```{admonition} TODO -:class: warning - -Have a table that lists which signatures take precedence in which cases. -``` - There can be more than one signature on a component. As an example, there are 3 direct key signatures (e.g., because the key's expiry has been extended two times). In general, for each component, only the newest self-signature is "in effect," and older signatures are "shadowed." For each certificate, there is at most one "active" direct key signature, for each User ID at most one active self-certification and for each subkey exactly one subkey binding. -```{admonition} TODO -:class: warning - -direct key signatures can be revoked, [canceling them](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-4), meaning an older direct-key signature might become active again? The text of the spec is confusing here. -``` - ## Complexity of the packet format OpenPGP certificates can contain complex preference settings. Additionally, the OpenPGP packet format allows a lot of flexibility when storing certificates in TPK format. diff --git a/book/source/compression.md b/book/source/compression.md index b7822d6..a7b70b0 100644 --- a/book/source/compression.md +++ b/book/source/compression.md @@ -23,11 +23,3 @@ The series of OpenPGP packets inside the Compressed Data packet can be handled l ## Typical usage Compressed data packets are often used inside [encrypted data packets](/encryption), or wrapping the data of an [inline-signed message](inline-signature). - ---- - -```{admonition} TODO -:class: warning - -link to a packet dump example that shows compression -``` diff --git a/book/source/decryption.md b/book/source/decryption.md index 7286c31..bc0e6f1 100644 --- a/book/source/decryption.md +++ b/book/source/decryption.md @@ -21,15 +21,6 @@ If no suitable PKESK packets were found, SKESK packets are tried next, meaning t Once any of these methods succeeded, the resulting *session key* is used to decrypt the SEIPD packet. -```{admonition} TODO -:class: warning - - - using expired certificate? - - using revoked certificate? - - using expired subkey? - - using revoked subkey? -``` - ## Passphrase-protected session key (SKESK) Decrypting a SKESK packet to recover the *session key* is done by performing the encryption steps in reverse, based on a user-provided passphrase. @@ -137,12 +128,6 @@ The cipher algorithm is either extracted from the decrypted session key (the alg Once the cipher is initialized, the whole encrypted data from the SEIPD packet is decrypted. -```{admonition} TODO -:class: warning - -Describe the MDC which is used for modification detection. -``` - ```{figure} plain_svg/SEIPDv1-decryption.svg :name: fig-decryption-seipd1 :alt: Depicts how the session key is used directly to decrypt the contents of the SEIPD packet. diff --git a/book/source/encryption.md b/book/source/encryption.md index 2bbdba6..fc982ce 100644 --- a/book/source/encryption.md +++ b/book/source/encryption.md @@ -84,12 +84,6 @@ Also see https://flowcrypt.com/docs/guide/send-and-receive/send-password-protect As for protection of secret key material, it is important to choose appropriate S2K parameters when generating an SKESK packet. The specification currently recommends to use either *Iterated and Salted S2K* or *Argon2*. -```{admonition} TODO: -:class: warning - -Add further guidance for recommended S2K parameters, like iteration count or Argon2 configuration. Perhaps in a dedicated "S2K Parameters" section, which can be reused for the encryption chapter and when we talk about secret key encryption in TSKs. -``` - ## Symmetric encryption of data, SEIPD *Symmetrically Encrypted Integrity Protected Data* (SEIPD) packets represent the symmetric aspect of OpenPGP's encryption mechanism. The function of these packets is entirely independent of (asymmetric) OpenPGP keys. @@ -144,11 +138,3 @@ With SEIPDv2, the message key is derived from the session key in an extra step. ``` This additional step introduces key-separation into the protocol, which protects against certain attacks, such as an [OpenPGP SEIP downgrade attack](https://www.metzdowd.com/pipermail/cryptography/2015-October/026685.html). - -```{admonition} TODO -:class: warning - -Explain, that with SEIPDv2, a session key can essentially protect more than one message by reusing the same session key and *ESK packets with a fresh, per-message salt. - -This might very well go into the advanced topics section though. -``` diff --git a/book/source/policy.md b/book/source/policy.md index 0bc613d..7ac4cca 100644 --- a/book/source/policy.md +++ b/book/source/policy.md @@ -5,10 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 # Algorithms and Policy -```{admonition} TODO -:class: warning +```{note} - - What algorithms are trustworthy? -> Depend on regulatory bodies like the BSI? - - How to decide, when to deprecate / reject algorithms (how to be competent) - - Transitioning from one set of algorithms to another (Interoperability) -``` \ No newline at end of file +This section is still about to be written. +``` diff --git a/book/source/signing_components.md b/book/source/signing_components.md index 439b83b..c3b1611 100644 --- a/book/source/signing_components.md +++ b/book/source/signing_components.md @@ -201,12 +201,6 @@ Common scenarios for using {term}`revocations` include marking {term {term}`Revocations` are used to mark {term}`components` or {term}`signatures` as {term}`invalid`. ``` -```{admonition} TODO -:class: warning - -Research, under what circumstances revocations revoke individual signatures, and when they instead "unbind" components. -``` - Note: {term}`certification signatures` [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-revocable). (hard-vs-soft-revocations)= diff --git a/book/source/verification.md b/book/source/verification.md index 0eb4328..b8159cb 100644 --- a/book/source/verification.md +++ b/book/source/verification.md @@ -115,9 +115,3 @@ A signature can be *disqualified* by the presence of a revocation signature. Revocations can be limited in scope, e.g., a subkey-revocation signature only revokes a single subkey. Moreover, revocations can also be constrained to a certain validity period by including a soft revocation reason and expiration time in the revocation signature. - -```{admonition} TODO -:class: warning - -Give guidance which revocations need to be considered for different types of signatures -``` diff --git a/book/source/versions.md b/book/source/versions.md index ff7d46f..e78b80b 100644 --- a/book/source/versions.md +++ b/book/source/versions.md @@ -7,9 +7,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 ## Differences between OpenPGP versions -```{admonition} TODO -:class: warning +```{note} -write about the delta between v4 and v6, most of all -- a starting point? https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-upgrade-guidance-adapting-i +This section is still about to be written. ``` diff --git a/book/source/zoom/certificates.md b/book/source/zoom/certificates.md index 7f01a40..9fa6da8 100644 --- a/book/source/zoom/certificates.md +++ b/book/source/zoom/certificates.md @@ -83,16 +83,6 @@ This is the shape of the packets we'll explore in the subsequent sections: A minimal OpenPGP certificate, visualized ``` -```{admonition} VISUAL -:class: warning - -This diagram needs adjustments about - - what exactly is signed - - fix naming of fields? - -We could show repeat-copies of the individual packet visualization again, below for each packet-related section. -``` - In real-world scenarios, OpenPGP certificates are typically far more complex than this minimal example. However, this is indeed a valid OpenPGP certificate. In the following sections, we will introduce more components to this certificate, increasing its complexity and exploring their details. In ASCII-armored representation, this very minimal key appears as follows: @@ -431,22 +421,6 @@ The aforementioned subkey packet is disconnected from the OpenPGP certificate to The type of signature is called a *subkey binding signature*, because it "binds" or connects the subkey to the rest of the key. -```{admonition} VISUAL -:class: warning - -Add detailed packet diagram analogous to 4.6.1 -``` - -```{admonition} TODO -:class: warning - -david points out: "The information on metadata in binding signatures may also make sense in other contexts (direct key signature)?" - -Should this text go elsewhere? -- 4.2.3? -- ch 6? -``` - The signature does more than just bind the subkey; it also carries additional metadata about the subkey. This metadata is in the binding signature, and not in the subkey packet, because it may change over time, while the subkey packet itself remains unchanged. This evolving metadata is stored in self-signatures: if the key holder wants to modify the metadata (for example, to change the key's expiration time), a newer version of the same signature type can be issued. The recipient OpenPGP software will recognize that the newer self-signature supersedes the older one, and that the metadata in the newer signature reflects the most current intent of the key holder. Note that this subkey binding signature packet is quite similar to the Direct Key Signature discussed above. Both signatures serve a similar purpose in adding metadata to a component key, particularly as the hashed subpacket data contains much of the same metadata elements. @@ -536,10 +510,9 @@ Refer to [Computing Signatures](https://www.ietf.org/archive/id/draft-ietf-openp ## Signing subkey -```{admonition} TODO -:class: warning +```{note} -write +This section is still about to be written. ``` ```text @@ -782,14 +755,6 @@ Historically, the self-signature that binds the primary User ID to the certifica Setting key expiration time and key flags on the primary User ID self-signature is one mechanism to configure the primary key. The interaction between metadata on direct key signatures and User ID binding self-signatures [is subtle](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-self-signatures), with changes between version 6 and version 4. - - -```{admonition} TODO -:class: warning - -- link to a section that goes into more depth about "#name-notes-on-self-signatures"? -``` - ```` This section is followed, again, by the (informational) unhashed subpacket area. @@ -807,4 +772,14 @@ Refer to [Computing Signatures](https://www.ietf.org/archive/id/draft-ietf-openp ## Certifications (Third Party Signatures) +```{note} + +This section is still about to be written. +``` + ## Revocations + +```{note} + +This section is still about to be written. +``` diff --git a/book/source/zoom/private_keys.md b/book/source/zoom/private_keys.md index 9eeafbb..5973a9d 100644 --- a/book/source/zoom/private_keys.md +++ b/book/source/zoom/private_keys.md @@ -189,15 +189,4 @@ The next fields are [specific to Argon2](https://www.ietf.org/archive/id/draft-i - `argon2_p`: "degree of parallelism p" - `argon2_m`: "the exponent of the memory size" -```{admonition} TODO -:class: warning - -Where is that IV: - -["If string-to-key usage octet was 253 (AEAD), an initialization vector (IV) of size specified by the AEAD algorithm (see Section 5.13.2), which is used as the nonce for the AEAD algorithm"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.5.3-3.4.2.5) - -Is the example key wrong?! -``` - - "Plain or encrypted multiprecision integers comprising the secret key data. This is algorithm-specific and described in Section 5.5.5. If the string-to-key usage octet is 253 (AEAD), then an AEAD authentication tag is at the end of that data."