Added documentation on FLASH_OTP_KEYSTORE

Author: danielinux

docs/Targets.md

@@ -850,6 +850,11 @@ arm-none-eabi-gdb
 Like [STM32L5](#stm32l5) and [STM32U5](#stm32u5), STM32H5 support is also demonstrated
 through different scenarios.
 
+Additionally, wolfBoot can be compiled with `FLASH_OTP_KEYSTORE` option, to store
+the public key(s) used for firmware authentication into a dedicated, one-time
+programmable flash area that can be write protected.
+For more information, see [/docs/flash-OTP.md](/docs/flash-OTP.md).
+
 ### Scenario 1: TrustZone enabled, staging non-secure application
 
 #### Example description

docs/compile.md

@@ -279,6 +279,10 @@ You can also manually override the fill bytes using `FILL_BYTE=` at build-time.
 
 Note: if you are using an external FLASH (e.g. SPI) in combination with a flash with inverted logic, ensure that you store all the flags in one partition, by using the `FLAGS_HOME=1` option described above.
 
+### Using One-time programmable (OTP) flash as keystore
+
+By default, keys are directly incorporated in the firmware image. To store the keys in a separate, one-time programmable (OTP) flash memory, use the `FLASH_OTP_KEYSTORE=1` option.
+For more information, see [/docs/OTP-keystore.md](/docs/OTP-keystore.md).
 
 ### Using Mac OS/X
 

docs/flash-OTP.md

@@ -0,0 +1,44 @@
+## Using One-Time Programmable (OTP) flash area for keystore
+
+Some microcontrollers provide a special area in flash memory that can
+only be written once and cannot be erased.
+
+This feature comes particularly handy when you want to store the public keys required
+to authenticate the firmware update images, which has exactly the same requirements. A public
+key is a cryptographic key that can be freely distributed and is used to verify the signature
+of the firmware update image. By storing the public keys in the OTP area, you can ensure that
+they are immutable and cannot be tampered with.
+
+### Compiling wolfBoot to access OTP as keystore
+
+To use the OTP area as a keystore, you need to compile wolfBoot with the `FLASH_OTP_KEYSTORE`
+option enabled. This option is disabled by default, which means that the keystore is incorporated into
+the wolfBoot binary itself.
+
+When wolfBoot uses the OTP area as a keystore, it reads the public keys from the OTP area at runtime.
+The public keys are stored in the OTP area, after an initial 16-byte header that contains the number of
+keys stored, the size of each key, and other information.
+
+In order for wolfBoot to start authenticating the firmware images at boot and upon update, the public keys
+must be provisioned to the OTP area in a separate step, as described in the next section.
+
+### Provisioning the public keys to the OTP area
+
+After enabling the `FLASH_OTP_KEYSTORE` option in your `.config` file, when you compile wolfBoot by running "make",
+an additional application called `otp-keystore-primer` is generated under `tools/keytools/otp`. This application is used to
+provision the public keys to the OTP area. By flashing this application to the microcontroller, the public keys contained 
+in your keystore (previously generated by `keygen`) are written to the OTP area.
+
+The `otp-keystore-primer` application is generated with the public keys embedded in it. The keys are retrieved from the `keystore.c` file,
+generated by the `keygen` command. The `otp-keystore-primer` application reads the public keys from the `keystore.c` file and writes them to the OTP area.
+
+After generating a new `keystore.c` with the `keygen` application, you can generate the `otp-keystore-primer` application again, by running `make otp`.
+
+> [!WARNING]
+> The `otp-keystore-primer` application is a one-time use application. Once the application runs on your target, the public keys are written to the OTP area,
+> and it will be impossible to erase them. Therefore, it is important to ensure that the public keys are correct before provisioning them to the OTP area,
+> and that the associated private keys are stored securely. Accidentally losing the private keys will render the public keys stored in the OTP area useless.
+
+> [!CAUTION]
+> ** Be very careful when using the `otp-keystore-primer` application. Use it at your own risk. **
+

tools/keytools/otp/README.md

@@ -0,0 +1,6 @@
+## OTP keystore primer application
+
+This application is used to provision the public keys into a dedicated FLASH OTP
+area. For more information about its usage, please refer to [/docs/flash-OTP.md](/docs/flash-OTP.md).
+
+