Jump to content

Connect SuperML | Leeroopedia MCP: Equip your AI agents with best practices, code verification, and debugging knowledge. Powered by Leeroo — building Organizational Superintelligence. Contact us at founders@leeroo.com.

Implementation:Duckdb Duckdb Mbedtls Utility

From Leeroopedia


Knowledge Sources
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

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

Page Connections

Double-click a node to navigate. Hold to expand connections.
Principle
Implementation
Heuristic
Environment
Retrieved from "https://leeroopedia.com/index.php?title=Implementation:Duckdb_Duckdb_Mbedtls_Utility&oldid=12919"