emsha 1.1.0
A compact HMAC-SHA-256 C++11 library.
Classes | Enumerations | Functions | Variables
emsha Namespace Reference

Classes

class  Hash
 
class  HMAC
 
class  SHA256
 

Enumerations

enum class  EMSHAResult : std::uint8_t {
  Unknown = 0 , OK = 1 , TestFailure = 2 , NullPointer = 3 ,
  InvalidState = 4 , InputTooLong = 5 , SelfTestDisabled = 6
}
 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 = 32
 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 class 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
kA byte buffer containing the HMAC key.
klThe length of the HMAC key.
mThe message data over which the HMAC is to be computed.
mlThe length of the message.
dByte 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();
}
const std::uint32_t SHA256_HASH_SIZE
SHA256_HASH_SIZE is the output length of SHA-256 in bytes.
Definition: emsha.h:57
Parameters
aA byte buffer of size Hash::Size().
bA 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
destThe destination byte array at least (2*srclen) bytes in length.
srcA byte array containing the data to hexify.
srclenThe 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
mByte buffer containing the message to hash.
mlThe length of m.
dByte 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 = 32

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.