Chapter 186. eCos port
Prev Part XLIX. Mbed TLS v3 Next

Chapter 186. eCos port

Table of Contents

186.1. Overview
186.2. Entropy

186.1. Overview

The goal for the CYGPKG_MBEDTLS3 package is to avoid where possible having to have any core Mbed TLS source file changes made specifically for eCos. This is to ensure that re-imports of newer versions of the Mbed TLS world involve minimal effort. The files are as provided in the official Mbed TLS release package as imported, with the following exceptions:

  1. Files have been moved, unmodified, to create a standard eCos package tree structure to integrate with the eCosPro build environment
  2. The file include/mbedtls/mbedtls_config.h has been replaced by an eCos specific implementation.
  3. The file src/aes.c has been changed to avoid a compilation warning.
  4. The file src/ecos_net_sockets.c provides the internal Mbed TLS network API (as originally provided by src/net_sockets.c) to support the eCos network stacks (e.g. CYGPKG_NET_LWIP or CYGPKG_NET_FREEBSD_STACK).
  5. The file src/ecos_platform.c provides some eCos specific platform support required by Mbed TLS depending on the configuration.
  6. The file tests/selftest.c has been modified with some eCos specific code to allow use in the eCos automated test farm. However, the core of the selftest functionality is unchanged.

The current Mbed TLS version provided by the eCos package is 3.6.1 (with 3.6 being a Long Term Support (LTS) release supported until at least 2027Q1). Please read the package ChangeLog file for the original Mbed TLS release notes which are interleaved with the commments covering eCosCentric changes.

186.2. Entropy

Cryptographic security is dependent on the use of strong keys. Strong keys are dependent on the quality of entropy used in their generation.

The eCosPro port of Mbed TLS provides both a default portable weak entropy mechanism, and the ability to implement a target platform specific mechanism to gather high-quality entropy.

We strongly recommend that you use as high a quality source of entropy as possible when using Mbed TLS on your target platform. The use of the generic weak entropy mechanism (provided by MBEDTLS_TIMING_C) is NOT recommended for anything other than simplifying the initial bring-up and testing of applications.

For eCos we define MBEDTLS_ENTROPY_HARDWARE_ALT for the configuration (in include/mbedtls/mbedtls_config.h) since the default Mbed TLS platform entropy implementation is Un*x/Windows only. The use of MBEDTLS_ENTROPY_HARDWARE_ALT provides for a link-time entropy source to be provided by the platform support. Other entropy sources are dynamically added at runtime via the mbedtls_entropy_add_source() functionality.

[Note]Note

In the following weak refers to the linker preference when linking an application, and not to a weak entropy source.

The eCos src/ecos_platform.c source file provides a weak function definition for the mbedtls_hardware_poll() implementation that will return MBEDTLS_ERR_ENTROPY_SOURCE_FAILED since we expect the platform support or application code to provide a cryptographically strong implementation. Ideally such an implementation will use TRNG (True Random Number Generator) hardware support by the HAL, variant, architecture, etc. as appropriate.

The function prototype: 

#include <mbedtls/entropy_poll.h>

int mbedtls_hardware_poll(void *data, unsigned char *output, size_t len, size_t *olen);

conforms to the entropy provision API for routines declared via the mbedtls_entropy_add_source() API (in fact the Mbed TLS run-time will add mbedtls_hardware_poll() automatically via that mechanism).

The callback specific (context data pointer) parameter data will normally be NULL for the Mbed TLS registered implementation. The output parameter references a buffer of at least len bytes to receive random data. The olen pointer is filled by the function to report the number of valid bytes actually written, and may be 0 (zero) if the function is not able to satisfy the request for true random data. The function should return 0 to indicate no errors occurred, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED on error.

As an example of a platform specific implementation, the STM32 port of eCos provides an Mbed TLS entropy source based on the STM32's RNG hardware.

Prev Up Next
Chapter 185. Configuration Home Chapter 187. Test Programs