RustCrypto: block ciphers
Collection of block ciphers and block modes written in pure Rust.
Warnings
Currently only the aes
crate provides constant-time implementation and has received a third-party security audit.
Other crates in this repository are not implemented in a constant-time manner and have not yet received any formal cryptographic and security reviews.
It's generally recommended not to use other cipher implementations in this repository besides the aes
crate.
USE AT YOUR OWN RISK.
Supported algorithms
Name | Crate name | crates.io | Docs | Build Status |
---|---|---|---|---|
AES (Rijndael) | aes |
|||
Blowfish | blowfish |
|||
CAST5 (CAST-128) | cast5 |
|||
DES + 3DES (DEA, 3DEA) | des |
|||
IDEA | idea |
|||
Kuznyechik (GOST R 34.12-2015) | kuznyechik |
|||
Magma (GOST 28147-89 and GOST R 34.12-2015) | magma |
|||
RC2 (ARC2) | rc2 |
|||
Serpent | serpent |
|||
SM4 | sm4 |
|||
Twofish | twofish |
|||
Threefish | threefish |
Additional crates
Crate name | crates.io | Docs | Build Status |
---|---|---|---|
block-modes |
|||
gost-modes |
Minimum Supported Rust Version
All crates in this repository support Rust 1.22 or higher. (except aesni
and aes
crates, which require Rust 1.27) In future minimum supported Rust version can be changed, but it will be done with the minor version bump.
Usage
Block cipher crates provide only bare block cipher implementations. For most applications you will need to use some block cipher mode of operation which are generically implemented in the block-modes
crate.
Some block modes (CTR, CFB, OFV) transform block ciphers into stream ciphers.Such modes are published under separate crates in the RustCrypto/stream-ciphers repository.
Lets use AES128-CBC with PKCS7 padding to show an example:
use aes::Aes128;
use block_modes::{BlockMode, Cbc};
use block_modes::block_padding::Pkcs7;
use hex_literal::hex;
// create an alias for convenience
type Aes128Cbc = Cbc<Aes128, Pkcs7>;
let key = hex!("000102030405060708090a0b0c0d0e0f");
let iv = hex!("f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff");
let plaintext = b"Hello world!";
let cipher = Aes128Cbc::new_from_slices(&key, &iv).unwrap();
// buffer must have enough space for message+padding
let mut buffer = [0u8; 32];
// copy message to the buffer
let pos = plaintext.len();
buffer[..pos].copy_from_slice(plaintext);
let ciphertext = cipher.encrypt(&mut buffer, pos).unwrap();
assert_eq!(ciphertext, hex!("1b7a4c403124ae2fb52bedc534d82fa8"));
// re-create cipher mode instance and decrypt the message
let cipher = Aes128Cbc::new_from_slices(&key, &iv).unwrap();
let mut buf = ciphertext.to_vec();
let decrypted_ciphertext = cipher.decrypt(&mut buf).unwrap();
assert_eq!(decrypted_ciphertext, plaintext);
With an enabled std
feature (which is enabled by default) you can use encrypt_vec
and decrypt_vec
methods:
let cipher = Aes128Cbc::new_from_slices(&key, &iv).unwrap();
let ciphertext = cipher.encrypt_vec(plaintext);
assert_eq!(ciphertext, hex!("1b7a4c403124ae2fb52bedc534d82fa8"));
let cipher = Aes128Cbc::new_from_slices(&key, &iv).unwrap();
let decrypted_ciphertext = cipher.decrypt_vec(&ciphertext).unwrap();
assert_eq!(decrypted_ciphertext, plaintext);
Note that this example does not use any authentification which can lead to serious vulnarabilities! For Message Authentication Code implementations take a look at RustCrypto/MACs repository.
License
All crates licensed under either of
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.