Skip to main content

arx_kw/
ex.rs

1use crate::{util, ArxKW, ArxKwError, AuthTag, ConstantTimeEq};
2
3/// The ARX-KW-8-2-4-EX variant. Has a key length of 48 bytes and a maximum input length of one MiB.
4/// See the [`ArxKW`] trait for usage.
5pub struct EX {}
6impl EX {
7    /// The length in bytes of the secret key used by this variant of ARX-KW
8    #[must_use]
9    pub const fn key_length() -> usize {
10        48
11    }
12}
13
14impl ArxKW for EX {
15    type Key = [u8; Self::key_length()];
16    const VARIANT_ID: u8 = 3;
17    fn encrypt(key: &Self::Key, plaintext: &[u8]) -> Result<(Vec<u8>, AuthTag), ArxKwError> {
18        crate::memory::check_length(plaintext.len(), Self::MAX_INPUT_LENGTH)?;
19        let (k1, k2) = array_refs![key, 16, 32];
20        let authentication_tag = util::sip_array_keyed(k1, plaintext);
21        let nonce = construct_nonce(&authentication_tag);
22        let mut stream = util::xchacha8::new(k2, &nonce);
23        let mut ciphertext = crate::memory::copy_secret(plaintext)?;
24        stream.xor_read(&mut ciphertext)?;
25        Ok((std::mem::take(&mut *ciphertext), authentication_tag))
26    }
27
28    fn decrypt(
29        key: &Self::Key,
30        ciphertext: &[u8],
31        authentication_tag: &AuthTag,
32    ) -> Result<Vec<u8>, ArxKwError> {
33        crate::memory::check_length(ciphertext.len(), Self::MAX_INPUT_LENGTH)?;
34        let (k1, k2) = array_refs![key, 16, 32];
35        let nonce = construct_nonce(authentication_tag);
36        let mut p_prime = crate::memory::copy_secret(ciphertext)?;
37        let mut stream = util::xchacha8::new(k2, &nonce);
38        stream.xor_read(&mut p_prime)?;
39        let t_prime = zeroize::Zeroizing::new(util::sip_array_keyed(k1, &p_prime));
40        if bool::from(t_prime.ct_eq(authentication_tag)) {
41            return Ok(std::mem::take(&mut *p_prime));
42        }
43        Err(ArxKwError::BadTags)
44    }
45}
46
47/// The prefix specified for the EX variant in the ARX-KW paper (61 72 62 69 74 72 45 58) followed by 16 zeros
48const NONCE_INIT_EX: [u8; 24] = [
49    0x61, 0x72, 0x62, 0x69, 0x74, 0x72, 0x45, 0x58, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
50];
51
52/// Builds the 24-byte XChaCha8 nonce for ARX-KW-8-2-4-EX.
53///
54/// Concatenates the eight-byte ASCII prefix `arbitrEX` (`0x6172626974724558`)
55/// with the 16-byte authentication tag. Encryption and decryption call this
56/// internally; applications normally only need the [`ArxKW`] methods.
57///
58/// ```
59/// # use arx_kw::ex::construct_nonce;
60/// # use arx_kw::AuthTag;
61/// let mut t = AuthTag([0u8; 16]);
62/// for i in (0u8..16u8) {
63///     t.0[i as usize] = i;
64/// }
65///
66/// let nonce = construct_nonce(&t);
67/// assert_eq!(nonce,
68/// [0x61,0x72,0x62,0x69,0x74,0x72,0x45,0x58,0x0,0x1,0x2,0x3,0x4,0x5,0x6,0x7,0x8,0x9,0xa,0xb,0xc,0xd,0xe,0xf]);
69/// ```
70///
71/// Using T and N from the test vectors for EX included in the ARX-KW paper:
72/// ```
73///  extern crate hex;
74/// # extern crate anyhow;
75/// use hex::FromHex;
76/// use arx_kw::{
77///     ex::construct_nonce,
78///     AuthTag,
79///     ConstantTimeEq,
80///     assert_ct_eq
81/// };
82///
83/// # fn main() -> anyhow::Result<()> {
84/// let authentication_tag = AuthTag(<[u8;16]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f")?);
85/// let nonce_expected = <[u8;24]>::from_hex("6172626974724558c4f21d3b4dbcc566c3a73bbc59790f2f")?;
86/// let nonce = construct_nonce(&authentication_tag);
87/// assert_ct_eq!(nonce, &nonce_expected);
88/// Ok(())
89/// # }
90/// ```
91#[must_use]
92#[inline]
93pub fn construct_nonce(authentication_tag: &AuthTag) -> [u8; 24] {
94    // Initialize nonce with the defined prefix followed by 16 zeros.
95    let mut nonce = NONCE_INIT_EX;
96    // Copy the contents of t into bytes 8 to 23 of nonce
97    nonce[8..24].clone_from_slice(authentication_tag.as_ref());
98    nonce
99}
100
101#[cfg(test)]
102mod tests {
103    extern crate hex;
104    use super::*;
105    use crate::assert_ct_eq;
106    use anyhow::Result;
107    use hex::FromHex;
108
109    #[test]
110    fn test_encrypt() -> Result<()> {
111        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
112        let p = <[u8; 32]>::from_hex(
113            "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
114        )?;
115        let t_expected = AuthTag(<[u8; 16]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f")?);
116        let c_expected = <[u8; 32]>::from_hex(
117            "02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db",
118        )?;
119        let (c, t) = EX::encrypt(array_ref![k, 0, 48], &p)?;
120        assert_eq!(&c, &c_expected);
121        assert_ct_eq!(&t, &t_expected);
122        Ok(())
123    }
124
125    #[test]
126    fn test_encrypt_blob() -> Result<()> {
127        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
128        let p = <[u8; 32]>::from_hex(
129            "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
130        )?;
131        let blob_expected = <[u8;48]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db")?;
132        let blob = EX::encrypt_blob(&k, &p)?;
133        assert_ct_eq!(blob, &blob_expected);
134        Ok(())
135    }
136
137    #[test]
138    fn test_decrypt_blob() -> Result<()> {
139        let blob = <[u8;48]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db")?;
140        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
141        let p_expected = <[u8; 32]>::from_hex(
142            "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
143        )?;
144        let p = EX::decrypt_blob(&k, &blob)?;
145        assert_ct_eq!(p, &p_expected);
146        Ok(())
147    }
148
149    #[test]
150    fn test_decrypt() -> Result<()> {
151        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
152        let p_expected = <[u8; 32]>::from_hex(
153            "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
154        )?;
155        let t = AuthTag(<[u8; 16]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f")?);
156        let c = <[u8; 32]>::from_hex(
157            "02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db",
158        )?;
159        let p = EX::decrypt(&k, &c, &t)?;
160        assert_eq!(p, p_expected);
161        Ok(())
162    }
163
164    #[test]
165    /// Make sure that a bad authentication tag yields an error when decrypting
166    fn test_bad_decrypt() -> Result<()> {
167        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
168        let t_bad = AuthTag(<[u8; 16]>::from_hex("aaf21d3b4dbcc566c3a73bbc59790f2f")?); // first two hex digits should be c4
169        let c = <[u8; 32]>::from_hex(
170            "02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db",
171        )?;
172        let res = EX::decrypt(&k, &c, &t_bad);
173        assert!(res.is_err());
174        Ok(())
175    }
176}