SHA2 driver header.
SHA2 (Secure Hash Algorithm 2) is a cryptographic hashing algorithm that maps an input of arbitrary length to a fixed-length output with negligible probability of collision. A collision would occur when two different inputs map to the same output.
It is not currently technologicaly feasible to derive an input from the hash digest (output) itself.
Hashes are often used to ensure the integrity of messages. They are also used to as constituent parts of more complicated cyptographic schemes. HMAC is a message authentication code that is based on hash functions such as SHA2 rather than a block cipher. Hashes may themselves be used as or form a part of key derivation functions used to derive symmetric keys from sources of entropy such as an Elliptic Curve Diffie-Helman key exchange (ECDH).
SHA2 is not actually a single algorithm, but a suite of similar algorithms that produce hash digests of different lengths. 224, 256, 384, and 512-bit outputs are available.
"Hash" may refer to either the process of hashing when used as a verb and the output digest when used as a noun.
Before starting a SHA2 operation, the application must do the following:
There are two general ways to execute a SHA2 operation:
The SHA2_hashData() function can perform a SHA2 operation in a single call. It will always use the most highly optimized routine with the least overhead and the fastest runtime. However, it requires that the entire input message is available to the function in a contiguous location at the start of the call. The single call operation is required when hashing a message with a length smaller than or equal to one hash-block length. All devices support single call operations.
After a SHA2 operation completes, the application may either start another operation or close the driver by calling SHA2_close().
When trying to operate on data that is too large to fit into available memory, partial processing is more advisable. The segments are processed with SHA2_addData() whereas the final digest is computed by SHA2_finalize().
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
Go to the source code of this file.
Data Structures | |
struct | SHA2_Config |
SHA2 Global configuration. More... | |
struct | SHA2_Params |
SHA2 Parameters. More... | |
Macros | |
#define | SHA2_STATUS_RESERVED (-32) |
#define | SHA2_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | SHA2_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | SHA2_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | SHA2_STATUS_CANCELED (-3) |
The ongoing operation was canceled. More... | |
Typedefs | |
typedef struct SHA2_Config | SHA2_Config |
SHA2 Global configuration. More... | |
typedef SHA2_Config * | SHA2_Handle |
A handle that is returned from an SHA2_open() call. More... | |
typedef void(* | SHA2_CallbackFxn) (SHA2_Handle handle, int_fast16_t returnStatus) |
The definition of a callback function used by the SHA2 driver when used in SHA2_RETURN_BEHAVIOR_CALLBACK. More... | |
Enumerations | |
enum | SHA2_ReturnBehavior { SHA2_RETURN_BEHAVIOR_CALLBACK = 1, SHA2_RETURN_BEHAVIOR_BLOCKING = 2, SHA2_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which SHA2 function calls return after performing an operation. More... | |
enum | SHA2_HashType { SHA2_HASH_TYPE_224 = 0, SHA2_HASH_TYPE_256 = 1, SHA2_HASH_TYPE_384 = 2, SHA2_HASH_TYPE_512 = 3 } |
Enum for the hash types supported by the driver. More... | |
enum | SHA2_DigestLengthBytes { SHA2_DIGEST_LENGTH_BYTES_224 = 28, SHA2_DIGEST_LENGTH_BYTES_256 = 32, SHA2_DIGEST_LENGTH_BYTES_384 = 48, SHA2_DIGEST_LENGTH_BYTES_512 = 64 } |
Enum for the hash digest lengths in bytes supported by the driver. More... | |
enum | SHA2_BlockSizeBytes { SHA2_BLOCK_SIZE_BYTES_224 = 64, SHA2_BLOCK_SIZE_BYTES_256 = 64, SHA2_BLOCK_SIZE_BYTES_384 = 128, SHA2_BLOCK_SIZE_BYTES_512 = 128 } |
Enum for the block sizes of the algorithms. More... | |
Functions | |
void | SHA2_init (void) |
Initializes the SHA2 driver module. More... | |
void | SHA2_Params_init (SHA2_Params *params) |
Initializes params with default values. More... | |
SHA2_Handle | SHA2_open (uint_least8_t index, const SHA2_Params *params) |
Initializes a SHA2 driver instance and returns a handle. More... | |
void | SHA2_close (SHA2_Handle handle) |
Closes a SHA2 peripheral specified by handle. More... | |
int_fast16_t | SHA2_addData (SHA2_Handle handle, const void *data, size_t length) |
Adds a segment of data with a length in bytes to the cryptographic hash. More... | |
int_fast16_t | SHA2_hashData (SHA2_Handle handle, const void *data, size_t size, void *digest) |
Hashes a segment of data with a size in bytes and writes the resulting hash to digest. More... | |
int_fast16_t | SHA2_finalize (SHA2_Handle handle, void *digest) |
Finishes hash a operation and writes the result to digest. More... | |
void | SHA2_reset (SHA2_Handle handle) |
Clears internal buffers and aborts an ongoing SHA2 operation. More... | |
int_fast16_t | SHA2_cancelOperation (SHA2_Handle handle) |
Aborts an ongoing SHA2 operation and clears internal buffers. More... | |
int_fast16_t | SHA2_setHashType (SHA2_Handle handle, SHA2_HashType type) |
Selects a new hash algorithm type. More... | |
SHA2_Handle | SHA2_construct (SHA2_Config *config, const SHA2_Params *params) |
Constructs a new SHA2 object. More... | |
Variables | |
const SHA2_Config | SHA2_config [] |
Global SHA2 configuration struct. More... | |
const uint_least8_t | SHA2_count |
Global SHA2 configuration count. More... | |
const SHA2_Params | SHA2_defaultParams |
Default SHA2_Params structure. More... | |
#define SHA2_STATUS_RESERVED (-32) |
Common SHA2 status code reservation offset. SHA2 driver implementations should offset status codes with SHA2_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define SHA2_STATUS_SUCCESS (0) |
Successful status code.
Functions return SHA2_STATUS_SUCCESS if the function was executed successfully.
#define SHA2_STATUS_ERROR (-1) |
Generic error status code.
Functions return SHA2_STATUS_ERROR if the function was not executed successfully and no more specific error is applicable.
#define SHA2_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable.
SHA2 driver implementations may have hardware or software limitations on how many clients can simultaneously perform operations. This status code is returned if the mutual exclusion mechanism signals that an operation cannot currently be performed.
#define SHA2_STATUS_CANCELED (-3) |
The ongoing operation was canceled.
typedef struct SHA2_Config SHA2_Config |
SHA2 Global configuration.
The SHA2_Config structure contains a set of pointers used to characterize the SHA2 driver implementation.
This structure needs to be defined before calling SHA2_init() and it must not be changed thereafter.
typedef SHA2_Config* SHA2_Handle |
A handle that is returned from an SHA2_open() call.
typedef void(* SHA2_CallbackFxn) (SHA2_Handle handle, int_fast16_t returnStatus) |
The definition of a callback function used by the SHA2 driver when used in SHA2_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the SHA2 operation. |
returnStatus | The result of the SHA2 operation. May contain an error code. Informs the application of why the callback function was called. |
enum SHA2_ReturnBehavior |
The way in which SHA2 function calls return after performing an operation.
Not all SHA2 operations exhibit the specified return behavor. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specfied return behavior is not implementation dependent. Specifically, a software-backed implementation run on the same CPU as the application will emulate the return behavior while not actually offloading the computation to the background thread.
SHA2 functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
SHA2_RETURN_BEHAVIOR_CALLBACK | X | X | X |
SHA2_RETURN_BEHAVIOR_BLOCKING | X | ||
SHA2_RETURN_BEHAVIOR_POLLING | X | X | X |
enum SHA2_HashType |
enum SHA2_BlockSizeBytes |
Enum for the block sizes of the algorithms.
SHA2 iteratively consumes segments of the block size and computes intermediate digests which are fed back into the algorithm together with the next segment to compute the next intermediate or final digest. The block sizes of the algorithms differ from their digest lengths. When performing partial hashes, the segment lengths for all but the last segment must be multiples of the relevant block size.
Enumerator | |
---|---|
SHA2_BLOCK_SIZE_BYTES_224 | |
SHA2_BLOCK_SIZE_BYTES_256 | |
SHA2_BLOCK_SIZE_BYTES_384 | |
SHA2_BLOCK_SIZE_BYTES_512 |
void SHA2_init | ( | void | ) |
Initializes the SHA2 driver module.
void SHA2_Params_init | ( | SHA2_Params * | params | ) |
Initializes params with default values.
params | A pointer to SHA2_Params structure for initialization |
Defaults values are: returnBehavior = SHA2_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
SHA2_Handle SHA2_open | ( | uint_least8_t | index, |
const SHA2_Params * | params | ||
) |
Initializes a SHA2 driver instance and returns a handle.
index | Logical peripheral number for the SHA2 indexed into the SHA2_config table |
params | Pointer to a parameter block, if NULL it will use default values. |
void SHA2_close | ( | SHA2_Handle | handle | ) |
Closes a SHA2 peripheral specified by handle.
handle | A SHA2_Handle returned from SHA2_open() |
int_fast16_t SHA2_addData | ( | SHA2_Handle | handle, |
const void * | data, | ||
size_t | length | ||
) |
Adds a segment of data with a length in bytes to the cryptographic hash.
SHA2_addData() may be called arbitrary times before finishing the operation with SHA2_finalize().
This function blocks until the final digest hash been computed. It returns immediately when SHA2_RETURN_BEHAVIOR_CALLBACK is set.
handle | A SHA2_Handle returned from SHA2_open() |
data | Pointer to the location to read from. There might be alignment restrictions on different platforms. |
length | Length of the message segment to hash, in bytes. |
SHA2_STATUS_SUCCESS | The hash operation succeeded. |
SHA2_STATUS_ERROR | The hash operation failed. |
SHA2_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
SHA2_STATUS_CANCELED | The hash operation was canceled. |
int_fast16_t SHA2_hashData | ( | SHA2_Handle | handle, |
const void * | data, | ||
size_t | size, | ||
void * | digest | ||
) |
Hashes a segment of data with a size in bytes and writes the resulting hash to digest.
The digest content is computed in one step. Intermediate data from a previous partial operation started with SHA2_addData() is discarded.
This function blocks until the final digest hash been computed. It returns immediately when SHA2_RETURN_BEHAVIOR_CALLBACK is set.
handle | A SHA2_Handle returned from SHA2_open() |
data | Pointer to the location to read from. There might be alignment restrictions on different platforms. |
size | Length of the message segment to hash, in bytes. |
digest | Pointer to the location to write the digest to. There might be alignment restrictions on different platforms. |
SHA2_STATUS_SUCCESS | The hash operation succeeded. |
SHA2_STATUS_ERROR | The hash operation failed. |
SHA2_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
SHA2_STATUS_CANCELED | The hash operation was canceled. |
int_fast16_t SHA2_finalize | ( | SHA2_Handle | handle, |
void * | digest | ||
) |
Finishes hash a operation and writes the result to digest.
This function finishes a hash operation that has been previously started by SHA2_addData().
This function blocks until the final digest hash been computed. It returns immediately when SHA2_RETURN_BEHAVIOR_CALLBACK is set.
handle | A SHA2_Handle returned from SHA2_open() |
digest | Pointer to the location to write the digest to. |
SHA2_STATUS_SUCCESS | The hash operation succeeded. |
SHA2_STATUS_ERROR | The hash operation failed. |
SHA2_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
SHA2_STATUS_CANCELED | The hash operation was canceled. |
void SHA2_reset | ( | SHA2_Handle | handle | ) |
Clears internal buffers and aborts an ongoing SHA2 operation.
Clears all internal buffers and the intermediate digest of this driver instance. If an asynchronous operation is ongoing, the behavior is the same as for SHA2_cancelOperation().
handle | A SHA2_Handle returned from SHA2_open() |
int_fast16_t SHA2_cancelOperation | ( | SHA2_Handle | handle | ) |
Aborts an ongoing SHA2 operation and clears internal buffers.
Aborts an ongoing hash operation of this driver instance. The operation will terminate as though an error occured and the status code of the operation will be SHA2_STATUS_CANCELED in this case.
handle | A SHA2_Handle returned from SHA2_open() |
SHA2_STATUS_SUCCESS | The operation was canceled. |
SHA2_STATUS_ERROR | The operation was not canceled. There may be no operation to cancel. |
int_fast16_t SHA2_setHashType | ( | SHA2_Handle | handle, |
SHA2_HashType | type | ||
) |
Selects a new hash algorithm type.
This function changes the hash algorithm type of the hash digest at run-time. The hash type is usually specified during SHA2_open().
Neither is it allowed to call this function during a running hash operation nor during an incomplete multistep hash operation. In this case SHA2_STATUS_ERROR would be returned.
handle | A SHA2_Handle returned from SHA2_open() |
type | New hash algorithm type |
SHA2_STATUS_SUCCESS | Hash type set correctly. |
SHA2_STATUS_ERROR | Error. Platform may not support this hash type. |
SHA2_Handle SHA2_construct | ( | SHA2_Config * | config, |
const SHA2_Params * | params | ||
) |
Constructs a new SHA2 object.
Unlike SHA2_open(), SHA2_construct() does not require the hwAttrs and object to be allocated in a SHA2_Config array that is indexed into. Instead, the SHA2_Config, hwAttrs, and object can be allocated at any location. This allows for relatively simple run-time allocation of temporary driver instances on the stack or the heap. The drawback is that this makes it more difficult to write device-agnostic code. If you use an ifdef with DeviceFamily, you can choose the correct object and hwAttrs to allocate. That compilation unit will be tied to the device it was compiled for at this point. To change devices, recompilation of the application with a different DeviceFamily setting is necessary.
config | SHA2_Config describing the location of the object and hwAttrs. |
params | SHA2_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue. const SHA2_Config SHA2_config[] |
Global SHA2 configuration struct.
Specifies context objects and hardware attributes for every driver instance.
This variable is supposed to be defined in the board file.
const uint_least8_t SHA2_count |
Global SHA2 configuration count.
Specifies the amount of available SHA2 driver instances.
This variable is supposed to be defined in the board file.
const SHA2_Params SHA2_defaultParams |
Default SHA2_Params structure.