tc_camellia/lib.rs
1//! Camellia-128, Camellia-192 and Camellia-256 block cipher as specified by
2//! RFC 3713.
3//!
4//! [`CamelliaEngine`] accepts 16-, 24- or 32-byte keys and processes 16-byte
5//! blocks. Import [`BlockCipherInit`](tc_block_cipher::BlockCipherInit) and
6//! [`BlockCipher`](tc_block_cipher::BlockCipher) to initialize and use it.
7//!
8//! # Example
9//!
10//! Encrypt one block with the 128-bit key from RFC 3713, then decrypt it:
11//!
12//! ```
13//! use tc_block_cipher::{BlockCipher, BlockCipherInit, CipherDirection, KeyRef};
14//! use tc_camellia::{BLOCK_BYTES, CamelliaEngine};
15//!
16//! let key = [
17//! 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef,
18//! 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10,
19//! ];
20//! let plaintext = key;
21//!
22//! let mut encryptor = CamelliaEngine::new();
23//! encryptor.init(CipherDirection::Encrypt, &KeyRef::new(&key))?;
24//! let mut ciphertext = [0; BLOCK_BYTES];
25//! encryptor.process_block(&plaintext, &mut ciphertext)?;
26//!
27//! let mut decryptor = CamelliaEngine::new();
28//! decryptor.init(CipherDirection::Decrypt, &KeyRef::new(&key))?;
29//! let mut recovered = [0; BLOCK_BYTES];
30//! decryptor.process_block(&ciphertext, &mut recovered)?;
31//!
32//! assert_eq!(recovered, plaintext);
33//! # Ok::<(), Box<dyn core::error::Error>>(())
34//! ```
35//!
36//! # Backend selection
37//!
38//! With the `rustcrypto` feature, `CamelliaEngine` delegates to
39//! `CamelliaRustCryptoEngine`, backed by the RustCrypto `camellia` crate.
40//! Without it, the engine delegates to [`CamelliaTableEngine`], which uses four
41//! 256-entry `u32` T-tables. [`CamelliaLightEngine`] uses a single 256-byte
42//! S-box instead, for small code and data. Every implementation is also
43//! available for direct use when enabled.
44//!
45//! # Security
46//!
47//! No backend is **constant time**: key setup and block processing use
48//! secret-dependent table lookups. It is unsuitable where cache-timing attacks
49//! are in scope. Stored schedules are wiped on drop, but callers remain
50//! responsible for their input keys and other copies.
51//!
52//! This is a block-cipher primitive, not message encryption. It provides no
53//! padding, nonce handling, mode or authentication. Use an appropriate
54//! authenticated-encryption construction for messages.
55//!
56//! The crate is `no_std` and requires no allocator.
57
58#![no_std]
59#![deny(missing_docs)]
60#![forbid(unsafe_code)]
61
62mod cipher;
63mod engine;
64mod light_engine;
65#[cfg(feature = "rustcrypto")]
66mod rustcrypto_engine;
67mod table_engine;
68
69pub use engine::CamelliaEngine;
70pub use light_engine::CamelliaLightEngine;
71#[cfg(feature = "rustcrypto")]
72pub use rustcrypto_engine::CamelliaRustCryptoEngine;
73pub use table_engine::CamelliaTableEngine;
74
75/// Algorithm name returned by every engine's `Display` implementation.
76pub const ALGO_NAME: &str = "Camellia";
77/// Camellia block length in bytes (128 bits), independent of key size.
78pub const BLOCK_BYTES: usize = 16;
79/// Accepted key lengths in bytes (128, 192 and 256 bits).
80pub const KEY_BYTES: [usize; 3] = [16, 24, 32];