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.

Note

Building the keywriter has only been tested with version 09.00.00.35 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 <MCU_PLUS_SDK_DIRECTORY>/source/security.

Before we begin programming keys, we need to make one change to the source code. In <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/am64x-evm/r5fss0-0_nortos/main.c remove line 61:

-    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 <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/scripts/cert_gen/am64x and run

host:~$ ./gen_keywr_cert.sh -g

This will create a set of five keys in the 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.

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 the previous step, we can now generate a keywriter to sign our hardware and enable secure boot. Go to <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/scripts/cert_gen/am64x and run the following:

host:~$ ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem --msv 0xC0FFE -s keys_devel/smpk.pem --smek keys_devel/smek.key --keycnt 1 --keyrev 1

Note

If necessary you can write protect these fields using --msv-wp -s-wp --smek-wp --keycnt-wp and --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 <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/scripts/cert_gen/am64x directory where we left off:

host:~$ cd ../../x509cert
host:~$ python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT
host:~$ cd ../../am64x-evm/r5fss0-0_nortos/ti-arm-clang/
host:~$ make -sj PROFILE=debug clean
host:~$ make -sj PROFILE=debug

The keywriter has now been built and is the tiboot3.bin file in <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/am64x-evm/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 <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/scripts/cert_gen/am64x, generate the first keywriter for the Model Specific Value (MSV):

MSV
host:~$ ./gen_keywr_cert.sh --msv 0xC0FFE -t tifek/ti_fek_public.pem
host:~$ cd ../../x509cert
host:~$ python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT
host:~$ cd ../../am64x-evm/r5fss0-0_nortos/ti-arm-clang/
host:~$ make -sj PROFILE=debug clean
host:~$ make -sj PROFILE=debug

Note

To write protect the MSV, use --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 tiboot3.bin file in <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/am64x-evm/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,

host:~$ cd ../../../scripts/cert_gen/am64x/

Now we can generate the next keywriter for the SMPK and SMEK:

SMPK and SMEK
host:~$ ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem -s keys/smpk.pem --smek keys/smek.key
host:~$ cd ../../x509cert
host:~$ python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT
host:~$ cd ../../am64x-evm/r5fss0-0_nortos/ti-arm-clang/
host:~$ make -sj PROFILE=debug clean
host:~$ make -sj PROFILE=debug

Note

To write protect the SMPK and SMEK, use -s-wp and --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 tiboot3.bin file in <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/am64x-evm/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,

host:~$ cd ../../../scripts/cert_gen/am64x/

Next we will generate the keywriter for the key count:

Key Count
host:~$ ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem --keycnt 1
host:~$ cd ../../x509cert
host:~$ python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT
host:~$ cd ../../am64x-evm/r5fss0-0_nortos/ti-arm-clang/
host:~$ make -sj PROFILE=debug clean
host:~$ 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 tiboot3.bin file in <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/am64x-evm/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,

host:~$ cd ../../../scripts/cert_gen/am64x/

Finally we can generate the keywriter for the key revision:

Key Revision
host:~$ ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem --keyrev 1
host:~$ cd ../../x509cert
host:~$ python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT
host:~$ cd ../../am64x-evm/r5fss0-0_nortos/ti-arm-clang/
host:~$ make -sj PROFILE=debug clean
host:~$ make -sj PROFILE=debug

Note

To write protect the key revision, use --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 tiboot3.bin file in <MCU_PLUS_SDK_DIRECTORY>/source/security/sbl_keywriter/am64x-evm/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 Pre-Built Binaries and flashing it to the card by following the guide in the SD Card boot documentation. Once you have your bootable SD card, copy the 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 JP5 to pins 1 and 2 on the development kit in order to flash the keys.

phyCORE-AM64x JP5

Once this jumper 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.