README ¶
NXP HABv4 Secure Boot utility
crucible | https://github.com/usbarmory/crucible
Copyright (c) WithSecure Corporation
▄████▄ ██▀███ █ ██ ▄████▄ ██▓ ▄▄▄▄ ██▓ ▓█████
▒██▀ ▀█ ▓██ ▒ ██▒ ██ ▓██▒▒██▀ ▀█ ▓██▒▓█████▄ ▓██▒ ▓█ ▀
▒▓█ ▄ ▓██ ░▄█ ▒▓██ ▒██░▒▓█ ▄ ▒██▒▒██▒ ▄██▒██░ ▒███
▒▓▓▄ ▄██▒▒██▀▀█▄ ▓▓█ ░██░▒▓▓▄ ▄██▒░██░▒██░█▀ ▒██░ ▒▓█ ▄
▒ ▓███▀ ░░██▓ ▒██▒▒▒█████▓ ▒ ▓███▀ ░░██░░▓█ ▀█▓░██████▒░▒████▒
░ ░▒ ▒ ░░ ▒▓ ░▒▓░░▒▓▒ ▒ ▒ ░ ░▒ ▒ ░░▓ ░▒▓███▀▒░ ▒░▓ ░░░ ▒░ ░
░ ▒ ░▒ ░ ▒░░░▒░ ░ ░ ░ ▒ ▒ ░▒░▒ ░ ░ ░ ▒ ░ ░ ░ ░
░ ░░ ░ ░░░ ░ ░ ░ ▒ ░ ░ ░ ░ ░ ░
░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░ ░
░ ░ ░
Where SoCs meet their fate.
Authors
Andrea Barisani
[email protected] | [email protected]
Andrej Rosano
[email protected] | [email protected]
Introduction
The habtool
utility provides support functions for NXP HABv4
Secure Boot
provisioning and executable signing.
Warning
Fusing SoC OTPs is an irreversible action that permanently fuses values on the device. This means that any errors in the process, or lost fused data such as cryptographic key material, might result in a bricked device.
The use of this tool is therefore at your own risk.
Installing
Pre-compiled binaries for Linux and Windows are released here.
You can also automatically download, compile and install the package, under your GOPATH, as follows:
go install github.com/usbarmory/crucible/cmd/habtool@latest
Alternatively you can manually compile it from source:
git clone https://github.com/usbarmory/crucible
cd crucible && make
The utility can be cross compiled Windows as follows:
make habtool.exe
Operation
Usage: habtool [OPTIONS]
-h Show this help
-z <crypto backend> "file" (default) or "gcp"
SRK CA creation options:
-C <output path> SRK private key in PEM format
-c <output path> SRK public key in PEM format
CSF/IMG certificates creation options:
-C <input path> SRK private key in PEM format
-c <input path> SRK public key in PEM format
-A <output path> CSF private key in PEM format
-a <output path> CSF public key in PEM format
-B <output path> IMG private key in PEM format
-b <output path> IMG public key in PEM format
SRK table creation options:
-1 <input path> SRK public key 1 ('file': PEM format, 'gcp': resource ID)
-2 <input path> SRK public key 2 ('file': PEM format, 'gcp': resource ID)
-3 <input path> SRK public key 3 ('file': PEM format, 'gcp': resource ID)
-4 <input path> SRK public key 4 ('file': PEM format, 'gcp': resource ID)
-o <output path> Write SRK table hash to file
-t <output path> Write SRK table to file
Executable signing options:
-A <input path> CSF private key ('file': PEM format, 'gcp': resource ID)
-a <input path> CSF public key ('file': PEM format, 'gcp': resource ID)
-B <input path> IMG private key ('file': PEM format, 'gcp': resource ID)
-b <input path> IMG public key ('file': PEM format, 'gcp': resource ID)
-t <input path> Read SRK table from file
-x <1-4> Index for SRK key
-e <id> Crypto engine (e.g. 0x1b for HAB_ENG_DCP)
-i <input path> Image file w/ IVT header (e.g. boot.imx)
-o <output path> Write CSF to file
-s Serial download mode
-S <address> Serial download DCD OCRAM address
(depends on mfg tool, default: 0x00910000)
The USB armory guide for Secure Boot provides an introduction on HABv4 using the USB armory Mk II as reference platform.
Google Cloud support
When setting the -z
flag to gcp
, habtool
will use the Google Cloud APIs to fetch certificates
and perform signing operations. This backend requires that public and private keys are referenced
using GCP Resource IDs
rather than on-disk files.
Signing keys must be stored in CloudHSM, and the particular
keys to use when signing the CSF and IMG payloads are passed as
CloudHSM Key Resource IDs to the -A
and -B
flags, e.g:
projects/myProject/locations/global/keyRings/myKeyRing/cryptoKeys/myKey/cryptoKeyVersions/1
.
Public key Resource IDs, passed via the -1
, -2
, -3
, -4
, -A
, or -B
flags, should reference either:
- a
Certificate
resource, e.g.:
projects/myProject/locations/us-central1/caPools/myPool/certificates/myCertificate
- a CertificateAuthority
resource, e.g.:
projects/myProject/locations/us-central1/caPools/myPool/certificateAuthorities/myCertificateAuthority
In the later case, the authoritie's public key certificate will be used.
License
crucible | https://github.com/usbarmory/crucible
Copyright (c) WithSecure Corporation
This project is distributed under the BSD-style license found in the LICENSE file.
Documentation ¶
There is no documentation for this package.