BearSSL

Data Structures | Macros | Typedefs | Functions | Variables
bearssl_hash.h File Reference
Include dependency graph for bearssl_hash.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | br_hash_class
| Class type for hash function implementations. More...
struct | br_md5_context
| MD5 context. More...
struct | br_sha1_context
| SHA-1 context. More...
struct | br_sha224_context
| SHA-224 context. More...
struct | br_sha256_context
| SHA-256 context. More...
struct | br_sha384_context
| SHA-384 context. More...
struct | br_sha512_context
| SHA-512 context. More...
struct | br_md5sha1_context
| MD5+SHA-1 context. More...
union | br_hash_compat_context
| Aggregate context for configurable hash function support. More...
struct | br_multihash_context
| Multi-hasher context structure. More...

## Macros
#define | br_md5_ID 1
| Symbolic identifier for MD5. More...
#define | br_md5_SIZE 16
| MD5 output size (in bytes). More...
#define | br_sha1_ID 2
| Symbolic identifier for SHA-1. More...
#define | br_sha1_SIZE 20
| SHA-1 output size (in bytes). More...
#define | br_sha224_ID 3
| Symbolic identifier for SHA-224. More...
#define | br_sha224_SIZE 28
| SHA-224 output size (in bytes). More...
#define | br_sha256_ID 4
| Symbolic identifier for SHA-256. More...
#define | br_sha256_SIZE 32
| SHA-256 output size (in bytes). More...
#define | br_sha384_ID 5
| Symbolic identifier for SHA-384. More...
#define | br_sha384_SIZE 48
| SHA-384 output size (in bytes). More...
#define | br_sha512_ID 6
| Symbolic identifier for SHA-512. More...
#define | br_sha512_SIZE 64
| SHA-512 output size (in bytes). More...
#define | br_md5sha1_ID 0
| Symbolic identifier for MD5+SHA-1. More...
#define | br_md5sha1_SIZE 36
| MD5+SHA-1 output size (in bytes). More...

## Typedefs
typedef void(* | br_ghash) (void *y, const void *h, const void *data, size_t len)
| Type for a GHASH implementation. More...

