caffeine-hal 0.6.6
A Header-Defined Interface c library, it provides the hal layer for the Caffeine framework
Loading...
Searching...
No Matches
Data Structures | Typedefs | Enumerations | Functions
cfn_hal_crypto.h File Reference

Hardware Crypto HAL API. More...

#include "cfn_hal.h"
#include "cfn_hal_base.h"
#include "cfn_hal_types.h"

Go to the source code of this file.

Data Structures

struct  cfn_hal_crypto_config_t
 Crypto configuration structure. More...
 
struct  cfn_hal_crypto_phy_t
 Crypto hardware physical mapping. More...
 
struct  cfn_hal_crypto_api_s
 Crypto Virtual Method Table (VMT). More...
 

Typedefs

typedef struct cfn_hal_crypto_s cfn_hal_crypto_t
 
typedef struct cfn_hal_crypto_api_s cfn_hal_crypto_api_t
 
typedef void(* cfn_hal_crypto_callback_t) (cfn_hal_crypto_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)
 Crypto callback signature.
 

Enumerations

enum  cfn_hal_crypto_event_t { CFN_HAL_CRYPTO_EVENT_NONE = 0 , CFN_HAL_CRYPTO_EVENT_OP_COMPLETE = CFN_HAL_BIT(0) }
 Crypto nominal event flags. More...
 
enum  cfn_hal_crypto_error_t { CFN_HAL_CRYPTO_ERROR_NONE = 0 , CFN_HAL_CRYPTO_ERROR_AUTH = CFN_HAL_BIT(0) , CFN_HAL_CRYPTO_ERROR_GENERAL = CFN_HAL_BIT(1) }
 Crypto exception error flags. More...
 
enum  cfn_hal_crypto_algo_t {
  CFN_HAL_CRYPTO_ALGO_AES_ECB , CFN_HAL_CRYPTO_ALGO_AES_CBC , CFN_HAL_CRYPTO_ALGO_AES_GCM , CFN_HAL_CRYPTO_ALGO_SHA256 ,
  CFN_HAL_CRYPTO_ALGO_SHA512 , CFN_HAL_CRYPTO_ALGO_MAX
}
 Supported cryptographic algorithms. More...
 

Functions

 CFN_HAL_VMT_CHECK (struct cfn_hal_crypto_api_s)
 
 CFN_HAL_CREATE_DRIVER_TYPE (crypto, cfn_hal_crypto_config_t, cfn_hal_crypto_api_t, cfn_hal_crypto_phy_t, cfn_hal_crypto_callback_t)
 
CFN_HAL_INLINE void cfn_hal_crypto_populate (cfn_hal_crypto_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_crypto_api_t *api, const cfn_hal_crypto_phy_t *phy, const cfn_hal_crypto_config_t *config, cfn_hal_crypto_callback_t callback, void *user_arg)
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_config_validate (const cfn_hal_crypto_t *driver, const cfn_hal_crypto_config_t *config)
 Validates the Crypto configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_init (cfn_hal_crypto_t *driver)
 Initializes the Crypto driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_deinit (cfn_hal_crypto_t *driver)
 Deinitializes the Crypto driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_config_set (cfn_hal_crypto_t *driver, const cfn_hal_crypto_config_t *config)
 Sets the Crypto configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_config_get (cfn_hal_crypto_t *driver, cfn_hal_crypto_config_t *config)
 Gets the current Crypto configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_callback_register (cfn_hal_crypto_t *driver, const cfn_hal_crypto_callback_t callback, void *user_arg)
 Registers a callback for Crypto events and errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_power_state_set (cfn_hal_crypto_t *driver, cfn_hal_power_state_t state)
 Sets the Crypto power state.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_event_enable (cfn_hal_crypto_t *driver, uint32_t event_mask)
 Enables one or more Crypto nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_event_disable (cfn_hal_crypto_t *driver, uint32_t event_mask)
 Disables one or more Crypto nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_event_get (cfn_hal_crypto_t *driver, uint32_t *event_mask)
 Retrieves the current Crypto nominal event status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_error_enable (cfn_hal_crypto_t *driver, uint32_t error_mask)
 Enables one or more Crypto exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_error_disable (cfn_hal_crypto_t *driver, uint32_t error_mask)
 Disables one or more Crypto exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_error_get (cfn_hal_crypto_t *driver, uint32_t *error_mask)
 Retrieves the current Crypto exception error status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_encrypt (cfn_hal_crypto_t *driver, const uint8_t *in, uint8_t *out, size_t size, uint32_t timeout)
 Encrypts a block of data.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_decrypt (cfn_hal_crypto_t *driver, const uint8_t *in, uint8_t *out, size_t size, uint32_t timeout)
 Decrypts a block of data.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_hash_update (cfn_hal_crypto_t *driver, const uint8_t *data, size_t size)
 Feeds data into the hashing engine.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_hash_finish (cfn_hal_crypto_t *driver, uint8_t *hash, uint32_t timeout)
 Finalizes the hash calculation and retrieves the digest.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_generate_random (cfn_hal_crypto_t *driver, uint8_t *buffer, size_t size)
 Generates cryptographically secure random numbers.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_set_key (cfn_hal_crypto_t *driver, const uint8_t *key, size_t key_size)
 Sets the cryptographic key for symmetric algorithms.
 
