Skip to content

Commit 850b447

Browse files
JacobBarthelmehJacobBarthelmeh
authored
Merge pull request #540 from anhu/aes_modes_preamble
AES modes extravaganza. Makefile, README and misc. files
2 parents b8e2445 + 6d68018 commit 850b447

5 files changed

Lines changed: 200 additions & 0 deletions

File tree

‎crypto/aes-modes/Makefile‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
CC=gcc
2+
CFLAGS=-Wall
3+
WOLFSSL_INSTALL_DIR=/usr/local
4+
LIBS=-L$(WOLFSSL_INSTALL_DIR)/lib -lwolfssl -lm
5+
6+
# All AES mode examples
7+
EXAMPLES = aes-cbc aes-cfb aes-cfb1 aes-cfb8 aes-ofb aes-ecb aes-ctr \
8+
aes-direct aes-gcm aes-gmac aes-ccm aes-keywrap aes-xts \
9+
aes-siv aes-eax aes-cts
10+
11+
all: $(EXAMPLES)
12+
13+
aes-cbc: aes-cbc.o
14+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
15+
16+
aes-cfb: aes-cfb.o
17+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
18+
19+
aes-cfb1: aes-cfb1.o
20+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
21+
22+
aes-cfb8: aes-cfb8.o
23+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
24+
25+
aes-ofb: aes-ofb.o
26+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
27+
28+
aes-ecb: aes-ecb.o
29+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
30+
31+
aes-ctr: aes-ctr.o
32+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
33+
34+
aes-direct: aes-direct.o
35+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
36+
37+
aes-gcm: aes-gcm.o
38+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
39+
40+
aes-gmac: aes-gmac.o
41+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
42+
43+
aes-ccm: aes-ccm.o
44+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
45+
46+
aes-keywrap: aes-keywrap.o
47+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
48+
49+
aes-xts: aes-xts.o
50+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
51+
52+
aes-siv: aes-siv.o
53+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
54+
55+
aes-eax: aes-eax.o
56+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
57+
58+
aes-cts: aes-cts.o
59+
$(CC) -o $@ $^ $(CFLAGS) $(LIBS)
60+
61+
%.o: %.c
62+
$(CC) -c -o $@ $< $(CFLAGS) -I$(WOLFSSL_INSTALL_DIR)/include
63+
64+
.PHONY: clean
65+
66+
clean:
67+
rm -f *.o $(EXAMPLES) temp_*.bin