## Functions
void | br_md5_init (br_md5_context *ctx)
| MD5 context initialisation. More...
void | br_md5_update (br_md5_context *ctx, const void *data, size_t len)
| Inject some data bytes in a running MD5 computation. More...
void | br_md5_out (const br_md5_context *ctx, void *out)
| Compute MD5 output. More...
uint64_t | br_md5_state (const br_md5_context *ctx, void *out)
| Save MD5 running state. More...
void | br_md5_set_state (br_md5_context *ctx, const void *stb, uint64_t count)
| Restore MD5 running state. More...
void | br_sha1_init (br_sha1_context *ctx)
| SHA-1 context initialisation. More...
void | br_sha1_update (br_sha1_context *ctx, const void *data, size_t len)
| Inject some data bytes in a running SHA-1 computation. More...
void | br_sha1_out (const br_sha1_context *ctx, void *out)
| Compute SHA-1 output. More...
uint64_t | br_sha1_state (const br_sha1_context *ctx, void *out)
| Save SHA-1 running state. More...
void | br_sha1_set_state (br_sha1_context *ctx, const void *stb, uint64_t count)
| Restore SHA-1 running state. More...
void | br_sha224_init (br_sha224_context *ctx)
| SHA-224 context initialisation. More...
void | br_sha224_update (br_sha224_context *ctx, const void *data, size_t len)
| Inject some data bytes in a running SHA-224 computation. More...
void | br_sha224_out (const br_sha224_context *ctx, void *out)
| Compute SHA-224 output. More...
uint64_t | br_sha224_state (const br_sha224_context *ctx, void *out)
| Save SHA-224 running state. More...
void | br_sha224_set_state (br_sha224_context *ctx, const void *stb, uint64_t count)
| Restore SHA-224 running state. More...
void | br_sha256_init (br_sha256_context *ctx)
| SHA-256 context initialisation. More...
void | br_sha256_update (br_sha256_context *ctx, const void *data, size_t len)
| Inject some data bytes in a running SHA-256 computation. More...
void | br_sha256_out (const br_sha256_context *ctx, void *out)
| Compute SHA-256 output. More...
uint64_t | br_sha256_state (const br_sha256_context *ctx, void *out)
| Save SHA-256 running state. More...
void | br_sha256_set_state (br_sha256_context *ctx, const void *stb, uint64_t count)
| Restore SHA-256 running state. More...
void | br_sha384_init (br_sha384_context *ctx)
| SHA-384 context initialisation. More...
void | br_sha384_update (br_sha384_context *ctx, const void *data, size_t len)
| Inject some data bytes in a running SHA-384 computation. More...
void | br_sha384_out (const br_sha384_context *ctx, void *out)
| Compute SHA-384 output. More...
uint64_t | br_sha384_state (const br_sha384_context *ctx, void *out)
| Save SHA-384 running state. More...
void | br_sha384_set_state (br_sha384_context *ctx, const void *stb, uint64_t count)
| Restore SHA-384 running state. More...
void | br_sha512_init (br_sha512_context *ctx)
| SHA-512 context initialisation. More...
void | br_sha512_update (br_sha512_context *ctx, const void *data, size_t len)
| Inject some data bytes in a running SHA-512 computation. More...
void | br_sha512_out (const br_sha512_context *ctx, void *out)
| Compute SHA-512 output. More...
uint64_t | br_sha512_state (const br_sha512_context *ctx, void *out)
| Save SHA-512 running state. More...
void | br_sha512_set_state (br_sha512_context *ctx, const void *stb, uint64_t count)
| Restore SHA-512 running state. More...
void | br_md5sha1_init (br_md5sha1_context *ctx)
| MD5+SHA-1 context initialisation. More...
void | br_md5sha1_update (br_md5sha1_context *ctx, const void *data, size_t len)
| Inject some data bytes in a running MD5+SHA-1 computation. More...
void | br_md5sha1_out (const br_md5sha1_context *ctx, void *out)
| Compute MD5+SHA-1 output. More...
uint64_t | br_md5sha1_state (const br_md5sha1_context *ctx, void *out)
| Save MD5+SHA-1 running state. More...
void | br_md5sha1_set_state (br_md5sha1_context *ctx, const void *stb, uint64_t count)
| Restore MD5+SHA-1 running state. More...
void | br_multihash_zero (br_multihash_context *ctx)
| Clear a multi-hasher context. More...
static void | br_multihash_setimpl (br_multihash_context *ctx, int id, const br_hash_class *impl)
| Set a hash function implementation. More...
static const br_hash_class * | br_multihash_getimpl (const br_multihash_context *ctx, int id)
| Get a hash function implementation. More...
void | br_multihash_init (br_multihash_context *ctx)
| Reset a multi-hasher context. More...
void | br_multihash_update (br_multihash_context *ctx, const void *data, size_t len)
| Inject some data bytes in a running multi-hashing computation. More...
size_t | br_multihash_out (const br_multihash_context *ctx, int id, void *dst)
| Compute a hash output from a multi-hasher. More...
void | br_ghash_ctmul (void *y, const void *h, const void *data, size_t len)
| GHASH implementation using multiplications (mixed 32-bit). More...
void | br_ghash_ctmul32 (void *y, const void *h, const void *data, size_t len)
| GHASH implementation using multiplications (strict 32-bit). More...
void | br_ghash_ctmul64 (void *y, const void *h, const void *data, size_t len)
| GHASH implementation using multiplications (64-bit). More...
void | br_ghash_pclmul (void *y, const void *h, const void *data, size_t len)
| GHASH implementation using the `pclmulqdq` opcode (part of the AES-NI instructions). More...
br_ghash | br_ghash_pclmul_get (void)
| Obtain the `pclmul` GHASH implementation, if available. More...
void | br_ghash_pwr8 (void *y, const void *h, const void *data, size_t len)
| GHASH implementation using the POWER8 opcodes. More...
br_ghash | br_ghash_pwr8_get (void)
| Obtain the `pwr8` GHASH implementation, if available. More...

## Variables
const br_hash_class | br_md5_vtable
| Constant vtable for MD5. More...
const br_hash_class | br_sha1_vtable
| Constant vtable for SHA-1. More...
const br_hash_class | br_sha224_vtable
| Constant vtable for SHA-224. More...
const br_hash_class | br_sha256_vtable
| Constant vtable for SHA-256. More...
const br_hash_class | br_sha384_vtable
| Constant vtable for SHA-384. More...
const br_hash_class | br_sha512_vtable
| Constant vtable for SHA-512. More...
const br_hash_class | br_md5sha1_vtable
| Constant vtable for MD5+SHA-1. More...

## Detailed Description

# Hash Functions

This file documents the API for hash functions.

## Procedural API

For each implemented hash function, of name "`xxx`", the following elements are defined:

- `br_xxx_vtable`

  An externally defined instance of `br_hash_class`.

- `br_xxx_SIZE`

  A macro that evaluates to the output size (in bytes) of the hash function.

- `br_xxx_ID`

  A macro that evaluates to a symbolic identifier for the hash function. Such identifiers are used with HMAC and signature algorithm implementations.

  NOTE: for the "standard" hash functions defined in the TLS standard, the symbolic identifiers match the constants used in TLS, i.e. 1 to 6 for MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512, respectively.

- `br_xxx_context`

  Context for an ongoing computation. It is allocated by the caller, and a pointer to it is passed to all functions. A context contains no interior pointer, so it can be moved around and cloned (with a simple `memcpy()` or equivalent) in order to capture the function state at some point. Computations that use distinct context structures are independent of each other. The first field of `br_xxx_context` is always a pointer to the `br_xxx_vtable` structure; `br_xxx_init()` sets that pointer.

- `br_xxx_init(br_xxx_context *ctx)`

  Initialise the provided context. Previous contents of the structure are ignored. This calls resets the context to the start of a new hash computation; it also sets the first field of the context structure (called `vtable`) to a pointer to the statically allocated constant `br_xxx_vtable` structure.

- `br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)`

  Add some more bytes to the hash computation represented by the provided context.

- `br_xxx_out(const br_xxx_context *ctx, void *out)`

  Complete the hash computation and write the result in the provided buffer. The output buffer MUST be large enough to accommodate the result. The context is NOT modified by this operation, so this function can be used to get a "partial hash" while still keeping the possibility of adding more bytes to the input.

- `br_xxx_state(const br_xxx_context *ctx, void *out)`

  Get a copy of the "current state" for the computation so far. For MD functions (MD5, SHA-1, SHA-2 family), this is the running state resulting from the processing of the last complete input block. Returned value is the current input length (in bytes).

- `br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count)`

  Set the internal state to the provided values. The 'stb' and 'count' values shall match that which was obtained from `br_xxx_state()`. This restores the hash state only if the state values were at an appropriate block boundary. This does NOT set the `vtable` pointer in the context.

Context structures can be discarded without any explicit deallocation. Hash function implementations are purely software and don't reserve any resources outside of the context structure itself.

## Object-Oriented API

For each hash function that follows the procedural API described above, an object-oriented API is also provided. In that API, function pointers from the vtable (`br_xxx_vtable`) are used. The vtable incarnates object-oriented programming. An introduction on the OOP concept used here can be read on the BearSSL Web site:
https://www.bearssl.org/oop.html

The vtable offers functions called `init()`, `update()`, `out()`, `set()` and `set_state()`, which are in fact the functions from the procedural API. That vtable also contains two informative fields:

- `context_size`

  The size of the context structure (`br_xxx_context`), in bytes. This can be used by generic implementations to perform dynamic context allocation.

- `desc`

  A "descriptor" field that encodes some information on the hash function: symbolic identifier, output size, state size, internal block size, details on the padding.

Users of this object-oriented API (in particular generic HMAC implementations) may make the following assumptions:

- Hash output size is no more than 64 bytes.
- Hash internal state size is no more than 64 bytes.
- Internal block size is a power of two, no less than 16 and no more than 256.

## Implemented Hash Functions

Implemented hash functions are:

Function | Name | Output length | State length
--- | --- | --- | ---
MD5 | md5 | 16 | 16
SHA-1 | sha1 | 20 | 20
SHA-224 | sha224 | 28 | 32
SHA-256 | sha256 | 32 | 32
SHA-384 | sha384 | 48 | 64
SHA-512 | sha512 | 64 | 64
MD5+SHA-1 | md5sha1 | 36 | 36

(MD5+SHA-1 is the concatenation of MD5 and SHA-1 computed over the same input; in the implementation, the internal data buffer is shared, thus making it more memory-efficient than separate MD5 and SHA-1. It can be useful in implementing SSL 3.0, TLS 1.0 and TLS 1.1.)

## Multi-Hasher

An aggregate hasher is provided, that can compute several standard hash functions in parallel. It uses `br_multihash_context` and a procedural API. It is configured with the implementations (the vtables) that it should use; it will then compute all these hash functions in parallel, on the same input. It is meant to be used in cases when the hash of an object will be used, but the exact hash function is not known yet (typically, streamed processing on X.509 certificates).

Only the standard hash functions (MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512) are supported by the multi-hasher.

## GHASH

GHASH is not a generic hash function; it is a universal hash function, which, as the name does not say, means that it CANNOT be used in most places where a hash function is needed. GHASH is used within the GCM encryption mode, to provide the checked integrity functionality.

A GHASH implementation is basically a function that uses the type defined in this file under the name `br_ghash`:

    typedef void (*br_ghash)(void *y, const void *h, const void *data, size_t len);

The `y` pointer refers to a 16-byte value which is used as input, and receives the output of the GHASH invocation. `h` is a 16-byte secret value (that serves as key). `data` and `len` define the input data.

Three GHASH implementations are provided, all constant-time, based on the use of integer multiplications with appropriate masking to cancel carry propagation.

## Macro Definition Documentation

## ◆ br_md5_ID

#define br_md5_ID 1

Symbolic identifier for MD5.

## ◆ br_md5_SIZE

#define br_md5_SIZE 16

