This information applies to the following SoftDevice: S132

Overview

Transport Layer Security (TLS) ensures privacy between server and client endpoints by providing protection against eavesdropping and the tampering of data exchanged between the communicating endpoints.

The Datagram Transport Layer Security (DTLS) defines transport layer security for datagram protocols thereby providing communications privacy for datagram protocols. The DTLS protocol is based on the Transport Layer Security (TLS) protocol and provides equivalent security guarantees. TLS assumes a reliable transport and breaks when re-hosted on an unreliable transport. DTLS aims at fixing this problem by proposing changes to allow the reordering of packets and by implementing retransmission timers to handle packet loss.

CoAP defines DTLS bindings for secure communication. MQTT defines bindings for TLS.

Note: The term TLS covers both security for TCP and UDP transport types, this means DTLS is implied if the transport type is UDP.

Figure 1. End to end security with TLS/DTLS

Figure 2 below shows the position of the TLS/DTLS layers in the Nordic IoT SDK.

Figure 2: Transport Layer Security on nRF5x

Nordic's TLS Abstraction Interface

To avoid binding the users of the SDK with a specific TLS library, an abstracted interface is used in the SDK. This abstraction of TLS/DTLS is defined in TLS on nRF5x. CoAP and MQTT rely on availability of this interface for securing their respective transport layers.

Figure 3: Nordic's TLS Abstraction Interface

In the SDK, mbedtls is used to provide the TLS interface to the IoT protocols.

Warning: Please read and understand the terms of use of mbedtls, which is published under the Apache 2.0 license.

Note: The current interface is minimalistic and strips down many of the functionalities like the session tickets, session caching etc. The interface will be extended in the future to add the relevant features.

Feature Configuration Summary

Currently DTLS and TLS are maintained as two different configurations. The table below summarizes the features supported in the two configurations.

Feature	DTLS	TLS
Role	Server and Client	Client only
Ciphers	TLS_PSK_WITH_AES_128_CCM_8	TLS_PSK_WITH_AES_128_CBC_SHA TLS_PSK_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
Max Fragment Length	1024	3072
Maximum concurrent sessions	2	1

Warning: The raw public key mandated by RFC 7252 is not supported.

Configuration of mbedtls as TLS client used in all MQTT examples can be found at
<InstallFolder>components/iot/tls/mbedtls/tls/config. Configuration of mbedtls as DTLS server and client used for CoAP DTLS examples can be found at
<InstallFolder>components/iot/tls/mbedtls/dtls/config.

Application Interface

This section describes the application interface of this module.

Create TLS/DTLS instance using nrf_tls_alloc : The cipher suites, protocol versions are fixed by the library. User is permitted to select the key settings, transport type and role. For client roles, a handshake is automatically initiated if the interface configuration and context setup was successful.
Free the TLS instance nrf_tls_free : All information and configuration for the instance is removed.
Write on the instance nrf_tls_write : This API is used to provide application data which is encrypted by the library for secure transfer to the remote endpoint.
Note
Application should not attempt to send data more than the maximum fragment length configured.
Read on the instance nrf_tls_read : This procedure is used to retrieve any decrypted application data received from the remote end point.
Transport data input nrf_tls_input : All data received on the transport should be submitted to the library using this call. The library takes care of advancing the handshake protocol or decrypting data received based on the state of TLS connection.
Transport data write nrf_tls_output_t : Callback registered with the TLS interface to write output of TLS library on to the associated transport interface.
Heartbeat for the library nrf_tls_process : This call shall be made periodically to be able to process any queued input or output data in the TLS library.
Note
The periodicity of calling this function has an impact on time taken to complete handshake protocol.

Version and Reference

The repository for mbedtls source is located at mbedTLS GitHub. mbedtls version included in the SDK is the tag mbedtls-2.4.2, corresponding hash is 59ae96f167a19f4d04dc6db61f6587b37ccd429f.