lcx_hmac.h

Back to the files list

HMAC (Keyed-Hash Message Authentication Code) More...

Data Structures
struct	cx_hmac_t
	HMAC context, abstract type. More...
struct	cx_hmac_ripemd160_t
	HMAC context, concrete type for RIPEMD160. More...
struct	cx_hmac_sha256_t
	HMAC context, concrete type for SHA-224/SHA-256. More...
struct	cx_hmac_sha512_t
	HMAC context, concrete type for SHA-384/SHA-512. More...

Functions
cx_err_t	cx_hmac_ripemd160_init_no_throw (cx_hmac_ripemd160_t *hmac, const uint8_t *key, size_t key_len)
	Initializes a HMAC-RIPEMD160 context. More...
static int	cx_hmac_ripemd160_init (cx_hmac_ripemd160_t *hmac, const unsigned char *key, unsigned int key_len)
	Initializes a HMAC-RIPEMD160 context. More...
cx_err_t	cx_hmac_sha224_init (cx_hmac_sha256_t *hmac, const uint8_t *key, unsigned int key_len)
	Initializes a HMAC-SHA224 context. More...
cx_err_t	cx_hmac_sha256_init_no_throw (cx_hmac_sha256_t *hmac, const uint8_t *key, size_t key_len)
	Initializes a HMAC-SHA256 context. More...
static int	cx_hmac_sha256_init (cx_hmac_sha256_t *hmac, const unsigned char *key, unsigned int key_len)
	Initializes a HMAC-SHA256 context. More...
size_t	cx_hmac_sha256 (const uint8_t *key, size_t key_len, const uint8_t *in, size_t len, uint8_t *mac, size_t mac_len)
	Computes a HMAC value using SHA256. More...
cx_err_t	cx_hmac_sha384_init (cx_hmac_sha512_t *hmac, const uint8_t *key, unsigned int key_len)
	Initializes a HMAC-SHA384 context. More...
cx_err_t	cx_hmac_sha512_init_no_throw (cx_hmac_sha512_t *hmac, const uint8_t *key, size_t key_len)
	Initializes a HMAC-SHA512 context. More...
static int	cx_hmac_sha512_init (cx_hmac_sha512_t *hmac, const unsigned char *key, unsigned int key_len)
	Initializes a HMAC-SHA512 context. More...
size_t	cx_hmac_sha512 (const uint8_t *key, size_t key_len, const uint8_t *in, size_t len, uint8_t *mac, size_t mac_len)
	Computes a HMAC value using SHA512. More...
cx_err_t	cx_hmac_no_throw (cx_hmac_t *hmac, uint32_t mode, const uint8_t *in, size_t len, uint8_t *mac, size_t mac_len)
	Computes a HMAC value according to the specified hash function. More...
static int	cx_hmac (cx_hmac_t *hmac, int mode, const unsigned char *in, unsigned int len, unsigned char *mac, unsigned int mac_len)
	Computes a HMAC value according to the specified hash function. More...
cx_err_t	cx_hmac_init (cx_hmac_t *hmac, cx_md_t hash_id, const uint8_t *key, size_t key_len)
	Initializes a HMAC context. More...
cx_err_t	cx_hmac_update (cx_hmac_t *hmac, const uint8_t *in, size_t in_len)
	Adds more data to compute the HMAC. More...
cx_err_t	cx_hmac_final (cx_hmac_t *ctx, uint8_t *out, size_t *out_len)
	Finalizes the HMAC algorithm. More...

Detailed Description

HMAC (Keyed-Hash Message Authentication Code)

A HMAC is a specific type of message authentication code which involves a hash function and a secret key. It enables the verification of the integrity and the authenticity of a message.

Function Documentation

cx_hmac()

static int cx_hmac ( cx_hmac_t *  hmac, int  mode, const unsigned char *  in, unsigned int  len, unsigned char *  mac, unsigned int  mac_len  )

Computes a HMAC value according to the specified hash function.

This function throws an exception if the computation doesn't succeed.

Warning

It is recommended to use cx_hmac_no_throw rather than this function.

Parameters

[in]	hmac	Pointer to the HMAC context. The context shall be initialized with one of the initialization functions. The context shall be in RAM. The function shall be called with the cast (cx_hmac_t *).
[in]	mode	Crypto mode flags. Supported flags: CX_LAST CX_NO_REINIT If CX_LAST is set and CX_NO_REINIT is not set, the context is reinitialized.
[in]	in	Input data to add to the context.
[in]	len	Length of the input data.
[out]	mac	Pointer to the computed HMAC or NULL pointer (if CX_LAST is not set).
[in]	mac_len	Length of the output buffer if not NULL, 0 otherwise. The buffer size must be larger than the length of the HMAC value.