MD5 output size (in bytes).

## ◆ br_md5sha1_ID

#define br_md5sha1_ID 0

Symbolic identifier for MD5+SHA-1.

MD5+SHA-1 is the concatenation of MD5 and SHA-1, computed over the same input. It is not one of the functions identified in TLS, so we give it a symbolic identifier of value 0.

## ◆ br_md5sha1_SIZE

#define br_md5sha1_SIZE 36

MD5+SHA-1 output size (in bytes).

## ◆ br_sha1_ID

#define br_sha1_ID 2

Symbolic identifier for SHA-1.

## ◆ br_sha1_SIZE

#define br_sha1_SIZE 20

SHA-1 output size (in bytes).

## ◆ br_sha224_ID

#define br_sha224_ID 3

Symbolic identifier for SHA-224.

## ◆ br_sha224_SIZE

#define br_sha224_SIZE 28

SHA-224 output size (in bytes).

## ◆ br_sha256_ID

#define br_sha256_ID 4

Symbolic identifier for SHA-256.

## ◆ br_sha256_SIZE

#define br_sha256_SIZE 32

SHA-256 output size (in bytes).

## ◆ br_sha384_ID

#define br_sha384_ID 5

Symbolic identifier for SHA-384.

## ◆ br_sha384_SIZE

#define br_sha384_SIZE 48

SHA-384 output size (in bytes).

## ◆ br_sha512_ID

#define br_sha512_ID 6

Symbolic identifier for SHA-512.

## ◆ br_sha512_SIZE

#define br_sha512_SIZE 64

SHA-512 output size (in bytes).

## Typedef Documentation

## ◆ br_ghash

typedef void(* br_ghash) (void *y, const void *h, const void *data, size_t len)

Type for a GHASH implementation.

GHASH is a sort of keyed hash meant to be used to implement GCM in combination with a block cipher (with 16-byte blocks).

The `y` array has length 16 bytes and is used for input and output; in a complete GHASH run, it starts with an all-zero value. `h` is a 16-byte value that serves as key (it is derived from the encryption key in GCM, using the block cipher). The data length (`len`) is expressed in bytes. The `y` array is updated.

If the data length is not a multiple of 16, then the data is implicitly padded with zeros up to the next multiple of 16. Thus, when using GHASH in GCM, this method may be called twice, for the associated data and for the ciphertext, respectively; the zero-padding implements exactly the GCM rules.

Parameters

  y | the array to update.
  h | the GHASH key.
  data | the input data (may be `NULL` if `len` is zero).
  len | the input data length (in bytes).

## Function Documentation

## ◆ br_ghash_ctmul()

void br_ghash_ctmul | ( | void * | y,
|  | const void * | h,
|  | const void * | data,
|  | size_t | len
| ) |  |

GHASH implementation using multiplications (mixed 32-bit).

This implementation uses multiplications of 32-bit values, with a 64-bit result. It is constant-time (if multiplications are constant-time).

Parameters

  y | the array to update.
  h | the GHASH key.
  data | the input data (may be `NULL` if `len` is zero).
  len | the input data length (in bytes).

## ◆ br_ghash_ctmul32()

void br_ghash_ctmul32 | ( | void * | y,
|  | const void * | h,
|  | const void * | data,
|  | size_t | len
| ) |  |

GHASH implementation using multiplications (strict 32-bit).

This implementation uses multiplications of 32-bit values, with a 32-bit result. It is usually somewhat slower than `br_ghash_ctmul()`, but it is expected to be faster on architectures for which the 32-bit multiplication opcode does not yield the upper 32 bits of the product. It is constant-time (if multiplications are constant-time).

Parameters

  y | the array to update.
  h | the GHASH key.
  data | the input data (may be `NULL` if `len` is zero).
  len | the input data length (in bytes).

## ◆ br_ghash_ctmul64()

void br_ghash_ctmul64 | ( | void * | y,
|  | const void * | h,
|  | const void * | data,
|  | size_t | len
| ) |  |

GHASH implementation using multiplications (64-bit).

This implementation uses multiplications of 64-bit values, with a 64-bit result. It is constant-time (if multiplications are constant-time). It is substantially faster than `br_ghash_ctmul()` and `br_ghash_ctmul32()` on most 64-bit architectures.

Parameters

  y | the array to update.
  h | the GHASH key.
  data | the input data (may be `NULL` if `len` is zero).
  len | the input data length (in bytes).

## ◆ br_ghash_pclmul()

void br_ghash_pclmul | ( | void * | y,
|  | const void * | h,
|  | const void * | data,
|  | size_t | len
| ) |  |

GHASH implementation using the `pclmulqdq` opcode (part of the AES-NI instructions).

This implementation is available only on x86 platforms where the compiler supports the relevant intrinsic functions. Even if the compiler supports these functions, the local CPU might not support the `pclmulqdq` opcode, meaning that a call will fail with an illegal instruction exception. To safely obtain a pointer to this function when supported (or 0 otherwise), use `br_ghash_pclmul_get()`.

Parameters

  y | the array to update.
  h | the GHASH key.
  data | the input data (may be `NULL` if `len` is zero).
  len | the input data length (in bytes).

## ◆ br_ghash_pclmul_get()

br_ghash br_ghash_pclmul_get | ( | void |  | ) |

Obtain the `pclmul` GHASH implementation, if available.

If the `pclmul` implementation was compiled in the library (depending on the compiler abilities) and the local CPU appears to support the opcode, then this function will return a pointer to the `br_ghash_pclmul()` function. Otherwise, it will return `0`.

Returns
  the `pclmul` GHASH implementation, or `0`.

## ◆ br_ghash_pwr8()

void br_ghash_pwr8 | ( | void * | y,
|  | const void * | h,
|  | const void * | data,
|  | size_t | len
| ) |  |

GHASH implementation using the POWER8 opcodes.

This implementation is available only on POWER8 platforms (and later). To safely obtain a pointer to this function when supported (or 0 otherwise), use `br_ghash_pwr8_get()`.

Parameters

  y | the array to update.
  h | the GHASH key.
  data | the input data (may be `NULL` if `len` is zero).
  len | the input data length (in bytes).

## ◆ br_ghash_pwr8_get()

br_ghash br_ghash_pwr8_get | ( | void |  | ) |

Obtain the `pwr8` GHASH implementation, if available.

If the `pwr8` implementation was compiled in the library (depending on the compiler abilities) and the local CPU appears to support the opcode, then this function will return a pointer to the `br_ghash_pwr8()` function. Otherwise, it will return `0`.

Returns
  the `pwr8` GHASH implementation, or `0`.

## ◆ br_md5_init()

void br_md5_init | ( | br_md5_context * | ctx | ) |

MD5 context initialisation.

This function initialises or resets a context for a new MD5 computation. It also sets the vtable pointer.

Parameters

  ctx | pointer to the context structure.

## ◆ br_md5_out()

void br_md5_out | ( | const br_md5_context * | ctx,
|  | void * | out
| ) |  |

Compute MD5 output.

The MD5 output for the concatenation of all bytes injected in the provided context since the last initialisation or reset call, is computed and written in the buffer pointed to by `out`. The context itself is not modified, so extra bytes may be injected afterwards to continue that computation.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the hash output.

## ◆ br_md5_set_state()

void br_md5_set_state | ( | br_md5_context * | ctx,
|  | const void * | stb,
|  | uint64_t | count
| ) |  |

Restore MD5 running state.

The running state for MD5 is set to the provided values.

Parameters

  ctx | pointer to the context structure.
  stb | source buffer for the running state.
  count | the injected total byte length.

## ◆ br_md5_state()

uint64_t br_md5_state | ( | const br_md5_context * | ctx,
|  | void * | out
| ) |  |

Save MD5 running state.

The running state for MD5 (output of the last internal block processing) is written in the buffer pointed to by `out`. The number of bytes injected since the last initialisation or reset call is returned. The context is not modified.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the running state.

Returns
  the injected total byte length.

## ◆ br_md5_update()

