aes_elk/lib.rs
1//! Generic implementation of the ELK (Encrypted LFSR Keystream) mode of operation for block ciphers.
2//!
3//! Mode functionality is accessed using traits from the re-exported [`cipher`] crate.
4//! ELK is a stream-like mode of operation that generates a keystream by encrypting the state of a
5//! Galois-Field Linear Feedback Shift Register (LFSR) with a block cipher.
6//!
7//! # ⚠️ Security Warning: Hazmat!
8//!
9//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
10//! is not verified, which can lead to serious vulnerabilities!
11//! It is highly recommended to use ELK in combination with a strong MAC to provide robust authenticated encryption.
12//!
13//! # Stream Cipher Behavior & State
14//!
15//! Because ELK is a keystream-based cipher, encryption and decryption are mathematically identical
16//! (XORing a keystream). However, the internal LFSR state of the `Elk` instance is advanced with each
17//! block processed. Therefore:
18//!
19//! * To decrypt a ciphertext, you must use a cipher instance initialized with the **same** initial key and IV.
20//! * Calling `.apply_keystream(&mut data)` twice in succession on the *same* unmodified instance will
21//! not work as expected because the second call will use the advanced LFSR state instead of the initial state.
22//!
23//! # Example
24//! ```
25//! use aes::cipher::KeyIvInit;
26//! use aes_elk::Elk;
27//!
28//! type Aes128Elk = Elk<aes::Aes128>;
29//!
30//! let key = [0x42; 16];
31//! let iv = [0x24; 16];
32//! let plaintext = *b"hello world! this is my plaintext! it can be any length.";
33//!
34//! // encrypt in-place
35//! let mut buf = plaintext.to_vec();
36//! let mut encryptor = Aes128Elk::new(&key.into(), &iv.into());
37//! let mut decryptor = encryptor.clone(); // Clone the initial state for decryption
38//!
39//! encryptor.apply_keystream(&mut buf).unwrap();
40//! assert_ne!(buf[..], plaintext[..]);
41//!
42//! // decrypt in-place
43//! decryptor.apply_keystream(&mut buf).unwrap();
44//! assert_eq!(buf[..], plaintext[..]);
45//! ```
46
47#![no_std]
48#![forbid(unsafe_code, elided_lifetimes_in_paths)]
49#![cfg_attr(docsrs, feature(doc_cfg))]
50
51mod elk;
52
53pub use cipher;
54pub use crate::elk::{Elk, Error};