zeros/poly1305/

xchacha20.rs

/*
==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--

Zeros

Copyright (C) 2019-2025  Anonymous

There are several releases over multiple years,
they are listed as ranges, such as: "2019-2025".

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

::--::--::--::--::--::--::--::--::--::--::--::--::--::--::--::--
*/

//! # Poly1305-XChacha20
//!
//! ## Notes
//!
//! -   This module is `unsafe`, because we made it from a [*drafted* specification][specification].  We have tried to search for a formal one,
//!     but failed.
//! -   Tests are passed using data from the draft specification.
//! -   Tests are also passed against [`libsodium`][site:libsodium] project.
//! -   Key is same as [`chacha::Key`][type:chacha/Key].
//! -   But nonce must be [`192`-bit][type:Nonce].
//! -   Additional authenticated data (AAD) is optional.
//! -   For small amount of data, you can use shortcuts like [`encrypt()`][fn:encrypt], [`encrypt_stream()`][fn:encrypt_stream],
//!     [`decrypt()`][fn:decrypt]... For large data, use [`make_encrypter()`][fn:make_encrypter], [`make_decrypter()`][fn:make_decrypter].
//! -   Some functions use an initial counter of zero.  That is **NOT** in specification.  They exist only for some odd features provided by
//!     other libraries, such as [`libsodium`][site:libsodium].  Use with care!
//!
//! [type:Nonce]: type.Nonce.html
//! [type:chacha/Key]: ../../chacha/type.Key.html
//!
//! [specification]: https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03
//! [site:libsodium]: https://github.com/jedisct1/libsodium
//! [fn:encrypt]: fn.encrypt.html
//! [fn:encrypt_stream]: fn.encrypt_stream.html
//! [fn:decrypt]: fn.decrypt.html
//! [fn:make_encrypter]: fn.make_encrypter.html
//! [fn:make_decrypter]: fn.make_decrypter.html

use {
    core::mem,
    alloc::{
        string::String,
        vec::Vec,
    },
    crate::{
        Bytes,
        Result,
        chacha::{
            self,
            Chacha,
            Key,
            TWENTY,
            word_array::{self, WORD_SIZE},
        },
    },
    super::{
        Poly1305,
        Tag,
        chacha20::{self, Args, Counter},
        encrypted_data_buffer::EncryptedDataBuffer,
    },
};

#[cfg(not(feature="std"))]
use crate::io::Write;

#[cfg(feature="std")]
use {
    std::io::{Read, Write},
    crate::IoResult,
};

#[cfg(feature="simd")]
use crate::chacha::salsa20_simd::run_quarter_rounds;

#[cfg(not(feature="simd"))]
use crate::chacha::salsa20::run_quarter_rounds;

/// # Nonce (`192` bits)
///
/// ## Notes
///
/// This is __`192-bit`__, which is different to [`chacha::Nonce`][type:chacha/Nonce] (`128` bits).
///
/// [type:chacha/Nonce]: ../../chacha/type.Nonce.html
pub type Nonce = [u8; 24];

/// # Makes new Poly1305-XChacha20 for encryption
pub unsafe fn make_encrypter<K, N, A, W>(key: K, nonce: N, aad: Option<A>, output: W) -> Result<Poly1305<&'static [u8], W>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, W: Write {
    unsafe {
        make_encrypter_with_counter(key, nonce, aad, output, Counter::DEFAULT)
    }
}

/// # Makes new Poly1305-XChacha20 for encryption
unsafe fn make_encrypter_with_counter<K, N, A, W>(key: K, nonce: N, aad: Option<A>, output: W, counter: Counter) ->
Result<Poly1305<&'static [u8], W>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, W: Write {
    let args = make_args(true, key, nonce, aad, output, counter)?;
    Ok(Poly1305 {
        encrypted_data_buffer: None,
        chacha20: args.chacha20,
        aad_len: args.aad_len,
        s: args.s,
        output_size: u64::MIN,
    })
}

/// # Makes new Poly1305-XChacha20 for decryption
///
/// When done decrypting, if the tag made from input data does not match your `authenticated_tag`, an error is returned.
pub unsafe fn make_decrypter<K, N, A, T, W>(key: K, nonce: N, aad: Option<A>, authenticated_tag: T, output: W) -> Result<Poly1305<T, W>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, T: AsRef<[u8]>, W: Write {
    unsafe {
        make_decrypter_with_counter(key, nonce, aad, authenticated_tag, output, Counter::DEFAULT)
    }
}

