libsignal_service/groups_v2/
manager.rs

1use std::{collections::HashMap, convert::TryInto};
2
3use crate::{
4    configuration::Endpoint,
5    groups_v2::{
6        model::{Group, GroupChanges},
7        operations::{GroupDecodingError, GroupOperations},
8    },
9    prelude::{PushService, ServiceError},
10    proto::GroupContextV2,
11    push_service::{HttpAuth, HttpAuthOverride, ReqwestExt, ServiceIds},
12    utils::BASE64_RELAXED,
13};
14
15use base64::prelude::*;
16use bytes::Bytes;
17use chrono::{Days, NaiveDate, NaiveTime, Utc};
18use futures::AsyncReadExt;
19use rand::{CryptoRng, Rng};
20use reqwest::Method;
21use serde::Deserialize;
22use zkgroup::{
23    auth::{AuthCredentialWithPni, AuthCredentialWithPniResponse},
24    groups::{GroupMasterKey, GroupSecretParams},
25    ServerPublicParams,
26};
27
28#[derive(Debug, serde::Deserialize)]
29#[serde(rename_all = "camelCase")]
30pub struct TemporalCredential {
31    credential: String,
32    redemption_time: u64,
33}
34
35#[derive(Deserialize)]
36#[serde(rename_all = "camelCase")]
37pub struct CredentialResponse {
38    credentials: Vec<TemporalCredential>,
39}
40
41#[expect(clippy::result_large_err)]
42impl CredentialResponse {
43    pub fn parse(
44        self,
45    ) -> Result<HashMap<u64, AuthCredentialWithPniResponse>, ServiceError> {
46        self.credentials
47            .into_iter()
48            .map(|c| {
49                let bytes = BASE64_RELAXED.decode(c.credential)?;
50                let data = AuthCredentialWithPniResponse::new(&bytes)?;
51                Ok((c.redemption_time, data))
52            })
53            .collect::<Result<_, ServiceError>>()
54    }
55}
56
57#[derive(Debug, thiserror::Error)]
58pub enum CredentialsCacheError {
59    #[error("failed to read values from cache: {0}")]
60    ReadError(String),
61    #[error("failed to write values from cache: {0}")]
62    WriteError(String),
63}
64
65/// Global cache for groups v2 credentials, as demonstrated in the libsignal-service
66/// java library of Signal-Android.
67///
68/// A basic in-memory implementation is provided with `InMemoryCredentialsCache`.
69pub trait CredentialsCache {
70    fn clear(&mut self) -> Result<(), CredentialsCacheError>;
71
72    /// Get an entry of the cache, key usually represents the day number since EPOCH.
73    fn get(
74        &self,
75        key: &u64,
76    ) -> Result<Option<&AuthCredentialWithPniResponse>, CredentialsCacheError>;
77
78    /// Overwrite the entire contents of the cache with new data.
79    fn write(
80        &mut self,
81        map: HashMap<u64, AuthCredentialWithPniResponse>,
82    ) -> Result<(), CredentialsCacheError>;
83}
84
85#[derive(Default)]
86pub struct InMemoryCredentialsCache {
87    map: HashMap<u64, AuthCredentialWithPniResponse>,
88}
89
90impl CredentialsCache for InMemoryCredentialsCache {
91    fn clear(&mut self) -> Result<(), CredentialsCacheError> {
92        self.map.clear();
93        Ok(())
94    }
95
96    fn get(
97        &self,
98        key: &u64,
99    ) -> Result<Option<&AuthCredentialWithPniResponse>, CredentialsCacheError>
100    {
101        Ok(self.map.get(key))
102    }
103
104    fn write(
105        &mut self,
106        map: HashMap<u64, AuthCredentialWithPniResponse>,
107    ) -> Result<(), CredentialsCacheError> {
108        self.map = map;
109        Ok(())
110    }
111}
112
113impl<T: CredentialsCache> CredentialsCache for &mut T {
114    fn clear(&mut self) -> Result<(), CredentialsCacheError> {
115        (**self).clear()
116    }
117
118    fn get(
119        &self,
120        key: &u64,
121    ) -> Result<Option<&AuthCredentialWithPniResponse>, CredentialsCacheError>
122    {
123        (**self).get(key)
124    }
125
126    fn write(
127        &mut self,
128        map: HashMap<u64, AuthCredentialWithPniResponse>,
129    ) -> Result<(), CredentialsCacheError> {
130        (**self).write(map)
131    }
132}
133
134pub struct GroupsManager<C: CredentialsCache> {
135    service_ids: ServiceIds,
136    push_service: PushService,
137    credentials_cache: C,
138    server_public_params: ServerPublicParams,
139}
140
141impl<C: CredentialsCache> GroupsManager<C> {
142    pub fn new(
143        service_ids: ServiceIds,
144        push_service: PushService,
145        credentials_cache: C,
146        server_public_params: ServerPublicParams,
147    ) -> Self {
148        Self {
149            service_ids,
150            push_service,
151            credentials_cache,
152            server_public_params,
153        }
154    }
155
156    pub async fn get_authorization_for_today<R: Rng + CryptoRng>(
157        &mut self,
158        csprng: &mut R,
159        group_secret_params: GroupSecretParams,
160    ) -> Result<HttpAuth, ServiceError> {
161        let (today, today_plus_7_days) = current_days_seconds();
162
163        let auth_credential_response = if let Some(auth_credential_response) =
164            self.credentials_cache.get(&today)?
165        {
166            auth_credential_response
167        } else {
168            let path =
169            format!("/v1/certificate/auth/group?redemptionStartSeconds={}&redemptionEndSeconds={}&pniAsServiceId=true", today, today_plus_7_days);
170
171            let credentials_response: CredentialResponse = self
172                .push_service
173                .request(
174                    Method::GET,
175                    Endpoint::service(path),
176                    HttpAuthOverride::NoOverride,
177                )?
178                .send()
179                .await?
180                .service_error_for_status()
181                .await?
182                .json()
183                .await?;
184            self.credentials_cache
185                .write(credentials_response.parse()?)?;
186            self.credentials_cache.get(&today)?.ok_or({
187                ServiceError::InvalidFrame {
188                    reason:
189                        "credentials received did not contain requested day",
190                }
191            })?
192        };
193
194        self.get_authorization_string(
195            csprng,
196            group_secret_params,
197            auth_credential_response.clone(),
198            today,
199        )
200    }
201
202    #[expect(clippy::result_large_err)]
203    fn get_authorization_string<R: Rng + CryptoRng>(
204        &self,
205        csprng: &mut R,
206        group_secret_params: GroupSecretParams,
207        credential_response: AuthCredentialWithPniResponse,
208        today: u64,
209    ) -> Result<HttpAuth, ServiceError> {
210        let redemption_time = zkgroup::Timestamp::from_epoch_seconds(today);
211
212        let auth_credential_bytes =
213            zkgroup::serialize(&credential_response.receive(
214                &self.server_public_params,
215                self.service_ids.aci(),
216                self.service_ids.pni(),
217                redemption_time,
218            )?);
219
220        let auth_credential =
221            AuthCredentialWithPni::new(&auth_credential_bytes)
222                .expect("just validated");
223
224        let mut random_bytes = [0u8; 32];
225        csprng.fill_bytes(&mut random_bytes);
226
227        let auth_credential_presentation =
228            zkgroup::serialize(&auth_credential.present(
229                &self.server_public_params,
230                &group_secret_params,
231                random_bytes,
232            ));
233
234        // see simpleapi.rs GroupSecretParams_getPublicParams, everything is bincode encoded
235        // across the boundary of Rust/Java
236        let username = hex::encode(bincode::serialize(
237            &group_secret_params.get_public_params(),
238        )?);
239
240        let password = hex::encode(&auth_credential_presentation);
241
242        Ok(HttpAuth { username, password })
243    }
244
245    pub async fn fetch_encrypted_group<R: Rng + CryptoRng>(
246        &mut self,
247        csprng: &mut R,
248        master_key_bytes: &[u8],
249    ) -> Result<crate::proto::Group, ServiceError> {
250        let group_master_key = GroupMasterKey::new(
251            master_key_bytes
252                .try_into()
253                .map_err(|_| ServiceError::GroupsV2Error)?,
254        );
255        let group_secret_params =
256            GroupSecretParams::derive_from_master_key(group_master_key);
257        let authorization = self
258            .get_authorization_for_today(csprng, group_secret_params)
259            .await?;
260        self.push_service.get_group(authorization).await
261    }
262
263    #[tracing::instrument(
264        skip(self, group_secret_params),
265        fields(path = %path[..4.min(path.len())]),
266    )]
267    pub async fn retrieve_avatar(
268        &mut self,
269        path: &str,
270        group_secret_params: GroupSecretParams,
271    ) -> Result<Option<Vec<u8>>, ServiceError> {
272        let mut encrypted_avatar = self
273            .push_service
274            .retrieve_groups_v2_profile_avatar(path)
275            .await?;
276        let mut result = Vec::with_capacity(10 * 1024 * 1024);
277        encrypted_avatar.read_to_end(&mut result).await?;
278        Ok(GroupOperations::new(group_secret_params).decrypt_avatar(&result))
279    }
280
281    pub fn decrypt_group_context(
282        &self,
283        group_context: GroupContextV2,
284    ) -> Result<Option<GroupChanges>, GroupDecodingError> {
285        match (group_context.master_key, group_context.group_change) {
286            (Some(master_key), Some(group_change)) => {
287                let master_key_bytes: [u8; 32] = master_key
288                    .try_into()
289                    .map_err(|_| GroupDecodingError::WrongBlob)?;
290                let group_master_key = GroupMasterKey::new(master_key_bytes);
291                let group_secret_params =
292                    GroupSecretParams::derive_from_master_key(group_master_key);
293                let encrypted_group_change =
294                    prost::Message::decode(Bytes::from(group_change))?;
295                let group_change = GroupOperations::new(group_secret_params)
296                    .decrypt_group_change(encrypted_group_change)?;
297                Ok(Some(group_change))
298            },
299            _ => Ok(None),
300        }
301    }
302}
303
304#[expect(clippy::result_large_err)]
305pub fn decrypt_group(
306    master_key_bytes: &[u8],
307    encrypted_group: crate::proto::Group,
308) -> Result<Group, ServiceError> {
309    let group_master_key = GroupMasterKey::new(
310        master_key_bytes
311            .try_into()
312            .expect("wrong master key bytes length"),
313    );
314    let group_secret_params =
315        GroupSecretParams::derive_from_master_key(group_master_key);
316
317    Ok(GroupOperations::new(group_secret_params)
318        .decrypt_group(encrypted_group)?)
319}
320
321fn current_days_seconds() -> (u64, u64) {
322    let days_seconds = |date: NaiveDate| {
323        date.and_time(NaiveTime::from_hms_opt(0, 0, 0).unwrap())
324            .and_utc()
325            .timestamp() as u64
326    };
327
328    let today = Utc::now().naive_utc().date();
329    let today_plus_7_days = today + Days::new(7);
330
331    (days_seconds(today), days_seconds(today_plus_7_days))
332}
libsignal_service/groups_v2/manager.rs

libsignal_service/groups_v2/
manager.rs
