gmcrypto-core 1.11.1

//! TLCP record protection (GB/T 38636-2020 §6.3) — the protect/deprotect
//! primitives for the four SM2-family suites.
//!
//! TLCP is TLS-1.1-with-SM-algorithms; record version on the wire is
//! `0x0101`; maximum record plaintext is `2^14` bytes. This module is the
//! crypto core only: byte-in / byte-out, **no 5-byte header framing**, no
//! fragmentation, no sequence-number bookkeeping, no I/O. The 5-byte record
//! header is the caller's; `type`/`version` ride in as explicit parameters
//! because they are MAC/AAD-bound.
//!
//! # Engine shape
//!
//! Stateless and policy-free (decomposition §5): the caller holds the
//! sequence number (`seq: u64`), supplies per-record RNG for the CBC
//! explicit IV, and owns key placement. A future sans-I/O TLCP engine can
//! drive these primitives directly.
//!
//! # Suites
//!
//! - **SM4-CBC** (`ECC/ECDHE_SM4_CBC_SM3`): TLS-1.1-style explicit
//!   per-record IV, **MAC-then-encrypt**, TLS padding (every pad byte equals
//!   the pad-length byte). Record MAC = HMAC-SM3 over
//!   `seq(8) ‖ type(1) ‖ version(2) ‖ length(2) ‖ plaintext`. Pure-core
//!   (feature `tlcp`).
//! - **SM4-GCM** (`ECC/ECDHE_SM4_GCM_SM3`): RFC 5288 TLS-1.2 AEAD shape —
//!   nonce = 4-byte implicit salt ‖ 8-byte explicit (seq-derived) nonce;
//!   AAD = `seq ‖ type ‖ version ‖ length`; 16-byte tag. Requires feature
//!   `sm4-aead` in addition to `tlcp` (it composes `sm4::mode_gcm`).
//!
//! # Constant-time CBC deprotect (Lucky13)
//!
//! [`deprotect_cbc`] is a single operation that is constant-time over BOTH
//! the TLS padding validity AND the MAC comparison. The secret post-strip
//! plaintext length is never allowed to influence the work done: the
//! inner-HMAC SM3 is computed over a fixed, public block schedule with every
//! byte chosen by constant-time selection (`mac_ct` — not the streaming
//! hasher plus dummy compressions, which left length-dependent buffering and
//! padding branches; see its doc), the pad-validity scan covers a fixed
//! window, and the MAC is extracted at its secret offset by a
//! data-independent scan. A bad-padding record still runs the full MAC.
//! There is a single failure mode (`None`) and no plaintext escapes on
//! failure.
//!
//! # Misuse warning — `(key, seq)` uniqueness is the caller's contract
//!
//! These primitives take `seq` explicitly and **cannot detect reuse or
//! wrap**. Reusing a `(key, seq)` pair is catastrophic — for GCM it repeats
//! the `salt ‖ explicit_nonce` and breaks confidentiality + integrity; for
//! CBC it leaks plaintext equality. In TLCP the Finished-gated handshake
//! guarantees fresh keys per connection and the sequence number increments
//! per record. A future stateful wrapper would enforce wrap → reject; the
//! stateless layer here cannot. Never reuse a `(direction_key, seq)`.

use crate::sm3::BLOCK_SIZE as SM3_BLOCK;
use crate::sm4::cipher::Sm4Cipher;
use crate::tlcp::key_schedule::TlcpRole;
use alloc::vec::Vec;
use rand_core::TryCryptoRng;
use subtle::{
    Choice, ConditionallySelectable, ConstantTimeEq, ConstantTimeGreater, ConstantTimeLess,
};
use zeroize::{Zeroize, ZeroizeOnDrop};

/// TLCP record version on the wire (GB/T 38636: TLS-1.1-style `0x0101`).
///
/// Provided as a convenience; `version` is a caller parameter on every
/// protect/deprotect call (engine-shaped explicit input), not a hardcoded
/// constant inside the primitives.
pub const TLCP_RECORD_VERSION: [u8; 2] = [0x01, 0x01];

/// The SM4-CBC key-block length (carved per-direction into [`RecordKeysCbc`]
/// via [`RecordKeysCbc::from_key_block`]).
pub const CBC_KEY_BLOCK_LEN: usize = 128;

/// The SM4-GCM key-block length (carved per-direction into [`RecordKeysGcm`]).
#[cfg(feature = "sm4-aead")]
pub const GCM_KEY_BLOCK_LEN: usize = 40;

/// HMAC-SM3 record MAC length.
const MAC_LEN: usize = 32;
/// TLS MAC/AAD header length: `seq(8) ‖ type(1) ‖ version(2) ‖ length(2)`.
const HEADER_LEN: usize = 13;
/// TLCP record plaintext ceiling (`2^14`).
const MAX_PLAINTEXT: usize = 1 << 14;

// ===========================================================================
// Key carriers
// ===========================================================================

