arcana/cipher/

ocb.rs

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Cédric Mesnil <cslashm@pm.me>

//! AES-OCB authenticated encryption (OCB3, RFC 7253).
//!
//! OCB is a single-pass, parallelizable AEAD built on a 128-bit block
//! cipher (here AES-128/192/256, via the existing [`Aes`] core). This
//! module implements **OCB3 exactly as specified in RFC 7253**: the
//! `L_*`, `L_$`, `L_i` doubling in GF(2¹²⁸), the incremental `Offset`
//! update driven by `ntz(i)`, the `Checksum`, the PMAC-style
//! associated-data hash `HASH`, and the `Stretch`/`Nonce` bottom
//! rotation for the initial offset.
//!
//! Encryption returns `ciphertext ‖ tag`; decryption verifies the tag
//! in constant time and returns the plaintext only on success — a
//! wrong tag never releases plaintext.
//!
//! Only the standard 16-byte (128-bit) tag and the RFC's default
//! block cipher (AES) are exposed here. Nonces of 1..=15 bytes are
//! accepted per RFC 7253 §4.2 (`TAGLEN` is fixed at 128, so the low
//! byte of the nonce-format block is `0`).
//!
//! # Construction (RFC 7253 §4-5)
//!
//! Setup (once per key, [`Ocb::new`]):
//! - `L_* = ENCIPHER(K, zeros(128))`
//! - `L_$ = double(L_*)`
//! - `L_0 = double(L_$)`, `L_i = double(L_{i-1})`
//!
//! Per message the initial offset comes from the nonce:
//! - `Nonce = num2str(TAGLEN mod 128, 7) ‖ zeros(120 − 8·|N|) ‖ 1 ‖ N`
//! - `bottom = str2num(Nonce[123..128])` (low 6 bits)
//! - `Ktop = ENCIPHER(K, Nonce with last 6 bits zeroed)`
//! - `Stretch = Ktop ‖ (Ktop[0..8] xor Ktop[1..9])`
//! - `Offset_0 = Stretch[1+bottom .. 1+bottom+128]` (bit offset)
//!
//! # Side-channel posture
//!
//! - **Block cipher.** OCB calls the existing table-based AES
//!   ([`Aes`]); AES's cache-timing gap is the tracked item `T1-A`,
//!   handled separately. This module does not add or fix any AES
//!   leakage — it only calls `encrypt_block` / `decrypt_block`.
//! - **Tag verification.** Decryption compares the recomputed tag
//!   against the received tag with [`silentops::ct_eq`] — a single
//!   data-oblivious pass, no early exit, and **no plaintext is
//!   returned on mismatch** (the decrypted buffer is dropped). A wrong
//!   tag leaks nothing through timing.
//! - **Offset / doubling / checksum / HASH.** All are `xor`,
//!   fixed-shift `double`, and fixed byte moves on public-position
//!   data; `ntz(i)` and all loop bounds depend only on the (public)
//!   message and AAD lengths, never on secrets. Constant-time by
//!   construction.
//! - **`bottom` rotation.** The `Stretch` bit-rotation is indexed by
//!   `bottom`, which is derived from the (public) nonce, not from a
//!   secret. No secret-dependent memory access.
//!
//! # References
//!
//! - T. Krovetz, P. Rogaway, RFC 7253, "The OCB Authenticated-
//!   Encryption Algorithm" (2014). <https://www.rfc-editor.org/rfc/rfc7253>
//! - Test vectors: RFC 7253 Appendix A.

use super::aes::Aes;
use crate::BlockCipher;

const BLOCK: usize = 16;
const TAG_LEN: usize = 16;

// ============================================================================
// GF(2^128) doubling and block XOR helpers (RFC 7253 §2)
// ============================================================================

/// `double(S)` over GF(2¹²⁸) with the OCB reduction polynomial
/// `x^128 + x^7 + x^2 + x + 1` (i.e. constant `0x87`), big-endian
/// bit ordering per RFC 7253 §2.
///
/// Constant-time: the top-bit test is folded into a mask (no branch
/// on secret data — and `S` here is never secret-position anyway).
#[inline]
fn double(s: &[u8; BLOCK]) -> [u8; BLOCK] {
    let msb = s[0] >> 7; // 0 or 1
    let mut out = [0u8; BLOCK];
    let mut carry = 0u8;
    for i in (0..BLOCK).rev() {
        let cur = s[i];
        out[i] = (cur << 1) | carry;
        carry = cur >> 7;
    }
    // If the original MSB was set, xor 0x87 into the last byte.
    out[BLOCK - 1] ^= msb.wrapping_mul(0x87);
    out
}

