Crypto: PSA TLS

The Platform Security Architecture Transport Layer Security (PSA TLS) sample shows how to perform a TLS handshake and send encrypted messages with Cortex-M Security Extensions (CMSE) enabled, in both Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE) with Trusted Firmware-M.

For information about CMSE and the difference between the two environments, see Processing environments in the nRF Connect SDK.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

nRF9161 DK

PCA10153

nrf9161dk

nrf9161dk/nrf9161/ns nrf9161dk/nrf9161

nRF9160 DK

PCA10090

nrf9160dk

nrf9160dk/nrf9160/ns nrf9160dk/nrf9160

nRF9151 DK

PCA10171

nrf9151dk

nrf9151dk/nrf9151/ns nrf9151dk/nrf9151

nRF7120 DK

nrf7120dk

nrf7120dk/nrf7120/cpuapp/ns nrf7120dk/nrf7120/cpuapp

nRF54LV10 DK

PCA10188

nrf54lv10dk

nrf54lv10dk/nrf54lv10a/cpuapp/ns nrf54lv10dk/nrf54lv10a/cpuapp

nRF54LS05 DK

PCA10214

nrf54ls05dk

nrf54ls05dk/nrf54ls05b/cpuapp

nRF54LM20 DK

PCA10184

nrf54lm20dk

nrf54lm20dk/nrf54lm20b/cpuapp/ns nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp/ns nrf54lm20dk/nrf54lm20a/cpuapp

nRF54LC10 DK

PCA10226

nrf54lc10dk

nrf54lc10dk/nrf54lc10a/cpuapp

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp/ns nrf54l15dk/nrf54l15/cpuapp

nRF54L15 DK (emulating nRF54L10)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l10/cpuapp/ns nrf54l15dk/nrf54l10/cpuapp

nRF54H20 DK

PCA10175

nrf54h20dk

nrf54h20dk/nrf54h20/cpurad nrf54h20dk/nrf54h20/cpuapp

nRF5340 DK

PCA10095

nrf5340dk

nrf5340dk/nrf5340/cpuapp/ns nrf5340dk/nrf5340/cpuapp

For more security, it is recommended to use the */ns variant of the board target. When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

The sample requires a TAP adapter to perform the TLS handshake. This functionality is currently only supported in Linux.

Overview

The sample can act as either a network server or a network client. By default, the sample is configured to act as a server.

After a successful TLS handshake, the client and server echo any message received over the secured connection.

TLS version support

The sample supports both TLS v1.2 and TLS v1.3. See the following table for the support overview for each compatible board target. The table mirrors the test setup used for TLS verification.

Board target

Backend

CMSE supported

DTLS supported

Limitations

Comments

nrf52840dk/nrf52840 nrf9160dk/nrf9160 nrf9151dk/nrf9151

Mbed TLS legacy nrf_cc3xx backend

No

No

AES256, AES-GCM, SHA-512

nrf52840dk/nrf52840 nrf9160dk/nrf9160 nrf9151dk/nrf9151

Mbed TLS legacy oberon backend

No

No

nrf52840dk/nrf52840

PSA Crypto nrf_cc3xx driver

No (secure only)

Yes

RSA not supported

Also supports PSA Crypto nrf_oberon driver

nrf9160dk/nrf9160 nrf9151dk/nrf9151

PSA Crypto nrf_cc3xx driver

Yes

Yes

RSA not supported

Also supports PSA Crypto nrf_oberon driver

nrf5340dk/nrf5340/cpuapp

Mbed TLS legacy nrf_cc3xx backend

No

No

nrf5340dk/nrf5340/cpuapp

Mbed TLS legacy nrf_oberon backend

No

No

nrf5340dk/nrf5340/cpuapp

PSA Crypto nrf_cc3xx driver

Yes

Yes

RSA not supported

Also supports PSA Crypto nrf_oberon driver

nrf54l15dk/nrf54l15/cpuapp

PSA Crypto CRACEN driver

Yes

Yes

RSA not supported

Also supports PSA Crypto nrf_oberon driver

nrf54l15dk/nrf54l10/cpuapp

PSA Crypto CRACEN driver

No

Yes

RSA not supported

Also supports PSA Crypto nrf_oberon driver

nrf54lm20dk/nrf54lm20a/cpuapp

PSA Crypto CRACEN driver

No

Yes

