Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
SHA2.h File Reference

Detailed Description

SHA2 driver header.

============================================================================

Warning
This is a beta API. It may change in future releases.

Overview

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.

It is not currently technologicaly feasible to derive an input from the hash 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 algorithms but a suite of similar algorithms that produce hashes of different lengths. 224, 256, 384, and 512-bit outputs are available.

Usage

Before starting a SHA2 operation

Before starting a SHA2 operation, the application must do the following:

Starting a SHA2 operation

There are two general ways to execute a SHA2 operation. In one call or multiple.

The SHA2_oneStepHash function performs a SHA2 operation in a single call. It will always be the most highly optimized routine with the least overhead and the fastest runtime. However, it requires that the entire input message be available to the function at the start of the call. When trying to operate on data that is too large to fit into available memory, partial processing would be more advisable. The single call operation is required when hashing a message with lenth smaller than or equal to one hash-block length. All devices support single call operations.

After the SHA2 operation completes

After the SHA2 operation completes, the application should either start another operation or close the driver by calling SHA2_close()

SHA2 Driver Configuration

In order to use the SHA2 APIs, the application is required to provide device-specific SHA2 configuration in the Board.c file. The SHA2 driver interface defines a configuration data structure:

typedef struct SHA2_Config_ {
void *object;
void const *hwAttrs;
} SHA2_Config;

The application must declare an array of SHA2_Config elements, named SHA2_config[]. Each element of SHA2_config[] must be populated with pointers to a device specific SHA2 driver implementation's driver object and hardware attributes. The hardware attributes define properties such as the SHA2 peripheral's base address. Each element in SHA2_config[] corresponds to an SHA2 instance and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as SHA20 or SHA21). For example, it is possible to use SHA2_config[0] for SHA21. Multiple drivers and driver instances may all access the same underlying hardware. This is transparent to the application. Mutual exclusion is performed automatically by the drivers as necessary.

Because the SHA2 configuration is very device dependent, you will need to check the doxygen for the device specific SHA2 implementation. There you will find a description of the SHA2 hardware attributes. Please also refer to the Board.c file of any of your examples to see the SHA2 configuration.

SHA2 Parameters

The SHA2_Params structure is passed to the SHA2_open() call. If NULL is passed for the parameters, SHA2_open() uses default parameters. A SHA2_Params structure is initialized with default values by passing it to SHA2_Params_init(). Some of the SHA2 parameters are described below. To see brief descriptions of all the parameters, see SHA2_Params.

Examples

### Single call SHA2 256=bit hash in blocking mode

#include <ti/drivers/SHA2.h>
SHA2_Handle handle;
HA2_OperationOneStepHash operationOneStepHash;
uint8_t message[] = ""; // The message is the empty string
uint8_t digest[SHA2_DIGEST_LENGTH_BYTES_256];
handle = SHA2_open(0, NULL);
if (!handle) {
while(1);
}
SHA2_OperationOneStepHash_init(&operationOneStepHash);
operationOneStepHash.hashSize = SHA2_HASH_SIZE_256;
operationOneStepHash.message = message;
operationOneStepHash.digest = digest;
operationOneStepHash.totalLength = 0;
int_fast16_t testResult = SHA2_oneStepHash(handle, &operationOneStepHash);
if (testResult != SHA2_STATUS_SUCCESS) {
// handle error
while(1);
}
// The resultant digest should be:
// 0xE3, 0xB0, 0xC4, 0x42,
// 0x98, 0xFC, 0x1C, 0x14,
// 0x9A, 0xFB, 0xF4, 0xC8,
// 0x99, 0x6F, 0xB9, 0x24,
// 0x27, 0xAE, 0x41, 0xE4,
// 0x64, 0x9B, 0x93, 0x4C,
// 0xA4, 0x95, 0x99, 0x1B,
// 0x78, 0x52, 0xB8, 0x55,
SHA2_close(handle);

Partial hash with exported intermediate context

#include <ti/drivers/SHA2.h>
SHA2_Handle handle;
HA2_OperationStartHash operationStartHash;
HA2_OperationFinishHash operationFinishHash;
// 112-byte string
uint8_t message[] = "abcdefghbcdefghicdefghijdefghijkefghijklfghijklmgh
ijklmnhijklmnoijklmnopjklmnopqklmnopqrlmnopqrsmnop
qrstnopqrstu";
uint8_t digest[SHA2_DIGEST_LENGTH_BYTES_256];
handle = SHA2_open(0, NULL);
if (!handle) {
while(1);
}
SHA2_OperationStartHash_init(&operationStartHash);
operationStartHash.hashSize = SHA2_HASH_SIZE_256;
operationStartHash.length = SHA2_DIGEST_LENGTH_BYTES_256;
operationStartHash.message = message;
operationStartHash.intermediateDigest = digest;
int_fast16_t testResult = SHA2_startHash(handle, &operationStartHash);
if (testResult != SHA2_STATUS_SUCCESS) {
while(1);
}
SHA2_OperationFinishHash_init(&operationFinishHash);
operationFinishHash.hashSize = SHA2_HASH_SIZE_256;
operationFinishHash.segmentLength = 112 - SHA2_DIGEST_LENGTH_BYTES_256;
operationFinishHash.message = message + SHA2_DIGEST_LENGTH_BYTES_256;
operationFinishHash.intermediateDigest = digest;
operationFinishHash.finalDigest = digest;
operationFinishHash.totalLength = 112;
testResult = SHA2_finishHash(handle, &operationFinishHash);
if (testResult != SHA2_STATUS_SUCCESS) {
while(1);
}
// The resultant digest should be:
// 0xcf, 0x5b, 0x16, 0xa7,
// 0x78, 0xaf, 0x83, 0x80,
// 0x03, 0x6c, 0xe5, 0x9e,
// 0x7b, 0x04, 0x92, 0x37,
// 0x0b, 0x24, 0x9b, 0x11,
// 0xe8, 0xf0, 0x7a, 0x51,
// 0xaf, 0xac, 0x45, 0x03,
// 0x7a, 0xfe, 0xe9, 0xd1
SHA2_close(handle);
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>

