Kenji Arai / mbed-os_TYBLE16

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

CryptoCell HMAC APIs
Data Structures | Modules | Typedefs | Functions

CryptoCell HMAC APIs

Data Structures

struct  CRYS_HMACUserContext_t

Modules

 CryptoCell Hmac definitions
 CryptoCell HMAC specific errors

Typedefs

typedef struct
CRYS_HMACUserContext_t 		CRYS_HMACUserContext_t

Functions

CIMPORT_C CRYSError_t CRYS_HMAC_Init (CRYS_HMACUserContext_t *ContextID_ptr, CRYS_HASH_OperationMode_t OperationMode, uint8_t *key_ptr, uint16_t keySize)
 This function initializes the HMAC machine.
CIMPORT_C CRYSError_t CRYS_HMAC_Update (CRYS_HMACUserContext_t *ContextID_ptr, uint8_t *DataIn_ptr, size_t DataInSize)
 This function processes a block of data to be HASHed.
CIMPORT_C CRYSError_t CRYS_HMAC_Finish (CRYS_HMACUserContext_t *ContextID_ptr, CRYS_HASH_Result_t HmacResultBuff)
 This function finalizes the HMAC processing of a data block.
CIMPORT_C CRYSError_t CRYS_HMAC_Free (CRYS_HMACUserContext_t *ContextID_ptr)
 This function is a service function that frees the context if the operation has failed.
CIMPORT_C CRYSError_t CRYS_HMAC (CRYS_HASH_OperationMode_t OperationMode, uint8_t *key_ptr, uint16_t keySize, uint8_t *DataIn_ptr, size_t DataSize, CRYS_HASH_Result_t HmacResultBuff)
 This function processes a single buffer of data, and returns the data buffer's message digest.

Detailed Description

HMAC is a wrapping algorithm that uses a HASH function (one of the supported HASH algorithms, as specified in the HASH chapter) and a key, to generate a unique authentication code over the input data. HMAC calculation can be performed in either of the following two modes of operation:

  • Integrated operation - Processes all data in a single function call. This flow is applicable when all data is available prior to the cryptographic operation.
  • Block operation - Processes a subset of the data buffers, and is called multiple times in a sequence. This flow is applicable when the next data buffer becomes available only during/after processing of the current data buffer.

The following is a typical HMAC Block operation flow:

  1. CRYS_HMAC_Init: This function initializes the HMAC machine on the CRYS level by setting the context pointer that is used on the entire HMAC operation.
  2. CRYS_HMAC_Update: This function runs an HMAC operation on a block of data allocated by the user. This function may be called as many times as required.
  3. CRYS_HMAC_Finish: This function ends the HMAC operation. It returns the digest result and clears the context.

Typedef Documentation

typedef struct CRYS_HMACUserContext_t CRYS_HMACUserContext_t

User's context prototype - the argument type that is passed by the user to the HMAC APIs. The context saves the state of the operation and must be saved by the user till the end of the APIs flow

Function Documentation

CIMPORT_C CRYSError_t CRYS_HMAC ( CRYS_HASH_OperationMode_t  OperationMode,
uint8_t *  key_ptr,
uint16_t  keySize,
uint8_t *  DataIn_ptr,
size_t  DataSize,
CRYS_HASH_Result_t  HmacResultBuff 
)

This function processes a single buffer of data, and returns the data buffer's message digest.

Returns:
CRYS_OK on success.
A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
Parameters:
[in]OperationModeOne of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t.
[in]key_ptrThe pointer to the user's key buffer.
[in]keySizeThe key size in bytes. If the key size is bigger than the HASH block, the key will be hashed. The limitations on the key size are the same as the limitations on MAX hash size.
[in]DataIn_ptrPointer to the input data to be HASHed. The size of the scatter/gather list representing the data buffer is limited to 128 entries, and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB).
[in]DataSizeThe size of the data to be hashed (in bytes).
[out]HmacResultBuffPointer to the word-aligned 64 byte buffer. The actual size of the HMAC result depends on CRYS_HASH_OperationMode_t.
CIMPORT_C CRYSError_t CRYS_HMAC_Finish ( CRYS_HMACUserContext_t *  ContextID_ptr,
CRYS_HASH_Result_t  HmacResultBuff 
)

This function finalizes the HMAC processing of a data block.

It receives a handle to the HMAC context that was previously initialized by CRYS_HMAC_Init, or by CRYS_HMAC_Update. It completes the HASH calculation on the ipad and text, and then executes a new HASH operation with the key XOR opad and the previous HASH operation result.

Returns:
CRYS_OK on success.
A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
Parameters:
[in]ContextID_ptrPointer to the HMAC context buffer allocated by the user, which is used for the HMAC machine operation.
[out]HmacResultBuffPointer to the word-aligned 64 byte buffer. The actual size of the HASH result depends on CRYS_HASH_OperationMode_t.
CIMPORT_C CRYSError_t CRYS_HMAC_Free ( CRYS_HMACUserContext_t *  ContextID_ptr )

This function is a service function that frees the context if the operation has failed.

The function executes the following major steps:

  1. Checks the validity of all of the inputs of the function.
  2. Clears the user's context.
  3. Exits the handler with the OK code.
Returns:
CRYS_OK on success.
a non-zero value from crys_hmac_error.h on failure.
Parameters:
[in]ContextID_ptrPointer to the HMAC context buffer allocated by the user, which is used for the HMAC machine operation.
CIMPORT_C CRYSError_t CRYS_HMAC_Init ( CRYS_HMACUserContext_t *  ContextID_ptr,
CRYS_HASH_OperationMode_t  OperationMode,
uint8_t *  key_ptr,
uint16_t  keySize 
)

This function initializes the HMAC machine.

It allocates and initializes the HMAC Context. It initiates a HASH session and processes a HASH update on the Key XOR ipad, then stores it in the context

Returns:
CRYS_OK on success.
A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
Parameters:
[in]ContextID_ptrPointer to the HMAC context buffer allocated by the user, which is used for the HMAC machine operation.
[in]OperationModeOne of the supported HASH modes, as defined in CRYS_HASH_OperationMode_t.
[in]key_ptrThe pointer to the user's key buffer.
[in]keySizeThe key size in bytes. If the key size is bigger than the HASH block, the key will be hashed. The limitations on the key size are the same as the limitations on MAX hash size.
CIMPORT_C CRYSError_t CRYS_HMAC_Update ( CRYS_HMACUserContext_t *  ContextID_ptr,
uint8_t *  DataIn_ptr,
size_t  DataInSize 
)

This function processes a block of data to be HASHed.

It receives a handle to the HMAC Context, and updates the HASH value with the new data.

Returns:
CRYS_OK on success.
A non-zero value from crys_hmac_error.h or crys_hash_error.h on failure.
Parameters:
[in]ContextID_ptrPointer to the HMAC context buffer allocated by the user that is used for the HMAC machine operation.
[in]DataIn_ptrPointer to the input data to be HASHed. The size of the scatter/gather list representing the data buffer is limited to 128 entries, and the size of each entry is limited to 64KB (fragments larger than 64KB are broken into fragments <= 64KB).
[in]DataInSizeByte size of the input data. Must be > 0. If not a multiple of the HASH block size (64 for SHA-1 and SHA-224/256, 128 for SHA-384/512), no further calls to CRYS_HMAC_Update are allowed in this context, and only CRYS_HMAC_Finish can be called to complete the computation.
Generated on Tue Jul 12 2022 13:55:21 by  doxygen 1.7.2