Implementation:Duckdb Duckdb Mbedtls Cipher

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

Overview

The mbedTLS Cipher module provides a generic abstraction interface for symmetric cipher operations, offering a unified API across all supported block ciphers, cipher modes, and padding schemes.

Description

This module serves as the primary abstraction layer for symmetric encryption in mbedTLS. It wraps multiple underlying cipher implementations (AES, Camellia, ARIA, DES, ChaCha20) behind a common interface, allowing cipher-agnostic code to perform encryption and decryption.

The module defines several key enumerations:

• mbedtls_cipher_id_t: Base cipher identifiers -- MBEDTLS_CIPHER_ID_AES, MBEDTLS_CIPHER_ID_DES, MBEDTLS_CIPHER_ID_3DES, MBEDTLS_CIPHER_ID_CAMELLIA, MBEDTLS_CIPHER_ID_ARIA, MBEDTLS_CIPHER_ID_CHACHA20
• mbedtls_cipher_type_t: Specific cipher+mode combinations (over 60 entries) such as MBEDTLS_CIPHER_AES_256_GCM, MBEDTLS_CIPHER_AES_128_CBC, MBEDTLS_CIPHER_CHACHA20_POLY1305
• mbedtls_cipher_mode_t: Block cipher modes -- ECB, CBC, CFB, OFB, CTR, GCM, CCM, XTS, KW, KWP, Stream, ChaCha-Poly
• mbedtls_cipher_padding_t: Padding types -- PKCS7, ISO/IEC 7816-4, ANSI X.923, Zero, None

The mbedtls_cipher_info_t structure uses bit fields for compact storage, holding the cipher name, block size, IV size, key bit length, mode, type, and flags. The mbedtls_cipher_context_t holds the runtime state for an active cipher operation.

The implementation is split across three files:

• cipher.cpp: Core cipher API -- mbedtls_cipher_list(), context setup, key binding, IV setting, update/finish for multi-part operations, and single-shot mbedtls_cipher_crypt()
• cipher_wrap.cpp: Concrete wrappers that bridge the generic cipher interface to specific implementations (AES, DES, Camellia, ARIA, ChaCha20), plus GCM, CCM, and NIST Key Wrap mode adapters

Usage

DuckDB uses the cipher abstraction layer as the central interface for:

• TLS record encryption/decryption: The cipher module provides the uniform API used during TLS record processing in the httpfs extension
• AEAD operations: GCM and CCM authenticated encryption modes are accessed through the cipher layer for TLS 1.2 and TLS 1.3 cipher suites
• Cipher suite negotiation: The cipher info lookup functions (mbedtls_cipher_info_from_type, mbedtls_cipher_info_from_string) are used during TLS handshake to select appropriate ciphers

Code Reference

Source Location

• Repository: Duckdb_Duckdb
• Files:
  • third_party/mbedtls/include/mbedtls/cipher.h -- Cipher abstraction API header (1173 lines)
  • third_party/mbedtls/library/cipher.cpp -- Cipher implementation (1689 lines)
  • third_party/mbedtls/library/cipher_wrap.cpp -- Cipher wrappers (2482 lines)

Signature

// Cipher information lookup
const int *mbedtls_cipher_list(void);
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type(
    mbedtls_cipher_type_t cipher_type);
const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string(
    const char *cipher_name);

// Context lifecycle
void mbedtls_cipher_init(mbedtls_cipher_context_t *ctx);
void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx);
int mbedtls_cipher_setup(mbedtls_cipher_context_t *ctx,
                         const mbedtls_cipher_info_t *cipher_info);

// Key and IV binding
int mbedtls_cipher_setkey(mbedtls_cipher_context_t *ctx,
                          const unsigned char *key,
                          int key_bitlen,
                          mbedtls_operation_t operation);
int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx,
                          const unsigned char *iv, size_t iv_len);

// Single-shot encryption/decryption
int mbedtls_cipher_crypt(mbedtls_cipher_context_t *ctx,
                         const unsigned char *iv, size_t iv_len,
                         const unsigned char *input, size_t ilen,
                         unsigned char *output, size_t *olen);

Import

#include "mbedtls/cipher.h"

I/O Contract

Inputs

Name	Type	Required	Description
ctx	mbedtls_cipher_context_t *	Yes	Cipher context, must be initialized and set up with a cipher info
cipher_info	const mbedtls_cipher_info_t *	For setup	Cipher information structure from lookup functions
key	const unsigned char *	Yes	Encryption/decryption key
key_bitlen	int	Yes	Key length in bits (e.g., 128, 192, 256)
operation	mbedtls_operation_t	Yes	MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT
iv	const unsigned char *	Mode-dependent	Initialization vector (up to MBEDTLS_MAX_IV_LENGTH = 16 bytes)
input	const unsigned char *	Yes	Input data buffer
ilen	size_t	Yes	Input data length in bytes

Outputs

Name	Type	Description
return value	int	0 on success; error codes include MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA (-0x6100), MBEDTLS_ERR_CIPHER_ALLOC_FAILED (-0x6180), MBEDTLS_ERR_CIPHER_AUTH_FAILED (-0x6300)
output	unsigned char *	Buffer receiving encrypted or decrypted data
olen	size_t *	Number of bytes written to output buffer

Usage Examples

// AES-256-CBC encryption via the cipher abstraction
mbedtls_cipher_context_t ctx;
mbedtls_cipher_init(&ctx);

const mbedtls_cipher_info_t *info =
    mbedtls_cipher_info_from_type(MBEDTLS_CIPHER_AES_256_CBC);
mbedtls_cipher_setup(&ctx, info);

unsigned char key[32] = { /* 256-bit key */ };
unsigned char iv[16]  = { /* initialization vector */ };

mbedtls_cipher_setkey(&ctx, key, 256, MBEDTLS_ENCRYPT);
mbedtls_cipher_set_iv(&ctx, iv, 16);

unsigned char input[64]  = { /* plaintext */ };
unsigned char output[80]; // extra space for padding
size_t olen;

int ret = mbedtls_cipher_crypt(&ctx, iv, 16,
                               input, sizeof(input),
                               output, &olen);
if (ret != 0) { /* handle error */ }

mbedtls_cipher_free(&ctx);

Related Pages

• Principle:Duckdb_Duckdb_TLS_Cryptography