arx_kw/
ex.rs

1use chacha::KeyStream;
2use crate::{util,ArxKW,ArxKwError,AuthTag,ConstantTimeEq};
3
4/// A user-friendly implementation of ARX-KW-8-2-4-EX. Has a key length of 48 bytes and no maximum
5/// input length.
6/// See the [`ArxKW`] trait for usage.
7pub struct EX {}
8impl EX {
9    /// The length in bytes of the secret key used by this variant of ARX-KW
10    #[cfg(not(tarpaulin_include))]
11    #[must_use] pub const fn key_length() -> usize {
12        48
13    }
14}
15
16impl ArxKW for EX {
17    type Key = [u8; Self::key_length()];
18    fn encrypt(key: &Self::Key, plaintext: &[u8]) -> Result<(Vec<u8>, AuthTag), ArxKwError> {
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 = plaintext.to_vec();
24        stream.xor_read(&mut ciphertext).map_err(|e| ArxKwError::ChaChaError(format!("Reached end of stream: {:?} X",e)))?;
25        Ok((ciphertext,authentication_tag))
26    }
27
28    fn decrypt(key: &Self::Key, ciphertext: &[u8], authentication_tag: &AuthTag) -> Result<Vec<u8>, ArxKwError> {
29        let (k1,k2) = array_refs![key,16,32];
30        let nonce = construct_nonce(authentication_tag);
31        let mut p_prime = ciphertext.to_vec();
32        let mut stream = util::xchacha8::new(k2,&nonce);
33        stream.xor_read(&mut p_prime).map_err(|e| ArxKwError::ChaChaError(format!("Reached end of stream: {:?} X",e)))?;
34        let t_prime = util::sip_array_keyed(k1, &p_prime);
35        if bool::from(t_prime.ct_eq(authentication_tag)) {
36            return Ok(p_prime);
37        }
38        Err(ArxKwError::BadTags(t_prime, *authentication_tag))
39    }
40}
41
42/// The prefix specified for the EX variant in the ARX-KW paper (61 72 62 69 74 72 45 58) followed by 16 zeros
43const NONCE_INIT_EX: [u8;24] = [0x61, 0x72, 0x62, 0x69, 0x74, 0x72, 0x45, 0x58,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0];
44
45/// Concatenates an authentication tag to the EX prefix and returns the resulting intermediate nonce
46///
47/// **There is probably not much of a reason to use this outside of this library unless you're writing a new ARX-KW implementation**.
48///
49/// # Please read:
50///
51/// I am making it public largely to provide a look into how ARX-KW works (and because I already wrote documentation and doctests for it). 
52///
53/// Because the nonce is created and consumed within the key wrapping process itself (as opposed to the authentication tag, stored alongside the wrapped key) and the API exposed by this crate 
54/// uses fixed length (ie checked at compile time) input for keys and authentication tags which are of different size than that of the nonce, I hope (perhaps naïvely) that misuse of this function is too awkward to take place. 
55/// That said, it is useful as an example and could be re-used in another crate looking to implement ARX-KW-*-*-EX.
56///
57/// ---
58/// ## With that out of the way:
59///
60/// The prefix is the ASCII encoding of the string `arbitrEX`, or 0x6172626974724558, as defined
61/// for ARX-KW-8-2-4-EX in the paper by Sato Shinichi.
62///
63/// The value returned is a fixed-length array of 192 bits suitable for use as a nonce with
64/// the `XChaCha8` stream cipher when using the EX variant of ARX-KW
65/// ```
66/// # use arx_kw::ex::construct_nonce;
67/// # use arx_kw::AuthTag;
68/// let mut t = AuthTag([0u8; 16]);
69/// for i in (0u8..16u8) {
70///     t.0[i as usize] = i;
71/// }
72///
73/// let nonce = construct_nonce(&t);
74/// assert_eq!(nonce,
75/// [0x61,0x72,0x62,0x69,0x74,0x72,0x45,0x58,0x0,0x1,0x2,0x3,0x4,0x5,0x6,0x7,0x8,0x9,0xa,0xb,0xc,0xd,0xe,0xf]);
76/// ```
77///
78/// Using T and N from the test vectors for EX included in the ARX-KW paper:
79/// ```
80///  extern crate hex;
81/// # extern crate anyhow;
82/// use hex::FromHex;
83/// use arx_kw::{
84///     ex::construct_nonce,
85///     AuthTag,
86///     ConstantTimeEq,
87///     assert_ct_eq
88/// };
89///
90/// # fn main() -> anyhow::Result<()> {
91/// let authentication_tag = AuthTag(<[u8;16]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f")?);
92/// let nonce_expected = <[u8;24]>::from_hex("6172626974724558c4f21d3b4dbcc566c3a73bbc59790f2f")?;
93/// let nonce = construct_nonce(&authentication_tag);
94/// assert_ct_eq!(nonce, &nonce_expected);
95/// Ok(())
96/// # }
97/// ```
98#[must_use]
99#[inline]
100#[cfg(not(tarpaulin_include))]
101pub fn construct_nonce(authentication_tag: &AuthTag) -> [u8;24] {
102    // Initialize nonce with the defined prefix followed by 16 zeros.
103    let mut nonce = NONCE_INIT_EX;
104    // Copy the contents of t into bytes 15 to 23 of nonce
105    nonce[8..24].clone_from_slice(authentication_tag.as_ref());
106    nonce
107}
108
109
110#[cfg(test)]
111mod tests {
112    extern crate hex;
113    use super::*;
114    use anyhow::Result;
115    use hex::FromHex;
116    use crate::{assert_ct_eq,ConstantTimeEq};
117
118    #[test]
119    fn test_encrypt() -> Result<()> {
120        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
121        let p = <[u8; 32]>::from_hex("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")?;
122        let t_expected = AuthTag(<[u8; 16]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f")?);
123        let c_expected = <[u8; 32]>::from_hex("02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db")?;
124        let (c,t) = EX::encrypt(array_ref![k,0,48], &p)?;
125        assert_eq!(&c.to_vec(), &c_expected);
126        assert_ct_eq!(&t, &t_expected);
127        Ok(())
128    }
129
130    #[test]
131    fn test_encrypt_blob() -> Result<()> {
132        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
133        let p = <[u8; 32]>::from_hex("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")?;
134        let blob_expected = <[u8;48]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db")?;
135        let blob = EX::encrypt_blob(&k, &p)?;
136        assert_ct_eq!(blob, &blob_expected);
137        Ok(())
138    }
139
140    #[test]
141    fn test_decrypt_blob() -> Result<()> {
142        let blob = <[u8;48]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db")?;
143        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
144        let p_expected = <[u8; 32]>::from_hex("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")?;
145        let p = EX::decrypt_blob(&k, &blob)?;
146        assert_ct_eq!(p, &p_expected);
147        Ok(())
148    }
149
150    #[test]
151    fn test_decrypt() -> Result<()> {
152        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
153        let p_expected = <[u8; 32]>::from_hex("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")?;
154        let t = AuthTag(<[u8; 16]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2f")?);
155        let c = <[u8; 32]>::from_hex("02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db")?;
156        let p = EX::decrypt(&k, &c, &t)?;
157        assert_eq!(p, p_expected);
158        Ok(())
159    }
160
161    #[test]
162    /// Make sure that a bad authentication tag yields an error when decrypting
163    fn test_bad_decrypt() -> Result<()> {
164        let k = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
165        let t_bad = AuthTag(<[u8; 16]>::from_hex("aaf21d3b4dbcc566c3a73bbc59790f2f")?); // first two hex digits should be c4
166        let c = <[u8; 32]>::from_hex("02a55ab1d7f549db160e8ecb33e1c6d65a05d0ebaba54dc0712285787c8a62db")?;
167        let res = EX::decrypt(&k, &c, &t_bad);
168        assert!(res.is_err());
169        Ok(())
170    }
171}
arx_kw/ex.rs

arx_kw/
ex.rs
