diff --git a/docs/design/trusted-board-boot-build.rst b/docs/design/trusted-board-boot-build.rst index caf367b66..1cc1ba65e 100644 --- a/docs/design/trusted-board-boot-build.rst +++ b/docs/design/trusted-board-boot-build.rst @@ -54,16 +54,34 @@ images with support for these features: On Juno board, the default value corresponds to an ECDSA-SECP256R1 public key hash, whose private part is not currently available. - - ``ARM_ROTPK_LOCATION=devel_rsa``: use the default hash located in - ``plat/arm/board/common/rotpk/arm_rotpk_rsa_sha256.bin``. Enforce - generation of the new hash if ``ROT_KEY`` is specified. + - ``ARM_ROTPK_LOCATION=devel_rsa``: the ROTPK is a hash of the + RSA public key corresponding to the private key specified by + ``ROT_KEY``. If ``ROT_KEY`` is not specified, the private key is + the development key ``plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem``. + There are also 3k and 4k RSA development keys in ``plat/arm/board/common/rotpk/``. + The hashing algorithm is selected by ``HASH_ALG``; sha256 is used if + ``HASH_ALG`` is not specified. - - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the default hash located in - ``plat/arm/board/common/rotpk/arm_rotpk_ecdsa_sha256.bin``. Enforce - generation of the new hash if ``ROT_KEY`` is specified. + - ``ARM_ROTPK_LOCATION=devel_ecdsa``: the ROTPK is a hash of the + ECDSA public key corresponding to the private key specified by + ``ROT_KEY``. If ``ROT_KEY`` is not specified, the private key is + the development key ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa.pem`` by default, + a 384 bit key ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa_secp384r1.pem`` also exists, + and can be specified by ``ROT_KEY``. The hashing algorithm is selected by ``HASH_ALG``; + sha256 is used if ``HASH_ALG`` is not specified. - - ``ARM_ROTPK_LOCATION=devel_full_dev_rsa_key``: use the key located in - ``plat/arm/board/common/rotpk/arm_full_dev_rsa_rotpk.S``. + - ``ARM_ROTPK_LOCATION=devel_full_dev_rsa_key``: the ROTPK is an unhashed + RSA public key corresponding to the private key specified by ``ROT_KEY``. + If ``ROT_KEY`` is not specified, the private key is the development key + ``plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem``. There are also + 3k and 4k RSA development keys in ``plat/arm/board/common/rotpk/``. + + - ``ARM_ROTPK_LOCATION=devel_full_dev_ecdsa_key``: the ROTPK is an unhashed + RSA public key corresponding to the private key specified by ``ROT_KEY``. + If ``ROT_KEY`` is not specified, the private key is the development key + ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa.pem``, a 384 bit key + ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa_secp384r1.pem`` also exists, + and can be specified by ``ROT_KEY``. Example of command line using RSA development keys: @@ -119,7 +137,7 @@ images with support for these features: -------------- -*Copyright (c) 2019-2022, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2024, Arm Limited. All rights reserved.* .. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git .. _mbed TLS Security Center: https://tls.mbed.org/security diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst index f10d2e72c..f3e094ce8 100644 --- a/docs/design/trusted-board-boot.rst +++ b/docs/design/trusted-board-boot.rst @@ -39,7 +39,8 @@ The implicitly trusted components forming the trust anchor are: - A Root of Trust Public Key (ROTPK), or a hash of it. - On Arm development platforms, a SHA-256 hash of the ROTPK is stored in the + On Arm development platforms, a hash of the ROTPK (hash algorithm selected by + the ``HASH_ALG`` build option, with sha256 as default) is stored in the trusted root-key storage registers. Alternatively, a development ROTPK might be used and its hash embedded into the BL1 and BL2 images (only for development purposes). @@ -330,7 +331,7 @@ Instructions for building and using the tool can be found in the -------------- -*Copyright (c) 2015-2020, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2015-2024, Arm Limited and Contributors. All rights reserved.* .. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt .. _Trusted Board Boot Requirements (TBBR): https://developer.arm.com/docs/den0006/latest diff --git a/docs/plat/arm/arm-build-options.rst b/docs/plat/arm/arm-build-options.rst index afbb15767..a086a98db 100644 --- a/docs/plat/arm/arm-build-options.rst +++ b/docs/plat/arm/arm-build-options.rst @@ -65,25 +65,26 @@ Arm Platform Build Options - ``regs`` : return the ROTPK hash stored in the Trusted root-key storage registers. - ``devel_rsa`` : return a development public key hash embedded in the BL1 - and BL2 binaries. This hash has been obtained from the RSA public key - ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. To use - this option, ``arm_rotprivk_rsa.pem`` must be specified as ``ROT_KEY`` - when creating the certificates. + and BL2 binaries. This hash corresponds to the development private key + ``plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem``. + The hashing algorithm is selected by ``HASH_ALG``; sha256 is used if + ``HASH_ALG`` is not specified. A different RSA key can be specified by setting + ``ROT_KEY``, there are 3k and 4k RSA keys in ``plat/arm/board/common/rotpk/``. - ``devel_ecdsa`` : return a development public key hash embedded in the BL1 - and BL2 binaries. This hash has been obtained from the ECDSA public key - ``arm_rotpk_ecdsa.der``, located in ``plat/arm/board/common/rotpk``. To - use this option, ``arm_rotprivk_ecdsa.pem`` must be specified as - ``ROT_KEY`` when creating the certificates. - - ``devel_full_dev_rsa_key`` : returns a development public key embedded in - the BL1 and BL2 binaries. This key has been obtained from the RSA public - key ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. - -- ``ARM_ROTPK_HASH``: used when ``ARM_ROTPK_LOCATION=devel_*``, excluding - ``devel_full_dev_rsa_key``. Specifies the location of the ROTPK hash. Not - expected to be a build option. This defaults to - ``plat/arm/board/common/rotpk/*_sha256.bin`` depending on the specified - algorithm. Providing ``ROT_KEY`` enforces generation of the hash from the - ``ROT_KEY`` and overwrites the default hash file. + and BL2 binaries. This hash corresponds to the development private key + ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa.pem`` unless a different key + is specified with ``ROT_KEY``, such as the 384 bit key in the same directory. + he hashing algorithm is selected by ``HASH_ALG``; sha256 is used if ``HASH_ALG`` + is not specified. + - ``devel_full_dev_rsa_key`` : return a development public key embedded in + the BL1 and BL2 binaries. This key corresponds to the RSA private + key ``plat/arm/board/common/rotpk/arm_rotprivk.pem`` by default, but can + be changed by setting ``ROT_KEY``, there are 3k and 4k RSA keys in + ``plat/arm/board/common/rotpk/``. + - ``devel_full_dev_ecdsa_key`` : return a development public key embedded in + the BL1 and BL2 binaries. This key corresponds to the EC private key + ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa.pem``, unless a different + ECDSA key is specified by ``ROT_KEY``, such as the 384 bit key in the same directory. - ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options: