Cryptographic engine driver definition for LR1110. More...

#include "transceiver/lr1110_crypto_engine_types.h"
#include "common/lr1110_types.h"
#include "common/lr1110_hal.h"

Functions
err_t	lr1110_crypto_select (lriot_t *ctx, lr1110_crypto_element_t element)
	Select the crypto element to be used.

err_t	lr1110_crypto_set_key (lriot_t ctx, uint8_t status, uint8_t key_id, lr1110_crypto_key_t key)
	Set a key in the previously selected crypto element.

err_t	lr1110_crypto_derive_key (lriot_t ctx, uint8_t status, uint8_t src_key_id, uint8_t dest_key_id, lr1110_crypto_nonce_t nonce)
	Derive a key previously set.

err_t	lr1110_crypto_process_join_accept (lriot_t ctx, uint8_t status, uint8_t dec_key_id, uint8_t ver_key_id, lr1110_crypto_lorawan_version_t lorawan_version, uint8_t header, uint8_t data_in, uint8_t length, uint8_t *data_out)
	Perform the needed operations to extract the payload from a join accept message.

err_t	lr1110_crypto_compute_aes_cmac (lriot_t ctx, uint8_t status, uint8_t key_id, uint8_t *data_buf, uint16_t length, lr1110_crypto_mic_t mic)
	Compute an AES-CMAC.

err_t	lr1110_crypto_verify_aes_cmac (lriot_t ctx, uint8_t status, uint8_t key_id, uint8_t *data_buf, uint16_t length, lr1110_crypto_mic_t mic)
	Compute an AES-CMAC and make a comparison with a value given as parameter.

err_t	lr1110_crypto_aes_encrypt_01 (lriot_t ctx, uint8_t status, uint8_t key_id, uint8_t data_buf, uint16_t length, uint8_t result)
	Compute an AES encryption with a key ID specified in parameter.

err_t	lr1110_crypto_aes_encrypt (lriot_t ctx, uint8_t status, uint8_t key_id, uint8_t data_buf, uint16_t length, uint8_t result)
	Compute an AES encryption with a key ID specified in parameter.

err_t	lr1110_crypto_aes_decrypt (lriot_t ctx, uint8_t status, uint8_t key_id, uint8_t data_buf, uint16_t length, uint8_t result)
	Compute an AES decryption with a key ID specified in parameter.

err_t	lr1110_crypto_store_to_flash (lriot_t ctx, uint8_t status)
	Store the crypto data (keys, parameters) from RAM into the flash memory.

err_t	lr1110_crypto_restore_from_flash (lriot_t ctx, uint8_t status)
	Restore the crypto data (keys, parameters) from flash memory into RAM.

err_t	lr1110_crypto_set_parameter (lriot_t ctx, uint8_t status, uint8_t param_id, lr1110_crypto_param_t parameter)
	Set a specific parameter identified by param_id in the crypto RAM.

err_t	lr1110_crypto_get_parameter (lriot_t ctx, uint8_t status, uint8_t param_id, lr1110_crypto_param_t parameter)
	Get a specific parameter identified by paramID from the crypto RAM.

Detailed Description

Cryptographic engine driver definition for LR1110.

Redistribution and use in source and binary forms, with or without modification, are permitted (subject to the limitations in the disclaimer below) provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Semtech corporation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Function Documentation

◆ lr1110_crypto_aes_decrypt()

err_t lr1110_crypto_aes_decrypt	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	key_id,
		uint8_t *	data_buf,
		uint16_t	length,
		uint8_t *	result )

Compute an AES decryption with a key ID specified in parameter.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	key_id	The identifier of the key to be used for the computation
[in]	data_buf	The data to decrypt
[in]	length	The length in bytes of the data to decrypt - this value shall be a multiple of 16
[out]	result	A pointer to a data buffer that will be filled with the decrypted data. Values of this buffer are meaningful if and only if the return status is LR1110_CRYPTO_STATUS_SUCCESS

See also: lr1110_crypto_set_key, lr1110_crypto_derive_key

Returns: Operation status

◆ lr1110_crypto_aes_encrypt()

err_t lr1110_crypto_aes_encrypt	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	key_id,
		uint8_t *	data_buf,
		uint16_t	length,
		uint8_t *	result )

Compute an AES encryption with a key ID specified in parameter.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	key_id	The identifier of the key to be used for the computation
[in]	data_buf	The data to encrypt
[in]	length	The length in bytes of the data to encrypt - this value shall be a multiple of 16
[out]	result	A pointer to a data buffer that will be filled with the encrypted data. Values of this buffer are meaningful if and only if the return status is LR1110_CRYPTO_STATUS_SUCCESS

See also: lr1110_crypto_set_key, lr1110_crypto_derive_key

Returns: Operation status

◆ lr1110_crypto_aes_encrypt_01()

err_t lr1110_crypto_aes_encrypt_01	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	key_id,
		uint8_t *	data_buf,
		uint16_t	length,
		uint8_t *	result )

Compute an AES encryption with a key ID specified in parameter.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	key_id	The identifier of the key to be used for the computation
[in]	data_buf	The data to encrypt
[in]	length	The length in bytes of the data to encrypt - this value shall be a multiple of 16
[out]	result	A pointer to a data buffer that will be filled with the encrypted data. Values of this buffer are meaningful if and only if the return status is LR1110_CRYPTO_STATUS_SUCCESS

See also: lr1110_crypto_set_key, lr1110_crypto_derive_key

Returns: Operation status

◆ lr1110_crypto_compute_aes_cmac()

