hardwarekey – Cryptographic operations with keys held in hardware
The hardwarekey module exposes keys that live in a hardware key store –
eFuse, a key manager, a secure element – and can be used but never read
back. Application code can compute a MAC with the key; there is no API to
read the raw key bytes, and no API to write or burn keys. Provisioning a key
is a manufacturing-time step done with vendor tools (for example
espefuse.py on Espressif chips).
HardwareKey objects are not created by application code. Every hardware key
slot the board has is exposed as a fixed object in board (for example
board.EFUSE_KEY0), in the same way that pins are. Compute a MAC with one
by passing it to hmac.new().
Available on these boards
- class hardwarekey.Purpose
What a hardware key slot is provisioned for. Instances are singletons; compare with
is.- HMAC_UP: object
The slot holds an HMAC key. It can be used with
hmac.new().
- UNUSED: object
No key is burned into the slot (or it is burned for something this module does not expose). The slot’s
HardwareKeystill exists but cannot be used.
- class hardwarekey.HardwareKey
A key held in a hardware key store, usable but not readable.
This class cannot be instantiated. Every hardware key slot the board has is exposed as a fixed
HardwareKeyinboard– for exampleboard.EFUSE_KEY0– just like pins. A slot with no key burned into it still has aHardwareKeyobject; itspurposeishardwarekey.Purpose.UNUSED.Compute a MAC with a key by passing it to
hmac.new()in place of abyteskey.On espressif the slots are the eFuse key blocks (
BLOCK_KEY0-BLOCK_KEY5); a slot is usable only if its block was burned with purposeHMAC_UP.- __bool__() bool
Falseifpurposeishardwarekey.Purpose.UNUSED,Trueotherwise. This lets you writeif key:to check whether a slot is usable.
- key_slot: int
The port-defined key identifier this handle is bound to. On espressif, the eFuse key block index. (read-only)
- purpose: Purpose
What this key slot is provisioned for –
hardwarekey.Purpose.HMAC_UPorhardwarekey.Purpose.UNUSED. (read-only)
- exportable: bool
Whether the raw key bytes can ever leave the hardware. Always informational.
On espressif this is
Falseonce the key block’sRD_DISeFuse bit is set (whichespefuse.pydoes by default). It is meant for manufacturing-time self-test code to confirm a key block was burned as expected. (read-only)