RSA not supported

Also supports PSA Crypto nrf_oberon driver

nrf54lv10dk/nrf54lv10a/cpuapp

PSA Crypto CRACEN driver

No

Yes

RSA not supported

Also supports PSA Crypto nrf_oberon driver

nrf54ls05dk/nrf54ls05b/cpuapp

PSA Crypto nrf_oberon driver

No

Yes

RSA not supported

No support for CRACEN

nrf54h20dk/nrf54h20/cpuapp nrf54h20dk/nrf54h20/cpurad

SSF Crypto (CONFIG_PSA_SSF_CRYPTO_CLIENT)

No

Yes

RSA not supported

nrf7120dk/nrf7120/cpuapp

PSA Crypto CRACEN driver

No

Yes

RSA not supported

Also supports PSA Crypto nrf_oberon driver

Supported cipher suites

See the following tabs for the list of supported and verified cipher suites for each TLS version. Cipher suites not listed may still work but have not been verified.

Supported rsa_ciphers suites:

  • AES128-GCM-SHA256

  • AES128-SHA

  • AES128-SHA256

  • AES256-GCM-SHA384

  • AES256-SHA

  • AES256-SHA256

  • DHE-RSA-AES128-CCM

  • DHE-RSA-AES128-GCM-SHA256

  • DHE-RSA-AES128-SHA

  • DHE-RSA-AES128-SHA256

  • DHE-RSA-AES256-GCM-SHA384

  • DHE-RSA-AES256-SHA

  • DHE-RSA-AES256-SHA256

  • DHE-RSA-CHACHA20-POLY1305

  • ECDHE-RSA-AES128-GCM-SHA256

  • ECDHE-RSA-AES128-SHA

  • ECDHE-RSA-AES128-SHA256

  • ECDHE-RSA-AES256-GCM-SHA384

  • ECDHE-RSA-AES256-SHA

  • ECDHE-RSA-AES256-SHA384

  • ECDHE-RSA-CHACHA20-POLY1305

Supported rsa_ciphers_cc310_legacy suites (AES256 and GCM removed):

  • AES128-SHA

  • AES128-SHA256

  • DHE-RSA-AES128-CCM

  • DHE-RSA-AES128-SHA

  • DHE-RSA-AES128-SHA256

  • DHE-RSA-CHACHA20-POLY1305

  • ECDHE-RSA-AES128-SHA

  • ECDHE-RSA-AES128-SHA256

  • ECDHE-RSA-CHACHA20-POLY1305

Supported ecdsa_ciphers suites:

  • ECDHE-ECDSA-AES128-GCM-SHA256

  • ECDHE-ECDSA-AES128-SHA

  • ECDHE-ECDSA-AES128-SHA256

  • ECDHE-ECDSA-AES128-CCM8

  • ECDHE-ECDSA-AES128-CCM

  • ECDHE-ECDSA-AES256-GCM-SHA384

  • ECDHE-ECDSA-AES256-SHA

  • ECDHE-ECDSA-AES256-SHA384

  • ECDHE-ECDSA-AES256-CCM8

  • ECDHE-ECDSA-AES256-CCM

  • ECDHE-ECDSA-CHACHA20-POLY1305

  • ECDHE-PSK-AES128-CBC-SHA256

  • ECDHE-PSK-AES256-CBC-SHA384

  • ECDHE-PSK-CHACHA20-POLY1305

Supported ecdsa_ciphers_cc310_legacy suites (AES256 and GCM removed):

  • ECDHE-ECDSA-AES128-SHA

  • ECDHE-ECDSA-AES128-SHA256

  • ECDHE-ECDSA-AES128-CCM8

  • ECDHE-ECDSA-AES128-CCM

  • ECDHE-ECDSA-CHACHA20-POLY1305

  • ECDHE-PSK-AES128-CBC-SHA256

  • ECDHE-PSK-CHACHA20-POLY1305

AES256 is supported on all compatible board targets with the CMSE enabled because it enables both nrf_cc3xx and nrf_oberon as backends for devices with Arm CryptoCell.

The following combinations are not supported:

  • RSA is not supported in applications that use the PSA Crypto configuration (which includes the CMSE).

  • AES CCM-256 and AES GCM are not supported for nRF52840 and for the nRF91 Series devices when using the nrf_cc3xx legacy crypto configuration.

