STM32 header for binary files

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP25x lines

The STM32 header is a STMicroelectronics header needed for binaries loaded by ROM code.

1. Description[edit | edit source]

Each binary image loaded by the ROM code needs to include a specific STM32 header added on top of the binary data. This header includes mandatory and optional information: this second one is only needed for the authentication (STM32MP1 series) and decryption (STM32MP13x lines and STM32MP2 series) processes.

2. On STM32MP13x lines [edit | edit source]

2.1. Base header[edit | edit source]

Name	Length	Byte Offset ^{[Note 1]}	Description
Magic number	32 bits	0	4 bytes in big endian: 'S', 'T', 'M', 0x32 = 0x53544D32
Image signature	512 bits	4	ECDSA signature for image authentication^{[Note 2]}
Image checksum	32 bits	68	Checksum of the payload^{[Note 3]}
Header version	32 bits	72	Header version v2.0 = 0x00020000 Byte0: reserved Byte1: major version = 0x02 Byte2: minor version = 0x00 Byte3: reserved
Image length	32 bits	76	Length of image in bytes^{[Note 4]}
Image entry Point	32 bits	80	Entry point of image
Reserved	96 bits	84	Reserved
Version number	32 bits	96	Image Version (monotonic number)^{[Note 5]}
Option flags	32 bits	100	b0=1: Authentication enabled^{[Note 6]} b1=1: Decryption enabled.^{[Note 7]} b31=1: Header padding enabled^{[Note 8]}
Header extensions length	32 bits	104	Sizes of header extensions enabled by option flags.
Padding	20 Bytes	108	Reserved padding bytes^{[Note 9]}. Must all be set to 0

↑ Unless expressed differently, the 32 bits values are stored in little endian.
↑ Signature is calculated from first byte of header version field to last byte of image given by image length field.
↑ 32-bit sum of all payload bytes accessed as 8-bit unsigned numbers, discarding any overflow bits. Used to check the downloaded image integrity when signature is not used (if b0=0 in Option flags).
↑ Length is the length of the built image, it does not include the length of the STM32 header.
↑ Image version number is an anti rollback monotonic counter. The ROM code checks that it is higher or equal to the monotonic counter stored in OTP.
↑ Enabling signature verification is mandatory on secure closed chips. Authentication parameters are stored in "Authentication header extension".
↑ When decryption is enabled, authentication is mandatory. Decryption parameters are stored in "Decryption header extension".
↑ This header padding extension is always used to have a fixed size of 512 bytes for the whole size of header + its extensions.
↑ This padding forces STM32 base header size to 128 bytes (0x80).

2.2. Authentication header extension[edit | edit source]

This header extension contains parameters needed for authentication.

Name	Length	Byte Offset^{[Note 1]}	Description
Extension type	32 bits	0	4 bytes in big endian: 'S', 'T', 0x00, 0x02 = 0x53540002
Extension length	32 bits	4	Number of bytes of header extension = 340
Public key index	32 bits	8	Index of the public key to be used.
Public key number	32 bits	12	Number of public keys in table = 8
ECDSA algorithm	32 bits	16	1: P-256 NIST ; 2: brainpool 256
ECDSA public key	512 bits	20	ECDSA public key to be used to verify the signature.^{[Note 2]}
Public key1 hash	256 bits	84	Hash of (ECDSA Algorithm+Public key1).^{[Note 3]}.
...	...	...	Hashes of (ECDSA Algorithm+Public key), for key2 up to key7
Public key8 hash^{[Note 4]}	256 bits	308	Hash of (ECDSA Algorithm+Public key8)

↑ Offset is relative to header extension base. Unless expressed differently, the 32 bits values are stored in little endian.
↑ Public key is a point on the ECC curve. This field contains the two big numbers in big endian format corresponding to ECC Point coordinates x and y. (If these coordinates are extracted from a PEM public key file that only kept coordinates in a raw binary format, you shall remove the first byte "04" which is an asn1 tag ; for more info: RFC 5480).
↑ The Public Key hash computation is the SHA-256 of ECDSA Algorithm expressed in little endian, concatenated to the public key itself. The entry of the public key table referenced by the public key index is compared to the hash of the ECDSA algorithm and public key that are stored in the header.
↑ The table of public key hashes will be hashed with SHA-256 by the ROM code and compared to the Hash of Public Keys Hashes Table (PKHTH) that is stored in OTP.

2.3. Decryption header extension[edit | edit source]

This header extension contains parameters needed for decryption.

Name	Length	Byte Offset^{[Note 1]}	Description
Extension type	32 bits	0	4 bytes in big endian: 'S', 'T', 0x00, 0x01 = 0x53540001
Extension length	32 bits	4	Number of bytes of header extension = 32
Key size	32 bits	8	Size of extension key (128 bits)^{[Note 2]}.
Derivation constant	32 bits	12	Constant used to derive decryption key from master key stored in OTP.
Plain hash	128 bits	16	128 msb bits of plain payload SHA256.

↑ Offset is relative to header extension base. Unless expressed differently, the 32 bits values are stored in little endian.
↑ Key size is fixed to 128 bits

2.4. Padding header extension[edit | edit source]

Name	Length	Byte Offset^{[Note 1]}	Description
Extension type	32 bits	0	4 bytes in big endian: 'S', 'T', 0xFF, 0xFF = 0x5354FFFF
Extension length	32 bits	4	Number of bytes of header extension = N + 8
Padding bytes	N bytes	8	Padding bytes^{[Note 2]}.

↑ Offset is relative to header extension base. Unless expressed differently, the 32 bits values are stored in little endian.
↑ N shall be calculated by signing tool so that the size of whole header plus its extension is equal to 512 bytes

3. On STM32MP15x lines [edit | edit source]

Name	Length	Byte Offset	Description
Magic number	32 bits	0	4 bytes in big endian: 'S', 'T', 'M', 0x32 = 0x53544D32
Image signature	512 bits	4	ECDSA signature for image authentication^{[Note 1]}
Image checksum	32 bits	68	Checksum of the payload^{[Note 2]}
Header version	32 bits	72	Header version v1.0 = 0x00010000 Byte0: reserved Byte1:major version = 0x01 Byte2: minor version = 0x00 Byte3: reserved
Image length	32 bits	76	Length of image in bytes^{[Note 3]}
Image entry Point	32 bits	80	Entry point of image
Reserved1	32 bits	84	Reserved
Load address	32 bits	88	Load address of image^{[Note 4]}
Reserved2	32 bits	92	Reserved
Version number	32 bits	96	Image Version (monotonic number)^{[Note 5]}
Option flags	32 bits	100	b0=1: no signature verification^{[Note 6]}
ECDSA algorithm	32 bits	104	1: P-256 NIST ; 2: brainpool 256
ECDSA public key	512 bits	108	ECDSA public key to be used to verify the signature.^{[Note 7]}^{[Note 8]}
Padding	83 Bytes	172	Reserved padding bytes^{[Note 9]}. Must all be set to 0.
Binary type	1 Byte	255	Used to check the binary type 0x10-0x1F: FSBL 0x30: Copro

↑ Signature is calculated from first byte of header version field to last byte of image given by image length field.
↑ 32-bit sum of all payload bytes accessed as 8-bit unsigned numbers, discarding any overflow bits. Used to check the downloaded image integrity when signature is not used (if b0=1 in Option flags).
↑ Length is the length of the built image, it does not include the length of the STM32 header.
↑ This field is not used by ROM code.
↑ Image version number is an anti rollback monotonic counter. The ROM code checks that it is higher or equal to the monotonic counter stored in OTP.
↑ Enabling signature verification is mandatory on secure closed chips.
↑ Public key is a point on the ECC curve. This field contains the two big numbers in big endian format corresponding to ECC Point coordinates x and y. (If these coordinates are extracted from a PEM public key file that only kept coordinates in a raw binary format, you shall remove the first byte "04" which is an asn1 tag ; for more info: RFC 5480).
↑ The Public Key hash computation is the SHA-256 of the public key itself, then the resulting value is compared to the Hash of pubKey that is stored in OTP.
↑ This padding forces STM32 header size to 256 bytes (0x100).

4. On STM32MP25x lines [edit | edit source]

4.1. Base header[edit | edit source]

Name	Length	Byte Offset ^{[Note 1]}	Description	Signed
Magic number	32 bits	0	4 bytes in big endian: 'S', 'T', 'M', 0x32 = 0x53544D32	No
Image signature	512 bits	4	ECDSA signature for image authentication^{[Note 2]}	No
Image checksum	32 bits	68	Checksum of the payload^{[Note 3]}	No
Header version	32 bits	72	Header version v2.2 = 0x00020200 Byte0: reserved Byte1: major version = 0x02 Byte2: minor version = 0x02 Byte3: reserved	Yes
Image length	32 bits	76	Length of image in bytes^{[Note 4]}	Yes
Image entry Point	32 bits	80	Entry point of image	Yes
Reserved	96 bits	84	Reserved	Yes
Version number	32 bits	96	Image Version (monotonic number)^{[Note 5]}	Yes
Option flags	32 bits	100	b0=1: Authentication enabled^{[Note 6]} b1=1: Decryption enabled.^{[Note 7]} b31=1: Header padding enabled^{[Note 8]}	Yes
Header extensions length	32 bits	104	Sizes of header extensions enabled by option flags.	Yes
Binary type	32 bits	108	Used to check binary type. Must be set to 0x30 for FSBLM.	Yes
Padding	8 Bytes	112	Reserved padding bytes^{[Note 9]}. Must all be set to 0	Yes
Non-secure payload length	32 bits	120	Length in bytes of optional non-secured payload.^{[Note 10]}	No
Non-secure payload hash	32 bits	124	32 msb bits of SHA256 of non authenticated payload.	No

↑ Unless expressed differently, the 32 bits values are stored in little endian.
↑ Signature is calculated from first byte of header version field to last byte of image given by image length field, excluding the last bytes following the padding field.
↑ 32-bit sum of all payload bytes accessed as 8-bit unsigned numbers, discarding any overflow bits. Used to check the downloaded image integrity when signature is not used (if b0=0 in Option flags).
↑ Length is the length of the built image, it does not include the length of the STM32 header.
↑ Image version number is an anti rollback monotonic counter. The ROM code checks that it is higher or equal to the monotonic counter stored in OTP.
↑ Enabling signature verification is mandatory on secure closed chips. Authentication parameters are stored in "Authentication header extension".
↑ When decryption is enabled, authentication is mandatory. Decryption parameters are stored in "Decryption header extension".
↑ This header padding extension is always used to have a fixed size of 512 bytes for the whole size of header + its extensions.
↑ This padding forces STM32 base header size to 128 bytes (0x80).
↑ when non secure payload is present, the image length must be a multiple of 32 bytes, so that non secure payload must start a 32 bytes aligned address.