### Configuration and Usage Notes

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Notes on configuring key-size, enabling modes, C++ usage, and security considerations.

```APIDOC
## Configuration and Usage Notes

### Key Size

The default key-size is 128 bits. You can override this to 192 or 256 bits by defining the symbols `AES192` or `AES256` in `aes.h` before compiling.

### Enabling Modes of Operation

You can choose to use any or all of the following modes by defining the corresponding symbols in `aes.h`:

*   `CBC`: Enable Cipher Block Chaining mode.
*   `CTR`: Enable Counter mode.
*   `ECB`: Enable Electronic Codebook mode.

If no mode is defined, the library may not compile or function as expected. Consult the comments in `aes.h` for clarification.

### C++ Usage

For C++ projects, include `aes.hpp` instead of `aes.h`.

*   `#include "aes.hpp"`

### Padding

No padding is provided by this library. For CBC and ECB modes, all buffers processed must be exact multiples of 16 bytes. PKCS7 padding is recommended if padding is required.

### Security Considerations

*   **ECB Mode**: ECB mode is generally considered insecure for most applications due to its deterministic nature. Use with caution and understand its limitations.
*   **Error Handling**: This library lacks built-in error checking or protection against out-of-bounds memory access errors that could result from malicious input.
*   **Resource Usage**: The module is designed for small code size and low memory footprint, making it suitable for embedded systems. It uses less than 200 bytes of RAM and 1-2 KB of ROM when compiled for ARM (depending on enabled modes).

### Verification

This implementation has been verified against the data in NIST Special Publication 800-38A, Appendix F.
```

--------------------------------

### AES Initialization

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Functions to initialize the AES context with a key, and optionally an Initialization Vector (IV).

```APIDOC
## AES Initialization Functions

### Initialize AES Context

Initializes the AES context structure with the provided key.

*   **`void AES_init_ctx(struct AES_ctx* ctx, const uint8_t* key);`**
    *   `ctx`: Pointer to the `AES_ctx` structure to be initialized.
    *   `key`: Pointer to the 128-bit key.

### Initialize AES Context with IV

Initializes the AES context structure with the provided key and Initialization Vector (IV).

*   **`void AES_init_ctx_iv(struct AES_ctx* ctx, const uint8_t* key, const uint8_t* iv);`**
    *   `ctx`: Pointer to the `AES_ctx` structure to be initialized.
    *   `key`: Pointer to the 128-bit key.
    *   `iv`: Pointer to the Initialization Vector.

### Set IV

Resets the Initialization Vector (IV) for the AES context. This is useful for resuming encryption/decryption at a random point, particularly in CTR mode.

*   **`void AES_ctx_set_iv(struct AES_ctx* ctx, const uint8_t* iv);`**
    *   `ctx`: Pointer to the `AES_ctx` structure.
    *   `iv`: Pointer to the new Initialization Vector.
```

--------------------------------

### C++ Integration with AES Wrapper

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Demonstrates how to integrate the C AES implementation into C++ projects using the provided C++ wrapper header ('aes.hpp'). This wrapper ensures correct `extern "C"` linkage for the C functions, allowing seamless usage within C++ code.

```cpp
#include "aes.hpp"

int main() {
    uint8_t key[16] = { /* key data */ };
    uint8_t data[16] = { /* plaintext */ };

    struct AES_ctx ctx;
    AES_init_ctx(&ctx, key);
    AES_ECB_encrypt(&ctx, data);

    return 0;
}

```

--------------------------------

### C: Complete AES CBC Encryption and Decryption Workflow

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

This C code snippet demonstrates a full encryption and decryption cycle using Tiny AES-c in Cipher Block Chaining (CBC) mode. It initializes the AES context with a key and IV, encrypts a plaintext buffer, then decrypts the resulting ciphertext, and finally verifies that the decrypted data matches the original plaintext. It requires the aes.h header and aes.c implementation, along with standard C libraries.

```c
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "aes.h"

