1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
//! This crate provides an intuitive interface for AES-128, AES-192, and AES-256 encryption and decryption.
//! The following modes of operation are supported:
//! - **Galois/counter mode** ([GCM](crate::Cipher::encrypt_gcm)), with optional additional authenticated data (AAD).
//! Encrypts using CTR mode and generates an authentication tag from the AAD + ciphertext. This tag is recomputed at decryption
//! and compared with the received tag.
//! - **Counter mode** ([CTR](crate::Cipher::encrypt_ctr)). A 16-byte counter is repeatedly incremented and encrypted.
//! The result is `XOR`'d with the plaintext to produce the ciphertext.
//! This turns AES into a stream cipher, which removes vulnerabilities present in modes such as ECB.
//! - **Electronic codebook mode** ([ECB](crate::Cipher::encrypt_ecb)). Encrypts each block of plaintext seperately and appends to the output.
//! Vulnerable to pattern emergence in larger inputs. Use a stream cipher mode (CTR or GCM) if security is important.
//!
//! ## Examples
//! Below is an example of a string being encrypted under a random key using AES-256-CTR, then decrypted back to plaintext.
//! ```
//! # fn main() -> aesp::Result<()> {
//! use aesp::{Key, Cipher};
//!
//! // generate a random 256-bit key.
//! let key = Key::rand_key_256()?;
//!
//! // instantiate a cipher object using that key.
//! let cipher = Cipher::new(&key);
//!
//! // instantiate sample plaintext (cipher encrypts raw bytes).
//! let plaintext = ("Hello, World!").as_bytes();
//!
//! // encrypt the plaintext bytes using AES-256-CTR.
//! // note that the key size does not need to be explicitly stated.
//! let ciphertext = cipher.encrypt_ctr(&plaintext)?;
//!
//! // decrypt the resultant ciphertext.
//! let decrypted_ct = cipher.decrypt_ctr(&ciphertext)?;
//!
//! // round trip results in the same plaintext as the original message.
//! assert_eq!(plaintext, decrypted_ct);
//!
//! # Ok(())
//! # }
//! ```
pub use ;