pamoja-session 0.1.14

//! ChaCha20-Poly1305 authenticated encryption (RFC 8439), the AEAD that protects
//! every message a session sends.
//!
//! ChaCha20-Poly1305 is chosen over AES-GCM because the cheap hardware this SDK
//! targets rarely has AES acceleration, and ChaCha20 is fast and constant-time in
//! plain software. The construction is used through the vetted RustCrypto
//! implementation; this module only wraps it in the in-place, detached-tag shape a
//! session needs, and the tests pin it to the worked example in RFC 8439 section
//! 2.8.2 so a wrong key, nonce, or associated-data wiring is caught.

use chacha20poly1305::aead::inout::InOutBuf;
use chacha20poly1305::aead::{AeadInOut, KeyInit};
use chacha20poly1305::ChaCha20Poly1305;

use crate::SessionError;

// Encrypts `buf` in place under `key` and `nonce`, authenticating `aad` alongside it,
// and returns the 16-byte Poly1305 tag. The ciphertext replaces the plaintext in
// `buf`; the tag travels separately so the caller controls framing.
pub(crate) fn seal(key: &[u8; 32], nonce: &[u8; 12], aad: &[u8], buf: &mut [u8]) -> [u8; 16] {
    let cipher = ChaCha20Poly1305::new(key.into());
    let tag = cipher
        .encrypt_inout_detached(nonce.into(), aad, InOutBuf::from(buf))
        .expect("ChaCha20-Poly1305 encryption is infallible for an in-memory buffer");
    let mut out = [0u8; 16];
    out.copy_from_slice(tag.as_slice());
    out
}