cfn_hal_error_code_t cfn_hal_crypto_construct (cfn_hal_crypto_t *driver, const cfn_hal_crypto_config_t *config, const cfn_hal_crypto_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_crypto_callback_t callback, void *user_arg)
 
cfn_hal_error_code_t cfn_hal_crypto_destruct (cfn_hal_crypto_t *driver)
 

Detailed Description

Hardware Crypto HAL API.

Copyright (c) 2026 Hisham Moussa Daou https://www.whileone.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Typedef Documentation

◆ cfn_hal_crypto_api_t

◆ cfn_hal_crypto_callback_t

typedef void(* cfn_hal_crypto_callback_t) (cfn_hal_crypto_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)

Crypto callback signature.

Parameters
driverPointer to the Crypto driver instance.
event_maskMask of triggered nominal events.
error_maskMask of triggered exception errors.
user_argUser-defined argument passed during registration.

◆ cfn_hal_crypto_t

typedef struct cfn_hal_crypto_s cfn_hal_crypto_t

Enumeration Type Documentation

◆ cfn_hal_crypto_algo_t

Supported cryptographic algorithms.

Enumerator
CFN_HAL_CRYPTO_ALGO_AES_ECB 
CFN_HAL_CRYPTO_ALGO_AES_CBC 
CFN_HAL_CRYPTO_ALGO_AES_GCM 
CFN_HAL_CRYPTO_ALGO_SHA256 
CFN_HAL_CRYPTO_ALGO_SHA512 
CFN_HAL_CRYPTO_ALGO_MAX 

◆ cfn_hal_crypto_error_t

Crypto exception error flags.

Enumerator
CFN_HAL_CRYPTO_ERROR_NONE 
CFN_HAL_CRYPTO_ERROR_AUTH 

Authentication/Tag mismatch error

CFN_HAL_CRYPTO_ERROR_GENERAL 

General hardware error

◆ cfn_hal_crypto_event_t

Crypto nominal event flags.

Enumerator
CFN_HAL_CRYPTO_EVENT_NONE 
CFN_HAL_CRYPTO_EVENT_OP_COMPLETE 

Cryptographic operation complete

Function Documentation

◆ CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE ( crypto  ,
cfn_hal_crypto_config_t  ,
cfn_hal_crypto_api_t  ,
cfn_hal_crypto_phy_t  ,
cfn_hal_crypto_callback_t   
)

◆ cfn_hal_crypto_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_callback_register ( cfn_hal_crypto_t driver,
const cfn_hal_crypto_callback_t  callback,
void *  user_arg 
)

Registers a callback for Crypto events and errors.

Parameters
driverPointer to the Crypto driver instance.
callbackThe callback function to register.
user_argUser-defined argument passed to the callback.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_config_get ( cfn_hal_crypto_t driver,
cfn_hal_crypto_config_t config 
)

Gets the current Crypto configuration.

Parameters
driverPointer to the Crypto driver instance.
config[out] Pointer to store the configuration.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_config_set ( cfn_hal_crypto_t driver,
const cfn_hal_crypto_config_t config 
)

Sets the Crypto configuration.

Parameters
driverPointer to the Crypto driver instance.
configPointer to the configuration structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_config_validate ( const cfn_hal_crypto_t driver,
const cfn_hal_crypto_config_t config 
)

Validates the Crypto configuration.

Parameters
driverPointer to the CRYPTO driver instance.
configPointer to the configuration structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_construct()

