arcana/cipher/

xsalsa20.rs

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

//! XSalsa20 stream cipher (DJB, "Extending the Salsa20 nonce").
//!
//! Extension of Salsa20 ([`super::salsa20`]) to a **24-byte nonce**
//! via the HSalsa20 subkey derivation — the Salsa20 analogue of
//! XChaCha20 ([`super::xchacha20poly1305`]). The larger nonce makes it
//! safe to pick nonces at random without a counter, and it is the
//! stream cipher underlying NaCl / libsodium's `crypto_secretbox`
//! (XSalsa20-Poly1305).
//!
//! # Construction
//!
//! Given a 32-byte key `K` and a 24-byte nonce `N`:
//!
//! 1. `subkey = HSalsa20(K, N[0..16])` — a 32-byte derived key.
//! 2. Run `Salsa20(subkey, N[16..24], counter)` — an 8-byte nonce.
//!
//! HSalsa20 runs the 20-round Salsa20 core over a state built exactly
//! like Salsa20's (constants on the diagonal, key in the border, the
//! 16-byte input in the counter+nonce words) but **does not add the
//! input back** and serializes only the eight "invariant" words
//! (indices 0, 5, 10, 15 and 6, 7, 8, 9).
//!
//! # Side-channel posture
//!
//! XSalsa20 inherits Salsa20's posture: pure ARX, no tables, no
//! secret-dependent branches or memory addressing. HSalsa20 uses the
//! same constant-time core (`super::salsa20::rounds`); the only
//! extra work is a fixed-position gather of eight words, which is
//! data-oblivious. Constant-time by construction.
//!
//! # References
//!
//! - D. J. Bernstein, "Extending the Salsa20 nonce" (2011).
//!   <https://cr.yp.to/snuffle/xsalsa-20110204.pdf>
//! - NaCl / libsodium `crypto_stream_xsalsa20`.

use super::salsa20::{Salsa20, rounds};

// ============================================================================
// HSalsa20 (Bernstein, "Extending the Salsa20 nonce")
// ============================================================================

/// "expand 32-byte k" — the four Salsa20 256-bit-key constant words.
const SIGMA: [u32; 4] = [0x6170_7865, 0x3320_646e, 0x7962_2d32, 0x6b20_6574];

/// HSalsa20 subkey derivation: 32-byte key + 16-byte input → 32-byte
/// output.
///
/// Builds the standard Salsa20 state (constants on the diagonal, key
/// in the border, the 16-byte `input` in words 6, 7, 8, 9), runs the
/// 20-round core, then serializes the eight diagonal/invariant words
/// `state[0], state[5], state[10], state[15], state[6], state[7],
/// state[8], state[9]` little-endian — **without** the final
/// `⊞ input` add.
fn hsalsa20(key: &[u8; 32], input: &[u8; 16]) -> [u8; 32] {
    let k = |i: usize| u32::from_le_bytes(key[4 * i..4 * i + 4].try_into().unwrap());
    let n = |i: usize| u32::from_le_bytes(input[4 * i..4 * i + 4].try_into().unwrap());

    let mut s = [0u32; 16];
    s[0] = SIGMA[0];
    s[1] = k(0);
    s[2] = k(1);
    s[3] = k(2);
    s[4] = k(3);
    s[5] = SIGMA[1];
    s[6] = n(0);
    s[7] = n(1);
    s[8] = n(2);
    s[9] = n(3);
    s[10] = SIGMA[2];
    s[11] = k(4);
    s[12] = k(5);
    s[13] = k(6);
    s[14] = k(7);
    s[15] = SIGMA[3];

    rounds(&mut s);

    // Serialize the invariant words (no input add).
    let idx = [0usize, 5, 10, 15, 6, 7, 8, 9];
    let mut out = [0u8; 32];
    for (j, &w) in idx.iter().enumerate() {
        out[4 * j..4 * j + 4].copy_from_slice(&s[w].to_le_bytes());
    }
    out
}

// ============================================================================
// Public API
// ============================================================================

/// XSalsa20 stream cipher with a 24-byte nonce.
///
/// A thin wrapper: it derives a subkey with HSalsa20 from the first 16
/// nonce bytes and runs [`Salsa20`] with the derived key and the
/// remaining 8 nonce bytes.
#[derive(Clone)]
pub struct XSalsa20 {
    inner: Salsa20,
}

