Implement Advanced Features

View source on GitHub

Some advanced features are optional, depending on whether or not they are supported on the target hardware platform.

Auto frame pending

IEEE 802.15.4 defines two kinds of data transmission methods between parent and child: direct transmission and indirect transmission. The latter is designed primarily for sleepy end devices (SEDs) which sleep most of the time, periodically waking to poll the parent for queued data.

  • Direct Transmission — parent sends a data frame directly to the end device Direct Transmission

  • Indirect Transmission — parent holds data until requested by its intended end device Direct Transmission

In the Indirect case, a child end device must first poll the parent to determine whether any data is available for it. To do this, the child sends a data request, which the parent acknowledges. The parent then determines whether it has any data for the child device; if so, it sends a data packet to the child device, which acknowledges receipt of the data.

If the radio supports dynamically setting the Frame Pending bit in outgoing acknowledgments to SEDs, the drivers must implement the source address match API to enable this capability. OpenThread uses this API to tell the radio which SEDs to set the Frame Pending bit for.

If the radio does not support dynamically setting the Frame Pending bit, the radio might stub out the source address match API to return OT_ERROR_NOT_IMPLEMENTED.

Energy Scan/Detect with radio

The Energy Scan/Detect feature requires the radio chip to sample energy presenting on selected channels and return the detected energy value to the upper layer.

If this feature is not implemented, the IEEE 802.15.4 MAC layer sends/receives a Beacon Request/Response packet to evaluate the current energy value on the channel.

If the radio chip supports Energy Scan/Detect, make sure to disable software energy scanning logic by setting the macro OPENTHREAD_CONFIG_ENABLE_SOFTWARE_ENERGY_SCAN = 0.

Hardware acceleration for mbedTLS

mbedTLS defines several macros in the main configuration header file, mbedtls-config.h, to allow users to enable alternative implementations of AES, SHA1, SHA2, and other modules, as well as individual functions for the Elliptic curve cryptography (ECC) over GF(p) module. See mbedTLS hardware acceleration for more information.

OpenThread does not enable those macros, therefore the symmetric crypto algorithms, hash algorithms and ECC functions all utilize software implementations by default. These implementations require considerable memory and computational resources. For optimal performance and a better user experience, we recommend enabling hardware acceleration instead of software to implement the above operations.

To enable hardware acceleration within OpenThread, the following mbedTLS configuration header files should be added to the ot-config compile definitions in the platform's CMake files:

  • Main configuration, which defines all necessary macros used in OpenThread: /openthread/third-party/mbedtls/mbedtls-config.h
  • User-specific configuration, which defines alternate implementations of modules and functions: src/platform-name-mbedtls-config.h

Example from nrf52811.cmake:

target_compile_definitions(ot-config INTERFACE
    "MBEDTLS_USER_CONFIG_FILE=\"nrf52811-mbedtls-config.h\""
)

Commented macros in mbedtls-config.h are not mandatory, and can be enabled in the user-specific configuration header file for hardware acceleration.

For a complete example user-specific configuration, see the mbedtls_config_autogen.h file in ot-efr32.

AES module

OpenThread Security applies AES CCM (Counter with CBC-MAC) crypto to encrypt/decrypt the IEEE 802.15.4 or MLE messages and validates the message integration code. Hardware acceleration should at least support basic AES ECB (Electronic Codebook Book) mode for AES CCM basic functional call.

To utilize an alternative AES module implementation:

  1. Define the MBEDTLS_AES_ALT macro in the user-specific mbedTLS configuration header file
  2. Indicate the path of the aes_alt.h file using the MBEDTLS_CPPFLAGS variable

SHA256 module

OpenThread Security applies HMAC and SHA256 hash algorithms to calculate the hash value for network key management and PSKc generation according to the Thread Specification.

To utilize an alternative basic SHA256 module implementation:

  1. Define the MBEDTLS_SHA256_ALT macro in the user-specific mbedTLS configuration header file
  2. Indicate the path of the sha256_alt.h file using the MBEDTLS_CPPFLAGS variable

ECC functions

Since mbedTLS currently only supports hardware acceleration for parts of ECC functions, rather than the entire module, you can choose to implement some functions defined in path-to-mbedtls/library/ecp.c to accelerate ECC point multiplication.

Curve secp256r1 is used in the key exchange algorithm of the ECJPAKE draft. Hence, hardware acceleration should at least support the secp256r1 short weierstrass curve operation. See SiLabs CRYPTO Hardware Acceleration for mbedTLS for an example.