Implementation:Duckdb Duckdb Mbedtls Utility

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

Overview

The mbedTLS Utility module provides foundational support libraries including platform abstraction, base64 encoding, PEM format parsing, OID definitions, DES cipher support, constant-time operations, memory alignment utilities, and configuration validation.

Description

This module groups the cross-cutting utility components that support the core cryptographic modules:

Platform Abstraction (platform.h / platform.cpp): Removes direct dependencies on standard C library functions, enabling portability. Provides configurable wrappers for snprintf, printf, fprintf, calloc, free, and exit. Handles platform-specific quirks such as non-conforming snprintf on older MSVC and MinGW builds.

Base64 Encoding (base64.cpp): RFC 1521 compliant base64 encoding and decoding implemented with constant-time character mapping to prevent timing side-channel attacks. Key functions include mbedtls_base64_encode() and mbedtls_base64_decode(), plus internal constant-time helpers mbedtls_ct_base64_enc_char() and mbedtls_ct_base64_dec_value().

PEM Format (pem.cpp): Parsing and writing of Privacy Enhanced Mail (PEM) format, which wraps DER-encoded binary data in base64 with header/footer delimiters (e.g., -----BEGIN CERTIFICATE-----). Used for reading certificates and keys from text files.

OID Database (oid.h / oid.cpp): Comprehensive Object Identifier registry mapping OID byte strings to algorithm identifiers, key types, cipher suites, X.509 extensions, and other standardized values. Defines OID constants for RSA, ECDSA, SHA-family hashes, and X.509 extension types.

DES Cipher (des.h): DES and Triple-DES block cipher API. The mbedtls_des_context stores 32 subkeys; mbedtls_des3_context stores 96 subkeys. Marked as weak/deprecated with security warnings. Included for legacy compatibility.

Constant-Time Operations (constant_time.cpp, constant_time_impl.h, constant_time_internal.h): Functions implemented without comparison operators to prevent branch-based timing leaks. The core function mbedtls_ct_memcmp() compares two buffers using volatile pointers and XOR accumulation to ensure constant execution time regardless of content. Includes platform-specific optimized assembly for ARM and AArch64 unaligned volatile access.

Alignment Utilities (alignment.h): Macros and functions for safe unaligned memory access, byte-swapping (MBEDTLS_BSWAP32, MBEDTLS_BSWAP64), and endianness handling (MBEDTLS_GET_UINT32_BE, MBEDTLS_PUT_UINT32_BE, etc.).

Common Definitions (common.h): Internal build configuration, feature detection macros, and utility definitions shared across the library.

Configuration Validation (check_config.h): Compile-time checks ensuring that the mbedTLS build configuration is consistent (e.g., verifying that required dependencies are enabled when a feature is selected).

PSA Crypto Core (psa_crypto_core.h): Internal header for the Platform Security Architecture (PSA) cryptography interface, providing key management and algorithm dispatch definitions.

Usage

DuckDB relies on these utility components for:

• PEM/DER key and certificate loading: Base64 decoding and PEM parsing are essential for loading certificates and keys from PEM-formatted files in the httpfs extension
• Platform-independent memory management: The platform abstraction layer enables DuckDB to build mbedTLS across all supported platforms without modification
• Side-channel resistance: Constant-time comparison and memory operations protect against timing attacks during signature verification and key operations
• OID-based algorithm identification: The OID database maps X.509 certificate algorithm identifiers to internal mbedTLS types during certificate chain validation
• Data format conversion: Base64 encoding/decoding and endianness utilities are used throughout the cryptographic pipeline

Code Reference

Source Location

