Context Navigation

PolarSSL Symmetric Cipher (Cipher) module MLD

PolarSSL Symmetric Cipher (Cipher) module MLD

Introduction

This document describes the internal functionality of the PolarSSL Symmetric Cipher (Cipher) module.

Component overview

The Cipher module provides symmetric encryption and decryption using some chosen ciphers in a generic way. The Cipher module does not interact with other modules.

Component design

The following ciphers may be included:

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

The mentioned ciphers are implemented as sub-modules that can be included or excluded at compile time. Sub-modules context structures, initialization and function calls are wrapped to comply with the generic calling methods.

The following functions are provided by the Cipher module interface:

Initialization and cleanup functions.
Setting the encryption/decryption key.
Encrypting a message.
Decrypting a message.
Getting available cipher information.

The following naming convention is used for coherence: cipher_function where function is the one of the mentioned function e.g. cipher_setkey for setting the symmetric key.

Initialization and cleanup

An allocated, generic cipher context can be initialized and cleaned up. The underlying cipher specific initialization and cleanup is done through the wrapper-functions. A cipher context can be obtained by name.

Key handling

The key(s) for encryption and decryption can be set. The mode of operation, encryption or decryption, is set with the key. Each key needs only be set once and is stored in the context.

Encryption/decryption

The encryption/decryption process can be reset with a new initialization vector (IV), updated with new input data and finalized to write pending data to the output buffer. Pre-allocated input and output buffers must be provided by the calling function.

Separate contexts are used for encryption and decryption. The mode of operation (encryption or decryption) is set when the key is set.

Cipher information

The supported ciphers can be listed as well as their generic context information like cipher name, initialization vector (IV), block and key size.

Used structures

Each cipher has a context structure. These cipher specific context structures are wrapped into a generic context structure. This generic context structure is used throughout the component interface.

Internal state

A context structure is typically initialized once for encryption and decryption. The cipher specific implementations are hidden from the caller by wrapping them into a generic context and functions.

Note that some sub-modules always return success, even when the cryptographic function has failed. The diagram below thus describes how it typically is rather than how it always is.