void br_md5_update | ( | br_md5_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject some data bytes in a running MD5 computation.

The provided context is updated with some data bytes. If the number of bytes (`len`) is zero, then the data pointer (`data`) is ignored and may be `NULL`, and this function does nothing.

Parameters

  ctx | pointer to the context structure.
  data | pointer to the injected data.
  len | injected data length (in bytes).

## ◆ br_md5sha1_init()

void br_md5sha1_init | ( | br_md5sha1_context * | ctx | ) |

MD5+SHA-1 context initialisation.

This function initialises or resets a context for a new SHA-512 computation. It also sets the vtable pointer.

Parameters

  ctx | pointer to the context structure.

## ◆ br_md5sha1_out()

void br_md5sha1_out | ( | const br_md5sha1_context * | ctx,
|  | void * | out
| ) |  |

Compute MD5+SHA-1 output.

The MD5+SHA-1 output for the concatenation of all bytes injected in the provided context since the last initialisation or reset call, is computed and written in the buffer pointed to by `out`. The context itself is not modified, so extra bytes may be injected afterwards to continue that computation.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the hash output.

## ◆ br_md5sha1_set_state()

void br_md5sha1_set_state | ( | br_md5sha1_context * | ctx,
|  | const void * | stb,
|  | uint64_t | count
| ) |  |

Restore MD5+SHA-1 running state.

The running state for MD5+SHA-1 is set to the provided values.

Parameters

  ctx | pointer to the context structure.
  stb | source buffer for the running state.
  count | the injected total byte length.

## ◆ br_md5sha1_state()

uint64_t br_md5sha1_state | ( | const br_md5sha1_context * | ctx,
|  | void * | out
| ) |  |

Save MD5+SHA-1 running state.

The running state for MD5+SHA-1 (output of the last internal block processing) is written in the buffer pointed to by `out`. The number of bytes injected since the last initialisation or reset call is returned. The context is not modified.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the running state.

Returns
  the injected total byte length.

## ◆ br_md5sha1_update()

void br_md5sha1_update | ( | br_md5sha1_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject some data bytes in a running MD5+SHA-1 computation.

The provided context is updated with some data bytes. If the number of bytes (`len`) is zero, then the data pointer (`data`) is ignored and may be `NULL`, and this function does nothing.

Parameters

  ctx | pointer to the context structure.
  data | pointer to the injected data.
  len | injected data length (in bytes).

## ◆ br_multihash_getimpl()

static const br_hash_class * br_multihash_getimpl | ( | const br_multihash_context * | ctx,
|  | int | id
| ) |  |
| inline static

Get a hash function implementation.

This function returns the currently configured vtable for a given hash function (by symbolic ID). If no such function was configured in the provided multi-hasher context, then this function returns `NULL`.

Parameters

  ctx | the multi-hasher context.
  id | the hash function symbolic identifier.

Returns
  the hash function vtable, or `NULL`.

## ◆ br_multihash_init()

void br_multihash_init | ( | br_multihash_context * | ctx | ) |

Reset a multi-hasher context.

This function prepares the context for a new hashing computation, for all implementations configured at that point.

Parameters

  ctx | the multi-hasher context.

## ◆ br_multihash_out()

size_t br_multihash_out | ( | const br_multihash_context * | ctx,
|  | int | id,
|  | void * | dst
| ) |  |

Compute a hash output from a multi-hasher.

The hash output for the concatenation of all bytes injected in the provided context since the last initialisation or reset call, is computed and written in the buffer pointed to by `dst`. The hash function to use is identified by `id` and must be one of the standard hash functions. If that hash function was indeed configured in the multi-hasher context, the corresponding hash value is written in `dst` and its length (in bytes) is returned. If the hash function was not configured, then nothing is written in `dst` and 0 is returned.

The context itself is not modified, so extra bytes may be injected afterwards to continue the hash computations.

Parameters

  ctx | pointer to the context structure.
  id | the hash function symbolic identifier.
  dst | destination buffer for the hash output.

Returns
  the hash output length (in bytes), or 0.

## ◆ br_multihash_setimpl()

static void br_multihash_setimpl | ( | br_multihash_context * | ctx,
|  | int | id,
|  | const br_hash_class * | impl
| ) |  |
| inline static

Set a hash function implementation.

Implementations shall be set after clearing the context (with `br_multihash_zero()`) but before initialising the computation (with `br_multihash_init()`). The hash function implementation MUST be one of the standard hash functions (MD5, SHA-1, SHA-224, SHA-256, SHA-384 or SHA-512); it may also be `NULL` to remove an implementation from the multi-hasher.

Parameters

  ctx | the multi-hasher context.
  id | the hash function symbolic identifier.
  impl | the hash function vtable, or `NULL`.

## ◆ br_multihash_update()

void br_multihash_update | ( | br_multihash_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject some data bytes in a running multi-hashing computation.

The provided context is updated with some data bytes. If the number of bytes (`len`) is zero, then the data pointer (`data`) is ignored and may be `NULL`, and this function does nothing.

Parameters

  ctx | pointer to the context structure.
  data | pointer to the injected data.
  len | injected data length (in bytes).

## ◆ br_multihash_zero()

void br_multihash_zero | ( | br_multihash_context * | ctx | ) |

Clear a multi-hasher context.

This should always be called once on a given context, before setting the implementation pointers.

Parameters

  ctx | the multi-hasher context.

## ◆ br_sha1_init()

void br_sha1_init | ( | br_sha1_context * | ctx | ) |

SHA-1 context initialisation.

This function initialises or resets a context for a new SHA-1 computation. It also sets the vtable pointer.

Parameters

  ctx | pointer to the context structure.

## ◆ br_sha1_out()

void br_sha1_out | ( | const br_sha1_context * | ctx,
|  | void * | out
| ) |  |

Compute SHA-1 output.

The SHA-1 output for the concatenation of all bytes injected in the provided context since the last initialisation or reset call, is computed and written in the buffer pointed to by `out`. The context itself is not modified, so extra bytes may be injected afterwards to continue that computation.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the hash output.

## ◆ br_sha1_set_state()

void br_sha1_set_state | ( | br_sha1_context * | ctx,
|  | const void * | stb,
|  | uint64_t | count
| ) |  |

Restore SHA-1 running state.

The running state for SHA-1 is set to the provided values.

Parameters

  ctx | pointer to the context structure.
  stb | source buffer for the running state.
  count | the injected total byte length.

## ◆ br_sha1_state()

uint64_t br_sha1_state | ( | const br_sha1_context * | ctx,
|  | void * | out
| ) |  |

Save SHA-1 running state.

The running state for SHA-1 (output of the last internal block processing) is written in the buffer pointed to by `out`. The number of bytes injected since the last initialisation or reset call is returned. The context is not modified.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the running state.

Returns
  the injected total byte length.

## ◆ br_sha1_update()

void br_sha1_update | ( | br_sha1_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject some data bytes in a running SHA-1 computation.

The provided context is updated with some data bytes. If the number of bytes (`len`) is zero, then the data pointer (`data`) is ignored and may be `NULL`, and this function does nothing.

Parameters

  ctx | pointer to the context structure.
  data | pointer to the injected data.
  len | injected data length (in bytes).

## ◆ br_sha224_init()

void br_sha224_init | ( | br_sha224_context * | ctx | ) |

SHA-224 context initialisation.

This function initialises or resets a context for a new SHA-224 computation. It also sets the vtable pointer.

Parameters

  ctx | pointer to the context structure.

## ◆ br_sha224_out()

void br_sha224_out | ( | const br_sha224_context * | ctx,
|  | void * | out
| ) |  |

Compute SHA-224 output.

The SHA-224 output for the concatenation of all bytes injected in the provided context since the last initialisation or reset call, is computed and written in the buffer pointed to by `out`. The context itself is not modified, so extra bytes may be injected afterwards to continue that computation.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the hash output.

## ◆ br_sha224_set_state()

void br_sha224_set_state | ( | br_sha224_context * | ctx,
|  | const void * | stb,
|  | uint64_t | count
| ) |  |

Restore SHA-224 running state.

The running state for SHA-224 is set to the provided values.

Parameters

  ctx | pointer to the context structure.
  stb | source buffer for the running state.
  count | the injected total byte length.

## ◆ br_sha224_state()

uint64_t br_sha224_state | ( | const br_sha224_context * | ctx,
|  | void * | out
| ) |  |

Save SHA-224 running state.

The running state for SHA-224 (output of the last internal block processing) is written in the buffer pointed to by `out`. The number of bytes injected since the last initialisation or reset call is returned. The context is not modified.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the running state.

Returns
  the injected total byte length.

## ◆ br_sha224_update()

void br_sha224_update | ( | br_sha224_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject some data bytes in a running SHA-224 computation.

The provided context is updated with some data bytes. If the number of bytes (`len`) is zero, then the data pointer (`data`) is ignored and may be `NULL`, and this function does nothing.

Parameters

  ctx | pointer to the context structure.
  data | pointer to the injected data.
  len | injected data length (in bytes).

## ◆ br_sha256_init()

void br_sha256_init | ( | br_sha256_context * | ctx | ) |

SHA-256 context initialisation.

This function initialises or resets a context for a new SHA-256 computation. It also sets the vtable pointer.

Parameters

  ctx | pointer to the context structure.

## ◆ br_sha256_out()

void br_sha256_out | ( | const br_sha256_context * | ctx,
|  | void * | out
| ) |  |

Compute SHA-256 output.

The SHA-256 output for the concatenation of all bytes injected in the provided context since the last initialisation or reset call, is computed and written in the buffer pointed to by `out`. The context itself is not modified, so extra bytes may be injected afterwards to continue that computation.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the hash output.

## ◆ br_sha256_set_state()

void br_sha256_set_state | ( | br_sha256_context * | ctx,
|  | const void * | stb,
|  | uint64_t | count
| ) |  |

Restore SHA-256 running state.

The running state for SHA-256 is set to the provided values.

Parameters

  ctx | pointer to the context structure.
  stb | source buffer for the running state.
  count | the injected total byte length.

## ◆ br_sha256_state()

uint64_t br_sha256_state | ( | const br_sha256_context * | ctx,
|  | void * | out
| ) |  |

Save SHA-256 running state.

The running state for SHA-256 (output of the last internal block processing) is written in the buffer pointed to by `out`. The number of bytes injected since the last initialisation or reset call is returned. The context is not modified.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the running state.

Returns
  the injected total byte length.

## ◆ br_sha256_update()

void br_sha256_update | ( | br_sha256_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject some data bytes in a running SHA-256 computation.

The provided context is updated with some data bytes. If the number of bytes (`len`) is zero, then the data pointer (`data`) is ignored and may be `NULL`, and this function does nothing.

Parameters

  ctx | pointer to the context structure.
  data | pointer to the injected data.
  len | injected data length (in bytes).

## ◆ br_sha384_init()

void br_sha384_init | ( | br_sha384_context * | ctx | ) |

SHA-384 context initialisation.

This function initialises or resets a context for a new SHA-384 computation. It also sets the vtable pointer.

Parameters

  ctx | pointer to the context structure.

## ◆ br_sha384_out()

void br_sha384_out | ( | const br_sha384_context * | ctx,
|  | void * | out
| ) |  |

Compute SHA-384 output.

The SHA-384 output for the concatenation of all bytes injected in the provided context since the last initialisation or reset call, is computed and written in the buffer pointed to by `out`. The context itself is not modified, so extra bytes may be injected afterwards to continue that computation.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the hash output.

## ◆ br_sha384_set_state()

void br_sha384_set_state | ( | br_sha384_context * | ctx,
|  | const void * | stb,
|  | uint64_t | count
| ) |  |

Restore SHA-384 running state.

The running state for SHA-384 is set to the provided values.

Parameters

  ctx | pointer to the context structure.
  stb | source buffer for the running state.
  count | the injected total byte length.

## ◆ br_sha384_state()

uint64_t br_sha384_state | ( | const br_sha384_context * | ctx,
|  | void * | out
| ) |  |

Save SHA-384 running state.

The running state for SHA-384 (output of the last internal block processing) is written in the buffer pointed to by `out`. The number of bytes injected since the last initialisation or reset call is returned. The context is not modified.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the running state.

Returns
  the injected total byte length.

## ◆ br_sha384_update()

void br_sha384_update | ( | br_sha384_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject some data bytes in a running SHA-384 computation.

The provided context is updated with some data bytes. If the number of bytes (`len`) is zero, then the data pointer (`data`) is ignored and may be `NULL`, and this function does nothing.

Parameters

  ctx | pointer to the context structure.
  data | pointer to the injected data.
  len | injected data length (in bytes).

## ◆ br_sha512_init()

void br_sha512_init | ( | br_sha512_context * | ctx | ) |

SHA-512 context initialisation.

This function initialises or resets a context for a new SHA-512 computation. It also sets the vtable pointer.

Parameters

  ctx | pointer to the context structure.

## ◆ br_sha512_out()

void br_sha512_out | ( | const br_sha512_context * | ctx,
|  | void * | out
| ) |  |

Compute SHA-512 output.

The SHA-512 output for the concatenation of all bytes injected in the provided context since the last initialisation or reset call, is computed and written in the buffer pointed to by `out`. The context itself is not modified, so extra bytes may be injected afterwards to continue that computation.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the hash output.

## ◆ br_sha512_set_state()

void br_sha512_set_state | ( | br_sha512_context * | ctx,
|  | const void * | stb,
|  | uint64_t | count
| ) |  |

Restore SHA-512 running state.

The running state for SHA-512 is set to the provided values.

Parameters

  ctx | pointer to the context structure.
  stb | source buffer for the running state.
  count | the injected total byte length.

## ◆ br_sha512_state()

uint64_t br_sha512_state | ( | const br_sha512_context * | ctx,
|  | void * | out
| ) |  |

Save SHA-512 running state.

The running state for SHA-512 (output of the last internal block processing) is written in the buffer pointed to by `out`. The number of bytes injected since the last initialisation or reset call is returned. The context is not modified.

Parameters

  ctx | pointer to the context structure.
  out | destination buffer for the running state.

Returns
  the injected total byte length.

## ◆ br_sha512_update()

void br_sha512_update | ( | br_sha512_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject some data bytes in a running SHA-512 computation.

The provided context is updated with some data bytes. If the number of bytes (`len`) is zero, then the data pointer (`data`) is ignored and may be `NULL`, and this function does nothing.

Parameters

  ctx | pointer to the context structure.
  data | pointer to the injected data.
  len | injected data length (in bytes).

## Variable Documentation

## ◆ br_md5_vtable

const br_hash_class br_md5_vtable
| extern

Constant vtable for MD5.

## ◆ br_md5sha1_vtable

const br_hash_class br_md5sha1_vtable
| extern

Constant vtable for MD5+SHA-1.

## ◆ br_sha1_vtable

const br_hash_class br_sha1_vtable
| extern

Constant vtable for SHA-1.

## ◆ br_sha224_vtable

const br_hash_class br_sha224_vtable
| extern

Constant vtable for SHA-224.

## ◆ br_sha256_vtable

const br_hash_class br_sha256_vtable
| extern

Constant vtable for SHA-256.

## ◆ br_sha384_vtable

const br_hash_class br_sha384_vtable
| extern

Constant vtable for SHA-384.

## ◆ br_sha512_vtable

const br_hash_class br_sha512_vtable
| extern

Constant vtable for SHA-512.