Go to the source code of this file.

Data Structures

struct  SHA2_OperationOneStep_
 Struct containing the parameters required to hash a message in one go. More...
 
struct  SHA2_OperationStartHash_
 Struct containing the parameters required to start hashing a message. More...
 
struct  SHA2_OperationProcessHash_
 Struct containing the parameters required to continue hashing a message. More...
 
struct  SHA2_OperationFinishlHash_
 Struct containing the parameters required to process the last blocks of a message and finalize the hash. More...
 
union  SHA2_Operation_
 Union containing pointers to all supported operation structs. More...
 
struct  SHA2_Config_
 SHA2 Global configuration. More...
 
struct  SHA2_Params_
 SHA2 Parameters. More...
 

Macros

#define SHA2_CMD_RESERVED   (32)
 
#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_UNDEFINEDCMD   (-2)
 An error status code returned by SHA2_control() for undefined command codes. More...
 
#define SHA2_STATUS_RESOURCE_UNAVAILABLE   (-3)
 An error status code returned if the hardware or software resource is currently unavailable. More...
 

Typedefs

typedef struct SHA2_Config_ * SHA2_Handle
 A handle that is returned from an SHA2_open() call. More...
 
typedef enum SHA2_ReturnBehavior_ SHA2_ReturnBehavior
 The way in which SHA2 function calls return after performing an operation. More...
 
typedef enum SHA2_HashSize_ SHA2_HashSize
 Enum for the hash digest sizes supported by the driver. More...
 
typedef enum SHA2_DigestLengthBytes_ SHA2_DigestLengthBytes
 Enum for the hash digest lengths in bytes supported by the driver. More...
 
typedef struct SHA2_OperationOneStep_ SHA2_OperationOneStepHash
 Struct containing the parameters required to hash a message in one go. More...
 
typedef struct SHA2_OperationStartHash_ SHA2_OperationStartHash
 Struct containing the parameters required to start hashing a message. More...
 
typedef struct SHA2_OperationProcessHash_ SHA2_OperationProcessHash
 Struct containing the parameters required to continue hashing a message. More...
 
typedef struct SHA2_OperationFinishlHash_ SHA2_OperationFinishHash
 Struct containing the parameters required to process the last blocks of a message and finalize the hash. More...
 
typedef union SHA2_Operation_ SHA2_Operation
 Union containing pointers to all supported operation structs. More...
 
typedef enum SHA2_OperationType_ SHA2_OperationType
 Enum for the operation types supported by the driver. More...
 
typedef struct SHA2_Config_ SHA2_Config
 SHA2 Global configuration. More...
 
typedef void(* SHA2_CallbackFxn) (SHA2_Handle handle, int_fast16_t returnStatus, SHA2_Operation operation, SHA2_OperationType operationType)
 The definition of a callback function used by the SHA2 driver when used in SHA2_RETURN_BEHAVIOR_CALLBACK. More...
 
typedef struct SHA2_Params_ SHA2_Params
 SHA2 Parameters. 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_HashSize_ { SHA2_HASH_SIZE_224 = 0, SHA2_HASH_SIZE_256 = 1, SHA2_HASH_SIZE_384 = 2, SHA2_HASH_SIZE_512 = 3 }
 Enum for the hash digest sizes 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_OperationType_ { SHA2_OPERATION_TYPE_START_HASH = 1, SHA2_OPERATION_TYPE_PROCESS_HASH = 2, SHA2_OPERATION_TYPE_FINISH_HASH = 3, SHA2_OPERATION_TYPE_ONE_STEP_HASH = 4 }
 Enum for the operation types supported by the driver. More...
 

Functions

void SHA2_init (void)
 This function initializes the SHA2 module. More...
 
void SHA2_Params_init (SHA2_Params *params)
 Function to initialize the SHA2_Params struct to its defaults. More...
 
SHA2_Handle SHA2_open (uint_least8_t index, SHA2_Params *params)
 This function opens a given SHA2 peripheral. More...
 
void SHA2_close (SHA2_Handle handle)
 Function to close a SHA2 peripheral specified by the SHA2 handle. More...
 
int_fast16_t SHA2_control (SHA2_Handle handle, uint32_t cmd, void *args)
 Function performs implementation specific features on a given SHA2_Handle. More...
 
void SHA2_OperationStartHash_init (SHA2_OperationStartHash *operation)
 Function to initialize a SHA2_OperationStartHash struct to its defaults. More...
 
void SHA2_OperationProcessHash_init (SHA2_OperationProcessHash *operation)
 Function to initialize a SHA2_OperationProcessHash struct to its defaults. More...
 
void SHA2_OperationFinishHash_init (SHA2_OperationFinishHash *operation)
 Function to initialize a SHA2_OperationFinishHash struct to its defaults. More...
 
void SHA2_OperationOneStepHash_init (SHA2_OperationOneStepHash *operation)
 Function to initialize a SHA2_OperationOneStepHash struct to its defaults. More...
 
int_fast16_t SHA2_startHash (SHA2_Handle handle, SHA2_OperationStartHash *operation)
 Sets up a SHA2 hash. More...
 
int_fast16_t SHA2_processHash (SHA2_Handle handle, SHA2_OperationProcessHash *operation)
 Performs the SHA2