SSL / TLS Module Level Design
This document describes the internal function of the mbed TLS SSL/TLS module.
The SSL/TLS module provides the means to setup and communicate over a secure communication channel using SSL/TLS.
Its basic provisions are:
Many aspects of such a channel are set through parameters and callback functions:
*. 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.
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:
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.
The ssl context object is the ubiquitous parameter used throughout the SSL/TLS module. It keeps state for the:
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.
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:
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.
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.
The SSL/TLS module provides a function to notify the peer that the connection is being closed.
This module implements the following structures:
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.
SSL_HELLO_REQUEST, SSL_CLIENT_HELLO, SSL_SERVER_HELLO, SSL_SERVER_CERTIFICATE, SSL_SERVER_KEY_EXCHANGE, SSL_CERTIFICATE_REQUEST, SSL_SERVER_HELLO_DONE, SSL_CLIENT_CERTIFICATE, SSL_CLIENT_KEY_EXCHANGE, SSL_CERTIFICATE_VERIFY, SSL_CLIENT_CHANGE_CIPHER_SPEC, SSL_CLIENT_FINISHED, SSL_SERVER_CHANGE_CIPHER_SPEC, SSL_SERVER_FINISHED, SSL_FLUSH_BUFFERS, SSL_HANDSHAKE_OVER
This section contains a high-level view of the internal state. Especially the internal state for an SSL/TLS handshake is quite extensive. In the scenarios section these states are covered in detail.
The following scenarios are described:
Initialize the SSL/TLS context for a client host
This scenario describes how an SSL/TLS context is initialized.
Perform an SSL/TLS handshake for a client host
This scenario describes how an SSL/TLS handshake is performed.
Fail to send data
This scenario describes how a failure to send data is handled.
Complex usage: SSL/TLS setup, send/receive, breakdown
This scenario describes a typical SSL/TLS session where the necessary a SSL/TLS communication channel is set up, some communication takes place and the channel is broken down.
All uses are: