blob: a4f5c40e710df97d77523cc8bba0df719cada335 [file] [log] [blame] [view]
David Browne369fec2017-06-07 09:35:48 -06001## 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' manually:
10
David Brown6998fd52017-06-14 11:27:45 -040011 pip3 install --user pycrypto
12 pip3 install --user pyasn1
13 pip3 install --user ecdsa
David Browne369fec2017-06-07 09:35:48 -060014
15or, on Ubuntu, using the package manager:
16
17 sudo apt-get install python3-crypto python3-pyasn1 python3-ecdsa
18
19## Managing keys
20
21This tool currently supports rsa-2048 and ecdsa-p256 keys. You can
22generate a keypair for one of these types using the 'keygen' command:
23
24 ./scripts/imgtool.py keygen -k filename.pem -t rsa-2048
25
26or use ecdsa-p256 for the type. The key type used should match what
27mcuboot is configured to verify.
28
29This key file is what is used to sign images, this file should be
30protected, and not widely distributed.
31
32## Incorporating the public key into the code
33
34There is a development key distributed with mcuboot that can be used
35for testing. Since this private key is widely distributed, it should
36never be used for production. Once you have generated a production
37key, as described above, you should replace the public key in the
38bootloader with the generated one.
39
40For Zephyr, the keys live in the file `boot/zephyr/keys.c`. For
41mynewt, follow the instructions in `doc/signed_images.md` to generate
42the key file.
43
44 ./scripts/imgtool.py getpub -k filename.pem
45
46will extract the public key from the given private key file, and
47output it as a C data structure. You can replace or insert this code
48into the key file.
49
50## Signing images
51
52Image signing takes a binary image intended for Slot 0 and adds a
53header and trailer that the bootloader is expecting:
54
55 usage: imgtool.py sign [-h] -k filename --align ALIGN -v VERSION -H
56 HEADER_SIZE [--pad PAD] [--rsa-pkcs1-15]
57 infile outfile
58
59 positional arguments:
60 infile
61 outfile
62
63 optional arguments:
64 -h, --help show this help message and exit
65 -k filename, --key filename
66 --align ALIGN
67 -v VERSION, --version VERSION
68 -H HEADER_SIZE, --header-size HEADER_SIZE
David Brown2c21f712017-06-08 10:03:42 -060069 --included-header Image has gap for header
David Browne369fec2017-06-07 09:35:48 -060070 --pad PAD Pad image to this many bytes, adding trailer magic
71 --rsa-pkcs1-15 Use old PKCS#1 v1.5 signature algorithm
72
73The main arguments given are the key file generated above, a version
74field to place in the header (1.2.3 for example), the alignment of the
75flash device in question, and the header size.
76
77The header size depends on the operating system and the particular
78flash device. For Zephyr, it will be configured as part of the build,
David Brown2c21f712017-06-08 10:03:42 -060079and will be a small power of two. By default, the header will be
80prepended to the image. If `--included-header` is given, the image
81must start with header-size bytes of zeros, and the header will be
82overwritten over these bytes.
David Browne369fec2017-06-07 09:35:48 -060083
84The optional --pad argument will place a trailer on the image that
85indicates that the image should be considered an upgrade. Writing
86this image in slot 1 will then cause the bootloader to upgrade to it.
87
88Lastly, the --rsa-pkcs1-15 will cause the tool to use the older,
89deprecated pkcs#1 v1.5 signing algorithm when using RSA. This can be
90enabled in the bootloader as wel, and may be needed if you are using
91an older version of the bootloader.