unsafe fn make_decrypter_with_counter<K, N, A, T, W>(key: K, nonce: N, aad: Option<A>, authenticated_tag: T, output: W, counter: Counter)
-> Result<Poly1305<T, W>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, T: AsRef<[u8]>, W: Write {
    let args = make_args(false, key, nonce, aad, output, counter)?;
    Ok(Poly1305 {
        encrypted_data_buffer: Some(EncryptedDataBuffer::new(authenticated_tag, args.tag, args.r)),
        chacha20: args.chacha20,
        aad_len: args.aad_len,
        s: args.s,
        output_size: u64::MIN,
    })
}

/// # Makes arguments
fn make_args<K, N, A, W>(for_encrypter: bool, key: K, nonce: N, aad: Option<A>, output: W, counter: Counter) -> Result<Args<W>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, W: Write {
    let (key, nonce) = make_key_and_chacha20_nonce(key, nonce)?;
    chacha20::make_args(for_encrypter, key, nonce, aad, output, counter)
}

/// # Makes key and Chacha20 nonce
fn make_key_and_chacha20_nonce<K, N>(key: K, nonce: N) -> Result<(Key, chacha20::Nonce)> where K: AsRef<[u8]>, N: AsRef<[u8]> {
    let key = key.as_ref();
    let key = Key::try_from(key)
        .map_err(|_| err!("Invalid key size: {key_len}. Required: {required}", key_len=key.len(), required=mem::size_of::<Key>()))?;

    let nonce = nonce.as_ref();
    let nonce = Nonce::try_from(nonce)
        .map_err(|_| err!("Invalid nonce size: {nonce_len}. Required: {required}", nonce_len=nonce.len(), required=mem::size_of::<Nonce>()))?;

    let key = {
        let mut key = word_array::new(key, chacha::Nonce::try_from(&nonce[..size_of::<chacha::Nonce>()]).map_err(|_| e!())?);
        run_quarter_rounds(&TWENTY, &mut key);

        let mut tmp = Key::default();
        macro_rules! copy { ($(($i: literal, $k: literal)),+) => {
            $(
                tmp[$i .. $i + WORD_SIZE].copy_from_slice(&key[$k].to_le_bytes());
            )+
        }}
        copy!((0, 0), (4, 1), (8, 2), (12, 3), (16, 12), (20, 13), (24, 14), (28, 15));
        tmp
    };

    let nonce = {
        let mut tmp = chacha20::Nonce::default();
        tmp[4..].copy_from_slice(&nonce[size_of::<chacha::Nonce>()..]);
        tmp
    };

    Ok((key, nonce))
}

/// # Encrypts some bytes
pub unsafe fn encrypt<'a, const X: usize, K, N, A, B, B0>(key: K, nonce: N, aad: Option<A>, bytes: B) -> Result<(Vec<u8>, Tag)>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, B: Into<Bytes<'a, X, B0>>, B0: AsRef<[u8]> + 'a {
    let mut encrypter = unsafe {
        make_encrypter(key, nonce, aad, Vec::new())?
    };
    encrypter.encrypt_bytes(bytes)?;
    encrypter.finish()
}

/// # Encrypts a stream
///
/// _See [`io`](../../io/index.html#reading-streams) for more details._
#[cfg(feature="std")]
#[doc(cfg(feature="std"))]
pub unsafe fn encrypt_stream<K, N, A, R>(key: K, nonce: N, aad: Option<A>, stream: &mut R, capacity: Option<usize>) -> IoResult<(Vec<u8>, Tag)>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, R: Read {
    let mut encrypter = unsafe {
        make_encrypter(key, nonce, aad, Vec::with_capacity(capacity.unwrap_or(0)))?
    };
    crate::io::read_stream(stream, |data| {
        encrypter.encrypt(data)?;
        Ok(())
    })?;
    Ok(encrypter.finish()?)
}

/// # Decrypts some bytes
pub unsafe fn decrypt<'a, const X: usize, K, N, A, T, B, B0>(key: K, nonce: N, aad: Option<A>, authenticated_tag: T, bytes: B) -> Result<Vec<u8>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, T: AsRef<[u8]>, B: Into<Bytes<'a, X, B0>>, B0: AsRef<[u8]> + 'a {
    let mut decrypter = unsafe {
        make_decrypter(key, nonce, aad, authenticated_tag, Vec::new())?
    };
    decrypter.encrypt_bytes(bytes)?;
    decrypter.finish().map(|(bytes, _)| bytes)
}

