Implementation:Duckdb Duckdb Mbedtls GCM CCM

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

Overview

The mbedTLS GCM/CCM module implements Galois/Counter Mode (GCM) and Counter with CBC-MAC (CCM) authenticated encryption modes for 128-bit block ciphers, providing both confidentiality and integrity protection.

Description

This module provides two AEAD (Authenticated Encryption with Associated Data) modes:

GCM (Galois/Counter Mode) -- defined by NIST SP 800-38D:

• Combines Counter mode encryption with Galois field multiplication for authentication
• The mbedtls_gcm_context stores the underlying block cipher context, a precomputed hash table H (16 or 256 entries of 128-bit values), running lengths, working buffers, and an acceleration flag
• Supports four acceleration backends: small lookup table (MBEDTLS_GCM_ACC_SMALLTABLE), large lookup table (MBEDTLS_GCM_ACC_LARGETABLE), AES-NI with CLMUL (MBEDTLS_GCM_ACC_AESNI), and ARMv8-A Crypto Extensions (MBEDTLS_GCM_ACC_AESCE)
• The implementation uses Shoup's method with 4-bit tables as described in the GCM specification for efficient GHASH computation

CCM (Counter with CBC-MAC) -- defined by NIST SP 800-38C and RFC 3610:

• Combines Counter mode encryption with CBC-MAC authentication
• The mbedtls_ccm_context stores working buffers Y (CBC-MAC state) and CTR (counter), plaintext/additional data lengths, tag length, and the underlying cipher context
• Supports four operation modes: MBEDTLS_CCM_ENCRYPT, MBEDTLS_CCM_DECRYPT, MBEDTLS_CCM_STAR_ENCRYPT, and MBEDTLS_CCM_STAR_DECRYPT (CCM* variant per IEEE 802.15.4)
• Nonce length must be between 7 and 13 bytes; tag length must be 4, 6, 8, 10, 12, 14, or 16 bytes

Both modes support single-shot operations (encrypt-and-tag / authenticate-and-decrypt) as well as multi-part (streaming) interfaces for processing data incrementally.

Usage

DuckDB uses GCM and CCM for:

• TLS record protection: AES-GCM is the primary AEAD cipher suite for TLS 1.2 and TLS 1.3 connections in the httpfs extension (e.g., TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384)
• Authenticated encryption: Both modes provide simultaneous data confidentiality and integrity, ensuring that encrypted TLS records cannot be tampered with or forged
• Cipher suite support: GCM and CCM modes are registered through the cipher abstraction layer and selected during TLS handshake negotiation

Code Reference

Source Location

• Repository: Duckdb_Duckdb
• Files:
  • third_party/mbedtls/include/mbedtls/gcm.h -- GCM API header (384 lines)
  • third_party/mbedtls/include/mbedtls/ccm.h -- CCM API header (526 lines)
  • third_party/mbedtls/library/gcm.cpp -- GCM implementation (1330 lines)

Signature

// === GCM API ===

// Context lifecycle
void mbedtls_gcm_init(mbedtls_gcm_context *ctx);
void mbedtls_gcm_free(mbedtls_gcm_context *ctx);

// Key setup
int mbedtls_gcm_setkey(mbedtls_gcm_context *ctx,
                       mbedtls_cipher_id_t cipher,
                       const unsigned char *key,
                       unsigned int keybits);

// Single-shot encryption/decryption with tag
int mbedtls_gcm_crypt_and_tag(mbedtls_gcm_context *ctx,
                              int mode, size_t length,
                              const unsigned char *iv, size_t iv_len,
                              const unsigned char *add, size_t add_len,
                              const unsigned char *input,
                              unsigned char *output,
                              size_t tag_len, unsigned char *tag);

// Authenticated decryption (verifies tag)
int mbedtls_gcm_auth_decrypt(mbedtls_gcm_context *ctx,
                             size_t length,
                             const unsigned char *iv, size_t iv_len,
                             const unsigned char *add, size_t add_len,
                             const unsigned char *tag, size_t tag_len,
                             const unsigned char *input,
                             unsigned char *output);

