Hashing functions
[Cryptographic functions]

Common cryptographic hash functions. More...

Data Structures
struct	BC_HASH
	Hash state descriptor object. More...
struct	BC_HMAC
	HMAC state descriptor object. More...
Functions
void	BC_HashInit (BC_HASH *hash, const struct bc_hfun_s *func)
	Initialise hash calculations.
void	BC_HashData (BC_HASH *hash, const void *data, unsigned dlen)
	Feeds data into a hash.
void	BC_HashDone (const BC_HASH *hash, void *data)
	Calculate the hash value of the data fed to the hash function so far.
void	BC_HmacInit (BC_HMAC *hmac, const struct bc_hfun_s *func, const void *kptr, unsigned int klen)
	Initialise a HMAC calculation.
void	BC_HmacData (BC_HMAC *hmac, const void *data, unsigned dlen)
	Process the next data block in a HMAC calculations.
void	BC_HmacDone (const BC_HMAC *hmac, void *data)
	Finalises a HMAC calculation.

---

Detailed Description

Common cryptographic hash functions.

A hash function is a function that receives some input of arbitrary length and generates a fixed length output. Since the input is usually much longer than the output, you can not recover the input from the output. Furthermore, even a single bit change in the input will cause many bits of the output to change. Since the output is of a fixed length capable of representing only a finite number of possible values but there are infinitely many possible inputs, there will be clashes, when two different inputs generate the same output. However, cryptographic hash functions are designed to make such clashes extremely improbable on similar inputs. Therefore, hash functions can be used to verify that a message is not altered.

The most commonly used two cryptographic hash functions, MD5 and SHA-1 are implemented in this sub-module. In addition, HMAC, the keyed hash message authentication code (using MD5 or SHA-1) is also provided.

Although MD5 has been broken (meaning that there exist programs that can generate input that will hash to a given output value), it is probably the most frequently used cryptographic hash function. SHA-1 is more resistent; even though vulnerabilities of the algorithm were identified, as of 2009 it has not been broken yet.

To use the these functions, you need to include crypto/hash.h.

The following table gives you a rough idea about the performance of the various hash functions. The values represent the time (in milliseconds) required to calculate the hash of 1KB of data using various functions. The final calculation of the hash is included in the time. The performance of these functions is significantly different depending on whether you use the ARM or the THUMB versions. If you can afford the FLASH, you should consider enabling interworking and use the ARM version of the crypto library even if you use THUMB mode otherwise. The times were measured on an LPC23xx running at 60MHz.

Time needed to hash 1KB of data [ms]

Hash function     ARM      THUMB

MD5               1.38     2.30
MD5 fast          0.77     1.25
SHA1              1.48     2.92
SHA1 fast         1.13     1.81

---

Function Documentation

void BC_HashData	(	BC_HASH *	hash,
		const void *	data,
		unsigned	dlen
	)

Feeds data into a hash.

The function takes an already initialised hash state descriptor, a pointer to some data and the length of the data and upgrades the hash state with the data. The data is not changed. Subsequent calls to this function are equivalent to a single call with the data for the separate calls concatenated, that is,

    BC_HashData( &myhash, "abc", 3 );
    BC_HashData( &myhash, "def", 3 );

is equivalent to

    BC_HashData( &myhash, "abcdef", 6 );

Parameters:

	hash	Pointer to a BC_HASH structure, the hash state.
	data	Pointer to the data to feed to the hash.
	dlen	The length of the data.

void BC_HashDone	(	const BC_HASH *	hash,
		void *	data
	)

Calculate the hash value of the data fed to the hash function so far.

The function calculates the actual value of an MD5 or SHA1 hash, on the data that has been fed into the hash state so far. The final hash value is stored in the result buffer. For MD5 the buffer must be at least 16 bytes long, for SHA1 it must be at least 20 bytes long. The hash state is not changed, therefore further data can be fed to the hash. This allows the calculation of hash values on portions of the data.

Parameters:

	hash	The hash state, which is not modified.
	data	Pointer to the result buffer. For MD5 it must be 16, for SHA1 20 bytes long.

void BC_HashInit	(	BC_HASH *	hash,
		const struct bc_hfun_s *	func
	)

Initialise hash calculations.

The function prepares for a hash calculation. The hash state, passed as a pointer to a BC_HASH structure is prepared to be ready to receive data of which the hash should be calculated. The second argument is a pointer to an opaque structure. That structure defines the hash function to be used. Four such structures are defined by the library and they are #define-d:

• BC_HASH_MD5
  The hash will use the MD5 algorithm, resulting in a 16-byte hash value.
• BC_HASH_MD5_FAST
  The has will use the MD5 algorithm, but the hash calculating core is faster (and larger). Apart from the code size and the speed there's no difference between BC_HASH_MD5 and BC_HASH_MD5_FAST.
• BC_HASH_SHA1
  The hash will use the SHA-1 algorithm, resulting in a 20-byte hash value.
• BC_HASH_MD5_FAST
  The has will use the SHA-1 algorithm, but the hash calculating core is somewhat faster (and much larger). Apart from the code size and the speed there's no difference between BC_HASH_SHA1 and BC_HASH_SHA1_FAST.

Parameters:

	hash	Pointer to a BC_HASH structure, the hash state.
	func	Pointer to an opaque structure that selects the hash function. Use the predefined values described above.

void BC_HmacData	(	BC_HMAC *	hmac,
		const void *	data,
		unsigned	dlen
	)

Process the next data block in a HMAC calculations.

Parameters:

	hmac	Pointer to the HMAC state
	data	Pointer to data
	dlen	The length of the data, in bytes.

void BC_HmacDone	(	const BC_HMAC *	hmac,
		void *	data
	)

Finalises a HMAC calculation.

The function modifies neither the HMAC state nor the data, therefore it can be used to calculate the partial HMAC value at any given point of a bytestream.

Parameters:

	hmac	Pointer to the HMAC state
	data	Pointer to the result buffer (16 or 20 bytes, for MD5 and SHA1 respectively).

void BC_HmacInit	(	BC_HMAC *	hmac,
		const struct bc_hfun_s *	func,
		const void *	kptr,
		unsigned int	klen
	)

Initialise a HMAC calculation.

This function prepares for a HMAC operation. It can use MD5 or SHA-1 as its hash function. This call prepares the BC_HMAC structure passed as the first argumanet. The hash funtion that will be used is determined by the second argument, which should be one of BC_HASH_MD5, BC_HASH_SHA1, BC_HASH_MD5_FAST or BC_HASH_SHA1_FAST. The third argument is apointer to the key and the fourth is the length of the key, in bytes.

Parameters:

	hmac	Pointer to the HMAC state structure
	func	The hash function to use, the same as the parameter for the BC_HashInit() function.
	kptr	Pointer to the HMAC key
	klen	The length of the key (in bytes).