impl XSalsa20 {
    /// Initialise XSalsa20 with a 256-bit key, a 24-byte nonce, and an
    /// initial 64-bit block counter (usually 0).
    pub fn new(key: &[u8; 32], nonce: &[u8; 24], counter: u64) -> Self {
        let mut h_in = [0u8; 16];
        h_in.copy_from_slice(&nonce[..16]);
        let subkey = hsalsa20(key, &h_in);

        let mut n8 = [0u8; 8];
        n8.copy_from_slice(&nonce[16..24]);

        // Salsa20 under the derived key with the trailing 8 nonce bytes.
        Self {
            inner: Salsa20::new(&subkey, &n8, counter),
        }
    }

    /// XOR the keystream into `data` in place (symmetric: encrypt or
    /// decrypt). Partial calls are buffered like [`Salsa20`].
    pub fn apply_keystream(&mut self, data: &mut [u8]) {
        self.inner.apply_keystream(data);
    }
}

// ============================================================================
// Tests (NaCl / libsodium 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()
    }

    fn hex_arr<const N: usize>(s: &str) -> [u8; N] {
        let v = hex(s);
        assert_eq!(v.len(), N);
        let mut out = [0u8; N];
        out.copy_from_slice(&v);
        out
    }

    /// HSalsa20 test vector from Bernstein, "Extending the Salsa20
    /// nonce", §7 (the worked example also used by NaCl's tests).
    ///
    /// ```text
    /// k = 1b27556473e985d462cd51197a9a46c7 6009549eac6474f206c4ee0844f68389
    /// n = 69696ee955b62b73cd62bda875fc73d6 8219e0036b7a0b37
    ///     (first 16 bytes → HSalsa20 input)
    /// HSalsa20(k, n[0..16]) =
    ///     dc908dda0b9344a953629b733820778880f3ceb421bb61b91cbd4c3e66256ce4
    /// ```
    #[test]
    fn hsalsa20_djb_vector() {
        let key: [u8; 32] = hex_arr(
            "1b27556473e985d462cd51197a9a46c7\
             6009549eac6474f206c4ee0844f68389",
        );
        let input: [u8; 16] = hex_arr("69696ee955b62b73cd62bda875fc73d6");
        let out = hsalsa20(&key, &input);
        let expected = hex("dc908dda0b9344a953629b733820778880f3ceb421bb61b91cbd4c3e66256ce4");
        assert_eq!(out.to_vec(), expected);
    }

    /// XSalsa20 keystream test vector (NaCl / libsodium
    /// `crypto_stream_xsalsa20`). Encrypting an all-zero buffer yields
    /// the raw keystream, whose first 32 bytes are the well-known
    /// NaCl `secretbox` sub-derivation for this (key, nonce).
    ///
    /// ```text
    /// k = 1b27556473e985d462cd51197a9a46c7 6009549eac6474f206c4ee0844f68389
    /// n = 69696ee955b62b73cd62bda875fc73d6 8219e0036b7a0b37 (24 bytes)
    /// keystream[0..32] =
    ///     eea6a7251c1e72916d11c2cb214d3c25 2539121d8e234e652d651fa4c8cff880
    /// ```
    #[test]
    fn xsalsa20_nacl_keystream_vector() {
        let key: [u8; 32] = hex_arr(
            "1b27556473e985d462cd51197a9a46c7\
             6009549eac6474f206c4ee0844f68389",
        );
        let nonce: [u8; 24] = hex_arr("69696ee955b62b73cd62bda875fc73d68219e0036b7a0b37");

        let mut ks = [0u8; 32];
        XSalsa20::new(&key, &nonce, 0).apply_keystream(&mut ks);
        let expected = hex("eea6a7251c1e72916d11c2cb214d3c25\
             2539121d8e234e652d651fa4c8cff880");
        assert_eq!(ks.to_vec(), expected);
    }

    /// Round-trip: XSalsa20 is symmetric.
    #[test]
    fn xsalsa20_roundtrip() {
        let key = [0x24u8; 32];
        let nonce = [0x91u8; 24];
        let pt = b"XSalsa20 round-trip test message spanning multiple 64-byte blocks !!";
        let mut buf = pt.to_vec();

        XSalsa20::new(&key, &nonce, 0).apply_keystream(&mut buf);
        assert_ne!(buf.as_slice(), pt.as_slice());
        XSalsa20::new(&key, &nonce, 0).apply_keystream(&mut buf);
        assert_eq!(buf.as_slice(), pt.as_slice());
    }
}