Introduction

This document describes the internal function of the mbed TLS SSL/TLS module.

Component overview

The SSL/TLS module provides the means to setup and communicate over a secure communication channel using SSL/TLS.

Its basic provisions are:

  • Initialize an SSL/TLS context.
  • Perform an SSL/TLS handshake.
  • Send/receive data.
  • Notify a peer that a connection is being closed.

Many aspects of such a channel are set through parameters and callback functions:

  • Endpoint role: client or server.
  • Authentication mode: whether verification should take place.
  • Protocol versions accepted.
  • Ciphersuite for the channel.
  • Send/receive callbacks*.
  • Random number generator (RNG)*.
  • Renegotiation availability.
  • Session resumption callbacks.
  • Session caching*.
  • Debug callbacks.
  • Verification parameters: CRLs, CAs, expected CN, and verification callbacks
  • A certificate verification function.
  • X.509 parameters for certificate-handling and key exchange.
  • Which extensions to send (e.g. Truncated HMAC, or ServerName)

*. 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:

  • SSL/TLS protocol layer, namely handshake, version and TLS extension information.
  • 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.

Used structures

This module implements the following structures:

  • `ssl_context`: contains the SSL/TLS context and state.
  • `ssl_handhsake`: contains the SSL/TLS handshake context and state.
  • `ssl_session`: contains session information, most importantly the session identifier and master key.
  • `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.

    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

Internal state

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.

Scenarios

The following scenarios are described:

  • Initialize the SSL/TLS context for a client host.
  • Perform an SSL/TLS handshake for a client host.
  • Fail to send data.
  • Complex usage: SSL/TLS setup, send/receive, breakdown.

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.

Use cases

All uses are:

  • Initialize context. Reset the SSL/TLS context.
  • Set parameters. Many parameters can be set to improve flexibility. See details in diagram.
  • Get info. Get certificate verification result, get bytes available, get cipher.
  • Write data. Write data over SSL/TLS performing handshake if needed, perform handshake.
  • Read data. Read a number of bytes over SSL/TLS.
  • Close notify. Notify the peer that the connection is being closed.
  • Cleanup. Free the SSL/TLS context internals.