Skip to main content

hide_object/
lib.rs

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;
19/// A signed encrypt must hold the whole plaintext to hash it, so it is the one
20/// path that cannot stream. Unsigned encryption has no such limit.
21pub 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";
25/// HIDE/0.5–0.8 signed containers (preamble minor 2). Verified, never produced.
26const 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/// Where a signature is written. Public signatures are readable by anyone
57/// holding the file; confidential ones only by those who can already decrypt.
58#[derive(Debug, Clone, Copy, PartialEq, Eq)]
59pub enum SignaturePlacement {
60    /// In the unencrypted header. Reveals the signer to anyone with the file.
61    Public,
62    /// Inside the encrypted metadata. Hides the signer from non-recipients.
63    Confidential,
64    /// Signs, then discards the signature while leaving the preamble claiming
65    /// to be signed. Exists only so tests can reach the stripped-signature check.
66    #[cfg(feature = "test-vectors")]
67    #[doc(hidden)]
68    Stripped,
69    /// The HIDE/0.5 wire form: minor 2 and the legacy transcript. Exists only so
70    /// tests and vectors can prove that such files are still read.
71    #[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    /// The signer, if the container carried a signature that verified.
81    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
123/// Encrypts and signs. Unlike [`encrypt`], this buffers the payload, because the
124/// signature commits to the plaintext and so cannot be produced while streaming.
125pub 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/// Wire features a HIDE/1.0 writer never emits but every reader must accept.
180/// Production code always uses the default; the vector generator uses the rest
181/// to freeze GREASE containers that prove readers skip what they do not know.
182#[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
202/// Commits to the recipient set, the metadata and the plaintext. Binding only
203/// the header would let any recipient re-encrypt different content under the
204/// same header and keep the signature valid, since they hold the CEK and the
205/// payload salt is public.
206///
207/// The metadata is bound as its *plaintext* signing base rather than via the
208/// header's ciphertext: sealing is randomised and the confidential placement
209/// reseals after signing, so the ciphertext a verifier sees is not the one that
210/// existed when the signature was made.
211///
212/// HIDE/1.0 also binds the preamble's version and flags, every stanza's tag and
213/// every field length (so unknown stanzas and a stanza boundary cannot be
214/// shifted), and the header extensions, which the metadata base does not cover.
215fn 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
253/// The HIDE/0.5 transcript. Only reachable for minor 2, which admits neither
254/// extensions nor unknown stanzas, so every stanza here is X-Wing.
255fn 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    // Signing needs the plaintext hash, which is only known once the payload has
295    // been consumed, so the container is built in memory and written at the end.
296    // Bounded, because a signed encrypt is the one path that cannot stream.
297    // Metadata extension keys are writer-controlled and a 1.0 writer MUST NOT
298    // emit them (spec 4). The public API takes the caller's Metadata, so a
299    // caller that pre-set one, or a signature, is refused rather than obeyed.
300    if !metadata.extensions.is_empty() || metadata.signature.is_some() {
301        return Err(FormatError::InvalidMetadata.into());
302    }
303    // The only writer that may grease the metadata is the vector generator,
304    // through the shape; production never reaches this with a non-empty shape.
305    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    // The signing base is the metadata without any signature; both placements
327    // commit to it. It is only hashed into the transcript, never sealed on its
328    // own: the metadata key and its fixed nonce must encrypt exactly one thing.
329    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    // The signed prefix does not include header_len, so the preamble the
344    // transcript binds can be fixed before the header is sized.
345    #[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    // Exactly one seal under the metadata key, whichever placement was chosen.
389    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
422/// Writes provisional plaintext. The writer must be private staging storage, not a
423/// published file or stdout. Commit it only after this function returns Ok.
424/// Integrity does not authenticate the sender or verify a human identity.
425pub 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    // The legacy transcript binds neither extensions nor stanza tags, so a
438    // minor-2 container carrying either could have them added after signing.
439    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    // The signature commits to the plaintext, so it can only be checked once the
462    // payload has been read. Hash it on the way past rather than buffering.
463    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
481/// Returns the signer when the container carries a signature that verifies, and
482/// refuses the object otherwise. Called before the caller may publish plaintext.
483fn 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            // A preamble claiming to be signed with no signature is a stripped
496            // signature, not an unsigned object.
497            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    // Unknown stanza types are skipped, not refused: a later recipient type must
531    // not lock out the recipients a file already had.
532    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
548/// Hashes plaintext as it streams to staging, so verifying a signature over the
549/// content does not require buffering the whole object.
550struct 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(&current[..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/// Writes a container whose preamble claims to be signed while carrying no
733/// signature: the shape an attacker produces by stripping one. Test-only.
734#[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/// Mounts the forgery a signature must prevent: keep the container's header
771/// byte-for-byte, then re-encrypt different plaintext with the CEK the
772/// recipient already holds. Exposed only for tests, because it exists purely to
773/// prove the signature binds the payload and not merely the header.
774#[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/// Everything a recipient can do to a container: open it, change the header
826/// (and optionally the minor), then recompute the header MAC and re-encrypt
827/// the payload so every authenticator a recipient controls is valid again.
828/// What survives this is exactly what a signature must catch. Test-only; it is
829/// also how the rejection vectors that need an authentic MAC are produced.
830#[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/// As [`rewrite_header_for_test`], and also sets the flags byte and edits the
841/// decrypted metadata before resealing it.
842#[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    // Encoded by hand where the edit left the header outside what encode()
874    // accepts would defeat the purpose; every edit used here stays encodable.
875    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/// Swaps in `protected` verbatim, which may be bytes `encode()` refuses, and
902/// re-authenticates everything a recipient controls around it. Lets the vector
903/// generator prove a reader refuses a malformed header for that reason alone,
904/// not because the MAC failed first. Test-only.
905#[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/// Deterministic signed container, so the vectors are reproducible.
941#[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/// Deterministic container with an explicit wire shape (GREASE, other minors),
961/// signed or not. The vector generator is the only caller.
962#[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    /// A caller cannot pre-set a metadata signature; the writer owns that field.
1073    #[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}