Examples#

Enable Encrypted XiP in Devices With External Flash#

Initialize PUF intrinsic keys.
```
commander manufacturing init --mbr default
```
Power Off and on the device to ensure the PUF takes effect.
Generate key configuration file with following command
```
commander util genkeyconfig --outfile keys.json --device Si917
```
Keys.json file will contain keys for signing the firmware image and keys for decrypting the image during OTA and keys for secure boot.
You can generate your own keys. It is highly recommended to secure these keys. Once written, the keys remain permanently in the device. If private keys are leaked or lost, the device can no longer be upgraded and becomes vulnerable to compromise.
Note: The keys inside keys.json are used only for encrypting, signing and MIC calculations during OTA process.Intrinsic keys which are generated during PUF initialization are used to encrypt/decrypt FLASH contents.These keys will not be available to the user by any means.

Set e-fuses as shown in AES-CTR Configuration and AES-XTS Configuration, write keys, and efuses into device with this command.

commander manufacturing provision --keys keys.json --data mbrEfuses.json

Sample mbrEfuses.json file as shown below

 {
     "puf_activation_code_addr": 8192,
      "efuse_data":
    {
         "m4_encrypt_firmware": 1,
         "m4_fw_encryption_mode": 1,
         “ta_encrypt_firmware”:1,
         "m4_secure_boot_enable": 1,
         “ta_secure_boot_enable”: 1
     },
     "key_desc_table_addr": 768
 }

Download the latest WiseConnect SDK from Silicon labs website. WiseConnect SDK is firmware for NWP processors. Please refer to this page for more details about WiseConnect.
Since secure boot is enabled, si917 device expects minimum MIC computed image. But Si917 bootloader is intelligent and flexible enough to accept a signed, encrypted and MIC computed image to be flashed into the device.
Use following commands to encrypt, sign and compute MIC for application and NWP images.
```
commander rps convert applicationSigned.rps --app applicaiton.rps --mic keys.json --encrypt keys.json --sign keys.json
commander rps convert NWPFirmwarSigned.rps --taapp NWPFirmware.rps --mic keys.json --encrypt keys.json --sign keys.json
```
Flash both singed and encrypted images into the device using following commands
```
commander rps load applicationSigned.rps -d si917
commander rps load NWPFirmwarSigned.rps -d si917
```
After flashing the images, the user should see their application is running.

Enable Encrypted XiP in Devices With External PSRAM#

As mentioned in the Introduction section, to execute some AI/ML algorithms and to drive displays internal RAM of a chip is not sufficient. So, an external PSRAM is added. In some cases, code is made to run from PSRAM. Since both code and data reside in external PSRAM, if PSRAM contents are not encrypted bad actor can easily tamper the contents. So SiWx917 has a feature that encrypts code and data while writing/updating into PSRAM and decrypts the contents back before using or executing the contents.

Note: Only configured memory regions are encrypted.

Following are the steps for enabling encrypted XiP in PSRAM.

Initialize PUF intrinsic keys. (This is one time process. If it is already done , no need to do again)
```
commander manufacturing init --mbr default
```
Power Off and on the device to ensure the PUF takes effect.
Generate key configuration file with following command. If keys are already available, this step is not required
```
commander util genkeyconfig --outfile keys.json --device Si917
```

Set MBR configuraiton as shown further. You can configure 4 sections of PSRAM to enable security. psram_section_start_add, psram_section_start_add fuses contains starting and end address of section which needs to be protected.

Note: Address range must be given only in decimal format.

Use this command to update keys and efuses

commander manufacturing provision --keys keys.json --data mbr_security_PSRAM.json

Sample mbr_security_PSRAM file is shown further

{
    "puf_activation_code_addr": 8192,
    "valids":
    {
        "psram_security_segments_valid":1
    },
    "psram_section_start_add":[
        0,
        1048576,
        2097152,
        3145728
    ]
    "psram_section_end_add":[
        1048575,
        2097151,
        3145727,
        4194303
    ],
    "key_desc_table_addr": 768
}

Build a sample app, such as “psram_blinky” found https://github.com/SiliconLabs/wiseconnect/tree/master/exam-ples/si91x_soc/peripheral/psram_blinky, as well as in the WiSeConnect SDK available in the Simplicity Studio IDE.
PFlash the signed, encrypted image and press the reset button on the WPK board. The application will run as expected.

How to Ensure That PSRAM Contents Are Encrypted#

Take example program like psram_driver_example found at https://github.com/SiliconLabs/wiseconnect/tree/master/exam-ples/si91x_soc/peripheral/psram_driver_example
Modify MBR flags as shown above in Enable encrypted XiP in devices with external PSRAM.
Add following Snippet code in main.c after sl_si91x_psram_init() is called
Users can observe that data read in auto mode is same as data wrote, whereas data read in manual mode is 0. Since data needs to be protected, data is not read in manual mode from secure sections. To know more about auto and manual mode refer to PSRAM Driver

/// Auto Write to PSRAM in secure area
psram_read_address = PSRAM_BASE_ADDRESS + 0x1040000;
uint8_t* psramBufWrtPtr = (uint8_t*)psram_read_address;
for (uint32_t index = 0; index < BIT_8_READ_WRITE_LENGTH; index++) {
    psramBufWrtPtr[index] = testBuf[index];
}
DEBUGOUT("Reading back data in auto mode: \r\n");
for (size_t i = 0; i < 10; i++) {
DEBUGOUT("0x%08X 0x%02X 0x%02X",(unsigned int)&psramBufWrtPtr[i],testBuf[i],psramBufWrtPtr[i]);
DEBUGOUT("\r\n");
}
DEBUGOUT("Reading back data in manual mode: \r\n");
sl_si91x_psram_manual_read_in_blocking_mode((uint32)psramBufWrtPtr, verifyBuf, sizeof(uint8_t), 10);
for (size_t i = 0; i < 10; i++) {
DEBUGOUT("0x%08X 0x%02X 0x%02X",(unsigned int)&psramBufWrtPtr[i],testBuf[i], verifyBuf[i]);
DEBUGOUT("\r\n");
}