*. An implementation is included with mbed TLS, but own implementations can be provided as well.

This module can be used to create an SSL/TLS server and client by providing a framework to setup and communicate through an SSL/TLS communication channel.

Note that you need to provide several aspects yourself as mentioned above.

The SSL/TLS depends directly on the X.509, Cipher, Public Key Cryptography and Hashing modules. Definitions from these modules are used in the extensive context that keeps the SSL/TLS state and their functions in the implementation. Usage details are provided in the next sections. The SSL/TLS context can be initialized with the RNG and TCP/IP modules that are provided by the mbed TLS library.

Component design

The internal design provides a framework for an SSL/TLS solution. A complete solution can be constructed using the elements from the mbed TLS library. Alternatively, several functions can be provided using external elements. The internal design has the following functions:

Provide the context to keep track of an SSL/TLS state.

Setup an SSL/TLS connection.

Communicate over an SSL/TLS connection.

Renegotiate an SSL/TLS connection.

Breakdown an SSL/TLS connection.

The implementation provided by the mbed TLS library is split up into a client-, a server- and a common-part, e.g. ssl_handshake_client, ssl_handshake_server and ssl_handshake.

All functions are prefixed ssl_ for coherence. All SSL error codes have negative values.

Keeping state

The ssl context object is the ubiquitous parameter used throughout the SSL/TLS module. It keeps state for the:

callbacks layer, the functions to use for RNG, I/O, session handling, debugging and their state.

handshake layer, a handshake context and relevant handshake state.

session layer, a session context and additional session state.

record layer, input and output data message state.

PKI layer, certificate information and state.

Crypto layer, key exchange and cipher context and state.

Before the setup/handshake the callback functions must be set. The appropriate keys and certificate chains must be loaded. A list of accepted ciphersuites must be set. Use of specific protocol parameters and extensions can be indicated. These are the user adjustable framework variables; the main internal provision of this framework is the record layer/messaging using the SSL/TLS protocol.

Setup

After initializing the SSL/TLS context, the handshake function is called to setup an SSL/TLS communication channel. If the application does not call the handshake function explicitly, it is called automatically based on state. The handshake performs a client- or server-side SSL/TLS handshake which basically is a protocol (version) negotiation, optional certificate verification, key exchange and cipher negotiation.

mbed TLS supports all four TLS handshakes:

Simple - only the server is authenticated

(Client-)Authenticated - the client and the server are authenticated

Resumed - a session is resumed based on a session id

Renegotiated - a session is renegotiated within the existing session

The state of the handshake is kept in the SSL/TLS handshake context.

After setup the SSL/TLS client and server have created a SSL/TLS communication channel that uses the negotiated security elements from the handshake.

Communicate

After setup a SSL/TLS communication channel is available. The SSL/TLS module contains functions to read and write data from and to this channel and to check the number of bytes that are available to read.

Breakdown

The SSL/TLS module provides a function to notify the peer that the connection is being closed.

`ssl_states`: the states that the SSL/TLS communication channel can be in.

In mbed TLS the SSL/TLS context is the facade that brings all the elements needed for SSL/TLS together. The layers/elements that are included in this context are mentioned in the section 'Keeping state'. The context structure simply includes all the variables it may need for the functions it supports, e.g. ciphers and hash functions, in one big structure. The context structure can be considered private as the functions needed for normal use are provided and return meaningful errors.

The handshake structure is only present during the handshake part of the connection and contains all variables only needed during the handshake. This structure should be considered private and internal to the SSL/TLS module.

The session structure is kept separate to allow the user to implement session caching. This structure can thus be considered public as any implementation to find a specific session typically accesses this structure directly.

The states enumeration structure shows the ordered, internal states of the SSL/TLS solution for the handshake. It is included here for reference as these states are covered step-by-step in the scenarios section.