Cairo AES

A production-ready Cairo v2 implementation of AES-128 encryption, migrated and enhanced from Cairo 0.

Overview

This library provides a secure, NIST-compliant implementation of AES-128 (Advanced Encryption Standard with 128-bit keys) in Cairo v2. It features a u128 interface for seamless integration with Cairo applications and maintains full compatibility with standard AES implementations.

Features

• 🔒 AES-128 Encryption & Decryption: Complete implementation following NIST FIPS 197
• ✅ NIST Compliant: Passes all official test vectors
• 🚀 Production Ready: Thoroughly tested with comprehensive test coverage
• 🔄 u128 Interface: Clean API using Cairo's native u128 type
• ⚡ Optimized: Efficient Galois Field operations and AES transformations
• 🧹 Modern Cairo v2: Leverages latest language features and best practices

Installation

Add to your Scarb.toml:

[dependencies]
cairo_aes = { git = "https://github.com/yourusername/cairo-aes" }

Quick Start

use cairo_aes::{AES128, AES128Trait};

fn example() {
    // 128-bit key as u128
    let key: u128 = 0x2b7e151628aed2a6abf7158809cf4f3c;
    
    // 128-bit plaintext as u128  
    let plaintext: u128 = 0x3243f6a8885a308d313198a2e0370734;
    
    // Create AES instance
    let aes = AES128Trait::new(key);
    
    // Encrypt
    let ciphertext = aes.encrypt(plaintext);
    
    // Decrypt
    let decrypted = aes.decrypt(ciphertext);
    
    assert_eq!(decrypted, plaintext);
}

API Reference

Core Types

pub struct AES128 {
    round_keys: [u128; 11]
}

pub trait AES128Trait {
    fn new(key: u128) -> AES128;
    fn encrypt(self: @AES128, plaintext: u128) -> u128;
    fn decrypt(self: @AES128, ciphertext: u128) -> u128;
}

Utility Functions

// Convert between u128 and byte arrays
pub fn u128_to_bytes(value: u128) -> [u8; 16];
pub fn bytes_to_u128(bytes: [u8; 16]) -> u128;

Testing

Run the comprehensive test suite:

# Using Scarb (recommended)
scarb test

# Using Starknet Foundry
snforge test

Test Coverage

• ✅ NIST FIPS 197 official test vectors
• ✅ Encryption/decryption roundtrip tests
• ✅ Edge cases (zero keys/data)
• ✅ Conversion function validation
• ✅ All major AES operations verified

Project Structure

cairo-aes/
├── src/
│   ├── lib.cairo           # Public API exports
│   └── aes_128.cairo       # AES-128 implementation
├── tests/                  # Integration tests
│   ├── test_aes_128.cairo  # NIST test vectors
│   ├── test_fixed.cairo    # Core functionality tests
│   └── test_simple.cairo   # Basic validation tests
└── docs/
    └── AES_128_FIX_REPORT.md # Technical implementation notes

Implementation Details

This implementation includes all standard AES-128 operations:

• SubBytes/InvSubBytes: S-box transformations with 256-byte lookup tables
• ShiftRows/InvShiftRows: Row shifting operations
• MixColumns/InvMixColumns: Galois Field (GF(2^8)) multiplication
• AddRoundKey: XOR operations with expanded round keys
• Key Expansion: Generates 11 round keys using AES key schedule

Performance Notes

• Fixed-size arrays for optimal Cairo v2 performance
• Efficient span-based operations for array manipulation
• Optimized Galois Field arithmetic with proper overflow handling
• Memory-efficient implementation suitable for on-chain usage

Migration from Cairo 0

This version represents a complete rewrite for Cairo v2:

Cairo 0	Cairo v2
Manual lookup tables (3000+ lines)	Efficient array constants
felt interface	Clean u128 interface
Basic test coverage	Comprehensive test suite
Complex memory management	Modern array operations

Breaking Changes:

• API changed from felt to u128
• Function signatures updated for Cairo v2 syntax
• Module structure reorganized

Migration Guide:

// Cairo 0
let result = aes_128_encrypt(input, key, length);

// Cairo v2  
let aes = AES128Trait::new(key);
let result = aes.encrypt(plaintext);

Security & Production Readiness

✅ Functional Validation

• Cryptographically correct implementation
• NIST test vector compliance
• Comprehensive test coverage

⚠️ Security Considerations

• Implementation not formally audited for side-channel attacks
• Recommended additional hardening for high-security environments:
  • External cryptographic review
  • Constant-time analysis
  • Fuzz testing

Production Deployment

• ✅ Ready for most production use cases
• ⚠️ Additional review recommended for high-security applications

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: scarb test
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

Special thanks to Onur Inanc for the original Cairo 0 AES implementation that served as the foundation for this Cairo v2 migration. This project builds upon that excellent groundwork while modernizing it for the latest Cairo language features.

References

• NIST FIPS 197 - AES Specification
• Cairo v2 Documentation
• Scarb Documentation
• Original Cairo 0 Implementation by Onur Inanc

---

Status: Production Ready ✅ | Tests: 12/12 Passing ✅ | NIST Compliant: ✅