8 Key Management

Key Concepts


Term	Definition
Key registry	In-memory list (`key_slots[]`) that accumulates all keys loaded during a session. Maximum 10 entries.
VSS slot	A numbered position (2-127) in the VSS where a key is stored on-device
Key code	A PUF-wrapped version of a key. Can only be unwrapped on the same physical device. Stored in slot `0x80 \
Signing key	The first asymmetric key (slot 2) used by `hsmsfmdgen.exe` to sign the FWMD

Key Types Supported


Type	Subtype	Generation Methods	Step
Asymmetric ECC P-256	`ecc_p256`	TPDS software, load from file, PUF hardware	1, 1b
Symmetric AES-128	`aes128`	Load from file, manual hex entry	1b
Symmetric AES-256	`aes256`	Load from file, manual hex entry	1b

Key Slot Numbering Convention

 Slot range     Usage
 ----------     -----
   0 -   1      Reserved (not used)
   2            Secure Boot signing key (Step 1, fixed)
   3 - 255      Freely available for user keys and key codes

Note: In this use case demo, the convention keycode_slot = 0x80 | original_slot is used so that the LED demo application can locate key codes and verify them against the original keys. This is not a hardware or ROM Boot requirement -- in production, any slot from 3 to 255 can hold either a plain key or a key code, at the user's discretion.

Key Registry

Each entry in key_slots[] is a dictionary:


Field	Type	Description
`slot`	int	VSS slot index (2-127)
`type`	str	`"asymmetric"` or `"symmetric"`
`subtype`	str	`"ecc_p256"`, `"aes128"`, or `"aes256"`
`privatekey`	str	Hex string (asymmetric private key)
`publickey`	str	Hex string (asymmetric public key X\
`public_numbers`	obj	`ec.EllipticCurvePublicNumbers` (has `.x`, `.y`)
`key_data`	str	Hex string (symmetric key bytes)
`keycode`	str	Hex string of PUF-wrapped symmetric key (set by Step 1c)
`keycode_prv`	str	Hex string of PUF-wrapped private key (set by Step 1c)
`label`	str	Human-readable description

PUF Key Wrapping

The PUF produces a device-unique wrapping that binds keys to a specific chip. A wrapped key (key code) can only be unwrapped on the device that created it.

Why this matters: When key codes are used (Step 1c), the original key material does not need to be stored anywhere. The VSS only contains the opaque key codes, and the application firmware recovers the original keys at runtime by calling the PUF unwrap function. This means:

No plaintext keys on-device: an attacker reading the Flash sees only key codes, which are cryptographically bound to that specific chip's PUF and cannot be used on another device
No plaintext keys off-device: after provisioning, the original key material can be discarded. The device is self-sufficient -- it reconstructs the keys from the key codes using its own PUF.
Clone-resistant: copying the Flash contents to another chip is useless because the PUF response differs per silicon die

Note: For any deployment beyond development/debugging, always execute Step 1c and select only "Key codes" in the Step 3 VSS content dialog. This ensures the strongest level of key protection.

Key code size formula (from HSM firmware DRV_PUF_KEY_CODE_SIZE):

keyCodeSize = 36 + keyLen + 16 * ceil(keyLenBits / 384)


Key Type	Key Length	Key Code Size
ECC P-256 private (32 B)	32	84 bytes
AES-128 (16 B)	16	68 bytes
AES-256 (32 B)	32	84 bytes
ECC P-256 public (64 B)	64	132 bytes

Wrapping flow: