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, 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;
18/// A signed encrypt must hold the whole plaintext to hash it, so it is the one
19/// path that cannot stream. Unsigned encryption has no such limit.
20pub 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";
24/// HIDE/0.5–0.8 signed containers (preamble minor 2). Verified, never produced.
25const 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/// Where a signature is written. Public signatures are readable by anyone
56/// holding the file; confidential ones only by those who can already decrypt.
57#[derive(Debug, Clone, Copy, PartialEq, Eq)]
58pub enum SignaturePlacement {
59    /// In the unencrypted header. Reveals the signer to anyone with the file.
60    Public,
61    /// Inside the encrypted metadata. Hides the signer from non-recipients.
62    Confidential,
63    /// Signs, then discards the signature while leaving the preamble claiming
64    /// to be signed. Exists only so tests can reach the stripped-signature check.
65    #[cfg(feature = "test-vectors")]
66    #[doc(hidden)]
67    Stripped,
68    /// The HIDE/0.5 wire form: minor 2 and the legacy transcript. Exists only so
69    /// tests and vectors can prove that such files are still read.
70    #[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    /// The signer, if the container carried a signature that verified.
80    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
122/// Encrypts and signs. Unlike [`encrypt`], this buffers the payload, because the
123/// signature commits to the plaintext and so cannot be produced while streaming.
124pub 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/// Wire features a HIDE/1.0 writer never emits but every reader must accept.
179/// Production code always uses the default; the vector generator uses the rest
180/// to freeze GREASE containers that prove readers skip what they do not know.
181#[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
199/// Commits to the recipient set, the metadata and the plaintext. Binding only
200/// the header would let any recipient re-encrypt different content under the
201/// same header and keep the signature valid, since they hold the CEK and the
202/// payload salt is public.
203///
204/// The metadata is bound as its *plaintext* signing base rather than via the
205/// header's ciphertext: sealing is randomised and the confidential placement
206/// reseals after signing, so the ciphertext a verifier sees is not the one that
207/// existed when the signature was made.
208///
209/// HIDE/1.0 also binds the preamble's version and flags, every stanza's tag and
210/// every field length (so unknown stanzas and a stanza boundary cannot be
211/// shifted), and the header extensions, which the metadata base does not cover.
212fn 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
250/// The HIDE/0.5 transcript. Only reachable for minor 2, which admits neither
251/// extensions nor unknown stanzas, so every stanza here is X-Wing.
252fn 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    // Signing needs the plaintext hash, which is only known once the payload has
292    // been consumed, so the container is built in memory and written at the end.
293    // Bounded, because a signed encrypt is the one path that cannot stream.
294    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    // The signing base is the metadata without any signature; both placements
313    // commit to it. It is only hashed into the transcript, never sealed on its
314    // own: the metadata key and its fixed nonce must encrypt exactly one thing.
315    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    // The signed prefix does not include header_len, so the preamble the
330    // transcript binds can be fixed before the header is sized.
331    #[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    // Exactly one seal under the metadata key, whichever placement was chosen.
375    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
408/// Writes provisional plaintext. The writer must be private staging storage, not a
409/// published file or stdout. Commit it only after this function returns Ok.
410/// Integrity does not authenticate the sender or verify a human identity.
411pub 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    // The legacy transcript binds neither extensions nor stanza tags, so a
424    // minor-2 container carrying either could have them added after signing.
425    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    // The signature commits to the plaintext, so it can only be checked once the
448    // payload has been read. Hash it on the way past rather than buffering.
449    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
467/// Returns the signer when the container carries a signature that verifies, and
468/// refuses the object otherwise. Called before the caller may publish plaintext.
469fn 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            // A preamble claiming to be signed with no signature is a stripped
482            // signature, not an unsigned object.
483            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    // Unknown stanza types are skipped, not refused: a later recipient type must
517    // not lock out the recipients a file already had.
518    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
534/// Hashes plaintext as it streams to staging, so verifying a signature over the
535/// content does not require buffering the whole object.
536struct 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(&current[..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/// Writes a container whose preamble claims to be signed while carrying no
719/// signature: the shape an attacker produces by stripping one. Test-only.
720#[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/// Mounts the forgery a signature must prevent: keep the container's header
757/// byte-for-byte, then re-encrypt different plaintext with the CEK the
758/// recipient already holds. Exposed only for tests, because it exists purely to
759/// prove the signature binds the payload and not merely the header.
760#[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/// Everything a recipient can do to a container: open it, change the header
812/// (and optionally the minor), then recompute the header MAC and re-encrypt
813/// the payload so every authenticator a recipient controls is valid again.
814/// What survives this is exactly what a signature must catch. Test-only; it is
815/// also how the rejection vectors that need an authentic MAC are produced.
816#[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/// As [`rewrite_header_for_test`], and also sets the flags byte and edits the
827/// decrypted metadata before resealing it.
828#[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    // Encoded by hand where the edit left the header outside what encode()
860    // accepts would defeat the purpose; every edit used here stays encodable.
861    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/// Swaps in `protected` verbatim, which may be bytes `encode()` refuses, and
888/// re-authenticates everything a recipient controls around it. Lets the vector
889/// generator prove a reader refuses a malformed header for that reason alone,
890/// not because the MAC failed first. Test-only.
891#[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/// Deterministic signed container, so the vectors are reproducible.
927#[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/// Deterministic container with an explicit wire shape (GREASE, other minors),
947/// signed or not. The vector generator is the only caller.
948#[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}