emsha Namespace Reference

Classes
class	Hash
class	HMAC
class	SHA256

Enumerations
enum class	EMSHAResult : std::uint8_t {   Unknown = 0U , OK = 1U , TestFailure = 2U , NullPointer = 3U ,   InvalidState = 4U , InputTooLong = 5U , SelfTestDisabled = 6U }
	Describe the result of an EMSHA operation. More...

Functions
bool	HashEqual (const std::uint8_t *a, const std::uint8_t *b)
	Constant-time function for comparing two digests. More...
void	HexString (std::uint8_t *dest, std::uint8_t *src, std::uint32_t srclen)
	Write a hex-encoded version of a byte string. More...
EMSHAResult	ComputeHMAC (const uint8_t *k, const uint32_t kl, const uint8_t *m, const uint32_t ml, uint8_t *d)
	Perform a single-pass HMAC computation over a message. More...
EMSHAResult	SHA256Digest (const uint8_t *m, uint32_t ml, uint8_t *d)
	SHA256Digest performs a single pass hashing of the message passed in. More...
EMSHAResult	SHA256SelfTest ()
	SHA256SelfTest runs through two test cases to ensure that the SHA-256 functions are working correctly. More...

Variables
const std::uint32_t	SHA256_HASH_SIZE = 32U
	SHA256_HASH_SIZE is the output length of SHA-256 in bytes. More...
const uint32_t	HMAC_KEY_LENGTH = SHA256_MB_SIZE
const uint32_t	SHA256_MB_SIZE = 64
	SHA256_MB_SIZE is the size of a message block. More...

Enumeration Type Documentation

EMSHAResult

enum emsha::EMSHAResult : std::uint8_t

strong

Describe the result of an EMSHA operation.

The EMSHAResult type is used to indicate whether an operation succeeded, and if not, what the general fault type was.

Enumerator
Unknown	An unknown fault occurred. This is a serious bug in the program.
OK	All operations have completed successfully so far.
TestFailure	The self-test failed.
NullPointer	A null pointer was passed in as a buffer where it shouldn't have been.
InvalidState	The Hash is in an invalid state.
InputTooLong	The input to SHA256::update is too large.
SelfTestDisabled	The self tests have been disabled, but a self-test function was called.

Function Documentation

ComputeHMAC()

EMSHAResult emsha::ComputeHMAC	(	const uint8_t *	k,
		const uint32_t	kl,
		const uint8_t *	m,
		const uint32_t	ml,
		uint8_t *	d
	)

Perform a single-pass HMAC computation over a message.

Parameters

k	A byte buffer containing the HMAC key.
kl	The length of the HMAC key.
m	The message data over which the HMAC is to be computed.
ml	The length of the message.
d	Byte buffer that will be used to store the resulting HMAC. It should be emsha::SHA256_HASH_SIZE bytes in size.

Returns

An EMSHAResult describing the result of the HMAC operation.

HashEqual()

bool emsha::HashEqual	(	const std::uint8_t *	a,
		const std::uint8_t *	b
	)

Constant-time function for comparing two digests.

HashEqual provides a constant time function for comparing two digests. The caller must ensure that both a and b are the same size. The recommended approach is to use fixed-size buffers of emsha::SHA256_HASH_SIZE length:

 {c++}
uint8_t expected[emsha::SHA256_HASH_SIZE];
uint8_t actual[emsha::SHA256_HASH_SIZE];
 
// Fill in expected and actual using the Hash operations.
 
if (hash_equal(expected, actual)) {
        proceed();
}

Parameters

a	A byte buffer of size Hash::Size().
b	A byte buffer of size Hash::Size().

Returns

True if both byte arrays match.

HexString()

void emsha::HexString	(	std::uint8_t *	dest,
		std::uint8_t *	src,
		std::uint32_t	srclen
	)

Write a hex-encoded version of a byte string.

HexString writes a hex-encoded version of the src byte array into dest. The caller must ensure that dest is srclen * 2 bytes or longer.

Parameters

dest	The destination byte array at least (2*srclen) bytes in length.
src	A byte array containing the data to hexify.
srclen	The size in bytes of src.

SHA256Digest()

EMSHAResult emsha::SHA256Digest	(	const uint8_t *	m,
		uint32_t	ml,
		uint8_t *	d
	)

SHA256Digest performs a single pass hashing of the message passed in.

Parameters

m	Byte buffer containing the message to hash.
ml	The length of m.
d	Byte buffer that will be used to store the resulting hash; it should have at least emsha::SHA256_HASH_SIZE bytes available.

Returns

An EMSHAResult describing the result of the operation.

SHA256SelfTest()

EMSHAResult emsha::SHA256SelfTest

(

)

SHA256SelfTest runs through two test cases to ensure that the SHA-256 functions are working correctly.

Returns

The result of the self-test.

    - EMSHAResult::OK is returned if the self tests pass.
    - EMSHAResult::SelfTestDisabled is returned if the self
      tests have been disabled (e.g., libemsha was compiled
      with the EMSHA_NO_SELFTEST #define).
    - If a fault occurred inside the SHA-256 code, the error
      code from one of the update, finalize, result, or reset
      methods is returned.
    - If the fault is that the output does not match the test
      vector, EMSHAResult::TestFailure is returned. 

Variable Documentation

HMAC_KEY_LENGTH

const uint32_t emsha::HMAC_KEY_LENGTH = SHA256_MB_SIZE

SHA256_HASH_SIZE

const std::uint32_t emsha::SHA256_HASH_SIZE = 32U

SHA256_HASH_SIZE is the output length of SHA-256 in bytes.

SHA256_MB_SIZE

const uint32_t emsha::SHA256_MB_SIZE = 64

SHA256_MB_SIZE is the size of a message block.