1use super::age_seal::{AgeIdentities, AgeRecipients};
18use aes_gcm_siv::{
19 aead::{Aead, KeyInit, Payload},
20 Aes256GcmSiv, Nonce,
21};
22use anyhow::{anyhow, ensure, Context, Result};
23use hkdf::Hkdf;
24use rand::RngCore as _;
25use sha2::Sha256;
26use std::{ffi::OsString, path::PathBuf, sync::Arc};
27use zeroize::{ZeroizeOnDrop, Zeroizing};
28
29pub const AGE_RECIPIENTS_ENV: &str = "HYPRSTREAM_USERSTORE_AGE_RECIPIENTS";
30pub const AGE_IDENTITIES_ENV: &str = "HYPRSTREAM_USERSTORE_AGE_IDENTITIES";
31
32pub(crate) const ROOT_DEK_BYTES: usize = 32;
33const NONCE_BYTES: usize = 12;
34const TAG_BYTES: usize = 16;
35const CIPHERTEXT_MAGIC: &[u8; 4] = b"HSC1";
36const CIPHERTEXT_HEADER_BYTES: usize = CIPHERTEXT_MAGIC.len() + NONCE_BYTES;
37const MAX_WRAPPED_DEK_BYTES: usize = 64 * 1024;
38const MAX_COLUMN_PLAINTEXT_BYTES: usize = 1024 * 1024;
39const FIELD_KEY_SALT: &[u8] = b"hyprstream.userstore.field-key.v1";
40const FIELD_CONTEXT_DOMAIN: &[u8] = b"hyprstream.userstore.column.v1";
41
42#[derive(Clone, Debug, Eq, PartialEq)]
50pub struct UserStoreEncryptionConfig {
51 recipients: AgeRecipients,
52 identities: AgeIdentities,
53}
54
55impl UserStoreEncryptionConfig {
56 pub fn new(recipients: Vec<String>, identities: Vec<PathBuf>) -> Result<Self> {
57 Ok(Self {
58 recipients: AgeRecipients::new(recipients)
59 .context("invalid UserStore age recipients")?,
60 identities: AgeIdentities::new(identities)
61 .context("invalid UserStore age identities")?,
62 })
63 }
64
65 pub fn from_env() -> Result<Self> {
70 let recipients = std::env::var(AGE_RECIPIENTS_ENV)
71 .with_context(|| format!("{AGE_RECIPIENTS_ENV} is required"))?
72 .split([',', '\n'])
73 .map(str::trim)
74 .filter(|value| !value.is_empty())
75 .map(str::to_owned)
76 .collect();
77 let identity_list: OsString = std::env::var_os(AGE_IDENTITIES_ENV)
78 .ok_or_else(|| anyhow!("{AGE_IDENTITIES_ENV} is required"))?;
79 let identities = std::env::split_paths(&identity_list).collect();
80 Self::new(recipients, identities)
81 }
82}
83
84#[derive(Clone, Copy, Debug)]
92pub(crate) enum EncryptedColumn<'a> {
93 ProfileName,
95 ProfileEmail,
97 ProfileExternalId,
99 PublicKey { fingerprint: &'a str },
101 PublicKeyLabel { fingerprint: &'a str },
103 PqPublicKey { fingerprint: &'a str },
105}
106
107impl<'a> EncryptedColumn<'a> {
108 fn tag(self) -> &'static [u8] {
109 match self {
110 Self::ProfileName => b"users.name",
111 Self::ProfileEmail => b"users.email",
112 Self::ProfileExternalId => b"users.external_id",
113 Self::PublicKey { .. } => b"pubkeys.pubkey",
114 Self::PublicKeyLabel { .. } => b"pubkeys.label",
115 Self::PqPublicKey { .. } => b"pubkeys.pq_pubkey",
116 }
117 }
118
119 fn row_binding(self) -> Option<&'static str> {
120 match self {
124 Self::ProfileName | Self::ProfileEmail | Self::ProfileExternalId => None,
125 Self::PublicKey { .. } | Self::PublicKeyLabel { .. } | Self::PqPublicKey { .. } => {
126 Some("fingerprint")
127 }
128 }
129 }
130
131 fn row_value(self) -> Option<&'a str> {
132 match self {
133 Self::ProfileName | Self::ProfileEmail | Self::ProfileExternalId => None,
134 Self::PublicKey { fingerprint }
135 | Self::PublicKeyLabel { fingerprint }
136 | Self::PqPublicKey { fingerprint } => Some(fingerprint),
137 }
138 }
139}
140
141pub(crate) trait DekSealer: Send + Sync {
142 fn seal(&self, plaintext: &[u8]) -> Result<Vec<u8>>;
143 fn open(&self, ciphertext: &[u8]) -> Result<Zeroizing<Vec<u8>>>;
144}
145
146struct TrustMintAgeDekSealer {
148 config: UserStoreEncryptionConfig,
149}
150
151impl TrustMintAgeDekSealer {
152 fn new(config: UserStoreEncryptionConfig) -> Self {
153 Self { config }
154 }
155}
156
157impl DekSealer for TrustMintAgeDekSealer {
158 fn seal(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
159 self.config
160 .recipients
161 .seal(plaintext, MAX_WRAPPED_DEK_BYTES)
162 .context("seal UserStore DEK through deployment trust")
163 }
164
165 fn open(&self, ciphertext: &[u8]) -> Result<Zeroizing<Vec<u8>>> {
166 ensure!(
167 !ciphertext.is_empty() && ciphertext.len() <= MAX_WRAPPED_DEK_BYTES,
168 "wrapped UserStore DEK has invalid size"
169 );
170 let plaintext = self
171 .config
172 .identities
173 .open(ciphertext, ROOT_DEK_BYTES)
174 .context("open UserStore DEK through deployment trust")?;
175 ensure!(
176 plaintext.len() == ROOT_DEK_BYTES,
177 "unwrapped UserStore DEK has invalid length"
178 );
179 Ok(plaintext)
180 }
181}
182
183pub(crate) struct NewUserKey {
184 pub root: Zeroizing<[u8; ROOT_DEK_BYTES]>,
185 pub wrapped: Vec<u8>,
186}
187
188#[derive(Clone)]
191pub(crate) struct ColumnCipher {
192 sealer: Arc<dyn DekSealer>,
193}
194
195impl ColumnCipher {
196 fn from_age_config(config: UserStoreEncryptionConfig) -> Self {
197 Self::new(Arc::new(TrustMintAgeDekSealer::new(config)))
198 }
199
200 pub(crate) fn from_deployment_env() -> Result<Self> {
201 Ok(Self::from_age_config(UserStoreEncryptionConfig::from_env()?))
202 }
203
204 pub(crate) fn new(sealer: Arc<dyn DekSealer>) -> Self {
205 Self { sealer }
206 }
207
208 pub(crate) async fn create_user_key(&self) -> Result<NewUserKey> {
209 let mut root = Zeroizing::new([0u8; ROOT_DEK_BYTES]);
210 rand::rngs::OsRng.fill_bytes(&mut *root);
211 let sealer = Arc::clone(&self.sealer);
212 let seal_input = Zeroizing::new(root.to_vec());
213 let wrapped = tokio::task::spawn_blocking(move || sealer.seal(&seal_input))
214 .await
215 .context("join age DEK sealing task")??;
216 ensure!(
217 !wrapped
218 .windows(ROOT_DEK_BYTES)
219 .any(|window| window == root.as_slice()),
220 "age returned a wrapped DEK containing its plaintext"
221 );
222 Ok(NewUserKey { root, wrapped })
223 }
224
225 pub(crate) async fn open_user_key(
226 &self,
227 wrapped: &[u8],
228 ) -> Result<Zeroizing<[u8; ROOT_DEK_BYTES]>> {
229 let sealer = Arc::clone(&self.sealer);
230 let wrapped = wrapped.to_vec();
231 let plaintext = tokio::task::spawn_blocking(move || sealer.open(&wrapped))
232 .await
233 .context("join age DEK unsealing task")??;
234 plaintext
235 .as_slice()
236 .try_into()
237 .map(Zeroizing::new)
238 .map_err(|_| anyhow!("unwrapped UserStore DEK has invalid length"))
239 }
240
241 pub(crate) fn encrypt(
242 &self,
243 root: &[u8; ROOT_DEK_BYTES],
244 username: &str,
245 column: EncryptedColumn<'_>,
246 plaintext: &[u8],
247 ) -> Result<Vec<u8>> {
248 ensure!(
249 plaintext.len() <= MAX_COLUMN_PLAINTEXT_BYTES,
250 "UserStore column plaintext exceeds size limit"
251 );
252 let context = field_context(username, column)?;
253 let key = derive_field_key(root, &context)?;
254 let cipher = Aes256GcmSiv::new_from_slice(&*key)
255 .map_err(|_| anyhow!("initialize UserStore column cipher"))?;
256 let mut nonce = [0u8; NONCE_BYTES];
257 rand::rngs::OsRng.fill_bytes(&mut nonce);
258 let encrypted = cipher
259 .encrypt(
260 Nonce::from_slice(&nonce),
261 Payload {
262 msg: plaintext,
263 aad: &context,
264 },
265 )
266 .map_err(|_| anyhow!("encrypt UserStore value column"))?;
267 let mut output = Vec::with_capacity(CIPHERTEXT_HEADER_BYTES + encrypted.len());
268 output.extend_from_slice(CIPHERTEXT_MAGIC);
269 output.extend_from_slice(&nonce);
270 output.extend_from_slice(&encrypted);
271 Ok(output)
272 }
273
274 pub(crate) fn decrypt(
275 &self,
276 root: &[u8; ROOT_DEK_BYTES],
277 username: &str,
278 column: EncryptedColumn<'_>,
279 ciphertext: &[u8],
280 ) -> Result<Zeroizing<Vec<u8>>> {
281 ensure!(
282 ciphertext.len() >= CIPHERTEXT_HEADER_BYTES + TAG_BYTES
283 && ciphertext.len()
284 <= CIPHERTEXT_HEADER_BYTES + MAX_COLUMN_PLAINTEXT_BYTES + TAG_BYTES,
285 "UserStore column ciphertext has invalid size"
286 );
287 ensure!(
288 ciphertext.starts_with(CIPHERTEXT_MAGIC),
289 "UserStore column ciphertext has invalid version"
290 );
291 let context = field_context(username, column)?;
292 let key = derive_field_key(root, &context)?;
293 let cipher = Aes256GcmSiv::new_from_slice(&*key)
294 .map_err(|_| anyhow!("initialize UserStore column cipher"))?;
295 let nonce = Nonce::from_slice(&ciphertext[CIPHERTEXT_MAGIC.len()..CIPHERTEXT_HEADER_BYTES]);
296 let plaintext = cipher
297 .decrypt(
298 nonce,
299 Payload {
300 msg: &ciphertext[CIPHERTEXT_HEADER_BYTES..],
301 aad: &context,
302 },
303 )
304 .map_err(|_| anyhow!("authenticate/decrypt UserStore value column"))?;
305 Ok(Zeroizing::new(plaintext))
306 }
307
308 pub(crate) fn seal_text(
314 &self,
315 root: &Zeroizing<[u8; ROOT_DEK_BYTES]>,
316 username: &str,
317 column: EncryptedColumn<'_>,
318 value: Option<String>,
319 ) -> Result<Option<Vec<u8>>> {
320 match value {
321 None => Ok(None),
322 Some(text) => Ok(Some(self.encrypt(
323 root,
324 username,
325 column,
326 text.as_bytes(),
327 )?)),
328 }
329 }
330
331 pub(crate) fn open_text(
333 &self,
334 root: &Zeroizing<[u8; ROOT_DEK_BYTES]>,
335 username: &str,
336 column: EncryptedColumn<'_>,
337 raw: Option<Vec<u8>>,
338 ) -> Result<Option<String>> {
339 match raw {
340 None => Ok(None),
341 Some(bytes) => self
342 .decrypt(root, username, column, &bytes)
343 .and_then(zeroizing_bytes_into_string)
344 .map(Some),
345 }
346 }
347
348 pub(crate) fn seal_raw(
350 &self,
351 root: &Zeroizing<[u8; ROOT_DEK_BYTES]>,
352 username: &str,
353 column: EncryptedColumn<'_>,
354 value: &[u8],
355 ) -> Result<Vec<u8>> {
356 self.encrypt(root, username, column, value)
357 }
358
359 pub(crate) fn open_raw(
361 &self,
362 root: &Zeroizing<[u8; ROOT_DEK_BYTES]>,
363 username: &str,
364 column: EncryptedColumn<'_>,
365 raw: &[u8],
366 ) -> Result<Zeroizing<Vec<u8>>> {
367 self.decrypt(root, username, column, raw)
368 }
369
370 #[cfg(test)]
372 pub(crate) fn test_cipher() -> Self {
373 Self::new(Arc::new(TestDekSealer))
374 }
375}
376
377#[cfg(test)]
379struct TestDekSealer;
380
381#[cfg(test)]
382impl DekSealer for TestDekSealer {
383 fn seal(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
384 let cipher = Aes256GcmSiv::new_from_slice(&TEST_KEK)
385 .map_err(|_| anyhow!("initialize test DEK sealer"))?;
386 let mut nonce = [0u8; NONCE_BYTES];
387 rand::rngs::OsRng.fill_bytes(&mut nonce);
388 let ct = cipher
389 .encrypt(
390 Nonce::from_slice(&nonce),
391 Payload {
392 msg: plaintext,
393 aad: TEST_WRAP_AAD,
394 },
395 )
396 .map_err(|_| anyhow!("seal test DEK"))?;
397 let mut out = nonce.to_vec();
398 out.extend_from_slice(&ct);
399 Ok(out)
400 }
401
402 fn open(&self, ciphertext: &[u8]) -> Result<Zeroizing<Vec<u8>>> {
403 ensure!(
404 ciphertext.len() >= NONCE_BYTES + TAG_BYTES,
405 "test wrapped key is truncated"
406 );
407 let cipher = Aes256GcmSiv::new_from_slice(&TEST_KEK)
408 .map_err(|_| anyhow!("initialize test DEK sealer"))?;
409 let plaintext = cipher
410 .decrypt(
411 Nonce::from_slice(&ciphertext[..NONCE_BYTES]),
412 Payload {
413 msg: &ciphertext[NONCE_BYTES..],
414 aad: TEST_WRAP_AAD,
415 },
416 )
417 .map_err(|_| anyhow!("test wrapped key authentication failed"))?;
418 Ok(Zeroizing::new(plaintext))
419 }
420}
421
422#[cfg(test)]
423const TEST_KEK: [u8; ROOT_DEK_BYTES] = [0xA7; ROOT_DEK_BYTES];
424#[cfg(test)]
425const TEST_WRAP_AAD: &[u8] = b"hyprstream.userstore.test-wrap.v1";
426
427fn zeroizing_bytes_into_string(mut plaintext: Zeroizing<Vec<u8>>) -> Result<String> {
428 match String::from_utf8(std::mem::take(&mut *plaintext)) {
429 Ok(value) => Ok(value),
430 Err(error) => {
431 let _invalid_plaintext = Zeroizing::new(error.into_bytes());
432 Err(anyhow!("decrypted UserStore text is not UTF-8"))
433 }
434 }
435}
436
437const _: fn() = || {
441 fn assert_zeroize_on_drop<T: ZeroizeOnDrop>() {}
442 assert_zeroize_on_drop::<aes::Aes256>();
443};
444
445fn field_context(username: &str, column: EncryptedColumn<'_>) -> Result<Vec<u8>> {
446 ensure!(
447 !username.is_empty(),
448 "encrypted UserStore username is empty"
449 );
450 let mut context = Vec::with_capacity(128);
451 append_context_part(&mut context, FIELD_CONTEXT_DOMAIN)?;
452 append_context_part(&mut context, username.as_bytes())?;
453 append_context_part(&mut context, column.tag())?;
454 if let Some(row_binding) = column.row_binding() {
455 append_context_part(&mut context, row_binding.as_bytes())?;
456 append_context_part(
457 &mut context,
458 column
459 .row_value()
460 .ok_or_else(|| anyhow!("encrypted UserStore row binding is absent"))?
461 .as_bytes(),
462 )?;
463 }
464 Ok(context)
465}
466
467fn append_context_part(output: &mut Vec<u8>, value: &[u8]) -> Result<()> {
468 let length = u32::try_from(value.len()).context("UserStore encryption context is too large")?;
469 output.extend_from_slice(&length.to_be_bytes());
470 output.extend_from_slice(value);
471 Ok(())
472}
473
474fn derive_field_key(
475 root: &[u8; ROOT_DEK_BYTES],
476 context: &[u8],
477) -> Result<Zeroizing<[u8; ROOT_DEK_BYTES]>> {
478 let hkdf = Hkdf::<Sha256>::new(Some(FIELD_KEY_SALT), root);
479 let mut key = Zeroizing::new([0u8; ROOT_DEK_BYTES]);
480 hkdf.expand(context, &mut *key)
481 .map_err(|_| anyhow!("derive UserStore per-field key"))?;
482 Ok(key)
483}
484
485#[cfg(test)]
486#[allow(clippy::unwrap_used, clippy::expect_used, clippy::op_ref)]
487mod tests {
488 use super::*;
489
490 struct FailableTestSealer {
492 fail_open: bool,
493 }
494
495 impl DekSealer for FailableTestSealer {
496 fn seal(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
497 let cipher = Aes256GcmSiv::new_from_slice(&TEST_KEK).unwrap();
498 let mut nonce = [0u8; NONCE_BYTES];
499 rand::rngs::OsRng.fill_bytes(&mut nonce);
500 let encrypted = cipher
501 .encrypt(
502 Nonce::from_slice(&nonce),
503 Payload {
504 msg: plaintext,
505 aad: TEST_WRAP_AAD,
506 },
507 )
508 .unwrap();
509 let mut output = nonce.to_vec();
510 output.extend_from_slice(&encrypted);
511 Ok(output)
512 }
513
514 fn open(&self, ciphertext: &[u8]) -> Result<Zeroizing<Vec<u8>>> {
515 if self.fail_open {
516 anyhow::bail!("test key material is unavailable");
517 }
518 ensure!(
519 ciphertext.len() >= NONCE_BYTES + TAG_BYTES,
520 "test wrapped key is truncated"
521 );
522 let cipher = Aes256GcmSiv::new_from_slice(&TEST_KEK).unwrap();
523 let plaintext = cipher
524 .decrypt(
525 Nonce::from_slice(&ciphertext[..NONCE_BYTES]),
526 Payload {
527 msg: &ciphertext[NONCE_BYTES..],
528 aad: TEST_WRAP_AAD,
529 },
530 )
531 .map_err(|_| anyhow!("test wrapped key authentication failed"))?;
532 Ok(Zeroizing::new(plaintext))
533 }
534 }
535
536 fn cipher() -> ColumnCipher {
537 ColumnCipher::test_cipher()
538 }
539
540 #[tokio::test]
541 async fn envelope_and_field_round_trip_contains_no_plaintext() {
542 let cipher = cipher();
543 let key = cipher.create_user_key().await.unwrap();
544 let email = Zeroizing::new(b"private.person@example.test".to_vec());
545 let encrypted = cipher
546 .encrypt(
547 &key.root,
548 "private-person",
549 EncryptedColumn::ProfileEmail,
550 &email,
551 )
552 .unwrap();
553
554 assert!(!key.wrapped.windows(key.root.len()).any(|w| w == &*key.root));
555 assert!(!encrypted.windows(email.len()).any(|w| w == &**email));
556 let opened = cipher.open_user_key(&key.wrapped).await.unwrap();
557 let decrypted = cipher
558 .decrypt(
559 &opened,
560 "private-person",
561 EncryptedColumn::ProfileEmail,
562 &encrypted,
563 )
564 .unwrap();
565 assert_eq!(&*decrypted, &**email);
566 }
567
568 #[tokio::test]
569 async fn ciphertext_is_bound_to_user_column_and_lookup_key() {
570 let cipher = cipher();
571 let key = cipher.create_user_key().await.unwrap();
572 let encrypted = cipher
573 .encrypt(
574 &key.root,
575 "alice",
576 EncryptedColumn::PublicKey {
577 fingerprint: "key-a",
578 },
579 &[0x42; 32],
580 )
581 .unwrap();
582
583 assert!(cipher
584 .decrypt(
585 &key.root,
586 "bob",
587 EncryptedColumn::PublicKey {
588 fingerprint: "key-a"
589 },
590 &encrypted
591 )
592 .is_err());
593 assert!(cipher
594 .decrypt(
595 &key.root,
596 "alice",
597 EncryptedColumn::PublicKeyLabel {
598 fingerprint: "key-a"
599 },
600 &encrypted
601 )
602 .is_err());
603 assert!(cipher
604 .decrypt(
605 &key.root,
606 "alice",
607 EncryptedColumn::PublicKey {
608 fingerprint: "key-b"
609 },
610 &encrypted
611 )
612 .is_err());
613 }
614
615 #[tokio::test]
616 async fn tampering_and_unavailable_key_material_fail_closed() {
617 let cipher = cipher();
618 let key = cipher.create_user_key().await.unwrap();
619 let mut encrypted = cipher
620 .encrypt(
621 &key.root,
622 "alice",
623 EncryptedColumn::ProfileEmail,
624 b"sensitive-id",
625 )
626 .unwrap();
627 let last = encrypted.last_mut().unwrap();
628 *last ^= 1;
629 assert!(cipher
630 .decrypt(
631 &key.root,
632 "alice",
633 EncryptedColumn::ProfileEmail,
634 &encrypted
635 )
636 .is_err());
637
638 let unavailable = ColumnCipher::new(Arc::new(FailableTestSealer { fail_open: true }));
639 assert!(unavailable.open_user_key(&key.wrapped).await.is_err());
640 }
641
642 #[test]
643 fn configuration_rejects_absent_or_invalid_key_material() {
644 assert!(UserStoreEncryptionConfig::new(Vec::new(), Vec::new()).is_err());
645 assert!(UserStoreEncryptionConfig::new(
646 vec!["age1valid-looking-recipient".to_owned()],
647 vec![PathBuf::from("/definitely/not/an/identity")],
648 )
649 .is_err());
650 }
651}