arno/trezor-firmware
1
0
Fork 0
mirror of https://github.com/trezor/trezor-firmware.git synced 2024-11-22 15:38:11 +00:00
Code Issues Releases Wiki Activity

update bootloader documentation

Browse Source
This commit is contained in:
Pavol Rusnak 2017-02-08 15:42:52 +01:00
parent 1f56e8651b
commit d65b6b35d9
No known key found for this signature in database
GPG Key ID: 91F3B339B9A02A3D
1 changed files with 40 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
docs/bootloader.md
View File

@ -1,17 +1,50 @@
#TREZOR Core Bootloader
All multibyte integer values are little endian!
Bootloader code is split into two stages. See [Memory Layout](memory.md) for more info about in which sectors the code is stored.
##Firmware File Format
First stage checks the integrity and signatures of second stage and runs it if everything is OK.
However, if first stage bootloader finds a valid second stage bootloader on the SD card (in raw format, no filesystem), it will replace the internal second stage, allowing an upgrade of the second stage.
TREZOR Core firmware file consists of 3 parts:
First stage is stored in write-protected area, which means only upgrade of the second stage bootloader is allowed.
##Common notes
* Hash function used is SHA-256 and signature system is Ed25519 (allows combining signatures by multiple keys into one).
* All multibyte integer values are little endian.
##Bootloader Format
TREZOR Core (second stage) bootloader consists of 2 parts:
1. bootloader header
2. bootloader code
###Bootloader Header
Total length of bootloader header is 256 bytes.
| offset | length | name | description |
|-------:|-------:|------|-------------|
| 0x0000 | 4 | magic | firmware magic `TRZB` |
| 0x0004 | 4 | hlen | length of the bootloader header |
| 0x0008 | 4 | expiry | valid until timestamp (0=infinity) |
| 0x000C | 4 | codelen | length of the bootloader code |
| 0x0010 | 1 | vmajor | version (major) |
| 0x0011 | 1 | vminor | version (minor) |
| 0x0012 | 1 | vpatch | version (patch) |
| 0x0013 | 1 | vbuild | version (build) |
| 0x0014 | 1 | slsigidx | SatoshiLabs signature indexes (bitmap) |
| 0x0015 | 64 | slsig | SatoshiLabs signature |
| 0x0079 | 135 | reserved | not used yet |
##Firmware Format
TREZOR Core firmware consists of 3 parts:
1. vendor header
2. firmware header
3. firmware code
Hash function used is SHA-256 and signature system is Ed25519 (allows combining signatures by multiple keys into one).
###Vendor Header
Total length of vendor header is 82 + 32 * (number of pubkeys) + (length of vendor string) + (length of vendor image) bytes rounded up to the closest multiply of 256 bytes.
@ -20,7 +53,7 @@ Total length of vendor header is 82 + 32 * (number of pubkeys) + (length of vend
|-------:|-------:|------|-------------|
| 0x0000 | 4 | magic | firmware magic `TRZV` |
| 0x0004 | 4 | hlen | length of the vendor header |
| 0x0008 | 4 | expiry | valid until timestamp |
| 0x0008 | 4 | expiry | valid until timestamp (0=infinity) |
| 0x000C | 1 | vsig_m | number of signatures needed to run the firmware from this vendor |
| 0x000D | 1 | vsig_n | number of pubkeys vendor wants to use for signing |
| 0x000E | 2 | reserved | not used yet |
@ -41,7 +74,7 @@ Total length of firmware header is 256 bytes.
|-------:|-------:|------|-------------|
| 0x0000 | 4 | magic | firmware magic `TRZF` |
| 0x0004 | 4 | hlen | length of the firmware header |
| 0x0008 | 4 | expiry | valid until timestamp |
| 0x0008 | 4 | expiry | valid until timestamp (0=infinity) |
| 0x000C | 4 | codelen | length of the firmware code |
| 0x0010 | 1 | vmajor | version (major) |
| 0x0011 | 1 | vminor | version (minor) |