// Decrypts `buf` in place under `key` and `nonce`, checking it against `aad` and the
// 16-byte `tag`. On success the plaintext replaces the ciphertext in `buf`. On any
// authentication failure the buffer is zeroed before returning, so a forgery never
// leaves keystream-decrypted bytes behind for a caller to read by mistake.
pub(crate) fn open(
    key: &[u8; 32],
    nonce: &[u8; 12],
    aad: &[u8],
    buf: &mut [u8],
    tag: &[u8; 16],
) -> Result<(), SessionError> {
    let cipher = ChaCha20Poly1305::new(key.into());
    let opened =
        cipher.decrypt_inout_detached(nonce.into(), aad, InOutBuf::from(&mut *buf), tag.into());
    opened.map_err(|_| {
        buf.fill(0);
        SessionError::Inauthentic
    })
}

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

    // The AEAD_CHACHA20_POLY1305 worked example from RFC 8439 section 2.8.2.
    const KEY: [u8; 32] = [
        0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x8d, 0x8e,
        0x8f, 0x90, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9a, 0x9b, 0x9c, 0x9d,
        0x9e, 0x9f,
    ];
    const NONCE: [u8; 12] = [
        0x07, 0x00, 0x00, 0x00, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47,
    ];
    const AAD: [u8; 12] = [
        0x50, 0x51, 0x52, 0x53, 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7,
    ];
    const PLAINTEXT: [u8; 114] = [
        0x4c, 0x61, 0x64, 0x69, 0x65, 0x73, 0x20, 0x61, 0x6e, 0x64, 0x20, 0x47, 0x65, 0x6e, 0x74,
        0x6c, 0x65, 0x6d, 0x65, 0x6e, 0x20, 0x6f, 0x66, 0x20, 0x74, 0x68, 0x65, 0x20, 0x63, 0x6c,
        0x61, 0x73, 0x73, 0x20, 0x6f, 0x66, 0x20, 0x27, 0x39, 0x39, 0x3a, 0x20, 0x49, 0x66, 0x20,
        0x49, 0x20, 0x63, 0x6f, 0x75, 0x6c, 0x64, 0x20, 0x6f, 0x66, 0x66, 0x65, 0x72, 0x20, 0x79,
        0x6f, 0x75, 0x20, 0x6f, 0x6e, 0x6c, 0x79, 0x20, 0x6f, 0x6e, 0x65, 0x20, 0x74, 0x69, 0x70,
        0x20, 0x66, 0x6f, 0x72, 0x20, 0x74, 0x68, 0x65, 0x20, 0x66, 0x75, 0x74, 0x75, 0x72, 0x65,
        0x2c, 0x20, 0x73, 0x75, 0x6e, 0x73, 0x63, 0x72, 0x65, 0x65, 0x6e, 0x20, 0x77, 0x6f, 0x75,
        0x6c, 0x64, 0x20, 0x62, 0x65, 0x20, 0x69, 0x74, 0x2e,
    ];
    const CIPHERTEXT: [u8; 114] = [
        0xd3, 0x1a, 0x8d, 0x34, 0x64, 0x8e, 0x60, 0xdb, 0x7b, 0x86, 0xaf, 0xbc, 0x53, 0xef, 0x7e,
        0xc2, 0xa4, 0xad, 0xed, 0x51, 0x29, 0x6e, 0x08, 0xfe, 0xa9, 0xe2, 0xb5, 0xa7, 0x36, 0xee,
        0x62, 0xd6, 0x3d, 0xbe, 0xa4, 0x5e, 0x8c, 0xa9, 0x67, 0x12, 0x82, 0xfa, 0xfb, 0x69, 0xda,
        0x92, 0x72, 0x8b, 0x1a, 0x71, 0xde, 0x0a, 0x9e, 0x06, 0x0b, 0x29, 0x05, 0xd6, 0xa5, 0xb6,
        0x7e, 0xcd, 0x3b, 0x36, 0x92, 0xdd, 0xbd, 0x7f, 0x2d, 0x77, 0x8b, 0x8c, 0x98, 0x03, 0xae,
        0xe3, 0x28, 0x09, 0x1b, 0x58, 0xfa, 0xb3, 0x24, 0xe4, 0xfa, 0xd6, 0x75, 0x94, 0x55, 0x85,
        0x80, 0x8b, 0x48, 0x31, 0xd7, 0xbc, 0x3f, 0xf4, 0xde, 0xf0, 0x8e, 0x4b, 0x7a, 0x9d, 0xe5,
        0x76, 0xd2, 0x65, 0x86, 0xce, 0xc6, 0x4b, 0x61, 0x16,
    ];
    const TAG: [u8; 16] = [
        0x1a, 0xe1, 0x0b, 0x59, 0x4f, 0x09, 0xe2, 0x6a, 0x7e, 0x90, 0x2e, 0xcb, 0xd0, 0x60, 0x06,
        0x91,
    ];

    #[test]
    fn seal_matches_the_rfc_8439_vector() {
        let mut buf = PLAINTEXT;
        let tag = seal(&KEY, &NONCE, &AAD, &mut buf);
        assert_eq!(buf, CIPHERTEXT);
        assert_eq!(tag, TAG);
    }

    #[test]
    fn open_recovers_the_rfc_8439_plaintext() {
        let mut buf = CIPHERTEXT;
        open(&KEY, &NONCE, &AAD, &mut buf, &TAG).expect("authentic ciphertext opens");
        assert_eq!(buf, PLAINTEXT);
    }

    #[test]
    fn a_flipped_ciphertext_bit_fails_and_zeroes_the_buffer() {
        let mut buf = CIPHERTEXT;
        buf[0] ^= 0x01;
        let result = open(&KEY, &NONCE, &AAD, &mut buf, &TAG);
        assert_eq!(result, Err(SessionError::Inauthentic));
        assert!(buf.iter().all(|&byte| byte == 0));
    }

    #[test]
    fn altered_associated_data_fails_authentication() {
        let mut buf = CIPHERTEXT;
        let mut aad = AAD;
        aad[0] ^= 0x01;
        assert_eq!(
            open(&KEY, &NONCE, &aad, &mut buf, &TAG),
            Err(SessionError::Inauthentic)
        );
    }
}