1use std::io::{self, Read, Write};
2
3use hide_crypto::{
4 ChunkCipher, ContentKey, CryptoError, DerivedKey, RecipientPublic, RecipientSecret,
5};
6use hide_format::{
7 CHUNK_LEN, FormatError, MAX_RECIPIENTS, PREAMBLE_LEN, RecipientStanza, SUITE, SignatureStanza,
8 TAG_LEN,
9};
10pub use hide_format::{Extension, Metadata, Preamble, ProtectedHeader, Stanza, UnknownStanza};
11use hide_sign::{SigningIdentity, VerifyingIdentity};
12use thiserror::Error;
13use zeroize::Zeroizing;
14
15const DATA: u8 = 1;
16const FINAL: u8 = 2;
17const MAX_CHUNKS: u64 = 1 << 32;
18pub const MAX_SIGNED_INPUT: u64 = 1 << 30;
21const RECORD_LEN: usize = CHUNK_LEN + TAG_LEN;
22const CHUNK_AAD_LEN: usize = 91;
23const SIGNING_CONTEXT: &[u8] = b"HIDE/1.0 container";
24const LEGACY_SIGNING_CONTEXT: &[u8] = b"HIDE/0.5 container";
26
27#[derive(Debug, Error)]
28pub enum ObjectError {
29 #[error(transparent)]
30 Format(#[from] FormatError),
31 #[error(transparent)]
32 Crypto(#[from] CryptoError),
33 #[error("I/O operation failed: {0}")]
34 Io(#[from] io::Error),
35 #[error("no matching recipient or invalid header authentication")]
36 NoMatchingRecipient,
37 #[error("truncated payload")]
38 TruncatedPayload,
39 #[error("invalid payload record")]
40 InvalidRecord,
41 #[error("unexpected bytes after final record")]
42 TrailingData,
43 #[error("object exceeds the chunk limit")]
44 ObjectTooLarge,
45 #[error("recipient count must be between 1 and 64")]
46 InvalidRecipients,
47 #[error("signature does not verify")]
48 InvalidSignature,
49 #[error("container is signed but the reader was not asked to verify")]
50 UnexpectedSignature,
51 #[error("container is not signed")]
52 MissingSignature,
53}
54
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
58pub enum SignaturePlacement {
59 Public,
61 Confidential,
63 #[cfg(feature = "test-vectors")]
66 #[doc(hidden)]
67 Stripped,
68 #[cfg(feature = "test-vectors")]
71 #[doc(hidden)]
72 LegacyPublic,
73}
74
75#[derive(Debug, PartialEq, Eq)]
76pub struct VerifiedObject {
77 pub metadata: Metadata,
78 pub plaintext_len: u64,
79 pub signer: Option<VerifyingIdentity>,
81}
82
83struct ObjectMaterial {
84 cek: ContentKey,
85 object_id: [u8; 32],
86 payload_salt: [u8; 16],
87}
88
89pub fn encrypt<R: Read, W: Write>(
90 input: &mut R,
91 output: &mut W,
92 recipients: &[RecipientPublic],
93 metadata: &Metadata,
94) -> Result<u64, ObjectError> {
95 validate_recipients(recipients)?;
96 let material = ObjectMaterial {
97 cek: ContentKey::generate()?,
98 object_id: hide_crypto::random_array()?,
99 payload_salt: hide_crypto::random_array()?,
100 };
101 let stanzas = recipients
102 .iter()
103 .map(|recipient| {
104 hide_crypto::wrap_cek(recipient, &material.cek, &material.object_id).map(|wrapped| {
105 RecipientStanza {
106 encapsulation: wrapped.encapsulation,
107 wrapped_cek: wrapped.wrapped_cek,
108 }
109 })
110 })
111 .collect::<Result<Vec<_>, _>>()?;
112 encrypt_with_material(input, output, metadata, material, stanzas)
113}
114
115fn validate_recipients(recipients: &[RecipientPublic]) -> Result<(), ObjectError> {
116 if recipients.is_empty() || recipients.len() > MAX_RECIPIENTS {
117 return Err(ObjectError::InvalidRecipients);
118 }
119 Ok(())
120}
121
122pub fn encrypt_signed<R: Read, W: Write>(
125 input: &mut R,
126 output: &mut W,
127 recipients: &[RecipientPublic],
128 metadata: &Metadata,
129 identity: &SigningIdentity,
130 placement: SignaturePlacement,
131) -> Result<u64, ObjectError> {
132 validate_recipients(recipients)?;
133 let material = ObjectMaterial {
134 cek: ContentKey::generate()?,
135 object_id: hide_crypto::random_array()?,
136 payload_salt: hide_crypto::random_array()?,
137 };
138 let stanzas = recipients
139 .iter()
140 .map(|recipient| {
141 hide_crypto::wrap_cek(recipient, &material.cek, &material.object_id).map(|wrapped| {
142 RecipientStanza {
143 encapsulation: wrapped.encapsulation,
144 wrapped_cek: wrapped.wrapped_cek,
145 }
146 })
147 })
148 .collect::<Result<Vec<_>, _>>()?;
149 encrypt_inner(
150 input,
151 output,
152 metadata,
153 material,
154 stanzas,
155 Some((identity, placement)),
156 &VectorShape::default(),
157 )
158}
159
160fn encrypt_with_material<R: Read, W: Write>(
161 input: &mut R,
162 output: &mut W,
163 metadata: &Metadata,
164 material: ObjectMaterial,
165 recipients: Vec<RecipientStanza>,
166) -> Result<u64, ObjectError> {
167 encrypt_inner(
168 input,
169 output,
170 metadata,
171 material,
172 recipients,
173 None,
174 &VectorShape::default(),
175 )
176}
177
178#[derive(Debug, Clone)]
182#[doc(hidden)]
183pub struct VectorShape {
184 pub minor: u8,
185 pub header_extensions: Vec<hide_format::Extension>,
186 pub leading_stanzas: Vec<Stanza>,
187}
188
189impl Default for VectorShape {
190 fn default() -> Self {
191 Self {
192 minor: hide_format::CURRENT_MINOR,
193 header_extensions: Vec::new(),
194 leading_stanzas: Vec::new(),
195 }
196 }
197}
198
199fn transcript(
213 preamble: Preamble,
214 header: &ProtectedHeader,
215 metadata_base: &[u8],
216 plaintext_hash: &[u8; 32],
217 plaintext_len: u64,
218) -> Vec<u8> {
219 if preamble.is_legacy() {
220 return legacy_transcript(header, metadata_base, plaintext_hash, plaintext_len);
221 }
222 let mut message = Vec::new();
223 message.extend_from_slice(b"HIDE/1.0 transcript");
224 message.extend_from_slice(&preamble.signed_prefix());
225 message.extend_from_slice(&SUITE.to_be_bytes());
226 message.extend_from_slice(&header.object_id);
227 message.extend_from_slice(&(header.recipients.len() as u64).to_be_bytes());
228 for stanza in &header.recipients {
229 let fields = stanza.fields();
230 message.extend_from_slice(&u64::from(stanza.tag()).to_be_bytes());
231 message.extend_from_slice(&(fields.len() as u64).to_be_bytes());
232 for field in fields {
233 message.extend_from_slice(&(field.len() as u64).to_be_bytes());
234 message.extend_from_slice(field);
235 }
236 }
237 message.extend_from_slice(&(header.extensions.len() as u64).to_be_bytes());
238 for extension in &header.extensions {
239 message.extend_from_slice(&extension.key.to_be_bytes());
240 message.extend_from_slice(&(extension.value.len() as u64).to_be_bytes());
241 message.extend_from_slice(&extension.value);
242 }
243 message.extend_from_slice(&(metadata_base.len() as u64).to_be_bytes());
244 message.extend_from_slice(metadata_base);
245 message.extend_from_slice(plaintext_hash);
246 message.extend_from_slice(&plaintext_len.to_be_bytes());
247 message
248}
249
250fn legacy_transcript(
253 header: &ProtectedHeader,
254 metadata_base: &[u8],
255 plaintext_hash: &[u8; 32],
256 plaintext_len: u64,
257) -> Vec<u8> {
258 let mut message = Vec::new();
259 message.extend_from_slice(b"HIDE/0.5 transcript");
260 message.extend_from_slice(&SUITE.to_be_bytes());
261 message.extend_from_slice(&header.object_id);
262 message.extend_from_slice(&(header.recipients.len() as u64).to_be_bytes());
263 for stanza in header.recipients.iter().filter_map(Stanza::as_xwing) {
264 message.extend_from_slice(&stanza.encapsulation);
265 message.extend_from_slice(&stanza.wrapped_cek);
266 }
267 message.extend_from_slice(&(metadata_base.len() as u64).to_be_bytes());
268 message.extend_from_slice(metadata_base);
269 message.extend_from_slice(plaintext_hash);
270 message.extend_from_slice(&plaintext_len.to_be_bytes());
271 message
272}
273
274fn signing_context(preamble: Preamble) -> &'static [u8] {
275 if preamble.is_legacy() {
276 LEGACY_SIGNING_CONTEXT
277 } else {
278 SIGNING_CONTEXT
279 }
280}
281
282fn encrypt_inner<R: Read, W: Write>(
283 input: &mut R,
284 output: &mut W,
285 metadata: &Metadata,
286 material: ObjectMaterial,
287 recipients: Vec<RecipientStanza>,
288 signer: Option<(&SigningIdentity, SignaturePlacement)>,
289 shape: &VectorShape,
290) -> Result<u64, ObjectError> {
291 let mut plaintext = Zeroizing::new(Vec::new());
295 let (metadata, plaintext_hash, plaintext_len) = match signer {
296 None => (metadata.clone(), None, None),
297 Some(_) => {
298 input
299 .take(MAX_SIGNED_INPUT + 1)
300 .read_to_end(&mut plaintext)?;
301 if plaintext.len() as u64 > MAX_SIGNED_INPUT {
302 return Err(ObjectError::ObjectTooLarge);
303 }
304 let hash = hide_crypto::hash(&[&plaintext]);
305 (metadata.clone(), Some(hash), Some(plaintext.len() as u64))
306 }
307 };
308
309 let metadata_key =
310 hide_crypto::derive_key(&material.cek, &material.object_id, b"HIDE/0.1 metadata")?;
311
312 let base_metadata = Zeroizing::new(metadata.signing_base()?);
316 let mut header = ProtectedHeader {
317 object_id: material.object_id,
318 recipients: shape
319 .leading_stanzas
320 .iter()
321 .cloned()
322 .chain(recipients.into_iter().map(Stanza::from))
323 .collect(),
324 encrypted_metadata: Vec::new(),
325 signatures: Vec::new(),
326 extensions: shape.header_extensions.clone(),
327 };
328
329 #[cfg(feature = "test-vectors")]
332 let legacy = matches!(signer, Some((_, SignaturePlacement::LegacyPublic)));
333 #[cfg(not(feature = "test-vectors"))]
334 let legacy = false;
335 let preamble_for = |length: usize| -> Result<Preamble, FormatError> {
336 if legacy {
337 Preamble::legacy_signed(length)
338 } else {
339 let flags = if signer.is_some() {
340 hide_format::FLAG_SIGNED
341 } else {
342 0
343 };
344 Preamble::from_parts(length, shape.minor, flags)
345 }
346 };
347
348 let mut metadata = metadata;
349 if let Some((identity, placement)) = signer {
350 let provisional = preamble_for(1)?;
351 let message = transcript(
352 provisional,
353 &header,
354 &base_metadata,
355 &plaintext_hash.expect("set when signing"),
356 plaintext_len.expect("set when signing"),
357 );
358 let stanza = SignatureStanza {
359 verifying_key: identity.verifying_key().to_bytes().to_vec(),
360 signature: identity
361 .sign(signing_context(provisional), &message)
362 .to_vec(),
363 };
364 match placement {
365 SignaturePlacement::Public => header.signatures.push(stanza),
366 SignaturePlacement::Confidential => metadata.signature = Some(stanza),
367 #[cfg(feature = "test-vectors")]
368 SignaturePlacement::Stripped => drop(stanza),
369 #[cfg(feature = "test-vectors")]
370 SignaturePlacement::LegacyPublic => header.signatures.push(stanza),
371 }
372 }
373
374 let final_metadata = Zeroizing::new(metadata.encode()?);
376 header.encrypted_metadata = hide_crypto::seal(
377 &metadata_key,
378 &[0; 12],
379 &metadata_aad(&material.object_id),
380 &final_metadata,
381 )?;
382
383 let signed = signer.is_some();
384 let protected = header.encode()?;
385 let header_length = hide_format::encode_header(&protected, &[0; 32])?.len();
386 let preamble = preamble_for(header_length)?.encode();
387 let mac_key =
388 hide_crypto::derive_key(&material.cek, &material.object_id, b"HIDE/0.1 header-mac")?;
389 let mac = hide_crypto::mac(&mac_key, &[&preamble, &protected])?;
390 output.write_all(&preamble)?;
391 output.write_all(&hide_format::encode_header(&protected, &mac)?)?;
392 output.write_all(&material.payload_salt)?;
393 let key = payload_key(&material.cek, &material.object_id, &material.payload_salt)?;
394 let header_hash = hide_crypto::hash(&[&protected]);
395 if signed {
396 encrypt_records(
397 &mut plaintext.as_slice(),
398 output,
399 &key,
400 &material.object_id,
401 &header_hash,
402 )
403 } else {
404 encrypt_records(input, output, &key, &material.object_id, &header_hash)
405 }
406}
407
408pub fn decrypt_to_staging<R: Read, W: Write>(
412 input: &mut R,
413 staging: &mut W,
414 secret: &RecipientSecret,
415) -> Result<VerifiedObject, ObjectError> {
416 let mut preamble_bytes = [0; PREAMBLE_LEN];
417 input.read_exact(&mut preamble_bytes)?;
418 let preamble = Preamble::decode(&preamble_bytes)?;
419 let mut header_bytes = vec![0; preamble.header_len()];
420 input.read_exact(&mut header_bytes)?;
421 let (protected, mac) = hide_format::decode_header(&header_bytes)?;
422 let header = ProtectedHeader::decode(&protected)?;
423 if preamble.is_legacy()
426 && (!header.extensions.is_empty()
427 || header.recipients.iter().any(|s| s.as_xwing().is_none()))
428 {
429 return Err(FormatError::MalformedHeader.into());
430 }
431 let cek = recover_cek(secret, &header, &preamble_bytes, &protected, &mac)?;
432 let metadata_key = hide_crypto::derive_key(&cek, &header.object_id, b"HIDE/0.1 metadata")?;
433 let metadata_plaintext = hide_crypto::open(
434 &metadata_key,
435 &[0; 12],
436 &metadata_aad(&header.object_id),
437 &header.encrypted_metadata,
438 )?;
439 let metadata = Metadata::decode(&metadata_plaintext)?;
440 if preamble.is_legacy() && !metadata.extensions.is_empty() {
441 return Err(FormatError::InvalidMetadata.into());
442 }
443 let mut salt = [0; 16];
444 read_payload(input, &mut salt)?;
445 let key = payload_key(&cek, &header.object_id, &salt)?;
446
447 let mut hasher = PlaintextHasher::new(staging);
450 let plaintext_len = decrypt_records(
451 input,
452 &mut hasher,
453 &key,
454 &header.object_id,
455 &hide_crypto::hash(&[&protected]),
456 )?;
457 let plaintext_hash = hasher.finish();
458
459 let signer = verify_signature(preamble, &header, &metadata, &plaintext_hash, plaintext_len)?;
460 Ok(VerifiedObject {
461 metadata,
462 plaintext_len,
463 signer,
464 })
465}
466
467fn verify_signature(
470 preamble: Preamble,
471 header: &ProtectedHeader,
472 metadata: &Metadata,
473 plaintext_hash: &[u8; 32],
474 plaintext_len: u64,
475) -> Result<Option<VerifyingIdentity>, ObjectError> {
476 let preamble_says_signed = preamble.is_signed();
477 let stanza = match (header.signatures.first(), metadata.signature.as_ref()) {
478 (Some(_), Some(_)) => return Err(ObjectError::InvalidSignature),
479 (Some(stanza), None) | (None, Some(stanza)) => stanza,
480 (None, None) => {
481 return if preamble_says_signed {
484 Err(ObjectError::MissingSignature)
485 } else {
486 Ok(None)
487 };
488 }
489 };
490 if !preamble_says_signed {
491 return Err(ObjectError::UnexpectedSignature);
492 }
493
494 let identity = VerifyingIdentity::from_bytes(&stanza.verifying_key)
495 .map_err(|_| ObjectError::InvalidSignature)?;
496 let message = transcript(
497 preamble,
498 header,
499 &metadata.signing_base()?,
500 plaintext_hash,
501 plaintext_len,
502 );
503 identity
504 .verify(signing_context(preamble), &message, &stanza.signature)
505 .map_err(|_| ObjectError::InvalidSignature)?;
506 Ok(Some(identity))
507}
508
509fn recover_cek(
510 secret: &RecipientSecret,
511 header: &ProtectedHeader,
512 preamble: &[u8],
513 protected: &[u8],
514 mac: &[u8; 32],
515) -> Result<ContentKey, ObjectError> {
516 for stanza in header.recipients.iter().filter_map(Stanza::as_xwing) {
519 if let Ok(cek) = hide_crypto::unwrap_cek(
520 secret,
521 &header.object_id,
522 &stanza.encapsulation,
523 &stanza.wrapped_cek,
524 ) {
525 let key = hide_crypto::derive_key(&cek, &header.object_id, b"HIDE/0.1 header-mac")?;
526 if hide_crypto::verify_mac(&key, &[preamble, protected], mac).is_ok() {
527 return Ok(cek);
528 }
529 }
530 }
531 Err(ObjectError::NoMatchingRecipient)
532}
533
534struct PlaintextHasher<'a, W: Write> {
537 inner: &'a mut W,
538 hasher: hide_crypto::Hasher,
539}
540
541impl<'a, W: Write> PlaintextHasher<'a, W> {
542 fn new(inner: &'a mut W) -> Self {
543 Self {
544 inner,
545 hasher: hide_crypto::Hasher::new(),
546 }
547 }
548
549 fn finish(self) -> [u8; 32] {
550 self.hasher.finish()
551 }
552}
553
554impl<W: Write> Write for PlaintextHasher<'_, W> {
555 fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
556 let written = self.inner.write(buffer)?;
557 self.hasher.update(&buffer[..written]);
558 Ok(written)
559 }
560
561 fn flush(&mut self) -> io::Result<()> {
562 self.inner.flush()
563 }
564}
565
566fn metadata_aad(object_id: &[u8; 32]) -> Vec<u8> {
567 [
568 b"HIDE/0.1 metadata".as_slice(),
569 object_id,
570 &SUITE.to_be_bytes(),
571 ]
572 .concat()
573}
574
575fn payload_key(
576 cek: &ContentKey,
577 object_id: &[u8; 32],
578 salt: &[u8; 16],
579) -> Result<DerivedKey, CryptoError> {
580 hide_crypto::derive_key(
581 cek,
582 salt,
583 &[b"HIDE/0.1 payload".as_slice(), object_id].concat(),
584 )
585}
586
587fn nonce(counter: u64, kind: u8) -> [u8; 12] {
588 let mut nonce = [0; 12];
589 nonce[3..11].copy_from_slice(&counter.to_be_bytes());
590 nonce[11] = u8::from(kind == FINAL);
591 nonce
592}
593
594fn chunk_aad(
595 object_id: &[u8; 32],
596 header_hash: &[u8; 32],
597 counter: u64,
598 kind: u8,
599 length: usize,
600) -> [u8; CHUNK_AAD_LEN] {
601 let mut aad = [0; CHUNK_AAD_LEN];
602 aad[..14].copy_from_slice(b"HIDE/0.1 chunk");
603 aad[14..46].copy_from_slice(object_id);
604 aad[46..78].copy_from_slice(header_hash);
605 aad[78..86].copy_from_slice(&counter.to_be_bytes());
606 aad[86] = kind;
607 aad[87..].copy_from_slice(&(length as u32).to_be_bytes());
608 aad
609}
610
611fn read_chunk<R: Read>(reader: &mut R, buffer: &mut [u8]) -> Result<usize, io::Error> {
612 let mut length = 0;
613 while length < buffer.len() {
614 match reader.read(&mut buffer[length..]) {
615 Ok(0) => break,
616 Ok(count) => length += count,
617 Err(error) if error.kind() == io::ErrorKind::Interrupted => continue,
618 Err(error) => return Err(error),
619 }
620 }
621 Ok(length)
622}
623
624fn encrypt_records<R: Read, W: Write>(
625 input: &mut R,
626 output: &mut W,
627 key: &DerivedKey,
628 object_id: &[u8; 32],
629 header_hash: &[u8; 32],
630) -> Result<u64, ObjectError> {
631 let cipher = ChunkCipher::new(key)?;
632 let mut current = Zeroizing::new(vec![0; RECORD_LEN]);
633 let mut next = Zeroizing::new(vec![0; RECORD_LEN]);
634 let mut length = read_chunk(input, &mut current[..CHUNK_LEN])?;
635 let mut counter = 0;
636 let mut total = 0;
637 loop {
638 if counter >= MAX_CHUNKS {
639 return Err(ObjectError::ObjectTooLarge);
640 }
641 let next_length = read_chunk(input, &mut next[..CHUNK_LEN])?;
642 let kind = if next_length == 0 { FINAL } else { DATA };
643 let aad = chunk_aad(object_id, header_hash, counter, kind, length);
644 let sealed = cipher.seal_in_place(&nonce(counter, kind), &aad, &mut current, length)?;
645 let mut record = [0; 5];
646 record[0] = kind;
647 record[1..].copy_from_slice(&(sealed as u32).to_be_bytes());
648 output.write_all(&record)?;
649 output.write_all(¤t[..sealed])?;
650 total += length as u64;
651 if kind == FINAL {
652 return Ok(total);
653 }
654 core::mem::swap(&mut current, &mut next);
655 length = next_length;
656 counter += 1;
657 }
658}
659
660fn decrypt_records<R: Read, W: Write>(
661 input: &mut R,
662 staging: &mut W,
663 key: &DerivedKey,
664 object_id: &[u8; 32],
665 header_hash: &[u8; 32],
666) -> Result<u64, ObjectError> {
667 let cipher = ChunkCipher::new(key)?;
668 let mut buffer = Zeroizing::new(vec![0; RECORD_LEN]);
669 let mut total = 0;
670 for counter in 0..MAX_CHUNKS {
671 let mut record = [0; 5];
672 read_payload(input, &mut record)?;
673 let kind = record[0];
674 let ciphertext_len =
675 u32::from_be_bytes([record[1], record[2], record[3], record[4]]) as usize;
676 let length = record_length(kind, ciphertext_len, counter)?;
677 let ciphertext = &mut buffer[..ciphertext_len];
678 read_payload(input, ciphertext)?;
679 let aad = chunk_aad(object_id, header_hash, counter, kind, length);
680 let opened = cipher.open_in_place(&nonce(counter, kind), &aad, ciphertext)?;
681 if kind == FINAL {
682 let mut extra = [0; 1];
683 if read_chunk(input, &mut extra)? != 0 {
684 return Err(ObjectError::TrailingData);
685 }
686 }
687 staging.write_all(&buffer[..opened])?;
688 total += opened as u64;
689 if kind == FINAL {
690 return Ok(total);
691 }
692 }
693 Err(ObjectError::ObjectTooLarge)
694}
695
696fn record_length(kind: u8, ciphertext_len: usize, counter: u64) -> Result<usize, ObjectError> {
697 if !(TAG_LEN..=CHUNK_LEN + TAG_LEN).contains(&ciphertext_len) {
698 return Err(ObjectError::InvalidRecord);
699 }
700 let length = ciphertext_len - TAG_LEN;
701 match kind {
702 DATA if length == CHUNK_LEN => Ok(length),
703 FINAL if length > 0 || counter == 0 => Ok(length),
704 _ => Err(ObjectError::InvalidRecord),
705 }
706}
707
708fn read_payload<R: Read>(reader: &mut R, buffer: &mut [u8]) -> Result<(), ObjectError> {
709 reader.read_exact(buffer).map_err(|error| {
710 if error.kind() == io::ErrorKind::UnexpectedEof {
711 ObjectError::TruncatedPayload
712 } else {
713 ObjectError::Io(error)
714 }
715 })
716}
717
718#[cfg(feature = "test-vectors")]
721pub fn encrypt_stripped_signature_for_test<R: Read, W: Write>(
722 input: &mut R,
723 output: &mut W,
724 recipients: &[RecipientPublic],
725 metadata: &Metadata,
726 identity: &SigningIdentity,
727) -> Result<u64, ObjectError> {
728 validate_recipients(recipients)?;
729 let material = ObjectMaterial {
730 cek: ContentKey::generate()?,
731 object_id: hide_crypto::random_array()?,
732 payload_salt: hide_crypto::random_array()?,
733 };
734 let stanzas = recipients
735 .iter()
736 .map(|recipient| {
737 hide_crypto::wrap_cek(recipient, &material.cek, &material.object_id).map(|wrapped| {
738 RecipientStanza {
739 encapsulation: wrapped.encapsulation,
740 wrapped_cek: wrapped.wrapped_cek,
741 }
742 })
743 })
744 .collect::<Result<Vec<_>, _>>()?;
745 encrypt_inner(
746 input,
747 output,
748 metadata,
749 material,
750 stanzas,
751 Some((identity, SignaturePlacement::Stripped)),
752 &VectorShape::default(),
753 )
754}
755
756#[cfg(feature = "test-vectors")]
761pub fn forge_payload_for_test(
762 container: &[u8],
763 secret: &RecipientSecret,
764 replacement: &[u8],
765) -> Result<Vec<u8>, ObjectError> {
766 let preamble = Preamble::decode(&container[..PREAMBLE_LEN])?;
767 let header_end = PREAMBLE_LEN + preamble.header_len();
768 let (protected, mac) = hide_format::decode_header(&container[PREAMBLE_LEN..header_end])?;
769 let header = ProtectedHeader::decode(&protected)?;
770 let cek = recover_cek(
771 secret,
772 &header,
773 &container[..PREAMBLE_LEN],
774 &protected,
775 &mac,
776 )?;
777
778 let salt: [u8; 16] = container[header_end..header_end + 16]
779 .try_into()
780 .map_err(|_| ObjectError::TruncatedPayload)?;
781 let key = payload_key(&cek, &header.object_id, &salt)?;
782
783 let mut forged = container[..header_end + 16].to_vec();
784 encrypt_records(
785 &mut &replacement[..],
786 &mut forged,
787 &key,
788 &header.object_id,
789 &hide_crypto::hash(&[&protected]),
790 )?;
791 Ok(forged)
792}
793
794#[cfg(feature = "test-vectors")]
795pub fn encrypt_for_vector<R: Read, W: Write>(
796 input: &mut R,
797 output: &mut W,
798 recipient: &RecipientPublic,
799 metadata: &Metadata,
800) -> Result<u64, ObjectError> {
801 encrypt_for_vector_inner(
802 input,
803 output,
804 recipient,
805 metadata,
806 None,
807 &VectorShape::default(),
808 )
809}
810
811#[cfg(feature = "test-vectors")]
817pub fn rewrite_header_for_test(
818 container: &[u8],
819 secret: &RecipientSecret,
820 minor: Option<u8>,
821 edit: impl FnOnce(&mut ProtectedHeader),
822) -> Result<Vec<u8>, ObjectError> {
823 rewrite_for_test(container, secret, minor, None, edit, |_| {})
824}
825
826#[cfg(feature = "test-vectors")]
829pub fn rewrite_for_test(
830 container: &[u8],
831 secret: &RecipientSecret,
832 minor: Option<u8>,
833 flags: Option<u8>,
834 edit: impl FnOnce(&mut ProtectedHeader),
835 edit_metadata: impl FnOnce(&mut Vec<u8>),
836) -> Result<Vec<u8>, ObjectError> {
837 let preamble = Preamble::decode(&container[..PREAMBLE_LEN])?;
838 let header_end = PREAMBLE_LEN + preamble.header_len();
839 let (protected, mac) = hide_format::decode_header(&container[PREAMBLE_LEN..header_end])?;
840 let mut header = ProtectedHeader::decode(&protected)?;
841 let cek = recover_cek(
842 secret,
843 &header,
844 &container[..PREAMBLE_LEN],
845 &protected,
846 &mac,
847 )?;
848 let mut plaintext = Vec::new();
849 decrypt_to_staging(&mut &container[..], &mut plaintext, secret)?;
850
851 let metadata_key = hide_crypto::derive_key(&cek, &header.object_id, b"HIDE/0.1 metadata")?;
852 let aad = metadata_aad(&header.object_id);
853 let mut metadata =
854 hide_crypto::open(&metadata_key, &[0; 12], &aad, &header.encrypted_metadata)?;
855 edit_metadata(&mut metadata);
856 header.encrypted_metadata = hide_crypto::seal(&metadata_key, &[0; 12], &aad, &metadata)?;
857 edit(&mut header);
858
859 let protected = header.encode()?;
862 let length = hide_format::encode_header(&protected, &[0; 32])?.len();
863 let mut bytes = Preamble::decode(&container[..PREAMBLE_LEN])?.encode();
864 bytes[9] = minor.unwrap_or(bytes[9]);
865 bytes[11] = flags.unwrap_or(bytes[11]);
866 bytes[12..].copy_from_slice(&(length as u32).to_be_bytes());
867 let mac_key = hide_crypto::derive_key(&cek, &header.object_id, b"HIDE/0.1 header-mac")?;
868 let mac = hide_crypto::mac(&mac_key, &[&bytes, &protected])?;
869 let salt: [u8; 16] = container[header_end..header_end + 16]
870 .try_into()
871 .map_err(|_| ObjectError::TruncatedPayload)?;
872
873 let mut out = bytes.to_vec();
874 out.extend_from_slice(&hide_format::encode_header(&protected, &mac)?);
875 out.extend_from_slice(&salt);
876 let key = payload_key(&cek, &header.object_id, &salt)?;
877 encrypt_records(
878 &mut plaintext.as_slice(),
879 &mut out,
880 &key,
881 &header.object_id,
882 &hide_crypto::hash(&[&protected]),
883 )?;
884 Ok(out)
885}
886
887#[cfg(feature = "test-vectors")]
892pub fn replace_protected_for_test(
893 container: &[u8],
894 secret: &RecipientSecret,
895 protected: &[u8],
896) -> Result<Vec<u8>, ObjectError> {
897 let preamble = Preamble::decode(&container[..PREAMBLE_LEN])?;
898 let header_end = PREAMBLE_LEN + preamble.header_len();
899 let (original, mac) = hide_format::decode_header(&container[PREAMBLE_LEN..header_end])?;
900 let header = ProtectedHeader::decode(&original)?;
901 let cek = recover_cek(secret, &header, &container[..PREAMBLE_LEN], &original, &mac)?;
902 let mut plaintext = Vec::new();
903 decrypt_to_staging(&mut &container[..], &mut plaintext, secret)?;
904
905 let length = hide_format::encode_header(protected, &[0; 32])?.len();
906 let mut bytes = preamble.encode();
907 bytes[12..].copy_from_slice(&(length as u32).to_be_bytes());
908 let mac_key = hide_crypto::derive_key(&cek, &header.object_id, b"HIDE/0.1 header-mac")?;
909 let mac = hide_crypto::mac(&mac_key, &[&bytes, protected])?;
910 let salt = &container[header_end..header_end + 16];
911 let mut out = bytes.to_vec();
912 out.extend_from_slice(&hide_format::encode_header(protected, &mac)?);
913 out.extend_from_slice(salt);
914 let salt: [u8; 16] = salt.try_into().map_err(|_| ObjectError::TruncatedPayload)?;
915 let key = payload_key(&cek, &header.object_id, &salt)?;
916 encrypt_records(
917 &mut plaintext.as_slice(),
918 &mut out,
919 &key,
920 &header.object_id,
921 &hide_crypto::hash(&[protected]),
922 )?;
923 Ok(out)
924}
925
926#[cfg(feature = "test-vectors")]
928pub fn encrypt_signed_for_vector<R: Read, W: Write>(
929 input: &mut R,
930 output: &mut W,
931 recipient: &RecipientPublic,
932 metadata: &Metadata,
933 identity: &SigningIdentity,
934 placement: SignaturePlacement,
935) -> Result<u64, ObjectError> {
936 encrypt_for_vector_inner(
937 input,
938 output,
939 recipient,
940 metadata,
941 Some((identity, placement)),
942 &VectorShape::default(),
943 )
944}
945
946#[cfg(feature = "test-vectors")]
949pub fn encrypt_shaped_for_vector<R: Read, W: Write>(
950 input: &mut R,
951 output: &mut W,
952 recipient: &RecipientPublic,
953 metadata: &Metadata,
954 signer: Option<(&SigningIdentity, SignaturePlacement)>,
955 shape: &VectorShape,
956) -> Result<u64, ObjectError> {
957 encrypt_for_vector_inner(input, output, recipient, metadata, signer, shape)
958}
959
960#[cfg(feature = "test-vectors")]
961fn encrypt_for_vector_inner<R: Read, W: Write>(
962 input: &mut R,
963 output: &mut W,
964 recipient: &RecipientPublic,
965 metadata: &Metadata,
966 signer: Option<(&SigningIdentity, SignaturePlacement)>,
967 shape: &VectorShape,
968) -> Result<u64, ObjectError> {
969 let material = ObjectMaterial {
970 cek: ContentKey::from_bytes([0x11; 32]),
971 object_id: [0x22; 32],
972 payload_salt: [0x33; 16],
973 };
974 let wrapped = hide_crypto::wrap_cek_for_vector(
975 recipient,
976 &material.cek,
977 &material.object_id,
978 [0x44; 32],
979 )?;
980 encrypt_inner(
981 input,
982 output,
983 metadata,
984 material,
985 vec![RecipientStanza {
986 encapsulation: wrapped.encapsulation,
987 wrapped_cek: wrapped.wrapped_cek,
988 }],
989 signer,
990 shape,
991 )
992}
993
994#[cfg(test)]
995mod tests {
996 use super::*;
997
998 fn encrypt_bytes(plaintext: &[u8], secret: &RecipientSecret) -> Result<Vec<u8>, ObjectError> {
999 let mut ciphertext = Vec::new();
1000 encrypt(
1001 &mut &*plaintext,
1002 &mut ciphertext,
1003 &[secret.public_key()?],
1004 &Metadata::default(),
1005 )?;
1006 Ok(ciphertext)
1007 }
1008
1009 #[test]
1010 fn boundary_sizes_roundtrip() -> Result<(), ObjectError> {
1011 let secret = RecipientSecret::generate()?;
1012 for size in [
1013 0,
1014 1,
1015 CHUNK_LEN - 1,
1016 CHUNK_LEN,
1017 CHUNK_LEN + 1,
1018 2 * CHUNK_LEN,
1019 3 * CHUNK_LEN + 17,
1020 ] {
1021 let plaintext = vec![0x5a; size];
1022 let ciphertext = encrypt_bytes(&plaintext, &secret)?;
1023 let mut output = Vec::new();
1024 let verified = decrypt_to_staging(&mut ciphertext.as_slice(), &mut output, &secret)?;
1025 assert_eq!(verified.plaintext_len, size as u64);
1026 assert_eq!(output, plaintext);
1027 }
1028 Ok(())
1029 }
1030
1031 #[test]
1032 fn multiple_recipients_share_one_payload() -> Result<(), ObjectError> {
1033 let alice = RecipientSecret::generate()?;
1034 let bob = RecipientSecret::generate()?;
1035 let mut ciphertext = Vec::new();
1036 let metadata = Metadata {
1037 filename: Some("hello.txt".into()),
1038 media_type: Some("text/plain".into()),
1039 signature: None,
1040 extensions: Vec::new(),
1041 };
1042 encrypt(
1043 &mut b"Hello HIDE\n".as_slice(),
1044 &mut ciphertext,
1045 &[alice.public_key()?, bob.public_key()?],
1046 &metadata,
1047 )?;
1048 for secret in [&alice, &bob] {
1049 let mut output = Vec::new();
1050 let verified = decrypt_to_staging(&mut ciphertext.as_slice(), &mut output, secret)?;
1051 assert_eq!(output, b"Hello HIDE\n");
1052 assert_eq!(verified.metadata, metadata);
1053 }
1054 assert!(!ciphertext.windows(9).any(|window| window == b"hello.txt"));
1055 Ok(())
1056 }
1057
1058 #[test]
1059 fn rejects_tampering_in_every_container_region() -> Result<(), ObjectError> {
1060 let secret = RecipientSecret::generate()?;
1061 let ciphertext = encrypt_bytes(&vec![7; CHUNK_LEN + 1], &secret)?;
1062 let header_end = PREAMBLE_LEN + Preamble::decode(&ciphertext[..PREAMBLE_LEN])?.header_len();
1063 for offset in [
1064 8,
1065 11,
1066 15,
1067 30,
1068 80,
1069 header_end - 1,
1070 header_end,
1071 header_end + 16,
1072 header_end + 20,
1073 header_end + 30,
1074 ciphertext.len() - 1,
1075 ] {
1076 let mut damaged = ciphertext.clone();
1077 damaged[offset] ^= 1;
1078 assert!(
1079 decrypt_to_staging(&mut damaged.as_slice(), &mut Vec::new(), &secret).is_err(),
1080 "offset {offset}"
1081 );
1082 }
1083 let other = RecipientSecret::generate()?;
1084 assert!(decrypt_to_staging(&mut ciphertext.as_slice(), &mut Vec::new(), &other).is_err());
1085 Ok(())
1086 }
1087
1088 #[test]
1089 fn rejects_missing_final_reordered_duplicate_and_extra_records() -> Result<(), ObjectError> {
1090 let secret = RecipientSecret::generate()?;
1091 let ciphertext = encrypt_bytes(&vec![7; 2 * CHUNK_LEN + 1], &secret)?;
1092 let payload_start =
1093 PREAMBLE_LEN + Preamble::decode(&ciphertext[..PREAMBLE_LEN])?.header_len() + 16;
1094 let record_len = 5 + CHUNK_LEN + TAG_LEN;
1095 let mut reordered = ciphertext.clone();
1096 reordered[payload_start..payload_start + record_len].copy_from_slice(
1097 &ciphertext[payload_start + record_len..payload_start + 2 * record_len],
1098 );
1099 let mut duplicated = ciphertext.clone();
1100 duplicated.splice(
1101 payload_start..payload_start,
1102 ciphertext[payload_start..payload_start + record_len]
1103 .iter()
1104 .copied(),
1105 );
1106 let mut extra = ciphertext.clone();
1107 extra.push(0);
1108 for damaged in [
1109 ciphertext[..payload_start + 2 * record_len].to_vec(),
1110 reordered,
1111 duplicated,
1112 extra,
1113 ciphertext[..ciphertext.len() - 1].to_vec(),
1114 ] {
1115 assert!(decrypt_to_staging(&mut damaged.as_slice(), &mut Vec::new(), &secret).is_err());
1116 }
1117 Ok(())
1118 }
1119
1120 #[test]
1121 fn rejects_noncanonical_empty_final_and_large_record() {
1122 assert!(record_length(FINAL, 16, 1).is_err());
1123 assert!(record_length(DATA, 16, 0).is_err());
1124 assert!(record_length(FINAL, usize::MAX, 0).is_err());
1125 assert!(record_length(3, 17, 0).is_err());
1126 }
1127
1128 #[test]
1129 fn chunk_binding_covers_every_field_exactly() {
1130 let aad = chunk_aad(
1131 &[0xa1; 32],
1132 &[0xb2; 32],
1133 0x0102_0304_0506_0708,
1134 DATA,
1135 0x1234,
1136 );
1137 assert_eq!(&aad[..14], b"HIDE/0.1 chunk");
1138 assert_eq!(&aad[14..46], &[0xa1; 32]);
1139 assert_eq!(&aad[46..78], &[0xb2; 32]);
1140 assert_eq!(&aad[78..86], &[1, 2, 3, 4, 5, 6, 7, 8]);
1141 assert_eq!(aad[86], DATA);
1142 assert_eq!(&aad[87..], &[0, 0, 0x12, 0x34]);
1143
1144 let mut contexts = std::collections::HashSet::new();
1145 for kind in [DATA, FINAL] {
1146 for counter in [0, 1, 2, u32::MAX as u64] {
1147 let context = (
1148 chunk_aad(&[0; 32], &[0; 32], counter, kind, 7).to_vec(),
1149 nonce(counter, kind),
1150 );
1151 assert!(
1152 contexts.insert(context),
1153 "nonce/AAD reuse at {counter}/{kind}"
1154 );
1155 }
1156 }
1157 assert_ne!(
1158 chunk_aad(&[0; 32], &[0; 32], 0, DATA, 7),
1159 chunk_aad(&[0; 32], &[0; 32], 0, FINAL, 7)
1160 );
1161 assert_eq!(nonce(1, DATA), [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0]);
1162 assert_eq!(nonce(1, FINAL), [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1]);
1163 assert_eq!(
1164 nonce(u32::MAX as u64, DATA)[3..11],
1165 [0, 0, 0, 0, 0xff, 0xff, 0xff, 0xff]
1166 );
1167 }
1168
1169 #[test]
1170 fn metadata_binding_covers_object_and_suite() {
1171 let aad = metadata_aad(&[0xc3; 32]);
1172 assert_eq!(&aad[..17], b"HIDE/0.1 metadata");
1173 assert_eq!(&aad[17..49], &[0xc3; 32]);
1174 assert_eq!(&aad[49..], &[0, 1]);
1175 assert_ne!(metadata_aad(&[1; 32]), metadata_aad(&[2; 32]));
1176 }
1177}