# Soft-AES: A Software-Based Functional AES Library in Rust
**Soft-AES** is a Rust library offering a software-based implementation of the
Advanced Encryption Standard (AES) algorithm, distinct from hardware-based
solutions. It provides AES encryption and decryption in Electronic Codebook
(ECB) and Cipher Block Chaining (CBC) modes and an integrated Cipher-based
Message Authentication Code (AES-CMAC) calculation.
The library includes support for PKCS#7 padding and `0x80` padding (ISO/IEC
9797-1 Padding Method 2).
AES functionalities in Soft-AES are implemented using a functional approach, as
opposed to instance-based approaches. By employing lookup tables for critical
AES operations, the library achieves a balance between simplicity and
performance.
**HAZMAT!** It's important to recognize that this implementation does not
currently incorporate defenses against side-channel attacks. Consequently,
Soft-AES is optimally suited for educational purposes and non-critical
application scenarios like testing where advanced protections are not a primary
concern.
## Table of Contents
- [Features](#features)
- [Usage](#usage)
- [AES ECB Mode](#aes-ecb-mode)
- [AES CBC Mode](#aes-cbc-mode)
- [AES CMAC](#aes-cmac)
- [PKCS#7 Padding](#pkcs7-padding)
- [Testing](#testing)
- [Current NIST Test Coverage](#current-nist-test-coverage)
- [Core Unit Tests](#core-unit-tests)
- [Future Test Expansion](#future-test-expansion)
- [Disclaimer](#disclaimer)
- [Official Standard References](#official-standard-references)
- [Acknowledgments](#acknowledgments)
- [Related Projects](#related-projects)
- [soft-aes-wasm](#soft-aes-wasm)
- [Web UI for AES Encryption/Decryption](#web-ui-for-aes-encryptiondecryption)
- [Contributing](#contributing)
- [License](#license)
## Features
- **AES Core:** Core implementations for encryption and decryption processes of
a single block, including SubBytes, ShiftRows, MixColumns, and their
inverses.
- **ECB Mode:** Simple block-wise encryption and decryption without chaining.
- **CBC Mode:** Improved block-wise encryption and decryption with
Initialization Vector (IV) based chaining.
- **AES-CMAC:** Message authentication capabilities based on AES-128, AES-192
and AES-256.
- **PKCS#7 Padding:** Support for PKCS#7 padding scheme to ensure uniform block
sizes.
- **0x80 Padding:** Support for `0x80` padding (ISO/IEC 9797-1 Padding Method
2).
## Usage
To use `soft-aes` in your Rust project, add it as a dependency in your
`Cargo.toml` file:
```toml
[dependencies]
soft-aes = "0.2.0"
```
This library is designed for straightforward integration into cryptographic
applications, especially those requiring AES encryption and decryption. Below
are basic usage examples for different components of the library.
### AES ECB Mode
```rust
use soft_aes::aes::{aes_enc_ecb, aes_dec_ecb};
let plaintext = b"Example plaintext.";
let key = b"Very secret key.";
let padding = Some("PKCS7");
let encrypted = aes_enc_ecb(plaintext, key, padding).expect("Encryption failed");
let decrypted = aes_dec_ecb(&encrypted, key, padding).expect("Decryption failed");
assert_eq!(decrypted, plaintext);
```
### AES CBC Mode
```rust
use soft_aes::aes::{aes_enc_cbc, aes_dec_cbc};
let plaintext = b"Example plaintext.";
let key = b"Very secret key.";
let iv = b"Random Init Vec.";
let padding = Some("PKCS7");
let encrypted = aes_enc_cbc(plaintext, key, iv, padding).expect("Encryption failed");
let decrypted = aes_dec_cbc(&encrypted, key, iv, padding).expect("Decryption failed");
assert_eq!(decrypted, plaintext);
```
### AES CMAC
```rust
use soft_aes::aes::aes_cmac;
use hex::decode as hex_decode;
let key = hex_decode("603DEB1015CA71BE2B73AEF0857D77811F352C073B6108D72D9810A30914DFF4").unwrap();
let message = hex_decode("6BC1BEE22E409F96E93D7E117393172AAE2D8A57").unwrap();
let mac = aes_cmac(&message, &key).unwrap();
assert_eq!(
mac.to_vec(),
hex_decode("156727DC0878944A023C1FE03BAD6D93").unwrap()
);
```
### PKCS#7 Padding
```rust
use soft_aes::padding::{pkcs7_pad, pkcs7_unpad};
let mut data = vec![0x01, 0x02, 0x03];
let block_size = 8;
pkcs7_pad(&mut data, block_size).expect("Padding failed");
assert_eq!(data, vec![0x01, 0x02, 0x03, 0x05, 0x05, 0x05, 0x05, 0x05]);
pkcs7_unpad(&mut data).expect("Unpadding failed");
assert_eq!(data, vec![0x01, 0x02, 0x03]);
```
## Testing
The Soft-AES library includes comprehensive testing against the National
Institute of Standards and Technology (NIST) Advanced Encryption Standard
Algorithm Validation Suite (AESAVS) for ECB mode and additional test vectors.
### Current NIST Test Coverage
- **AES ECB Mode Validation:** Extensive coverage utilizing Known Answer Tests
(KAT) from the AESAVS for various key sizes.
### Core Unit Tests
Additional tests using test vectors from CryptoTool's Online AES Step-by-Step
Tool.
### Future Test Expansion
Plans to expand test coverage for other AES modes and additional test
scenarios.
## Disclaimer
- **ECB Mode Limitations:** The ECB mode of AES does not ensure confidentiality
for data with recognizable patterns.
- **CBC Mode Considerations:** While AES CBC mode enhances security, it
requires careful management of the Initialization Vector (IV).
- **Cryptographic Randomness and Key Management:** The library does not include
its own cryptographic random number generators or manage cryptographic
keys.
- **No Protection Against Side-Channel Attacks:** Intended primarily for
educational use and non-critical applications.
- **"As Is" Provision:** The library is provided "as is," without any
warranty.
## Official Standard References
- AES is defined in [FIPS PUB 197](https://csrc.nist.gov/pubs/fips/197/final).
- AES-CMAC is defined in [RFC 4493](https://www.rfc-editor.org/rfc/rfc4493).
- AES-CMAC for different key lengths is defined in [NIST SP
800-38B](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38b.pdf).
- PKCS#7 padding is defined in [RFC
2315](https://www.rfc-editor.org/rfc/rfc2315).
- 0x80 padding is defined in [ISO/IEC 9797-1 padding method
2](https://www.iso.org/standard/50375.html).
## Acknowledgments
The development of the Soft-AES library is a culmination of knowledge,
resources, and tools that have significantly influenced its design and
implementation.
The Rust implementation of Soft-AES is fundamentally based on a C
implementation I implemented during my studies, primarily guided by the book
"The Design of Rijndael" and its reference code. The updated insights from "The
Design of Rijndael: AES - The Advanced Encryption Standard" by Joan Daemen and
Vincent Rijmen.
Additionally, AI assistance was utilized for documenting, commenting, and
troubleshooting various aspects of the library and
[SmartCommit](https://github.com/5n00py/SmartCommit) served as commit
assistant.
## Related Projects
### soft-aes-wasm
[soft-aes-wasm](https://github.com/5n00py/soft-aes-wasm) is a
companion project that extends the functionality of the `Soft-AES` library to
WebAssembly (Wasm). This project enables AES encryption and
decryption directly in web applications by providing a Wasm interface for
`Soft-AES`.
### Web UI
For a practical and user-friendly implementation of AES directly in the
browser, visit [AES-Wasm Tool](https://jointech.at/tools/aes-wasm/index.html).
This web tool based on `soft-aes-wasm` library provides a convenient solution
for performing AES encryption and decryption tests in the browser.
## License
Copyright David Schmid (david.schmid@mailbox.org)
The binaries are distributed under the terms of the GNU General Public License
Version 3 (GPLv3), as detailed in the [LICENSE](LICENSE) file.