hab

package
v0.0.0-...-245c505 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 25, 2022 License: GPL-3.0-only Imports: 13 Imported by: 0

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

View Source 
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).

View Source 
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).

View Source 
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).

View Source 
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).

View Source 
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).

View Source 
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).

View Source 
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).

View Source 
const DCD_OFFSET = 0x00910000

DCD represents the default DCD location in OCRAM for Serial Download Mode

View Source 
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.

View Source 
const DEFAULT_KEY_LENGTH = 2048

DEFAULT_KEY_LENGTH defines the default key length in bytes for generated HAB PKI certificates.

View Source 
const HAB_VER = 0x40

HAB_VER specifies HABv4

View Source 
const IVT_OFFSET = 1024

IVT_OFFSET represents the image vector table offset on disk images

Variables

This section is empty.

Functions

func NewCA 

func NewCA(keyLength int, keyExpiry int) (pemKey []byte, pemCert []byte, err error)

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).

func NewBootData 

func NewBootData(imx []byte, ivt *IVT) (data *BootData, err error)

NewBootData returns the Boot Data included in the passed IMX image.

type CSF 

type CSF struct {
	Header Header
	Data   []byte
}

CSF represents a Command Sequence File (p23, 4.3 Command Sequence File, HABv4 API RM).

func NewCSF 

func NewCSF(tag uint8) *CSF

NewCSF returns a tagged Command Sequence File with default values.

func (*CSF) Bytes 

func (csf *CSF) Bytes() []byte

Bytes converts the CSF to byte array format.

func (*CSF) Set 

func (csf *CSF) Set(buf []byte)

Set sets the CSF data.

type DCD 

type DCD struct {
	Header Header
	Data   []byte
}

DCD represents Device Configuration Data information (p311, 8.7.1.1 Device Configuration Data (DCD), IMX6ULLRM).

func (*DCD) Bytes 

func (dcd *DCD) Bytes() []byte

Bytes converts the DCD to byte array format.

func (*DCD) Read 

func (dcd *DCD) Read(buf []byte) (err error)

Read parses a buffer as Device Configuration Data.

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 struct {
	Tag uint8
	Len uint16
	Ver uint8
}

Header represents a data structure header (p22, 4.3 Command Sequence File, HABv4 API RM).

func NewHeader 

func NewHeader(tag uint8) Header

NewHeader returns a tagged data structure header with default values.

func (*Header) Bytes 

func (hdr *Header) Bytes() []byte

Bytes converts the header to byte array format.

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).

func (*IVT) Bytes 

func (ivt *IVT) Bytes() []byte

Bytes converts the IVT to byte array format.

func (*IVT) Read 

func (ivt *IVT) Read(buf []byte) (err error)

Read parses a buffer as Image Vector Table.

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.

func (*PublicKey) Bytes 

func (pk *PublicKey) Bytes() []byte

Bytes converts the SRK public key to byte array format.

func (*PublicKey) Hash 

func (pk *PublicKey) Hash() [32]byte

Hash returns the Super Root Key public key hash (SHA256), suitable for SRK table generation.

func (*PublicKey) Set 

func (pk *PublicKey) Set(pubKey *rsa.PublicKey) (err error)

Set imports an RSA public key in a Super Root Key public key.

type SRKTable 

type SRKTable struct {
	Tag uint8
	Len uint16
	Ver uint8
	SRK []PublicKey
}

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 

func NewSRKTable(srks [][]byte) (table *SRKTable, err error)

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().

func (*SRKTable) AddKey 

func (table *SRKTable) AddKey(srk []byte) (err error)

AddKey imports an RSA public key in a Super Root Key table.

func (*SRKTable) Bytes 

func (table *SRKTable) Bytes() []byte

Bytes converts the SRK table to byte array format.

func (*SRKTable) Hash 

func (table *SRKTable) Hash() [32]byte

Hash returns the Super Root Key public key hash (SHA256), suitable for OTP fusing.

type SignOptions 

type SignOptions struct {
	// CSFKeyPEMBlock specifies the Command Sequence File signing key in
	// PEM format.
	CSFKeyPEMBlock []byte

	// CSFCertPEMBlock specifies the Command Sequence File signing
	// certificate in PEM format.
	CSFCertPEMBlock []byte

	// IMGKeyPEMBlock specifies the IMX executable signing key in PEM
	// format.
	IMGKeyPEMBlock []byte

	// IMGCertPEMBlock specifies the IMX executable signing certificate in
	// PEM format.
	IMGCertPEMBlock []byte

	// 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.