pg_core/client/
header.rs

1//! PostGuard header definitions.
2
3use crate::artifacts::{deserialize_bin_or_b64, serialize_bin_or_b64};
4use crate::artifacts::{MultiRecipientCiphertext, PublicKey, UserSecretKey};
5use crate::consts::*;
6use crate::error::Error;
7use crate::identity::{EncryptionPolicy, HiddenPolicy, Policy};
8
9use ibe::kem::cgw_kv::CGWKV;
10use ibe::kem::mkem::MultiRecipient;
11use ibe::kem::{SharedSecret, IBKEM};
12
13use ibs::gg::Signature;
14
15use alloc::collections::BTreeMap;
16use alloc::fmt::Debug;
17use alloc::string::String;
18use alloc::vec::Vec;
19
20use rand::{CryptoRng, RngCore};
21use serde::{Deserialize, Serialize};
22
23/// Possible encryption modes.
24#[derive(Serialize, Deserialize, Debug, Eq, PartialEq, Clone, Copy)]
25pub enum Mode {
26    /// The payload is a stream, processed in segments.
27    Streaming {
28        /// The size of segments.
29        segment_size: u32,
30
31        /// Possible size hint about the payload in the form (min, max), defaults to (0, None).
32        ///
33        /// Can be used to allocate memory beforehand, saving re-allocations.
34        size_hint: (u64, Option<u64>),
35    },
36
37    /// The payload is processed fully in memory, its size is known beforehand.
38    InMemory {
39        /// The size of the payload.
40        size: u32,
41    },
42}
43
44impl Default for Mode {
45    fn default() -> Self {
46        Mode::Streaming {
47            segment_size: SYMMETRIC_CRYPTO_DEFAULT_CHUNK,
48            size_hint: (0, None),
49        }
50    }
51}
52
53/// An initialization vector (IV).
54#[derive(Debug, Eq, PartialEq, Clone, Copy)]
55pub struct Iv<const N: usize>(pub [u8; N]);
56
57impl<const N: usize> Iv<N> {
58    fn random<R: RngCore + CryptoRng>(r: &mut R) -> Self {
59        let mut buf = [0u8; N];
60        r.fill_bytes(&mut buf);
61        Self(buf)
62    }
63}
64
65// The IV is not secret but we do want to have the possibility to encode it as human-readable.
66impl<const N: usize> Serialize for Iv<N> {
67    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
68    where
69        S: serde::Serializer,
70    {
71        serialize_bin_or_b64(&self.0, serializer)
72    }
73}
74
75impl<'de, const N: usize> Deserialize<'de> for Iv<N> {
76    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
77    where
78        D: serde::Deserializer<'de>,
79    {
80        let mut buf = [0u8; N];
81        deserialize_bin_or_b64(&mut buf, deserializer)?;
82
83        Ok(Self(buf))
84    }
85}
86
87/// Supported symmetric-key encryption algorithms.
88// We only target 128-bit security because it more closely matches the security target BLS12-381.
89#[derive(Serialize, Deserialize, Debug, Eq, PartialEq, Clone, Copy)]
90pub enum Algorithm {
91    /// AES-128-GCM.
92    // Good performance with hardware acceleration.
93    Aes128Gcm(Iv<12>),
94}
95
96impl Algorithm {
97    fn new_aes128_gcm<R: RngCore + CryptoRng>(r: &mut R) -> Self {
98        Self::Aes128Gcm(Iv::random(r))
99    }
100}
101
102/// A header contains header data for _all_ recipients.
103#[derive(Debug, Serialize, Deserialize, Clone)]
104pub struct Header {
105    /// Map of recipient identifiers to [`RecipientHeader`]s.
106    pub recipients: BTreeMap<String, RecipientHeader>,
107
108    /// The symmetric-key encryption algorithm used.
109    pub algo: Algorithm,
110
111    /// The encryption mode.
112    #[serde(default)]
113    pub mode: Mode,
114}
115
116/// Contains header data specific to _one_ recipient.
117#[derive(Serialize, Deserialize, Clone, Debug)]
118pub struct RecipientHeader {
119    /// The [`HiddenPolicy`] associated with this identifier.
120    pub policy: HiddenPolicy,
121
122    /// Ciphertext for this specific recipient.
123    pub ct: MultiRecipientCiphertext<CGWKV>,
124}
125
126impl RecipientHeader {
127    /// Decapsulates a [`ibe::kem::SharedSecret`] from a [`RecipientHeader`].
128    ///
129    /// These bytes can either directly be used for an AEAD, or a key derivation function.
130    pub fn decaps(&self, usk: &UserSecretKey<CGWKV>) -> Result<SharedSecret, Error> {
131        CGWKV::multi_decaps(None, &usk.0, &self.ct.0).map_err(|_e| Error::KEM)
132    }
133}
134
135impl Header {
136    /// Creates a new [`Header`] using the Master Public Key and the policies.
137    pub fn new<R: RngCore + CryptoRng>(
138        pk: &PublicKey<CGWKV>,
139        policies: &EncryptionPolicy,
140        rng: &mut R,
141    ) -> Result<(Self, SharedSecret), Error> {
142        // Map each RecipientPolicy to an IBE identity.
143        let ids = policies
144            .values()
145            .map(Policy::derive_kem::<CGWKV>)
146            .collect::<Result<Vec<<CGWKV as IBKEM>::Id>, _>>()?;
147
148        // Generate the shared secret and ciphertexts.
149        let (cts, ss) = CGWKV::multi_encaps(&pk.0, &ids[..], rng);
150
151        // Generate all RecipientHeaders.
152        let recipient_info: BTreeMap<String, RecipientHeader> = policies
153            .iter()
154            .zip(cts)
155            .map(|((rid, policy), ct)| {
156                (
157                    rid.clone(),
158                    RecipientHeader {
159                        policy: policy.to_hidden(),
160                        ct: MultiRecipientCiphertext(ct),
161                    },
162                )
163            })
164            .collect();
165
166        Ok((
167            Header {
168                recipients: recipient_info,
169                algo: Algorithm::new_aes128_gcm(rng),
170                mode: Mode::default(),
171            },
172            ss,
173        ))
174    }
175
176    /// Set the encryption mode.
177    pub fn with_mode(mut self, mode: Mode) -> Self {
178        self.mode = mode;
179        self
180    }
181
182    /// Set the encryption algorithm.
183    pub fn with_algo(mut self, algo: Algorithm) -> Self {
184        self.algo = algo;
185        self
186    }
187}
188
189/// An IBS signature, extended with the identity claims.
190#[derive(Debug, Clone, Serialize, Deserialize)]
191pub struct SignatureExt {
192    /// The identity-based signature.
193    pub sig: Signature,
194
195    /// The claimed identity as a [`Policy`] associated with this signature.
196    pub pol: Policy,
197}
198
199#[cfg(test)]
200mod tests {
201    use super::*;
202    use crate::test::TestSetup;
203
204    #[test]
205    fn test_enc_dec_json() {
206        let mut rng = rand::thread_rng();
207        let setup = TestSetup::new(&mut rng);
208
209        let (header, _ss) = Header::new(&setup.ibe_pk, &setup.policy, &mut rng).unwrap();
210        let header2 = header.clone();
211
212        let s = serde_json::to_string(&header).unwrap();
213        let decoded: Header = serde_json::from_str(&s).unwrap();
214
215        assert_eq!(decoded.recipients.len(), 2);
216
217        assert_eq!(
218            &decoded.recipients.get("Bob").unwrap().policy,
219            &setup.policy.get("Bob").unwrap().to_hidden()
220        );
221
222        assert_eq!(&decoded.algo, &header2.algo);
223        assert_eq!(&decoded.mode, &header2.mode);
224    }
225
226    #[test]
227    fn test_enc_dec_binary() {
228        let mut rng = rand::thread_rng();
229        let setup = TestSetup::new(&mut rng);
230
231        let (header, _ss) = Header::new(&setup.ibe_pk, &setup.policy, &mut rng).unwrap();
232        let header2 = header.clone();
233
234        let v = bincode::serialize(&header).unwrap();
235        let decoded: Header = bincode::deserialize(&v).unwrap();
236
237        assert_eq!(decoded.recipients.len(), 2);
238        assert_eq!(
239            &decoded.recipients.get("Charlie").unwrap().policy,
240            &setup.policy.get("Charlie").unwrap().to_hidden()
241        );
242        assert_eq!(&decoded.algo, &header2.algo);
243        assert_eq!(&decoded.mode, &header2.mode);
244    }
245
246    #[test]
247    fn test_round() {
248        // This test tests that both encoding methods derive the same keys as the sender.
249
250        let mut rng = rand::thread_rng();
251        let setup = TestSetup::new(&mut rng);
252
253        // Take Bob's usk for email + name.
254        let test_usk = &setup.usks[2];
255
256        let (header, ss1) = Header::new(&setup.ibe_pk, &setup.policy, &mut rng).unwrap();
257        let header2 = header.clone();
258        let header3 = header.clone();
259
260        // encode as binary
261        let bytes = bincode::serialize(&header).unwrap();
262
263        // encode as JSON
264        let json = serde_json::to_string(&header2).unwrap();
265
266        let decoded1: Header = bincode::deserialize(&bytes).unwrap();
267        let ss2 = decoded1
268            .recipients
269            .get("Bob")
270            .unwrap()
271            .decaps(test_usk)
272            .unwrap();
273
274        let decoded2: Header = serde_json::from_str(&json).unwrap();
275        let ss3 = decoded2
276            .recipients
277            .get("Bob")
278            .unwrap()
279            .decaps(test_usk)
280            .unwrap();
281
282        assert_eq!(&decoded1.recipients.len(), &header3.recipients.len());
283        assert_eq!(&decoded1.algo, &header3.algo);
284        assert_eq!(&decoded1.mode, &header3.mode);
285
286        // Make sure we derive the same keys.
287        assert_eq!(&ss1, &ss2);
288        assert_eq!(&ss1, &ss3);
289    }
290}
pg_core/client/header.rs

pg_core/client/
header.rs
