[sha256sw.h] SHA2 256/224 SW APIs

SHA2 256/224 SW APIs. More...

Collaboration diagram for [sha256sw.h] SHA2 256/224 SW APIs:

Data Structures
struct	SHA256SW_Object
	SHA256SW Object. More...

Macros
#define	SHA256SWHashData   HAPI_TABLE_POINTER->sha256SwHashData
#define	SHA256SWStart   HAPI_TABLE_POINTER->sha256SwStart
#define	SHA256SWAddData   HAPI_TABLE_POINTER->sha256SwAddData
#define	SHA256SWFinalize   HAPI_TABLE_POINTER->sha256SwFinalize

Typedefs
typedef SHA256SW_Object *	SHA256SW_Handle
	A handle to a SHA256SW_Object. More...

Functions
int_fast16_t	SHA256SWHashData (SHA256SW_Handle handle, SHA2SW_HashType hashType, const void *data, size_t length, uint32_t digest[8])
	Performs a complete hash operation, producing a final digest for the data. More...
int_fast16_t	SHA256SWStart (SHA256SW_Handle handle, SHA2SW_HashType hashType)
	Initialize a SHA256SW_Handle, preparing for hashing data. More...
int_fast16_t	SHA256SWAddData (SHA256SW_Handle handle, const void *data, size_t length)
	Add data to a SHA256/224 operation. More...
int_fast16_t	SHA256SWFinalize (SHA256SW_Handle handle, uint32_t digest[8])
	Finalize a SHA256/224 operation, creating the final digest. More...

Detailed Description

SHA2 256/224 SW APIs.

Overview

Provides top-level general purpose SHA2 256/224 APIs. SHA2 algorithm is implemented in SW with no HW acceleration. The implementation is highly optimized for speed and code size. These functions reside in ROM, and are exposed through HAPI, and also through the function prototypes and macros below.

Availability of SHA2 224 depends on build configuration. See file sha2sw_config.h.

Limitations

• A maximum of 512MiB may be hashed by this implementation. (SHA2 standard supports 2 million Terabytes for 224/256)
• Input data may be 8-bit aligned. However, output digest must be 32-bit aligned.
• Intermediate values, input data, and final digest value may be left behind on the stack.

---

Usage

There are two general ways to execute a SHA2 operation:

• one-step, using SHA256SWHashData()
• multi-step, using SHA256SWStart(), SHA256SWAddData(), and SHA256SWFinalize()

The multi-step approach allows the hash to be extended by adding more data.

All input data is to be in little-endian (LE) format and the resulting hash values produced by these APIs are in LE format.

Synopsis

The following is a quick overview of one-step hashing.

// Import SHA2 SW Driver definitions
#include <sha256sw.h>

// Create an object and handle
SHA256SW_Object sha256SWObject;
SHA256SW_Handle sha256SWHandle = &sha256SWObject;

// Allocate space for digest output
uint32_t actualDigest[8];

result = SHA256SWHashData(sha256SWHandle, SHA2SW_HASH_TYPE_256,
                           message, strlen(message), actualDigest);

---

Examples

• Hashing data in one call
• Hashing data in multiple calls

Hashing data in one call

SHA256SW_Object sha256SWObject;
SHA256SW_Handle sha256SWHandle = &sha256SWObject;
int_fast16_t sha2SWresult;
uint32_t finalDigest[8];
int notsame;

char message[] =
        "abcdefghijklmnabcdefghijklmnabcdefghijklmnabcdefghijklmn1234";
uint8_t expectedDigest[] =
        { 0x60, 0x06, 0x00, 0x24, 0x13, 0xe4, 0x27, 0x0d,
          0x4d, 0xdb, 0x66, 0x93, 0x42, 0xa9, 0xe2, 0xdb,
          0x66, 0x5e, 0xc8, 0x70, 0x73, 0xc4, 0x2e, 0xb5,
          0x44, 0x99, 0x62, 0xf1, 0x2a, 0xb2, 0xe8, 0x60 };

sha2SWresult = SHA256SWHashData(sha256SWHandle, SHA2SW_HASH_TYPE_256,
                                 message, strlen(message), finalDigest);

if (sha2SWresult != SHA2SW_STATUS_SUCCESS)
{
    while(1);
}

// NOTE: If expectedDigest is a secret value, a timing constant comparison
// routine shall be used instead of memcmp.
notsame = memcmp(finalDigest, expectedDigest, sizeof(finalDigest));

if (notsame)
{
    while(1);
}

Hashing data in multiple calls

SHA256SW_Object sha256SWObject;
SHA256SW_Handle sha256SWHandle = &sha256SWObject;
int_fast16_t sha2SWresult;
uint32_t finalDigest[8];
int notsame;

char message[] =
        "abcdefghijklmnabcdefghijklmnabcdefghijklmnabcdefghijklmn1234";
uint8_t expectedDigest[] =
        { 0x60, 0x06, 0x00, 0x24, 0x13, 0xe4, 0x27, 0x0d,
          0x4d, 0xdb, 0x66, 0x93, 0x42, 0xa9, 0xe2, 0xdb,
          0x66, 0x5e, 0xc8, 0x70, 0x73, 0xc4, 0x2e, 0xb5,
          0x44, 0x99, 0x62, 0xf1, 0x2a, 0xb2, 0xe8, 0x60, };


sha2SWresult = SHA256SWStart(sha256SWHandle, SHA2SW_HASH_TYPE_256);

if (sha2SWresult == SHA2SW_STATUS_SUCCESS) {
    sha2SWresult = SHA256SWAddData(sha256SWHandle, message, 20);
}

