1//! Low level AES IGE and key wrapping functionality
2//!
3//! AES ECB, CBC, XTS, CTR, CFB, GCM and other conventional symmetric encryption
4//! modes are found in [`symm`]. This is the implementation of AES IGE and key wrapping
5//!
6//! Advanced Encryption Standard (AES) provides symmetric key cipher that
7//! the same key is used to encrypt and decrypt data. This implementation
8//! uses 128, 192, or 256 bit keys. This module provides functions to
9//! create a new key with [`new_encrypt`] and perform an encryption/decryption
10//! using that key with [`aes_ige`].
11//!
12//! [`new_encrypt`]: struct.AesKey.html#method.new_encrypt
13//! [`aes_ige`]: fn.aes_ige.html
14//!
15//! The [`symm`] module should be used in preference to this module in most cases.
16//! The IGE block cipher is a non-traditional cipher mode. More traditional AES
17//! encryption methods are found in the [`Crypter`] and [`Cipher`] structs.
18//!
19//! [`symm`]: ../symm/index.html
20//! [`Crypter`]: ../symm/struct.Crypter.html
21//! [`Cipher`]: ../symm/struct.Cipher.html
22//!
23//! # Examples
24
25#![cfg_attr(
26 all(
27 not(boringssl),
28 not(awslc),
29 not(osslconf = "OPENSSL_NO_DEPRECATED_3_0")
30 ),
31 doc = r#"\
32## AES IGE
33```rust
34use openssl::aes::{AesKey, aes_ige};
35use openssl::symm::Mode;
36
37let key = b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F";
38let plaintext = b"\x12\x34\x56\x78\x90\x12\x34\x56\x12\x34\x56\x78\x90\x12\x34\x56";
39let mut iv = *b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\
40 \x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F";
41
42 let key = AesKey::new_encrypt(key).unwrap();
43 let mut output = [0u8; 16];
44 aes_ige(plaintext, &mut output, &key, &mut iv, Mode::Encrypt);
45 assert_eq!(output, *b"\xa6\xad\x97\x4d\x5c\xea\x1d\x36\xd2\xf3\x67\x98\x09\x07\xed\x32");
46```"#
47)]
48
49//!
50//! ## Key wrapping
51//! ```rust
52//! use openssl::aes::{AesKey, unwrap_key, wrap_key};
53//!
54//! let kek = b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F";
55//! let key_to_wrap = b"\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF";
56//!
57//! let enc_key = AesKey::new_encrypt(kek).unwrap();
58//! let mut ciphertext = [0u8; 24];
59//! wrap_key(&enc_key, None, &mut ciphertext, &key_to_wrap[..]).unwrap();
60//! let dec_key = AesKey::new_decrypt(kek).unwrap();
61//! let mut orig_key = [0u8; 16];
62//! unwrap_key(&dec_key, None, &mut orig_key, &ciphertext[..]).unwrap();
63//!
64//! assert_eq!(&orig_key[..], &key_to_wrap[..]);
65//! ```
66//!
67use cfg_if::cfg_if;
68use libc::{c_int, c_uint};
69use std::mem::MaybeUninit;
70use std::ptr;
71
72#[cfg(not(any(boringssl, awslc)))]
73use crate::symm::Mode;
74use openssl_macros::corresponds;
75
76/// Provides Error handling for parsing keys.
77#[derive(Debug)]
78pub struct KeyError(());
79
80/// The key used to encrypt or decrypt cipher blocks.
81pub struct AesKey(ffi::AES_KEY);
82
83cfg_if! {
84 if #[cfg(any(boringssl, awslc))] {
85 type AesBitType = c_uint;
86 type AesSizeType = usize;
87 } else {
88 type AesBitType = c_int;
89 type AesSizeType = c_uint;
90 }
91}
92
93impl AesKey {
94 /// Prepares a key for encryption.
95 ///
96 /// # Failure
97 ///
98 /// Returns an error if the key is not 128, 192, or 256 bits.
99 #[corresponds(AES_set_encrypt_key)]
100 pub fn new_encrypt(key: &[u8]) -> Result<AesKey, KeyError> {
101 unsafe {
102 assert!(key.len() <= c_int::MAX as usize / 8);
103
104 let mut aes_key = MaybeUninit::uninit();
105 let r = ffi::AES_set_encrypt_key(
106 key.as_ptr() as *const _,
107 key.len() as AesBitType * 8,
108 aes_key.as_mut_ptr(),
109 );
110 if r == 0 {
111 Ok(AesKey(aes_key.assume_init()))
112 } else {
113 Err(KeyError(()))
114 }
115 }
116 }
117
118 /// Prepares a key for decryption.
119 ///
120 /// # Failure
121 ///
122 /// Returns an error if the key is not 128, 192, or 256 bits.
123 #[corresponds(AES_set_decrypt_key)]
124 pub fn new_decrypt(key: &[u8]) -> Result<AesKey, KeyError> {
125 unsafe {
126 assert!(key.len() <= c_int::MAX as usize / 8);
127
128 let mut aes_key = MaybeUninit::uninit();
129 let r = ffi::AES_set_decrypt_key(
130 key.as_ptr() as *const _,
131 key.len() as AesBitType * 8,
132 aes_key.as_mut_ptr(),
133 );
134
135 if r == 0 {
136 Ok(AesKey(aes_key.assume_init()))
137 } else {
138 Err(KeyError(()))
139 }
140 }
141 }
142}
143
144/// Performs AES IGE encryption or decryption
145///
146/// AES IGE (Infinite Garble Extension) is a form of AES block cipher utilized in
147/// OpenSSL. Infinite Garble refers to propagating forward errors. IGE, like other
148/// block ciphers implemented for AES requires an initialization vector. The IGE mode
149/// allows a stream of blocks to be encrypted or decrypted without having the entire
150/// plaintext available. For more information, visit [AES IGE Encryption].
151///
152/// This block cipher uses 16 byte blocks. The rust implementation will panic
153/// if the input or output does not meet this 16-byte boundary. Attention must
154/// be made in this low level implementation to pad the value to the 128-bit boundary.
155///
156/// [AES IGE Encryption]: http://www.links.org/files/openssl-ige.pdf
157///
158/// # Panics
159///
160/// Panics if `in_` is not the same length as `out`, if that length is not a multiple of 16, or if
161/// `iv` is not at least 32 bytes.
162#[cfg(not(any(boringssl, awslc)))]
163#[cfg(not(osslconf = "OPENSSL_NO_DEPRECATED_3_0"))]
164#[corresponds(AES_ige_encrypt)]
165pub fn aes_ige(in_: &[u8], out: &mut [u8], key: &AesKey, iv: &mut [u8], mode: Mode) {
166 unsafe {
167 assert!(in_.len() == out.len());
168 assert!(in_.len() % ffi::AES_BLOCK_SIZE as usize == 0);
169 assert!(iv.len() >= ffi::AES_BLOCK_SIZE as usize * 2);
170
171 let mode: i32 = match mode {
172 Mode::Encrypt => ffi::AES_ENCRYPT,
173 Mode::Decrypt => ffi::AES_DECRYPT,
174 };
175 ffi::AES_ige_encrypt(
176 in_.as_ptr() as *const _,
177 out.as_mut_ptr() as *mut _,
178 length:in_.len(),
179 &key.0,
180 ivec:iv.as_mut_ptr() as *mut _,
181 enc:mode,
182 );
183 }
184}
185
186/// Wrap a key, according to [RFC 3394](https://tools.ietf.org/html/rfc3394)
187///
188/// * `key`: The key-encrypting-key to use. Must be a encrypting key
189/// * `iv`: The IV to use. You must use the same IV for both wrapping and unwrapping
190/// * `out`: The output buffer to store the ciphertext
191/// * `in_`: The input buffer, storing the key to be wrapped
192///
193/// Returns the number of bytes written into `out`
194///
195/// # Panics
196///
197/// Panics if either `out` or `in_` do not have sizes that are a multiple of 8, or if
198/// `out` is not 8 bytes longer than `in_`
199#[corresponds(AES_wrap_key)]
200pub fn wrap_key(
201 key: &AesKey,
202 iv: Option<[u8; 8]>,
203 out: &mut [u8],
204 in_: &[u8],
205) -> Result<usize, KeyError> {
206 unsafe {
207 assert!(out.len() >= in_.len() + 8); // Ciphertext is 64 bits longer (see 2.2.1)
208
209 let written: i32 = ffi::AES_wrap_key(
210 &key.0 as *const _ as *mut _, // this is safe, the implementation only uses the key as a const pointer.
211 iv.as_ref()
212 .map_or(ptr::null(), |iv| iv.as_ptr() as *const _),
213 out.as_ptr() as *mut _,
214 in_.as_ptr() as *const _,
215 inlen:in_.len() as AesSizeType,
216 );
217 if written <= 0 {
218 Err(KeyError(()))
219 } else {
220 Ok(written as usize)
221 }
222 }
223}
224
225/// Unwrap a key, according to [RFC 3394](https://tools.ietf.org/html/rfc3394)
226///
227/// * `key`: The key-encrypting-key to decrypt the wrapped key. Must be a decrypting key
228/// * `iv`: The same IV used for wrapping the key
229/// * `out`: The buffer to write the unwrapped key to
230/// * `in_`: The input ciphertext
231///
232/// Returns the number of bytes written into `out`
233///
234/// # Panics
235///
236/// Panics if either `out` or `in_` do not have sizes that are a multiple of 8, or
237/// if `in_` is not 8 bytes longer than `out`
238#[corresponds(AES_unwrap_key)]
239pub fn unwrap_key(
240 key: &AesKey,
241 iv: Option<[u8; 8]>,
242 out: &mut [u8],
243 in_: &[u8],
244) -> Result<usize, KeyError> {
245 unsafe {
246 assert!(out.len() + 8 <= in_.len());
247
248 let written: i32 = ffi::AES_unwrap_key(
249 &key.0 as *const _ as *mut _, // this is safe, the implementation only uses the key as a const pointer.
250 iv.as_ref()
251 .map_or(ptr::null(), |iv| iv.as_ptr() as *const _),
252 out.as_ptr() as *mut _,
253 in_.as_ptr() as *const _,
254 inlen:in_.len() as AesSizeType,
255 );
256
257 if written <= 0 {
258 Err(KeyError(()))
259 } else {
260 Ok(written as usize)
261 }
262 }
263}
264
265#[cfg(test)]
266mod test {
267 use hex::FromHex;
268
269 use super::*;
270 #[cfg(not(any(boringssl, awslc)))]
271 use crate::symm::Mode;
272
273 // From https://www.mgp25.com/AESIGE/
274 #[test]
275 #[cfg(not(any(boringssl, awslc)))]
276 #[cfg(not(osslconf = "OPENSSL_NO_DEPRECATED_3_0"))]
277 fn ige_vector_1() {
278 let raw_key = "000102030405060708090A0B0C0D0E0F";
279 let raw_iv = "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F";
280 let raw_pt = "0000000000000000000000000000000000000000000000000000000000000000";
281 let raw_ct = "1A8519A6557BE652E9DA8E43DA4EF4453CF456B4CA488AA383C79C98B34797CB";
282
283 let key = AesKey::new_encrypt(&Vec::from_hex(raw_key).unwrap()).unwrap();
284 let mut iv = Vec::from_hex(raw_iv).unwrap();
285 let pt = Vec::from_hex(raw_pt).unwrap();
286 let ct = Vec::from_hex(raw_ct).unwrap();
287
288 let mut ct_actual = vec![0; ct.len()];
289 aes_ige(&pt, &mut ct_actual, &key, &mut iv, Mode::Encrypt);
290 assert_eq!(ct_actual, ct);
291
292 let key = AesKey::new_decrypt(&Vec::from_hex(raw_key).unwrap()).unwrap();
293 let mut iv = Vec::from_hex(raw_iv).unwrap();
294 let mut pt_actual = vec![0; pt.len()];
295 aes_ige(&ct, &mut pt_actual, &key, &mut iv, Mode::Decrypt);
296 assert_eq!(pt_actual, pt);
297 }
298
299 // from the RFC https://tools.ietf.org/html/rfc3394#section-2.2.3
300 #[test]
301 fn test_wrap_unwrap() {
302 let raw_key = Vec::from_hex("000102030405060708090A0B0C0D0E0F").unwrap();
303 let key_data = Vec::from_hex("00112233445566778899AABBCCDDEEFF").unwrap();
304 let expected_ciphertext =
305 Vec::from_hex("1FA68B0A8112B447AEF34BD8FB5A7B829D3E862371D2CFE5").unwrap();
306
307 let enc_key = AesKey::new_encrypt(&raw_key).unwrap();
308 let mut wrapped = [0; 24];
309 assert_eq!(
310 wrap_key(&enc_key, None, &mut wrapped, &key_data).unwrap(),
311 24
312 );
313 assert_eq!(&wrapped[..], &expected_ciphertext[..]);
314
315 let dec_key = AesKey::new_decrypt(&raw_key).unwrap();
316 let mut unwrapped = [0; 16];
317 assert_eq!(
318 unwrap_key(&dec_key, None, &mut unwrapped, &wrapped).unwrap(),
319 16
320 );
321 assert_eq!(&unwrapped[..], &key_data[..]);
322 }
323}
324