docs: Update with X25519 encrypted images info
Signed-off-by: Fabio Utzig <utzig@apache.org>
diff --git a/docs/design.md b/docs/design.md
index e1045ad..5ff22d1 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -107,7 +107,8 @@
#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 */
```
diff --git a/docs/encrypted_images.md b/docs/encrypted_images.md
index 8901cbf..497634a 100644
--- a/docs/encrypted_images.md
+++ b/docs/encrypted_images.md
@@ -71,22 +71,24 @@
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 @@
* 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 @@
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`