• Repository: Duckdb_Duckdb
• Files:
  • third_party/mbedtls/include/mbedtls/platform.h -- Platform abstraction header (485 lines)
  • third_party/mbedtls/library/platform.cpp -- Platform implementation (402 lines)
  • third_party/mbedtls/library/base64.cpp -- Base64 encoding/decoding (323 lines)
  • third_party/mbedtls/library/pem.cpp -- PEM format handling (554 lines)
  • third_party/mbedtls/include/mbedtls/oid.h -- OID definitions (727 lines)
  • third_party/mbedtls/library/oid.cpp -- OID implementation (1166 lines)
  • third_party/mbedtls/include/mbedtls/des.h -- DES API header (385 lines)
  • third_party/mbedtls/library/constant_time.cpp -- Constant-time operations (248 lines)
  • third_party/mbedtls/library/constant_time_impl.h -- Constant-time implementation (541 lines)
  • third_party/mbedtls/library/constant_time_internal.h -- Constant-time internal API (579 lines)
  • third_party/mbedtls/library/alignment.h -- Alignment utilities (684 lines)
  • third_party/mbedtls/library/common.h -- Common definitions (453 lines)
  • third_party/mbedtls/include/mbedtls/check_config.h -- Configuration validation (1141 lines)
  • third_party/mbedtls/library/psa_crypto_core.h -- PSA crypto core header (995 lines)

Signature

// Base64 encoding/decoding
int mbedtls_base64_encode(unsigned char *dst, size_t dlen, size_t *olen,
                          const unsigned char *src, size_t slen);
int mbedtls_base64_decode(unsigned char *dst, size_t dlen, size_t *olen,
                          const unsigned char *src, size_t slen);

// Constant-time memory comparison
int mbedtls_ct_memcmp(const void *a, const void *b, size_t n);

// Constant-time base64 helpers (internal)
unsigned char mbedtls_ct_base64_enc_char(unsigned char value);
signed char mbedtls_ct_base64_dec_value(unsigned char c);

// DES context lifecycle
void mbedtls_des_init(mbedtls_des_context *ctx);
void mbedtls_des_free(mbedtls_des_context *ctx);
void mbedtls_des3_init(mbedtls_des3_context *ctx);
void mbedtls_des3_free(mbedtls_des3_context *ctx);

Import

#include "mbedtls/platform.h"
#include "mbedtls/base64.h"
#include "mbedtls/pem.h"
#include "mbedtls/oid.h"
#include "mbedtls/des.h"
#include "mbedtls/constant_time.h"

I/O Contract

Inputs

Name	Type	Required	Description
src	const unsigned char *	For base64	Source buffer (raw bytes for encode, base64 text for decode)
slen	size_t	For base64	Source buffer length
dst	unsigned char *	For base64	Destination buffer (NULL to query required size)
dlen	size_t	For base64	Destination buffer capacity
a, b	const void *	For ct_memcmp	Buffers to compare in constant time
n	size_t	For ct_memcmp	Number of bytes to compare
value	unsigned char	For enc_char	6-bit value (0-63) to encode as base64 character
c	unsigned char	For dec_value	Base64 character to decode to 6-bit value

Outputs

Name	Type	Description
return value (base64)	int	0 on success; MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL if dst is too small; MBEDTLS_ERR_BASE64_INVALID_CHARACTER on invalid input
olen	size_t *	Number of bytes written (or required if dst is NULL)
return value (ct_memcmp)	int	0 if buffers are equal; non-zero otherwise (constant-time, not meaningful as a comparison result)
return value (enc_char)	unsigned char	ASCII base64 character corresponding to input value
return value (dec_value)	signed char	6-bit value (0-63) or -1 for invalid input character

Usage Examples

// Base64 encoding
const unsigned char data[] = "Hello, DuckDB!";
unsigned char encoded[64];
size_t olen;

int ret = mbedtls_base64_encode(encoded, sizeof(encoded), &olen,
                                data, sizeof(data) - 1);
// encoded now contains "SGVsbG8sIER1Y2tEQiE="

// Base64 decoding
unsigned char decoded[64];
ret = mbedtls_base64_decode(decoded, sizeof(decoded), &olen,
                            encoded, olen);
// decoded now contains "Hello, DuckDB!"

// Constant-time comparison (for MAC verification)
unsigned char computed_mac[32] = { /* ... */ };
unsigned char expected_mac[32] = { /* ... */ };
int diff = mbedtls_ct_memcmp(computed_mac, expected_mac, 32);
if (diff != 0) {
    // MACs do not match -- authentication failure
}

Related Pages

• Principle:Duckdb_Duckdb_TLS_Cryptography