Commit e542295f authored by Dominik Ermel's avatar Dominik Ermel Committed by Dominik Ermel
Browse files

doc: Add information on supporting SHA512 with ECIES-X25519



Information on TLV and format.

Signed-off-by: default avatarDominik Ermel <dominik.ermel@nordicsemi.no>
parent 7de064ea
Loading
Loading
Loading
Loading
+15 −6
Original line number Diff line number Diff line
@@ -92,24 +92,33 @@ libraries. The whole key encryption can be summarized as:
  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
  are not using a `salt` and using an `info` of `MCUBoot_ECIES_v1`, generating
  48 bytes of key material.
* Derive the new keys from the secret using HKDF. We are not using a `salt`
  and using an `info` of `MCUBoot_ECIES_v1`, generating 48 bytes of key material.
* A new random encryption key is generated (for AES). This is
  the AES key used to encrypt the images.
* The key is encrypted with AES-128-CTR or AES-256-CTR and a `nonce` of 0 using
  the first 16 bytes of key material generated previously by the HKDF.
* The encrypted key now goes through a HMAC-SHA256 using the remaining 32
* The encrypted key now goes through a HMAC using the remaining 32
  bytes of key material from the HKDF.

There are different TLVs for ECIES-P256, ECIES-X25519 with SHA256 HKDF/HMAC
and ECIES-X25519 with SHA512 HKDF/HMAC.
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 or 32 bytes of the encrypted key, resulting in
a TLV of 113 or 129 bytes for ECIES-P256 and 80 or 96 bytes for ECIES-X25519.
MAC tag and the 16 or 32 bytes of the encrypted key, resulting in final TLV
length:
 * ECIES-P256 has TLV length 113 to 129 bytes, depending on AES key length.
 * ECIES-X25519 on SHA256 TLV length is 80 or 96 bytes, depending on AES key
   length.
 * ECIES-X25519 on SHA512 TLV length is 112 or 128, depending on AES key
   length.

The implemenation of ECIES-P256 is named ENC_EC256 in the source code and
artifacts while ECIES-X25519 is named ENC_X25519.

Note that MCUboot is built to support only one ECIES and HMAC SHA at once,
and truncated HMAC is not supported at this time

## [Upgrade process](#upgrade-process)

When starting a new upgrade process, `MCUboot` checks that the image in the