Example Path: examples/aes

AES Encryption Example

Overview

This example demonstrates how to use NetBurner's built-in AES library to encrypt and decrypt a 16-byte block of data with a 128-bit key. It also runs a self-test that verifies the AES implementation against NIST test vectors for 128-, 192-, and 256-bit keys in ECB mode.

AES (Advanced Encryption Standard) is a symmetric block cipher that operates on fixed 16-byte blocks. The same key is used for both encryption and decryption, so the sender and receiver must have a way to share the key securely before communicating.

What This Example Does

Runs aes_self_test() – a diagnostic that encrypts and decrypts a known buffer 10,000 times for each of AES-128, AES-192, and AES-256, then compares the output against NIST test vectors. This is a sanity check on the library, not something your production code needs to do.
Creates a 128-bit AES context from the key string "The Decode Key..".
Encrypts the 16-byte plaintext "The Plain Text.." into a ciphertext buffer.
Decrypts that ciphertext back into a plaintext buffer.
Prints both buffers in hex using ShowData() so you can verify the round-trip succeeded.

Key API Calls

These are defined in <aes.h>, which is part of the NetBurner crypto library:

Call	Purpose
`aes_set_key(&ctx, key, bits)`	Initialize an `aes_context` from a key (128, 192, or 256 bits).
`aes_encrypt(&ctx, in, out)`	Encrypt one 16-byte block.
`aes_decrypt(&ctx, in, out)`	Decrypt one 16-byte block.

The bits parameter to aes_set_key() is the key length in bits (not bytes), so a 16-byte key passes 16 * 8 = 128.

Important Notes

Block size is fixed at 16 bytes. If your plaintext is longer than 16 bytes, you must break it into 16-byte chunks, encrypt each one, and reassemble the ciphertext on the other side. If it's shorter, you must pad it to 16 bytes before encryption.
This example uses ECB mode (Electronic Codebook), which encrypts each block independently. ECB is simple but leaks information when the same plaintext block appears twice. For real applications, prefer CBC, CTR, or GCM mode with a fresh IV per message.
The key and plaintext are hard-coded for demonstration only. In production, never compile keys into firmware – derive them at runtime from a secure source (key store, provisioning flow, key exchange protocol, etc.).

Expected Serial Output

AES test program
  AES-ECB-128 (enc): passed
  AES-ECB-128 (dec): passed
  AES-ECB-192 (enc): passed
  AES-ECB-192 (dec): passed
  AES-ECB-256 (enc): passed
  AES-ECB-256 (dec): passed
 
The encoded result
<16 bytes of ciphertext, shown as hex>
The decoded result
54 68 65 20 50 6C 61 69 6E 20 54 65 78 74 2E 2E    The Plain Text..
Test complete

The decoded result matches the original plaintext byte-for-byte, confirming that the encrypt/decrypt round-trip works.

Project Structure

aes/
    |
    +-- src/
    |     |
    |     +-- main.cpp          Self-test and single-block encrypt/decrypt demo
    |
    +-- makefile                Build configuration
    +-- ReadMe.txt              This file