RFC: Expose AEAD, HKDF, and ECDH from mbedTLS

[beriberikix]

Summary

I'd like to propose exposing three cryptographic primitives that are already (or nearly) compiled into mbedTLS to Python:

1. AEAD ciphers (AES-GCM, optionally ChaCha20-Poly1305) via cryptolib
2. HKDF-SHA256 key derivation via hashlib
3. ECDH P-256 key agreement via a new ec module

These primitives enable secure IoT protocols without requiring users to build native modules.

---

Motivation

Modern IoT protocols require cryptographic primitives beyond what MicroPython currently exposes:

Protocol	Requires
Matter (smart home)	ECDH P-256, HKDF, AES-CCM
Thread	ECDH, HKDF, AES-CCM
DTLS-PSK	HKDF, AES-GCM or ChaCha20-Poly1305
BLE LESC	ECDH P-256
Pouch (IoT gateway)	ECDH P-256, HKDF-SHA256, AES-GCM
COSE/CBOR crypto	ECDH, HKDF, AEAD

Currently, projects needing these primitives must:

• Build custom native .mpy modules (complex, architecture-specific)
• Vendor crypto libraries like mbedTLS or micro-ecc
• Maintain separate build pipelines per target

This is significant friction when mbedTLS is already compiled into the firmware with these capabilities.

---

Current State

The common mbedTLS config (extmod/mbedtls/mbedtls_config_common.h) already enables:

#define MBEDTLS_ECP_DP_SECP256R1_ENABLED  // line 43 — P-256 curve
#define MBEDTLS_ECDH_C                    // line 73 — compiled, not exposed
#define MBEDTLS_GCM_C                     // line 78 — compiled, not exposed (issue #10485)

These are used internally for TLS but not accessible from Python.

Not currently compiled:

• MBEDTLS_HKDF_C — ~1KB additional code
• MBEDTLS_CHACHA20_C / MBEDTLS_CHACHAPOLY_C — ~4KB (optional)

---

Proposed API

1. AEAD in cryptolib (extends existing module)

from cryptolib import aes_gcm

# AES-128-GCM (key=16 bytes, nonce=12 bytes)
cipher = aes_gcm(key, nonce)
ciphertext, tag = cipher.encrypt(plaintext, aad=b"")
plaintext = cipher.decrypt(ciphertext, tag, aad=b"")  # raises ValueError on auth fail

Alternative one-shot API (simpler, lower memory):

from cryptolib import aes_gcm_encrypt, aes_gcm_decrypt

ct_with_tag = aes_gcm_encrypt(key, nonce, plaintext, aad=b"")
plaintext = aes_gcm_decrypt(key, nonce, ct_with_tag, aad=b"")

2. HKDF in hashlib (extends existing module)

import hashlib

# HKDF-SHA256 one-shot (RFC 5869)
derived_key = hashlib.hkdf_sha256(ikm, salt, info, length)

Note: CPython's hashlib doesn't include HKDF (it's in the cryptography package). This would be a documented MicroPython extension, following the pattern of other MicroPython-specific additions.

3. ECDH in new ec module

import ec

# ECDH key agreement on P-256 (secp256r1)
# private_key: 32 bytes, peer_pubkey: 65 bytes (uncompressed 0x04 || X || Y)
shared_secret = ec.ecdh_p256(private_key, peer_pubkey)  # returns 32 bytes

Optional future extension:

# Key generation (if MICROPY_PY_EC_KEYGEN enabled)
private_key, public_key = ec.generate_keypair("secp256r1")

---

CPython Compatibility

Feature	CPython stdlib	Proposed approach
AES-GCM	Not in stdlib	Add to cryptolib (already MicroPython-specific)
HKDF	Not in hashlib	Add to hashlib as documented MicroPython extension
ECDH	Not in stdlib	New ec module (MicroPython-specific)

Per the contributor guidelines, these would be documented as MicroPython additions since CPython doesn't expose these in its standard library (they're in third-party packages like cryptography).

---

Configuration Flags

All features would be opt-in via MICROPY_* flags, defaulting based on MICROPY_SSL_MBEDTLS:

// py/mpconfig.h additions

#ifndef MICROPY_PY_CRYPTOLIB_AEAD
#define MICROPY_PY_CRYPTOLIB_AEAD (MICROPY_SSL_MBEDTLS)
#endif

#ifndef MICROPY_PY_HASHLIB_HKDF
#define MICROPY_PY_HASHLIB_HKDF (MICROPY_SSL_MBEDTLS)
#endif

#ifndef MICROPY_PY_EC
#define MICROPY_PY_EC (MICROPY_SSL_MBEDTLS)
#endif

Ports with size constraints can disable specific features.

---

Code Size Estimate

Feature	New mbedTLS code	Python bindings	Total
AES-GCM bindings	0 (already compiled)	~1 KB	~1 KB
HKDF-SHA256	~1 KB	~0.5 KB	~1.5 KB
ECDH bindings	0 (already compiled)	~1 KB	~1 KB
Total	~1 KB	~2.5 KB	~3.5 KB

ChaCha20-Poly1305 would add ~4 KB if enabled.

---

Test Vectors

Standard test vectors would be included:

• HKDF: RFC 5869 test cases
• AES-GCM: NIST SP 800-38D test vectors
• ECDH: NIST CAVP test vectors
• ChaCha20-Poly1305: RFC 7539 Section 2.8.2 (if enabled)

---

Implementation Approach

I propose splitting this into three separate PRs for easier review:

1. PR 1: AEAD in cryptolib — Highest value, uses already-compiled GCM code
2. PR 2: HKDF in hashlib — Requires enabling MBEDTLS_HKDF_C
3. PR 3: EC module with ECDH — Uses already-compiled ECDH code

Each PR would include:

• C implementation following code conventions
• Documentation updates
• Test cases with standard vectors

---

Use Cases

Beyond the protocols listed above, these primitives enable:

• Secure device provisioning — ECDH for key exchange during setup
• Encrypted sensor data — AEAD for authenticated encryption
• Session key derivation — HKDF for deriving multiple keys from shared secret
• Offline authentication — HMAC-based tokens without TLS overhead

---

Questions for Maintainers

1. Is extending cryptolib with AEAD the right home, or should this be a new module?
2. For HKDF, is hashlib.hkdf_sha256() acceptable, or would a separate kdf module be preferred?
3. Should the AEAD API be object-based (like current aes) or one-shot functions?
4. Any concerns about exposing ECDH that I should address?

---

References

• Issue Enable MBEDTLS_GCM_C by default #10485: Enable MBEDTLS_GCM_C by default (closed, completed)
• PR extmod/mbedtls: Enable modern cipher suites #15211: extmod/mbedtls: Enable modern cipher suites
• RFC 5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
• NIST SP 800-38D: Recommendation for Block Cipher Modes of Operation: GCM
• RFC 7539: ChaCha20 and Poly1305 for IETF Protocols

---

I'm happy to implement this if there's interest. I have a working proof-of-concept as a native module that could serve as a reference for the API design.