ch6: write "Choosing the hash algorithm"

book/source/06-signatures.md

@@ -160,13 +160,32 @@ For specific guidelines on which {term}`subpackets<OpenPGP Signature Subpacket>`
 
 {term}`Notations<Notation>`, as described earlier, allow for user-defined extensions to the {term}`OpenPGP signature subpacket types<OpenPGP Signature Subpacket Type>`. A practical and popular application of this functionality is seen in Keyoxide, a decentralized {term}`identity verification` service. Keyoxide uses {term}`notations<Notation>` in the `ariadne.id` namespace. For the details of this {term}`implementation<OpenPGP Implementation>`, refer to the [Keyoxide documentation](https://docs.keyoxide.org/wiki/ariadne-identity/).
 
-### "Negotiating" signature hash algorithm based on recipients preference subpackets
+### Choosing the hash algorithm for a signature
 
-```{admonition} TODO
-:class: warning
+A central element of signature packets is the hash digest of the input data. Most OpenPGP software supports a set of different hash mechanisms, of which one is chosen for each signature packet (this is one aspect of OpenPGP's *cryptographic agility*), and used to calculate the hash digest.
 
-investigate, discuss: GnuPG uses preference packets for the User ID that was addressed while sequoia completely omits User ID preferences and either uses Direct Key Sigs or (I think) primary User ID.
-```
+Different hash mechanisms offer different trade-offs:
+
+- *Hash digest size*: Larger hash size tends to correspond with greater strength against cryptanalysis, and hash digests are relatively small: at the time of this writing, typical sizes are 32 to 64 bytes. However, for some use cases - especially where small messages are sent over a bandwidth-limited transport - larger hash sizes may unacceptably increase message size.  
+- *Computational cost*: Different hash algorithms may have different computational costs. Some OpenPGP users may prefer to limit this cost, for example on constrained computing environments.
+
+The following sections discuss how the hash algorithm is chosen, based on preferences that are associated with the involved OpenPGP certificates.
+
+#### Typically: Local determination
+
+Often, signature creation isn't targeted at a specific receiver. Many signatures are issued for an indeterminate set of "anyone who receives the signature."
+
+For example, self-signatures that form a certificate are aimed at everyone who interacts with that certificate. Similarly, when creating a data signature for a software package, this signature is aimed at "anyone who will check the signature," often over a long period of time, easily spanning years.
+
+In such cases, the issuer of that signature chooses the hash algorithm locally, without following preferences of a third party.
+
+#### With a specific recipient: "Negotiation" based on recipient's preferences
+
+In contrast, when a message is created for a specific recipient, the sender can - and should - choose the hash algorithm for the signature packet [based on the recipient's hash algorithm preference](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hash-algorithm-preferences).
+
+The recipient's hash algorithm preference is defined in metadata of their certificate, see {ref}`algo-pref` for more details.
+
+In this workflow, the signed hash digest is created with a hash algorithm that follows the recipient's preferences, and its intersection with the sender's capabilities and preferences. 
 
 ### Explore viability of having multiple signatures, e.g. v4+v6?