High Level Design
Providing the bird's-eye viewPolarSSL does not have a simple core. There is a reason that other projects got so unreadable. The entire SSL/TLS protocol handling requires a lot of logic. Let us present you with a high level overview that helps guide you through our software.
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 1.3.2 as downloaded from this site. Note that the terms module and component are used interchangeably. Implementing security in applications or systems should be easy and straightforward. We provide a simple and effective SSL library that makes it easy to use cryptography and SSL/TLS in your developments. PolarSSL is designed to be readable, documented, tested, low profile, loosely coupled and portable.
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.
The PolarSSL software is "a light-weight open source cryptographic and SSL 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, x86, x64, etc.
PolarSSL includes support for three build systems out-of-the-box, a simple Makefile-based system, a CMake-based system and a few Microsoft Visual C workspaces. It works out-of-the-box on most architectures with a UNIX, Linux or Windows based OS.
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 (include/polarssl/config.h). A central SSL module uses the cryptographic components, the abstraction layers and the support components to provide a complete protocol implementation for SSL v3, TLS v1.0, TLS v1.1 and TLS v1.2. Components are included for:
These components have the following dependencies:
Internally most of these modules contain multiple low level modules. These are described on their respective module level design pages.
This means that all components can be deployed independently, except for the SSL/TLS component.
The following figure shows all possible dependencies.
This section gives an overview of all PolarSSL components. It provides an overview per component by:
The SSL/TLS communication module provides the means to create an SSL/TLS communication channel. It implements the TLS protocol versions SSLv3, TLS v1.0, TLS v1.1 and TLS v1.2. 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:
Many aspects of such a channel are set through parameters and callback functions:
1. An implementation is included with PolarSSL, but own implementations can be provided as well.
The SSL/TLS module depends directly on the X.509, Cipher, Public Key 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:
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:
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.
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:
A generic interface is provided for all the mentioned hashing functions, called the MD layer.
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 an entropy pool and random number generation. It uses the CTR-DRBG (Counter mode Deterministic Random Byte Generator) generator, which is a NIST standardized random number generator. The entropy pool system gathers entropy from standard sources and application-provided sources.
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. Most symmetric algorithms also provide Counter Mode (CTR), Cipher Feedback Mode (CFB) and Galois Counter Mode (GCM). There is a generic interface to provide a common calling method for the implemented ciphers, called the Cipher layer.
The following algorithms are provided with PolarSSL:
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 Public Key
The Public Key module provides public key (or asymmetric) cryptographic functions, namely Diffie-Hellman-Merkle key exchange, RSA, Elliptic Curve, ECDH and ECDSA functions. The following functions are provided:
This module provides public key functions which can be used for confidentiality, integrity, authentication and non-repudiation.
The Public Key module is independent in C-terms and loosely coupled in OO-terms. This means that for example:
RSA uses a random number generation function amongst others to create key pairs or provide protection to blinding as is shown in the following examples:
Component X.509 Certificate support
The X.509 module provides X.509 support which includes:
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 Public Key Cryptography module for its RSA and Elliptic Curve support and the Hashing module for signature verification. Further, it uses the Symmetric Cipher module to decode encrypted keys.
This section contains some example scenarios where a simple application uses the PolarSSL library. The following scenarios 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
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.
Typical uses for the PolarSSL library are: