Implementation:Duckdb Duckdb Mbedtls Hash

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

Overview

The mbedTLS Hash module provides a generic message-digest (hashing) and HMAC interface supporting multiple hash algorithms including MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, and SHA-3 variants.

Description

This module implements cryptographic hash functions through two layers:

Generic message digest API (md.h / md.cpp): Provides a unified interface for all supported hash algorithms. The mbedtls_md_type_t enumeration defines supported digest types:

• MBEDTLS_MD_MD5 (0x03), MBEDTLS_MD_RIPEMD160 (0x04), MBEDTLS_MD_SHA1 (0x05)
• MBEDTLS_MD_SHA224 (0x08), MBEDTLS_MD_SHA256 (0x09)
• MBEDTLS_MD_SHA384 (0x0a), MBEDTLS_MD_SHA512 (0x0b)
• MBEDTLS_MD_SHA3_224 (0x10) through MBEDTLS_MD_SHA3_512 (0x13)

The mbedtls_md_context_t structure contains an opaque md_info pointer, a digest-specific context (md_ctx), and an optional HMAC context (hmac_ctx). The maximum digest output size (MBEDTLS_MD_MAX_SIZE) is 64 bytes (SHA-512) and the maximum block size (MBEDTLS_MD_MAX_BLOCK_SIZE) is 144 bytes (SHA3-224).

Algorithm-specific implementations:

• sha1.cpp: FIPS-180-1 compliant SHA-1 (160-bit output). Initializes state with the standard constants (0x67452301, 0xEFCDAB89, etc.) and processes 64-byte blocks. Functions include mbedtls_sha1_init(), mbedtls_sha1_starts(), and mbedtls_internal_sha1_process().
• sha256.cpp: FIPS-180-2 compliant SHA-256/SHA-224 (256/224-bit output). Includes support for ARMv8-A Crypto Extensions hardware acceleration. Processes 64-byte blocks with the standard round constants.

The MD module supports both legacy (direct function calls) and PSA Crypto Client dispatch modes, controlled by the MBEDTLS_MD_SOME_PSA configuration option.

Usage

DuckDB uses the hash module for:

• Extension signature verification: SHA-256 hashing of extension binaries before RSA signature verification
• TLS handshake: Computing message digests during the TLS handshake (Finished messages, CertificateVerify)
• HMAC computation: HMAC-SHA-256 used in TLS PRF (pseudo-random function) for key derivation
• Certificate validation: Digest computation for X.509 certificate signature verification

Code Reference

Source Location

• Repository: Duckdb_Duckdb
• Files:
  • third_party/mbedtls/include/mbedtls/md.h -- Message digest API header (526 lines)
  • third_party/mbedtls/library/md.cpp -- Message digest implementation (1108 lines)
  • third_party/mbedtls/library/sha1.cpp -- SHA-1 implementation (480 lines)
  • third_party/mbedtls/library/sha256.cpp -- SHA-256/SHA-224 implementation (980 lines)

Signature

// Message digest information lookup
const mbedtls_md_info_t *mbedtls_md_info_from_type(mbedtls_md_type_t md_type);

// Context lifecycle
void mbedtls_md_init(mbedtls_md_context_t *ctx);
void mbedtls_md_free(mbedtls_md_context_t *ctx);
int mbedtls_md_setup(mbedtls_md_context_t *ctx,
                     const mbedtls_md_info_t *md_info, int hmac);
int mbedtls_md_clone(mbedtls_md_context_t *dst,
                     const mbedtls_md_context_t *src);

// Digest properties
unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info);
unsigned char mbedtls_md_get_size_from_type(mbedtls_md_type_t md_type);

// SHA-1 specific (low-level)
void mbedtls_sha1_init(mbedtls_sha1_context *ctx);
void mbedtls_sha1_free(mbedtls_sha1_context *ctx);
void mbedtls_sha1_clone(mbedtls_sha1_context *dst,
                        const mbedtls_sha1_context *src);
int mbedtls_sha1_starts(mbedtls_sha1_context *ctx);
int mbedtls_internal_sha1_process(mbedtls_sha1_context *ctx,
                                  const unsigned char data[64]);

Import

#include "mbedtls/md.h"
#include "mbedtls/sha1.h"
#include "mbedtls/sha256.h"

I/O Contract

Inputs

Name	Type	Required	Description
ctx	mbedtls_md_context_t *	Yes	Message digest context
md_info	const mbedtls_md_info_t *	For setup	Digest algorithm information (from mbedtls_md_info_from_type)
hmac	int	For setup	0 = no HMAC; non-zero = allocate HMAC context
md_type	mbedtls_md_type_t	For lookup	Digest type enumeration value (e.g., MBEDTLS_MD_SHA256)
data	const unsigned char *	For process	Input data block (64 bytes for SHA-1/SHA-256)

Outputs

Name	Type	Description
return value	int	0 on success; error codes include MBEDTLS_ERR_MD_BAD_INPUT_DATA (-0x5100), MBEDTLS_ERR_MD_ALLOC_FAILED (-0x5180), MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE (-0x5080)
md_info	const mbedtls_md_info_t *	Pointer to digest information (NULL if type unknown)
(size)	unsigned char	Digest output size in bytes (e.g., 20 for SHA-1, 32 for SHA-256)

Usage Examples

// SHA-256 hashing via the generic MD interface
mbedtls_md_context_t ctx;
mbedtls_md_init(&ctx);

const mbedtls_md_info_t *md_info =
    mbedtls_md_info_from_type(MBEDTLS_MD_SHA256);
mbedtls_md_setup(&ctx, md_info, 0 /* no HMAC */);

mbedtls_md_starts(&ctx);
mbedtls_md_update(&ctx, (const unsigned char *)"Hello", 5);

unsigned char hash[32];
mbedtls_md_finish(&ctx, hash);
// hash now contains the SHA-256 digest of "Hello"

mbedtls_md_free(&ctx);

Related Pages

• Principle:Duckdb_Duckdb_TLS_Cryptography