feat(crypto): Supports new UtdCause variants for withheld keys

Adds new UtdCause variants for withheld keys, enabling applications to display customized messages when an Unable-To-Decrypt message is expected.

crates/matrix-sdk-base/src/sliding_sync/mod.rs

@@ -2656,7 +2656,7 @@ mod tests {
             .unwrap(),
             UnableToDecryptInfo {
                 session_id: Some("".to_owned()),
-                reason: UnableToDecryptReason::MissingMegolmSession,
+                reason: UnableToDecryptReason::MissingMegolmSession(None),
             },
         )
     }

crates/matrix-sdk-common/src/deserialized_responses.rs

@@ -669,6 +669,23 @@ fn unknown_utd_reason() -> UnableToDecryptReason {
     UnableToDecryptReason::Unknown
 }
 
+/// A room key might be missing because the sender refused to share it or was
+/// not technically able to share it.
+/// In the protocol this is reflected by clients sending `m.room_key.withheld`
+/// to the participant that won't receive the key.
+/// We only want here to consider the subset of codes that clients should
+/// use to display specific UX.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+pub enum WithheldReason {
+    /// When the sender refuses to send the key because his security settings in
+    /// that room are not met by your device. Could be that your device is
+    /// not cross-signed (insecure device) or that you are not verified by
+    /// the sender.
+    TrustRequirementMismatch,
+    /// Other reasons. Like fail to establish a secure channel to share the key,
+    /// or if for some reason our device is blocked.
+    Other,
+}
 /// Reason code for a decryption failure
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub enum UnableToDecryptReason {
@@ -684,9 +701,7 @@ pub enum UnableToDecryptReason {
 
     /// Decryption failed because we're missing the megolm session that was used
     /// to encrypt the event.
-    ///
-    /// TODO: support withheld codes?
-    MissingMegolmSession,
+    MissingMegolmSession(Option<WithheldReason>),
 
     /// Decryption failed because, while we have the megolm session that was
     /// used to encrypt the message, it is ratcheted too far forward.
@@ -718,7 +733,12 @@ impl UnableToDecryptReason {
     /// Returns true if this UTD is due to a missing room key (and hence might
     /// resolve itself if we wait a bit.)
     pub fn is_missing_room_key(&self) -> bool {
-        matches!(self, Self::MissingMegolmSession | Self::UnknownMegolmMessageIndex)
+        match self {
+            // Return true only if the key is not withheld on purpose.
+            Self::MissingMegolmSession(None) => true,
+            Self::UnknownMegolmMessageIndex => true,
+            _ => false,
+        }
     }
 }
 

crates/matrix-sdk-crypto/src/machine/mod.rs

@@ -23,7 +23,7 @@ use matrix_sdk_common::{
     deserialized_responses::{
         AlgorithmInfo, DecryptedRoomEvent, DeviceLinkProblem, EncryptionInfo, UnableToDecryptInfo,
         UnableToDecryptReason, UnsignedDecryptionResult, UnsignedEventLocation, VerificationLevel,
-        VerificationState,
+        VerificationState, WithheldReason,
     },
     BoxFuture,
 };
@@ -86,6 +86,7 @@ use crate::{
             room_key::{MegolmV1AesSha2Content, RoomKeyContent},
             room_key_withheld::{
                 MegolmV1AesSha2WithheldContent, RoomKeyWithheldContent, RoomKeyWithheldEvent,
+                WithheldCode,
             },
             ToDeviceEvents,
         },
@@ -2582,7 +2583,13 @@ fn megolm_error_to_utd_info(
     let reason = match error {
         EventError(_) => UnableToDecryptReason::MalformedEncryptedEvent,
         Decode(_) => UnableToDecryptReason::MalformedEncryptedEvent,
-        MissingRoomKey(_) => UnableToDecryptReason::MissingMegolmSession,
+        MissingRoomKey(maybe_withheld) => match maybe_withheld {
+            Some(WithheldCode::Unverified) => UnableToDecryptReason::MissingMegolmSession(Some(
+                WithheldReason::TrustRequirementMismatch,
+            )),
+            Some(_) => UnableToDecryptReason::MissingMegolmSession(Some(WithheldReason::Other)),
+            _ => UnableToDecryptReason::MissingMegolmSession(None),
+        },
         Decryption(DecryptionError::UnknownMessageIndex(_, _)) => {
             UnableToDecryptReason::UnknownMegolmMessageIndex
         }

crates/matrix-sdk-crypto/src/machine/tests/mod.rs

@@ -19,6 +19,7 @@ use futures_util::{pin_mut, FutureExt, StreamExt};
 use itertools::Itertools;
 use matrix_sdk_common::deserialized_responses::{
     UnableToDecryptInfo, UnableToDecryptReason, UnsignedDecryptionResult, UnsignedEventLocation,
+    WithheldReason,
 };
 use matrix_sdk_test::{async_test, message_like_event_content, ruma_response_from_json, test_json};
 use ruma::{
@@ -683,7 +684,10 @@ async fn test_withheld_unverified() {
         bob.try_decrypt_room_event(&room_event, room_id, &decryption_settings).await.unwrap();
     assert_let!(RoomEventDecryptionResult::UnableToDecrypt(utd_info) = decrypt_result);
     assert!(utd_info.session_id.is_some());
-    assert_eq!(utd_info.reason, UnableToDecryptReason::MissingMegolmSession);
+    assert_eq!(
+        utd_info.reason,
+        UnableToDecryptReason::MissingMegolmSession(Some(WithheldReason::TrustRequirementMismatch))
+    );
 }
 
 /// Test what happens when we feed an unencrypted event into the decryption
@@ -1362,7 +1366,7 @@ async fn test_unsigned_decryption() {
         replace_encryption_result,
         UnsignedDecryptionResult::UnableToDecrypt(UnableToDecryptInfo {
             session_id: Some(second_room_key_session_id),
-            reason: UnableToDecryptReason::MissingMegolmSession,
+            reason: UnableToDecryptReason::MissingMegolmSession(None),
         })
     );
 
@@ -1468,7 +1472,7 @@ async fn test_unsigned_decryption() {
         thread_encryption_result,
         UnsignedDecryptionResult::UnableToDecrypt(UnableToDecryptInfo {
             session_id: Some(third_room_key_session_id),
-            reason: UnableToDecryptReason::MissingMegolmSession,
+            reason: UnableToDecryptReason::MissingMegolmSession(None),
         })
     );
 

crates/matrix-sdk-crypto/src/types/events/utd_cause.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 use matrix_sdk_common::deserialized_responses::{
-    UnableToDecryptInfo, UnableToDecryptReason, VerificationLevel,
+    UnableToDecryptInfo, UnableToDecryptReason, VerificationLevel, WithheldReason,
 };
 use ruma::{events::AnySyncTimelineEvent, serde::Raw, MilliSecondsSinceUnixEpoch};
 use serde::Deserialize;
@@ -57,6 +57,18 @@ pub enum UtdCause {
     /// be confused with pre-join or pre-invite messages (see
     /// [`UtdCause::SentBeforeWeJoined`] for that).
     HistoricalMessage = 5,
+
+    /// The keys for this event are intentionally withheld.
+    /// The sender has refused to share the key because our device does not meet
+    /// the sender's security requirements.
+    WithheldForUnverifiedOrInsecureDevice = 6,
+
+    /// The keys for this event are missing, likely because the sender was
+    /// unable to share them (e.g., failure to establish an Olm 1:1
+    /// channel). Alternatively, the sender may have deliberately excluded
+    /// this device by cherry-picking and blocking it, no action can be taken on
+    /// our side.
+    WithheldBySender = 7,
 }
 
 /// MSC4115 membership info in the unsigned area.
@@ -98,7 +110,13 @@ impl UtdCause {
     ) -> Self {
         // TODO: in future, use more information to give a richer answer. E.g.
         match unable_to_decrypt_info.reason {
-            UnableToDecryptReason::MissingMegolmSession
+            UnableToDecryptReason::MissingMegolmSession(Some(reason)) => match reason {
+                WithheldReason::TrustRequirementMismatch => {
+                    UtdCause::WithheldForUnverifiedOrInsecureDevice
+                }
+                WithheldReason::Other => UtdCause::WithheldBySender,
+            },
+            UnableToDecryptReason::MissingMegolmSession(None)
             | UnableToDecryptReason::UnknownMegolmMessageIndex => {
                 // Look in the unsigned area for a `membership` field.
                 if let Some(unsigned) =
@@ -162,7 +180,7 @@ mod tests {
                 some_crypto_context_info(),
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession,
+                    reason: UnableToDecryptReason::MissingMegolmSession(None),
                 }
             ),
             UtdCause::Unknown
@@ -178,7 +196,7 @@ mod tests {
                 some_crypto_context_info(),
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::Unknown
@@ -195,7 +213,7 @@ mod tests {
                 some_crypto_context_info(),
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::Unknown
@@ -212,7 +230,7 @@ mod tests {
                 some_crypto_context_info(),
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::Unknown
@@ -229,7 +247,7 @@ mod tests {
                 some_crypto_context_info(),
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::Unknown
@@ -246,7 +264,7 @@ mod tests {
                 some_crypto_context_info(),
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::SentBeforeWeJoined
@@ -280,7 +298,7 @@ mod tests {
                 some_crypto_context_info(),
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::SentBeforeWeJoined
@@ -356,7 +374,7 @@ mod tests {
                 older_than_event_device,
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::Unknown
@@ -375,7 +393,7 @@ mod tests {
                 newer_than_event_device,
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::HistoricalMessage
@@ -493,7 +511,7 @@ mod tests {
                 crypto_context_info,
                 &UnableToDecryptInfo {
                     session_id: None,
-                    reason: UnableToDecryptReason::MissingMegolmSession
+                    reason: UnableToDecryptReason::MissingMegolmSession(None)
                 }
             ),
             UtdCause::Unknown

crates/matrix-sdk-ui/src/timeline/tests/encryption.rs

@@ -774,7 +774,7 @@ fn utd_event_with_unsigned(unsigned: serde_json::Value) -> SyncTimelineEvent {
         raw,
         matrix_sdk::deserialized_responses::UnableToDecryptInfo {
             session_id: Some("SESSION_ID".into()),
-            reason: UnableToDecryptReason::MissingMegolmSession,
+            reason: UnableToDecryptReason::MissingMegolmSession(None),
         },
     )
 }

testing/matrix-sdk-test/src/event_factory.rs

@@ -201,7 +201,10 @@ impl EventBuilder<RoomEncryptedEventContent> {
 
         SyncTimelineEvent::new_utd_event(
             self.into(),
-            UnableToDecryptInfo { session_id, reason: UnableToDecryptReason::MissingMegolmSession },
+            UnableToDecryptInfo {
+                session_id,
+                reason: UnableToDecryptReason::MissingMegolmSession(None),
+            },
         )
     }
 }