1# Image tool
2
3The Python program `scripts/imgtool.py` can be used to perform the
4operations that are necessary to manage keys and sign images.  Using
5this script should be preferred to the manual steps described in
6`doc/signed_images.md`.
7
8This program is written for Python3, and has several dependencies on
9Python libraries.  These can be installed using 'pip3':
10
11    pip3 install --user -r scripts/requirements.txt
12
13## [Managing keys](#managing-keys)
14
15This tool currently supports rsa-2048, rsa-3072, ecdsa-p256 and ed25519 keys.
16You can generate a keypair for one of these types using the 'keygen' command:
17
18    ./scripts/imgtool.py keygen -k filename.pem -t rsa-2048
19
20or use rsa-3072, ecdsa-p256, or ed25519 for the type.  The key type used
21should match what MCUboot is configured to verify.
22
23This key file is what is used to sign images, this file should be
24protected, and not widely distributed.
25
26You can add the `-p` argument to `keygen`, which will cause it to
27prompt for a password.  You will need to enter this password in every
28time you use the private key.
29
30## [Incorporating the public key into the code](#incorporating-the-public-key-into-the-code)
31
32There is a development key distributed with MCUboot that can be used
33for testing.  Since this private key is widely distributed, it should
34never be used for production.  Once you have generated a production
35key, as described above, you should replace the public key in the
36bootloader with the generated one.
37
38For Zephyr, the keys live in the file `boot/zephyr/keys.c`.  For
39mynewt, follow the instructions in `doc/signed_images.md` to generate
40the key file.
41
42    ./scripts/imgtool.py getpub -k filename.pem
43
44will extract the public key from the given private key file, and
45output it as a C data structure.  You can replace or insert this code
46into the key file. However, when the `MCUBOOT_HW_KEY` config option is
47enabled, this last step is unnecessary and can be skipped.
48
49## [Signing images](#signing-images)
50
51Image signing takes an image in binary or Intel Hex format intended for the
52primary slot and adds a header and trailer that the bootloader is expecting:
53
54    Usage: imgtool.py sign [OPTIONS] INFILE OUTFILE
55
56      Create a signed or unsigned image
57
58      INFILE and OUTFILE are parsed as Intel HEX if the params have .hex
59      extension, otherwise binary format is used
60
61    Options:
62      -k, --key filename
63      --public-key-format [hash|full]
64      --align [1|2|4|8]             [required]
65      -v, --version TEXT            [required]
66      -s, --security-counter TEXT   Specify the value of security counter. Use
67                                    the `auto` keyword to automatically generate
68                                    it from the image version.
69      -d, --dependencies TEXT
70      --pad-sig                     Add 0-2 bytes of padding to ECDSA signature
71                                    (for MCUboot <1.5)
72      -H, --header-size INTEGER     [required]
73      --pad-header                  Add --header-size zeroed bytes at the
74                                    beginning of the image
75      -S, --slot-size INTEGER       Size of the slot where the image will be
76                                    written [required]
77      --pad                         Pad image to --slot-size bytes, adding
78                                    trailer magic
79      --confirm                     When padding the image, mark it as confirmed
80      -M, --max-sectors INTEGER     When padding allow for this amount of
81                                    sectors (defaults to 128)
82      --boot-record sw_type         Create CBOR encoded boot record TLV. The
83                                    sw_type represents the role of the software
84                                    component (e.g. CoFM for coprocessor
85                                    firmware). [max. 12 characters]
86      --overwrite-only              Use overwrite-only instead of swap upgrades
87      -e, --endian [little|big]     Select little or big endian
88      -E, --encrypt filename        Encrypt image using the provided public key
89      --save-enctlv                 When upgrading, save encrypted key TLVs
90                                    instead of plain keys. Enable when
91                                    BOOT_SWAP_SAVE_ENCTLV config option was set.
92      -L, --load-addr INTEGER       Load address for image when it should run
93                                    from RAM.
94      -x, --hex-addr INTEGER        Adjust address in hex output file.
95      -R, --erased-val [0|0xff]     The value that is read back from erased
96                                    flash.
97      -h, --help                    Show this message and exit.
98
99The main arguments given are the key file generated above, a version
100field to place in the header (1.2.3 for example), the alignment of the
101flash device in question, and the header size.
102
103The header size depends on the operating system and the particular
104flash device.  For Zephyr, it will be configured as part of the build,
105and will be a small power of two.  By default, the Zephyr build system will
106already prepended a zeroed header to the image.  If another build system is
107in use that does not automatically add this zeroed header, `--pad-header` can
108be passed and the `--header-size` will be added by imgtool. If `--pad-header`
109is used with an Intel Hex file, `--header-size` bytes will be subtracted from
110the load address (in Intel Hex terms, the Extended Linear Address record) to
111adjust for the new bytes prepended to the file. The load address of all data
112existing in the file should not change.
113
114The `--slot-size` argument is required and used to check that the firmware
115does not overflow into the swap status area (metadata). If swap upgrades are
116not being used, `--overwrite-only` can be passed to avoid adding the swap
117status area size when calculating overflow.
118
119The optional `--pad` argument will place a trailer on the image that
120indicates that the image should be considered an upgrade.  Writing this image
121in the secondary slot will then cause the bootloader to upgrade to it.
122
123A dependency can be specified in the following way:
124`-d "(image_id, image_version)"`. The `image_id` is the number of the image
125which the current image depends on. The `image_version` is the minimum version
126of that image to satisfy compliance. For example `-d "(1, 1.2.3+0)"` means this
127image depends on Image 1 which version has to be at least 1.2.3+0.
128
129The `--public-key-format` argument can be used to distinguish where the public
130key is stored for image authentication. The `hash` option is used by default, in
131which case only the hash of the public key is added to the TLV area (the full
132public key is incorporated into the bootloader). When the `full` option is used
133instead, the TLV area will contain the whole public key and thus the bootloader
134can be independent from the key(s). For more information on the additional
135requirements of this option, see the [design](design.md) document.
136