High Level Design

Providing the bird's-eye view

PolarSSL 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.

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

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 "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.

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 (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:

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

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.

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

  • 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.
  • Protocol versions accepted.
  • Ciphersuite for the channel.
  • Send/receive callbacks1.
  • Random number generator (RNG)1.
  • Renegotiation availability.
  • Session resumption callbacks.
  • Session caching1.
  • Debug callbacks.
  • Verification parameters: CRLs, CAs, expected CN, and verification callbacks

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:

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, 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.

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

  • AES - ECB, CBC, CTR, CFB and GCM
  • ARCFOUR (RC4) - stream cipher
  • Blowfish - ECB, CBC, CTR and CFB
  • Camellia - ECB, CBC, CTR, CFB and GCM
  • 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 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:

  • Diffie-Hellman-Merkle - import public, export public and calculate shared secret part.
  • RSA - key generation, message signing, message verification, encryption and decryption.
  • Elliptic Curve Diffie-Hellman-Merkle (ECDH) - import public, export public and calculate shared secret part.
  • Elliptic Curve Digital Signature Algorithm (ECDSA) - key generation, message signing and message encryption.

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:

  • 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 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:

  • Support for using X.509:
    • X.509 certificate (CRT) parsing.
    • X.509 certificate revocation list (CRL) parsing.
    • X.509 (RSA/ECDSA) private key parsing.
    • X.509 certificate verification.
  • Support for creating X.509:
    • X.509 certificate (CRT) writing.
    • X.509 (RSA/ECDSA) private key writing.
    • X.509 certificate request (CSR) parsing.
    • X.509 certificate request (CSR) writing.

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.

Scenarios

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