/// One direction's SM4-CBC record keys, carved from the key block.
///
/// The IV is NOT stored — TLCP CBC uses a fresh RNG-injected explicit IV per
/// record (the key-block IV bytes are vestigial). `ZeroizeOnDrop`.
#[derive(Clone, ZeroizeOnDrop)]
pub struct RecordKeysCbc {
    pub(crate) mac_key: [u8; 32],
    pub(crate) enc_key: [u8; 16],
}

/// One direction's SM4-GCM record keys (4-byte salt = implicit nonce half).
/// `ZeroizeOnDrop`. Requires feature `sm4-aead`.
#[cfg(feature = "sm4-aead")]
#[derive(Clone, ZeroizeOnDrop)]
pub struct RecordKeysGcm {
    pub(crate) enc_key: [u8; 16],
    pub(crate) salt: [u8; 4],
}

impl RecordKeysCbc {
    /// Carve the client-half keys: `client_MAC (0..32)` ‖ `client_key (64..80)`.
    #[must_use]
    pub fn client_half(key_block: &[u8; 128]) -> Self {
        let mut mac_key = [0u8; 32];
        let mut enc_key = [0u8; 16];
        mac_key.copy_from_slice(&key_block[0..32]);
        enc_key.copy_from_slice(&key_block[64..80]);
        Self { mac_key, enc_key }
    }

    /// Carve the server-half keys: `server_MAC (32..64)` ‖ `server_key (80..96)`.
    #[must_use]
    pub fn server_half(key_block: &[u8; 128]) -> Self {
        let mut mac_key = [0u8; 32];
        let mut enc_key = [0u8; 16];
        mac_key.copy_from_slice(&key_block[32..64]);
        enc_key.copy_from_slice(&key_block[80..96]);
        Self { mac_key, enc_key }
    }

    /// Carve the half identified by `role` (`Client → client_half`,
    /// `Server → server_half`). `role` is public, so the dispatch is not a
    /// secret branch. A client writes with the client half and reads with
    /// the server half (the role→direction mapping is the caller's).
    #[must_use]
    pub fn from_key_block(role: TlcpRole, key_block: &[u8; 128]) -> Self {
        match role {
            TlcpRole::Client => Self::client_half(key_block),
            TlcpRole::Server => Self::server_half(key_block),
        }
    }
}

#[cfg(feature = "sm4-aead")]
impl RecordKeysGcm {
    /// Carve the client-half keys: `client_key (0..16)` ‖ `client_salt (32..36)`.
    #[must_use]
    pub fn client_half(key_block: &[u8; 40]) -> Self {
        let mut enc_key = [0u8; 16];
        let mut salt = [0u8; 4];
        enc_key.copy_from_slice(&key_block[0..16]);
        salt.copy_from_slice(&key_block[32..36]);
        Self { enc_key, salt }
    }

    /// Carve the server-half keys: `server_key (16..32)` ‖ `server_salt (36..40)`.
    #[must_use]
    pub fn server_half(key_block: &[u8; 40]) -> Self {
        let mut enc_key = [0u8; 16];
        let mut salt = [0u8; 4];
        enc_key.copy_from_slice(&key_block[16..32]);
        salt.copy_from_slice(&key_block[36..40]);
        Self { enc_key, salt }
    }

    /// Carve the half identified by `role` (`Client → client_half`,
    /// `Server → server_half`).
    #[must_use]
    pub fn from_key_block(role: TlcpRole, key_block: &[u8; 40]) -> Self {
        match role {
            TlcpRole::Client => Self::client_half(key_block),
            TlcpRole::Server => Self::server_half(key_block),
        }
    }
}

// ===========================================================================
// Shared 13-byte MAC/AAD header
// ===========================================================================

/// The 13-byte TLS MAC/AAD header `seq(8) ‖ type(1) ‖ version(2) ‖ len(2)`.
/// `len` is the PLAINTEXT length.
fn record_header(seq: u64, content_type: u8, version: [u8; 2], len: u16) -> [u8; HEADER_LEN] {
    let mut h = [0u8; HEADER_LEN];
    h[0..8].copy_from_slice(&seq.to_be_bytes());
    h[8] = content_type;
    h[9..11].copy_from_slice(&version);
    h[11..13].copy_from_slice(&len.to_be_bytes());
    h
}

// ===========================================================================
// SM4-GCM record (RFC 5288 TLS-1.2 shape) — feature `sm4-aead`
// ===========================================================================

#[cfg(feature = "sm4-aead")]
fn gcm_nonce(salt: [u8; 4], explicit: [u8; 8]) -> [u8; 12] {
    let mut nonce = [0u8; 12];
    nonce[0..4].copy_from_slice(&salt);
    nonce[4..12].copy_from_slice(&explicit);
    nonce
}

