doc: Add documentation for imgtool.py
diff --git a/doc/imgtool.md b/doc/imgtool.md
new file mode 100644
index 0000000..f881d57
--- /dev/null
+++ b/doc/imgtool.md
@@ -0,0 +1,88 @@
+## 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' manually:
+
+ pip install --user pycrypto
+ pip install --user pyasn1
+ pip install --user ecdsa
+
+or, on Ubuntu, using the package manager:
+
+ sudo apt-get install python3-crypto python3-pyasn1 python3-ecdsa
+
+## Managing keys
+
+This tool currently supports rsa-2048 and ecdsa-p256 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 ecdsa-p256 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.
+
+## 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
+
+Image signing takes a binary image intended for Slot 0 and adds a
+header and trailer that the bootloader is expecting:
+
+ usage: imgtool.py sign [-h] -k filename --align ALIGN -v VERSION -H
+ HEADER_SIZE [--pad PAD] [--rsa-pkcs1-15]
+ infile outfile
+
+ positional arguments:
+ infile
+ outfile
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -k filename, --key filename
+ --align ALIGN
+ -v VERSION, --version VERSION
+ -H HEADER_SIZE, --header-size HEADER_SIZE
+ --pad PAD Pad image to this many bytes, adding trailer magic
+ --rsa-pkcs1-15 Use old PKCS#1 v1.5 signature algorithm
+
+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. The generated image should start
+with zero bytes of this length (and the script will check this).
+
+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 slot 1 will then cause the bootloader to upgrade to it.
+
+Lastly, the --rsa-pkcs1-15 will cause the tool to use the older,
+deprecated pkcs#1 v1.5 signing algorithm when using RSA. This can be
+enabled in the bootloader as wel, and may be needed if you are using
+an older version of the bootloader.