Application key management

Retrieves the application key handle for a given application key index.

Parameters

[in]

appkey_index

The application key index used in looking up for the handle.

Returns

If found, the handle for the application key stored otherwise DSM_HANDLE_INVALID.

Retrieves the application key handle for a given application security material.

Parameters

[in]

p_secmat

The application security material used in looking up for the handle.

Returns

If found, the handle for the application key stored otherwise DSM_HANDLE_INVALID.

Retrieves the application key index for a specified application key handle.

Parameters

[in]	appkey_handle	Application key handle.
[out]	p_index	Pointer to a variable where the application key index can be stored.

Return values

NRF_SUCCESS	The index of the specified application key was successfully retrieved.
NRF_ERROR_NULL	p_index was NULL.
NRF_ERROR_NOT_FOUND	The specified application handle is invalid.

Stores the network key handle to the p_netkey_handle pointer for a specified application key handle.

Parameters

[in]	appkey_handle	Application key handle.
[out]	p_netkey_handle	Pointer to a variable where the associated netkey handle can be stored.

Return values

NRF_SUCCESS	The index of the network key associated with the specified application key was successfully retrieved.
NRF_ERROR_NULL	p_netkey_handle was NULL.
NRF_ERROR_NOT_FOUND	The specified application handle is invalid.

Adds an application key and its associated application key index to the device state storage.

The added application key will be bound with the given subnetwork.

Note

"An application key shall only be bound to a single network key." see Bluetooth Mesh Profile Specification (MshPRFv1.0.1), section 3.8.6

Parameters

[in]	app_key_id	The application key index of the application key being added.
[in]	subnet_handle	The handle of the subnetwork the application key belongs to.
[in]	p_key	The application key, it must be NRF_MESH_KEY_SIZE bytes long.
[in,out]	p_app_handle	The assigned handle to the stored application key.

Return values

NRF_SUCCESS	The application key and its associated appplication key index have been added and bound to the given subnetwork successfully.
NRF_ERROR_NULL	Unexpected NULL pointer is given.
NRF_ERROR_NOT_FOUND	The given subnetwork handle is not valid.
NRF_ERROR_INVALID_PARAM	Invalid application key index is given,

See also

DSM_KEY_INDEX_MAX.

Return values

NRF_ERROR_FORBIDDEN	The given application key index has already been added before.
NRF_ERROR_INTERNAL	The given application key index has already been added before and keys are the same.
NRF_ERROR_NO_MEM	The application key storage is out of space,

See also

DSM_APP_MAX.

Updates an existing application key.

Application keys can only be updated in key refresh phase 1, after the key refresh procedure has been initiated but before the new keys are in use.

Updating an application key is an optional part of the key refresh procedure. Any keys not updated will work as before after the key refresh, but be bound to the updated network key.

Parameters

[in]	app_handle	The handle for the existing application key.
[in]	p_key	The new application key to use.

Return values

NRF_SUCCESS	The application key for the given handle was updated successfully.
NRF_ERROR_NULL	Unexpected NULL pointer is given.
NRF_ERROR_INVALID_STATE	The key could not be updated because the key's subnet was not in the correct key refresh phase.
NRF_ERROR_NOT_FOUND	The given application handle is not valid.

Removes an existing application key from the device state storage.

Parameters

[in]

app_handle

The handle for the existing application key.

Return values

NRF_SUCCESS	The given application handle has been freed successfully.
NRF_ERROR_NOT_FOUND	The given application handle is not valid.

Retrieves all the application key indices of the stored application keys of a specific subnetwork.

Parameters

[in]	subnet_handle	The handle of the subnetwork the application key belongs to.
[in,out]	p_key_list	Pointer to the array for storing the application key indices.
[in,out]	p_count	The size of the p_key_list array. Will be changed to the number of application key indices returned via the p_key_list.

Return values

NRF_SUCCESS	The p_key_list has been successfully populated by all the application key indices of the requested subnetwork.
NRF_ERROR_NOT_FOUND	The given subnetwork handle is not valid.
NRF_ERROR_NULL	An unexpected NULL pointer is given.
NRF_ERROR_INVALID_LENGTH	The p_key_list is not large enough to store all the application key indices, so only a partial list (the first *p_count indices) is returned.