libsignal_service/
cipher.rs

1use std::{convert::TryFrom, fmt, time::SystemTime};
2
3use aes::cipher::block_padding::{Iso7816, RawPadding};
4use base64::prelude::*;
5use libsignal_protocol::{
6    group_decrypt, message_decrypt_prekey, message_decrypt_signal,
7    message_encrypt, process_sender_key_distribution_message,
8    sealed_sender_decrypt_to_usmc, sealed_sender_encrypt,
9    CiphertextMessageType, DeviceId, IdentityKeyStore, KyberPreKeyStore,
10    PreKeySignalMessage, PreKeyStore, ProtocolAddress, ProtocolStore,
11    PublicKey, SealedSenderDecryptionResult, SenderCertificate,
12    SenderKeyDistributionMessage, SenderKeyStore, ServiceId, SessionStore,
13    SignalMessage, SignalProtocolError, SignedPreKeyStore, Timestamp,
14};
15use prost::Message;
16use rand::{CryptoRng, Rng};
17use uuid::Uuid;
18
19use crate::{
20    content::{Content, Metadata},
21    envelope::Envelope,
22    push_service::ServiceError,
23    sender::OutgoingPushMessage,
24    session_store::SessionStoreExt,
25    utils::BASE64_RELAXED,
26    ServiceIdExt,
27};
28/// Decrypts incoming messages and encrypts outgoing messages.
29///
30/// Equivalent of SignalServiceCipher in Java.
31#[derive(Clone)]
32pub struct ServiceCipher<S> {
33    protocol_store: S,
34    trust_root: PublicKey,
35    local_uuid: Uuid,
36    local_device_id: u32,
37}
38
39impl<S> fmt::Debug for ServiceCipher<S> {
40    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
41        f.debug_struct("ServiceCipher")
42            .field("protocol_store", &"...")
43            .field("trust_root", &"...")
44            .field("local_uuid", &self.local_uuid)
45            .field("local_device_id", &self.local_device_id)
46            .finish()
47    }
48}
49
50fn debug_envelope(envelope: &Envelope) -> String {
51    if envelope.content.is_none() {
52        "Envelope { empty }".to_string()
53    } else {
54        format!(
55            "Envelope {{ \
56                 source_address: {:?}, \
57                 source_device: {:?}, \
58                 server_guid: {:?}, \
59                 timestamp: {:?}, \
60                 content: {} bytes, \
61             }}",
62            envelope.source_service_id,
63            envelope.source_device(),
64            envelope.server_guid(),
65            envelope.timestamp(),
66            envelope.content().len(),
67        )
68    }
69}
70
71impl<S> ServiceCipher<S>
72where
73    S: ProtocolStore + SenderKeyStore + SessionStoreExt + Clone,
74{
75    pub fn new(
76        protocol_store: S,
77        trust_root: PublicKey,
78        local_uuid: Uuid,
79        local_device_id: u32,
80    ) -> Self {
81        Self {
82            protocol_store,
83            trust_root,
84            local_uuid,
85            local_device_id,
86        }
87    }
88
89    /// Opens ("decrypts") an envelope.
90    ///
91    /// Envelopes may be empty, in which case this method returns `Ok(None)`
92    #[tracing::instrument(skip(envelope, csprng), fields(envelope = debug_envelope(&envelope)))]
93    pub async fn open_envelope<R: Rng + CryptoRng>(
94        &mut self,
95        envelope: Envelope,
96        csprng: &mut R,
97    ) -> Result<Option<Content>, ServiceError> {
98        if envelope.content.is_some() {
99            let plaintext = self.decrypt(&envelope, csprng).await?;
100            let was_plaintext = plaintext.metadata.was_plaintext;
101            let message =
102                crate::proto::Content::decode(plaintext.data.as_slice())?;
103
104            tracing::Span::current()
105                .record("envelope_metadata", plaintext.metadata.to_string());
106
107            // Sanity test: if the envelope was plaintext, the message should *only* be a
108            // decryption failure error
109            if was_plaintext {
110                if let crate::proto::Content {
111                    data_message: None,
112                    sync_message: None,
113                    call_message: None,
114                    null_message: None,
115                    receipt_message: None,
116                    typing_message: None,
117                    sender_key_distribution_message: None,
118                    decryption_error_message: Some(decryption_error_message),
119                    story_message: None,
120                    pni_signature_message: None,
121                    edit_message: None,
122                } = &message
123                {
124                    tracing::warn!(
125                        ?envelope,
126                        "Received a decryption error message: {}.",
127                        String::from_utf8_lossy(decryption_error_message)
128                    );
129                } else {
130                    tracing::error!(
131                        ?envelope,
132                        "Received a plaintext envelope with a non-decryption error message."
133                    );
134                    return Ok(None);
135                }
136            }
137
138            if message.sync_message.is_some()
139                && plaintext.metadata.sender.aci().map(Into::into)
140                    != Some(self.local_uuid)
141            {
142                tracing::warn!("Source is not ourself.");
143                return Ok(None);
144            }
145
146            if let Some(bytes) = message.sender_key_distribution_message {
147                let skdm = SenderKeyDistributionMessage::try_from(&bytes[..])?;
148                process_sender_key_distribution_message(
149                    &plaintext.metadata.protocol_address(),
150                    &skdm,
151                    &mut self.protocol_store,
152                )
153                .await?;
154                Ok(None)
155            } else {
156                let content = Content::from_proto(message, plaintext.metadata)?;
157                Ok(Some(content))
158            }
159        } else {
160            Ok(None)
161        }
162    }
163
164    /// Equivalent of decrypt(Envelope, ciphertext)
165    ///
166    /// Triage of legacy messages happens inside this method, as opposed to the
167    /// Java implementation, because it makes the borrow checker and the
168    /// author happier.
169    #[tracing::instrument(skip(envelope, csprng), fields(envelope = debug_envelope(envelope)))]
170    async fn decrypt<R: Rng + CryptoRng>(
171        &mut self,
172        envelope: &Envelope,
173        csprng: &mut R,
174    ) -> Result<Plaintext, ServiceError> {
175        let ciphertext = if let Some(msg) = envelope.content.as_ref() {
176            msg
177        } else {
178            return Err(ServiceError::InvalidFrame {
179                reason:
180                    "envelope should have either a legacy message or content.",
181            });
182        };
183
184        let server_guid =
185            envelope.server_guid.as_ref().and_then(|g| match g.parse() {
186                Ok(uuid) => Some(uuid),
187                Err(e) => {
188                    tracing::error!(
189                        ?envelope,
190                        "Unparseable server_guid ({})",
191                        e
192                    );
193                    None
194                },
195            });
196
197        use crate::proto::envelope::Type;
198        let plaintext = match envelope.r#type() {
199            Type::PrekeyBundle => {
200                let sender = get_preferred_protocol_address(
201                    &self.protocol_store,
202                    &envelope.source_address(),
203                    envelope.source_device().into(),
204                )
205                .await?;
206                let metadata = Metadata {
207                    destination: envelope.destination_address(),
208                    sender: envelope.source_address(),
209                    sender_device: envelope.source_device(),
210                    timestamp: envelope.server_timestamp(),
211                    needs_receipt: false,
212                    unidentified_sender: false,
213                    was_plaintext: false,
214
215                    server_guid,
216                };
217
218                let mut data = message_decrypt_prekey(
219                    &PreKeySignalMessage::try_from(&ciphertext[..]).unwrap(),
220                    &sender,
221                    &mut self.protocol_store.clone(),
222                    &mut self.protocol_store.clone(),
223                    &mut self.protocol_store.clone(),
224                    &self.protocol_store.clone(),
225                    &mut self.protocol_store.clone(),
226                    csprng,
227                )
228                .await?
229                .as_slice()
230                .to_vec();
231
232                let session_record = self
233                    .protocol_store
234                    .load_session(&sender)
235                    .await?
236                    .ok_or(SignalProtocolError::SessionNotFound(sender))?;
237
238                strip_padding_version(
239                    session_record.session_version()?,
240                    &mut data,
241                )?;
242                Plaintext { metadata, data }
243            },
244            Type::PlaintextContent => {
245                tracing::warn!(?envelope, "Envelope with plaintext content.  This usually indicates a decryption retry.");
246                let metadata = Metadata {
247                    destination: envelope.destination_address(),
248                    sender: envelope.source_address(),
249                    sender_device: envelope.source_device(),
250                    timestamp: envelope.server_timestamp(),
251                    needs_receipt: false,
252                    unidentified_sender: false,
253                    was_plaintext: true,
254
255                    server_guid,
256                };
257                Plaintext {
258                    metadata,
259                    data: ciphertext.clone(),
260                }
261            },
262            Type::Ciphertext => {
263                let sender = get_preferred_protocol_address(
264                    &self.protocol_store,
265                    &envelope.source_address(),
266                    envelope.source_device().into(),
267                )
268                .await?;
269                let metadata = Metadata {
270                    destination: envelope.destination_address(),
271                    sender: envelope.source_address(),
272                    sender_device: envelope.source_device(),
273                    timestamp: envelope.timestamp(),
274                    needs_receipt: false,
275                    unidentified_sender: false,
276                    was_plaintext: false,
277
278                    server_guid,
279                };
280
281                let mut data = message_decrypt_signal(
282                    &SignalMessage::try_from(&ciphertext[..])?,
283                    &sender,
284                    &mut self.protocol_store.clone(),
285                    &mut self.protocol_store.clone(),
286                    csprng,
287                )
288                .await?
289                .as_slice()
290                .to_vec();
291
292                let session_record = self
293                    .protocol_store
294                    .load_session(&sender)
295                    .await?
296                    .ok_or(SignalProtocolError::SessionNotFound(sender))?;
297
298                strip_padding_version(
299                    session_record.session_version()?,
300                    &mut data,
301                )?;
302                Plaintext { metadata, data }
303            },
304            Type::UnidentifiedSender => {
305                let SealedSenderDecryptionResult {
306                    sender_uuid,
307                    sender_e164: _,
308                    device_id,
309                    mut message,
310                } = sealed_sender_decrypt(
311                    ciphertext,
312                    &self.trust_root,
313                    Timestamp::from_epoch_millis(envelope.timestamp()),
314                    None,
315                    self.local_uuid.to_string(),
316                    self.local_device_id.into(),
317                    &mut self.protocol_store.clone(),
318                    &mut self.protocol_store.clone(),
319                    &mut self.protocol_store.clone(),
320                    &mut self.protocol_store.clone(),
321                    &mut self.protocol_store.clone(),
322                    &mut self.protocol_store,
323                )
324                .await?;
325
326                let Some(sender) =
327                    ServiceId::parse_from_service_id_string(&sender_uuid)
328                else {
329                    return Err(
330                        SignalProtocolError::InvalidSealedSenderMessage(
331                            "invalid sender UUID".to_string(),
332                        )
333                        .into(),
334                    );
335                };
336
337                let needs_receipt = if envelope.source_service_id.is_some() {
338                    tracing::warn!(?envelope, "Received an unidentified delivery over an identified channel.  Marking needs_receipt=false");
339                    false
340                } else {
341                    true
342                };
343
344                let metadata = Metadata {
345                    destination: envelope.destination_address(),
346                    sender,
347                    sender_device: device_id.into(),
348                    timestamp: envelope.timestamp(),
349                    unidentified_sender: true,
350                    needs_receipt,
351                    was_plaintext: false,
352
353                    server_guid,
354                };
355
356                strip_padding(&mut message)?;
357
358                Plaintext {
359                    metadata,
360                    data: message,
361                }
362            },
363            _ => {
364                // else
365                return Err(ServiceError::InvalidFrame {
366                    reason: "envelope has unknown type",
367                });
368            },
369        };
370        Ok(plaintext)
371    }
372
373    #[tracing::instrument(
374        skip(address, unidentified_access, content, csprng),
375        fields(
376            address = %address,
377            with_unidentified_access = unidentified_access.is_some(),
378            content_length = content.len(),
379        )
380    )]
381    pub(crate) async fn encrypt<R: Rng + CryptoRng>(
382        &mut self,
383        address: &ProtocolAddress,
384        unidentified_access: Option<&SenderCertificate>,
385        content: &[u8],
386        csprng: &mut R,
387    ) -> Result<OutgoingPushMessage, ServiceError> {
388        let session_record = self
389            .protocol_store
390            .load_session(address)
391            .await?
392            .ok_or_else(|| {
393            SignalProtocolError::SessionNotFound(address.clone())
394        })?;
395
396        let padded_content =
397            add_padding(session_record.session_version()?, content)?;
398
399        if let Some(unindentified_access) = unidentified_access {
400            let destination_registration_id =
401                session_record.remote_registration_id()?;
402
403            let message = sealed_sender_encrypt(
404                address,
405                unindentified_access,
406                &padded_content,
407                &mut self.protocol_store.clone(),
408                &mut self.protocol_store,
409                SystemTime::now(),
410                csprng,
411            )
412            .await?;
413
414            use crate::proto::envelope::Type;
415            Ok(OutgoingPushMessage {
416                r#type: Type::UnidentifiedSender as u32,
417                destination_device_id: address.device_id().into(),
418                destination_registration_id,
419                content: BASE64_RELAXED.encode(message),
420            })
421        } else {
422            let message = message_encrypt(
423                &padded_content,
424                address,
425                &mut self.protocol_store.clone(),
426                &mut self.protocol_store.clone(),
427                SystemTime::now(),
428            )
429            .await?;
430
431            let destination_registration_id =
432                session_record.remote_registration_id()?;
433
434            let body = BASE64_RELAXED.encode(message.serialize());
435
436            use crate::proto::envelope::Type;
437            let message_type = match message.message_type() {
438                CiphertextMessageType::PreKey => Type::PrekeyBundle,
439                CiphertextMessageType::Whisper => Type::Ciphertext,
440                t => panic!("Bad type: {:?}", t),
441            } as u32;
442            Ok(OutgoingPushMessage {
443                r#type: message_type,
444                destination_device_id: address.device_id().into(),
445                destination_registration_id,
446                content: body,
447            })
448        }
449    }
450}
451
452struct Plaintext {
453    metadata: Metadata,
454    data: Vec<u8>,
455}
456
457#[expect(clippy::comparison_chain, clippy::result_large_err)]
458fn add_padding(version: u32, contents: &[u8]) -> Result<Vec<u8>, ServiceError> {
459    if version < 2 {
460        Err(ServiceError::PaddingVersion(version))
461    } else if version == 2 {
462        Ok(contents.to_vec())
463    } else {
464        let message_length = contents.len();
465        let message_length_with_terminator = contents.len() + 1;
466        let mut message_part_count = message_length_with_terminator / 160;
467        if message_length_with_terminator % 160 != 0 {
468            message_part_count += 1;
469        }
470
471        let message_length_with_padding = message_part_count * 160;
472
473        let mut buffer = vec![0u8; message_length_with_padding];
474        buffer[..message_length].copy_from_slice(contents);
475        Iso7816::raw_pad(&mut buffer, message_length);
476        Ok(buffer)
477    }
478}
479
480#[expect(clippy::comparison_chain, clippy::result_large_err)]
481fn strip_padding_version(
482    version: u32,
483    contents: &mut Vec<u8>,
484) -> Result<(), ServiceError> {
485    if version < 2 {
486        Err(ServiceError::InvalidFrame {
487            reason: "unknown version",
488        })
489    } else if version == 2 {
490        Ok(())
491    } else {
492        strip_padding(contents)?;
493        Ok(())
494    }
495}
496
497#[expect(clippy::result_large_err)]
498fn strip_padding(contents: &mut Vec<u8>) -> Result<(), ServiceError> {
499    let new_length = Iso7816::raw_unpad(contents)?.len();
500    contents.resize(new_length, 0);
501    Ok(())
502}
503
504/// Equivalent of `SignalServiceCipher::getPreferredProtocolAddress`
505pub async fn get_preferred_protocol_address<S: SessionStore>(
506    session_store: &S,
507    address: &ServiceId,
508    device_id: DeviceId,
509) -> Result<ProtocolAddress, libsignal_protocol::error::SignalProtocolError> {
510    let address = address.to_protocol_address(device_id);
511    if session_store.load_session(&address).await?.is_some() {
512        return Ok(address);
513    }
514
515    Ok(address)
516}
517
518/// Decrypt a Sealed Sender message `ciphertext` in either the v1 or v2 format, validate its sender
519/// certificate, and then decrypt the inner message payload.
520///
521/// This method calls [`sealed_sender_decrypt_to_usmc`] to extract the sender information, including
522/// the embedded [`SenderCertificate`]. The sender certificate (signed by the [`ServerCertificate`])
523/// is then validated against the `trust_root` baked into the client to ensure that the sender's
524/// identity was not forged.
525#[allow(clippy::too_many_arguments)]
526#[tracing::instrument(
527    skip(
528        ciphertext,
529        trust_root,
530        identity_store,
531        session_store,
532        pre_key_store,
533        signed_pre_key_store,
534        sender_key_store,
535        kyber_pre_key_store
536    ),
537    fields(
538        ciphertext = ciphertext.len(),
539    )
540)]
541async fn sealed_sender_decrypt(
542    ciphertext: &[u8],
543    trust_root: &PublicKey,
544    timestamp: Timestamp,
545    local_e164: Option<String>,
546    local_uuid: String,
547    local_device_id: DeviceId,
548    identity_store: &mut dyn IdentityKeyStore,
549    session_store: &mut dyn SessionStore,
550    pre_key_store: &mut dyn PreKeyStore,
551    signed_pre_key_store: &mut dyn SignedPreKeyStore,
552    sender_key_store: &mut dyn SenderKeyStore,
553    kyber_pre_key_store: &mut dyn KyberPreKeyStore,
554) -> Result<SealedSenderDecryptionResult, SignalProtocolError> {
555    let usmc =
556        sealed_sender_decrypt_to_usmc(ciphertext, identity_store).await?;
557
558    if !usmc.sender()?.validate(trust_root, timestamp)? {
559        return Err(SignalProtocolError::InvalidSealedSenderMessage(
560            "trust root validation failed".to_string(),
561        ));
562    }
563
564    let is_local_uuid = local_uuid == usmc.sender()?.sender_uuid()?;
565
566    let is_local_e164 = match (local_e164, usmc.sender()?.sender_e164()?) {
567        (Some(l), Some(s)) => l == s,
568        (_, _) => false,
569    };
570
571    if (is_local_e164 || is_local_uuid)
572        && usmc.sender()?.sender_device_id()? == local_device_id
573    {
574        return Err(SignalProtocolError::SealedSenderSelfSend);
575    }
576
577    let mut rng = rand::rngs::OsRng;
578
579    let remote_address = ProtocolAddress::new(
580        usmc.sender()?.sender_uuid()?.to_string(),
581        usmc.sender()?.sender_device_id()?,
582    );
583
584    let message = match usmc.msg_type()? {
585        CiphertextMessageType::Whisper => {
586            let ctext = SignalMessage::try_from(usmc.contents()?)?;
587            message_decrypt_signal(
588                &ctext,
589                &remote_address,
590                session_store,
591                identity_store,
592                &mut rng,
593            )
594            .await?
595        },
596        CiphertextMessageType::PreKey => {
597            let ctext = PreKeySignalMessage::try_from(usmc.contents()?)?;
598            message_decrypt_prekey(
599                &ctext,
600                &remote_address,
601                session_store,
602                identity_store,
603                pre_key_store,
604                signed_pre_key_store,
605                kyber_pre_key_store,
606                &mut rng,
607            )
608            .await?
609        },
610        CiphertextMessageType::SenderKey => {
611            group_decrypt(usmc.contents()?, sender_key_store, &remote_address)
612                .await?
613        },
614        msg_type => {
615            return Err(SignalProtocolError::InvalidMessage(
616                msg_type,
617                "unexpected message type for sealed_sender_decrypt",
618            ));
619        },
620    };
621
622    Ok(SealedSenderDecryptionResult {
623        sender_uuid: usmc.sender()?.sender_uuid()?.to_string(),
624        sender_e164: usmc.sender()?.sender_e164()?.map(|s| s.to_string()),
625        device_id: usmc.sender()?.sender_device_id()?,
626        message,
627    })
628}
libsignal_service/cipher.rs

libsignal_service/
cipher.rs