/// Protect a plaintext record under SM4-GCM. Output =
/// `explicit_nonce(8) ‖ ciphertext ‖ tag(16)`.
///
/// The 8-byte explicit nonce is derived from `seq` (big-endian) and prepended
/// to the wire; AAD = `seq ‖ type ‖ version ‖ length`. Returns `None` only if
/// `plaintext.len() > 2^14`. See the module misuse warning: never reuse
/// `(key, seq)`.
#[cfg(feature = "sm4-aead")]
#[must_use]
pub fn protect_gcm(
    keys: &RecordKeysGcm,
    seq: u64,
    content_type: u8,
    version: [u8; 2],
    plaintext: &[u8],
) -> Option<Vec<u8>> {
    if plaintext.len() > MAX_PLAINTEXT {
        return None;
    }
    // len == plaintext.len() == ciphertext.len() for GCM (AEAD, length-preserving);
    // the deprotect side recomputes the same value from the public ciphertext length.
    let len = u16::try_from(plaintext.len()).ok()?;
    let explicit = seq.to_be_bytes();
    let nonce = gcm_nonce(keys.salt, explicit);
    let aad = record_header(seq, content_type, version, len);
    let (ct, tag) = crate::sm4::mode_gcm::encrypt(&keys.enc_key, &nonce, &aad, plaintext)?;
    let mut out = Vec::with_capacity(8 + ct.len() + 16);
    out.extend_from_slice(&explicit);
    out.extend_from_slice(&ct);
    out.extend_from_slice(&tag);
    Some(out)
}

/// Deprotect an SM4-GCM record. `record = explicit_nonce(8) ‖ ct ‖ tag(16)`.
///
/// The explicit nonce is read from the wire (RFC 5288) while `AAD.seq` uses
/// the caller-held `seq`. Returns `Some(plaintext)` iff the tag verifies
/// (commit-on-verify via `mode_gcm`), `None` otherwise — no plaintext on
/// failure.
#[cfg(feature = "sm4-aead")]
#[must_use]
pub fn deprotect_gcm(
    keys: &RecordKeysGcm,
    seq: u64,
    content_type: u8,
    version: [u8; 2],
    record: &[u8],
) -> Option<Vec<u8>> {
    if record.len() < 8 + 16 {
        return None;
    }
    let ct_len = record.len() - 8 - 16;
    if ct_len > MAX_PLAINTEXT {
        return None;
    }
    let len = u16::try_from(ct_len).ok()?;
    let mut explicit = [0u8; 8];
    explicit.copy_from_slice(&record[0..8]);
    let nonce = gcm_nonce(keys.salt, explicit);
    let ct = &record[8..8 + ct_len];
    let mut tag = [0u8; 16];
    tag.copy_from_slice(&record[8 + ct_len..]);
    let aad = record_header(seq, content_type, version, len);
    crate::sm4::mode_gcm::decrypt(&keys.enc_key, &nonce, &aad, ct, &tag)
}

// ===========================================================================
// SM4-CBC record — the Lucky13 deprotect (feature `tlcp`)
// ===========================================================================

/// SM3 inner-hash compression-block count for an HMAC over a
/// `plaintext_len`-byte payload: the inner input is
/// `K'⊕ipad(64) ‖ header(13) ‖ plaintext(P)`, then SM3 finalize appends
/// `0x80` + an 8-byte length (≥ 9 pad bytes; an extra block when the partial
/// fill is `≥ 56`, matching `sm3::finalize`'s `buffer_len > 56` rule).
///
/// Test-only since the v1.11.1 rewrite: it pins that [`mac_ct`]'s fixed
/// schedule (`1 + ct_inner_blocks(13 + max)`) equals the count the v1.7
/// dummy-compression equalization already paid.
#[cfg(test)]
#[inline]
fn inner_blocks(plaintext_len: usize) -> usize {
    let n = SM3_BLOCK + HEADER_LEN + plaintext_len;
    n / SM3_BLOCK + 1 + usize::from(n % SM3_BLOCK >= SM3_BLOCK - 8)
}

/// SM3 blocks after the `K'⊕ipad` block needed to absorb a `msg_len`-byte
/// message plus its padding (`0x80`, zeros, 8-byte bit length): `⌈(L+9)/64⌉`.
/// Called on the PUBLIC bound only.
#[inline]
const fn ct_inner_blocks(msg_len: usize) -> usize {
    (msg_len + 9).div_ceil(SM3_BLOCK)
}

