105 lines
4.7 KiB
Markdown
105 lines
4.7 KiB
Markdown
# Image tool
|
|
|
|
The Python program `scripts/imgtool.py` can be used to perform the
|
|
operations that are necessary to manage keys and sign images. Using
|
|
this script should be preferred to the manual steps described in
|
|
`doc/signed_images.md`.
|
|
|
|
This program is written for Python3, and has several dependencies on
|
|
Python libraries. These can be installed using 'pip3':
|
|
|
|
pip3 install --user -r scripts/requirements.txt
|
|
|
|
## [Managing keys](#managing-keys)
|
|
|
|
This tool currently supports rsa-2048, rsa-3072, ecdsa-p256 and ed25519 keys.
|
|
You can generate a keypair for one of these types using the 'keygen' command:
|
|
|
|
./scripts/imgtool.py keygen -k filename.pem -t rsa-2048
|
|
|
|
or use rsa-3072, ecdsa-p256, or ed25519 for the type. The key type used
|
|
should match what mcuboot is configured to verify.
|
|
|
|
This key file is what is used to sign images, this file should be
|
|
protected, and not widely distributed.
|
|
|
|
You can add the `-p` argument to `keygen`, which will cause it to
|
|
prompt for a password. You will need to enter this password in every
|
|
time you use the private key.
|
|
|
|
## [Incorporating the public key into the code](#incorporating-the-public-key-into-the-code)
|
|
|
|
There is a development key distributed with mcuboot that can be used
|
|
for testing. Since this private key is widely distributed, it should
|
|
never be used for production. Once you have generated a production
|
|
key, as described above, you should replace the public key in the
|
|
bootloader with the generated one.
|
|
|
|
For Zephyr, the keys live in the file `boot/zephyr/keys.c`. For
|
|
mynewt, follow the instructions in `doc/signed_images.md` to generate
|
|
the key file.
|
|
|
|
./scripts/imgtool.py getpub -k filename.pem
|
|
|
|
will extract the public key from the given private key file, and
|
|
output it as a C data structure. You can replace or insert this code
|
|
into the key file.
|
|
|
|
## [Signing images](#signing-images)
|
|
|
|
Image signing takes an image in binary or Intel Hex format intended for the
|
|
primary slot and adds a header and trailer that the bootloader is expecting:
|
|
|
|
Usage: imgtool.py sign [OPTIONS] INFILE OUTFILE
|
|
|
|
Create a signed or unsigned image
|
|
|
|
Options:
|
|
-k, --key filename
|
|
--align [1|2|4|8] [required]
|
|
-v, --version TEXT [required]
|
|
-d, --dependencies TEXT
|
|
-H, --header-size INTEGER [required]
|
|
--pad-header Add --header-size zeroed bytes at the beginning
|
|
of the image
|
|
-S, --slot-size INTEGER Size of the slot where the image will be
|
|
written [required]
|
|
--pad Pad image to --slot-size bytes, adding trailer
|
|
magic
|
|
-M, --max-sectors INTEGER When padding allow for this amount of sectors
|
|
(defaults to 128)
|
|
--overwrite-only Use overwrite-only instead of swap upgrades
|
|
-e, --endian [little|big] Select little or big endian
|
|
-E, --encrypt filename Encrypt image using the provided public key
|
|
-h, --help Show this message and exit.
|
|
|
|
The main arguments given are the key file generated above, a version
|
|
field to place in the header (1.2.3 for example), the alignment of the
|
|
flash device in question, and the header size.
|
|
|
|
The header size depends on the operating system and the particular
|
|
flash device. For Zephyr, it will be configured as part of the build,
|
|
and will be a small power of two. By default, the Zephyr build system will
|
|
already prepended a zeroed header to the image. If another build system is
|
|
in use that does not automatically add this zeroed header, `--pad-header` can
|
|
be passed and the `--header-size` will be added by imgtool. If `--pad-header`
|
|
is used with an Intel Hex file, `--header-size` bytes will be subtracted from
|
|
the load address (in Intel Hex terms, the Extended Linear Address record) to
|
|
adjust for the new bytes prepended to the file. The load address of all data
|
|
existing in the file should not change.
|
|
|
|
The `--slot-size` argument is required and used to check that the firmware
|
|
does not overflow into the swap status area (metadata). If swap upgrades are
|
|
not being used, `--overwrite-only` can be passed to avoid adding the swap
|
|
status area size when calculating overflow.
|
|
|
|
The optional `--pad` argument will place a trailer on the image that
|
|
indicates that the image should be considered an upgrade. Writing this image
|
|
in the secondary slot will then cause the bootloader to upgrade to it.
|
|
|
|
A dependency can be specified in the following way:
|
|
`-d "(image_id, image_version)"`. The `image_id` is the number of the image
|
|
which the current image depends on. The `image_version` is the minimum version
|
|
of that image to satisfy compliance. For example `-d "(1, 1.2.3+0)"` means this
|
|
image depends on Image 1 which version has to be at least 1.2.3+0.
|