LAN969x OTP Provisioning

An 8-byte free-form OEM identifier used to track each unit through manufacturing, returns (RMA), and field deployments. Once written, the value is exposed for runtime queries via serial-num (ietf-hardware). The field lives in Region 0 and can only be programmed once (HW-blank rule).

Decide the 8 raw bytes — typically a manufacturing serial drawn from the OEM tracking system. Base64-encode them (see Field Encoding):

Fetch /ietf-hardware:hardware; the value appears as a hex-formatted string under the board component’s serial-num leaf.

Each switch port (and the management interface) consumes one MAC address. The chip is provisioned with a base MAC plus a count of consecutive addresses; the hardware derives each port’s address by adding to the base. The pair lives in the OTP key-value tag store (Region 7) — the only OTP field that can be updated multiple times (the old record is invalidated, a new one is appended).

The base MAC is a dash-separated string and is not base64.

After programming, port MAC addresses are derivable as <base> + interface_index. Fetch any port’s phys-address (ietf-interfaces) to spot-check.

Anchor the device to a single Root-of-Trust (ROT) key so that only firmware signed by that key can boot. Once the OTP ROTPK is programmed, BL1 (ROM) at every boot computes the SHA-256 of the public key embedded in the firmware’s signing certificate, compares it against the OTP value, and refuses to boot if it doesn’t match.

LAN969x firmware is split into a bootloader and an application. The bootloader (sometimes referred to as BL2) is the build artifact lan969x_<board>_<variant>-secure.fip. The application is the normal .fip file, which is also used for over-the-air updates (internally the FIP holds images for the two TrustZone domains, BL31 and BL33). Both the bootloader and the application are checked by secure boot, so when deploying secure boot both must be signed with the ROT key. To ease production a .img file is also generated; it contains both the bootloader and the application, replicated across two slots.

The ROT private key stays on the build host — only the SHA-256 of the public key is written to OTP.

The value written to OTP is simply the SHA-256 of the public ECDSA key. Derive it with openssl alone — the build system is not needed for this:

Then build the matching signed firmware — the build signs the FIP with the ROT key:

This emits the signed bootloader (lan969x_<board>-secure.fip) and application (.fip / .img) anchored at the ROT key. Anti-rollback NV counters are configured separately at build time — see Anti-Rollback (NV Counters).

The placeholder below is illustrative — replace it with the base64 string from the preparation step.

Secure boot anchors the OTP ROTPK while authenticating each sign-ed root certificate: the bootloader root (id=6, the tb_fw cert, checked by BL1) and the application root (id=7, the trusted-key cert that roots the BL31 + BL33 chain, checked by BL2). The trace on those two images is what changes once the ROTPK is programmed.

While the cell is still blank, neither root can be anchored against OTP, so each logs the same NOTICE:

After the ROTPK is programmed, the very next boot anchors both roots against the OTP value — the ROTPK is not deployed NOTICE is gone and the same certs authenticate silently:

A ROTPK mismatch fails this step and halts the boot before the corresponding image runs.

The upstream FWU recovery tool shipped at https://github.com/microchip-ung/arm-trusted-firmware/releases/ (e.g. fwu-lan969x_a0-release.html) embeds a BL2U FIP whose fwu_cert.crt is signed by the TFA sample ROT key. After a customer ROTPK is burned, BL1 will refuse to load that BL2U during recovery.

support/scripts/lan969x-fwu-resign re-signs the embedded BL2U cert with the customer’s ROT key without touching the BL2U binary itself:

Outputs:

Ship the resulting HTML alongside the customer-keyed application firmware. The BL2U binary itself is unchanged across the operation; only the cert chain anchored at the new ROT key is regenerated.

AES-GCM-encrypt BL31 and BL33 against the OTP Secret Symmetric Key (SSK) so the firmware payloads cannot be read off the boot media (NOR flash). BL2 auto-detects the encryption header, decrypts with the OTP SSK, and then authenticates the plaintext against the signing certs. BL2 itself, and the cert chain stay plaintext — they carry the signing material, not secrets.

Encryption is a complement to signing, not a replacement. A device with no SSK programmed can run signed plaintext images just fine; SSK only matters when confidentiality is also required.

Encryption is off by default. The standard build produces only the plaintext artifact set (<prefix>.bin, .fip, .img, -secure.fip). To enable:

The placeholder below is illustrative — replace it with the base64 from the preparation step.

BL2 decrypts BL31/BL33 with whatever bytes are in OTP SSK — including all zeros if the cell is blank. <prefix>.enc.img boots only when the OTP value exactly matches the SSK the image was encrypted with; any mismatch fails the AES-GCM integrity check and BL2 aborts the load. Recommended sequence:

Steps 1 and 2 can run in any order before the reboot — only the next reset enforces the new pairing.

Permanently refuse boot via specific strap-mode pins. Useful to lock down debug or recovery boot modes on production hardware so they cannot be entered even with physical access to the strap pins.

The strap-disable-mask leaf is a 16-bit value where bit N disables strap mode N in BL1 (ROM). The OTP cell is OR-merged at the hardware level — a follow-up RPC can only add more disabled modes, never clear a previously set bit.

Reboot the chip into the disabled mode and confirm BL1 refuses boot. There is no runtime read-back of the mask from non-secure world.

Lock down JTAG access on production silicon so a debugger cannot read internal state or drive the CPU without first authenticating against a device-specific secret. Three cooperating leafs are involved:

The factory default is Open (no JTAG protection). To leave the device Open, simply omit secure-jtag-conf from the RPC.

Decide the mode (see the table above), then prepare the inputs for each leaf to be programmed.

1. Generate the SSK (recommended for every secure mode):

Base64-encode for the RPC:

2. Pick the UUID (10 raw bytes, vendor-defined). The bytes are free-form; a common pattern is a serial-number-like sequence drawn from the OEM tracking system. Example — the bytes 01..0a:

3. Pick the mode — one of secure-boundary-scan, secure-full or closed. Per sw-doc-lan966x-secure-boot.pdf §6 the SSK must already be in OTP before the SJTAG controller is asked to authenticate, so program SSK in the same RPC as secure-jtag-conf (or in a strictly earlier RPC). The combined RPC in the next subsection gets the ordering right.

All three leafs can be submitted in a single RPC — the validator runs every check before any write, so a typo in any leaf aborts the whole RPC with no partial commit. Within the SJTAG cluster the firmware always writes secure-jtag-shared-secret-key before secure-jtag-conf, so the SSK is in place before the controller is asked to authenticate on the next reset (matching the §6 ordering rule).

The placeholders below are illustrative — replace them with the values from the preparation step.

The configured mode takes effect on the next cold reset. Run system-restart, then on the next boot:

Lock OTP regions to ensure that fields meant to stay unprovisioned remain unprovisioned, and that already-provisioned fields cannot be altered (e.g. by OR-ing more data into them). After all sensitive programming is done, locking the relevant regions freezes the chip’s configuration.

write-protect is the one OTP field that does not follow the HW-blank rule — it is OR-merged into the existing value, so this RPC can be called multiple times to add more locked regions, but never to clear them.

Decide which regions are ready to lock. Each bit locks one region: bit N → Region N. Common production locks:

This sets bits 0 and 4 (0x11), locking Region 0 (manufacturing data) and Region 4 (keys). If Region 0 was already locked, only Region 4 is additionally locked.

Subsequent RPCs targeting fields in the locked regions return the structured error Region is write-protected (see Error Handling).