/// HMAC-SM3 over `header ‖ data[..plaintext_len]` in constant time with
/// respect to the SECRET `plaintext_len` (Lucky13 surface #1).
///
/// `data` is the public-length candidate region (`body[..max_plaintext_len]`
/// in [`deprotect_cbc`]); `plaintext_len ≤ data.len()` is the caller's
/// contract (a violation cannot panic — it yields a wrong MAC, so the record
/// fails closed). The MAC value equals ordinary `HmacSm3` over the true-length
/// message; only the *work* is made length-independent.
///
/// # Why not `HmacSm3` + dummy compressions (v1.7 – v1.11.0)
///
/// Topping the compression *count* up to the public bound leaves
/// [`crate::sm3::Sm3`]'s streaming path secret-dependent: `update` copies a
/// secret-length tail into its buffer and branches on the fill, and
/// `finalize` takes the one- or two-block padding path on `buffer_len > 56`.
/// That residual sat under the dudect gate on the EPYC 7763 runners the gate
/// was calibrated on, but read `|tau| ≈ 0.30` at 100K samples on Zen 4 / Xeon
/// 8573C once the v1.11.1 SM4 repair shrank the window around it
/// (`docs/v1.11.1-release-review.md`, dudect note). This is the standard
/// remedy (the shape of OpenSSL's `ssl3_cbc_digest_record`): process a
/// FIXED, public number of blocks; build every byte by constant-time
/// selection (message / `0x80` / zero / length field); select the digest
/// state at the secret final-block index with masks. The block schedule
/// equals what the dummy-compression version already paid, so the fix adds
/// no SM3 work — only the per-byte selects.
///
/// All control flow depends on public quantities (`header`, `data.len()`,
/// block and byte indices). Every use of `plaintext_len` goes through
/// `subtle` (`ct_lt` / `ct_eq` / `conditional_select`) or a shift.
#[allow(clippy::cast_possible_truncation, clippy::cast_lossless)]
pub(crate) fn mac_ct(
    mac_key: &[u8; 32],
    header: &[u8; HEADER_LEN],
    data: &[u8],
    plaintext_len: usize,
) -> [u8; 32] {
    // ---- key schedule: fixed cost (the MAC key is exactly 32 bytes) ----
    let mut ipad = [0x36u8; SM3_BLOCK];
    let mut opad = [0x5cu8; SM3_BLOCK];
    for i in 0..mac_key.len() {
        ipad[i] ^= mac_key[i];
        opad[i] ^= mac_key[i];
    }
    let mut state = crate::sm3::IV;
    crate::sm3::compress(&mut state, &ipad);
    ipad.zeroize();

    // ---- public schedule ----
    let max_len = HEADER_LEN + data.len();
    let blocks = ct_inner_blocks(max_len);

    // ---- secret quantities, touched only through CT ops ----
    let msg_len = (HEADER_LEN + plaintext_len) as u64;
    // Block (0-based, after the ipad block) that carries the length field:
    // ⌊(L + 8) / 64⌋ — a shift, no division on a secret.
    let final_block = (msg_len + 8) >> 6;
    // SM3 length field counts the ipad block too.
    let len_bytes = ((SM3_BLOCK as u64 + msg_len) << 3).to_be_bytes();

    let mut result = [0u32; 8];
    let mut block = [0u8; SM3_BLOCK];
    for b in 0..blocks {
        let is_final = (b as u64).ct_eq(&final_block);
        for i in 0..SM3_BLOCK {
            let p = b * SM3_BLOCK + i;
            // Public candidate byte at position `p`: header, then the
            // candidate region, then zero. Branches here are on PUBLIC values.
            let cand = if p < HEADER_LEN {
                header[p]
            } else if p - HEADER_LEN < data.len() {
                data[p - HEADER_LEN]
            } else {
                0
            };
            let pu = p as u64;
            let in_msg = pu.ct_lt(&msg_len);
            let at_end = pu.ct_eq(&msg_len);
            let mut byte = u8::conditional_select(&0u8, &cand, in_msg);
            byte = u8::conditional_select(&byte, &0x80u8, at_end);
            if i >= SM3_BLOCK - 8 {
                // Length field occupies the last 8 bytes of the final block.
                // It never collides with the 0x80 byte: when L % 64 ≥ 56 the
                // final block is the NEXT one (the +8 above), so the 0x80
                // sits in the previous block.
                byte = u8::conditional_select(&byte, &len_bytes[i - (SM3_BLOCK - 8)], is_final);
            }
            block[i] = byte;
        }
        crate::sm3::compress(&mut state, &block);
        for (r, s) in result.iter_mut().zip(state.iter()) {
            *r = u32::conditional_select(r, s, is_final);
        }
    }
    block.zeroize();
    state.zeroize();

    let mut inner = [0u8; 32];
    for (w, v) in result.iter().enumerate() {
        inner[w * 4..(w + 1) * 4].copy_from_slice(&v.to_be_bytes());
    }
    result.zeroize();

    // ---- outer hash: fixed-length input, so no secret-dependent path ----
    let mut outer = crate::sm3::Sm3::new();
    outer.update(&opad);
    outer.update(&inner);
    opad.zeroize();
    inner.zeroize();
    outer.finalize()
}