/// In-place `dst ^= src` on a 16-byte block.
#[inline]
fn xor_block(dst: &mut [u8; BLOCK], src: &[u8; BLOCK]) {
    for i in 0..BLOCK {
        dst[i] ^= src[i];
    }
}

/// `a xor b` on 16-byte blocks (returns a fresh block).
#[inline]
fn xor_blocks(a: &[u8; BLOCK], b: &[u8; BLOCK]) -> [u8; BLOCK] {
    let mut out = *a;
    xor_block(&mut out, b);
    out
}

/// Number of trailing zero bits of a 1-based block index `i`
/// (`ntz(i)`, RFC 7253 §2). `i >= 1` always here.
#[inline]
fn ntz(i: usize) -> u32 {
    i.trailing_zeros()
}

// ============================================================================
// OCB context
// ============================================================================

/// AES-OCB (OCB3, RFC 7253) with a 128-bit tag.
///
/// Holds the AES key schedule and the precomputed `L_*`, `L_$`, and a
/// small cache of `L_i` doubling values. The cache grows on demand up
/// to the number of blocks seen; for typical messages a handful of
/// entries suffice.
pub struct Ocb {
    aes: Aes,
    l_star: [u8; BLOCK],
    l_dollar: [u8; BLOCK],
    /// `l[i] = double^{i+1}(L_$)`, i.e. `l[0] = L_0`, `l[1] = L_1`, ...
    l: Vec<[u8; BLOCK]>,
}

impl Ocb {
    /// Create an AES-OCB context. `key` must be 16, 24, or 32 bytes
    /// (AES-128/192/256). Returns `None` for an invalid key length.
    pub fn new(key: &[u8]) -> Option<Self> {
        if !matches!(key.len(), 16 | 24 | 32) {
            return None;
        }
        let aes = <Aes as BlockCipher>::new(key);

        // L_* = ENCIPHER(K, 0^128)
        let mut l_star = [0u8; BLOCK];
        aes.encrypt_block(&mut l_star);
        // L_$ = double(L_*), L_0 = double(L_$)
        let l_dollar = double(&l_star);
        let l0 = double(&l_dollar);

        Some(Self {
            aes,
            l_star,
            l_dollar,
            l: vec![l0],
        })
    }

    /// Ensure `self.l` has at least index `i` (0-based), extending by
    /// repeated doubling. `l[i]` is used when `ntz(block_index) == i`.
    fn ensure_l(&mut self, i: usize) {
        while self.l.len() <= i {
            let last = *self.l.last().unwrap();
            self.l.push(double(&last));
        }
    }

    /// Compute the initial offset `Offset_0` from the nonce
    /// (RFC 7253 §4.2), fixed `TAGLEN = 128`.
    ///
    /// `nonce.len()` must be 1..=15.
    fn init_offset(&self, nonce: &[u8]) -> [u8; BLOCK] {
        debug_assert!((1..=15).contains(&nonce.len()));

        // Nonce block: top byte = TAGLEN mod 128 = 0 (128 mod 128),
        // then zero pad, a single 1 bit before the nonce, then N.
        let mut nb = [0u8; BLOCK];
        // num2str(128 mod 128, 7) = 0, so byte 0 keeps its high 7 bits
        // clear. The "1" bit sits at position 120 - 8*len from the MSB,
        // i.e. just before the nonce.
        nb[BLOCK - 1 - nonce.len()] = 0x01;
        nb[BLOCK - nonce.len()..].copy_from_slice(nonce);

        // bottom = last 6 bits of the nonce block.
        let bottom = (nb[BLOCK - 1] & 0x3f) as usize;

        // Ktop = ENCIPHER(K, Nonce with bottom 6 bits zeroed).
        let mut ktop_in = nb;
        ktop_in[BLOCK - 1] &= 0xc0;
        let mut ktop = ktop_in;
        self.aes.encrypt_block(&mut ktop);

        // Stretch = Ktop ‖ (Ktop[0..8] xor Ktop[1..9]) — 24 bytes.
        let mut stretch = [0u8; BLOCK + 8];
        stretch[..BLOCK].copy_from_slice(&ktop);
        for i in 0..8 {
            stretch[BLOCK + i] = ktop[i] ^ ktop[i + 1];
        }

        // Offset_0 = Stretch[1+bottom .. 1+bottom+128] (bit-indexed).
        // Extract 128 bits starting at bit `bottom` from the byte
        // stream `stretch`.
        let mut offset = [0u8; BLOCK];
        let byte_shift = bottom / 8;
        let bit_shift = (bottom % 8) as u32;
        if bit_shift == 0 {
            offset.copy_from_slice(&stretch[byte_shift..byte_shift + BLOCK]);
        } else {
            for i in 0..BLOCK {
                let hi = (stretch[byte_shift + i] as u32) << bit_shift;
                let lo = (stretch[byte_shift + i + 1] as u32) >> (8 - bit_shift);
                offset[i] = (hi | lo) as u8;
            }
        }
        offset
    }

