.. _OTPKeywriter-62: .. include:: ../substitutions.rst OTP Keywriter ============= The keys are flashed to the hardware using the One Time Programmable (OTP) Keywriter. Installing the SDK ------------------ To create a copy of the OTP Keywriter that includes your own keys, you will need TI's MCU Plus SDK, CCS, SYSCONFIG, and the keywriter source code. * MCU Plus SDK for AM62x (09.01.00.39): https://www.ti.com/tool/download/MCU-PLUS-SDK-AM62X/09.01.00.39 * CCS (12.2.0): https://www.ti.com/tool/download/CCSTUDIO/12.2.0 * SYSCONFIG (1.15): https://www.ti.com/tool/download/SYSCONFIG/1.15.0.2826 * Keywriter source code must be requested from the AM62X-RESTRICTED-SW section of the AM62x downloads page: https://www.ti.com/tool/PROCESSOR-SDK-AM62X .. note:: Building the keywriter has only been tested with version 09.01.00.39 of the MCU Plus SDK and may not work with other versions. Once you have the MCU Plus SDK set up, install the keywriter source to :code:`/source/security`. Before we begin programming keys, we need to make one change to the source code. In :code:`/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/main.c` remove line 57: .. code-block:: - keywriter_setVpp(); This is because there is a pin on the SoC that needs to be set high to write keys, and TI does this using I2C on their boards which requires this function to run. We will set this pin using a jumper on our board. Generating keys --------------- The keywriter source comes with a tool to help generate your own keys. To generate keys, go to :code:`/source/security/sbl_keywriter/scripts/cert_gen/am62x` and run .. code-block:: console :substitutions: |host-prompt| ./gen_keywr_cert.sh -g This will create a set of five keys in the :code:`keys/` directory. You can use the keywriter to flash these keys to your hardware and you will need to keep them safe to use for signing your images as well. PHYTEC keys ----------- If you wish to use the PHYTEC dummy keys to sign your SoM, they are locating in phytec-dev-ca. phytec-dev-ca is stored in the yocto directory that you use to generate images, or you can get the source here: https://github.com/phytec/phytec-dev-ca Building the Keywriter ---------------------- There are two methods for creating the keywriter. You can create one keywriter that contains all of your keys, or you can make one keywriter per key. The all at once approach is more straightforward, but if your key certificates end up too large you may need to use the incremental approach. All at Once ~~~~~~~~~~~ Using the keys generated in a previous step or the PHYTEC dummy keys, we can now generate a keywriter to sign our hardware and enable secure boot. Go to :code:`/source/security/sbl_keywriter/scripts/cert_gen/am62x` and run the following: .. code-block:: console :substitutions: |host-prompt| ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem --msv 0xC0FFE -s --smek --keycnt 1 --keyrev 1 .. note:: If necessary you can write protect these fields using :code:`--msv-wp` :code:`-s-wp` :code:`--smek-wp` :code:`--keycnt-wp` and :code:`--keyrev-wp`, but this should only be done if necessary. This generates a certificate containing our keys (primary_cert.bin). We have left out the bmek and bmpk for now because with them included the certificate would exceed the 5400 byte limit. These are backup keys and are completely optional. To generate the binary itself, run the following commands, starting from the :code:`/source/security/sbl_keywriter/scripts/cert_gen/am62x` directory where we left off: .. code-block:: console :substitutions: |host-prompt| cd ../../x509cert |host-prompt| python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT |host-prompt| cd ../../am62x-sk/r5fss0-0_nortos/ti-arm-clang/ |host-prompt| make -sj PROFILE=debug clean |host-prompt| make -sj PROFILE=debug The keywriter has now been built and is the :code:`tiboot3.bin` file in :code:`/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang` Incremental ~~~~~~~~~~~ If you end up with a certificate exceeding 5400 bytes while trying to build and program all the keys at once, you may need to flash the keys incrementally. To do this you will need separate certificates for each key. Starting in :code:`/source/security/sbl_keywriter/scripts/cert_gen/am62x`, generate the first keywriter for the Model Specific Value (MSV): .. code-block:: console :caption: MSV :substitutions: |host-prompt| ./gen_keywr_cert.sh --msv 0xC0FFE -t tifek/ti_fek_public.pem |host-prompt| cd ../../x509cert |host-prompt| python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT |host-prompt| cd ../../am62x-sk/r5fss0-0_nortos/ti-arm-clang/ |host-prompt| make -sj PROFILE=debug clean |host-prompt| make -sj PROFILE=debug .. note:: To write protect the MSV, use :code:`--msv-wp` while generating the certificate in the first command. This is optional and should only be done if necessary. The keywriter for the MSV has now been built and is the :code:`tiboot3.bin` file in :code:`/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang`. Save it elsewhere so that we can build the other keywriters without overwriting this one. Make sure that you keep track of the binaries so that you can flash them in the correct order later. To get back to the starting directory, .. code-block:: console :substitutions: |host-prompt| cd ../../../scripts/cert_gen/am62x/ Now we can generate the next keywriter for the SMPK and SMEK: .. code-block:: console :caption: SMPK and SMEK :substitutions: |host-prompt| ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem -s --smek |host-prompt| cd ../../x509cert |host-prompt| python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT |host-prompt| cd ../../am62x-sk/r5fss0-0_nortos/ti-arm-clang/ |host-prompt| make -sj PROFILE=debug clean |host-prompt| make -sj PROFILE=debug .. note:: To write protect the SMPK and SMEK, use :code:`-s-wp` and :code:`--smek-wp` while generating the certificate in the first command. This is optional and should only be done if necessary. The keywriter for the SMPK and SMEK has now been built and is the :code:`tiboot3.bin` file in :code:`/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang`. Save it elsewhere so that we can build the other keywriters without overwriting this one. Make sure that you keep track of the binaries so that you can flash them in the correct order later. To get back to the starting directory, .. code-block:: console :substitutions: |host-prompt| cd ../../../scripts/cert_gen/am62x/ Next we will generate the keywriter for the key count: .. code-block:: console :caption: Key Count :substitutions: |host-prompt| ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem --keycnt 1 |host-prompt| cd ../../x509cert |host-prompt| python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT |host-prompt| cd ../../am62x-sk/r5fss0-0_nortos/ti-arm-clang/ |host-prompt| make -sj PROFILE=debug clean |host-prompt| make -sj PROFILE=debug .. note:: When writing keys incrementally it is important to not write protect the key count. This would prevent us from being able to write the key revision. The keywriter for the key count has now been built and is the :code:`tiboot3.bin` file in :code:`/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang`. Save it elsewhere so that we can build the other keywriters without overwriting this one. Make sure that you keep track of the binaries so that you can flash them in the correct order later. To get back to the starting directory, .. code-block:: console :substitutions: |host-prompt| cd ../../../scripts/cert_gen/am62x/ Finally we can generate the keywriter for the key revision: .. code-block:: console :caption: Key Revision :substitutions: |host-prompt| ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem --keyrev 1 |host-prompt| cd ../../x509cert |host-prompt| python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT |host-prompt| cd ../../am62x-sk/r5fss0-0_nortos/ti-arm-clang/ |host-prompt| make -sj PROFILE=debug clean |host-prompt| make -sj PROFILE=debug .. note:: To write protect the key revision, use :code:`--keyrev-wp` while generating the certificate in the first command. This is optional and should only be done if necessary. The keywriter for the key count has now been built and is the :code:`tiboot3.bin` file in :code:`/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang`. Make sure that you keep track of the binaries so that you can flash them in the correct order later. Running the Keywriter --------------------- To run the keywriter on your hardware we recommend starting with a regular SD card that has an unsigned image on it. You can get an unsigned image from the |ref-prebuilts| and flashing it to the card by following the guide in the |ref-create-sd| boot documentation. Once you have your bootable SD card, copy the :code:`tiboot3.bin` you generated in the previous step into the boot partition of the SD card, replacing the previous version of the binary. Now we must set JP8 on the development kit in order to flash the keys. .. image:: ../../images/phycore-am62x/pb-07124_secureboot_JP8_J28.webp :width: 700px :alt: phyCORE-AM62x JP8 .. note:: For some older boards we also need to verify that the resistor on J28 is set to position 2+3. Once these jumpers is set, plug the SD card into the kit and boot as you normally would. You should see a message that keywriting was successful. The keywriter will only successfully write one time. If you are using the incremental approach to programming your keys, it is essential that you run your Key Revision binary after all the other binaries have been successfully run. Writing the key revision is what converts the device to a secure boot device, so you will not be able to run your other binaries after the key revision is set.