Infineon OPTIGA™ Trust X Software Framework

Infineon OPTIGA Trust X is a high-end security controller with a versatile set of features to secure devices.

See Trust X Datasheet for detailed information on the framework.

Trust X Software Framework

On a Nordic platform, there are two APIs to use the functions of Trust X:

1. The OPTIGA™ backend, which operates on top of the native Trust X API.
2. The native Trust X API, split into Crypt API and Util API.

While the backend API implementation is Nordic-specific, the native API is portable and also available on other host platforms. Furthermore, the native API exposes the complete function set of Trust X, such as reading and writing data objects, which is required for personalization.

Trust X Software Framework

The OPTIGA Trust X software framework is composed of the following layers (top to bottom):

• Crypt API (Crypt API) and Util API (Util API), a set of high-level APIs to use Trust X services.
• OPTIGA Trust X Command Library, a lower-level API, documented in the Solution Reference manual Trust X Solution Reference Manual (SRM).
• Infineon I2C Protocol (Infineon I2C Protocol) implementation to exchange commands via I2C with the Trust X device.
• An implementation of the Platform Abstraction Layer (PAL) for the Nordic nRF5x platform: pal_gpio.c, pal_i2c.c, pal_ifx_i2c_config.c, pal_os.c and pal_os_lock.c.

External resources and documentation

More information can be found at:

• Infineon OPTIGA Trust X product page: OPTIGA Trust X product website
• Latest version of OPTIGA Trust X software framework: OPTIGA™ Trust X Software Framework on Github.com
• Latest version of OPTIGA Trust X documentation: OPTIGA™ Trust X Wiki on Github.com
• List of technical documents and specifications: List of OPTIGA™ Trust X Documents

Note

The Infineon OPTIGA Trust X hardware security module must be acquired separately, for example on a development board in Arduino-compatible form factor, and compatible with the Nordic development kit. For more information, visit Trust X evaluation and development kits.

Platform-specific configuration

Required configuration

Due to EasyDMA restrictions on nRF52832 devices, it is necessary to set a project-level define DL_MAX_FRAME_SIZE=250 to use the nrf5x Platform Abstraction Layer (PAL). This PAL is required by the Trust X host library, which is used by the OPTIGA backend implementation.

The OPTIGA software framework allocates memory on the heap. For proper operation, the heap should be equal to or larger than 8,192 bytes.

Hardware compatibility

When using the Nordic PCA10040 board with the Trust X Shield, the LEDs BSP_BOARD_LED_1 and BSP_BOARD_LED_2 must not be used. These pins are needed for the correct operation of the OPTIGA Trust X.

To use the the PAL together with other I2C devices and to also run it on a BLE Shield2Go, define IFX_2GO_SUPPORT on the project level.

Trust X Crypt and Util API (native API)

Initialization

To use Infineon Trust X without the nrf_crypto API and backend implementation, it must be initialized. The following code snippet demonstrates how to do this:

int32_t status = (int32_t) OPTIGA_LIB_ERROR;

// Initialize PAL
pal_gpio_init();
pal_os_event_init();

status = optiga_util_open_application(&optiga_comms);
if (OPTIGA_LIB_SUCCESS != status)
{
 NRF_LOG_INFO("Failure: CmdLib_OpenApplication(): 0x%04X", status);
}
NRF_LOG_INFO("Success: CmdLib_OpenApplication(): 0x%04X", status);

Data objects and personalization

A major capability of Trust X is to safely store cryptographic material, such as private keys for authentication, or public-key certificates for verification.

These credentials are stored in highly-protected areas of Trust X. These areas are called data objects, and they can be protected from reading or writing. Typically, these data objects are initialized by the product manufacturer or system owner, for example during production. In order to properly initialize the data objects, the native Util API provides the functions:

• optiga_util_read_data()
• optiga_util_write_data()
• optiga_util_read_metadata()
• optiga_util_write_metadata()

A complete example demonstrating the personalization of Trust X data objects for Amazon AWS is located on Github: Trust X Personalization. A complete documentation for the API is available at Crypt API.

Infineon I2C Protocol Stack Library

The Infineon I2C Protocol Stack library enables communication with Infineon OPTIGA(TM) Trust X products. The protocol stack consists of three layers that relate to the ISO OSI (Open Systems Interconnection) model: transport, data link, and physical. Beneath is a host-specific platform abstraction layer (PAL), which interfaces to a host's I2C driver or I2C peripheral.

Note

This section provides an informal overview of the Infineon I2C Protocol Stack. For official documentation, visit Infineon I2C Protocol.

Protocol stack layers

Transport Layer (TL)

The transport layer provides a single transceiver interface to send an application protocol data unit (APDU) to a device, and to subsequently retrieve the response APDU. The layer is responsible for chaining (fragmenting) APDUs larger than the maximum packet size, and reassembling the received packets back into APDUs.

Therefore, the TL provides a single transceive function to asynchronously send an APDU and receive the respective response APDU: ifx_i2c_tl_transceive().

The transport layer must be initialized by the higher layer using the ifx_i2c_tl_init() function.

Data Link Layer (DL)

The data link layer provides error correction on top of the physical layer's raw transmission facility.

Therefore, the DL provides two functions to asynchronously send and receive error-free data frames:

1. ifx_i2c_dl_send_frame()
2. ifx_i2c_dl_receive_frame()

The data link layer must be initialized by the higher layer using the ifx_i2c_dl_init() function.

Physical Layer (PL)

The physical layer provides two functions to asynchronously send and receive raw data frames:

1. ifx_i2c_pl_send_frame()
2. ifx_i2c_pl_receive_frame()

The physical layer is intended to be initialized by the higher layer using the ifx_i2c_pl_init() function.

Platform Abstraction Layer (PAL)

The PAL separates hardware-specific APIs and module interfaces from the portable and platform-independent implementation of the Infineon I2C Protocol Stack Library.

The nRF52-specific implementation of the Infineon I2C PAL module can be found in the following files:

• pal_gpio.c
• pal_i2c.c
• pal_ifx_i2c_config.c
• pal_os.c
• pal_os_lock.c

The PAL implementation for nRF52 uses the TWI transaction manager (nrf_twi_mngr.h) as an interface to the I2C hardware.