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