@@ -1,4 +1,4 @@
-//! Run in real mode: `cargo run --release --example aes_gcm_128`
+//! Run: `cargo run --release --example aes_gcm_128`
 #![allow(incomplete_features)]
 #![feature(generic_const_exprs)]
 
@@ -15,13 +15,23 @@
 use plonky2_aes::{AesGcm128Target, D, KEY_LEN_128};
 
 fn main() -> Result<()> {
-    const L: usize = 42; // size (bytes) of plaintext to encrypt
+    // max size (bytes) of plaintext supported by the instantiation of the circuit
+    const L: usize = 42;
 
-    let key: &[u8; KEY_LEN_128] = &[42; KEY_LEN_128];
+    let key: &[u8; KEY_LEN_128] = &[123; KEY_LEN_128];
     let nonce: &[u8; 12] = &[111; 12];
-    let pt: &[u8; L] = &[42u8; L];
+    let pt: &[u8; L] = &[231u8; L]; // plaintext
 
-    let (ct, tag) = plonky2_aes::native_gcm::encrypt::<4, 4, 10>(key, nonce, pt);
+    // use external rust library to compute the ciphertext & tag
+    let nonce_ext = aes_gcm::Nonce::from_slice(nonce);
+    use aes_gcm::{aead::Aead, KeyInit}; // needed traits
+    let cipher = aes_gcm::Aes128Gcm::new_from_slice(key.as_slice()).unwrap();
+    let encrypt_res = cipher.encrypt(nonce_ext, pt.as_ref()).unwrap();
+    let ct = &encrypt_res[..L]; // ciphertext
+    let tag = &encrypt_res[L..];
+
+    // alternatively we could use this repo's rust implementation (only for tests)
+    // let (ct, tag) = plonky2_aes::native_gcm::encrypt::<4, 4, 10>(key, nonce, pt);
 
     // Circuit declaration
     let config = CircuitConfig::standard_recursion_config();

@@ -1,4 +1,4 @@
-//! Run in real mode: `cargo run --release --example aes_gcm_256`
+//! Run: `cargo run --release --example aes_gcm_256`
 #![allow(incomplete_features)]
 #![feature(generic_const_exprs)]
 
@@ -15,13 +15,23 @@
 use plonky2_aes::{AesGcm256Target, D, KEY_LEN_256};
 
 fn main() -> Result<()> {
-    const L: usize = 42; // size (bytes) of plaintext to encrypt
+    // max size (bytes) of plaintext supported by the instantiation of the circuit
+    const L: usize = 42;
 
-    let key: &[u8; KEY_LEN_256] = &[42; KEY_LEN_256];
+    let key: &[u8; KEY_LEN_256] = &[123; KEY_LEN_256];
     let nonce: &[u8; 12] = &[111; 12];
-    let pt: &[u8; L] = &[42u8; L];
+    let pt: &[u8; L] = &[231u8; L]; // plaintext
 
-    let (ct, tag) = plonky2_aes::native_gcm::encrypt::<8, 4, 14>(key, nonce, pt);
+    // use external rust library to compute the ciphertext & tag
+    let nonce_ext = aes_gcm::Nonce::from_slice(nonce);
+    use aes_gcm::{aead::Aead, KeyInit}; // needed traits
+    let cipher = aes_gcm::Aes256Gcm::new_from_slice(key.as_slice()).unwrap();
+    let encrypt_res = cipher.encrypt(nonce_ext, pt.as_ref()).unwrap();
+    let ct = &encrypt_res[..L]; // ciphertext
+    let tag = &encrypt_res[L..];
+
+    // alternatively we could use this repo's rust implementation (only for tests)
+    // let (ct, tag) = plonky2_aes::native_gcm::encrypt::<8, 4, 14>(key, nonce, pt);
 
     // Circuit declaration
     let config = CircuitConfig::standard_recursion_config();

@@ -1,4 +1,7 @@
 //! For LICENSE check out https://github.com/0xPARC/plonky2-aes/blob/main/LICENSE
+//!
+//! Plonky2 circuit implementation of
+//! [AES](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197-upd1.pdf).
 
 use std::{array, sync::Arc};
 
@@ -13,9 +16,9 @@ plonk::circuit_builder::CircuitBuilder,
 };
 
 use crate::{
-    D,
     constants::{RCON, SBOX},
-    native_aes::{State, rot_word, shift_rows},
+    native_aes::{rot_word, shift_rows, State},
+    D,
 };
 
 #[derive(Debug, Copy, Clone)]
@@ -62,7 +65,7 @@ ) -> StateTarget;
 
     /// AddRoundKey
     fn state_add_round_key(&mut self, round_key: &[[ByteTarget; 4]], s: StateTarget)
-    -> StateTarget;
+        -> StateTarget;
 
     /// KeyExpansion
     fn key_expansion<const NK: usize, const NB: usize, const NR: usize>(
@@ -411,10 +414,10 @@ };
     use rand::RngExt;
 
     use super::{
-        ByteTarget, CircuitBuilderAESState, PartialWitnessAESState, PartialWitnessByteArray,
-        sbox_lut, state_mix_matrix_bits,
+        sbox_lut, state_mix_matrix_bits, ByteTarget, CircuitBuilderAESState,
+        PartialWitnessAESState, PartialWitnessByteArray,
     };