err_t lr1110_crypto_compute_aes_cmac	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	key_id,
		uint8_t *	data_buf,
		uint16_t	length,
		lr1110_crypto_mic_t	mic )

Compute an AES-CMAC.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	key_id	The identifier of the keyused for the computation
[in]	data_buf	The data to compute
[in]	length	The length in bytes of the data to compute
[out]	mic	Placeholder for the computed MIC (first 4 bytes of the AES-CMAC)

See also: lr1110_crypto_verify_aes_cmac

Returns: Operation status

◆ lr1110_crypto_derive_key()

err_t lr1110_crypto_derive_key	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	src_key_id,
		uint8_t	dest_key_id,
		lr1110_crypto_nonce_t	nonce )

Derive a key previously set.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	src_key_id	The identifier of the key to be derived
[in]	dest_key_id	The identifier where the derived key will be stored after call to lr1110_crypto_store_to_flash
[in]	nonce	The nonce to be used to perform the derivation

See also: lr1110_crypto_set_key

Returns: Operation status

◆ lr1110_crypto_get_parameter()

err_t lr1110_crypto_get_parameter	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	param_id,
		lr1110_crypto_param_t	parameter )

Get a specific parameter identified by paramID from the crypto RAM.

This function does not fetch a parameter from the flash memory. The parameters shall be restored before using lr1110_crypto_restore_from_flash command.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	param_id	The identifier of the parameter to get
[out]	parameter	The placeholder to store the parameter

See also: lr1110_crypto_set_parameter

Returns: Operation status

◆ lr1110_crypto_process_join_accept()

err_t lr1110_crypto_process_join_accept	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	dec_key_id,
		uint8_t	ver_key_id,
		lr1110_crypto_lorawan_version_t	lorawan_version,
		uint8_t *	header,
		uint8_t *	data_in,
		uint8_t	length,
		uint8_t *	data_out )

Perform the needed operations to extract the payload from a join accept message.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	dec_key_id	The identifier of the key used for message decryption
[in]	ver_key_id	The identifier of the key used for MIC verification
[in]	lorawan_version	LoRaWAN version to know the size of the header
[in]	header	The header to compute (length linked to lorawan_version)
[in]	data_buf	The data to compute
[in]	length	The length in bytes of the data to compute
[out]	data_out	Placeholder for the decrypted data

Returns: Operation status

◆ lr1110_crypto_restore_from_flash()

err_t lr1110_crypto_restore_from_flash	(	lriot_t *	ctx,
		uint8_t *	status )

Restore the crypto data (keys, parameters) from flash memory into RAM.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function

See also: lr1110_crypto_store_to_flash

Returns: Operation status

◆ lr1110_crypto_select()

err_t lr1110_crypto_select	(	lriot_t *	ctx,
		lr1110_crypto_element_t	element )

Select the crypto element to be used.

By default, the internal crypto engine is selected. It is not needed to call this command if one plans to use the internal crypto engine.

Parameters

[in]	ctx	Chip implementation context
[in]	element	The type of crypto element to use

Returns: Operation status

◆ lr1110_crypto_set_key()

err_t lr1110_crypto_set_key	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	key_id,
		lr1110_crypto_key_t	key )

Set a key in the previously selected crypto element.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	key_id	The identifier of the key to be set
[in]	key	The key to be set

See also: lr1110_crypto_derive_key

Returns: Operation status

◆ lr1110_crypto_set_parameter()

err_t lr1110_crypto_set_parameter	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	param_id,
		lr1110_crypto_param_t	parameter )

Set a specific parameter identified by param_id in the crypto RAM.

This function does not store a parameter in the flash memory. The parameters shall be stored after using lr1110_crypto_store_to_flash command.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	param_id	The identifier of the parameter to be set
[in]	parameter	The parameter to be set

See also: lr1110_crypto_get_parameter

Returns: Operation status

◆ lr1110_crypto_store_to_flash()

err_t lr1110_crypto_store_to_flash	(	lriot_t *	ctx,
		uint8_t *	status )

Store the crypto data (keys, parameters) from RAM into the flash memory.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function

See also: lr1110_crypto_restore_from_flash

Returns: Operation status

◆ lr1110_crypto_verify_aes_cmac()

err_t lr1110_crypto_verify_aes_cmac	(	lriot_t *	ctx,
		uint8_t *	status,
		uint8_t	key_id,
		uint8_t *	data_buf,
		uint16_t	length,
		lr1110_crypto_mic_t	mic )

Compute an AES-CMAC and make a comparison with a value given as parameter.

Parameters

[in]	ctx	Chip implementation context
[out]	status	The status returned by the execution of this cryptographic function
[in]	key_id	The identifier of the key to be used for the computation
[in]	data_buf	The data to compute
[in]	length	The length in bytes of the data to compute
[in]	mic	The MIC value (first 4 bytes of the CMAC) use for comparison

See also: lr1110_crypto_compute_aes_cmac

Returns: Operation status

Functions

Detailed Description

Function Documentation

◆ lr1110_crypto_aes_decrypt()

◆ lr1110_crypto_aes_encrypt()

◆ lr1110_crypto_aes_encrypt_01()

◆ lr1110_crypto_compute_aes_cmac()

◆ lr1110_crypto_derive_key()

◆ lr1110_crypto_get_parameter()

◆ lr1110_crypto_process_join_accept()

◆ lr1110_crypto_restore_from_flash()

◆ lr1110_crypto_select()

◆ lr1110_crypto_set_key()

◆ lr1110_crypto_set_parameter()

◆ lr1110_crypto_store_to_flash()

◆ lr1110_crypto_verify_aes_cmac()