‎crypto/aes-modes/README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# AES Mode Examples
2+
3+
This directory contains examples demonstrating all 16 AES modes supported by
4+
wolfSSL's wolfCrypt library. Each example encrypts a file using the one-shot
5+
API and decrypts it using the streaming API (where available).
6+
7+
## Overview
8+
9+
Each example demonstrates:
10+
- One-shot encryption using the mode's encrypt function
11+
- Streaming decryption using Init/Update/Final pattern (if available)
12+
- Proper key/IV/nonce generation and handling
13+
- File I/O for practical usage
14+
15+
## AES Modes
16+
17+
| Mode | File | Streaming Decrypt | Build Flag | Description |
18+
|------|------|-------------------|------------|-------------|
19+
| CBC | aes-cbc.c | No | HAVE_AES_CBC | Cipher Block Chaining |
20+
| CFB | aes-cfb.c | Yes | WOLFSSL_AES_CFB | Cipher Feedback (128-bit) |
21+
| CFB1 | aes-cfb1.c | Yes | WOLFSSL_AES_CFB | Cipher Feedback (1-bit) |
22+
| CFB8 | aes-cfb8.c | Yes | WOLFSSL_AES_CFB | Cipher Feedback (8-bit) |
23+
| OFB | aes-ofb.c | Yes | WOLFSSL_AES_OFB | Output Feedback |
24+
| ECB | aes-ecb.c | No | HAVE_AES_ECB | Electronic Codebook |
25+
| CTR | aes-ctr.c | Yes | WOLFSSL_AES_COUNTER | Counter Mode |
26+
| DIRECT | aes-direct.c | No | WOLFSSL_AES_DIRECT | Raw Block Cipher |
27+
| GCM | aes-gcm.c | Yes* | HAVE_AESGCM | Galois/Counter Mode (AEAD) |
28+
| GMAC | aes-gmac.c | No | HAVE_AESGCM | Galois MAC (auth only) |
29+
| CCM | aes-ccm.c | No | HAVE_AESCCM | Counter with CBC-MAC (AEAD) |
30+
| KEY WRAP | aes-keywrap.c | No | HAVE_AES_KEYWRAP | RFC 3394 Key Wrap |
31+
| XTS | aes-xts.c | Yes* | WOLFSSL_AES_XTS | XEX-based Tweaked-codebook |
32+
| SIV | aes-siv.c | No | WOLFSSL_AES_SIV | Synthetic IV (AEAD) |
33+
| EAX | aes-eax.c | Yes | WOLFSSL_AES_EAX | Encrypt-Authenticate-Translate |
34+
| CTS | aes-cts.c | No* | WOLFSSL_AES_CTS | Ciphertext Stealing |
35+
36+
*GCM streaming requires WOLFSSL_AESGCM_STREAM, XTS streaming requires
37+
WOLFSSL_AESXTS_STREAM, CTS streaming API requires complex internal buffering
38+
and is not demonstrated in this example
39+
40+
## Building
41+
42+
### Prerequisites
43+
44+
wolfSSL must be installed with the required AES modes enabled. To enable all
45+
modes:
46+
47+
```bash
48+
cd /path/to/wolfssl
49+
./autogen.sh
50+
./configure --enable-aescbc \
51+
--enable-aescfb \
52+
--enable-aesofb \
53+
--enable-aesecb \
54+
--enable-aesctr \
55+
--enable-aesgcm \
56+
--enable-aesccm \
57+
--enable-aeskeywrap \
58+
--enable-xts \
59+
--enable-aessiv \
60+
--enable-aeseax \
61+
--enable-aescts \
62+
--enable-aesgcm-stream \
63+
--enable-aesxts-stream
64+
make
65+
sudo make install
66+
```
67+
68+
### Building the Examples
69+
70+
```bash
71+
make
72+
```
73+
74+
## Usage
75+
76+
All examples follow the same pattern:
77+
78+
```bash
79+
./<example> <input_file> <output_file>
80+
```
81+
82+
The example will:
83+
1. Read the input file
84+
2. Encrypt it using the one-shot API
85+
3. Write encrypted data to a temporary file
86+
4. Decrypt using streaming API (or one-shot if no streaming available)
87+
5. Write decrypted data to the output file
88+
6. Clean up temporary files
89+
90+
### Example
91+
92+
```bash
93+
# Create a test file
94+
echo "Hello, wolfSSL AES modes!" > test.txt
95+
96+
# Test AES-GCM
97+
./aes-gcm test.txt output.txt
98+
cat output.txt
99+
100+
# Test AES-CTR
101+
./aes-ctr test.txt output.txt
102+
cat output.txt
103+
```
104+
105+
## Notes
106+
107+
### Security Considerations
108+
109+
- These examples use fixed keys for demonstration purposes only
110+
- In production, use proper key management and secure random key generation
111+
- ECB mode is not recommended for most use cases due to security weaknesses
112+
- GMAC provides authentication only (no encryption)
113+
114+
### Streaming vs One-Shot
115+
116+
Modes with streaming support allow processing data in chunks, which is useful
117+
for:
118+
- Large files that don't fit in memory
119+
- Network streams where data arrives incrementally
120+
- Memory-constrained environments
121+
122+
Modes without streaming support require the entire plaintext/ciphertext to be
123+
available before processing.
124+
125+
### Minimum Input Sizes
126+
127+
Some modes have minimum input size requirements:
128+
- XTS: Minimum 16 bytes
129+
- CTS: Minimum 16 bytes
130+
- KEY WRAP: Input must be multiple of 8 bytes (padding applied automatically)

‎crypto/aes-modes/testfile.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
This is a test file for AES encryption. It contains multiple lines of text to ensure we test with data larger than a single block.

‎crypto/aes-modes/testfile_direct.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Single block test

‎crypto/aes-modes/testfile_keywrap.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
12345678901234567890123456789012

0 commit comments

Comments
 (0)