// === CCM API ===

// Context lifecycle
void mbedtls_ccm_init(mbedtls_ccm_context *ctx);
void mbedtls_ccm_free(mbedtls_ccm_context *ctx);

// Key setup
int mbedtls_ccm_setkey(mbedtls_ccm_context *ctx,
                       mbedtls_cipher_id_t cipher,
                       const unsigned char *key,
                       unsigned int keybits);

// Encryption with authentication tag
int mbedtls_ccm_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length,
                                const unsigned char *iv, size_t iv_len,
                                const unsigned char *ad, size_t ad_len,
                                const unsigned char *input,
                                unsigned char *output,
                                unsigned char *tag, size_t tag_len);

Import

#include "mbedtls/gcm.h"
#include "mbedtls/ccm.h"

I/O Contract

Inputs

Name	Type	Required	Description
ctx	mbedtls_gcm_context * or mbedtls_ccm_context *	Yes	AEAD context, initialized and bound to a key
cipher	mbedtls_cipher_id_t	For setkey	Block cipher to use (typically MBEDTLS_CIPHER_ID_AES)
key	const unsigned char *	Yes	Encryption key
keybits	unsigned int	Yes	Key size in bits (128, 192, or 256)
mode	int	GCM only	MBEDTLS_GCM_ENCRYPT (1) or MBEDTLS_GCM_DECRYPT (0)
iv	const unsigned char *	Yes	Initialization vector / nonce
iv_len	size_t	Yes	IV length in bytes (typically 12 for GCM; 7-13 for CCM)
add/ad	const unsigned char *	Optional	Additional authenticated data (not encrypted)
add_len/ad_len	size_t	Optional	Length of additional data
input	const unsigned char *	Yes	Plaintext (encrypt) or ciphertext (decrypt)
length	size_t	Yes	Length of input/output data
tag_len	size_t	Yes	Authentication tag length (4-16 bytes)

Outputs

Name	Type	Description
return value	int	0 on success; MBEDTLS_ERR_GCM_AUTH_FAILED (-0x0012) or MBEDTLS_ERR_CCM_AUTH_FAILED (-0x000F) on authentication failure; MBEDTLS_ERR_GCM_BAD_INPUT (-0x0014) or MBEDTLS_ERR_CCM_BAD_INPUT (-0x000D) on bad parameters
output	unsigned char *	Encrypted ciphertext or decrypted plaintext
tag	unsigned char *	Authentication tag (written on encrypt, verified on decrypt)

Usage Examples

// AES-256-GCM authenticated encryption
mbedtls_gcm_context gcm;
mbedtls_gcm_init(&gcm);

unsigned char key[32] = { /* 256-bit key */ };
int ret = mbedtls_gcm_setkey(&gcm, MBEDTLS_CIPHER_ID_AES, key, 256);

unsigned char iv[12]     = { /* 96-bit nonce */ };
unsigned char aad[20]    = { /* additional authenticated data */ };
unsigned char input[64]  = { /* plaintext */ };
unsigned char output[64];
unsigned char tag[16];

ret = mbedtls_gcm_crypt_and_tag(&gcm, MBEDTLS_GCM_ENCRYPT,
                                sizeof(input),
                                iv, sizeof(iv),
                                aad, sizeof(aad),
                                input, output,
                                sizeof(tag), tag);
if (ret != 0) { /* handle error */ }

// Authenticated decryption (verifies tag)
unsigned char decrypted[64];
ret = mbedtls_gcm_auth_decrypt(&gcm, sizeof(output),
                               iv, sizeof(iv),
                               aad, sizeof(aad),
                               tag, sizeof(tag),
                               output, decrypted);
if (ret != 0) { /* authentication failed or error */ }

mbedtls_gcm_free(&gcm);

Related Pages

• Principle:Duckdb_Duckdb_TLS_Cryptography