# DTLS sock example

This example shows how to use DTLS sock `sock_dtls_t`.

## Testing using RIOT `native`

For testing, we can use two RIOT `native` RIOT instances. For that first we
need to prepare the network interfaces:

```bash
$ ./../../dist/tools/tapsetup/tapsetup --create 2
```

For the server instance:

```
$ PORT=tap0 make all term
[...]
> dtlss start
ifconfig
```

For the client:

```
$ PORT=tap1 make all term
[...]
> dtlsc <server ip address> "DATA to send"
```

## Debug logs

To enable debug logs uncomment `CFLAGS += -DCONFIG_DTLS_DEBUG` in the Makefile.
Tinydtls supports setting the log level. See Makefile for more info.

## Configs and constraints

DTLS sock acts as a wrapper for the underlying DTLS stack and as such, the
constraints that applies specifically to the stack are also applied here.
For tinydtls, please refer to [dtls-echo README][1].

[1]: https://github.com/RIOT-OS/RIOT/blob/master/examples/dtls-echo/README.md

### Cipher suite
You can select between `TLS_PSK_WITH_AES_128_CCM_8` (Pre-Shared Key) and
`TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8` (Raw Public Key - ECC) either by setting
the correspondent options in `make menuconfig` or via `CFLAGS`. See the `Makefile`
for more information.

## Credentials
### Pre-Shared Key
When using Pre-Shared Key (PSK), the client registers two keys to `credman` and
makes them available to the sock. The client registers a PSK callback function,
which allows the application to specify which credential to use with a
particular sock and endpoint. In this application the client will print the
server's endpoint and the sent hint, if any. As per the sock DTLS documentation,
if the application callback fails to determine which credential should be used,
an Identity Hint (https://tools.ietf.org/html/rfc4279#section-5.2) match is
attempted. `credential1` is assigned an Identity Hint, defined as
`PSK_DEFAULT_HINT` in `tinydtls_keys.h`. This hint is used by sock to select the
credential, in case the DTLS server sends such a hint. Finally, if none of the
above attempts succeed in determining which credential to use, sock DTLS will
pick the first valid credential registered in the sock.

The behaviour above can be tested, for example, by removing the hint from the
server (`sock_dtls_set_server_psk_id_hint`). As `credential0` is the first
registered credential in the client, it will be chosen. As the server does not
have this credential, the handshake will fail.

### ECC
When using ECC Raw Public Key (RPK), the server registers two keys to `credman`
and makes them available to the sock. It also registers an RPK callback
function, which allows the application to specify which credential to use with a
particular sock and endpoint (the client could as well do so). In the particular
case of this example the callback always returns the credential with tag
`SOCK_DTLS_SERVER_TAG_1`.