| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Encryption configuration
This information applies to the following SoftDevices: S212, S332

The ANT encryption configuration module provides functionality to initialize encrypted ANT channels. The configuration consists of two steps:

1. Configuring the cryptographic settings of the ANT stack.
2. Configuring and initializing the channels to use encryption.

The API for this module is available here: ANT encryption configuration

See ANT Message Protocol and Usage for detailed information about ANT's encryption capabilities.

To quickly get started, use the sample code from the ANT Multi Channels Encrypted example.

# Cryptographic settings of the ANT stack

After defining the encryption ID and key, use the macro ANT_ENCRYPT_STACK_SETTINGS_BASE_DEF to configure the cryptographic settings for the ANT stack.

To apply this configuration to the stack, call ant_stack_encryption_config.

The following code example shows how to create a cryptographic configuration and apply it to the stack:

uint8_t crypto_id[4] = CRYPTO_ID;
uint8_t crypto_key[16] = CRYPTO_KEY;
ANT_ENCRYPT_STACK_SETTINGS_BASE_DEF( se_conf , crypto_key, crypto_id);
err_code = ant_stack_encryption_config(&ANT_ENCRYPT_STACK_SETTINGS_BASE( se_conf ));
APP_ERROR_CHECK(err_code);

# Channel initialization

This module uses an extended version of ant_channel_config_t that includes an addition field (`.p_crypto_settings`). This field holds a pointer to the cryptographic settings for a channel.

You must change the value of ANT_CONFIG_ENC_CHANNEL_USED in `ant_stack_config_defs.h` so that the extended version of ant_channel_config_t is used. The value of the macro must be greater than 0.

To initialize an encrypted channel, call ant_channel_init.

The following code example shows how to configure and initialize an encrypted master channel:

ant_crypto_channel_setings_t channel_crypto_setings =
{
.mode = ENCRYPTION_BASIC_REQUEST_MODE,
.key_index = 0,
.decimation_rate = 1
};
ant_channel_config_t m_channel_config =
{
.channel_type = CHANNEL_TYPE_MASTER,
.ext_assign = ANT_EXT_ASSIGN,
.rf_freq = RF_FREQ,
.transmission_type = CHAN_ID_TRANS_TYPE,
.device_type = CHAN_ID_DEV_TYPE,
.channel_period = CHAN_PERIOD,
.network_number = ANT_CHANNEL_DEFAULT_NETWORK,
.p_crypto_settings = &channel_crypto_setings,
.device_number = 20,
.channel_number = 0
};
err_code = ant_channel_init(&m_channel_config);
APP_ERROR_CHECK(err_code);

If you do not want to use the extension to ant_channel_config_t, you can use the ant_channel_encrypt_config function directly to configure encryption for a channel.

See the following example code:

ant_crypto_channel_setings_t channel_crypto_settings =
{
.mode = ENCRYPTION_BASIC_REQUEST_MODE,
.key_index = 0,
.decimation_rate = 1
};
err_code = ant_channel_encrypt_config( CHANNEL_TYPE_MASTER , 0, channel_crypto_settings);
APP_ERROR_CHECK(err_code);

# Event handling

If your application (master or slave) needs information about the state of encryption, for example, whether a channel is encrypted, implement event handling for the encryption events. To do so, include the ANT encryption event handler ant_encrypt_event_handler in the ANT event dispatching process, so that it is called every time an ANT event occurs.

You can then implement an application-specific event handler of type ant_encryp_user_handler_t that deals with encryption events like negotiation success, negotiation failure, or channel loss. Call ant_enc_event_handler_register to register this event handler.