Documentation ¶
Overview ¶
Package hab provides support functions for NXP HABv4 Secure Boot provisioning and executable signing.
WARNING: Enabling NXP HABv4 secure boot is an irreversible action that permanently fuses verification keys hashes on the device. Any errors in the process or loss of the signing PKI will result in a bricked device incapable of executing unsigned code. This is a security feature, not a bug.
The use of this package is therefore **at your own risk**.
Index ¶
- Constants
- func NewCA(keyLength int, keyExpiry int) (pemKey []byte, pemCert []byte, err error)
- func NewCertificate(tag string, keyLength int, keyExpiry int, parent *x509.Certificate, ...) (pemKey []byte, pemCert []byte, err error)
- func Sign(imx []byte, opts SignOptions) (out []byte, err error)
- type AuthenticateData
- type BootData
- type CSF
- type DCD
- type DataBlock
- type Header
- type IVT
- type InstallKey
- type PublicKey
- type SRKTable
- type SignOptions
Constants ¶
const ( // Public Key types HAB_KEY_PUBLIC = 0xe1 HAB_KEY_HASH = 0xee // Public Key store indices HAB_IDX_SRK = 0 HAB_IDX_CSFK = 1 // Flags for Install Key commands HAB_CMD_INS_KEY_CLR = 0 // No flags set HAB_CMD_INS_KEY_ABS = 1 // Absolute certificate address HAB_CMD_INS_KEY_CSF = 2 // Install CSF key HAB_CMD_INS_KEY_DAT = 4 // Key binds to Data Type HAB_CMD_INS_KEY_CFG = 8 // Key binds to Configuration HAB_CMD_INS_KEY_FID = 16 // Key binds to Fabrication UID HAB_CMD_INS_KEY_MID = 32 // Key binds to Manufacturing ID HAB_CMD_INS_KEY_CID = 64 // Key binds to Caller ID HAB_CMD_INS_KEY_HSH = 128 // Certificate hash present )
HABv4 key constants (p37, 4.3.7 Install Key, HABv4 API RM).
const ( HAB_CMD_AUT_DAT_CLR = 0x00 // No flags set HAB_CMD_AUT_DAT_ABS = 0x01 // Absolute signature address )
HABv4 flags (p62, 4.3.8 Authenticate Data, HABv4 API RM).
const ( HAB_TAG_IVT = 0xd1 // Image Vector Table HAB_TAG_DCD = 0xd2 // Device Configuration Data HAB_TAG_CSF = 0xd4 // Command Sequence File HAB_TAG_CRT = 0xd7 // Certificate HAB_TAG_SIG = 0xd8 // Signature HAB_TAG_EVT = 0xdb // Event HAB_TAG_RVT = 0xdd // ROM Vector Table HAB_TAG_WRP = 0x81 // Wrapped Key HAB_TAG_MAC = 0xac // Message Authentication Code )
HABv4 data structures (p61, 6.2 Structure, HABv4 API RM).
const ( HAB_CMD_SET = 0xb1 // Set HAB_CMD_INS_KEY = 0xbe // Install Key HAB_CMD_AUT_DAT = 0xca // Authenticate Data HAB_CMD_WRT_DAT = 0xcc // Write Data HAB_CMD_CHK_DAT = 0xcf // Check Data HAB_CMD_NOP = 0xc0 // No Operation HAB_CMD_INIT = 0xb4 // Initialize HAB_CMD_UNLK = 0xb2 // Unlock )
HABv4 commands (p62, 6.3 Commands, HABv4 API RM).
const ( HAB_PCL_SRK = 0x03 // SRK certificate format HAB_PCL_X509 = 0x09 // X.509v3 certificate format HAB_PCL_CMS = 0xc5 // CMS/PKCS#7 signature format HAB_PCL_BLOB = 0xbb // SHW-specific wrapped key format HAB_PCL_AEAD = 0xa3 // Proprietary AEAD MAC format )
HABv4 protocol (p62, 6.4 Protocol, HABv4 API RM).
const ( // Algorithm types HAB_ALG_ANY = 0x00 // Algorithm type ANY HAB_ALG_HASH = 0x01 // Hash algorithm type HAB_ALG_SIG = 0x02 // Signature algorithm type HAB_ALG_F = 0x03 // Finite field arithmetic HAB_ALG_EC = 0x04 // Elliptic curve arithmetic HAB_ALG_CIPHER = 0x05 // Cipher algorithm type HAB_ALG_MODE = 0x06 // Cipher/Hash modes HAB_ALG_WRAP = 0x07 // Key wrap algorithm type // Hash algorithms HAB_ALG_SHA1 = 0x11 // SHA-1 algorithm ID HAB_ALG_SHA256 = 0x17 // SHA-256 algorithm ID HAB_ALG_SHA512 = 0x1b // SHA-512 algorithm ID // Signature algorithms HAB_ALG_PKCS1 = 0x21 // PKCS#1 RSA signature algorithm // Cipher algorithms HAB_ALG_AES = 0x55 // AES algorithm ID // Cipher or hash modes HAB_MODE_CCM = 0x66 // Counter with CBC-MAC // Key wrap algorithms HAB_ALG_BLOB = 0x71 // SHW-specific key wrap )
HABv4 tags (p63, 6.5 Algorithms, HABv4 API RM).
const ( HAB_ENG_ANY = 0x00 // First compatible engine HAB_ENG_SCC = 0x03 // Security controller HAB_ENG_RTIC = 0x05 // Run-time integrity checker HAB_ENG_SAHARA = 0x06 // Crypto accelerator HAB_ENG_CSU = 0x0a // Central Security Unit HAB_ENG_SRTC = 0x0c // Secure clock HAB_ENG_DCP = 0x1b // Data Co-Processor HAB_ENG_CAAM = 0x1d // Cryptographic Acceleration and Assurance Module HAB_ENG_SNVS = 0x1e // Secure Non-Volatile Storage HAB_ENG_OCOTP = 0x21 // Fuse controller HAB_ENG_DTCP = 0x22 //DTCP co-processor HAB_ENG_ROM = 0x36 // Protected ROM area HAB_ENG_HDCP = 0x24 // HDCP co-processor HAB_ENG_SW = 0xff // Software engine )
HABv4 engines (p64, 6.5 Engine, HABv4 API RM).
const DCD_OFFSET = 0x00910000
DCD represents the default DCD location in OCRAM for Serial Download Mode
const DEFAULT_KEY_EXPIRY = 3650
DEFAULT_KEY_EXPIRY defines the default key expiry in days for generated HAB PKI certificates, note that Secure Boot devices ignore any expiration value.
const DEFAULT_KEY_LENGTH = 2048
DEFAULT_KEY_LENGTH defines the default key length in bytes for generated HAB PKI certificates.
const HAB_VER = 0x40
HAB_VER specifies HABv4
const IVT_OFFSET = 1024
IVT_OFFSET represents the image vector table offset on disk images
Variables ¶
This section is empty.
Functions ¶
func NewCA ¶
NewCA generates a certificate authority suitable for signing HABv4 CSF/IMG certificates.
func NewCertificate ¶
func NewCertificate(tag string, keyLength int, keyExpiry int, parent *x509.Certificate, signer *rsa.PrivateKey) (pemKey []byte, pemCert []byte, err error)
NewCertificate generates a certificate suitable for HABv4 signing, the tag string (e.g. "CSF" or "IMG") is used in the certificate Common Name to distinguish its role.
func Sign ¶
func Sign(imx []byte, opts SignOptions) (out []byte, err error)
Sign generates an HABv4 compliant authentication and configuration script (CSF) based on passed keys and against a target IMX executable image. The resulting CSF can be concatenated to the IMX image and used as signed bootable payload on NXP HABv4 supported processors.
Types ¶
type AuthenticateData ¶
type AuthenticateData struct { Tag uint8 Len uint16 Flg uint8 Key uint8 // Verification key index Pcl uint8 // Authentication protocol Eng uint8 // Engine used to process data blocks Cfg uint8 // Engine configuration flags AutStart uint32 // Address of authentication data // contains filtered or unexported fields }
AuthenticateData represents an Authenticate Data command (p39, 4.3.8 Authenticate Data, HABv4 API RM).
func NewAuthenticateData ¶
func NewAuthenticateData() *AuthenticateData
NewAuthenticateData returns an Authenticate Data command with default values.
func (*AuthenticateData) Bytes ¶
func (cmd *AuthenticateData) Bytes() []byte
Bytes converts the Authenticate Data command to byte array format.
func (*AuthenticateData) SetDataBlock ¶
func (cmd *AuthenticateData) SetDataBlock(start uint32, size uint32)
SetDataBlock adds a data block to the command.
type BootData ¶
type BootData struct { Start uint32 // Absolute address of the image Length uint32 // Size of the program image Plugin uint32 // Plugin flag }
BootData represents a Boot Data structure (p162, 8.7.1.2 Boot data structure, IMX6ULLRM).
type CSF ¶
CSF represents a Command Sequence File (p23, 4.3 Command Sequence File, HABv4 API RM).
type DCD ¶
DCD represents Device Configuration Data information (p311, 8.7.1.1 Device Configuration Data (DCD), IMX6ULLRM).
type DataBlock ¶
type DataBlock struct { Start uint32 // Absolute address of data block Bytes uint32 // Size in bytes of data block }
DataBlock represents an optional data block for Authenticate Data commands.
type Header ¶
Header represents a data structure header (p22, 4.3 Command Sequence File, HABv4 API RM).
type IVT ¶
type IVT struct { Header Header Entry uint32 // Absolute address of the first instruction to execute from the image Reserved1 uint32 // Reserved and should be zero DCD uint32 // Absolute address of the image DCD BootData uint32 // Absolute address of the boot data Self uint32 // Absolute address of the IVT CSF uint32 // Absolute address of the Command Sequence File (CSF) Reserved2 uint32 // Reserved and should be zero }
IVT represents an Image Vector Table (p310, 8.7.1.1 Image vector table structure, IMX6ULLRM).
type InstallKey ¶
type InstallKey struct { Tag uint8 Len uint16 Flg uint8 Pcl uint8 // Key authentication protocol Alg uint8 // Hash algorithm Src uint8 // Source key index Tgt uint8 // Target key index KeyDat uint32 // Start address of key data to install }
InstallKey represents an Install Key command (p33, 4.3.7 Install Key, HABv4 API RM).
func NewInstallKey ¶
func NewInstallKey() *InstallKey
NewInstallKey returns an Install Key command with default values.
func (*InstallKey) Bytes ¶
func (cmd *InstallKey) Bytes() []byte
Bytes converts the Install Key command to byte array format.
type PublicKey ¶
type PublicKey struct { Tag1 uint8 KeyLen uint16 Tag2 uint8 Tag3 uint16 ModLen uint16 ExpLen uint16 Mod []byte Exp []byte // contains filtered or unexported fields }
PublicKey represents a Super Root Key publick key entry, suitable for SRK table generation.
type SRKTable ¶
SRKTable represents a Super Root Key table entry, suitable for fusing hash generation. To apply appropriate defaults NewSRKTable() should be used to instantiate it.
func NewSRKTable ¶
NewSRKTable returns a Super Root Key table entry with appropriate defaults. The argument takes an array of Super Root Keys for addition, it can be set to nil (or an empty list) as keys can also be individually added with AddKey().
type SignOptions ¶
type SignOptions struct { // CSFSigner is the signer to use for the Command Sequence File. // Its corresponding certificate should be provided in CSFCertPEMBlock. CSFSigner crypto.Signer // CSFCert specifies the Command Sequence File signing certificate. CSFCert *x509.Certificate // IMGSigner is the signer to use for IMX executables. // Its corresponding certificate should be in IMGCertPEMBlock below. IMGSigner crypto.Signer // IMGCertPEMBlock specifies the IMX executable signing certificate. IMGCert *x509.Certificate // Table specifies the Super Root Key (SRK) table. Table []byte // Index specifies the SRK key index. Index int // Engine specifies the crypto engine. Engine int // SDP specifies whether the signed image is meant for Serial Download // Protocol execution. SDP bool DCD uint32 }
SignOptions describes options for HABv4 executable image signing.