.. |br| raw:: html

   <br/>

.. _qsmp15-bsp-secure-boot:

Secure Boot
===========

How to perform Secure Boot on QSMP-15* module
---------------------------------------------

The purpose of this article is to explain how to perform a secure boot on our STM32MP15/QSMP-15* modules.
For detailed information, please refer to `STM Wiki - Secure Boot`_ .


Create signature key
~~~~~~~~~~~~~~~~~~~~

Use the STM32_KeyGen_CLI tool (`KeyGen tool`_) to create the keys.

.. prompt::
    :prompts: #

    STM32_KeyGen_CLI -abs <output directory> -pwd <password> -n <number of key>

With

* <output directory> = Patch to the generated private and public key files (privateKey.pem and publicKey*.pem).
* <password> = Password of the private key. The password must contain at least four characters.
* <number of key> = Number of key pairs, one for STM32MP15.

E.g.

.. prompt::
    :prompts: #

    STM32_KeyGen_CLI -abs stm32mp15-key/ -pwd password -n 1


Refer to `Creating signature key`_ for key generation.


Copy the keys into the BSP directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default the key directory is set to *${BSPDIR}/private/keys*. 
When performing secure boot, create this directory and copy the keys into this directory.
Alternatively set the variable *SB_KEYS_DIR* in your local.conf to your keys directory.


Putting signature key on the module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note:: For demonstration and test purposes, the signature key can be put on the module with a simple U-Boot command on the board. 
    For production purposes, it must be set in the production step, as described in `Secure Secret Provisioning`_ (SSP) overview.

To manually put the public key hash (PKH) on the module with a U-Boot stm32key command:

    * Put the Public Key Hash file (publicKeysHashHashes.bin), generated as described in the previous section, on the bootfs partition.
      Use *ums 0 mmc 0:2* in u-boot and copy the Hash to the usb device on your host.
    * Boot the board and stop on the U-Boot console.
    * Load public key hash in DDR.


For example: 

.. prompt::
    :prompts: #

    load mmc 0:2 ${loadaddr} publicKeysHashHashes.bin
    stm32key fuse ${loadaddr}


Set variables and build the image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note:: You need to install the STM Signing Tool on your host: `STM32 Signing Tool`_

* Set the following variables in your local.conf

    .. code-block:: text

        SIGN_KEY = "privateKey00.pem"
        SIGN_KEY_PASS = "your password"
        SIGN_PUB_KEY = "publicKey00.pem"
        SIGN_ENABLE = "1"
        SIGN_TOOL = "<path-to-sign-tool>/STM32_SigningTool_CLI>" 

    Replace the key names to make them fit with your keys.

* Build the image:

    .. prompt::
        :prompts: #

        bitbake karo-image-minimal



* Flash the module and reset it. You should see the following messages on the serial interface:

    .. code-block:: text

        NOTICE:  Bootrom authentication succeeded
        NOTICE:  TRUSTED_BOARD_BOOT support enabled


.. _`STM Wiki - Secure Boot`: https://wiki.st.com/stm32mpu/wiki/How_to_perform_Secure_Boot_from_Distribution_Package
.. _`Creating signature key`: https://wiki.st.com/stm32mpu/wiki/How_to_perform_Secure_Boot_from_Distribution_Package#Creating_signature_key
.. _`KeyGen tool`: https://wiki.st.com/stm32mpu/wiki/KeyGen_tool
.. _`Secure Secret Provisioning`: https://wiki.st.com/stm32mpu/wiki/Secure_Secret_Provisioning_(SSP)_overview
.. _`Download Area`: https://www.karo-electronics.com/downloads
.. _`STM32 Signing Tool`: https://wiki.st.com/stm32mpu/wiki/Signing_tool#STM32_Signing_Tool_install