ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add DTLS in Connectivity's design document

pull/12181/head
Michal Paszta 2020-01-02 12:06:25 +02:00
parent 5f495db06b
commit b3d1d1f487
1 changed files with 24 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
docs/design-documents/features/connectivity/TLSSocket - Design document.md
View File

@ -1,12 +1,14 @@
# TLSSocket - design document
## Overview and background
This document describes the design of the TLSSocket class, which provides an interface for an Mbed OS user to create TLS connections over a TCP socket.
This document describes the design of the TLSSocket and DTLSSocket classes, which provide an interface for an Mbed OS user to create TLS connections over a TCP socket or DTLS over a UDP socket.
Mbed OS provides two different implementations for TLS sockets; Mbed TLS based (default) or offloaded TLS socket when used network stack (for example, a cellular modem target driver) supports it.
This class greatly simplifies the use of TLS but limits itself to only one use case. This design limitation is accepted as other users can continue using Mbed TLS API directly. Mbed TLS based TLSSocket also exposes internal Mbed TLS structures allowing use of Mbed TLS API to configure the underlying library.
DTLSSocket shares most of its functionality with TLSSocket (via `TLSSocketWrapper` class), just using UDP instead of TCP as transport socket and handling connection differently.
The high-level goal is to demonstrate that secure connections are not hard to do.
## Design limitations
@ -26,10 +28,12 @@ Offloaded vs. Mbed TLS based TLSSocket:
# System architecture and high-level design
The Mbed TLS based secure socket consists of two classes:
The Mbed TLS based secure socket consists of four classes:
* `TLSSocketWrapper`, which handles initialization of TLS library, does the TLS handsake and takes any Socket as a transport.
* `TLSSocket`, which inherits TLSSocketWrapper, has TCP socket as a transport and adds `connect(char *hostname)` for initiating the TCP and TLS handshakes at one call.
* `DTLSSocketWrapper`, which inherits from TLSSocketWrapper and adds a few auxiliary functions.
* `DTLSSocket`, which inherits DTLSSocketWrapper, has UDP socket as a transport and adds `connect(char *hostname)` for initiating the UDP and DTLS handshakes at one call.
```
,--------------.
@ -52,14 +56,21 @@ The Mbed TLS based secure socket consists of two classes:
|void set_hostname(...); |
|int do_handshake(); |
`-----------------------------'
|
,----------------------------.
|TLSSocket |
|----------------------------|
|TCPSocket transport |
|----------------------------|
|int connect(char *hostname);|
`----------------------------'
|______________________________
| |
| ,----------------------------.
| |DTLSSocketWrapper |
| |----------------------------|
| |timer-related functions |
| `----------------------------'
| |
,----------------------------. ,----------------------------.
|TLSSocket | |DTLSSocket |
|----------------------------| |----------------------------|
|TCPSocket transport | |UDPSocket transport |
|----------------------------| |----------------------------|
|int connect(char *hostname);| |int connect(char *hostname);|
`----------------------------' `----------------------------'
```
Offloaded TLS socket:
@ -94,6 +105,8 @@ The offloaded secure socket shares the same API as Mbed TLS based TLSSocket as m
When TLSSocket implements the Socket API, it can be used instead of TCP connection in any Mbed OS library. For example, the MQTT library is made secure without any code changes: https://github.com/coisme/Mbed-to-Azure-IoT-Hub/tree/new-TLSSocket
The `DTLSSocket` class implements TLS handshake for UDPSocket.
## High-level design goal 2: Only certificate-based authentication
The aim is to first support only certificate-based authentication, so we implement only `set_root_ca_cert()` and `set_client_cert_key()` functions. Later on, different types of authentication methods can be added.
@ -148,7 +161,7 @@ This destroys the memory allocated by the TLS library. It also closes the transp
virtual nsapi_error_t connect(const SocketAddress &address);
```
This initiates the TCP connection and continues to the TLS hanshake.
This initiates the TCP/UDP connection and continues to the TLS hanshake.
This is currently forced to blocking mode.
@ -313,14 +326,6 @@ No tool changes required.
By default, the system is configured to use the Mbed TLS based secure socket because only a few network stacks support offloaded TLS socket. You can enable the offloaded TLS socket in the application json configuration file by setting: `"nsapi.offload-tlssocket": true`.
## Reusability
Mbed TLS secure socket:
Parts of the state machine are probably relevant when implementing DTLS socket. TLSSocketWrapper is entirely reusable when doing the TLS handshake using any socket type. It does not have tight bindings to TCP.
Offloaded secure socket:
The current implementation is for TLS only and does not support DTLS.
## Assumptions
We assume the server certificate is given from the application to `TLSSocket::set_root_ca_cert()` interface in a format that is understood by Mbed TLS or, in the case of the offloaded TLS socket, the implementation of TLS socket in the network stack.