/// Constant-time TLS pad-validity check (Lucky13 surface #2).
///
/// Over `body = plaintext ‖ MAC(32) ‖ padding`, scans a FIXED window of
/// `min(256, body.len())` trailing bytes — no early return, no padlen-bounded
/// loop. Returns `(pad_ok, plaintext_len)`; `plaintext_len` is meaningful only
/// when `pad_ok` (else `0`, and the caller uses the public fallback).
/// Self-checks `body.len() >= 48` (the `strip_pkcs7_ct` self-checking posture).
#[allow(clippy::cast_possible_truncation, clippy::cast_lossless)]
fn check_tls_padding_ct(body: &[u8]) -> (Choice, usize) {
    let n = body.len();
    if n < MAC_LEN + 16 {
        // Public-length precondition (a valid body is ≥ 48); not secret.
        return (Choice::from(0u8), 0);
    }
    let padlen = body[n - 1]; // secret
    let pad_region = padlen as u16 + 1; // bytes that must all equal padlen
    let window = core::cmp::min(256usize, n);
    let mut bad: u8 = 0;
    for i in 0..window {
        let pos = (i as u16) + 1; // 1 = last byte
        let byte = body[n - 1 - i];
        let in_pad = !pos.ct_gt(&pad_region); // pos <= pad_region
        let diff = byte ^ padlen;
        bad |= u8::conditional_select(&0u8, &diff, in_pad);
    }
    // pad_region must leave room for the 32-byte MAC: pad_region <= n - 32.
    // n is bounded by the caller's 2^14 ceiling, so (n - 32) fits u16.
    let region_ok = !pad_region.ct_gt(&((n - MAC_LEN) as u16));
    let ok = region_ok & bad.ct_eq(&0u8);
    // plaintext_len = n - 32 - pad_region (only meaningful when ok).
    let raw = (n as u64)
        .wrapping_sub(MAC_LEN as u64)
        .wrapping_sub(pad_region as u64);
    let plaintext_len = u64::conditional_select(&0u64, &raw, ok) as usize;
    (ok, plaintext_len)
}

/// Copy the 32-byte MAC from its secret offset (Lucky13 surface #3).
///
/// Uses a data-independent scan over the PUBLIC candidate range; never indexes
/// by the secret offset `plaintext_len` directly.
#[allow(clippy::cast_lossless)]
fn extract_mac_ct(body: &[u8], plaintext_len: usize) -> [u8; 32] {
    let n = body.len();
    let mut out = [0u8; 32];
    for i in 0..=(n - MAC_LEN) {
        let hit = (i as u64).ct_eq(&(plaintext_len as u64));
        for j in 0..MAC_LEN {
            out[j] = u8::conditional_select(&out[j], &body[i + j], hit);
        }
    }
    out
}

/// Protect a plaintext record under SM4-CBC (MAC-then-encrypt).
///
/// Output = `explicit_IV(16) ‖ CBC_enc(plaintext ‖ MAC(32) ‖ tls_pad)`. The
/// explicit IV is drawn from `rng` (must be an unpredictable CSPRNG — NIST
/// SP 800-38A). Returns `None` if `plaintext.len() > 2^14` or the RNG fails.
/// See the module misuse warning.
///
/// # Panics
///
/// Never — the `try_into()` on a `chunks_exact_mut(16)` chunk is infallible.
#[allow(clippy::missing_panics_doc)]
#[must_use]
pub fn protect_cbc<R: TryCryptoRng>(
    keys: &RecordKeysCbc,
    seq: u64,
    content_type: u8,
    version: [u8; 2],
    plaintext: &[u8],
    rng: &mut R,
) -> Option<Vec<u8>> {
    if plaintext.len() > MAX_PLAINTEXT {
        return None;
    }
    let len = u16::try_from(plaintext.len()).ok()?;
    let hdr = record_header(seq, content_type, version, len);
    let mut h = crate::hmac::HmacSm3::new(&keys.mac_key);
    h.update(&hdr);
    h.update(plaintext);
    let mac = h.finalize();

    // Build the wire record in one buffer — explicit IV (RNG, in the clear) ‖
    // plaintext ‖ MAC ‖ TLS padding — then CBC-encrypt in place over the body
    // (everything after the IV). Single allocation, no second copy.
    let mut iv = [0u8; 16];
    rng.try_fill_bytes(&mut iv).ok()?;

    let mut out = Vec::with_capacity(16 + plaintext.len() + MAC_LEN + 16);
    out.extend_from_slice(&iv);
    out.extend_from_slice(plaintext);
    out.extend_from_slice(&mac);
    // TLS padding: padlen+1 bytes each == padlen, filling the body (after the
    // 16-byte IV) to a 16-multiple.
    let padlen = 15 - ((out.len() - 16) % 16);
    #[allow(clippy::cast_possible_truncation)]
    let padbyte = padlen as u8;
    for _ in 0..=padlen {
        out.push(padbyte);
    }

    let cipher = Sm4Cipher::new(&keys.enc_key);
    let mut prev = iv;
    for chunk in out[16..].chunks_exact_mut(16) {
        let block: &mut [u8; 16] = chunk.try_into().expect("16-byte chunk");
        for j in 0..16 {
            block[j] ^= prev[j];
        }
        cipher.encrypt_block(block);
        prev = *block;
    }
    Some(out)
}

/// Deprotect an SM4-CBC record — the Lucky13-hardened single operation.
///
/// `record = explicit_IV(16) ‖ CBC_ct`. Public-length guards run first; then
/// raw CBC decrypt, the constant-time pad check (#2), the equalized MAC over
/// the recovered fragment (#1), the constant-time MAC extraction (#3), and a
/// single final `pad_ok & mac_ok` merge. Returns `Some(plaintext)` iff both
/// hold; `None` otherwise — no plaintext on failure, single failure mode.
/// The returned `Vec` is caller-owned and NOT zeroized by the SDK.
///
/// # Panics
///
/// Never — the `try_into()` on a `chunks_exact_mut(16)` chunk is infallible.
#[allow(
    clippy::cast_possible_truncation,
    clippy::cast_lossless,
    clippy::missing_panics_doc
)]
#[must_use]
pub fn deprotect_cbc(
    keys: &RecordKeysCbc,
    seq: u64,
    content_type: u8,
    version: [u8; 2],
    record: &[u8],
) -> Option<Vec<u8>> {
    // ---- public-length guards (no secret) ----
    if record.len() < 16 + MAC_LEN + 16 {
        return None; // IV + minimum body (0 plaintext + 32 MAC + 16 pad block)
    }
    let body_len = record.len() - 16;
    if body_len % 16 != 0 {
        return None;
    }
    if body_len > MAX_PLAINTEXT + MAC_LEN + 16 {
        return None; // 2^14 ceiling — bounds n so the u16 casts below are lossless
    }

    let mut iv = [0u8; 16];
    iv.copy_from_slice(&record[0..16]);
    let mut body = record[16..].to_vec();

    // ---- raw CBC decrypt (no unpad) ----
    let cipher = Sm4Cipher::new(&keys.enc_key);
    let mut prev = iv;
    for chunk in body.chunks_exact_mut(16) {
        let block: &mut [u8; 16] = chunk.try_into().expect("16-byte chunk");
        let saved = *block;
        cipher.decrypt_block(block);
        for j in 0..16 {
            block[j] ^= prev[j];
        }
        prev = saved;
    }

    // ---- surface #2: constant-time pad-validity check ----
    let (pad_ok, plaintext_len) = check_tls_padding_ct(&body);
    // Public safe upper bound (never reduced) for the equalization (#1).
    let max_plaintext_len = body_len - MAC_LEN - 1;
    // On bad pad, MAC still runs over the fallback length (never short-circuit).
    let eff_len =
        u64::conditional_select(&(max_plaintext_len as u64), &(plaintext_len as u64), pad_ok)
            as usize;
    // eff_len <= max_plaintext_len <= 2^14, so the u16 cast is lossless by the
    // ceiling guard — no fallible `?` on a secret length.
    let len16 = eff_len as u16;
    let hdr = record_header(seq, content_type, version, len16);

    // ---- surface #1: constant-time MAC; surface #3: CT MAC extraction ----
    // The candidate region is the PUBLIC-length prefix; the secret `eff_len`
    // enters `mac_ct` only through constant-time selection.
    let computed = mac_ct(&keys.mac_key, &hdr, &body[..max_plaintext_len], eff_len);
    let received = extract_mac_ct(&body, eff_len);
    let mac_ok = computed.ct_eq(&received);

    // ---- one final merge ----
    let valid = pad_ok & mac_ok;
    if bool::from(valid) {
        body.truncate(eff_len);
        Some(body)
    } else {
        body.zeroize();
        None
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::cast_possible_truncation)]
    use super::*;
    use rand_core::TryRng;

    /// Test-only fixed-bytes RNG (the repo `FixedRng` idiom).
    struct CountRng(u8);
    impl TryRng for CountRng {
        type Error = core::convert::Infallible;
        fn try_next_u32(&mut self) -> core::result::Result<u32, Self::Error> {
            Ok(0)
        }
        fn try_next_u64(&mut self) -> core::result::Result<u64, Self::Error> {
            Ok(0)
        }
        fn try_fill_bytes(&mut self, dst: &mut [u8]) -> core::result::Result<(), Self::Error> {
            for b in dst.iter_mut() {
                *b = self.0;
                self.0 = self.0.wrapping_add(1);
            }
            Ok(())
        }
    }
    impl TryCryptoRng for CountRng {}

    fn cbc_keys() -> RecordKeysCbc {
        let mut kb = [0u8; 128];
        for (i, b) in kb.iter_mut().enumerate() {
            *b = (i as u8).wrapping_mul(3).wrapping_add(1);
        }
        RecordKeysCbc::client_half(&kb)
    }

    #[test]
    fn cbc_keys_carve_offsets() {
        let mut kb = [0u8; 128];
        for (i, b) in kb.iter_mut().enumerate() {
            *b = i as u8;
        }
        let c = RecordKeysCbc::client_half(&kb);
        let s = RecordKeysCbc::server_half(&kb);
        assert_eq!(c.mac_key, kb[0..32]);
        assert_eq!(c.enc_key, kb[64..80]);
        assert_eq!(s.mac_key, kb[32..64]);
        assert_eq!(s.enc_key, kb[80..96]);
        // from_key_block delegates.
        assert_eq!(
            RecordKeysCbc::from_key_block(TlcpRole::Client, &kb).enc_key,
            c.enc_key
        );
        assert_eq!(
            RecordKeysCbc::from_key_block(TlcpRole::Server, &kb).mac_key,
            s.mac_key
        );
    }

    #[test]
    fn inner_blocks_matches_sm3_spill_rule() {
        // Cross-check inner_blocks against a direct count of compress calls
        // for an HMAC over header(13)+plaintext(P): inner input length is
        // 64 + 13 + P, padded with 0x80 + 8-byte length.
        for p in [0usize, 1, 42, 43, 44, 55, 56, 57, 100, 256, 1000] {
            let n = 64 + 13 + p;
            // ceil((n + 9) / 64): the +9 = 0x80 byte + 8-byte length.
            let expected = (n + 9).div_ceil(64);
            assert_eq!(inner_blocks(p), expected, "p={p}");
        }
    }

    #[test]
    fn ct_mac_matches_hmac_for_every_length_under_every_bound() {
        // The constant-time inner hash must reproduce ordinary HMAC-SM3 over
        // `header ‖ data[..plen]` for EVERY secret length `plen` ≤ the public
        // bound, including every `plen % 64` (both sides of the SM3 padding
        // spill at a 56-byte partial fill) and the `plen == max` edge.
        let mac_key = [0x2bu8; 32];
        for max in [
            0usize, 1, 42, 43, 50, 51, 55, 56, 57, 64, 127, 128, 200, 300,
        ] {
            let data: Vec<u8> = (0..max).map(|i| (i * 7 + 3) as u8).collect();
            for plen in 0..=max {
                let hdr = record_header(9, 0x17, TLCP_RECORD_VERSION, plen as u16);
                let mut h = crate::hmac::HmacSm3::new(&mac_key);
                h.update(&hdr);
                h.update(&data[..plen]);
                let want = h.finalize();
                let got = mac_ct(&mac_key, &hdr, &data, plen);
                assert_eq!(got, want, "ct MAC must equal HMAC, max={max} plen={plen}");
            }
        }
        // A large bound with sampled lengths (the 2^14 ceiling region).
        let max = MAX_PLAINTEXT;
        let data: Vec<u8> = (0..max).map(|i| (i * 13 + 1) as u8).collect();
        for plen in [0usize, 1, 63, 64, 4095, 4096, 16000, max - 1, max] {
            let hdr = record_header(7, 0x17, TLCP_RECORD_VERSION, plen as u16);
            let mut h = crate::hmac::HmacSm3::new(&mac_key);
            h.update(&hdr);
            h.update(&data[..plen]);
            assert_eq!(
                mac_ct(&mac_key, &hdr, &data, plen),
                h.finalize(),
                "plen={plen}"
            );
        }
    }

    #[test]
    fn ct_mac_block_count_depends_only_on_the_public_bound() {
        // The fixed block schedule is `1 (ipad) + ct_inner_blocks(max)`, and it
        // must equal `inner_blocks(max)` — the count the v1.7 dummy-compression
        // equalization already paid — for every bound, so the CT rewrite costs
        // no extra SM3 work. It must not depend on `plen` at all (it is computed
        // from the public bound alone; this pins the arithmetic).
        for max in [
            0usize,
            1,
            42,
            43,
            50,
            51,
            55,
            56,
            57,
            64,
            100,
            127,
            128,
            1000,
            MAX_PLAINTEXT,
        ] {
            assert_eq!(
                1 + ct_inner_blocks(HEADER_LEN + max),
                inner_blocks(max),
                "block schedule for max={max}"
            );
        }
    }

    #[test]
    fn cbc_round_trip_boundary_lengths() {
        let keys = cbc_keys();
        for len in [
            0usize,
            1,
            15,
            16,
            17,
            31,
            32,
            47,
            48,
            100,
            1000,
            MAX_PLAINTEXT,
        ] {
            let pt: Vec<u8> = (0..len).map(|i| (i as u8).wrapping_mul(7)).collect();
            let mut rng = CountRng(0xA0);
            let rec = protect_cbc(&keys, 42, 0x17, TLCP_RECORD_VERSION, &pt, &mut rng).unwrap();
            assert_eq!((rec.len() - 16) % 16, 0, "block-aligned body, len={len}");
            let got = deprotect_cbc(&keys, 42, 0x17, TLCP_RECORD_VERSION, &rec);
            assert_eq!(got.as_deref(), Some(&pt[..]), "round-trip len={len}");
        }
    }

    #[test]
    fn cbc_rejects_tamper_and_wrong_context() {
        let keys = cbc_keys();
        let pt = b"the quick brown fox jumps over the lazy tlcp record";
        let mut rng = CountRng(0x11);
        let rec = protect_cbc(&keys, 7, 0x17, TLCP_RECORD_VERSION, pt, &mut rng).unwrap();
        // wrong seq
        assert!(deprotect_cbc(&keys, 8, 0x17, TLCP_RECORD_VERSION, &rec).is_none());
        // wrong type
        assert!(deprotect_cbc(&keys, 7, 0x16, TLCP_RECORD_VERSION, &rec).is_none());
        // per-byte tamper anywhere → None
        for i in 0..rec.len() {
            let mut t = rec.clone();
            t[i] ^= 0x01;
            assert!(
                deprotect_cbc(&keys, 7, 0x17, TLCP_RECORD_VERSION, &t).is_none(),
                "tamper at byte {i} must reject"
            );
        }
    }

    #[test]
    fn cbc_rejects_malformed_lengths() {
        let keys = cbc_keys();
        // too short (< 16+48)
        assert!(deprotect_cbc(&keys, 0, 0x17, TLCP_RECORD_VERSION, &[0u8; 63]).is_none());
        // body not a 16-multiple
        assert!(deprotect_cbc(&keys, 0, 0x17, TLCP_RECORD_VERSION, &[0u8; 16 + 48 + 1]).is_none());
        // over the 2^14 ceiling
        let huge = alloc::vec![0u8; 16 + MAX_PLAINTEXT + MAC_LEN + 16 + 16];
        assert!(deprotect_cbc(&keys, 0, 0x17, TLCP_RECORD_VERSION, &huge).is_none());
    }

    #[test]
    fn pad_check_accepts_and_rejects() {
        // Build a 48-byte body: 0 plaintext + 32 MAC + 16-byte pad (padlen 15).
        let mut body = alloc::vec![0u8; 48];
        for b in body.iter_mut().skip(32) {
            *b = 15;
        }
        let (ok, pl) = check_tls_padding_ct(&body);
        assert!(bool::from(ok));
        assert_eq!(pl, 0);
        // corrupt one pad byte → reject
        body[40] = 14;
        assert!(!bool::from(check_tls_padding_ct(&body).0));
        // oversized padlen (255 in a 48-byte body) → reject
        let mut body2 = alloc::vec![0xffu8; 48];
        body2[47] = 0xff;
        assert!(!bool::from(check_tls_padding_ct(&body2).0));
    }

    #[test]
    fn extract_mac_ct_matches_slice() {
        let mut body = alloc::vec![0u8; 100];
        for (i, b) in body.iter_mut().enumerate() {
            *b = i as u8;
        }
        for off in [0usize, 1, 33, 68] {
            let got = extract_mac_ct(&body, off);
            assert_eq!(&got[..], &body[off..off + 32], "offset {off}");
        }
    }

    #[cfg(feature = "sm4-aead")]
    #[test]
    fn gcm_round_trip_and_context() {
        let mut kb = [0u8; 40];
        for (i, b) in kb.iter_mut().enumerate() {
            *b = (i as u8).wrapping_mul(5).wrapping_add(2);
        }
        let keys = RecordKeysGcm::client_half(&kb);
        for len in [0usize, 1, 16, 100, MAX_PLAINTEXT] {
            let pt: Vec<u8> = (0..len).map(|i| i as u8).collect();
            let rec = protect_gcm(&keys, 5, 0x17, TLCP_RECORD_VERSION, &pt).unwrap();
            assert_eq!(rec.len(), 8 + pt.len() + 16);
            assert_eq!(&rec[0..8], &5u64.to_be_bytes());
            assert_eq!(
                deprotect_gcm(&keys, 5, 0x17, TLCP_RECORD_VERSION, &rec).as_deref(),
                Some(&pt[..]),
                "gcm round-trip len={len}"
            );
        }
        // wrong seq in AAD → reject
        let rec = protect_gcm(&keys, 5, 0x17, TLCP_RECORD_VERSION, b"x").unwrap();
        assert!(deprotect_gcm(&keys, 6, 0x17, TLCP_RECORD_VERSION, &rec).is_none());
    }

    #[cfg(feature = "sm4-aead")]
    #[test]
    fn gcm_keys_carve_offsets() {
        let mut kb = [0u8; 40];
        for (i, b) in kb.iter_mut().enumerate() {
            *b = i as u8;
        }
        let c = RecordKeysGcm::client_half(&kb);
        let s = RecordKeysGcm::server_half(&kb);
        assert_eq!(c.enc_key, kb[0..16]);
        assert_eq!(c.salt, kb[32..36]);
        assert_eq!(s.enc_key, kb[16..32]);
        assert_eq!(s.salt, kb[36..40]);
    }
}