The CoAP over DTLS Server example demonstrates how DTLS can be integrated to Nordic's CoAP implementation for the server role.

The supplied CoAP server example has the same behavior as the CoAP server examples that do not use security in terms of resource set-up. However an additional procedure of coap_security_setup is required to set the security parameters for the local server port.

Note: It is not possible to multiplex the local server port for secure and non-secure communication from remote client endpoints. All exchanges on this port are expected to be secure.

The example implements an endpoint that hosts the following resources:

    host
    |-- .well-known
    |   `-- core
    `-- lights
        |-- led3
        `-- led4

The DTLS Handshake should be initiated by the client before accessing any of the serves resources.

Warning: When TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 cipher is selected the Handshake procedure takes perceivable time to complete, about 166 seconds. This delay is observed only for the handshake. Subsequent encrypted messages should be exchanged without any delays.

Figure 1 shows a CoAP client in PC accessing the resources exposed by this application on CoAP.

Figure 1: Setup of the CoAP server application.

Figure 2 shows LED control from a CoAP client example included in the SDK.

Figure 2: Setup of the CoAP client with Light server application.

Note: The figures above show one CoAP client controlling resources on the server. DTLS state is remembered only for one client, and multiple CoAP clients are not supported concurrently by this example.

Configuration parameters for all used modules are defined and described in the sdk_config.h file. This file is located in the config subfodler of the main application folder.

Note: This application needs custom SoftDevice for IPv6.; This application is not power optimized!; This application will start advertising again after disconnection.

Common module dependency and usage

This section summarizes the usage of nRF5x resources and common modules in the examples apart from the IoT 6lowpan and IPv6 stack library.

Module	Inclusion/Usage	Description
Timer	1	One timer is used for servicing the IoT timer.
Buttons	0	No buttons are used in this examples.
LEDs	4	LEDs are used to indicate the application states. See LED assignments section for details.
Adv Data Encoder	Yes	The device name used is 'DTLS-COAPServer', IPSP Service UUID is included in the UUID list.
RNG Driver	Yes	Random number generator is used for security procedures in tinyDTLS library.
Scheduler	No	Scheduler is used for processing stack events.
UART Trace	Included not enabled	Tracing is included but not enabled by default.

Note: DTLS examples use stack size of 3072 bytes as against other examples that use 2048 bytes.

Setup

The example named iot_dtls_coap_server uses Nordic's IPv6 stack to set up the CoAP server with DTLS that is implemented using the tinyDTLS library. You can find the source code and project files of this example in the following folder:
<InstallFolder>/examples/iot/dtls/coap_server

LED assignments:

The state of LED 3 and LED 4 can be set and queried via CoAP. Both are turned on in case of an assertion failure in the application.
LED 1 and LED 2 display the state of the application as described in the table below.

LED 1	LED 2
Blinking	Off	Device advertising as BLE peripheral.
On	Blinking	BLE link established, IPv6 interface down.
Off	On	BLE link established, IPv6 interface up.
On	On	Assertion failure in the application.

Note: If commissioning is enabled, additional LED and Button assignments are made.

Testing

This example is designed to work with the CoAP over DTLS Client example. However, if only one nRF5x DK is available, the Californium CoAP Framework can be used as a secure CoAP Client on a PC.

Note: Connecting DTLS coap client and coap server to the same router might cause an immediate disconnect when starting to transfer large amount of data on the links. Therefore, in order to test DTLS example kit against kit, please connect the kits to different routers. The two routers should be able to forward packets to each other for communication to succeed.

See Connecting devices to the router for a list of relevant Linux commands.

Compile and program the application. Observe that the device is advertising.
Prepare the Linux router device by initializing the 6LoWPAN module.
Discover the advertising device by using the hcitool lescan command.
Connect to the discovered device from the Linux console by using the Bluetooth 6LoWPAN connect command.
Check if the connected state is reflected by the LEDs.
Run the Wireshark or hcidump program to monitor the btX interface.
An ICMPv6 ping can be used on the link-local and on the global IPv6 address assigned to the device to check if the device is reachable.
Note
To find the global address, use the prefix assigned to the interface in Router Advertisement.
Use a secure CoAP client to interact with the application and set the states of LED 3 and LED 4.
Note
DTLS handshake precedes processing of the first request. The DTLS handshake phase may take a few seconds to complete.
Disconnect from the device using the Bluetooth 6LoWPAN disconnect command.
Observe that the device is advertising.

Known Issues

Below is a summary of known issues with the example.

If the DTLS handshake fails, no indication is provided to the application of the same. And there is no way to recover from this situation apart from disconnecting the BLE link and trying it again.
There is no indication on the LEDs, when the handshake is successfully complete. The only way to conclusively establish this is using wireshark or tshark or when the CoAP client is able to successfully toggle LEDS on the kit running the example.
If the remote server restarts and initiates handshake again on the server that has retained the DTLS session (as there is no indication of session termination), the server does re-establish the DTLS session. Therefore, if the remtoe application is re-initiate a session, the BLE link on the server must be disconnected and reconnected to trigger freeing of the existing DTLS sessions.

Troubleshooting Guide

It is possible that the global address is not immediately available on the connection as the Neighbor Discovery, Router Advertisement, and Duplicate Address Detection procedures take a few seconds to complete.
If you observe that the CoAP server responses are received at the btX interface but the CoAP client device never receives them, it is possible that the forwarding between networks is not enabled. This can be done on Linux using the command sysctl -w net.ipv6.conf.all.forwarding=1.
In case the CoAP client device is reachable, but the requests from the CoAP client device do not make it to the server, it is possible that the application is not configured with the correct remote server address. Verify that the address SERVER_IPV6_ADDRESS in the client application matches the server address.