ANSIX936KDF driver header.
The ANSI X9.63 Key Derivation Function (KDF) driver utilizes the SHA-256 hash function to derive a key from a shared secret value and optional shared info. See ANSI X9.63-2011 or SEC-1 v2.0 standard for more information.
Before starting a ANSIX936KDF operation, the application must do the following:
The ANSIX936KDF_deriveKey() function performs a key derivation operation in a single call.
After a ANSIX936KDF operation completes, the application may either start another operation or close the driver by calling ANSIX936KDF_close().
Go to the source code of this file.
Data Structures | |
struct | ANSIX936KDF_Config |
ANSIX936KDF Global configuration. More... | |
struct | ANSIX936KDF_Params |
ANSIX936KDF Parameters. More... | |
Macros | |
#define | ANSIX936KDF_STATUS_RESERVED ((int_fast16_t)-32) |
#define | ANSIX936KDF_STATUS_SUCCESS ((int_fast16_t)0) |
Successful status code. More... | |
#define | ANSIX936KDF_STATUS_ERROR ((int_fast16_t)-1) |
Generic error status code. More... | |
#define | ANSIX936KDF_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
Typedefs | |
typedef ANSIX936KDF_Config * | ANSIX936KDF_Handle |
A handle that is returned from an ANSIX936KDF_open() call. More... | |
Enumerations | |
enum | ANSIX936KDF_ReturnBehavior { ANSIX936KDF_RETURN_BEHAVIOR_BLOCKING = SHA2_RETURN_BEHAVIOR_BLOCKING, ANSIX936KDF_RETURN_BEHAVIOR_POLLING = SHA2_RETURN_BEHAVIOR_POLLING } |
The way in which ANSIX936KDF function calls return after performing an operation. More... | |
Functions | |
void | ANSIX936KDF_init (void) |
Initializes the ANSIX936KDF driver module. More... | |
void | ANSIX936KDF_Params_init (ANSIX936KDF_Params *params) |
Initializes params with default values. More... | |
ANSIX936KDF_Handle | ANSIX936KDF_open (uint_least8_t index, const ANSIX936KDF_Params *params) |
Initializes a ANSIX936KDF driver instance and returns a handle. More... | |
void | ANSIX936KDF_close (ANSIX936KDF_Handle handle) |
Closes a ANSIX936KDF peripheral specified by handle . More... | |
int_fast16_t | ANSIX936KDF_deriveKey (ANSIX936KDF_Handle handle, const void *input, size_t inputLen, const void *sharedInfo, size_t sharedInfoLen, void *output, size_t outputLen) |
Derives a key with the SHA-256 hash function. More... | |
ANSIX936KDF_Handle | ANSIX936KDF_construct (ANSIX936KDF_Config *config, const ANSIX936KDF_Params *params) |
Constructs a new ANSIX936KDF object. More... | |
Variables | |
const ANSIX936KDF_Config | ANSIX936KDF_config [] |
Global ANSIX936KDF configuration struct. More... | |
const uint_least8_t | ANSIX936KDF_count |
Global ANSIX936KDF configuration count. More... | |
const ANSIX936KDF_Params | ANSIX936KDF_defaultParams |
Default ANSIX936KDF_Params structure. More... | |
#define ANSIX936KDF_STATUS_RESERVED ((int_fast16_t)-32) |
Common ANSIX936KDF status code reservation offset. ANSIX936KDF driver implementations should offset status codes with ANSIX936KDF_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define ANSIX936KDF_STATUS_SUCCESS ((int_fast16_t)0) |
Successful status code.
Functions return ANSIX936KDF_STATUS_SUCCESS if the function was executed successfully.
#define ANSIX936KDF_STATUS_ERROR ((int_fast16_t)-1) |
Generic error status code.
Functions return ANSIX936KDF_STATUS_ERROR if the function was not executed successfully and no more specific error is applicable.
#define ANSIX936KDF_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2) |
An error status code returned if the hardware or software resource is currently unavailable.
ANSIX936KDF 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.
typedef ANSIX936KDF_Config* ANSIX936KDF_Handle |
A handle that is returned from an ANSIX936KDF_open() call.
The way in which ANSIX936KDF function calls return after performing an operation.
Not all ANSIX936KDF operations exhibit the specified return behavior. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specified 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.
ANSIX936KDF functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
ANSIX936KDF_RETURN_BEHAVIOR_BLOCKING | X | ||
ANSIX936KDF_RETURN_BEHAVIOR_POLLING | X | X | X |
void ANSIX936KDF_init | ( | void | ) |
Initializes the ANSIX936KDF driver module.
void ANSIX936KDF_Params_init | ( | ANSIX936KDF_Params * | params | ) |
Initializes params
with default values.
params | A pointer to ANSIX936KDF_Params structure for initialization |
Default values:
returnBehavior = ANSIX936KDF_RETURN_BEHAVIOR_BLOCKING
timeout = SemaphoreP_WAIT_FOREVER
ANSIX936KDF_Handle ANSIX936KDF_open | ( | uint_least8_t | index, |
const ANSIX936KDF_Params * | params | ||
) |
Initializes a ANSIX936KDF driver instance and returns a handle.
index | Logical peripheral number for the ANSIX936KDF indexed into the ANSIX936KDF_config table |
params | Pointer to a parameter block, if NULL it will use default values. |
void ANSIX936KDF_close | ( | ANSIX936KDF_Handle | handle | ) |
Closes a ANSIX936KDF peripheral specified by handle
.
handle | A ANSIX936KDF_Handle returned from ANSIX936KDF_open() |
int_fast16_t ANSIX936KDF_deriveKey | ( | ANSIX936KDF_Handle | handle, |
const void * | input, | ||
size_t | inputLen, | ||
const void * | sharedInfo, | ||
size_t | sharedInfoLen, | ||
void * | output, | ||
size_t | outputLen | ||
) |
Derives a key with the SHA-256 hash function.
Uses the SHA-256 hash function to derives a key from a shared secret value and optional shared information.
handle | A ANSIX936KDF_Handle returned from ANSIX936KDF_open() |
input | A pointer to the input (i.e. shared secret value) |
inputLen | The length of input in bytes. |
sharedInfo | A pointer to the shared info. May be NULL if there is no shared info. |
sharedInfoLen | The length of the sharedInfo in bytes. Set to zero if sharedInfo is NULL. |
output | A pointer to the location to write the output (i.e. derived key). |
outputLen | Output length in bytes. |
ANSIX936KDF_STATUS_SUCCESS | The operation succeeded. |
ANSIX936KDF_STATUS_ERROR | The operation failed. |
ANSIX936KDF_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
ANSIX936KDF_Handle ANSIX936KDF_construct | ( | ANSIX936KDF_Config * | config, |
const ANSIX936KDF_Params * | params | ||
) |
Constructs a new ANSIX936KDF object.
Unlike ANSIX936KDF_open(), ANSIX936KDF_construct() does not require the hwAttrs and object to be allocated in a ANSIX936KDF_Config array that is indexed into. Instead, the ANSIX936KDF_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 | ANSIX936KDF_Config describing the location of the object and hwAttrs. |
params | ANSIX936KDF_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue. const ANSIX936KDF_Config ANSIX936KDF_config[] |
Global ANSIX936KDF 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 ANSIX936KDF_count |
Global ANSIX936KDF configuration count.
Specifies the number of available ANSIX936KDF driver instances.
This variable is supposed to be defined in the board file.
const ANSIX936KDF_Params ANSIX936KDF_defaultParams |
Default ANSIX936KDF_Params structure.