1<!--
2    -
3    - Licensed to the Apache Software Foundation (ASF) under one
4    - or more contributor license agreements.  See the NOTICE file
5    - distributed with this work for additional information
6    - regarding copyright ownership.  The ASF licenses this file
7    - to you under the Apache License, Version 2.0 (the
8    - "License"); you may not use this file except in compliance
9    - with the License.  You may obtain a copy of the License at
10    -
11    -  http://www.apache.org/licenses/LICENSE-2.0
12    -
13    - Unless required by applicable law or agreed to in writing,
14    - software distributed under the License is distributed on an
15    - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16    - KIND, either express or implied.  See the License for the
17    - specific language governing permissions and limitations
18    - under the License.
19    -
20-->
21
22## Image signing
23
24This signs the image by computing hash over the image, and then
25signing that hash. Signature is computed by newt tool when it's
26creating the image. This signature is placed in the image trailer.
27
28The public key of this keypair must be included in the bootloader,
29as it verifies it before allowing the image to run.
30
31This facility allows you to use multiple signing keys. This would
32be useful when you want to prevent production units from booting
33development images, but want development units to be able to boot
34both production images and development images.
35
36For an alternative solution when the public key(s) doesn't need to be
37included in the bootloader, see the [design](design.md) document.
38
39## Creating signing keys
40First you need a keypair to use for signing. You can create
41one with openssl command line tool.
42
43openssl genrsa -out image_sign.pem 2048
44
45This created a file which contains both the private and public key,
46and will be used when signing images.
47
48Then you need to extract the public key from this to include it
49in the bootloader. Bootloader need to keep key parsing minimal,
50so it expects simple key format.
51
52openssl rsa -in image_sign.pem -pubout -out image_sign_pub.der -outform DER -RSAPublicKey_out
53
54Now the public key is in file called image_sign_pub.der.
55
56For ECDSA256 these commands are similar.
57openssl ecparam -name prime256v1 -genkey -noout -out image_sign.pem
58openssl ec -in image_sign.pem -pubout -outform DER -out image_sign_pub.der
59
60## Creating a key package
61
62xxd -i image_sign_pub.der image_sign_pub.c.import
63
64Then you need to create a package containing this key, or keys.
65
66## Sample pkg.yml
67This gets bootutil to turn on image signature validation.
68
69    pkg.name: libs/mykeys
70    pkg.deps:
71        - "@apache-mynewt-core/boot/bootutil"
72
73## Sample source file
74This exports the keys.
75
76    #include <bootutil/sign_key.h>
77
78    #include "image_sign_pub.c.import"
79
80    const struct bootutil_key bootutil_keys[] = {
81        [0] = {
82            .key = image_sign_pub_der,
83            .len = &image_sign_pub_der_len,
84        }
85    };
86
87    const int bootutil_key_cnt = sizeof(bootutil_keys) / sizeof(bootutil_keys[0]);
88
89## Building the bootloader
90
91Enable the BOOTUTIL_SIGN_RSA syscfg setting in your app or target syscfg.yml
92file
93
94    syscfg.vals:
95        BOOTUTIL_SIGN_RSA: 1
96
97After you've created the key package, you must include it in the build
98for bootloader. So modify the pkg.yml for apps/boot to include it.
99
100The syscfg variable to enable ECDSA256 is BOOTUTIL_SIGN_EC256.
101