Hashing Module Level Design
This document describes the internal functionality of the mbed TLS Hashing module.
The Hashing module provides one-way hashing functions. Hashing functions are used to create a fixed-length representation of a block of data so that when the data changes the hash value does not match. The hash value is also known as a (message) digest.
A hashing function is generally used for creating a hash message authentication code (HMAC) when sending a message. Such a HMAC can be used in combination with a previously exchanged symmetric key as a message integrity and authentication control.
With this module you can thus:
The hashing component implements the following hashing algorithms:
Each of these hash functions is implemented as a separate sub-module and can be included or excluded at compile time. All hash functions are wrapped to comply with a generic interface (called the MD layer) that includes:
The following naming convention is used for coherence: X_function.
where X is either md or md_hmac for the generic layer, or e.g. sha_256 or sha256_hmac for the direct calls to the SHA-256 sub-module. The following functions are provided:
Hash message authentication code (HMAC)
All functions return 0 on success and an error code on failure.
One-way hash with state
A message digest is generated in steps on variable length data blocks (stream):
One-way hash without state
A message digest is calculated over an input file or buffer. Internally the same functions are used as in 'One-way hash with state'.
HMAC with state
A HMAC is generated in steps on variable length data blocks (stream):
HMAC without state
A HMAC is calculated over an input buffer. A secret key must be supplied. Internally the same functions are used as in 'HMAC with state'.
A structure is defined to represent internal state. It contains a.o. the intermediate digest state, padding and the data block being processed.
It is used to process a variable length input block-by-block, intermediate state-by-intermediate state. The padding is used to hold the secret key information. If the key is too long, its hash value is calculated and used instead.
The one-pass hash/HMAC calculation from file or buffer is stateless. When using the start-update-finish construction a state is kept by means of a context structure. See the 'Used structures'-section for the internal workings.
When state is used the diagram below applies.
The following scenarios are described:
Calculate a hash value for a file
This scenario describes how a hash value is calculated for a file. Only the hash function information needs to be provided. There is initialization and no state between function calls.
Calculate a hash value for a stream
This scenario describes how a hash value is calculated for a stream. Initialization is required and state is kept between function calls.
Calculate a HMAC for a stream
This scenario describes how a hash message authentication code (HMAC) is calculated for a stream and then reset. Initialization is required with provision of a secret key. State is kept between function calls.
All uses are: