Skip to content

Commit 21dbcdd

Browse files
committed
move content to a guides section
1 parent 0465078 commit 21dbcdd

File tree

2 files changed

+54
-54
lines changed

2 files changed

+54
-54
lines changed

docs/guides/secure-boot.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
### Secure Boot
2+
3+
Some boards supports the secure boot. Basically the compiled sketch can be signed and encrypted with a
4+
[tool](../platform-specification.md#tools) before being flashed to the target board. The bootloader of the board is then
5+
responsible for starting the compiled sketch if the matching keys are used.
6+
7+
To be able to correctly carry out all the operations at the end of the build we can leverage the
8+
[post build hooks](../platform-specification.md#pre-and-post-build-hooks-since-arduino-ide-165) to sign and encrypt a
9+
binary by using `recipe.hooks.objcopy.postobjcopy.NUMBER.pattern` key in
10+
[`platform.txt`](../platform-specification.md#platformtxt). The security keys used are defined in the boards file, this
11+
way there could be different keys for different boards.
12+
13+
```
14+
[...]
15+
## Create output secure image (bin file)
16+
recipe.hooks.objcopy.postobjcopy.1.pattern={build.postbuild.cmd}
17+
#
18+
# IMGTOOL
19+
#
20+
21+
tools.imgtool.cmd=imgtool
22+
tools.imgtool.build.pattern=sign --key "{build.keys.keychain}/{build.keys.sign_key}" --encrypt "{build.keys.keychain}/{build.keys.encrypt_key}" "{build.path}/{build.project_name}.bin" "{build.path}/{build.project_name}.bin" --align {build.alignment} --max-align {build.alignment} --version {build.version} --header-size {build.header_size} --pad-header --slot-size {build.slot_size}
23+
[...]
24+
25+
```
26+
27+
By having only `tools.TOOL_NAME.cmd` and `tools.TOOL_NAME.build.pattern`, we can customize the behavior with a
28+
[custom board option](../platform-specification.md#custom-board-options). Then in the
29+
[`boards.txt`](../platform-specification.md#boardstxt) we can define the new option to use a different `postbuild.cmd`:
30+
31+
```
32+
[...]
33+
menu.security=Security setting
34+
35+
envie_m7.menu.security.none=None
36+
envie_m7.menu.security.sien=Signature + Encryption
37+
38+
envie_m7.menu.security.sien.build.postbuild.cmd="{tools.imgtool.cmd}" {tools.imgtool.build.pattern}
39+
envie_m7.menu.security.none.build.postbuild.cmd="{tools.imgtool.cmd}" exit
40+
41+
envie_m7.menu.security.sien.build.keys.type=public_keys
42+
envie_m7.menu.security.sien.build.keys.keychain={runtime.hardware.path}/Default_Keys
43+
envie_m7.menu.security.sien.build.keys.sign_key=default-signing-key.pem
44+
envie_m7.menu.security.sien.build.keys.encrypt_key=default-encrypt-key.pem
45+
[...]
46+
```
47+
48+
Currently we support the secure boot only with `build.keys.type=public_keys` but in the future other ways can be added.
49+
The security keys can be added with:
50+
51+
- `keys.keychain` indicates the path of the dir where to search for the custom keys to sign and encrypt a binary.
52+
- `keys.sign_key` indicates the name of the custom signing key to use to sign a binary during the compile process.
53+
- `keys.encrypt_key` indicates the name of the custom encryption key to use to encrypt a binary during the compile
54+
process.

docs/platform-specification.md

Lines changed: 0 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -768,60 +768,6 @@ All the tools launched to compile or upload a sketch will have the following env
768768
contain multiple space-delimited entries like `"arduino-cli/0.21.0 ArduinoIDE/2.0.0-rc1"` if this information is
769769
available.
770770

771-
### Secure Boot
772-
773-
Some boards supports the secure boot. Basically the compiled sketch can be signed and encrypted with a [tool](#tools)
774-
before being flashed to the target board. The bootloader of the board is then responsible for starting the compiled
775-
sketch if the matching keys are used.
776-
777-
To be able to correctly carry out all the operations at the end of the build we can leverage the
778-
[post build hooks](#pre-and-post-build-hooks-since-arduino-ide-165) to sign and encrypt a binary by using
779-
`recipe.hooks.objcopy.postobjcopy.NUMBER.pattern` key in [`platform.txt`](#platformtxt). The security keys used are
780-
defined in the boards file, this way there could be different keys for different boards.
781-
782-
```
783-
[...]
784-
## Create output secure image (bin file)
785-
recipe.hooks.objcopy.postobjcopy.1.pattern={build.postbuild.cmd}
786-
#
787-
# IMGTOOL
788-
#
789-
790-
tools.imgtool.cmd=imgtool
791-
tools.imgtool.build.pattern=sign --key "{build.keys.keychain}/{build.keys.sign_key}" --encrypt "{build.keys.keychain}/{build.keys.encrypt_key}" "{build.path}/{build.project_name}.bin" "{build.path}/{build.project_name}.bin" --align {build.alignment} --max-align {build.alignment} --version {build.version} --header-size {build.header_size} --pad-header --slot-size {build.slot_size}
792-
[...]
793-
794-
```
795-
796-
By having only `tools.TOOL_NAME.cmd` and `tools.TOOL_NAME.build.pattern`, we can customize the behavior with a
797-
[custom board option](#custom-board-options). Then in the [`boards.txt`](#boardstxt) we can define the new option to use
798-
a different `postbuild.cmd`:
799-
800-
```
801-
[...]
802-
menu.security=Security setting
803-
804-
envie_m7.menu.security.none=None
805-
envie_m7.menu.security.sien=Signature + Encryption
806-
807-
envie_m7.menu.security.sien.build.postbuild.cmd="{tools.imgtool.cmd}" {tools.imgtool.build.pattern}
808-
envie_m7.menu.security.none.build.postbuild.cmd="{tools.imgtool.cmd}" exit
809-
810-
envie_m7.menu.security.sien.build.keys.type=public_keys
811-
envie_m7.menu.security.sien.build.keys.keychain={runtime.hardware.path}/Default_Keys
812-
envie_m7.menu.security.sien.build.keys.sign_key=default-signing-key.pem
813-
envie_m7.menu.security.sien.build.keys.encrypt_key=default-encrypt-key.pem
814-
[...]
815-
```
816-
817-
The currently we support the secure boot only with `build.keys.type=public_keys` but in the future other ways can be
818-
added. The security keys can be added with:
819-
820-
- `keys.keychain` indicates the path of the dir where to search for the custom keys to sign and encrypt a binary.
821-
- `keys.sign_key` indicates the name of the custom signing key to use to sign a binary during the compile process.
822-
- `keys.encrypt_key` indicates the name of the custom encryption key to use to encrypt a binary during the compile
823-
process.
824-
825771
### Pluggable discovery
826772

827773
Discovery tools are a special kind of tool used to find supported boards. A platform must declare one or more Pluggable

0 commit comments

Comments
 (0)