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  )

inlinestatic

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  )

inlinestatic

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

Constant vtable for MD5.

br_md5sha1_vtable

const br_hash_class br_md5sha1_vtable

Constant vtable for MD5+SHA-1.

br_sha1_vtable

const br_hash_class br_sha1_vtable

Constant vtable for SHA-1.

br_sha224_vtable

const br_hash_class br_sha224_vtable

Constant vtable for SHA-224.

br_sha256_vtable

const br_hash_class br_sha256_vtable

Constant vtable for SHA-256.

br_sha384_vtable

const br_hash_class br_sha384_vtable

Constant vtable for SHA-384.

br_sha512_vtable

const br_hash_class br_sha512_vtable

Constant vtable for SHA-512.