espressif: Digital Signature peripheral — RSA sign/decrypt through hardwarekey, mutual TLS via ssl - #11425

Closes #3341.

Summary

The ESP32-S2/S3 (and C3/C5/C6/H2/P4) Digital Signature (DS) peripheral lets an RSA private key be used for signing or decryption without the key ever existing in readable form in software: it's decrypted internally by the peripheral, using a separate eFuse-held HMAC key, and the raw private key never appears in RAM. This closes #3341 by extending the hardwarekey/hmac machinery from PR #11319 (eFuse HMAC keys) to also cover the DS peripheral, and wiring the result into ssl for mutual-TLS client certificate authentication, the actual motivating use case in the issue (Azure IoT DPS / Adafruit IO style X.509 device identity).

import board, hardwarekey, crypto_primitives

key = board.EFUSE_KEY4  # any eFuse block burned with purpose HMAC_DOWN_DIGITAL_SIGNATURE
ds_key = hardwarekey.load_digital_signature_key(
    key, ds_params=open("/ds_params.bin", "rb").read()  # see "Provisioning" below
)

signature = ds_key.sign(
    data=b"message",
    padding=crypto_primitives.PKCS1v15,
    algorithm=crypto_primitives.SHA256,
)
plaintext = ds_key.decrypt(ciphertext=ciphertext, padding=crypto_primitives.PKCS1v15)

import board, hardwarekey, ssl, socketpool, wifi

key = board.EFUSE_KEY4
ds_key = hardwarekey.load_digital_signature_key(key, ds_params=open("/ds_params.bin", "rb").read())

pool = socketpool.SocketPool(wifi.radio)
ctx = ssl.create_default_context()
ctx.load_verify_locations(cadata=open("/ca.pem").read())
ctx.load_cert_chain(certfile="/client_cert.pem", keyfile=ds_key)  # private key never leaves the DS peripheral

sock = pool.socket(pool.AF_INET, pool.SOCK_STREAM)
sock.connect(("iot.example.com", 8443))
tls_sock = ctx.wrap_socket(sock, server_hostname="iot.example.com")

API

This revision reorganizes the DS API in response to review: HardwareKey stays a pure generic handle (key_slot, purpose, exportable, name/__repr__, __bool__, nothing else), the same type shared with hmac.new(). All DS-specific state and behavior lives on a new, separate type instead.

• HardwareKey.purpose gains hardwarekey.Purpose.HMAC_DOWN_DIGITAL_SIGNATURE, alongside the existing HMAC_UP/UNUSED, reported automatically for any eFuse block burned that way. This is the only DS-flavored thing left on HardwareKey itself.
• hardwarekey.load_digital_signature_key(key: HardwareKey, ds_params: ReadableBuffer) -> DigitalSignatureKey makes a DS-purpose key usable, mirroring cryptography.hazmat.primitives.serialization.load_pem_private_key(): a blob of key material in, a ready-to-use key object out. key must have purpose == Purpose.HMAC_DOWN_DIGITAL_SIGNATURE; the check happens once here rather than on every later call. ds_params is the encrypted parameter block produced at provisioning time by vendor tooling (see "Provisioning" below). It is not itself secret (it's only usable together with this specific eFuse block), so it's fine to keep in a plain file on CIRCUITPY.
• hardwarekey.DigitalSignatureKey holds key_size (the RSA modulus size in bits, e.g. 2048) and sign(data, padding, algorithm) -> bytes / decrypt(ciphertext, padding) -> bytes, mirroring cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey's method shape (sign, decrypt, key_size), not its full interface: there is intentionally no public_key(), private_numbers(), or private_bytes(), since the key material never leaves the DS peripheral and there is no honest way to implement export. Calling load_digital_signature_key() again returns a new, independent DigitalSignatureKey; an older one held across a later load for the same slot correctly raises ValueError on next use instead of silently signing or decrypting with the new load's key material (see "Testing" below).
• A new crypto_primitives module holds padding/algorithm objects: crypto_primitives.PKCS1v15 and crypto_primitives.SHA256 are plain constants (there's nothing to configure, so there's nothing to construct; compare with is, like hardwarekey.Purpose's own values). This deliberately doesn't mirror cryptography's padding.PKCS1v15()/hashes.SHA256(), which are instantiable classes there, since the peripheral only supports one concrete combination today and a stateless marker has nothing to configure. crypto_primitives.OAEP(algorithm) is a real class since it takes a real parameter, also available for decrypt() (see "OAEP / TLS 1.3" below for why it needs a non-default build). This lives in its own module rather than under hardwarekey, since these are algorithm and padding descriptors, not hardware keys, and the name and grouping are taken directly from cryptography.hazmat.primitives, the real shared parent of padding and hashes in the library this shape already mirrors.
• ssl.SSLContext.load_cert_chain(certfile, keyfile) accepts a hardwarekey.DigitalSignatureKey as keyfile in addition to a file path. When it does, wrap_socket() signs the TLS handshake (CertificateVerify) via mbedtls_pk_wrap_psa(): the private key is never parsed into mbedtls, never leaves the DS peripheral.

Deliberately not included: signature/plaintext verification against the public key. Verification only needs the public key, which needs no hardware protection and is already available wherever the application already has it (the X.509 cert file passed to load_cert_chain(), or a peer's own TLS stack), so reimplementing verification here would duplicate adafruit_rsa (the Bundle library) or a real cryptography install for no benefit.

Security: one key, one algorithm, enforced

A single RSA key must not be used under more than one algorithm for its lifetime. This isn't just caution, it's explicitly called out in the PSA Crypto API itself (psa_set_key_enrollment_algorithm()'s doc comment: "using the same key with different algorithms can allow some attacks based on arithmetic relations between different computations made with the same key"). So a DigitalSignatureKey commits to whichever algorithm it's first used with (sign(), decrypt() with a specific padding, or ssl.load_cert_chain(), which commits it to signing, since that's what a TLS handshake does), and stays committed to that one algorithm for the rest of its lifetime. A later call requesting a different algorithm raises ValueError rather than silently reusing the key unsafely:

ds_key = hardwarekey.load_digital_signature_key(key, ds_params=ds_params)
ds_key.sign(data=msg, padding=crypto_primitives.PKCS1v15, algorithm=crypto_primitives.SHA256)
ds_key.decrypt(ciphertext=ciphertext, padding=crypto_primitives.PKCS1v15)  # ValueError: already committed to signing
ds_key2 = hardwarekey.load_digital_signature_key(key, ds_params=ds_params)  # a fresh, independent key
ds_key2.decrypt(ciphertext=ciphertext, padding=crypto_primitives.PKCS1v15)  # fine, commits ds_key2 to decryption

OAEP / TLS 1.3

crypto_primitives.OAEP decrypt padding is more modern and secure than PKCS1v15 (which is susceptible to padding-oracle-style attacks). It's implemented and hardware-verified in this PR (see "Testing" below), but it only works in a build where CONFIG_MBEDTLS_SSL_PROTO_TLS1_3 is enabled: the ESP-IDF DS driver's OAEP un-padding code is compiled out otherwise. That flag is off by default in this port, and turning it on for every board is a real cost (extra flash and RAM for TLS 1.3 handshake machinery most boards don't otherwise need) and a decision that affects this whole port, not just this feature. We're deliberately leaving that call to the maintainers rather than making it ourselves as a side effect of this PR. Until (or unless) that flag is enabled, decrypt() raises a clear NotImplementedError for OAEP rather than a confusing generic PSA error, so the limitation is explicit rather than a silent trap.

To build and test the OAEP path yourself:

cd ports/espressif
make BOARD=<your_board>                                            # build once
echo "CONFIG_MBEDTLS_SSL_PROTO_TLS1_3=y" >> build-<your_board>/esp-idf/sdkconfig
rm -rf build-<your_board> && make BOARD=<your_board>                # clean rebuild, see note

Note the clean rebuild: an incremental rebuild after editing sdkconfig did not reliably pick up the change when we tested this (decrypt() kept raising NotImplementedError from a stale partial build even though the flag was set), so always do a full rebuild after changing this flag. With that build flashed:

plaintext = ds_key.decrypt(
    ciphertext=ciphertext,
    padding=crypto_primitives.OAEP(algorithm=crypto_primitives.SHA256),
)

works the same as PKCS1v15.

Provisioning (not part of this PR)

ds_params is produced entirely by existing, external Espressif vendor tooling: esp-secure-cert-tool generates the RSA key pair and the encrypted parameter blob, and espefuse.py burn-key (already used for the HMAC path in #11319) burns the paired HMAC key into an eFuse block with purpose HMAC_DOWN_DIGITAL_SIGNATURE. This fork intentionally adds no write/burn/provisioning API, consistent with the HMAC path's existing design, so a botched build can't brick a key block, and the diff stays small and reviewable.

Testing

Hardware-verified on an ESP32-S3-DevKitC-1-N8R8 with a real DS-purpose eFuse block (RSA-2048):

• load_digital_signature_key(): correctly refuses a key whose purpose isn't HMAC_DOWN_DIGITAL_SIGNATURE, and refuses a non-HardwareKey argument with a clear TypeError.
• sign(): output independently verified with openssl dgst -verify against the paired public key.
• decrypt(), both paddings: each round-trips against an independently-generated (openssl pkeyutl -encrypt) ciphertext back to the original plaintext. OAEP verified in a locally built TLS-1.3-enabled image (see above); PKCS1v15 in the default build.
• sign()/decrypt() keyword arguments: verified with arguments passed out of order, to confirm they're genuinely keyword-capable rather than just positional with labels.
• Algorithm commitment: verified in every direction (sign() after decrypt(), decrypt() after sign(), either after ssl.load_cert_chain(), and vice versa all raise ValueError; a fresh load_digital_signature_key() returns an independent key with no commitment).
• Generation-counter guard: loaded two DigitalSignatureKeys for the same slot, used the second one, then confirmed the first (now stale) raises ValueError on sign() instead of silently signing with the second load's key material.
• Error paths: decrypt()/sign() on an unsupported padding object, and a non-DS-purpose key, all raise clear, specific errors.
• Mutual TLS, on-device SoftAP loopback (the dev board has no antenna for a real network): server with authmode REQUIRED and a pinned CA accepts a DS-key-signed client CertificateVerify and completes the handshake; the same server never completes the handshake for a client presenting no certificate.
• No regression to the existing hmac.new() / eFuse HMAC path from hardwarekey: Add board-exposed keys usable via hmac.new() #11319.

.pot regeneration and .pyi stub extraction both pass cleanly. This revision's translatable-string count for the DS-related code is net lower than before it: the old "load_ds_params() has not been called on this key" check is gone entirely (the type's existence is now the proof), and load_digital_signature_key()'s type check reuses the existing mp_arg_validate_type() string rather than adding a new one.