cfn_hal_error_code_t cfn_hal_crypto_construct ( cfn_hal_crypto_t driver,
const cfn_hal_crypto_config_t config,
const cfn_hal_crypto_phy_t phy,
struct cfn_hal_clock_s *  clock,
void *  dependency,
cfn_hal_crypto_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_crypto_decrypt()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_decrypt ( cfn_hal_crypto_t driver,
const uint8_t *  in,
uint8_t *  out,
size_t  size,
uint32_t  timeout 
)

Decrypts a block of data.

Parameters
driverPointer to the Crypto driver instance.
inPointer to the ciphertext data.
outPointer to the buffer where plaintext will be stored.
sizeNumber of bytes to decrypt.
timeoutMaximum time to wait for completion in milliseconds.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_deinit ( cfn_hal_crypto_t driver)

Deinitializes the Crypto driver.

Parameters
driverPointer to the Crypto driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_destruct()

cfn_hal_error_code_t cfn_hal_crypto_destruct ( cfn_hal_crypto_t driver)

◆ cfn_hal_crypto_encrypt()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_encrypt ( cfn_hal_crypto_t driver,
const uint8_t *  in,
uint8_t *  out,
size_t  size,
uint32_t  timeout 
)

Encrypts a block of data.

Parameters
driverPointer to the Crypto driver instance.
inPointer to the plaintext data.
outPointer to the buffer where ciphertext will be stored.
sizeNumber of bytes to encrypt.
timeoutMaximum time to wait for completion in milliseconds.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_error_disable ( cfn_hal_crypto_t driver,
uint32_t  error_mask 
)

Disables one or more Crypto exception errors.

Parameters
driverPointer to the Crypto driver instance.
error_maskMask of errors to disable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_error_enable ( cfn_hal_crypto_t driver,
uint32_t  error_mask 
)

Enables one or more Crypto exception errors.

Parameters
driverPointer to the Crypto driver instance.
error_maskMask of errors to enable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_error_get ( cfn_hal_crypto_t driver,
uint32_t *  error_mask 
)

Retrieves the current Crypto exception error status.

Parameters
driverPointer to the Crypto driver instance.
error_mask[out] Pointer to store the error mask.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_event_disable ( cfn_hal_crypto_t driver,
uint32_t  event_mask 
)

Disables one or more Crypto nominal events.

Parameters
driverPointer to the Crypto driver instance.
event_maskMask of events to disable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_event_enable ( cfn_hal_crypto_t driver,
uint32_t  event_mask 
)

Enables one or more Crypto nominal events.

Parameters
driverPointer to the Crypto driver instance.
event_maskMask of events to enable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_event_get ( cfn_hal_crypto_t driver,
uint32_t *  event_mask 
)

Retrieves the current Crypto nominal event status.

Parameters
driverPointer to the Crypto driver instance.
event_mask[out] Pointer to store the event mask.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_generate_random()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_generate_random ( cfn_hal_crypto_t driver,
uint8_t *  buffer,
size_t  size 
)

Generates cryptographically secure random numbers.

Parameters
driverPointer to the Crypto driver instance.
buffer[out] Pointer to the buffer to be filled with random data.
sizeNumber of bytes to generate.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_hash_finish()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_hash_finish ( cfn_hal_crypto_t driver,
uint8_t *  hash,
uint32_t  timeout 
)

Finalizes the hash calculation and retrieves the digest.

Parameters
driverPointer to the Crypto driver instance.
hash[out] Pointer to the buffer where the digest will be stored.
timeoutMaximum time to wait for completion in milliseconds.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_hash_update()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_hash_update ( cfn_hal_crypto_t driver,
const uint8_t *  data,
size_t  size 
)

Feeds data into the hashing engine.

Parameters
driverPointer to the Crypto driver instance.
dataPointer to the data to be hashed.
sizeNumber of bytes to process.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_init ( cfn_hal_crypto_t driver)

Initializes the Crypto driver.

Parameters
driverPointer to the Crypto driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_populate()

CFN_HAL_INLINE void cfn_hal_crypto_populate ( cfn_hal_crypto_t driver,
uint32_t  peripheral_id,
struct cfn_hal_clock_s *  clock,
void *  dependency,
const cfn_hal_crypto_api_t api,
const cfn_hal_crypto_phy_t phy,
const cfn_hal_crypto_config_t config,
cfn_hal_crypto_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_crypto_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_power_state_set ( cfn_hal_crypto_t driver,
cfn_hal_power_state_t  state 
)

Sets the Crypto power state.

Parameters
driverPointer to the Crypto driver instance.
stateTarget power state.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_crypto_set_key()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_crypto_set_key ( cfn_hal_crypto_t driver,
const uint8_t *  key,
size_t  key_size 
)

Sets the cryptographic key for symmetric algorithms.

Parameters
driverPointer to the Crypto driver instance.
keyPointer to the key data.
key_sizeSize of the key in bytes.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ CFN_HAL_VMT_CHECK()

CFN_HAL_VMT_CHECK ( struct cfn_hal_crypto_api_s  )