PolarSSL SSL/TLS module MLD

Introduction

This document describes the internal function of the PolarSSL 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:

• The endpoint role: client or server.
• The authentication mode: whether certificate verification should take place.
• The host-to-host communication channel: send and receive functions.
• The random number generator (RNG) function.
• The ciphers to use for encryption/decryption.
• A certificate verification function.
• Session control: session get and set functions.
• X.509 parameters for certificate-handling and key exchange.

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, Asymmetric Cryptography (Asym) 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 PolarSSL library.

^* It also includes the TCP/IP module without actually referring to anything in it, so it is omitted as a dependency.

Component design

The internal design provides a framework for an SSL/TLS solution. A complete solution can be constructed using the elements from the PolarSSL 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.
• Breakdown an SSL/TLS connection.

The implementation provided by the PolarSSL 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:

1. SSL/TLS protocol layer, namely handshake, version and TLS extension information.
2. callbacks layer, the functions to use for RNG, I/O, session handling, debugging and their state.
3. session layer, a session context and additional session state.
4. record layer, input and output data message state.
5. PKI layer, certificate information and state.
6. Crypto layer, key exchange and cipher context and state.

Before the setup/handshake the callback functions must be set. The session layer must be initialized. The appropriate certificate chains must be loaded. A list of accepted ciphers must be set as well as the Diffie-Hellman-Merkle variables. 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. More details about the SSL/TLS handshake are provided  here.

PolarSSL supports all three TLS handshakes:

1. Simple - only the server is authenticated
2. (Client-)Authenticated - the client and the server are authenticated
3. Resumed - a session is resumed based on a session id

The state of the handshake is kept in the SSL/TLS 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_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 PolarSSL 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 session structure is kept separate as the user is responsible to implement session handling. 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.