Introduction

This document describes the internal functionality of the mbed TLS 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 (called the MD layer) 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 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:

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
  • Calculate a hash value for a stream
  • Calculate a HMAC for a stream

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