Implementation:Duckdb Duckdb Mbedtls AES

Knowledge Sources	Duckdb_Duckdb mbedTLS
Domains	Cryptography, Third_Party
Last Updated	2026-02-07 12:00 GMT

Overview

The mbedTLS AES module provides a FIPS-197 compliant implementation of the Advanced Encryption Standard (AES) symmetric block cipher, supporting 128-bit, 192-bit, and 256-bit key lengths with ECB, CBC, CFB, OFB, CTR, and XTS block cipher modes.

Description

This module implements the AES block cipher as specified in FIPS Publication 197. AES is a symmetric-key algorithm that operates on fixed 128-bit (16-byte) data blocks. The implementation supports three key sizes: 128, 192, and 256 bits, each corresponding to 10, 12, and 14 rounds of transformation respectively.

The core data structure is mbedtls_aes_context, which holds the number of rounds (nr), an offset for alignment (rk_offset), and a buffer (buf) that stores the expanded round keys. For AES-128-only builds, the buffer is sized at 44 32-bit words; otherwise it is 68 words to accommodate 256-bit key expansion plus alignment padding.

The implementation includes:

• S-box based encryption and decryption using precomputed forward and reverse substitution tables (FSb, RSb)
• Hardware acceleration support via AES-NI (x86/x64), ARMv8-A Crypto Extensions (AESCE), and VIA Padlock
• Multiple block cipher modes: ECB (single block), CBC (chained blocks with IV), CFB128 (cipher feedback), OFB (output feedback), CTR (counter mode), and XTS (tweakable encryption for storage)

The XTS mode uses a separate context type mbedtls_aes_xts_context containing two AES contexts: one for block encryption/decryption and one for tweak computation, as specified by NIST SP 800-38E and IEEE P1619.

Usage

DuckDB uses the AES module primarily through the higher-level cipher abstraction layer. AES encryption is employed for:

• Extension signing and verification: AES-based operations used in the cryptographic pipeline for verifying the integrity of DuckDB extensions
• HTTPS transport encryption: The httpfs extension uses TLS which relies on AES ciphers (AES-128-GCM, AES-256-GCM) for secure data transfer
• Authenticated encryption: AES serves as the underlying block cipher for GCM and CCM authenticated encryption modes used throughout DuckDB's TLS stack

Code Reference

Source Location

• Repository: Duckdb_Duckdb
• Files:
  • third_party/mbedtls/include/mbedtls/aes.h -- AES API header (631 lines)
  • third_party/mbedtls/library/aes.cpp -- AES implementation (2293 lines)

Signature

// Context lifecycle
void mbedtls_aes_init(mbedtls_aes_context *ctx);
void mbedtls_aes_free(mbedtls_aes_context *ctx);

// Key setup
int mbedtls_aes_setkey_enc(mbedtls_aes_context *ctx,
                           const unsigned char *key,
                           unsigned int keybits);
int mbedtls_aes_setkey_dec(mbedtls_aes_context *ctx,
                           const unsigned char *key,
                           unsigned int keybits);

// Single-block ECB mode
int mbedtls_aes_crypt_ecb(mbedtls_aes_context *ctx,
                          int mode,
                          const unsigned char input[16],
                          unsigned char output[16]);

// CBC mode (full blocks)
int mbedtls_aes_crypt_cbc(mbedtls_aes_context *ctx,
                          int mode,
                          size_t length,
                          unsigned char iv[16],
                          const unsigned char *input,
                          unsigned char *output);

// XTS mode context lifecycle and key setup
void mbedtls_aes_xts_init(mbedtls_aes_xts_context *ctx);
void mbedtls_aes_xts_free(mbedtls_aes_xts_context *ctx);
int mbedtls_aes_xts_setkey_enc(mbedtls_aes_xts_context *ctx,
                               const unsigned char *key,
                               unsigned int keybits);
int mbedtls_aes_xts_setkey_dec(mbedtls_aes_xts_context *ctx,
                               const unsigned char *key,
                               unsigned int keybits);

Import

#include "mbedtls/aes.h"

I/O Contract

Inputs

Name	Type	Required	Description
ctx	mbedtls_aes_context *	Yes	Initialized AES context bound to a key
key	const unsigned char *	Yes	Encryption or decryption key buffer
keybits	unsigned int	Yes	Key size in bits: 128, 192, or 256
mode	int	Yes	Operation: MBEDTLS_AES_ENCRYPT (1) or MBEDTLS_AES_DECRYPT (0)
input	const unsigned char *	Yes	Input data buffer (must be at least 16 bytes for ECB)
iv	unsigned char[16]	CBC only	Initialization vector, updated in place after each call
length	size_t	CBC only	Input data length in bytes (must be a multiple of 16)

Outputs

Name	Type	Description
return value	int	0 on success; MBEDTLS_ERR_AES_INVALID_KEY_LENGTH (-0x0020) or MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH (-0x0022) on failure
output	unsigned char *	Buffer receiving encrypted or decrypted data (same size as input)
iv	unsigned char[16]	Updated initialization vector (CBC mode) for streaming use

Usage Examples

// AES-256-CBC encryption example
mbedtls_aes_context aes;
mbedtls_aes_init(&aes);

unsigned char key[32] = { /* 256-bit key */ };
unsigned char iv[16]  = { /* initialization vector */ };
unsigned char input[64]  = { /* plaintext, multiple of 16 bytes */ };
unsigned char output[64];

// Set encryption key
int ret = mbedtls_aes_setkey_enc(&aes, key, 256);
if (ret != 0) { /* handle error */ }

// Encrypt using CBC mode
ret = mbedtls_aes_crypt_cbc(&aes, MBEDTLS_AES_ENCRYPT,
                            sizeof(input), iv, input, output);
if (ret != 0) { /* handle error */ }

mbedtls_aes_free(&aes);

Related Pages

• Principle:Duckdb_Duckdb_TLS_Cryptography