PolarSSL Hashing module MLD
Introduction
This document describes the internal functionality of the PolarSSL Hashing module.
Component overview
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:
- Create a hash value/message digest for a file, a stream or a buffer.
- Create a HMAC for a stream or a buffer.
Component design
The hashing component implements the following hashing algorithms:
- MD2, MD4, MD5 128-bit one-way hash functions by Ron Rivest.
- SHA-1, SHA-256, SHA-384/512 160-bit or more one-way hash functions by NIST and NSA.
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 that includes:
- Getting information about the supported hash functions.
- Start, update, finish a one-way-hash function with state.
- Perform a one-way-hash function without state.
- Start, update, stop calculating a hash message authentication code (HMAC) with state.
- Calculate a hash message authentication code (HMAC) without state.
The following naming convention is used for coherence: X_function. where X is either md or md_hmac and the following functions are provided:
One-way hash
- X_file performs a hash operation on a file.
- X performs a hash operation on a buffer.
- X_starts starts a hash operation.
- X_update updates a started hash operation.
- X_finish finishes a started hash operation.
Hash message authentication code (HMAC)
- X_hmac performs a HMAC operation on a buffer.
- X_hmac_starts starts a HMAC operation.
- X_hmac_update updates a started HMAC operation.
- X_hmac_finish finishes a started HMAC operation.
- X_hmac_reset resets a HMAC operation.
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):
- Start: The internal state is initialized.
- Update: Variable length input is supplied.
- Finish: The resulting hash value is delivered.
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):
- Start: The internal state is initialized. A secret key must be supplied.
- Update: Variable length input is supplied.
- Finish: The resulting HMAC is delivered.
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.
Used structures
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.
Internal state
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.
Scenarios
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.
Use cases
All uses are:
- Get supported hash information
- Calculate a hash value
- Start a hash value calculation
- Update a hash value calculation
- Finish a hash value calculation
- Calculate a HMAC
- Start a HMAC calculation
- Update a HMAC calculation
- Finish a HMAC calculation
- Reset a HMAC calculation
\