Configuration options

The sample comes with several sample-specific Kconfig options. Depending on the configuration, it also sets different IP addresses for the client and server, using Zephyr’s Kconfig options CONFIG_NET_CONFIG_MY_IPV4_ADDR and CONFIG_NET_CONFIG_PEER_IPV4_ADDR.

CONFIG_PSA_TLS_CERTIFICATE_TYPE_RSA

(bool) RSA certificate for the PSA TLS sample

Enable RSA certificates when testing ciphers that supports RSA for authentication.

CONFIG_PSA_TLS_CERTIFICATE_TYPE_ECDSA

(bool) ECDSA certificate for the PSA TLS sample

Enable ECDSA certificates when testing ciphers that supports ECDSA for authentication.

CONFIG_PSA_TLS_SAMPLE_TYPE_SERVER

(bool) Server functionality for the PSA TLS sample

When acting as a server, the sample waits for a connection from the client on port 4243. After the TCP connection is established, the sample waits for the “ClientHello” message from the client.

CONFIG_PSA_TLS_SAMPLE_TYPE_CLIENT

(bool) Client functionality for the PSA TLS sample

When acting as a client, the sample tries to connect to the server on port 4243. After the TCP connection is established, the sample automatically initiates the TLS handshake by sending the “ClientHello” message.

Certificates

The sample supports certificates signed with either ECDSA or RSA. The sample uses ECDSA certificates by default. Set the CONFIG_PSA_TLS_CERTIFICATE_TYPE_RSA option to y to make the sample use RSA certificates.

Certificates when running with CMSE

When the sample is compiled for the */ns variant of the board, that is, with TF-M enabled, it stores its TLS certificates and keys in TF-M’s Protected Storage. During the sample initialization, the certificates and keys are fetched from Protected Storage and kept in non-secure RAM for use during every subsequent TLS handshake.

Note

Currently, applications with CMSE enabled only support ECDSA certificates. This is automatically enforced in the configuration files for board targets with CMSE enabled (*/ns variant).

TAP adapter

The sample uses the Ethernet over RTT driver library in the nRF Connect SDK to transfer Ethernet frames to the connected PC. The PC must parse the incoming RTT data and dispatch these packets to a running TAP network device. This functionality is called TAP adapter.

There is currently no direct support for TAP adapters. However, you can still follow the steps given in the Testing section using a Linux distribution running inside a virtual machine.

OpenSSL

Use the OpenSSL command-line interface to perform the peer network operations when testing this sample.

It can act as either client or server with simple commands in a terminal. For more information, see the Testing section.

Building and running

This sample can be found under samples/crypto/psa_tls in the nRF Connect SDK folder structure.

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Testing

After programming the sample to your development kit, complete the following steps to test it:

  1. Start a terminal emulator like the Serial Terminal app and connect to the used serial port with the standard UART settings. See Testing and optimization for more information.

  2. Observe the logs from the application using the terminal emulator.

  3. Start the eth_rtt_link executable as a superuser with your development kit’s SEGGER ID and the following IPv4 address as parameters:

    sudo ./eth_rtt_link --snr 960010000 --ipv4 192.0.2.2

  4. Use OpenSSL to perform the client connection and handshake operation.

    openssl s_client -connect 192.0.2.1:4243 -cipher ECDHE-ECDSA-AES128-SHA256 -CAfile certs/ecdsa/root_cert.pem

    Note

    If the sample has been built with an RSA certificate, use this OpenSSL command:

    openssl s_client -connect 192.0.2.1:4243 -cipher AES128-SHA256 -CAfile certs/rsa/root_cert.pem

    For visualizing a list of the available Supported cipher suites for OpenSSL, use the following command:

    openssl ciphers

  5. Type Nordic Semiconductor into the OpenSSL connection session to send Nordic Semiconductor as an encrypted message to the server.

  6. Check that the TLS sample returns Nordic Semiconductor in the OpenSSL session.

  7. Check in the terminal emulator that 21 bytes were successfully received and returned.

Dependencies

This sample uses the following Zephyr libraries:

  • Logging:

    • include/logging/log.h

  • BSD Sockets:

    • net/socket.h

  • net/net_core.h

  • net/tls_credentials.h

It also uses the following TF-M libraries:

  • tfm_ns_interface.h

  • psa/storage_common.h

  • psa/protected_storage.h