/// # Decrypts a stream
///
/// _See [`io`](../../io/index.html#reading-streams) for more details._
#[cfg(feature="std")]
#[doc(cfg(feature="std"))]
pub unsafe fn decrypt_stream<K, N, A, T, R>(key: K, nonce: N, aad: Option<A>, authenticated_tag: T, stream: &mut R, capacity: Option<usize>)
-> IoResult<Vec<u8>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, T: AsRef<[u8]>, R: Read {
    let mut decrypter = unsafe {
        make_decrypter(key, nonce, aad, authenticated_tag, Vec::with_capacity(capacity.unwrap_or(0)))?
    };
    crate::io::read_stream(stream, |data| {
        decrypter.encrypt(data)?;
        Ok(())
    })?;
    Ok(decrypter.finish()?.0)
}

/// # Decrypts some bytes to string
pub unsafe fn decrypt_to_string<'a, const X: usize, K, N, A, T, B, B0>(key: K, nonce: N, aad: Option<A>, authenticated_tag: T, bytes: B)
-> Result<String>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, T: AsRef<[u8]>, B: Into<Bytes<'a, X, B0>>, B0: AsRef<[u8]> + 'a {
    unsafe {
        crate::str::string_from_utf8(decrypt(key, nonce, aad, authenticated_tag, bytes)?)
    }
}

/// # Decrypts a stream to string
///
/// _See [`io`](../../io/index.html#reading-streams) for more details._
#[cfg(feature="std")]
#[doc(cfg(feature="std"))]
pub unsafe fn decrypt_stream_to_string<K, N, A, T, R>(
    key: K, nonce: N, aad: Option<A>, authenticated_tag: T, stream: &mut R, capacity: Option<usize>,
) -> IoResult<String>
where K: AsRef<[u8]>, N: AsRef<[u8]>, A: AsRef<[u8]>, T: AsRef<[u8]>, R: Read {
    unsafe {
        Ok(crate::str::string_from_utf8(decrypt_stream(key, nonce, aad, authenticated_tag, stream, capacity)?)?)
    }
}

/// # Makes new Chacha20
pub unsafe fn make_chacha20<K, N, W>(key: K, nonce: N, output: W) -> Result<Chacha<W>> where K: AsRef<[u8]>, N: AsRef<[u8]>, W: Write {
    let (key, nonce) = make_key_and_chacha20_nonce(key, nonce)?;
    Ok(chacha20::make_chacha20_from_key_and_nonce(key, nonce, output, Counter::DEFAULT))
}

/// # Encrypts some bytes with just Chacha20
pub unsafe fn encrypt_with_chacha20<'a, const X: usize, K, N, B, B0>(key: K, nonce: N, bytes: B) -> Result<Vec<u8>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, B: Into<Bytes<'a, X, B0>>, B0: AsRef<[u8]> + 'a {
    let mut chacha20 = unsafe {
        make_chacha20(key, nonce, Vec::new())?
    };
    chacha20.encrypt_bytes(bytes)?;
    chacha20.finish()
}

/// # Makes new Chacha20 with zero counter
pub unsafe fn make_chacha20_with_zero_counter<K, N, W>(key: K, nonce: N, output: W) -> Result<Chacha<W>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, W: Write {
    let (key, nonce) = make_key_and_chacha20_nonce(key, nonce)?;
    Ok(chacha20::make_chacha20_from_key_and_nonce(key, nonce, output, unsafe { Counter::zero() }))
}

/// # Encrypts some bytes with just Chacha20 setup with zero counter
pub unsafe fn encrypt_with_chacha20_with_zero_counter<'a, const X: usize, K, N, B, B0>(key: K, nonce: N, bytes: B) -> Result<Vec<u8>>
where K: AsRef<[u8]>, N: AsRef<[u8]>, B: Into<Bytes<'a, X, B0>>, B0: AsRef<[u8]> + 'a {
    let mut chacha20 = unsafe {
        make_chacha20_with_zero_counter(key, nonce, Vec::new())?
    };
    chacha20.encrypt_bytes(bytes)?;
    chacha20.finish()
}