Introduction

This document describes the internal functionality of the mbed TLS 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, 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

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.

Scenarios

The following scenarios are described:

  • Initialization to encrypt
  • Failure to encrypt a message
  • Complex usage: encrypt and decrypt a message

Initialization to encrypt

This scenario describes how a context is initialized to encrypt messages.

Failure to encrypt a message

This scenario describes how an encrypted attempt fails, because the context is uninitialized.

Encrypt and decrypt a message

This scenario describes how a message is encrypted and decrypted.

Use cases

All uses are:

  • Initialize
  • Cleanup
  • Get cipher information.
  • Set a key.
  • Encrypt a message.
  • Decrypt a message.