Chapter 185. Configuration
Prev Part XLIX. Mbed TLS v3 Next

Chapter 185. Configuration

Table of Contents

185.1. Configuration Overview
185.1.1. Quick Start
185.1.2. Configuring Options

This chapter shows how to incorporate the Mbed TLS support into an eCos configuration, and how to configure it once included.

185.1. Configuration Overview

185.1.1. Quick Start
185.1.2. Configuring Options

The Mbed TLS support is contained in a single eCos package CYGPKG_MBEDTLS3. However, some functionality is dependant on other eCos features. e.g. the eCos networking stack support.

185.1.1. Quick Start

Incorporating the Mbed TLS support into your application is straightforward. The essential starting point is to incorporate the Mbed TLS eCos package (CYGPKG_MBEDTLS3) into your configuration.

This may be achieved directly using ecosconfig add on the command line, or the Build->Packages… menu item within the eCos Configuration Tool.

Depending on the Mbed TLS package configuration other packages may be required (e.g. network stack support). The package requires that the CYGPKG_INFRA and CYGPKG_MEMALLOC packages are included in the eCos application configuration.

185.1.2. Configuring Options

For the majority of situations the default Mbed TLS configuration as defined in the package include/mbedtls/mbedtls_config.h header will suffice. Especially since only referenced code will be linked into the final application.

The package does provide some configuration options TODO

CYGOPT_MBEDTLS3_USE_PSA_CRYPTO

Enable this option to configure the X.509 and TLS support to use PSA, and enable the PSA Crypto key handling APIs.

[Note]Note

This is still under development by the Mbed TLS maintainers, and not all of the released Mbed TLS sources are updated to use PSA. However they will continue to operate using the non-PSA support.

If this option is enabled than application MUST call the psa_crypto_init() function BEFORE calling any SSL/TLS, X.509 or PK modules. Enabling this option allows the TLS, X.509 and PK modules to utilise PSA drivers. For example, the drivers for ECDSA, ECDH and EC J-PAKE.

CYGOPT_MBEDTLS3_THREADING

This option can be set to enable the threading abstraction layer. Mbed TLS by default assumes either single-threaded operation, or a multi-threaded environment where contexts are NOT shared. If contexts do need to be shared between threads then this option should be configured appropriately. The native option provides direct eCos scheduler mutex support, with the pthread setting using the Mbed TLS pthread support via the eCos POSIX pthread abstraction layer (so more code overhead, but might be useful if a POSIX threaded application is being used).

[Note]Note

Currently for Mbed TLS 3.x the PSA-API is NOT thread-safe so applications should be written for single-threaded PSA operations.

CYGOPT_MBEDTLS3_DEPRECATED_WARNING
This option, disabled by default, controls whether deprecated Mbed TLS functions and features generate a compilation warning when used.
CYGOPT_MBEDTLS3_DEPRECATED_REMOVED
This option, disabled by default, controls whether deprecated Mbed TLS functions and features are disabled such that a compilation error will occur if used.

If, however, greater control over the configuration of the Mbed TLS library built is required then the developer can supply header files to #define or #undef options as desired to override the default settings. This is achieved by enabling the relevant configuration option, specifying a header file location, so that the build will include the referenced header.

The header file injection configuration options are:

CYGBLD_MBEDTLS3_USER_CONFIG_HEADER
If defined, the supplied header file will be included after the <mbedtls/mbedtls_config.h> header.
CYGBLD_MBEDTLS3_USER_PSA_CONFIG_HEADER
If defined, the supplied header file will be included after the <psa/crypto_config.h> header.

If the requirement for a specific Mbed TLS configuration is part of another package (for example the platform (PLF) or variant (VAR). or some application library package) then this can easily be achieved in the package specific CDL by a simple requires statement. e.g. 

    requires      { CYGBLD_MBEDTLS3_USER_CONFIG_HEADER == "<my_package/tls1p3_only.h>" }

If using the ecosconfig tool to construct a build configuration, then a CDL fragmant can be imported to set the desired header file reference. e.g. 

cat > mbedtls3_psa.ecm <<EOF
cdl_option CYGBLD_MBEDTLS3_USER_PSA_CONFIG_HEADER {
    inferred_value 1 “my_psa_options.h”
}
EOF
ecosconfig import mbedtls3_psa.ecm

Alternatively, for a specific build configuration .ecc file, the option can be manually set using the configtool GUI application with a suitable local or global path filename used to reference the required header for the build.

Prev Up Next
Chapter 184. Mbed TLS overview Home Chapter 186. eCos port