arcana/cipher/

salsa20.rs

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

//! Salsa20 stream cipher (Bernstein, eSTREAM / DJB spec).
//!
//! The original ARX stream cipher from the eSTREAM portfolio, and the
//! direct ancestor of ChaCha20 ([`super::chacha20`]). Salsa20 uses the
//! same "expand 32-byte k" / "expand 16-byte k" constants, a 4×4 u32
//! state, and 20 rounds (10 double-rounds), but with a different
//! quarter-round and a different word layout (constants on the
//! diagonal, key on two rows, counter+nonce on a row).
//!
//! This is the **DJB / eSTREAM variant**, not the IETF one: the nonce
//! is 8 bytes and the block counter is a 64-bit little-endian value
//! stored in the two words that follow the nonce. The keystream block
//! is 64 bytes. Both the 256-bit and 128-bit key sizes are supported
//! (matching the two sets of expansion constants); see [`Salsa20::new`]
//! and [`Salsa20::new_128`].
//!
//! Salsa20 is still used, mostly through XSalsa20 ([`super::xsalsa20`])
//! and the NaCl / libsodium `secretbox` construction, which pairs
//! XSalsa20 with Poly1305.
//!
//! # Layout
//!
//! ```text
//! state (4x4 u32 little-endian):
//!
//!   const  key    key    key
//!   key    const  nonce  nonce
//!   ctr    ctr    const  key
//!   key    key    key    const
//! ```
//!
//! The four constant words sit on the diagonal (indices 0, 5, 10, 15);
//! the key fills the eight off-diagonal border words; the 8-byte nonce
//! is at words 6, 7 and the 64-bit block counter at words 8, 9.
//!
//! Each 64-byte block is computed as `serialize(rounds(state) ⊞
//! state)`, exactly the structure of ChaCha20 but with the Salsa20
//! quarter-round and column/row ordering. Successive blocks increment
//! the 64-bit counter.
//!
//! # Side-channel posture
//!
//! Salsa20 is a pure ARX design: every operation is a 32-bit add,
//! XOR, or constant-distance rotate on public-position words. There
//! are **no table lookups, no secret-dependent branches, and no
//! secret-dependent memory addressing**. The key and counter only
//! ever flow through add/xor/rotate, so the core and the keystream
//! application are constant-time (data-oblivious) by construction —
//! the same posture as ChaCha20 and the reason both are preferred
//! over table-based AES on shared-cache targets.
//!
//! The block-counter loop bound in [`Salsa20::apply_keystream`]
//! depends only on the (public) message length, not on any secret.
//!
//! # References
//!
//! - D. J. Bernstein, "The Salsa20 family of stream ciphers", in *New
//!   Stream Cipher Designs* (2008); "Salsa20 specification"
//!   (eSTREAM, 2005). <https://cr.yp.to/snuffle/spec.pdf>
//! - eSTREAM "verified.test-vectors" ECRYPT test suite.

// ============================================================================
// Quarter-round and core (Salsa20 specification)
// ============================================================================

/// Salsa20 quarter-round on four state words, in place.
///
/// Unlike ChaCha20's quarter-round (four staged updates of all four
/// words), Salsa20's quarter-round updates `b, c, d, a` in turn, each
/// as `x ^= (y ⊞ z) <<< r`:
///
/// ```text
///   b ^= (a ⊞ d) <<<  7
///   c ^= (b ⊞ a) <<<  9
///   d ^= (c ⊞ b) <<< 13
///   a ^= (d ⊞ c) <<< 18
/// ```
#[inline(always)]
pub(crate) fn quarter_round(state: &mut [u32; 16], a: usize, b: usize, c: usize, d: usize) {
    state[b] ^= state[a].wrapping_add(state[d]).rotate_left(7);
    state[c] ^= state[b].wrapping_add(state[a]).rotate_left(9);
    state[d] ^= state[c].wrapping_add(state[b]).rotate_left(13);
    state[a] ^= state[d].wrapping_add(state[c]).rotate_left(18);
}

/// The 20-round Salsa20 core, without the final `⊞ input` and
/// serialization. Operates on a working copy; used by both the block
/// function and by HSalsa20 ([`super::xsalsa20`]).
///
/// 20 rounds = 10 double-rounds; each double-round is 4 column
/// quarter-rounds followed by 4 row quarter-rounds.
#[inline]
pub(crate) fn rounds(working: &mut [u32; 16]) {
    for _ in 0..10 {
        // Column round.
        quarter_round(working, 0, 4, 8, 12);
        quarter_round(working, 5, 9, 13, 1);
        quarter_round(working, 10, 14, 2, 6);
        quarter_round(working, 15, 3, 7, 11);
        // Row round.
        quarter_round(working, 0, 1, 2, 3);
        quarter_round(working, 5, 6, 7, 4);
        quarter_round(working, 10, 11, 8, 9);
        quarter_round(working, 15, 12, 13, 14);
    }
}