int main(void) {
    // 128-bit key
    uint8_t key[16] = {
        0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
        0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
    };

    // Initialization vector
    uint8_t iv[16] = {
        0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
        0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f
    };

    // Plaintext (must be multiple of 16 for CBC)
    uint8_t plaintext[64] = {
        0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
        0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a,
        0xae, 0x2d, 0x8a, 0x57, 0x1e, 0x03, 0xac, 0x9c,
        0x9e, 0xb7, 0x6f, 0xac, 0x45, 0xaf, 0x8e, 0x51,
        0x30, 0xc8, 0x1c, 0x46, 0xa3, 0x5c, 0xe4, 0x11,
        0xe5, 0xfb, 0xc1, 0x19, 0x1a, 0x0a, 0x52, 0xef,
        0xf6, 0x9f, 0x24, 0x45, 0xdf, 0x4f, 0x9b, 0x17,
        0xad, 0x2b, 0x41, 0x7b, 0xe6, 0x6c, 0x37, 0x10
    };

    // Copy for decryption test
    uint8_t ciphertext[64];

    // Initialize context with key and IV
    struct AES_ctx ctx;
    AES_init_ctx_iv(&ctx, key, iv);

    // Encrypt
    memcpy(ciphertext, plaintext, 64);
    AES_CBC_encrypt_buffer(&ctx, ciphertext, 64);

    printf("Encryption complete\n");

    // Reset IV for decryption
    AES_ctx_set_iv(&ctx, iv);

    // Decrypt
    AES_CBC_decrypt_buffer(&ctx, ciphertext, 64);

    // Verify
    if (memcmp(plaintext, ciphertext, 64) == 0) {
        printf("Decryption successful - data matches\n");
        return 0;
    } else {
        printf("Decryption failed\n");
        return 1;
    }
}

```

--------------------------------

### AES API Initialization and Context Management in C

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Initializes the AES context with a key and optionally an Initialization Vector (IV). Supports setting the IV at a later point. Uses C99 `<stdint.h>` style types. No external dependencies beyond standard C types.

```C
/* Initialize context calling one of: */
void AES_init_ctx(struct AES_ctx* ctx, const uint8_t* key);
void AES_init_ctx_iv(struct AES_ctx* ctx, const uint8_t* key, const uint8_t* iv);

/* ... or reset IV at random point: */
void AES_ctx_set_iv(struct AES_ctx* ctx, const uint8_t* iv);
```

--------------------------------

### GCC Size Output for Tiny AES CTR Mode on ARM

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Demonstrates the code size impact of compiling the Tiny AES library with only CTR mode enabled for an ARM target using GCC. Shows the output of the `size` command, indicating text, data, and BSS segment sizes.

```Shell
$ arm-none-eabi-gcc -Os -DCBC=0 -DECB=0 -DCTR=1 -c aes.c
$ size aes.o
   text    data     bss     dec     hex filename
   1171       0       0    1171     493 aes.o
```

--------------------------------

### Initialize AES Context for ECB Mode (C)

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Initializes an AES context for Electronic Codebook (ECB) mode operations using a provided 16-byte key. This context is then ready for encryption or decryption without an initialization vector. It requires the 'aes.h' header and 'stdint.h'.

```c
#include <stdint.h>
#include "aes.h"