if (sha2SWresult == SHA2SW_STATUS_SUCCESS) {
    sha2SWresult = SHA256SWAddData(sha256SWHandle, &message[20], strlen(message) - 20);
}

if (sha2SWresult == SHA2SW_STATUS_SUCCESS) {
    sha2SWresult = SHA256SWFinalize(sha256SWHandle, finalDigest);
}

if (sha2SWresult != SHA2SW_STATUS_SUCCESS)
{
    while(1);
}

// NOTE: If expectedDigest is a secret value, a timing constant comparison
// routine shall be used instead of memcmp.
notsame = memcmp(finalDigest, expectedDigest, sizeof(finalDigest));

if (notsame)
{
    while(1);
}

---

Configuration

See file sha2sw_config.h for full configuration information.

If SHA2SW_VALIDATE_INPUTS is not defined then:

• the caller is responsible for ensuring all inputs are valid, and
• the module's functions will only return SHA2SW_STATUS_SUCCESS

Macro Definition Documentation

SHA256SWHashData

#define SHA256SWHashData   HAPI_TABLE_POINTER->sha256SwHashData

SHA256SWStart

#define SHA256SWStart   HAPI_TABLE_POINTER->sha256SwStart

SHA256SWAddData

#define SHA256SWAddData   HAPI_TABLE_POINTER->sha256SwAddData

SHA256SWFinalize

#define SHA256SWFinalize   HAPI_TABLE_POINTER->sha256SwFinalize

Typedef Documentation

SHA256SW_Handle

typedef SHA256SW_Object* SHA256SW_Handle

A handle to a SHA256SW_Object.

Function Documentation

SHA256SWHashData()

int_fast16_t SHA256SWHashData	(	SHA256SW_Handle	handle,
		SHA2SW_HashType	hashType,
		const void *	data,
		size_t	length,
		uint32_t	digest[8]
	)

Performs a complete hash operation, producing a final digest for the data.

This function wraps SHA256SWStart(), SHA256SWAddData(), and SHA256SWFinalize().

There is no need to call SHA256SWStart() prior to calling this function.

The total length of data that can be hashed by this implementation is 512MiB (0x20000000 bytes.)

Parameters

[in]	handle	A SHA256SW_Handle.
[in]	hashType	The type of hash (256 or 224) to perform.
[in]	data	data (message) to hash. May point to zero.
[in]	length	the number of bytes (pointed to by data parameter) to add to the hash.
[out]	digest	Output location for the final digest. Must be able to hold 32 bytes of output and be 32-bit aligned.

Return values

SHA2SW_STATUS_SUCCESS	The hash operation succeeded.
SHA2SW_STATUS_ERROR	The hash operation failed.
SHA2SW_STATUS_UNSUPPORTED	Requested Hash Type is unsupported.
SHA2SW_STATUS_LENGTH_TOO_LARGE	The requested length of data to hash is more than the implementation supports.
SHA2SW_STATUS_NULL_INPUT	One or more of the pointer inputs is NULL.

SHA256SWStart()

int_fast16_t SHA256SWStart	(	SHA256SW_Handle	handle,
		SHA2SW_HashType	hashType
	)

Initialize a SHA256SW_Handle, preparing for hashing data.

Parameters

[in]	handle	A SHA256SW_Handle.
[in]	hashType	The type of hash (256 or 224) to perform.

Return values

SHA2SW_STATUS_SUCCESS	The hash operation succeeded.
SHA2SW_STATUS_UNSUPPORTED	Requested Hash Type is unsupported.
SHA2SW_STATUS_NULL_INPUT	One or more of the pointer inputs is NULL.

See also

SHA256SWAddData()

SHA256SWFinalize()

SHA256SWAddData()

int_fast16_t SHA256SWAddData	(	SHA256SW_Handle	handle,
		const void *	data,
		size_t	length
	)

Add data to a SHA256/224 operation.

Adds data to a hash operation. The handle must have been initialized by a call to SHA256SWStart first.

The total length of data that can be hashed by this implementation is 512MiB (0x20000000 bytes.)

After passing in all data to be hashed, call SHA256SWFinalize() to obtain the final digest.

Precondition

handle was previously passed to SHA256SWStart().

Parameters

[in]	handle	A SHA256SW_Handle.
[in]	data	data (message) to add to the hash. May point to zero.
[in]	length	the number of bytes (pointed to by data parameter) to add to the hash.

Return values

SHA2SW_STATUS_SUCCESS	The hash operation succeeded.
SHA2SW_STATUS_LENGTH_TOO_LARGE	The requested length of data to hash is more than the implementation supports.
SHA2SW_STATUS_NULL_INPUT	One or more of the pointer inputs is NULL.

See also

SHA256SWStart()

SHA256SWFinalize()

SHA256SWFinalize()

int_fast16_t SHA256SWFinalize	(	SHA256SW_Handle	handle,
		uint32_t	digest[8]
	)

Finalize a SHA256/224 operation, creating the final digest.

After calling this function, handle should not be used again until it has been reinitialized via a call to SHA256SWStart().

Precondition

handle was previously passed to SHA256SWStart() and data to be hashed was passed to SHA256SWAddData()

Parameters

[in]	handle	A SHA256SW_Handle.
[out]	digest	Output location for the final digest. Must be able to hold 32 bytes of output and be 32-bit aligned.

Return values

SHA2SW_STATUS_SUCCESS	The hash operation succeeded.
SHA2SW_STATUS_NULL_INPUT	One or more of the pointer inputs is NULL.

See also

SHA256SWStart()

SHA256SWAddData()