Returns

Identifier of the hash function.

Exceptions

CX_INVALID_PARAMETER

cx_hmac_final()

cx_err_t cx_hmac_final	(	cx_hmac_t *	ctx,
		uint8_t *	out,
		size_t *	out_len
)

Finalizes the HMAC algorithm.

A call to this function is equivalent to cx_hmac_no_throw(hash, CX_LAST, NULL, 0, out, out_len).

Parameters

[in]	ctx	Pointer to the HMAC context.
[out]	out	Computed HMAC value is CX_LAST is set.
[in]	out_len	Length of the output (the most significant bytes).

Returns

Error code:

• CX_OK on success

cx_hmac_init()

cx_err_t cx_hmac_init	(	cx_hmac_t *	hmac,
		cx_md_t	hash_id,
		const uint8_t *	key,
		size_t	key_len
)

Initializes a HMAC context.

Parameters

[out]	hmac	Pointer to the context. The context shall be in RAM.
[in]	hash_id	The message digest algorithm identifier.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 128 bytes.

Returns

Error code:

• CX_OK on success
• CX_INVALID_PARAMETER

cx_hmac_no_throw()

cx_err_t cx_hmac_no_throw	(	cx_hmac_t *	hmac,
		uint32_t	mode,
		const uint8_t *	in,
		size_t	len,
		uint8_t *	mac,
		size_t	mac_len
)

Computes a HMAC value according to the specified hash function.

Parameters

[in]	hmac	Pointer to the HMAC context. The context shall be initialized with one of the initialization functions. The context shall be in RAM. The function shall be called with the cast (cx_hmac_t *).
[in]	mode	Crypto mode flags. Supported flags: CX_LAST CX_NO_REINIT If CX_LAST is set and CX_NO_REINIT is not set, the context is reinitialized.
[in]	in	Input data to add to the context.
[in]	len	Length of the input data.
[out]	mac	Pointer to the computed HMAC or NULL pointer (if CX_LAST is not set).
[in]	mac_len	Length of the output buffer if not NULL, 0 otherwise. The buffer size must be larger than the length of the HMAC value.

Returns

Error code:

• CX_OK on success
• CX_INVALID_PARAMETER

cx_hmac_ripemd160_init()

static int cx_hmac_ripemd160_init ( cx_hmac_ripemd160_t *  hmac, const unsigned char *  key, unsigned int  key_len  )

Initializes a HMAC-RIPEMD160 context.

This function throws an exception if the initialization fails.

Warning

It is recommended to use cx_hmac_ripemd160_init_no_throw rather than this function.

Parameters

[out]	hmac	Pointer to the HMAC context. The context shall be in RAM.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 64 bytes.

Returns

RIPEMD160 identifier.

Exceptions

CX_INVALID_PARAMETER

cx_hmac_ripemd160_init_no_throw()

cx_err_t cx_hmac_ripemd160_init_no_throw	(	cx_hmac_ripemd160_t *	hmac,
		const uint8_t *	key,
		size_t	key_len
)

Initializes a HMAC-RIPEMD160 context.

Parameters

[out]	hmac	Pointer to the HMAC context. The context shall be in RAM.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 64 bytes.

Returns

Error code:

• CX_OK on success
• CX_INVALID_PARAMETER

cx_hmac_sha224_init()

cx_err_t cx_hmac_sha224_init	(	cx_hmac_sha256_t *	hmac,
		const uint8_t *	key,
		unsigned int	key_len
)

Initializes a HMAC-SHA224 context.

Parameters

[out]	hmac	Pointer to the HMAC context. The context shall be in RAM.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 64 bytes.

Returns

Error code:

• CX_OK on success
• CX_INVALID_PARAMETER

cx_hmac_sha256()

size_t cx_hmac_sha256	(	const uint8_t *	key,
		size_t	key_len,
		const uint8_t *	in,
		size_t	len,
		uint8_t *	mac,
		size_t	mac_len
)

Computes a HMAC value using SHA256.

Parameters

[in]	key	HMAC key value.
[in]	key_len	Length of the HMAC key.
[in]	in	Input data.
[in]	len	Length of the input data.
[out]	mac	Computed HMAC value.
[in]	mac_len	Size of the output buffer. The buffer size must be larger than the length of the HMAC value.

Returns

Length of the HMAC value.

cx_hmac_sha256_init()

static int cx_hmac_sha256_init ( cx_hmac_sha256_t *  hmac, const unsigned char *  key, unsigned int  key_len  )

Initializes a HMAC-SHA256 context.