    /// PMAC-style associated-data hash `HASH(K, A)` (RFC 7253 §4.1).
    ///
    /// Returns a 16-byte value that is xored into the tag. Uses `L_i`
    /// doubling with `ntz(i)` exactly like the message path, but with
    /// its own zero-initialized offset and sum.
    fn hash_aad(&mut self, aad: &[u8]) -> [u8; BLOCK] {
        let mut offset = [0u8; BLOCK];
        let mut sum = [0u8; BLOCK];

        let full = aad.len() / BLOCK;
        for i in 0..full {
            self.ensure_l(ntz(i + 1) as usize);
            xor_block(&mut offset, &self.l[ntz(i + 1) as usize]);

            let mut blk = [0u8; BLOCK];
            blk.copy_from_slice(&aad[i * BLOCK..i * BLOCK + BLOCK]);
            let mut enc = xor_blocks(&blk, &offset);
            self.aes.encrypt_block(&mut enc);
            xor_block(&mut sum, &enc);
        }

        // Final partial block (if any).
        let rem = aad.len() % BLOCK;
        if rem != 0 {
            xor_block(&mut offset, &self.l_star);
            let mut blk = [0u8; BLOCK];
            blk[..rem].copy_from_slice(&aad[full * BLOCK..]);
            blk[rem] = 0x80; // 10* padding
            let mut enc = xor_blocks(&blk, &offset);
            self.aes.encrypt_block(&mut enc);
            xor_block(&mut sum, &enc);
        }

        sum
    }

    /// Encrypt and authenticate. Returns `ciphertext ‖ tag`
    /// (`out.len() == plaintext.len() + 16`).
    ///
    /// `nonce.len()` must be 1..=15; returns `None` otherwise.
    pub fn encrypt(&mut self, nonce: &[u8], aad: &[u8], plaintext: &[u8]) -> Option<Vec<u8>> {
        if !(1..=15).contains(&nonce.len()) {
            return None;
        }

        let mut offset = self.init_offset(nonce);
        let mut checksum = [0u8; BLOCK];
        let mut out = Vec::with_capacity(plaintext.len() + TAG_LEN);

        let full = plaintext.len() / BLOCK;
        for i in 0..full {
            self.ensure_l(ntz(i + 1) as usize);
            xor_block(&mut offset, &self.l[ntz(i + 1) as usize]);

            let mut blk = [0u8; BLOCK];
            blk.copy_from_slice(&plaintext[i * BLOCK..i * BLOCK + BLOCK]);
            // Checksum ^= P_i
            xor_block(&mut checksum, &blk);
            // C_i = Offset ^ ENCIPHER(K, P_i ^ Offset)
            let mut enc = xor_blocks(&blk, &offset);
            self.aes.encrypt_block(&mut enc);
            xor_block(&mut enc, &offset);
            out.extend_from_slice(&enc);
        }

        // Final partial block (if any).
        let rem = plaintext.len() % BLOCK;
        if rem != 0 {
            xor_block(&mut offset, &self.l_star);
            // Pad = ENCIPHER(K, Offset)
            let mut pad = offset;
            self.aes.encrypt_block(&mut pad);
            // C_* = P_* ^ Pad[0..rem]
            let p_last = &plaintext[full * BLOCK..];
            for i in 0..rem {
                out.push(p_last[i] ^ pad[i]);
            }
            // Checksum ^= (P_* ‖ 1 ‖ 0*)
            let mut cs_block = [0u8; BLOCK];
            cs_block[..rem].copy_from_slice(p_last);
            cs_block[rem] = 0x80;
            xor_block(&mut checksum, &cs_block);
        }

        // Tag = ENCIPHER(K, Checksum ^ Offset ^ L_$) ^ HASH(K, A)
        let mut tag_in = xor_blocks(&checksum, &offset);
        xor_block(&mut tag_in, &self.l_dollar);
        let mut tag = tag_in;
        self.aes.encrypt_block(&mut tag);
        let aad_hash = self.hash_aad(aad);
        xor_block(&mut tag, &aad_hash);

        out.extend_from_slice(&tag);
        Some(out)
    }

