David Brown | d2fcc21 | 2017-09-11 14:47:48 -0600 | [diff] [blame] | 1 | # Image tool |
David Brown | e369fec | 2017-06-07 09:35:48 -0600 | [diff] [blame] | 2 | |
| 3 | The Python program `scripts/imgtool.py` can be used to perform the |
| 4 | operations that are necessary to manage keys and sign images. Using |
| 5 | this script should be preferred to the manual steps described in |
| 6 | `doc/signed_images.md`. |
| 7 | |
| 8 | This program is written for Python3, and has several dependencies on |
Carles Cufi | f242901 | 2018-01-30 16:45:50 +0100 | [diff] [blame] | 9 | Python libraries. These can be installed using 'pip3': |
David Brown | e369fec | 2017-06-07 09:35:48 -0600 | [diff] [blame] | 10 | |
Carles Cufi | f242901 | 2018-01-30 16:45:50 +0100 | [diff] [blame] | 11 | pip3 install --user -r scripts/requirements.txt |
David Brown | e369fec | 2017-06-07 09:35:48 -0600 | [diff] [blame] | 12 | |
| 13 | ## Managing keys |
| 14 | |
Fabio Utzig | 19fd79a | 2019-05-08 18:20:39 -0300 | [diff] [blame^] | 15 | This tool currently supports rsa-2048, rsa-3072 and ecdsa-p256 keys. You |
| 16 | can generate a keypair for one of these types using the 'keygen' command: |
David Brown | e369fec | 2017-06-07 09:35:48 -0600 | [diff] [blame] | 17 | |
| 18 | ./scripts/imgtool.py keygen -k filename.pem -t rsa-2048 |
| 19 | |
| 20 | or use ecdsa-p256 for the type. The key type used should match what |
| 21 | mcuboot is configured to verify. |
| 22 | |
| 23 | This key file is what is used to sign images, this file should be |
| 24 | protected, and not widely distributed. |
| 25 | |
David Brown | 31d29c8 | 2017-11-21 15:38:56 -0700 | [diff] [blame] | 26 | You can add the `-p` argument to `keygen`, which will cause it to |
| 27 | prompt for a password. You will need to enter this password in every |
| 28 | time you use the private key. |
| 29 | |
David Brown | e369fec | 2017-06-07 09:35:48 -0600 | [diff] [blame] | 30 | ## Incorporating the public key into the code |
| 31 | |
| 32 | There is a development key distributed with mcuboot that can be used |
| 33 | for testing. Since this private key is widely distributed, it should |
| 34 | never be used for production. Once you have generated a production |
| 35 | key, as described above, you should replace the public key in the |
| 36 | bootloader with the generated one. |
| 37 | |
| 38 | For Zephyr, the keys live in the file `boot/zephyr/keys.c`. For |
| 39 | mynewt, follow the instructions in `doc/signed_images.md` to generate |
| 40 | the key file. |
| 41 | |
| 42 | ./scripts/imgtool.py getpub -k filename.pem |
| 43 | |
| 44 | will extract the public key from the given private key file, and |
| 45 | output it as a C data structure. You can replace or insert this code |
| 46 | into the key file. |
| 47 | |
| 48 | ## Signing images |
| 49 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 50 | Image signing takes an image in binary or Intel Hex format intended for the |
| 51 | primary slot and adds a header and trailer that the bootloader is expecting: |
David Brown | e369fec | 2017-06-07 09:35:48 -0600 | [diff] [blame] | 52 | |
Fabio Utzig | 5901fd5 | 2018-06-13 11:24:30 -0700 | [diff] [blame] | 53 | Usage: imgtool.py sign [OPTIONS] INFILE OUTFILE |
| 54 | |
| 55 | Create a signed or unsigned image |
| 56 | |
| 57 | Options: |
| 58 | -k, --key filename |
| 59 | --align [1|2|4|8] [required] |
| 60 | -v, --version TEXT [required] |
| 61 | -H, --header-size INTEGER [required] |
Fabio Utzig | cdfa11a | 2018-10-01 09:45:54 -0300 | [diff] [blame] | 62 | --pad-header Add --header-size zeroed bytes at the beginning |
Fabio Utzig | 5901fd5 | 2018-06-13 11:24:30 -0700 | [diff] [blame] | 63 | of the image |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 64 | -S, --slot-size INTEGER Size of the slot where the image will be |
| 65 | written [required] |
Fabio Utzig | 5901fd5 | 2018-06-13 11:24:30 -0700 | [diff] [blame] | 66 | --pad Pad image to --slot-size bytes, adding trailer |
| 67 | magic |
| 68 | -M, --max-sectors INTEGER When padding allow for this amount of sectors |
| 69 | (defaults to 128) |
| 70 | --overwrite-only Use overwrite-only instead of swap upgrades |
Fabio Utzig | cdfa11a | 2018-10-01 09:45:54 -0300 | [diff] [blame] | 71 | -e, --endian [little|big] Select little or big endian |
| 72 | -E, --encrypt filename Encrypt image using the provided public key |
Fabio Utzig | 5901fd5 | 2018-06-13 11:24:30 -0700 | [diff] [blame] | 73 | -h, --help Show this message and exit. |
David Brown | e369fec | 2017-06-07 09:35:48 -0600 | [diff] [blame] | 74 | |
| 75 | The main arguments given are the key file generated above, a version |
| 76 | field to place in the header (1.2.3 for example), the alignment of the |
| 77 | flash device in question, and the header size. |
| 78 | |
| 79 | The header size depends on the operating system and the particular |
| 80 | flash device. For Zephyr, it will be configured as part of the build, |
Fabio Utzig | 5901fd5 | 2018-06-13 11:24:30 -0700 | [diff] [blame] | 81 | and will be a small power of two. By default, the Zephyr build system will |
| 82 | already prepended a zeroed header to the image. If another build system is |
| 83 | in use that does not automatically add this zeroed header, `--pad-header` can |
Mark Schulte | b88b2c4 | 2018-07-17 07:47:03 -0700 | [diff] [blame] | 84 | be passed and the `--header-size` will be added by imgtool. If `--pad-header` |
| 85 | is used with an Intel Hex file, `--header-size` bytes will be subtracted from |
| 86 | the load address (in Intel Hex terms, the Extended Linear Address record) to |
| 87 | adjust for the new bytes prepended to the file. The load address of all data |
| 88 | existing in the file should not change. |
Fabio Utzig | 5901fd5 | 2018-06-13 11:24:30 -0700 | [diff] [blame] | 89 | |
| 90 | The `--slot-size` argument is required and used to check that the firmware |
| 91 | does not overflow into the swap status area (metadata). If swap upgrades are |
| 92 | not being used, `--overwrite-only` can be passed to avoid adding the swap |
| 93 | status area size when calculating overflow. |
David Brown | e369fec | 2017-06-07 09:35:48 -0600 | [diff] [blame] | 94 | |
Fabio Utzig | cdfa11a | 2018-10-01 09:45:54 -0300 | [diff] [blame] | 95 | The optional `--pad` argument will place a trailer on the image that |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 96 | indicates that the image should be considered an upgrade. Writing this image |
| 97 | in the secondary slot will then cause the bootloader to upgrade to it. |