/// Compute one 64-byte Salsa20 keystream block from the initial state.
///
/// The output is `serialize(rounds(state) ⊞ state)`, little-endian
/// per 32-bit word — the same "add the untouched input" step that
/// ChaCha20 uses.
fn block(state: &[u32; 16]) -> [u8; 64] {
    let mut working = *state;
    rounds(&mut working);

    let mut out = [0u8; 64];
    for i in 0..16 {
        let word = working[i].wrapping_add(state[i]);
        out[4 * i..4 * i + 4].copy_from_slice(&word.to_le_bytes());
    }
    out
}

// ============================================================================
// State construction
// ============================================================================

/// "expand 32-byte k" — the four 256-bit-key constant words (sigma).
const SIGMA: [u32; 4] = [0x6170_7865, 0x3320_646e, 0x7962_2d32, 0x6b20_6574];
/// "expand 16-byte k" — the four 128-bit-key constant words (tau).
const TAU: [u32; 4] = [0x6170_7865, 0x3120_646e, 0x7962_2d36, 0x6b20_6574];

/// Build the initial Salsa20 state from a 256-bit key, an 8-byte
/// nonce, and a 64-bit block counter.
///
/// The layout places the four constant words on the diagonal (0, 5,
/// 10, 15), the eight key words in the border, the nonce in words
/// 6, 7 and the counter in words 8, 9 (all little-endian).
fn state_256(key: &[u8; 32], nonce: &[u8; 8], counter: u64) -> [u32; 16] {
    let mut s = [0u32; 16];
    let k = |i: usize| u32::from_le_bytes(key[4 * i..4 * i + 4].try_into().unwrap());

    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] = u32::from_le_bytes(nonce[0..4].try_into().unwrap());
    s[7] = u32::from_le_bytes(nonce[4..8].try_into().unwrap());
    s[8] = counter as u32;
    s[9] = (counter >> 32) as u32;
    s[10] = SIGMA[2];
    s[11] = k(4);
    s[12] = k(5);
    s[13] = k(6);
    s[14] = k(7);
    s[15] = SIGMA[3];
    s
}

/// Build the initial Salsa20 state from a 128-bit key (the key is used
/// twice, once per half of the border), an 8-byte nonce, and a 64-bit
/// block counter. Uses the `tau` constants.
fn state_128(key: &[u8; 16], nonce: &[u8; 8], counter: u64) -> [u32; 16] {
    let mut s = [0u32; 16];
    let k = |i: usize| u32::from_le_bytes(key[4 * i..4 * i + 4].try_into().unwrap());

    s[0] = TAU[0];
    s[1] = k(0);
    s[2] = k(1);
    s[3] = k(2);
    s[4] = k(3);
    s[5] = TAU[1];
    s[6] = u32::from_le_bytes(nonce[0..4].try_into().unwrap());
    s[7] = u32::from_le_bytes(nonce[4..8].try_into().unwrap());
    s[8] = counter as u32;
    s[9] = (counter >> 32) as u32;
    s[10] = TAU[2];
    // 128-bit key repeats: words 11..15 reuse k(0..4).
    s[11] = k(0);
    s[12] = k(1);
    s[13] = k(2);
    s[14] = k(3);
    s[15] = TAU[3];
    s
}

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

/// Salsa20 stream cipher state (DJB / eSTREAM variant).
///
/// Holds the initial state (key + nonce + 64-bit counter) and buffers
/// the leftover bytes of the current keystream block so partial calls
/// to [`Self::apply_keystream`] behave like one contiguous stream.
#[derive(Clone)]
pub struct Salsa20 {
    /// Initial 16-word state. The 64-bit counter (words 8, 9) is
    /// advanced in place between blocks.
    state: [u32; 16],
    /// Current 64-byte keystream block, possibly partially consumed.
    buffer: [u8; 64],
    /// Number of bytes already consumed from `buffer` (0..=64);
    /// 64 means "empty, refill on next byte".
    buf_pos: usize,
}

impl Salsa20 {
    /// Initialise Salsa20 with a 256-bit key, an 8-byte nonce, and an
    /// initial 64-bit block counter (usually 0).
    pub fn new(key: &[u8; 32], nonce: &[u8; 8], counter: u64) -> Self {
        Self {
            state: state_256(key, nonce, counter),
            buffer: [0u8; 64],
            buf_pos: 64,
        }
    }

    /// Initialise Salsa20 with a 128-bit key, an 8-byte nonce, and an
    /// initial 64-bit block counter. Uses the `tau` expansion
    /// constants and repeats the key across the state border.
    pub fn new_128(key: &[u8; 16], nonce: &[u8; 8], counter: u64) -> Self {
        Self {
            state: state_128(key, nonce, counter),
            buffer: [0u8; 64],
            buf_pos: 64,
        }
    }

