OrgZephyr/mcuboot
OrgZephyr
/
mcuboot
mirror of https://github.com/zephyrproject-rtos/mcuboot.git
1
0
Fork 0
Code Issues Releases Wiki Activity

docs: Update with X25519 encrypted images info 

Signed-off-by: Fabio Utzig <utzig@apache.org>
This commit is contained in:
Fabio Utzig 2020-04-02 13:30:43 -03:00 committed by Fabio Utzig
parent b6f014c4bc
commit 5eaa57647e
2 changed files with 19 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/design.md
View File

@ -107,7 +107,8 @@ struct image_tlv {
#define IMAGE_TLV_ED25519 0x24 /* ED25519 of hash output */
#define IMAGE_TLV_ENC_RSA2048 0x30 /* Key encrypted with RSA-OAEP-2048 */
#define IMAGE_TLV_ENC_KW128 0x31 /* Key encrypted with AES-KW-128 */
#define IMAGE_TLV_ENC_EC256 0x32 /* Key encrypted with ECIES P256 */
#define IMAGE_TLV_ENC_EC256 0x32 /* Key encrypted with ECIES-P256 */
#define IMAGE_TLV_ENC_X25519 0x33 /* Key encrypted with ECIES-X25519 */
#define IMAGE_TLV_DEPENDENCY 0x40 /* Image depends on other image */
#define IMAGE_TLV_SEC_CNT 0x50 /* security counter */
```

28
docs/encrypted_images.md
View File

@ -71,22 +71,24 @@ but randomizing a 16-byte block with a TRNG should make it highly
improbable that duplicates ever happen.
To distribute this AES-CTR-128 key, new TLVs were defined. The key can be
encrypted using either RSA-OAEP, AES-KW-128 or ECIES-P256.
encrypted using either RSA-OAEP, AES-KW-128, ECIES-P256 or ECIES-X25519.
For RSA-OAEP a new TLV with value `0x30` is added to the image, for
AES-KW-128 a new TLV with value `0x31` is added to the image, and for
ECIES-P256 a new TLV with value `0x32` is added. The contents of those TLVs
AES-KW-128 a new TLV with value `0x31` is added to the image, for
ECIES-P256 a new TLV with value `0x32` is added, and for ECIES-X25519 a
newt TLV with value `0x33` is added. The contents of those TLVs
are the results of applying the given operations over the AES-CTR-128 key.
## [ECIES-P256 encryption](#ecies-p256-encryption)
## [ECIES encryption](#ecies-encryption)
ECIES follows a well defined protocol to generate an encryption key. There are
multiple standards which differ only on which building blocks are used; for
MCUBoot we settled on some primitives that are easily found on our crypto
libraries. The whole key encryption can be summarized as:
* Generate a new secp256r1 private key and derive the public key; this will be
our ephemeral key.
* Generate a new private key and derive the public key; when using ECIES-P256
this is a secp256r1 keypair, when using ECIES-X25519 this will be a x25519
keypair. Those keys will be our ephemeral keys.
* Generate a new secret (DH) using the ephemeral private key and the public key
that corresponds to the private key embedded in the HW.
* Derive the new keys from the secret using HKDF (built on HMAC-SHA256). We
@ -99,12 +101,13 @@ libraries. The whole key encryption can be summarized as:
* The encrypted key now goes through a HMAC-SHA256 using the remaining 32
bytes of key material from the HKDF.
The final TLV is built from the 65 bytes of the ephemeral public key, followed
by the 32 bytes of MAC tag and the 16 bytes of the encrypted key, resulting in
a TLV of 113 bytes.
The final TLV is built from the 65 bytes for ECIES-P256 or 32 bytes for
ECIES-X25519, which correspond to the ephemeral public key, followed by the
32 bytes of MAC tag and the 16 bytes of the encrypted key, resulting in a TLV
of 113 bytes for ECIES-P256 or 80 bytes for ECIES-X25519.
Since other EC primitives could be used, we name this particular implementation
ECIES-P256 or ENC_EC256 in the source code and artifacts.
The implemenation of ECIES-P256 is named ENC_EC256 in the source code and
artifacts while ECIES-X25519 is named ENC_X25519.
## [Upgrade process](#upgrade-process)
@ -155,5 +158,8 @@ required keys.
described in [signed_images](signed_images.md) to create RSA keys.
* If using ECIES-P256, generate a keypair following steps similar to those
described in [signed_images](signed_images.md) to create ECDSA256 keys.
* If using ECIES-X25519, generate a private key passing the option `-t x25519`
to `imgtool keygen` command. To generate public key PEM file the following
command can be used: `openssl pkey -in <generated-private-key.pem> -pubout`
* If using AES-KW-128 (`newt` only), the `kek` can be generated with a
command like `dd if=/dev/urandom bs=1 count=16 | base64 > my_kek.b64`