signature.rst documents the RSA key workflow and lists CONFIG_ECDSA, but says nothing about creating ECDSA keys or about what is needed to verify an ECDSA-signed image at run time. The latter is a trap: CONFIG_ECDSA_VERIFY alone leaves verification failing with -ENODEV unless the board supplies a UCLASS_ECDSA driver.
Add a section on creating an ECDSA key pair and document CONFIG_ECDSA_VERIFY, CONFIG_ECDSA_VERIFY_MBEDTLS and the per-curve options along with the driver requirement. Signed-off-by: Ayoub Zaki <[email protected]> --- doc/usage/fit/signature.rst | 38 +++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/usage/fit/signature.rst b/doc/usage/fit/signature.rst index da08cc75c3a..cbe660c1376 100644 --- a/doc/usage/fit/signature.rst +++ b/doc/usage/fit/signature.rst @@ -82,6 +82,26 @@ If you like you can look at the public key also:: $ openssl rsa -in keys/dev.key -pubout +Creating an ECDSA key pair +-------------------------- +To create a new key pair on the NIST P-256 curve, used by the "ecdsa256" +signature algorithm:: + + $ openssl ecparam -name prime256v1 -genkey -noout -out keys/dev.key + +For the "ecdsa384" algorithm, use the P-384 curve instead:: + + $ openssl ecparam -name secp384r1 -genkey -noout -out keys/dev.key + +As with RSA the key is read from '<name>.key' where <name> comes from the +'key-name-hint' property of the signature node. + +No certificate is needed. The RSA signer reads the public key from a +'<name>.crt' certificate but mkimage takes the ECDSA public key from the +private key file itself. Either way only the raw key parameters end up in +the control DTB so a certificate is never stored in U-Boot. + + Public Key Storage ------------------ In order to verify an image that has been signed with a public key we need to @@ -432,6 +452,24 @@ CONFIG_RSA CONFIG_ECDSA enable ECDSA algorithm for signing +CONFIG_ECDSA_VERIFY + enable ECDSA signature verification in U-Boot + +CONFIG_ECDSA_VERIFY_MBEDTLS + provide ECDSA verification in software, using the MbedTLS ECP library + +Unlike RSA, which always has a software implementation available ECDSA +verification is performed by a UCLASS_ECDSA driver. Enabling +CONFIG_ECDSA_VERIFY on its own is not enough: a driver must be present or +verification fails with -ENODEV at boot. Boards with a suitable crypto engine +or ROM API can supply their own driver; everything else should enable +CONFIG_ECDSA_VERIFY_MBEDTLS which needs CONFIG_MBEDTLS_LIB. + +The elliptic-curve code is sizeable, so the curves are selected individually +and a board only pays for the ones it uses. CONFIG_MBEDTLS_ECP_DP_SECP256R1 +(for "ecdsa256") is enabled by default; CONFIG_MBEDTLS_ECP_DP_SECP384R1 (for +"ecdsa384") must be enabled explicitly. + WARNING: When relying on signed FIT images with required signature check the legacy image format is default disabled by not defining CONFIG_LEGACY_IMAGE_FORMAT -- 2.43.0
