diff --git a/aes/src/operations/column_mix.rs b/aes/src/operations/column_mix.rs index e0c064b..6806677 100644 --- a/aes/src/operations/column_mix.rs +++ b/aes/src/operations/column_mix.rs @@ -1,5 +1,9 @@ use crate::Block128; +/// Mixes each column using matrix multiplication in GF(2^8) (MixColumns step). +/// +/// Each column is treated as a polynomial and multiplied by a fixed polynomial +/// modulo x^4 + 1. This provides diffusion across the rows. #[must_use] pub fn mix_columns(block: Block128) -> Block128 { let mut bytes = block.to_be_bytes(); @@ -28,6 +32,7 @@ pub fn mix_columns(block: Block128) -> Block128 { Block128::from_be_bytes(bytes) } +/// Inverse of [`mix_columns`] using the inverse matrix. #[must_use] pub fn inv_mix_columns(block: Block128) -> Block128 { let mut bytes = block.to_be_bytes(); diff --git a/aes/src/operations/round_key.rs b/aes/src/operations/round_key.rs index bdd1fca..eb94b33 100644 --- a/aes/src/operations/round_key.rs +++ b/aes/src/operations/round_key.rs @@ -1,5 +1,10 @@ use crate::{Block128, key::Subkey}; +/// XORs the state with a round key (AddRoundKey step). +/// +/// Each round of AES combines the current state with a derived subkey +/// using bitwise XOR. This operation is its own inverse. +#[must_use] pub fn add_round_key(state: Block128, subkeys: &[Subkey; 4]) -> Block128 { let [k0, k1, k2, k3] = [subkeys[0], subkeys[1], subkeys[2], subkeys[3]]; let key_block = (k0 << 96) | (k1 << 64) | (k2 << 32) | k3; diff --git a/aes/src/operations/row_shift.rs b/aes/src/operations/row_shift.rs index 6db8282..7e61246 100644 --- a/aes/src/operations/row_shift.rs +++ b/aes/src/operations/row_shift.rs @@ -1,5 +1,9 @@ use crate::Block128; +/// Cyclically shifts rows of the state matrix (ShiftRows step). +/// +/// Row 0: no shift, Row 1: shift left 1, Row 2: shift left 2, Row 3: shift left 3. +/// This provides diffusion across the columns. #[must_use] pub const fn shift_rows(block: Block128) -> Block128 { let b = block.to_be_bytes(); @@ -32,6 +36,7 @@ pub const fn shift_rows(block: Block128) -> Block128 { Block128::from_be_bytes(out) } +/// Inverse of [`shift_rows`] - shifts rows right instead of left. #[must_use] pub const fn inv_shift_rows(block: Block128) -> Block128 { let b = block.to_be_bytes(); diff --git a/aes/src/operations/sbox_lookup.rs b/aes/src/operations/sbox_lookup.rs index 8ab44d8..06157f2 100644 --- a/aes/src/operations/sbox_lookup.rs +++ b/aes/src/operations/sbox_lookup.rs @@ -1,11 +1,16 @@ use crate::{Block128, sbox::SboxLookup}; +/// Substitutes each byte using the AES S-box (SubBytes step). +/// +/// Provides non-linearity by replacing each byte with its S-box lookup value. +/// The S-box is derived from the multiplicative inverse in GF(2^8). #[inline] #[must_use] pub fn sub_bytes(block: Block128) -> Block128 { block.sbox_lookup() } +/// Inverse of [`sub_bytes`] using the inverse S-box. #[inline] #[must_use] pub fn inv_sub_bytes(block: Block128) -> Block128 {