diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2023-05-10 11:52:05 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2023-05-26 17:32:50 +0100 |
commit | e31de097c25ddf997697c08ba5f77f758ca34f61 (patch) | |
tree | da6f571b2bcc902f6342cc2fae485d6c4d7ea226 /documentation/ref-manual | |
parent | a95cbed77fd2fa2ec263dbdf59bb2aed359d7ce1 (diff) | |
download | poky-e31de097c25ddf997697c08ba5f77f758ca34f61.tar.gz |
ref-manual: document uboot-sign class and variables
(From yocto-docs rev: 221bcf2e32fb42b6527ff0b4cfe0c4591ab89f78)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Jamin Lin <jamin_lin@aspeedtech.com>
CC: Sean Anderson <sean.anderson@seco.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r-- | documentation/ref-manual/classes.rst | 38 | ||||
-rw-r--r-- | documentation/ref-manual/variables.rst | 121 |
2 files changed, 154 insertions, 5 deletions
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 2f96ffb82f..78174d51d1 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst | |||
@@ -3178,6 +3178,44 @@ You can also specify the machine using this method:: | |||
3178 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional | 3178 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional |
3179 | information. | 3179 | information. |
3180 | 3180 | ||
3181 | .. _ref-classes-uboot-sign: | ||
3182 | |||
3183 | ``uboot-sign`` | ||
3184 | ============== | ||
3185 | |||
3186 | The :ref:`ref-classes-uboot-sign` class provides support for U-Boot verified boot. | ||
3187 | It is intended to be inherited from U-Boot recipes. | ||
3188 | |||
3189 | Here are variables used by this class: | ||
3190 | |||
3191 | - :term:`SPL_MKIMAGE_DTCOPTS`: DTC options for U-Boot ``mkimage`` when | ||
3192 | building the FIT image. | ||
3193 | - :term:`SPL_SIGN_ENABLE`: enable signing the FIT image. | ||
3194 | - :term:`SPL_SIGN_KEYDIR`: directory containing the signing keys. | ||
3195 | - :term:`SPL_SIGN_KEYNAME`: base filename of the signing keys. | ||
3196 | - :term:`UBOOT_FIT_ADDRESS_CELLS`: ``#address-cells`` value for the FIT image. | ||
3197 | - :term:`UBOOT_FIT_DESC`: description string encoded into the FIT image. | ||
3198 | - :term:`UBOOT_FIT_GENERATE_KEYS`: generate the keys if they don't exist yet. | ||
3199 | - :term:`UBOOT_FIT_HASH_ALG`: hash algorithm for the FIT image. | ||
3200 | - :term:`UBOOT_FIT_KEY_GENRSA_ARGS`: ``openssl genrsa`` arguments. | ||
3201 | - :term:`UBOOT_FIT_KEY_REQ_ARGS`: ``openssl req`` arguments. | ||
3202 | - :term:`UBOOT_FIT_SIGN_ALG`: signature algorithm for the FIT image. | ||
3203 | - :term:`UBOOT_FIT_SIGN_NUMBITS`: size of the private key for FIT image | ||
3204 | signing. | ||
3205 | - :term:`UBOOT_FIT_KEY_SIGN_PKCS`: algorithm for the public key certificate | ||
3206 | for FIT image signing. | ||
3207 | - :term:`UBOOT_FITIMAGE_ENABLE`: enable the generation of a U-Boot FIT image. | ||
3208 | - :term:`UBOOT_MKIMAGE_DTCOPTS`: DTC options for U-Boot ``mkimage`` when | ||
3209 | rebuilding the FIT image containing the kernel. | ||
3210 | |||
3211 | See U-Boot's documentation for details about `verified boot | ||
3212 | <https://source.denx.de/u-boot/u-boot/-/blob/master/doc/uImage.FIT/verified-boot.txt>`__ | ||
3213 | and the `signature process | ||
3214 | <https://source.denx.de/u-boot/u-boot/-/blob/master/doc/uImage.FIT/signature.txt>`__. | ||
3215 | |||
3216 | See also the description of :ref:`ref-classes-kernel-fitimage` class, which this class | ||
3217 | imitates. | ||
3218 | |||
3181 | .. _ref-classes-uninative: | 3219 | .. _ref-classes-uninative: |
3182 | 3220 | ||
3183 | ``uninative`` | 3221 | ``uninative`` |
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index b7d3c05ce2..b7829ae7af 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst | |||
@@ -2927,7 +2927,7 @@ system and gives an overview of their function and contents. | |||
2927 | The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage` | 2927 | The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage` |
2928 | class, which corresponds to 32 bit addresses. | 2928 | class, which corresponds to 32 bit addresses. |
2929 | 2929 | ||
2930 | For platforms who need to set 64 bit addresses in | 2930 | For platforms that need to set 64 bit addresses, for example in |
2931 | :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to | 2931 | :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to |
2932 | set this value to "2", as two 32 bit values (cells) will be needed | 2932 | set this value to "2", as two 32 bit values (cells) will be needed |
2933 | to represent such addresses. | 2933 | to represent such addresses. |
@@ -7759,6 +7759,32 @@ system and gives an overview of their function and contents. | |||
7759 | section in the Yocto Project Board Support Package Developer's Guide | 7759 | section in the Yocto Project Board Support Package Developer's Guide |
7760 | for additional information. | 7760 | for additional information. |
7761 | 7761 | ||
7762 | :term:`SPL_MKIMAGE_DTCOPTS` | ||
7763 | Options for the device tree compiler passed to ``mkimage -D`` feature | ||
7764 | while creating a FIT image with the :ref:`ref-classes-uboot-sign` | ||
7765 | class. If :term:`SPL_MKIMAGE_DTCOPTS` is not set then the | ||
7766 | :ref:`ref-classes-uboot-sign` class will not pass the ``-D`` option | ||
7767 | to ``mkimage``. | ||
7768 | |||
7769 | The default value is set to "" by the :ref:`ref-classes-uboot-config` | ||
7770 | class. | ||
7771 | |||
7772 | :term:`SPL_SIGN_ENABLE` | ||
7773 | Enable signing of the U-Boot FIT image. The default value is "0". | ||
7774 | This variable is used by the :ref:`ref-classes-uboot-sign` class. | ||
7775 | |||
7776 | :term:`SPL_SIGN_KEYDIR` | ||
7777 | Location of the directory containing the RSA key and certificate used for | ||
7778 | signing the U-Boot FIT image, used by the :ref:`ref-classes-uboot-sign` | ||
7779 | class. | ||
7780 | |||
7781 | :term:`SPL_SIGN_KEYNAME` | ||
7782 | The name of keys used by the :ref:`ref-classes-kernel-fitimage` class | ||
7783 | for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR` | ||
7784 | directory. If we have for example a ``dev.key`` key and a ``dev.crt`` | ||
7785 | certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will | ||
7786 | have to set :term:`SPL_SIGN_KEYNAME` to ``dev``. | ||
7787 | |||
7762 | :term:`SRCREV_FORMAT` | 7788 | :term:`SRCREV_FORMAT` |
7763 | See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual. | 7789 | See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual. |
7764 | 7790 | ||
@@ -9097,16 +9123,101 @@ system and gives an overview of their function and contents. | |||
9097 | creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a | 9123 | creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a |
9098 | command-line parameter to the ``uboot-mkimage`` utility. | 9124 | command-line parameter to the ``uboot-mkimage`` utility. |
9099 | 9125 | ||
9100 | To pass a 64 bit address for FIT image creation, you will need to set | 9126 | To pass a 64 bit address for FIT image creation, you will need to set: |
9101 | the :term:`FIT_ADDRESS_CELLS` variable too. | 9127 | - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. |
9128 | - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. | ||
9129 | |||
9130 | This variable is used by the :ref:`ref-classes-kernel-fitimage`, | ||
9131 | :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, | ||
9132 | :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` | ||
9133 | classes. | ||
9102 | 9134 | ||
9135 | :term:`UBOOT_FIT_ADDRESS_CELLS` | ||
9136 | Specifies the value of the ``#address-cells`` value for the | ||
9137 | description of the U-Boot FIT image. | ||
9138 | |||
9139 | The default value is set to "1" by the :ref:`ref-classes-uboot-sign` | ||
9140 | class, which corresponds to 32 bit addresses. | ||
9141 | |||
9142 | For platforms that need to set 64 bit addresses in | ||
9143 | :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to | ||
9144 | set this value to "2", as two 32 bit values (cells) will be needed | ||
9145 | to represent such addresses. | ||
9146 | |||
9147 | Here is an example setting "0x400000000" as a load address:: | ||
9148 | |||
9149 | UBOOT_FIT_ADDRESS_CELLS = "2" | ||
9150 | UBOOT_LOADADDRESS= "0x04 0x00000000" | ||
9151 | |||
9152 | See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. | ||
9153 | |||
9154 | :term:`UBOOT_FIT_DESC` | ||
9155 | Specifies the description string encoded into a U-Boot fitImage. The default | ||
9156 | value is set by the :ref:`ref-classes-uboot-sign` class as follows:: | ||
9157 | |||
9158 | UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" | ||
9159 | |||
9160 | :term:`UBOOT_FIT_GENERATE_KEYS` | ||
9161 | Decides whether to generate the keys for signing the U-Boot fitImage if | ||
9162 | they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`. | ||
9163 | The default value is "0". | ||
9164 | |||
9165 | Enable this as follows:: | ||
9166 | |||
9167 | UBOOT_FIT_GENERATE_KEYS = "1" | ||
9168 | |||
9169 | This variable is used in the :ref:`ref-classes-uboot-sign` class. | ||
9170 | |||
9171 | :term:`UBOOT_FIT_HASH_ALG` | ||
9172 | Specifies the hash algorithm used in creating the U-Boot FIT Image. | ||
9173 | It is set by default to ``sha256`` by the :ref:`ref-classes-uboot-sign` | ||
9174 | class. | ||
9175 | |||
9176 | :term:`UBOOT_FIT_KEY_GENRSA_ARGS` | ||
9177 | Arguments to ``openssl genrsa`` for generating a RSA private key for | ||
9178 | signing the U-Boot FIT image. The default value of this variable | ||
9179 | is set to "-F4" by the :ref:`ref-classes-uboot-sign` class. | ||
9180 | |||
9181 | :term:`UBOOT_FIT_KEY_REQ_ARGS` | ||
9182 | Arguments to ``openssl req`` for generating a certificate for signing | ||
9183 | the U-Boot FIT image. The default value is "-batch -new" by the | ||
9184 | :ref:`ref-classes-uboot-sign` class, "batch" for | ||
9185 | non interactive mode and "new" for generating new keys. | ||
9186 | |||
9187 | :term:`UBOOT_FIT_KEY_SIGN_PKCS` | ||
9188 | Format for the public key certificate used for signing the U-Boot FIT | ||
9189 | image. The default value is set to "x509" by the | ||
9190 | :ref:`ref-classes-uboot-sign` class. | ||
9191 | |||
9192 | :term:`UBOOT_FIT_SIGN_ALG` | ||
9193 | Specifies the signature algorithm used in creating the U-Boot FIT Image. | ||
9194 | This variable is set by default to "rsa2048" by the | ||
9195 | :ref:`ref-classes-uboot-sign` class. | ||
9196 | |||
9197 | :term:`UBOOT_FIT_SIGN_NUMBITS` | ||
9198 | Size of the private key used in signing the U-Boot FIT image, in number | ||
9199 | of bits. The default value for this variable is set to "2048" | ||
9200 | by the :ref:`ref-classes-uboot-sign` class. | ||
9201 | |||
9202 | :term:`UBOOT_FITIMAGE_ENABLE` | ||
9203 | This variable allows to generate a FIT image for U-Boot, which is one | ||
9204 | of the ways to implement a verified boot process. | ||
9205 | |||
9206 | Its default value is "0", so set it to "1" to enable this functionality:: | ||
9207 | |||
9208 | UBOOT_FITIMAGE_ENABLE = "1" | ||
9209 | |||
9210 | See the :ref:`ref-classes-uboot-sign` class for details. | ||
9211 | |||
9103 | :term:`UBOOT_LOADADDRESS` | 9212 | :term:`UBOOT_LOADADDRESS` |
9104 | Specifies the load address for the U-Boot image. During U-Boot image | 9213 | Specifies the load address for the U-Boot image. During U-Boot image |
9105 | creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a | 9214 | creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a |
9106 | command-line parameter to the ``uboot-mkimage`` utility. | 9215 | command-line parameter to the ``uboot-mkimage`` utility. |
9107 | 9216 | ||
9108 | To pass a 64 bit address for FIT image creation, you will need to set | 9217 | To pass a 64 bit address, you will also need to set: |
9109 | the :term:`FIT_ADDRESS_CELLS` variable too. | 9218 | |
9219 | - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. | ||
9220 | - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. | ||
9110 | 9221 | ||
9111 | This variable is used by the :ref:`ref-classes-kernel-fitimage`, | 9222 | This variable is used by the :ref:`ref-classes-kernel-fitimage`, |
9112 | :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, | 9223 | :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, |