libsignal_service/provisioning/
cipher.rs

1use std::fmt::{self, Debug};
2
3use aes::cipher::block_padding::Pkcs7;
4use aes::cipher::{BlockDecryptMut, BlockEncryptMut, KeyIvInit};
5use aes::Aes256;
6use bytes::Bytes;
7use hmac::{Hmac, Mac};
8use libsignal_protocol::{KeyPair, PublicKey};
9use prost::Message;
10use rand::{CryptoRng, Rng};
11use sha2::Sha256;
12
13pub use crate::proto::{ProvisionEnvelope, ProvisionMessage};
14
15use crate::{
16    envelope::{CIPHER_KEY_SIZE, IV_LENGTH, IV_OFFSET},
17    provisioning::ProvisioningError,
18};
19
20enum CipherMode {
21    DecryptAndEncrypt(KeyPair),
22    EncryptOnly(PublicKey),
23}
24
25impl Debug for CipherMode {
26    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
27        match self {
28            CipherMode::DecryptAndEncrypt(key_pair) => f
29                .debug_tuple("CipherMode::DecryptAndEncrypt")
30                .field(&key_pair.public_key)
31                .finish(),
32            CipherMode::EncryptOnly(public) => f
33                .debug_tuple("CipherMode::EncryptOnly")
34                .field(&public)
35                .finish(),
36        }
37    }
38}
39
40impl CipherMode {
41    fn public(&self) -> &PublicKey {
42        match self {
43            CipherMode::DecryptAndEncrypt(pair) => &pair.public_key,
44            CipherMode::EncryptOnly(pub_key) => pub_key,
45        }
46    }
47}
48
49const VERSION: u8 = 1;
50
51#[derive(Debug)]
52pub struct ProvisioningCipher {
53    key_material: CipherMode,
54}
55
56impl ProvisioningCipher {
57    pub fn from_public(key: PublicKey) -> Self {
58        Self {
59            key_material: CipherMode::EncryptOnly(key),
60        }
61    }
62
63    pub fn from_key_pair(key_pair: KeyPair) -> Self {
64        Self {
65            key_material: CipherMode::DecryptAndEncrypt(key_pair),
66        }
67    }
68
69    pub fn public_key(&self) -> &PublicKey {
70        self.key_material.public()
71    }
72
73    #[expect(clippy::result_large_err)]
74    pub fn encrypt<R: Rng + CryptoRng>(
75        &self,
76        csprng: &mut R,
77        msg: ProvisionMessage,
78    ) -> Result<ProvisionEnvelope, ProvisioningError> {
79        let msg = msg.encode_to_vec();
80
81        let our_key_pair = libsignal_protocol::KeyPair::generate(csprng);
82        let agreement = our_key_pair
83            .calculate_agreement(self.public_key())
84            .map_err(ProvisioningError::invalid_public_key)?;
85
86        let mut shared_secrets = [0; 64];
87        hkdf::Hkdf::<sha2::Sha256>::new(None, &agreement)
88            .expand(b"TextSecure Provisioning Message", &mut shared_secrets)
89            .expect("valid output length");
90
91        let aes_key = &shared_secrets[0..32];
92        let mac_key = &shared_secrets[32..];
93        let iv: [u8; IV_LENGTH] = csprng.random();
94
95        let cipher = cbc::Encryptor::<Aes256>::new(aes_key.into(), &iv.into());
96        let ciphertext = cipher.encrypt_padded_vec_mut::<Pkcs7>(&msg);
97        let mut mac = Hmac::<Sha256>::new_from_slice(mac_key)
98            .expect("HMAC can take any size key");
99        mac.update(&[VERSION]);
100        mac.update(&iv);
101        mac.update(&ciphertext);
102        let mac = mac.finalize().into_bytes();
103
104        let body: Vec<u8> = std::iter::once(VERSION)
105            .chain(iv.iter().cloned())
106            .chain(ciphertext)
107            .chain(mac)
108            .collect();
109
110        Ok(ProvisionEnvelope {
111            public_key: Some(our_key_pair.public_key.serialize().into()),
112            body: Some(body),
113        })
114    }
115
116    #[expect(clippy::result_large_err)]
117    pub fn decrypt(
118        &self,
119        provision_envelope: ProvisionEnvelope,
120    ) -> Result<ProvisionMessage, ProvisioningError> {
121        let key_pair = match self.key_material {
122            CipherMode::DecryptAndEncrypt(ref key_pair) => key_pair,
123            CipherMode::EncryptOnly(_) => {
124                return Err(ProvisioningError::EncryptOnlyProvisioningCipher);
125            },
126        };
127        let master_ephemeral = PublicKey::deserialize(
128            &provision_envelope.public_key.expect("no public key"),
129        )
130        .map_err(ProvisioningError::invalid_public_key)?;
131        let body = provision_envelope
132            .body
133            .expect("no body in ProvisionMessage");
134        if body[0] != VERSION {
135            return Err(ProvisioningError::BadVersionNumber);
136        }
137
138        let iv = &body[IV_OFFSET..(IV_LENGTH + IV_OFFSET)];
139        let mac = &body[(body.len() - 32)..];
140        let cipher_text = &body[16 + 1..(body.len() - CIPHER_KEY_SIZE)];
141        let iv_and_cipher_text = &body[0..(body.len() - CIPHER_KEY_SIZE)];
142        debug_assert_eq!(iv.len(), IV_LENGTH);
143        debug_assert_eq!(mac.len(), 32);
144
145        let agreement = key_pair
146            .calculate_agreement(&master_ephemeral)
147            .map_err(ProvisioningError::invalid_private_key)?;
148
149        let mut shared_secrets = [0; 64];
150        hkdf::Hkdf::<sha2::Sha256>::new(None, &agreement)
151            .expand(b"TextSecure Provisioning Message", &mut shared_secrets)
152            .expect("valid output length");
153
154        let parts1 = &shared_secrets[0..32];
155        let parts2 = &shared_secrets[32..];
156
157        let mut verifier = Hmac::<Sha256>::new_from_slice(parts2)
158            .expect("HMAC can take any size key");
159        verifier.update(iv_and_cipher_text);
160        let our_mac = verifier.finalize().into_bytes();
161        debug_assert_eq!(our_mac.len(), mac.len());
162        if &our_mac[..32] != mac {
163            return Err(ProvisioningError::MismatchedMac);
164        }
165
166        // libsignal-service-java uses Pkcs5,
167        // but that should not matter.
168        // https://crypto.stackexchange.com/questions/9043/what-is-the-difference-between-pkcs5-padding-and-pkcs7-padding
169        let cipher = cbc::Decryptor::<Aes256>::new(parts1.into(), iv.into());
170        let input = cipher
171            .decrypt_padded_vec_mut::<Pkcs7>(cipher_text)
172            .map_err(ProvisioningError::AesPaddingError)?;
173
174        Ok(prost::Message::decode(Bytes::from(input))?)
175    }
176}
177
178#[cfg(test)]
179mod tests {
180    use super::*;
181
182    #[test]
183    fn encrypt_provisioning_roundtrip() -> anyhow::Result<()> {
184        let mut rng = rand::rng();
185        let key_pair = KeyPair::generate(&mut rng);
186        let cipher = ProvisioningCipher::from_key_pair(key_pair);
187        let encrypt_cipher: ProvisioningCipher =
188            ProvisioningCipher::from_public(*cipher.public_key());
189
190        assert_eq!(
191            cipher.public_key(),
192            encrypt_cipher.public_key(),
193            "copy public key"
194        );
195
196        let msg = ProvisionMessage::default();
197        let encrypted = encrypt_cipher.encrypt(&mut rng, msg.clone())?;
198
199        assert!(matches!(
200            encrypt_cipher.decrypt(encrypted.clone()),
201            Err(ProvisioningError::EncryptOnlyProvisioningCipher)
202        ));
203
204        let decrypted = cipher.decrypt(encrypted)?;
205        assert_eq!(msg, decrypted);
206
207        Ok(())
208    }
209}
libsignal_service/provisioning/cipher.rs

libsignal_service/provisioning/
cipher.rs
