Lines Matching +full:- +full:a
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 -->
28 for encrypting/decrypting images on-the-fly while upgrading.
31 a TLV with the key must be present in the image. When upgrading the
35 TLV present, is re-encrypted while swapping to the `secondary slot`.
37 ## [Threat model](#threat-model)
41 storage, eg a SPI flash being used for the secondary slot.
43 It does not protect against the possibility of attaching a JTAG and
47 Since decrypting requires a private key (or secret if using symmetric
58 applied over the un-encrypted data. Validation on encrypted images, checks
62 The image is encrypted using AES-CTR-128 or AES-CTR-256, with a counter
64 16-byte block. AES-CTR was chosen for speed/simplicity and allowing for any
68 The key used is a randomized when creating a new image, by `imgtool` or
70 but randomizing a 16-byte block with a TRNG should make it highly
73 To distribute this AES-CTR key, new TLVs were defined. The key can be
74 encrypted using either RSA-OAEP, AES-KW (128 or 256 bits depending on the
75 AES-CTR key length), ECIES-P256 or ECIES-X25519.
77 For RSA-OAEP a new TLV with value `0x30` is added to the image, for
78 AES-KW a new TLV with value `0x31` is added to the image, for
79 ECIES-P256 a new TLV with value `0x32` is added, and for ECIES-X25519 a
81 are the results of applying the given operations over the AES-CTR key.
83 ## [ECIES encryption](#ecies-encryption)
85 ECIES follows a well defined protocol to generate an encryption key. There are
90 * Generate a new private key and derive the public key; when using ECIES-P256
91 this is a secp256r1 keypair, when using ECIES-X25519 this will be a x25519
93 * Generate a new secret (DH) using the ephemeral private key and the public key
95 * Derive the new keys from the secret using HKDF (built on HMAC-SHA256). We
96 are not using a `salt` and using an `info` of `MCUBoot_ECIES_v1`, generating
98 * A new random encryption key is generated (for AES). This is
100 * The key is encrypted with AES-128-CTR or AES-256-CTR and a `nonce` of 0 using
102 * The encrypted key now goes through a HMAC-SHA256 using the remaining 32
105 The final TLV is built from the 65 bytes for ECIES-P256 or 32 bytes for
106 ECIES-X25519, which correspond to the ephemeral public key, followed by the
108 a TLV of 113 or 129 bytes for ECIES-P256 and 80 or 96 bytes for ECIES-X25519.
110 The implemenation of ECIES-P256 is named ENC_EC256 in the source code and
111 artifacts while ECIES-X25519 is named ENC_X25519.
113 ## [Upgrade process](#upgrade-process)
115 When starting a new upgrade process, `MCUboot` checks that the image in the
119 start the validation process, decrypting the blocks before check. A good
134 sectors are re-encrypted when copying from the `primary slot` to
137 ---
143 ---
150 ## [Creating your keys with imgtool](#creating-your-keys-with-imgtool)
152 `imgtool` can generate keys by using `imgtool keygen -k <output.pem> -t <type>`,
153 where type can be one of `rsa-2048`, `rsa-3072`, `ecdsa-p256`
154 or `ed25519`. This will generate a keypair or private key.
157 `imgtool getpub -k <input.pem> -e <encoding>`, where `encoding` can be one of
158 `lang-c` or `lang-rust` (defaults to `lang-c`). To extract a public key in PEM
159 format, use `imgtool getpub -k <input.pem> -e pem`.
161 If using AES-KW, follow the steps in the next section to generate the
164 ## [Creating your keys with Unix tooling](#creating-your-keys-with-unix-tooling)
166 * If using RSA-OAEP, generate a keypair following steps similar to those
168 * If using ECIES-P256, generate a keypair following steps similar to those
170 * If using ECIES-X25519, generate a private key passing the option `-t x25519`
172 command can be used: `openssl pkey -in <generated-private-key.pem> -pubout`
173 * If using AES-KW (`newt` only), the `kek` can be generated with a
174 command like (change count to 32 for a 256 bit key)