ctr/lib.rs
1//! Generic implementations of [CTR mode][1] for block ciphers.
2//!
3//! <img src="https://raw.githubusercontent.com/RustCrypto/media/26acc39f/img/block-modes/ctr_enc.svg" width="49%" />
4//! <img src="https://raw.githubusercontent.com/RustCrypto/media/26acc39f/img/block-modes/ctr_dec.svg" width="49%"/>
5//!
6//! Mode functionality is accessed using traits from re-exported [`cipher`] crate.
7//!
8//! # ⚠️ Security Warning: Hazmat!
9//!
10//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
11//! is not verified, which can lead to serious vulnerabilities!
12//!
13//! # Example
14//! ```
15//! use aes::cipher::{KeyIvInit, StreamCipher, StreamCipherSeek};
16//! use hex_literal::hex;
17//!
18//! type Aes128Ctr64LE = ctr::Ctr64LE<aes::Aes128>;
19//!
20//! let key = [0x42; 16];
21//! let iv = [0x24; 16];
22//! let plaintext = *b"hello world! this is my plaintext.";
23//! let ciphertext = hex!(
24//! "3357121ebb5a29468bd861467596ce3da59bdee42dcc0614dea955368d8a5dc0cad4"
25//! );
26//!
27//! // encrypt in-place
28//! let mut buf = plaintext.to_vec();
29//! let mut cipher = Aes128Ctr64LE::new(&key.into(), &iv.into());
30//! cipher.apply_keystream(&mut buf);
31//! assert_eq!(buf[..], ciphertext[..]);
32//!
33//! // CTR mode can be used with streaming messages
34//! let mut cipher = Aes128Ctr64LE::new(&key.into(), &iv.into());
35//! for chunk in buf.chunks_mut(3) {
36//! cipher.apply_keystream(chunk);
37//! }
38//! assert_eq!(buf[..], plaintext[..]);
39//!
40//! // CTR mode supports seeking. The parameter is zero-based _bytes_ counter (not _blocks_).
41//! cipher.seek(0u32);
42//!
43//! // encrypt/decrypt from buffer to buffer
44//! // buffer length must be equal to input length
45//! let mut buf1 = [0u8; 34];
46//! cipher
47//! .apply_keystream_b2b(&plaintext, &mut buf1)
48//! .unwrap();
49//! assert_eq!(buf1[..], ciphertext[..]);
50//!
51//! let mut buf2 = [0u8; 34];
52//! cipher.seek(0u32);
53//! cipher.apply_keystream_b2b(&buf1, &mut buf2).unwrap();
54//! assert_eq!(buf2[..], plaintext[..]);
55//! ```
56//!
57//! [1]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CTR
58
59#![no_std]
60#![doc(
61 html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
62 html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
63)]
64#![forbid(unsafe_code)]
65#![cfg_attr(docsrs, feature(doc_cfg))]
66#![warn(missing_docs, rust_2018_idioms)]
67
68pub mod flavors;
69
70mod backend;
71mod ctr_core;
72
73pub use cipher;
74pub use flavors::CtrFlavor;
75
76use cipher::StreamCipherCoreWrapper;
77pub use ctr_core::CtrCore;
78
79/// CTR mode with 128-bit big endian counter.
80pub type Ctr128BE<B> = StreamCipherCoreWrapper<CtrCore<B, flavors::Ctr128BE>>;
81/// CTR mode with 128-bit little endian counter.
82pub type Ctr128LE<B> = StreamCipherCoreWrapper<CtrCore<B, flavors::Ctr128LE>>;
83/// CTR mode with 64-bit big endian counter.
84pub type Ctr64BE<B> = StreamCipherCoreWrapper<CtrCore<B, flavors::Ctr64BE>>;
85/// CTR mode with 64-bit little endian counter.
86pub type Ctr64LE<B> = StreamCipherCoreWrapper<CtrCore<B, flavors::Ctr64LE>>;
87/// CTR mode with 32-bit big endian counter.
88pub type Ctr32BE<B> = StreamCipherCoreWrapper<CtrCore<B, flavors::Ctr32BE>>;
89/// CTR mode with 32-bit little endian counter.
90pub type Ctr32LE<B> = StreamCipherCoreWrapper<CtrCore<B, flavors::Ctr32LE>>;