PolarSSL High-level design document

Introduction

This document describes the internal structure of the PolarSSL library. It contains descriptions of the external environment the software runs on, an overview of its components and some example scenarios. It thus forms an overview of the separate module level designs, but also includes some system-level information about its use and platform.

This document describes the design of PolarSSL version 0.14 as downloaded from  http://polarssl.org. Note that the terms module and component are used interchangeably.

System overview

This section describes the environment the PolarSSL library is used in and its decomposition. The details of the components that it comprises are in separate, module level design documents.

External environment

The PolarSSL software is described as "a light-weight open source cryptographic and SSL/TLS library written in C". It is suitable for embedded platforms and has been ported to a number of architectures, including ARM, PowerPC, MIPS and Motorola 68000.

It includes support for three build systems, a simple Makefile-based system, a CMake-based system and a Visual C workspace. It works out-of-the-box on most x86 architectures with a UNIX, Linux or Windows based OS.

Internal structure

The PolarSSL library provides a set of cryptographic components that can be used and compiled separately. Features can be included or excluded using a single configuration header file. A central binding module uses these cryptographic components to provide a complete protocol implementation for SSLv3, TLSv1.0 and TLSv1.1. Components are included for:

• SSL/TLS communication
• TCP/IP communication
• Hashing
• Random number generation (RNG)
• Symmetric cipher (Cipher)
• Asymmetric cryptography (Asym)
• X.509 public key infrastructure (X.509)

These components have the following dependencies:

• The SSL/TLS component uses the hashing, cipher and X.509 components
• The SSL/TLS component may be configured to use the RNG and TCP/IP components
• The Asym component may be configured to use the RNG component

This means that all components can be deployed independently, except for the SSL/TLS component. The following figure shows all possible dependencies.

Components

This section gives an overview of all PolarSSL components. It provides an overview per component by:

• describing the component as a black box.
• describing the functionality of the component.
• showing the interaction with other components.
• providing a typical usage sequence diagram.

Component SSL/TLS

The SSL/TLS communication module provides the means to create an SSL/TLS communication channel. It implements the  TLS protocol SSLv3, TLSv1.0 and TLSv1.1. Complying to this protocol requires hashing, encryption and X.509 certificate support. It also requires a reliable, ordered transport channel, e.g. TCP, and random functionality for its encryption functions. Components that cover these requirements are provided by the PolarSSL library.

This module provides the following basic functionality:

• Initialize and configure an SSL/TLS context.
• Perform an SSL/TLS handshake.
• Send and receive data.
• Notify a peer that 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.
• Ciphers for encryption/decryption.
• Send/receive callbacks. A TCP/IP wrapper is included with PolarSSL.
• Random number generator (RNG). An RNG module is included with PolarSSL.
• Session resumption callbacks.
• Verification parameters: CRLs, CAs, expected CN, and verification callbacks

The SSL/TLS module depends directly on the X.509, Cipher, Asym and Hashing modules. The SSL/TLS context can be initialized using the RNG and TCP/IP modules that are provided by the PolarSSL library. The following diagram describes the interaction with other components:

Simplified use of the SSL/TLS component is as follows:

Component TCP/IP

The TCP/IP module provides a reliable and ordered channel for the SSL/TLS module. It wraps operating system-specific TCP/IP interfaces, easing cross platform application development. It provides the following functionality:

• Listen on a port.
• Accept a connection.
• Read / Write.
• Close a connection.

The read and write functions can be used as a callback for the SSL/TLS module. This component can be used at server- and client-side to provide a basic means of communication over the internet.

Component Hashing

The Hashing module provides a number of one-way hash and hash message authentication code (HMAC) functions. An HMAC can be verified using a previously exchanged symmetric key to provide message integrity. The following hash algorithms are provided:

• MD2, MD4, MD5 128-bit one-way hash functions.
• SHA-1, SHA-256, SHA-384/512 160-bit or more one-way hash functions.

