Difference between revisions of "STM32 header for binary files"

[unchecked revision] [unchecked revision]
m (Reverted edits by Gerald Baeza (talk) to last revision by Lionel DEBIEVE)
(Tag: Rollback)
m

The STM32 header is a STMicroelectronics header needed for binaries loaded by ROM code and by TF-A.

Description[edit]


STM32 header.png

Each binary image (signed or not) loaded by ROM code and by TF-A need to include a specific STM32 header added on top of the binary data. The header includes the authentication information.

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 authentication1
Image Checksum 32 bits 68 Checksum of the payload2
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 bytes3
Image Entry Point 32 bits 80 Entry point of image
Reserved1 32 bits 84 Reserved
Load address 32 bits 88 Load address of image4
Reserved2 32 bits 92 Reserved
Version Number 32 bits 96 Image Version (monotonic number)5
Option flags 32 bits 100 b0=1: no signature verification6
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.7
Padding 84 Bytes 172 Reserved padding bytes8. Must all be set to 0
BinaryType 1 Byte 255 Used to check the binary type
0x00: U-Boot
0x10-0x1F: TF-A
0x20-0X2F: OPTEE
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 used by ROM code for specific executable images.
5 Image version 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 Hash of (algorithm+pubKey) is stored in OTP.
8 This padding forces Header size to 0x100 bytes.
<noinclude>

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

== Description ==</noinclude>


[[{{ReviewsComments|JCT W941:
* See in [[Contributors:SandBox]] a way to use "grouped references" in the table instead of <sup>1</sup>, <sup>2</sup> ...
* Generally speaking avoid uppercase letters in common words: "Image signature", "Image checksum", "Image length"... (note that if you modify the figure, you can also modify the uppercase letters)
* Check the "Byte offset" for "Padding": 83 bytes instead of 84 bytes to have an header size of 256 bytes?
* Add 256 in <sup>8</sup>: This padding forces header size to 256 (0x100) bytes.
* "Binary type" instead of "BinaryType"
* If possible, add "Version number", "Padding" and "Binary type" in the figure
}}

[[File:STM32_header.png | right]]

Each binary image (signed or not) loaded by [[:Category:ROM_code|ROM code]] and by [[TF-A_overview|TF-A]] need to include a specific STM32 header added on top of the binary data. The header includes the authentication information.

{|
! 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<sup>1</sup>

|-
| Image Checksum || 32 bits || 68 || Checksum of the payload<sup>2</sup>

|-
| 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<sup>3</sup>

|-
| Image Entry  Point || 32 bits || 80 || Entry point of image
|-
| Reserved1 || 32 bits || 84 || Reserved
|-
| Load address || 32 bits || 88 || Load address of image<sup>4</sup>

|-
| Reserved2 || 32 bits || 92 || Reserved
|-
| Version Number || 32 bits || 96 || Image Version (monotonic number)<sup>5</sup>

|-
| Option flags || 32 bits || 100 || b0=1: no signature verification<sup>6</sup>

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

|-
| Padding || 84 Bytes || 172 || Reserved padding bytes<sup>8</sup>. Must all be set to 0
|-
| BinaryType || 1 Byte || 255 || Used to check the binary type<br>0x00: U-Boot <br>0x10-0x1F: TF-A <br>0x20-0X2F: OPTEE <br>0x30: Copro
|}

:<sup>1</sup> Signature is calculated from first byte of header version field to last byte of image given by image length field.
:<sup>2</sup> 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).
:<sup>3</sup> Length is the length of the built image, it does not include the length of the STM32 header.
:<sup>4</sup> This field is used by ROM code for specific executable images.
:<sup>5</sup> Image version is an anti rollback monotonic counter. The ROM code checks that it is higher or equal to the monotonic counter stored in OTP.
:<sup>6</sup> Enabling signature verification is mandatory on secure closed chips.
:<sup>7</sup> Hash of (algorithm+pubKey) is stored in OTP.
:<sup>8</sup> This padding forces Header size to 0x100 bytes.
<noinclude>

[[Category:ROM code|0]]</noinclude>
Line 4: Line 4:
 
== Description ==
 
== Description ==
 
</noinclude>
 
</noinclude>
  +
{{ReviewsComments|JCT W941:
  +
* See in [[Contributors:SandBox]] a way to use "grouped references" in the table instead of <sup>1</sup>, <sup>2</sup> ...
  +
* Generally speaking avoid uppercase letters in common words: "Image signature", "Image checksum", "Image length"... (note that if you modify the figure, you can also modify the uppercase letters)
  +
* Check the "Byte offset" for "Padding": 83 bytes instead of 84 bytes to have an header size of 256 bytes?
  +
* Add 256 in <sup>8</sup>: This padding forces header size to 256 (0x100) bytes.
  +
* "Binary type" instead of "BinaryType"
  +
* If possible, add "Version number", "Padding" and "Binary type" in the figure
  +
}}
   
 
[[File:STM32_header.png | right]]
 
[[File:STM32_header.png | right]]

Attachments

Discussions