RPS Image Creation and Conversion Tools

Create and convert RPS images for Silicon Labs SiWx91x devices in a breeze!

Introduction

SiWx91x devices require application images to be converted into RPS images before they can be flashed to the device. The conversion from an application binary to an RPS image includes prepending a header to the application image. This header adds certain metadata to the application, including version numbers, control flags, size information, as well as other instructions to the device's bootloader.

The rps-create tool can be used to create RPS images from M4 application binaries, including adding security features like encryption and signing. By default, a CRC protects the RPS' integrity, however MIC protection can be used instead.

The rps-convert tool can be used to convert existing unsigned/unencrypted (M4 or NWP) RPS images into signed/encrypted RPS images. Changing into MIC integrity protection is also available.

Requirements

This tool was developed using Python 3.10. Required PyPI packages are:

• intelhex, for parsing Intel HEX-formatted (.hex) application images
• pycryptodome, for encryption functionality

Installation

pip install silabs-rps

Usage

Help text along with descriptions of each option can be shown by providing the -h or --help flags.

Create RPS Images

rps-create <output filename> --app <filename> 
        [--map <filename>] [--address <address>] [--app-version <version>] 
        [--fw-info <firmware info>] [--sign <filename>] [--sha <size>] 
        [--encrypt <filename>] [--mic <filename>] [--iv <filename>] 

Available options:

• <output filename> (required)
  • Name of the output RPS image file
• --app <filename> (required)
  • Name of the application filename to convert into RPS file. Must be in .bin or .hex format
• --map <filename> (optional, but recommended if your application is to be placed in PSRAM)
  • Name of the map file (.map) from the compilation of the provided application. Used for determining flash start address
• --address <address> (required if the application file provided with --app is a .bin file, optional otherwise)
  • Application start address. Both decimal and hexadecimal (prefixed by 0x) values are interpreted
• --app-version <version number> (optional)
  • Application version number. Both decimal and hexadecimal (prefixed by 0x) values are interpreted
• --fw-info <firmware info> (optional)
  • Additional version information. Both decimal and hexadecimal (prefixed by 0x) values are interpreted
• --sign <key filename> (optional)
  • Sign the RPS image using the provided (NIST P-256) private key, and append the signature (72 bytes) to the RPS image. The key must be in .pem or .der format
• --sha <size> (optional)
  • Use SHA-<size> for signing the RPS image. Supported options are 256 (default), 384, and 512 bits
• --encrypt <key filename> (optional)
  • Encrypt the application image using AES ECB encryption. Key must be 32 bytes, and must be formatted as .bin or .txt (as a string of hexadecimal characters)
• --mic <key filename> (optional)
  • Use MIC (AES CBC-MAC) based integrity check instead of CRC to protect the RPS image. Key must be 32 bytes, and must be formatted as .bin or .txt (as a string of hexadecimal characters)
• --iv <iv filename> (optional)
  • Custom initialization vector (IV) for the MIC calculation. IV must be 16 bytes, and must be formatted as .bin or .txt (as a string of hexadecimal characters). If no IV is provided, the default IV will be used.

Usage Examples

Here follows some examples on how to use rps-create.

Create an RPS Image From a .bin Application Image Using CRC Integrity Protection

rps-create my_rps.rps --app my_app.bin --address 0x08212000

Create an RPS Image From a .hex Application Image Using CRC Integrity Protection

The application start address is encoded in the file, so the --address option must be omitted.

rps-create my_rps.rps --app my_app.hex

Create an RPS Image to be Placed in PSRAM

rps-create my_rps.rps --app my_app.bin --address 0x0A012000 --map my_map.map

Note: The provided .map file must correspond to the provided application.

Create an RPS Image With MIC Integrity Protection

rps-create my_rps.rps --app my_app.hex --mic my_key.txt --iv my_iv.txt

Note: The provided MIC key must match the M4_OTA_KEY stored on the device for the device to be able to verify the MIC.

Create an Encrypted RPS Image

rps-create my_rps.rps --app my_app.hex --encrypt my_key.txt

Note: The provided encryption key must match the M4_OTA_KEY stored on the device for the device to be able decrypt the RPS image.

Create a Signed RPS Image, Using SHA-384 Hashing

rps-create my_rps.rps --app my_app.hex --sign my_private_key.pem --sha 384

Note: The provided private key must match the M4_PUBLIC_KEY stored on the device for the device to be able to verify the signature of the RPS image.

Convert RPS Images

rps-convert <output filename> --rps <filename> 
        [--sign <filename>] [--sha <size>]
        [--encrypt <filename>] 
        [--mic <filename>] [--iv <filename>]

Available options:

• <output filename> (required)
  • Name of the output RPS image file
• --rps <filename> (required)
  • Name of the application filename to convert into RPS file. Must be in .bin or .hex format
• --sign <key filename> (optional)
  • Sign the RPS image using the provided (NIST P-256) private key, and append the signature (72 bytes) to the RPS image. The key must be in .pem or .der format
• --sha <size> (optional)
  • Use SHA-<size> for signing the RPS image. Supported options are 256 (default), 384, and 512 bits
• --encrypt <key filename> (optional)
  • Encrypt the application image using AES ECB encryption. Key must be 32 bytes, and must be formatted as .bin or .txt (as a string of hexadecimal characters)
• --mic <key filename> (optional)
  • Use MIC (AES CBC-MAC) based integrity check instead of CRC to protect the RPS image. Key must be 32 bytes, and must be formatted as .bin or .txt (as a string of hexadecimal characters)
• --iv <iv filename> (optional)
  • Custom initialization vector (IV) for the MIC calculation. IV must be 16 bytes, and must be formatted as .bin or .txt (as a string of hexadecimal characters). If no IV is provided, the default IV will be used.

Usage Examples

Here follows some examples on how to use rps-convert.

Sign RPS Image

rps-convert my_signed_rps.rps --rps my_rps.rps --sign my_key.pem

Encrypt RPS Image

rps-convert my_encrypted_rps.rps --rps my_rps.rps --encrypt my_key.bin

Enable MIC Integrity Protection in RPS Image

rps-convert my_mic_rps.rps --rps my_rps.rps --mic my_key.bin --iv my_iv.bin