    /// XOR the keystream into `data` in place. Encrypts or decrypts
    /// indifferently (the cipher is symmetric).
    ///
    /// Handles arbitrary lengths and partial blocks: leftover
    /// keystream bytes are remembered between calls, so feeding data in
    /// chunks produces the same output as one contiguous call.
    pub fn apply_keystream(&mut self, data: &mut [u8]) {
        let mut pos = 0;
        while pos < data.len() {
            if self.buf_pos == 64 {
                self.buffer = block(&self.state);
                // Advance the 64-bit little-endian block counter
                // (words 8, 9).
                let ctr = (self.state[8] as u64) | ((self.state[9] as u64) << 32);
                let ctr = ctr.wrapping_add(1);
                self.state[8] = ctr as u32;
                self.state[9] = (ctr >> 32) as u32;
                self.buf_pos = 0;
            }
            let take = (64 - self.buf_pos).min(data.len() - pos);
            for i in 0..take {
                data[pos + i] ^= self.buffer[self.buf_pos + i];
            }
            self.buf_pos += take;
            pos += take;
        }
    }
}

// ============================================================================
// Tests (DJB / eSTREAM 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
    }

    /// eSTREAM `verified.test-vectors`, Salsa20 **256-bit Set 1,
    /// vector# 0** (key = 0x80 in byte 0, all else zero, IV = 0).
    ///
    /// Keystream bytes 0..63 and 192..255 are pinned. The XOR-digest
    /// form of the suite folds all 512 keystream bytes; here we pin the
    /// two directly-listed 64-byte stream segments, which is sufficient
    /// to catch any core / layout / counter error.
    #[test]
    fn estream_256_set1_vector0() {
        let key: [u8; 32] = hex_arr(
            "80000000000000000000000000000000\
             00000000000000000000000000000000",
        );
        let nonce = [0u8; 8];
        let mut cipher = Salsa20::new(&key, &nonce, 0);
        let mut stream = [0u8; 256];
        cipher.apply_keystream(&mut stream);

        // stream[0..64]
        let expected0 = hex("E3BE8FDD8BECA2E3EA8EF9475B29A6E7\
             003951E1097A5C38D23B7A5FAD9F6844\
             B22C97559E2723C7CBBD3FE4FC8D9A07\
             44652A83E72A9C461876AF4D7EF1A117");
        assert_eq!(&stream[0..64], expected0.as_slice(), "block 0");

        // stream[192..256]
        let expected192 = hex("57BE81F47B17D9AE7C4FF15429A73E10\
             ACF250ED3A90A93C711308A74C6216A9\
             ED84CD126DA7F28E8ABF8BB63517E1CA\
             98E712F4FB2E1A6AED9FDC73291FAA17");
        assert_eq!(&stream[192..256], expected192.as_slice(), "block 3");
    }

    /// eSTREAM `verified.test-vectors`, Salsa20 **128-bit Set 1,
    /// vector# 0** (key = 0x80 in byte 0, IV = 0), 128-bit key path.
    #[test]
    fn estream_128_set1_vector0() {
        let key: [u8; 16] = hex_arr("80000000000000000000000000000000");
        let nonce = [0u8; 8];
        let mut cipher = Salsa20::new_128(&key, &nonce, 0);
        let mut stream = [0u8; 256];
        cipher.apply_keystream(&mut stream);

        let expected0 = hex("4DFA5E481DA23EA09A31022050859936\
             DA52FCEE218005164F267CB65F5CFD7F\
             2B4F97E0FF16924A52DF269515110A07\
             F9E460BC65EF95DA58F740B7D1DBB0AA");
        assert_eq!(&stream[0..64], expected0.as_slice(), "block 0");

        let expected192 = hex("DA9C1581F429E0A00F7D67E23B730676\
             783B262E8EB43A25F55FB90B3E753AEF\
             8C6713EC66C51881111593CCB3E8CB8F\
             8DE124080501EEEB389C4BCB6977CF95");
        assert_eq!(&stream[192..256], expected192.as_slice(), "block 3");
    }

    /// Decryption is the same operation as encryption (XOR keystream).
    /// Re-applying the keystream must recover the plaintext.
    #[test]
    fn salsa20_encrypt_decrypt_roundtrip() {
        let key = [0x42u8; 32];
        let nonce = [0xa5u8; 8];
        let plaintext = b"the quick brown fox jumps over the lazy dog";
        let mut buf = plaintext.to_vec();

        let mut enc = Salsa20::new(&key, &nonce, 0);
        enc.apply_keystream(&mut buf);
        assert_ne!(buf.as_slice(), plaintext);

        let mut dec = Salsa20::new(&key, &nonce, 0);
        dec.apply_keystream(&mut buf);
        assert_eq!(buf.as_slice(), plaintext);
    }

    /// Chunked application must match a single call (buffered
    /// partial-block path is stateful and correct across block edges).
    #[test]
    fn salsa20_chunked_apply_matches_single() {
        let key = [0x77u8; 32];
        let nonce = [0x11u8; 8];
        let plaintext: Vec<u8> = (0..200).map(|i| i as u8).collect();

        let mut single = plaintext.clone();
        Salsa20::new(&key, &nonce, 0).apply_keystream(&mut single);

        let mut chunked = plaintext.clone();
        let mut c = Salsa20::new(&key, &nonce, 0);
        c.apply_keystream(&mut chunked[..30]);
        c.apply_keystream(&mut chunked[30..70]); // crosses block boundary
        c.apply_keystream(&mut chunked[70..130]); // crosses again
        c.apply_keystream(&mut chunked[130..]);

        assert_eq!(chunked, single);
    }
}