Difference between revisions of "STM32 header for binary files"

[unchecked revision] [quality revision]
m
m

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

1 Description[edit]

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 Warning.png) processes.

2 On STM32MP13x lines Warning.png[edit]

2.1 Base header[edit]

STM32MP13 header base.png
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 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 3]
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 4]
Option flags 32 bits 100 b0=1: Authentication enabled[Note 5]
b1=1: Decryption enabled.[Note 6]
b31=1: Header padding enabled[Note 7]
Header extensions length 32 bits 104 Sizes of header extensions enabled by option flags.
Padding 20 Bytes 108 Reserved padding bytes[Note 8].
Must all be set to 0
  1. ↑ Signature is calculated from first byte of header version field to last byte of image given by image length field.
  2. ↑ 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).
  3. ↑ Length is the length of the built image, it does not include the length of the STM32 header.
  4. ↑ 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.
  5. ↑ Enabling signature verification is mandatory on secure closed chips. Authentication parameters are stored in "Authentication header extension".
  6. ↑ When decryption is enabled, authentication is mandatory. Decryption parameters are stored in "Decryption header extension".
  7. ↑ This header padding extension is always used to have a fixed size of 512 bytes for the whole size of header + its extensions.
  8. ↑ This padding forces STM32 base header size to 128 bytes (0x80).

2.2 Authentication header extension[edit]

This header extension contains parameters needed for authentication.

STM32MP13 header authentication.png
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 (Algorithm+Public key1)
... ... ... Hashes of (Algorithm+Public key), for key2 up to key7
Public key8 hash[Note 3] 256 bits 308 Hash of (Algorithm+Public key8)
  1. ↑ Offset is relative to header extension base
  2. ↑ This field is an extract of PEM public key file that only kept the ECC Point coordinates x and y in a raw binary format (RFC 5480). This field will be hashed with SHA-256 and compared to the Hash of pubKey that is stored in the entry of the public key table referenced by the public key index.
  3. ↑ 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]

STM32MP13 header decryption.png

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.
  1. ↑ Offset is relative to header extension base
  2. ↑ Key size is fixed to 128 bits

2.4 Padding header extension[edit]

STM32MP13 header padding.png
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].
  1. ↑ Offset is relative to header extension base
  2. ↑ 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 More info.png[edit]

STM32 header.png
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]
Padding 83 Bytes 172 Reserved padding bytes[Note 8]. Must all be set to 0.
Binary type 1 Byte 255 Used to check the binary type
0x10-0x1F: FSBL
0x30: Copro
  1. ↑ Signature is calculated from first byte of header version field to last byte of image given by image length field.
  2. ↑ 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).
  3. ↑ Length is the length of the built image, it does not include the length of the STM32 header.
  4. ↑ This field is not used by ROM code.
  5. ↑ 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.
  6. ↑ Enabling signature verification is mandatory on secure closed chips.
  7. ↑ This field is an extract of PEM public key file that only kept the ECC Point coordinates x and y in a raw binary format (RFC 5480). This field will be hashed with SHA-256 and compared to the Hash of pubKey that is stored in OTP.
  8. ↑ This padding forces STM32 header size to 256 bytes (0x100). 


<noinclude>

The STM32 header is a STMicroelectronics header needed for binaries loaded by [[:Category:ROM_code|ROM code]].

== Description ==</noinclude>


