Symmetric Cipher (Cipher) Module Level Design
This document describes the internal functionality of the mbed TLS Symmetric Cipher (Cipher) module.
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.
The following ciphers may be included:
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:
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.
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.
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.
The supported ciphers can be listed as well as their generic context information like cipher name, initialization vector (IV), block and key size.
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.
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.
The following scenarios are described:
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.
All uses are: