Module lock 

/!\ IRREVERSIBLE LOCK OPERATIONS - HANDLE WITH EXTREME CARE.

The functions in this module mutate the chip’s lock state. Once a zone is locked, it cannot be unlocked. There is no factory reset. A misissued Lock command turns the chip into permanent silicon.

Project rules

1. No automatic flow calls Lock. Provisioning, initialization, tests, setup scripts: none of them call any function in this module implicitly. The user invokes Lock manually through a dedicated USB-HID command, with a magic word and a CRC of the expected state.

2. Every function takes an explicit confirmation parameter. For zone locks the caller supplies the CRC-16 of the zone as it currently is on the chip. The chip itself recomputes and compares against the value sent in param2. A mismatch is rejected with a chip error. The firmware combines this with a magic word check at the USB layer.

Workflow expectation

• Lock config zone: only after WriteConfigZone has been replayed, read back, and bit-compared against the expected blob. The CLI tool hsm-host lock-config-DANGEROUS reads the chip’s current configuration zone, computes the CRC over the full 128 bytes, shows it in the double-confirmation prompt, and only then sends the Lock command with that CRC. The chip verifies one last time before committing.

• Lock data zone: only after every data slot the project expects has been provisioned (PIN hash, PUK hash, IO key, and at least one ECC keypair generated on chip via GenKey). No CRC is checked at lock time: secret-bearing slots are not readable.

• Lock slot: only after the per-slot content has been verified.

ATECC Lock command encoding

From the ATECC608B datasheet:

mode bits (param1)	Effect
0b0000_0000	Lock config zone, verify CRC in param2
0b1000_0000	Lock config zone, no CRC verification
0b0000_0001	Lock data zone, verify CRC in param2
0b1000_0001	Lock data zone, no CRC verification
0b0nnn_n010	Lock individual slot nnnn
0b1nnn_n010	Same, no CRC check

Top bit (bit 7) = “summary mode” : when 1, the chip does not verify the CRC in param2. We always send with this bit cleared (CRC checked) for zone locks. For slot lock we set it (the chip does not check a CRC for individual slots in our usage).

Encoding the CRC for the config-zone lock

The chip expects param2 little-endian. Pass the CRC computed identically to the chip’s algorithm (CCITT variant used everywhere in CryptoAuthLib). The CLI helper in tools/hsm-host reads the configuration zone from the chip, computes that CRC over the full 128 bytes (factory area included), and passes the result to the firmware. The chip recomputes the same CRC and rejects the command if the two disagree.

Constants

LOCK_MODE_CONFIG_ZONE_VERIFY_CRC 🔒

Mode bits for a config-zone lock, with CRC verification.

LOCK_MODE_DATA_ZONE_NO_CRC 🔒

Mode bits for a data-zone lock, with the chip’s CRC verification disabled. The data zone holds secrets (slots 5, 6, 8 contain hashed PIN/PUK and the I/O master key) that cannot be read back even with the data zone unlocked, because every secret-bearing slot has IsSecret=1. There is therefore no way for the host to compute a meaningful CRC of what is about to be locked, and no value in asking the chip to verify one. We rely on the magic-word guard at the USB layer and the interactive double confirmation in the host CLI.

LOCK_MODE_SLOT_NO_CRC_BASE 🔒

Mode bits for an individual slot lock, no CRC verification.