    /// Decrypt and verify. `input` is `ciphertext ‖ tag`. Returns
    /// `Some(plaintext)` only if the 16-byte tag verifies (constant-
    /// time compare); returns `None` on any malformed input or tag
    /// mismatch, and never releases plaintext on failure.
    ///
    /// `nonce.len()` must be 1..=15.
    pub fn decrypt(&mut self, nonce: &[u8], aad: &[u8], input: &[u8]) -> Option<Vec<u8>> {
        if !(1..=15).contains(&nonce.len()) {
            return None;
        }
        if input.len() < TAG_LEN {
            return None;
        }
        let (ciphertext, recv_tag) = input.split_at(input.len() - TAG_LEN);

        let mut offset = self.init_offset(nonce);
        let mut checksum = [0u8; BLOCK];
        let mut plaintext = Vec::with_capacity(ciphertext.len());

        let full = ciphertext.len() / BLOCK;
        for i in 0..full {
            self.ensure_l(ntz(i + 1) as usize);
            xor_block(&mut offset, &self.l[ntz(i + 1) as usize]);

            let mut blk = [0u8; BLOCK];
            blk.copy_from_slice(&ciphertext[i * BLOCK..i * BLOCK + BLOCK]);
            // P_i = Offset ^ DECIPHER(K, C_i ^ Offset)
            let mut dec = xor_blocks(&blk, &offset);
            self.aes.decrypt_block(&mut dec);
            xor_block(&mut dec, &offset);
            xor_block(&mut checksum, &dec);
            plaintext.extend_from_slice(&dec);
        }

        // Final partial block (if any).
        let rem = ciphertext.len() % BLOCK;
        if rem != 0 {
            xor_block(&mut offset, &self.l_star);
            let mut pad = offset;
            self.aes.encrypt_block(&mut pad); // OCB decrypt uses ENCIPHER for the pad
            let c_last = &ciphertext[full * BLOCK..];
            let mut p_last = [0u8; BLOCK];
            for i in 0..rem {
                p_last[i] = c_last[i] ^ pad[i];
                plaintext.push(p_last[i]);
            }
            let mut cs_block = [0u8; BLOCK];
            cs_block[..rem].copy_from_slice(&p_last[..rem]);
            cs_block[rem] = 0x80;
            xor_block(&mut checksum, &cs_block);
        }

        // Recompute the tag.
        let mut tag_in = xor_blocks(&checksum, &offset);
        xor_block(&mut tag_in, &self.l_dollar);
        let mut tag = tag_in;
        self.aes.encrypt_block(&mut tag);
        let aad_hash = self.hash_aad(aad);
        xor_block(&mut tag, &aad_hash);

        // Constant-time tag compare; drop plaintext on failure so a
        // wrong tag never releases it.
        if silentops::ct_eq(&tag, recv_tag) == 1 {
            Some(plaintext)
        } else {
            None
        }
    }
}

// ============================================================================
// Tests (RFC 7253 Appendix A pinned vectors)
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    fn hex(s: &str) -> Vec<u8> {
        let s: String = s.chars().filter(|c| !c.is_whitespace()).collect();
        assert!(s.len() % 2 == 0);
        (0..s.len())
            .step_by(2)
            .map(|i| u8::from_str_radix(&s[i..i + 2], 16).unwrap())
            .collect()
    }

    /// RFC 7253 Appendix A sample-results key (AES-128) and nonce stem.
    /// `K = 000102...0F`, nonce = `BBAA99887766554433221100` with the
    /// low byte incremented per case.
    const KEY128: &str = "000102030405060708090A0B0C0D0E0F";

    fn key128() -> Vec<u8> {
        hex(KEY128)
    }

    /// RFC 7253 Appendix A test-vector case: given AAD, plaintext, and
    /// expected `ciphertext ‖ tag`, assert encrypt matches and decrypt
    /// round-trips.
    fn check_case(nonce_hex: &str, aad_hex: &str, pt_hex: &str, expected_hex: &str) {
        let key = key128();
        let nonce = hex(nonce_hex);
        let aad = hex(aad_hex);
        let pt = hex(pt_hex);
        let expected = hex(expected_hex);

        let mut ocb = Ocb::new(&key).unwrap();
        let out = ocb.encrypt(&nonce, &aad, &pt).unwrap();
        assert_eq!(out, expected, "OCB encrypt mismatch (nonce {nonce_hex})");

        let mut ocb2 = Ocb::new(&key).unwrap();
        let back = ocb2.decrypt(&nonce, &aad, &out).unwrap();
        assert_eq!(back, pt, "OCB decrypt mismatch (nonce {nonce_hex})");
    }

    /// RFC 7253 Appendix A case 1 — empty plaintext, empty AAD.
    #[test]
    fn rfc7253_case1_empty() {
        check_case("BBAA99887766554433221100", "", "", "785407BFFFC8AD9EDCC5520AC9111EE6");
    }

    /// RFC 7253 Appendix A case 2 — one AAD block, one plaintext block.
    #[test]
    fn rfc7253_case2_one_block() {
        check_case(
            "BBAA99887766554433221101",
            "0001020304050607",
            "0001020304050607",
            "6820B3657B6F615A5725BDA0D3B4EB3A257C9AF1F8F03009",
        );
    }

    /// RFC 7253 Appendix A case 3 — AAD only (empty plaintext).
    #[test]
    fn rfc7253_case3_aad_only() {
        check_case(
            "BBAA99887766554433221102",
            "0001020304050607",
            "",
            "81017F8203F081277152FADE694A0A00",
        );
    }

    /// RFC 7253 Appendix A case 4 — plaintext with no AAD.
    #[test]
    fn rfc7253_case4_pt_no_aad() {
        check_case(
            "BBAA99887766554433221103",
            "",
            "0001020304050607",
            "45DD69F8F5AAE72414054CD1F35D82760B2CD00D2F99BFA9",
        );
    }

    /// RFC 7253 Appendix A case 5 — one full block of AAD and plaintext.
    #[test]
    fn rfc7253_case5_full_block() {
        check_case(
            "BBAA99887766554433221104",
            "000102030405060708090A0B0C0D0E0F",
            "000102030405060708090A0B0C0D0E0F",
            "571D535B60B277188BE5147170A9A22C3AD7A4FF3835B8C5701C1CCEC8FC3358",
        );
    }

    /// RFC 7253 Appendix A case 7 — one full block of plaintext, no AAD.
    #[test]
    fn rfc7253_case7_pt_no_aad_full() {
        check_case(
            "BBAA99887766554433221106",
            "",
            "000102030405060708090A0B0C0D0E0F",
            "5CE88EC2E0692706A915C00AEB8B2396F40E1C743F52436BDF06D8FA1ECA343D",
        );
    }

    /// RFC 7253 Appendix A case 10 — 24-byte plaintext, no AAD (checks
    /// the L_i doubling cache across multiple blocks).
    #[test]
    fn rfc7253_case10_three_blocks() {
        check_case(
            "BBAA99887766554433221109",
            "",
            "000102030405060708090A0B0C0D0E0F1011121314151617",
            "221BD0DE7FA6FE993ECCD769460A0AF2D6CDED0C395B1C3CE725F32494B9F914D85C0B1EB38357FF",
        );
    }

    /// RFC 7253 Appendix A case 14 — 40-byte (2.5 block) plaintext +
    /// 40-byte AAD, exercising both final partial-block paths.
    #[test]
    fn rfc7253_case14_partial_block() {
        check_case(
            "BBAA9988776655443322110D",
            "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627",
            "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627",
            "D5CA91748410C1751FF8A2F618255B68A0A12E093FF454606E59F9C1D0DDC54B65E8628E568BAD7AED07BA06A4A69483A7035490C5769E60",
        );
    }

    /// RFC 7253 Appendix A case 16 — 40-byte plaintext, no AAD.
    #[test]
    fn rfc7253_case16_partial_no_aad() {
        check_case(
            "BBAA9988776655443322110F",
            "",
            "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627",
            "4412923493C57D5DE0D700F753CCE0D1D2D95060122E9F15A5DDBFC5787E50B5CC55EE507BCB084E479AD363AC366B95A98CA5F3000B1479",
        );
    }

    /// Tampered tag must be rejected (constant-time compare) and no
    /// plaintext returned.
    #[test]
    fn ocb_rejects_tampered_tag() {
        let key = key128();
        let nonce = hex("BBAA99887766554433221103");
        let pt = hex("000102030405060708090A0B0C0D0E0F");

        let mut ocb = Ocb::new(&key).unwrap();
        let mut out = ocb.encrypt(&nonce, b"", &pt).unwrap();
        let last = out.len() - 1;
        out[last] ^= 0x01;

        let mut ocb2 = Ocb::new(&key).unwrap();
        assert!(ocb2.decrypt(&nonce, b"", &out).is_none());
    }

    /// Tampered ciphertext must be rejected.
    #[test]
    fn ocb_rejects_tampered_ciphertext() {
        let key = key128();
        let nonce = hex("BBAA99887766554433221103");
        let pt = hex("000102030405060708090A0B0C0D0E0F");

        let mut ocb = Ocb::new(&key).unwrap();
        let mut out = ocb.encrypt(&nonce, b"", &pt).unwrap();
        out[0] ^= 0x01;

        let mut ocb2 = Ocb::new(&key).unwrap();
        assert!(ocb2.decrypt(&nonce, b"", &out).is_none());
    }

    /// Modified AAD must be detected.
    #[test]
    fn ocb_rejects_modified_aad() {
        let key = key128();
        let nonce = hex("BBAA99887766554433221101");
        let pt = hex("0001020304050607");

        let mut ocb = Ocb::new(&key).unwrap();
        let out = ocb.encrypt(&nonce, &hex("0001020304050607"), &pt).unwrap();

        let mut ocb2 = Ocb::new(&key).unwrap();
        assert!(ocb2.decrypt(&nonce, &hex("0001020304050608"), &out).is_none());
    }

    /// AES-192 and AES-256 round-trip (RFC allows any AES width; the
    /// Appendix A per-case vectors are AES-128 only, so we pin round-trip
    /// here — the per-width *tags* are pinned by the summary KAT below).
    #[test]
    fn ocb_aes192_aes256_roundtrip() {
        for klen in [24usize, 32] {
            let key: Vec<u8> = (0..klen).map(|i| i as u8).collect();
            let nonce = hex("BBAA99887766554433221103");
            let aad = b"associated data";
            let pt = b"a message that spans more than a couple of AES blocks for good measure!!";

            let mut ocb = Ocb::new(&key).unwrap();
            let out = ocb.encrypt(&nonce, aad, pt).unwrap();
            let mut ocb2 = Ocb::new(&key).unwrap();
            let back = ocb2.decrypt(&nonce, aad, &out).unwrap();
            assert_eq!(back.as_slice(), pt.as_slice(), "AES-{} OCB round-trip", klen * 8);
        }
    }

    // ------------------------------------------------------------------
    // RFC 7253 Appendix A summary KAT (all three key widths + high ntz).
    //
    // Provenance: RFC 7253 §Appendix A, "The following algorithm tests a
    // wider variety of inputs." (canonical text:
    // https://www.rfc-editor.org/rfc/rfc7253.txt, IETF May 2014).
    //
    // The 128-iteration loop drives OCB-ENCRYPT over many message/AAD
    // lengths, then a final empty-plaintext OCB-ENCRYPT over the whole
    // accumulated ciphertext C authenticates it. With TAGLEN = 128 the
    // final output is exactly the 16-byte tag. This exercises all three
    // AES widths AND deep L_i doubling (the concatenated C reaches ~22 kB,
    // so single messages inside the final call span well over 128 blocks →
    // high `ntz` in the L_i cache).
    //
    // NOTE (finding): the AES-192 tag is F673F2C3E7174AAE7BAE986CA9F29E17
    // per the RFC text (line 997) — cross-checked against the canonical
    // rfc-editor copy, not a paraphrase.

    /// Big-endian 96-bit (12-byte) nonce `num2str(v, 96)`.
    fn num2str96(v: u32) -> [u8; 12] {
        let mut n = [0u8; 12];
        n[8..].copy_from_slice(&v.to_be_bytes());
        n
    }

    /// Run the RFC 7253 Appendix A summary algorithm for one key length
    /// and return the 16-byte tag (`Output`). `TAGLEN = 128`, so
    /// `K = zeros(KEYLEN-8) || num2str(128, 8)` → last key byte 0x80.
    fn ocb_summary_kat(keylen: usize) -> Vec<u8> {
        let mut key = vec![0u8; keylen];
        *key.last_mut().unwrap() = 128u8; // num2str(TAGLEN=128, 8)

        let mut c: Vec<u8> = Vec::new();
        for i in 0u32..128 {
            // S = zeros(8i) — 8i *bits*, i.e. i zero bytes.
            let s = vec![0u8; i as usize];

            let mut ocb = Ocb::new(&key).unwrap();
            let n = num2str96(3 * i + 1);
            c.extend_from_slice(&ocb.encrypt(&n, &s, &s).unwrap());

            let mut ocb = Ocb::new(&key).unwrap();
            let n = num2str96(3 * i + 2);
            c.extend_from_slice(&ocb.encrypt(&n, &[], &s).unwrap());

            let mut ocb = Ocb::new(&key).unwrap();
            let n = num2str96(3 * i + 3);
            c.extend_from_slice(&ocb.encrypt(&n, &s, &[]).unwrap());
        }

        // Output = OCB-ENCRYPT(K, num2str(385,96), C, <empty>) → tag only.
        let mut ocb = Ocb::new(&key).unwrap();
        let n = num2str96(385);
        ocb.encrypt(&n, &c, &[]).unwrap()
    }

    #[test]
    fn rfc7253_appendix_a_summary_aes128() {
        assert_eq!(ocb_summary_kat(16), hex("67E944D23256C5E0B6C61FA22FDF1EA2"));
    }

    #[test]
    fn rfc7253_appendix_a_summary_aes192() {
        assert_eq!(ocb_summary_kat(24), hex("F673F2C3E7174AAE7BAE986CA9F29E17"));
    }

    #[test]
    fn rfc7253_appendix_a_summary_aes256() {
        assert_eq!(ocb_summary_kat(32), hex("D90EB8E9C977C88B79DD793D7FFA161C"));
    }

    /// Large single-message (> 128 blocks) AES-256 encrypt/decrypt
    /// round-trip. Directly exercises high `ntz(i)` in the `L_i` doubling
    /// cache within one message (the summary KAT reaches high ntz across a
    /// multi-kB final call; this pins it for a single call under AES-256).
    #[test]
    fn ocb_aes256_large_message_high_ntz() {
        let key: Vec<u8> = (0..32u8).collect();
        let nonce = hex("BBAA99887766554433221103");
        let aad = b"high-ntz associated data";
        // 200 full 16-byte blocks + a 7-byte tail: ntz reaches 7 (block 128).
        let pt: Vec<u8> = (0..(200 * 16 + 7)).map(|i| (i * 7 + 3) as u8).collect();

        let mut ocb = Ocb::new(&key).unwrap();
        let out = ocb.encrypt(&nonce, aad, &pt).unwrap();
        assert_eq!(out.len(), pt.len() + TAG_LEN);
        let mut ocb2 = Ocb::new(&key).unwrap();
        let back = ocb2.decrypt(&nonce, aad, &out).unwrap();
        assert_eq!(back, pt, "AES-256 OCB high-ntz round-trip");
    }

    /// Invalid key / nonce lengths rejected.
    #[test]
    fn ocb_rejects_bad_params() {
        assert!(Ocb::new(&[0u8; 17]).is_none());
        let mut ocb = Ocb::new(&key128()).unwrap();
        assert!(ocb.encrypt(&[], b"", b"").is_none()); // empty nonce
        assert!(ocb.encrypt(&[0u8; 16], b"", b"").is_none()); // 16-byte nonce
        assert!(ocb.decrypt(&hex("BBAA99887766554433221100"), b"", &[0u8; 8]).is_none()); // short input
    }
}