Module aes 

Advanced Encryption Standard (AES) hardware accelerator

This module provides support for the AES v3b hardware accelerator peripheral found on STM32WBA series microcontrollers.

Supported Cipher Modes

Mode	Padding	Auth	Use Case
ECB	Required	No	Keys only (not recommended for data)
CBC	Required	No	File/disk encryption
CTR	No	No	Streaming data, random access
GCM	No	Yes	Recommended - Modern applications
CCM	No	Yes	Resource-constrained devices

Key Sizes

• 128-bit (16 bytes)
• 256-bit (32 bytes)
• Note: 192-bit keys are NOT supported on this hardware

Examples

Basic ECB Mode (Block Cipher)

use embassy_stm32::aes::{Aes, AesEcb, Direction};
use embassy_stm32::{bind_interrupts, peripherals};

bind_interrupts!(struct Irqs {
    AES => embassy_stm32::aes::InterruptHandler<peripherals::AES>;
});

let key = [0u8; 16];  // 128-bit key
let cipher = AesEcb::new(&key);

let mut aes = Aes::new_blocking(p.AES, Irqs);
let mut ctx = aes.start(&cipher, Direction::Encrypt);

let plaintext = [0u8; 16];
let mut ciphertext = [0u8; 16];
aes.payload_blocking(&mut ctx, &plaintext, &mut ciphertext, true);
aes.finish_blocking(ctx);

CBC Mode (With IV)

use embassy_stm32::aes::{Aes, AesCbc, Direction};

let key = [0u8; 16];
let iv = [0u8; 16];  // Random IV, unique per message
let cipher = AesCbc::new(&key, &iv);

let mut ctx = aes.start(&cipher, Direction::Encrypt);
// Process multiple blocks
aes.payload_blocking(&mut ctx, &plaintext, &mut ciphertext, true);
aes.finish_blocking(ctx);

CTR Mode (Stream Cipher - No Padding)

use embassy_stm32::aes::{Aes, AesCtr, Direction};

let key = [0u8; 16];
let counter = [0u8; 16];  // Nonce + counter
let cipher = AesCtr::new(&key, &counter);

let mut ctx = aes.start(&cipher, Direction::Encrypt);
// Can process any length data (no padding needed)
let partial_data = [0u8; 13]; // Not block-aligned - OK for CTR!
let mut output = [0u8; 13];
aes.payload_blocking(&mut ctx, &partial_data, &mut output, true);
aes.finish_blocking(ctx);

GCM Mode (Authenticated Encryption - Recommended)

use embassy_stm32::aes::{Aes, AesGcm, Direction};

let key = [0u8; 16];
let iv = [0u8; 12];  // 96-bit nonce (12 bytes)
let cipher = AesGcm::new(&key, &iv);

let mut ctx = aes.start(&cipher, Direction::Encrypt);

// Process Additional Authenticated Data (AAD) - optional
let aad = b"metadata that will be authenticated but not encrypted";
aes.aad_blocking(&mut ctx, aad, true);

// Encrypt payload
aes.payload_blocking(&mut ctx, &plaintext, &mut ciphertext, true);

// Get authentication tag
if let Ok(Some(tag)) = aes.finish_blocking(ctx) {
    // Send tag with ciphertext for verification
}

Security Best Practices

Key Management

• Use hardware RNG for key generation
• Never hardcode keys in production
• Consider using SAES hardware key derivation
• Never reuse keys inappropriately

IV/Nonce Requirements

• CBC: Random, unique per message
• CTR: Must NEVER repeat with same key (use counter)
• GCM: 96-bit (12 bytes), unique per message
• CRITICAL: IV reuse is catastrophic in CTR/GCM modes

Mode Selection

• Use GCM for new applications (provides authentication)
• Use CTR for streaming or arbitrary-length data
• Avoid ECB for anything except encrypting random keys
• CBC/CTR alone don’t provide authentication - consider GCM or add HMAC

Hardware Capabilities

AES v3b (STM32WBA):

• Block size: 16 bytes (128 bits)
• Key sizes: 128-bit, 256-bit
• DMA support: Yes (async mode)
• Interrupt support: Yes
• Suspend/resume: Yes (for GCM/CCM)

Performance

Hardware acceleration provides significant speed improvements over software:

• ~10-20× faster than pure software implementation
• Constant-time operation (side-channel resistant)
• Low CPU overhead

See Also

• saes - Secure AES with hardware key derivation
• pka - Public Key Accelerator (ECDSA verification)
• Examples: examples/stm32wba/src/bin/aes_*.rs

Structs

Aes

AES driver.

AesCbc

AES-CBC Cipher Mode

AesCcm

AES-CCM Cipher Mode (Counter with CBC-MAC)

AesCtr

AES-CTR Cipher Mode

AesEcb

AES-ECB Cipher Mode

AesGcm

AES-GCM Cipher Mode

AesGmac

AES-GMAC Cipher Mode (Galois Message Authentication Code)

Context

Stores the state of the AES peripheral for suspending/resuming operations.

InterruptHandler

AES interrupt handler.

Enums

Direction

AES cipher direction

Error

AES error

KeySize

AES key size

Traits

Cipher

This trait encapsulates all cipher-specific behavior.

CipherAuthenticated

This trait enables restriction of a header phase to authenticated ciphers only.

CipherSized

This trait enables restriction of ciphers to specific key sizes.

DmaIn

DmaIn DMA request trait

DmaOut

DmaOut DMA request trait

IVSized

This trait enables restriction of initialization vectors to sizes compatible with a cipher mode.

Instance

AES instance trait.