// AES-128 example (16-byte key)
uint8_t key[16] = {
    0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
    0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

struct AES_ctx ctx;
AES_init_ctx(&ctx, key);

// Context is now ready for ECB encryption/decryption
```

--------------------------------

### Initialize AES Context with IV for CBC/CTR Mode (C)

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Initializes an AES context for Cipher Block Chaining (CBC) or Counter (CTR) mode operations using a key and a 16-byte initialization vector (IV). The IV is crucial for security and should not be reused with the same key. Requires 'aes.h' and 'stdint.h'.

```c
#include <stdint.h>
#include "aes.h"

// AES-128 key (16 bytes)
uint8_t key[16] = {
    0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
    0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

// Initialization vector (16 bytes)
uint8_t iv[16] = {
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f
};

struct AES_ctx ctx;
AES_init_ctx_iv(&ctx, key, iv);

// Context is now ready for CBC/CTR operations
```

--------------------------------

### GCC Size Output for Tiny AES CTR Mode on ARM Thumb

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Illustrates the reduced code size when compiling the Tiny AES library with CTR mode enabled for the ARM Thumb instruction set. This optimization further minimizes the binary size, as shown by the `size` command output.

```Shell
$ arm-none-eabi-gcc -Os -mthumb -DCBC=0 -DECB=0 -DCTR=1 -c aes.c
$ size aes.o
   text    data     bss     dec     hex filename
    903       0       0     903     387 aes.o
```

--------------------------------

### C++ Header Inclusion for Tiny AES in C

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Provides instructions for C++ users on how to include the AES library. Instead of the standard C header 'aes.h', C++ users should include 'aes.hpp' to ensure compatibility and proper C++ linkage.

```C++
// C++ users should include aes.hpp instead of aes.h
#include "aes.hpp"
```

--------------------------------

### AES Encryption and Decryption

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Functions for encrypting and decrypting data using ECB, CBC, and CTR modes.

```APIDOC
## AES Encryption and Decryption Functions

### AES ECB Mode

Encrypts or decrypts a single 16-byte block of data using AES in ECB mode.

*   **`void AES_ECB_encrypt(const struct AES_ctx* ctx, uint8_t* buf);`**
    *   `ctx`: Pointer to the initialized `AES_ctx` structure.
    *   `buf`: Pointer to a 16-byte buffer to be encrypted in-place.

*   **`void AES_ECB_decrypt(const struct AES_ctx* ctx, uint8_t* buf);`**
    *   `ctx`: Pointer to the initialized `AES_ctx` structure.
    *   `buf`: Pointer to a 16-byte buffer to be decrypted in-place.

**Note:** ECB mode is not implemented in streaming mode and is considered unsafe for most uses. For ECB, call these functions for every 16-byte block.

### AES CBC Mode

Encrypts or decrypts a buffer of data using AES in CBC mode.

*   **`void AES_CBC_encrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);`**
    *   `ctx`: Pointer to the initialized `AES_ctx` structure.
    *   `buf`: Pointer to the buffer containing data to be encrypted.
    *   `length`: The length of the buffer in bytes. Must be a multiple of 16.

*   **`void AES_CBC_decrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);`**
    *   `ctx`: Pointer to the initialized `AES_ctx` structure.
    *   `buf`: Pointer to the buffer containing data to be decrypted.
    *   `length`: The length of the buffer in bytes. Must be a multiple of 16.

**Note:** Buffers must be multiples of 16 bytes. Padding is not provided.

### AES CTR Mode

Encrypts or decrypts a buffer of data using AES in CTR mode. The same function is used for both encryption and decryption.

*   **`void AES_CTR_xcrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);`**
    *   `ctx`: Pointer to the initialized `AES_ctx` structure.
    *   `buf`: Pointer to the buffer containing data to be encrypted or decrypted.
    *   `length`: The length of the buffer in bytes.
```

--------------------------------

### AES Configuration Options via Preprocessor Definitions in C

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Allows customization of AES key size and enabled modes of operation using preprocessor macros. Key size can be set to 192 or 256 bits by defining AES192 or AES256, respectively. Modes (CBC, CTR, ECB) can be enabled or disabled by defining corresponding symbols in `aes.h`.

```C
// Example: Define in aes.h or via compiler flags
// #define AES192 // For 192-bit keys
// #define AES256 // For 256-bit keys
// #define CBC=1 // Enable CBC mode
// #define CTR=1 // Enable CTR mode
// #define ECB=1 // Enable ECB mode
```

--------------------------------

### Configure AES Key Size (Compile-Time) in C

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Allows selection of AES key size (128, 192, or 256 bits) by defining preprocessor macros before including the 'aes.h' header. Only one key size can be active at a time. This configuration can also be set via compiler flags.

```c
// In your source file before #include "aes.h":
#define AES256 1  // Enable AES-256 (32-byte keys)
// OR
#define AES192 1  // Enable AES-192 (24-byte keys)
// OR use default AES128 (16-byte keys)

#include "aes.h"

// Or via compiler flags:
// gcc -DAES256=1 -c aes.c
// gcc -DAES192=1 -c aes.c

```

--------------------------------

### CBC Mode Encryption in C

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Encrypts a buffer of data using AES in CBC mode. Requires the buffer length to be a multiple of 16 bytes. It's recommended to use PKCS7 padding for data that isn't block-aligned. The IV in the context is updated after encryption.

```c
#include <stdint.h>
#include <string.h>
#include "aes.h"

// Setup
uint8_t key[16] = {
    0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
    0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

uint8_t iv[16] = {
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f
};

// 64 bytes of plaintext (must be multiple of 16)
uint8_t buffer[64] = {
    0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
    0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a,
    // ... more data ...
};

struct AES_ctx ctx;
AES_init_ctx_iv(&ctx, key, iv);

// Encrypt entire buffer in-place
AES_CBC_encrypt_buffer(&ctx, buffer, 64);

// buffer now contains encrypted data
// IV in ctx is updated to last ciphertext block

```

--------------------------------

### CTR Mode Encryption/Decryption in C

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Performs AES CTR mode encryption or decryption; both operations use the same function. This mode works with any buffer length, unlike CBC mode. It is crucial that the IV/nonce is never reused with the same key to maintain security.

```c
#include <stdint.h>
#include <string.h>
#include "aes.h"

// Setup
uint8_t key[16] = {
    0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
    0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

uint8_t nonce[16] = {
    0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
    0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff
};

// Buffer can be any length (not required to be multiple of 16)
uint8_t buffer[64] = {
    0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
    0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a,
    // ... data to encrypt ...
};

struct AES_ctx ctx;
AES_init_ctx_iv(&ctx, key, nonce);

// Encrypt (or decrypt - same function)
AES_CTR_xcrypt_buffer(&ctx, buffer, 64);

// buffer now contains encrypted data
// Call again with ciphertext to decrypt

```

--------------------------------

### Set or Reset AES Context IV (C)

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Updates the initialization vector (IV) of an existing AES context. This function is useful for changing the IV between encryption/decryption operations without re-initializing the entire context. It requires 'aes.h' and 'stdint.h'.

```c
#include <stdint.h>
#include "aes.h"

struct AES_ctx ctx;
uint8_t key[16] = { /* key bytes */ };
uint8_t iv1[16] = { /* first IV */ };
uint8_t iv2[16] = { /* second IV */ };

// Initialize with first IV
AES_init_ctx_iv(&ctx, key, iv1);

// Perform encryption...

// Change to new IV for next operation
AES_ctx_set_iv(&ctx, iv2);

// Continue with new IV
```

--------------------------------

### AES CBC Encryption and Decryption Buffer Operations in C

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Handles Cipher Block Chaining (CBC) mode encryption and decryption for buffers of data. Requires buffers to be multiples of 16 bytes due to the absence of padding. The `length` parameter specifies the buffer size in bytes.

```C
void AES_CBC_encrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);
void AES_CBC_decrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);
```

--------------------------------

### AES ECB Encryption and Decryption in C

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Provides functions for Electronic Codebook (ECB) mode encryption and decryption. Buffers must be multiples of 16 bytes as no padding is provided. ECB is not implemented in streaming mode and should be called for every 16-byte block.

```C
/* Then start encrypting and decrypting with the functions below: */
void AES_ECB_encrypt(const struct AES_ctx* ctx, uint8_t* buf);
void AES_ECB_decrypt(const struct AES_ctx* ctx, uint8_t* buf);
```

--------------------------------

### Enable/Disable AES Modes (Compile-Time) in C

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Enables or disables specific AES encryption modes (CBC, ECB, CTR) at compile time using preprocessor macros. This feature helps reduce the final code size by excluding unused modes. Configuration can be done before including the header or via compiler flags.

```c
// Enable only CTR mode (smallest footprint)
#define CBC 0
#define ECB 0
#define CTR 1

#include "aes.h"

// Or via compiler flags for minimal code size:
// gcc -Os -DCBC=0 -DECB=0 -DCTR=1 -c aes.c
// Resulting code: ~900 bytes on ARM Thumb, ~1171 bytes on ARM

```

--------------------------------

### AES CTR Encrypt/Decrypt Buffer Operation in C

Source: https://github.com/kokke/tiny-aes-c/blob/master/README.md

Performs Counter (CTR) mode encryption and decryption using the same function. This mode is stream-based. The `length` parameter indicates the buffer size in bytes. CTR mode requires an IV to be set during context initialization or via `AES_ctx_set_iv`.

```C
/* Same function for encrypting as for decrypting in CTR mode */
void AES_CTR_xcrypt_buffer(struct AES_ctx* ctx, uint8_t* buf, size_t length);
```

--------------------------------

### AES-128 ECB Mode Encryption (C)

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Encrypts a single 16-byte block of data using AES in ECB mode. Note that ECB mode is generally not recommended due to its deterministic nature. The function modifies the input buffer in-place. Requires 'aes.h', 'stdint.h', and 'string.h'.

```c
#include <stdint.h>
#include <string.h>
#include "aes.h"

// Setup
uint8_t key[16] = {
    0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
    0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

uint8_t plaintext[16] = {
    0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
    0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a
};

struct AES_ctx ctx;
AES_init_ctx(&ctx, key);

// Encrypt in-place
AES_ECB_encrypt(&ctx, plaintext);

// plaintext now contains encrypted data:
// 3ad77bb40d7a3660a89ecaf32466ef97
```

--------------------------------

### AES-128 ECB Mode Decryption (C)

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Decrypts a single 16-byte block of data using AES in ECB mode. The function modifies the input buffer in-place, transforming ciphertext back to plaintext. Requires 'aes.h' and 'stdint.h'.

```c
#include <stdint.h>
#include "aes.h"

// Setup
uint8_t key[16] = {
    0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
    0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

uint8_t ciphertext[16] = {
    0x3a, 0xd7, 0x7b, 0xb4, 0x0d, 0x7a, 0x36, 0x60,
    0xa8, 0x9e, 0xca, 0xf3, 0x24, 0x66, 0xef, 0x97
};

struct AES_ctx ctx;
AES_init_ctx(&ctx, key);

// Decrypt in-place
AES_ECB_decrypt(&ctx, ciphertext);

// ciphertext now contains decrypted plaintext:
// 6bc1bee22e409f96e93d7e117393172a
```

--------------------------------

### CBC Mode Decryption in C

Source: https://context7.com/kokke/tiny-aes-c/llms.txt

Decrypts a buffer of data using AES in CBC mode. Requires the buffer length to be a multiple of 16 bytes. The IV is automatically updated for chained operations. The input buffer is modified in-place to contain the decrypted plaintext.

```c
#include <stdint.h>
#include <string.h>
#include "aes.h"

// Setup
uint8_t key[16] = {
    0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
    0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

uint8_t iv[16] = {
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f
};

// 64 bytes of ciphertext
uint8_t buffer[64] = {
    0x76, 0x49, 0xab, 0xac, 0x81, 0x19, 0xb2, 0x46,
    0xce, 0xe9, 0x8e, 0x9b, 0x12, 0xe9, 0x19, 0x7d,
    // ... more encrypted data ...
};

struct AES_ctx ctx;
AES_init_ctx_iv(&ctx, key, iv);

// Decrypt entire buffer in-place
AES_CBC_decrypt_buffer(&ctx, buffer, 64);

// buffer now contains decrypted plaintext

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.