docs: Update message key forwarding algorithm model.

- Change incorrect "key sharing" references to "key forwarding".
- Explain that this is a feature that needs to be enabled.
- Regenerate the key forwarding algorithm diagram.
- Provide a spec link and mention alternative names.

contrib/key-sharing-algorithm/README.md → contrib/key-forwarding-algorithm/README.md

@@ -1,4 +1,4 @@
-This models the room key sharing algorithm as a decision tree and provides
+This models the room key forwarding algorithm as a decision tree and provides
 tooling to render it as a PDF or PNG.
 
 # Usage

contrib/key-sharing-algorithm/model.dot → contrib/key-forwarding-algorithm/model.dot

@@ -1,5 +1,5 @@
 digraph {
-    label="Matrix room key sharing algorithm"
+    label="Matrix room key forwarding algorithm"
     fontname="Fira Sans"
     ratio=0.5
 
@@ -16,10 +16,10 @@ digraph {
     /* End states */
     allow_verified [label="Share the entire session from the earliest known index.\n\nOk(None)", color=4, fillcolor=3]
     allow_limited [label="Share a limited session starting from index i, which is the index we previously shared at.\n\nOk(Some(i))", color=4, fillcolor=3]
-    refuse_device_key_changed [label="Sender key changed, refuse to share.\n\nErr(KeyForwardDecision::ChangedSenderKey)", color=6, fillcolor=5]
-    refuse_not_shared [label="Session was never shared with this device, refuse to share.\n\nErr(KeyForwardDecision::OutboundSessionNotShared)", color=6, fillcolor=5]
-    refuse_untrusted_own_device [label="Our own device, but it is untrusted and we haven't previously shared with it. Refuse to share.\n\nErr(KeyForwardDecision::UntrustedDevice)", color=6, fillcolor=5]
-    refuse_missing_outbound_session [label="Not our device and haven't previously shared with it. Refuse to share.\n\nErr(KeyForwardDecision::MissingOutboundSession)", color=6, fillcolor=5]
+    refuse_device_key_changed [label="Sender key changed, refuse to forward.\n\nErr(KeyForwardDecision::ChangedSenderKey)", color=6, fillcolor=5]
+    refuse_not_shared [label="Session was never shared with this device, refuse to forward.\n\nErr(KeyForwardDecision::OutboundSessionNotShared)", color=6, fillcolor=5]
+    refuse_untrusted_own_device [label="Our own device, but it is untrusted and we haven't previously shared with it. Refuse to forward.\n\nErr(KeyForwardDecision::UntrustedDevice)", color=6, fillcolor=5]
+    refuse_missing_outbound_session [label="Not our device and haven't previously shared with it. Refuse to forward.\n\nErr(KeyForwardDecision::MissingOutboundSession)", color=6, fillcolor=5]
 
     /* Checks */
 

crates/matrix-sdk-crypto/README.md

@@ -56,10 +56,14 @@ async fn main() -> Result<(), OlmError> {
 [Matrix]: https://matrix.org/
 [matrix-sdk]: https://github.com/matrix-org/matrix-rust-sdk/
 
-# Room key sharing algorithm
+# Room key forwarding algorithm
 
-The decision tree below visualizes the way this crate decides whether a room
-key will be shared with a requester upon a key request.
+The decision tree below visualizes the way this crate decides whether a message
+key ("room key") will be [forwarded][forwarded_room_key] to a requester upon a
+key request, provided the `automatic-room-key-forwarding` feature is enabled.
+Key forwarding is sometimes also referred to as key *gossiping*.
+
+[forwarded_room_key]: <https://spec.matrix.org/v1.10/client-server-api/#mforwarded_room_key>
 
 ![](https://raw.githubusercontent.com/matrix-org/matrix-rust-sdk/main/contrib/key-sharing-algorithm/model.png)