-    use crate::native_aes::{State, encrypt_block, key_expansion, mix_columns, sub_bytes};
+    use crate::native_aes::{encrypt_block, key_expansion, mix_columns, sub_bytes, State};
 
     use super::D;
 

@@ -1,4 +1,7 @@
 //! For LICENSE check out https://github.com/0xPARC/plonky2-aes/blob/main/LICENSE
+//!
+//! Plonky2 circuit implementation of
+//! [AES-GCM (Galois Counter Mode)](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf).
 
 use anyhow::Result;
 use std::array;
@@ -11,12 +14,12 @@ plonk::circuit_builder::CircuitBuilder,
 };
 
 use crate::{
-    D,
     circuit_aes::{
-        ByteTarget, CircuitBuilderAESState, PartialWitnessByteArray, StateTarget,
-        le_bits_from_byte, sbox_lut, state_mix_matrix_bits, xor,
+        le_bits_from_byte, sbox_lut, state_mix_matrix_bits, xor, ByteTarget,
+        CircuitBuilderAESState, PartialWitnessByteArray, StateTarget,
     },
     constants::TAG_LEN,
+    D,
 };
 
 pub struct AesGcmTarget<
@@ -253,11 +256,8 @@ // fn ghash_target<const L: usize>(
 fn ghash_target(
     builder: &mut CircuitBuilder<F, D>,
     h: [ByteTarget; 16],
-    // x: &[ByteTarget; L],
     x: Vec<ByteTarget>,
 ) -> [ByteTarget; 16] {
-    // assert!(L.is_multiple_of(16)); // multiple of 128 bits
-    // let m = L / 16;
     assert!(x.len().is_multiple_of(16)); // multiple of 128 bits
     let m = x.len() / 16;
 
@@ -435,8 +435,8 @@ test_gctr_opt::<8, 4, 14, 13>()?;
 
         Ok(())
     }
-    fn test_gctr_opt<const NK: usize, const NB: usize, const NR: usize, const L: usize>()
-    -> Result<()>
+    fn test_gctr_opt<const NK: usize, const NB: usize, const NR: usize, const L: usize>(
+    ) -> Result<()>
     where
         [(); 4 * (NR + 1)]:,
         [(); NK * NB]:,
@@ -541,8 +541,8 @@ test_gf_mul_opt::<8, 4, 14, 16>()?;
 
         Ok(())
     }
-    fn test_gf_mul_opt<const NK: usize, const NB: usize, const NR: usize, const L: usize>()
-    -> Result<()>
+    fn test_gf_mul_opt<const NK: usize, const NB: usize, const NR: usize, const L: usize>(
+    ) -> Result<()>
     where
         [(); 4 * (NR + 1)]:,
         [(); NK * NB]:,
@@ -599,8 +599,8 @@ test_ghash_opt::<8, 4, 14, 16>()?;
 
         Ok(())
     }
-    fn test_ghash_opt<const NK: usize, const NB: usize, const NR: usize, const L: usize>()
-    -> Result<()>
+    fn test_ghash_opt<const NK: usize, const NB: usize, const NR: usize, const L: usize>(
+    ) -> Result<()>
     where
         [(); 4 * (NR + 1)]:,
         [(); NK * NB]:,

@@ -3,8 +3,6 @@ //!
 //! Constants for the implementation of AES following the specification from
 //! https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197-upd1.pdf.
 
-// pub const NB: usize = 4;
-
 /// supported tag length
 pub const TAG_LEN: usize = 128;
 

@@ -14,7 +14,7 @@ pub const D: usize = 2;
 
 pub use circuit_gcm::AesGcmTarget;
 
-// expose pre-defined configurations (AES 128, 192, 256):
+// expose pre-defined configurations (AES-128, AES-192, AES-256):
 
 pub type AesGcm128Target<const L: usize> = AesGcmTarget<4, 4, 10, L, false>;
 pub const KEY_LEN_128: usize = 4 * 4;

@@ -269,8 +269,8 @@ mod tests {
     use super::*;
 
     use aes_gcm::{
-        Aes128Gcm, Aes256Gcm, Nonce,
         aead::{Aead, KeyInit},
+        Aes128Gcm, Aes256Gcm, Nonce,
     };
     use rand::Rng;
 
@@ -335,8 +335,8 @@ fn test_with_external_lib() -> anyhow::Result<()> {
         test_with_external_lib_op::<4, 4, 10, Aes128Gcm>()?;
         test_with_external_lib_op::<8, 4, 14, Aes256Gcm>()
     }
-    fn test_with_external_lib_op<const NK: usize, const NB: usize, const NR: usize, C>()
-    -> anyhow::Result<()>
+    fn test_with_external_lib_op<const NK: usize, const NB: usize, const NR: usize, C>(
+    ) -> anyhow::Result<()>
     where
         [(); NK * NB]:,
         [(); 4 * (NR + 1)]:,