Each binary image loaded by the [[:Category:ROM_code|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 ({{MicroprocessorDevice | device=1}}) and decryption ({{MicroprocessorDevice | device=13}}) processes.

== On {{MicroprocessorDevice | device=13}} ==
=== Base header ===

[[File:STM32MP13_header_base.png | right | |400px]]

{|
! Name !! Length !! Byte Offset !! Description
|-
| Magic number || 32 bits || 0 || 4 bytes in big endian:<br> 'S', 'T', 'M', 0x32 = 0x53544D32
|-
| Image signature || 512 bits || 4 || ECDSA signature for image authentication<ref group="Note">Signature is calculated from first byte of header version field to last byte of image given by image length field.</ref>

|-
| Image checksum || 32 bits || 68 || Checksum of the payload<ref group="Note">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).</ref>

|-
| Header version || 32 bits || 72 || Header version '''v2.0''' = 0x00020000<br>    Byte0: reserved<br>    Byte1: major version = 0x02  <br>    Byte2: minor version = 0x00 <br>    Byte3: reserved
|-
| Image length || 32 bits || 76 || Length of image in bytes<ref group="Note">Length is the length of the built image, it does not include the length of the STM32 header.</ref>

|-
| Image entry  Point || 32 bits || 80 || Entry point of image
|-
| Reserved || 96 bits || 84 || Reserved
|-
| Version number || 32 bits || 96 || Image Version (monotonic number)<ref group="Note">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.</ref>

|-
| Option flags || 32 bits || 100 || b0=1: Authentication enabled<ref group="Note">Enabling signature verification is mandatory on secure closed chips. Authentication parameters are stored in "Authentication header extension".</ref><br>b1=1: Decryption enabled.<ref group="Note">When decryption is enabled, authentication is mandatory . Decryption parameters are stored in "Decryption header extension".</ref><br>b31=1: Header padding enabled<ref group="Note">This header padding extension is always used to have a fixed size of 512 bytes for the whole size of header + its extensions.</ref>

|-
| Header extensions length|| 32 bits || 104 || Sizes of header extensions enabled by option flags. 
|-
| Padding || 20 Bytes || 108 || Reserved padding bytes<ref group="Note">This padding forces STM32 base header size to '''128 bytes''' (0x80).</ref>. <br>Must all be set to 0
|}<references group="Note"/>


=== Authentication header extension ===
This header extension contains parameters needed for authentication.
[[File:STM32MP13_header_authentication.png | right | |400px]]
{|
! Name !! Length !! Byte Offset<ref group="Note">Offset is relative to header extension base</ref> !! Description
|-
| Extension type|| 32 bits || 0 || 4 bytes in big endian:<br> '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.<ref group="Note"> This field is an extract of PEM public key file that only kept the ECC Point coordinates ''x'' and ''y'' in a raw binary format  ([http://www.rfc-editor.org/info/rfc5480 RFC 5480]). This field will be hashed with SHA-256 and compared to the '''Hash of pubKey''' that is stored in the entry of the public key table referenced by the public key index. </ref>

|-
| Public key1 hash || 256 bits || 84 || Hash of (Algorithm+Public key1)
|-
| ...||...||...|| Hashes of (Algorithm+Public key), for key2 up to key7
|-
| Public key8 hash<ref group="Note">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.</ref> || 256 bits || 308 || Hash of (Algorithm+Public key8)
|}<references group="Note"/>


=== Decryption header extension ===
[[File:STM32MP13_header_decryption.png | right | |400px]]
This header extension contains parameters needed for decryption.

{|
! Name !! Length !! Byte Offset<ref group="Note">Offset is relative to header extension base</ref> !! Description
|-
| Extension type|| 32 bits || 0 || 4 bytes in big endian:<br> '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)<ref group="Note">Key size is fixed to 128 bits</ref>.
|-
| 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.
|}<references group="Note"/>


=== Padding header extension ===
[[File:STM32MP13_header_padding.png | right | |400px]]

{|
! Name !! Length !! Byte Offset<ref group="Note">Offset is relative to header extension base</ref> !! Description
|-
| Extension type|| 32 bits || 0 || 4 bytes in big endian:<br> '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<ref group="Note">N shall be calculated by signing tool so that the size of whole header plus its extension is equal to 512 bytes</ref>.
|}<references group="Note"/>


== On {{MicroprocessorDevice | device=15}} ==

[[File:STM32_header.png | right | |400px]]

{|
! Name !! Length !! Byte Offset !! Description
|-
| Magic number || 32 bits || 0 || 4 bytes in big endian:<br> 'S', 'T', 'M', 0x32 = 0x53544D32
|-
| Image signature || 512 bits || 4 || ECDSA signature for image authentication<ref group="Note">Signature is calculated from first byte of header version field to last byte of image given by image length field.</ref>

|-
| Image checksum || 32 bits || 68 || Checksum of the payload<ref group="Note">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).</ref>

|-
| Header version || 32 bits || 72 || Header version v1.0 = 0x00010000<br>    Byte0: reserved<br>    Byte1:major version = 0x01  <br>    Byte2: minor version = 0x00 <br>    Byte3: reserved
|-
| Image length || 32 bits || 76 || Length of image in bytes<ref group="Note">Length is the length of the built image, it does not include the length of the STM32 header.</ref>

|-
| Image entry  Point || 32 bits || 80 || Entry point of image
|-
| Reserved1 || 32 bits || 84 || Reserved
|-
| Load address || 32 bits || 88 || Load address of image<ref group="Note">This field is not used by ROM code.</ref>

|-
| Reserved2 || 32 bits || 92 || Reserved
|-
| Version number || 32 bits || 96 || Image Version (monotonic number)<ref group="Note">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 [[STM32MP15 OTP mapping#version monotonic counter|OTP]].</ref>

|-
| Option flags || 32 bits || 100 || b0=1: no signature verification<ref group="Note">Enabling signature verification is mandatory on secure closed chips.</ref>

|-
| 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.<ref group="Note"> This field is an extract of PEM public key file that only kept the ECC Point coordinates ''x'' and ''y'' in a raw binary format  ([http://www.rfc-editor.org/info/rfc5480 RFC 5480]). This field will be hashed with SHA-256 and compared to the '''Hash of pubKey''' that is stored in [[STM32MP15 OTP mapping#PKH|OTP]].</ref>

|-
| Padding || 83 Bytes || 172 || Reserved padding bytes<ref group="Note">This padding forces STM32 header size to 256 bytes (0x100).</ref>. Must all be set to 0.

|-
| Binary type || 1 Byte || 255 || Used to check the binary type <br>0x10-0x1F: FSBL <br>0x30: Copro
|}<references group="Note"/>

<noinclude>

[[Category:ROM code|0]]
{{PublicationRequestId | 24643 | 2022-09-26 | }}</noinclude>
Line 31: Line 31:
 
| Version number || 32 bits || 96 || Image Version (monotonic number)<ref group="Note">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.</ref>
  
| Version number || 32 bits || 96 || Image Version (monotonic number)<ref group="Note">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.</ref>
 
|-
  
|-
−
| Option flags || 32 bits || 100 || b0=1: Authentication enabled<ref group="Note">Enabling signature verification is mandatory on secure closed chips. Authentication parameters are stored in "Authentication header extension".</ref><br>b1=1: Decryption enabled.<ref group="Note">When decryption is enabled, authentication is mandatory . Decryption parameters are stored in "Decryption header extension".</ref><br>b31=1: Header padding enabled<ref group="Note">This header padding extension is always used to have a fixed size of 512 bytes for the whole size of header + its extensions.</ref>
 +
| Option flags || 32 bits || 100 || b0=1: Authentication enabled<ref group="Note">Enabling signature verification is mandatory on secure closed chips. Authentication parameters are stored in "Authentication header extension".</ref><br>b1=1: Decryption enabled.<ref group="Note">When decryption is enabled, authentication is mandatory. Decryption parameters are stored in "Decryption header extension".</ref><br>b31=1: Header padding enabled<ref group="Note">This header padding extension is always used to have a fixed size of 512 bytes for the whole size of header + its extensions.</ref>
 
|-
  
|-
 
| Header extensions length|| 32 bits || 104 || Sizes of header extensions enabled by option flags.  
  
| Header extensions length|| 32 bits || 104 || Sizes of header extensions enabled by option flags.  
 
|-
  
|-
−
| Padding || 20 Bytes || 108 || Reserved padding bytes<ref group="Note">This padding forces STM32 base header size to '''128 bytes''' (0x80).</ref>. Must all be set to 0
 +
| Padding || 20 Bytes || 108 || Reserved padding bytes<ref group="Note">This padding forces STM32 base header size to '''128 bytes''' (0x80).</ref>. <br>Must all be set to 0
 
|}
  
|}
 
<references group="Note"/>
  
<references group="Note"/>
Line 131: Line 131:
 
| ECDSA public key || 512 bits || 108 || ECDSA public key to be used to verify the signature.<ref group="Note"> This field is an extract of PEM public key file that only kept the ECC Point coordinates ''x'' and ''y'' in a raw binary format  ([http://www.rfc-editor.org/info/rfc5480 RFC 5480]). This field will be hashed with SHA-256 and compared to the '''Hash of pubKey''' that is stored in [[STM32MP15 OTP mapping#PKH|OTP]].</ref>
  
| ECDSA public key || 512 bits || 108 || ECDSA public key to be used to verify the signature.<ref group="Note"> This field is an extract of PEM public key file that only kept the ECC Point coordinates ''x'' and ''y'' in a raw binary format  ([http://www.rfc-editor.org/info/rfc5480 RFC 5480]). This field will be hashed with SHA-256 and compared to the '''Hash of pubKey''' that is stored in [[STM32MP15 OTP mapping#PKH|OTP]].</ref>
 
|-
  
|-
−
| Padding || 83 Bytes || 172 || Reserved padding bytes<ref group="Note">This padding forces STM32 header size to 256 bytes (0x100).</ref>. Must all be set to 0
 +
| Padding || 83 Bytes || 172 || Reserved padding bytes<ref group="Note">This padding forces STM32 header size to 256 bytes (0x100).</ref>. Must all be set to 0.
 
|-
  
|-
 
| Binary type || 1 Byte || 255 || Used to check the binary type <br>0x10-0x1F: FSBL <br>0x30: Copro
  
| Binary type || 1 Byte || 255 || Used to check the binary type <br>0x10-0x1F: FSBL <br>0x30: Copro
Retrieved from "https://wiki.st.com/stm32mpu/index.php?title=STM32_header_for_binary_files&oldid=88506"