This function throws an exception if the initialization fails.

Warning

It is recommended to use cx_hmac_sha256_init_no_throw rather than this function.

Parameters

[out]	hmac	Pointer to the HMAC context. The context shall be in RAM.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 64 bytes.

Returns

SHA256 identifier.

Exceptions

CX_INVALID_PARAMETER

cx_hmac_sha256_init_no_throw()

cx_err_t cx_hmac_sha256_init_no_throw	(	cx_hmac_sha256_t *	hmac,
		const uint8_t *	key,
		size_t	key_len
)

Initializes a HMAC-SHA256 context.

Parameters

[out]	hmac	Pointer to the HMAC context. The context shall be in RAM.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 64 bytes.

Returns

Error code:

• CX_OK on success
• CX_INVALID_PARAMETER

cx_hmac_sha384_init()

cx_err_t cx_hmac_sha384_init	(	cx_hmac_sha512_t *	hmac,
		const uint8_t *	key,
		unsigned int	key_len
)

Initializes a HMAC-SHA384 context.

Parameters

[out]	hmac	Pointer to the context. The context shall be in RAM.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 128 bytes.

Returns

Error code:

• CX_OK on success
• CX_INVALID_PARAMETER

cx_hmac_sha512()

size_t cx_hmac_sha512	(	const uint8_t *	key,
		size_t	key_len,
		const uint8_t *	in,
		size_t	len,
		uint8_t *	mac,
		size_t	mac_len
)

Computes a HMAC value using SHA512.

Parameters

[in]	key	HMAC key value.
[in]	key_len	Length of the HMAC key.
[in]	in	Input data.
[in]	len	Length of the input data.
[out]	mac	Computed HMAC value.
[in]	mac_len	Size of the output buffer. The buffer size must be larger than the length of the HMAC value.

Returns

Length of the HMAC value.

cx_hmac_sha512_init()

static int cx_hmac_sha512_init ( cx_hmac_sha512_t *  hmac, const unsigned char *  key, unsigned int  key_len  )

Initializes a HMAC-SHA512 context.

This function throws an exception if the initialization fails.

Warning

It is recommended to use cx_hmac_sha512_init_no_throw rather than this function.

Parameters

[out]	hmac	Pointer to the context. The context shall be in RAM.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 128 bytes.

Returns

SHA512 identifier.

Exceptions

CX_INVALID_PARAMETER

cx_hmac_sha512_init_no_throw()

cx_err_t cx_hmac_sha512_init_no_throw	(	cx_hmac_sha512_t *	hmac,
		const uint8_t *	key,
		size_t	key_len
)

Initializes a HMAC-SHA512 context.

Parameters

[out]	hmac	Pointer to the context. The context shall be in RAM.
[in]	key	Pointer to the HMAC key value. If a key has been set, passing NULL pointer will reinitialize the context with the previously set key.
[in]	key_len	Length of the key. The key length shall be less than 128 bytes.

Returns

Error code:

• CX_OK on success
• CX_INVALID_PARAMETER

cx_hmac_update()

cx_err_t cx_hmac_update	(	cx_hmac_t *	hmac,
		const uint8_t *	in,
		size_t	in_len
)

Adds more data to compute the HMAC.

A call to this function is equivalent to: cx_hmac_no_throw(hmac, 0, in, in_len, NULL, 0).

Parameters

[out]	hmac	Pointer to the HMAC context.
[in]	in	Input data to add to the context.
[in]	in_len	Length of the input data.

Returns

Error code:

• CX_OK on success
• CX_INVALID_PARAMETER
• INVALID_PARAMETER

Back to the files list

---

Did you find this page helpful?

How would you improve this page for developers?

I am a developer.
Contributors will be chosen randomly to receive rewards. Check this box to send your email and participate.

Ledger collects your email address to send you rewards for your contribution to improve the Developer Portal documentation. Learn more about how we manage your data and your rights.

By providing your email address, you consent that Ledger may contact you for rewards delivery purposes. If you are part of the randomly selected contributors, we will send you an email to ask for your physical address and if necessary, ask you for additional information on the suggestion you made. Your information will only be available to Ledger and will be retained for no longer than 90 days. It may be transferred to non-European countries that ensure an adequate level of protection or under the standard contractual clauses adopted by the EU Commission.

Please note that you may withdraw your consent at any time, access your data and request their rectification or deletion. You may also request the limitation of the processing of your data. To exercise your rights or for any question on the processing of your data, please contact LEDGER’s Data Protection Officer here. If nevertheless you believe LEDGER did not adequately address your concerns and mishandled your data, you may lodge a complaint with the personal data protection authority of your country.