sopc_hash_based_crypto.h File Reference

Defines a cryptographic API to performing hash mechanisms. This module is not required by the OPC UA protocol. It hashes a secret and may be used to authenticate users. More...

#include "sopc_builtintypes.h"
#include "sopc_enums.h"
#include "sopc_mem_alloc.h"
#include "sopc_secret_buffer.h"

Go to the source code of this file.

Typedefs
typedef enum SOPC_HashBasedCrypto_Algo	SOPC_HashBasedCrypto_Algo
	Defines the supported algorithms for user authentication.
typedef struct SOPC_HashBasedCrypto_Config	SOPC_HashBasedCrypto_Config
	cryptographic structure to configure the algorithm used.

Enumerations
enum	SOPC_HashBasedCrypto_Algo { SOPC_HashBasedCrypto_PBKDF2_HMAC_SHA256 }
	Defines the supported algorithms for user authentication. More...

Functions
SOPC_ReturnStatus	SOPC_HashBasedCrypto_Config_Create (SOPC_HashBasedCrypto_Config **cfg)
	Create the internal configuration structure.
void	SOPC_HashBasedCrypto_Config_Free (SOPC_HashBasedCrypto_Config *cfg)
	Free the internal configuration.
SOPC_ReturnStatus	SOPC_HashBasedCrypto_Config_PBKDF2 (SOPC_HashBasedCrypto_Config *config, const SOPC_ByteString *pSalt, size_t iteration_count, size_t lenOutput)
	Fills the configuration structure for SOPC_HashBasedCrypto_PBKDF2_HMAC_SHA256 algorithm.
SOPC_ReturnStatus	SOPC_HashBasedCrypto_Run (const SOPC_HashBasedCrypto_Config *config, const SOPC_ByteString *pSecret, SOPC_ByteString **ppOutput)
	Function that allows to execute a hashing mechanism.

Detailed Description

Defines a cryptographic API to performing hash mechanisms. This module is not required by the OPC UA protocol. It hashes a secret and may be used to authenticate users.

Supported algorithms:

• PBKDF2 with HMAC-SHA-256 [RFC8018]

Typedef Documentation

SOPC_HashBasedCrypto_Algo

typedef enum SOPC_HashBasedCrypto_Algo SOPC_HashBasedCrypto_Algo

Defines the supported algorithms for user authentication.

SOPC_HashBasedCrypto_Config

typedef struct SOPC_HashBasedCrypto_Config SOPC_HashBasedCrypto_Config

cryptographic structure to configure the algorithm used.

Enumeration Type Documentation

SOPC_HashBasedCrypto_Algo

enum SOPC_HashBasedCrypto_Algo

Defines the supported algorithms for user authentication.

Enumerator
SOPC_HashBasedCrypto_PBKDF2_HMAC_SHA256	PBKDF2 with HMAC-SHA-256 (Password-Based Key Derivation Function)

Function Documentation

SOPC_HashBasedCrypto_Config_Create()

SOPC_ReturnStatus SOPC_HashBasedCrypto_Config_Create

(

SOPC_HashBasedCrypto_Config **

cfg

)

Create the internal configuration structure.

Parameters

[out]

cfg

A valid pointer to the newly created structure. You should free it with SOPC_HashBasedCrypto_Config_Free()

Returns

SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when cfg is NULL ond SOPC_STATUS_OUT_OF_MEMORY when memory allocation failed.

SOPC_HashBasedCrypto_Config_Free()

void SOPC_HashBasedCrypto_Config_Free

(

SOPC_HashBasedCrypto_Config *

cfg

)

Free the internal configuration.

Parameters

cfg	A valid pointer to the configuration to freed.

SOPC_HashBasedCrypto_Config_PBKDF2()

SOPC_ReturnStatus SOPC_HashBasedCrypto_Config_PBKDF2	(	SOPC_HashBasedCrypto_Config *	config,
		const SOPC_ByteString *	pSalt,
		size_t	iteration_count,
		size_t	lenOutput )

Fills the configuration structure for SOPC_HashBasedCrypto_PBKDF2_HMAC_SHA256 algorithm.

Parameters

config	A valid pointer to the configuration structure.
pSalt	A valid pointer to a ByteString which contains the salt.
iteration_count	Desired iteration count (as large as possible).
lenOutput	Length of output desired.

Note

Function specific to SOPC_HashBasedCrypto_PBKDF2_HMAC_SHA256.

Returns

SOPC_STATUS_OK when successful or SOPC_STATUS_INVALID_PARAMETERS are invalid

SOPC_HashBasedCrypto_Run()

SOPC_ReturnStatus SOPC_HashBasedCrypto_Run	(	const SOPC_HashBasedCrypto_Config *	config,
		const SOPC_ByteString *	pSecret,
		SOPC_ByteString **	ppOutput )

Function that allows to execute a hashing mechanism.

Parameters

	config	A valid pointer to the configuration structure.
	pSecret	A valid pointer to a ByteString which contains the data to hash.
[out]	ppOutput	A valid pointer to the newly created ByteString which will contain the generated hash. You should free it.

Note

When config is configured with SOPC_HashBasedCrypto_PBKDF2_HMAC_SHA256 then length of pSecret should not exceed 32 bytes because a secret longer than digest size does not protect more, because, HMAC-SHA256 is considered to have 256 bits maximum input entropy.

Content of the ppOutput is unspecified when return value is not SOPC_STATUS_OK.

config is checked beforehand by this function.

Returns

SOPC_STATUS_OK when successful otherwise SOPC_STATUS_INVALID_PARAMETERS, SOPC_STATUS_NOK or SOPC_STATUS_OUT_OF_MEMORY.