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