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
• Usage
  • AES ECB Mode
  • AES CBC Mode
  • AES CMAC
  • PKCS#7 Padding
• Testing
  • Current NIST Test Coverage
  • Core Unit Tests
  • Future Test Expansion
• Disclaimer
• Official Standard References
• Acknowledgments
• Related Projects
  • soft-aes-wasm
  • Web UI for AES Encryption/Decryption
• Contributing
• 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:

[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

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

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

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

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.

• AES-CMAC is defined in RFC 4493.

• AES-CMAC for different key lengths is defined in NIST SP 800-38B.

• PKCS#7 padding is defined in RFC 2315.

• 0x80 padding is defined in ISO/IEC 9797-1 padding method 2.

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 served as commit assistant.

Related Projects

soft-aes-wasm

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. 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 file.