A generic interface is provided for all the mentioned hashing functions.

Hash calculation can occur at once or in steps as is shown in the following example:

Component Random Number Generator (RNG)

The Random number generator (RNG) module provides random number generation. It uses the HAVEGE (HArdware Volatile Entropy Gathering and Expansion) software heuristic which is claimed to be an unpredictable or empirically strong random number generator. ( http://www.irisa.fr/caps/projects/hipsor/publi.php). Random number generation requires an initialized HAVEGE state, which stores the entropy pool used.

Component Cipher

The Cipher module provides symmetric encryption/decryption functions.

These symmetric functions are generally used for message confidentiality. Some symmetric algorithms provide different block cipher modes, mainly Electronic Code Book (ECB) which is used for short, e.g. 64-bit, messages and Cipher Block Chaining (CBC) which provides the randomness needed for longer messages. There is a generic interface to provide a common calling method for the implemented ciphers.

The following algorithms are provided with PolarSSL:

• AES - ECB and CBC
• ARCFOUR - stream cipher
• Camellia - ECB and CBC
• DES/3DES - ECB and CBC
• XTEA - ECB

This module provides encryption/decryption which can be used to provide secrecy.

Randomization, e.g. random function and initialization vectors, is provided through parameters.

The Cipher module is independent of other modules.

Component Asym

The Asym module provides assymetric cryptographic functions, namely Diffie-Hellman-Merkle key exchange and RSA functions. The following functions are provided:

• Diffie-Hellman-Merkle - import public, export public and calculate shared secret part.
• RSA - key generation, message signing, message verification, encryption and decryption.

This module provides asymmetric key functions which can be used for confidentiality, integrity, authentication and non-repudiation.

The Asym module is independent in C-terms and loosely coupled in OO-terms. This means that for example:

• The RNG function is called through callback functions and provided as a parameter at initialization.
• The HMAC is provided when signing a message.
• X.509 depends on this component, not the other way around.

RSA uses a random number generation function to create key pairs as is shown in the following example:

Component X.509 Certificate support

The X.509 module provides X.509 support which includes:

• X.509 certificate (CRT) parsing.
• X.509 certificate revocation list (CRL) parsing.
• X.509 (RSA) private key parsing.
• X.509 certificate verification.

Certificate verification checks whether a certificate's signature chain is rooted with a trusted certificate authority. It also checks whether the certificate (or one of the intermediate CA's in its chain) is in the certificate revocation list of its issuing CA.

The X.509 module uses the Asymmetric Cryptography module for its RSA support and the Hashing module for signature verification. Further, it uses the Symmetric Cipher module to decode encrypted keys.

Scenarios

This section contains some example scenarios where a simple application uses the PolarSSL library. The following scenario's are covered from a high level perspective with the PolarSSL library as a black box.

• Scenario A: Use PolarSSL to generate an RSA key pair.
• Scenario B: Use PolarSSL for SSL/TLS communication.

Scenario A: Use PolarSSL to generate an RSA key pair

In this scenario the PolarSSL library is used as a lightweight RSA key pair generation tool. The keys are then saved to file. One use for such a key pair is for ssh communication.

Scenario B: Use PolarSSL for SSL/TLS communication

The PolarSSL library provides SSL/TLS communication for your application. This adds secrecy to any software solution that communicates over the internet. The example scenario shows a simple client application that generates a message, communicates it to an SSL/TLS server and processes the result.

Use cases

Typical uses for the PolarSSL library are:

• SSL/TLS communication. See the SSL/TLS module level design (MLD) document.
• TCP/IP communication. See the TCP/IP MLD document.
• Data encryption/decryption. See the Symmetric Cipher MLD document.
• Key exchange. See the Asymmetric Cryptography MLD document.
• X.509 certificate handling. See the X.509 MLD document.
• Hashing/HMAC generation. See the Hashing MLD document.
• Random number generation. See the RNG MLD document.