nRF5 SDK for Mesh v3.2.0  08c60f6
Application key management

Application key management. More...

Functions

dsm_handle_t dsm_appkey_index_to_appkey_handle (mesh_key_index_t appkey_index)
 Retrieves the application key handle for a given application key index. More...
 
dsm_handle_t dsm_appkey_handle_get (const nrf_mesh_application_secmat_t *p_secmat)
 Retrieves the application key handle for a given application security material. More...
 
uint32_t dsm_appkey_handle_to_appkey_index (dsm_handle_t appkey_handle, mesh_key_index_t *p_index)
 Retrieves the application key index for a specified application key handle. More...
 
uint32_t dsm_appkey_handle_to_subnet_handle (dsm_handle_t appkey_handle, dsm_handle_t *p_netkey_handle)
 Stores the network key handle to the p_netkey_handle pointer for a specified application key handle. More...
 
uint32_t dsm_appkey_add (mesh_key_index_t app_key_id, dsm_handle_t subnet_handle, const uint8_t *p_key, dsm_handle_t *p_app_handle)
 Adds an application key and its associated application key index to the device state storage. More...
 
uint32_t dsm_appkey_update (dsm_handle_t app_handle, const uint8_t *p_key)
 Updates an existing application key. More...
 
uint32_t dsm_appkey_delete (dsm_handle_t app_handle)
 Removes an existing application key from the device state storage. More...
 
uint32_t dsm_appkey_get_all (dsm_handle_t subnet_handle, mesh_key_index_t *p_key_list, uint32_t *p_count)
 Retrieves all the application key indices of the stored application keys of a specific subnetwork. More...
 

Detailed Description

Application key management.

Function Documentation

◆ dsm_appkey_index_to_appkey_handle()

dsm_handle_t dsm_appkey_index_to_appkey_handle ( mesh_key_index_t  appkey_index)

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

Parameters
[in]appkey_indexThe application key index used in looking up for the handle.
Returns
If found, the handle for the application key stored otherwise DSM_HANDLE_INVALID.

◆ dsm_appkey_handle_get()

dsm_handle_t dsm_appkey_handle_get ( const nrf_mesh_application_secmat_t p_secmat)

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

Parameters
[in]p_secmatThe application security material used in looking up for the handle.
Returns
If found, the handle for the application key stored otherwise DSM_HANDLE_INVALID.

◆ dsm_appkey_handle_to_appkey_index()

uint32_t dsm_appkey_handle_to_appkey_index ( dsm_handle_t  appkey_handle,
mesh_key_index_t p_index 
)

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

Parameters
[in]appkey_handleApplication key handle.
[out]p_indexPointer to a variable where the application key index can be stored.
Return values
NRF_SUCCESSThe index of the specified application key was successfully retrieved.
NRF_ERROR_NULLp_index was NULL.
NRF_ERROR_NOT_FOUNDThe specified application handle is invalid.

◆ dsm_appkey_handle_to_subnet_handle()

uint32_t dsm_appkey_handle_to_subnet_handle ( dsm_handle_t  appkey_handle,
dsm_handle_t p_netkey_handle 
)

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

Parameters
[in]appkey_handleApplication key handle.
[out]p_netkey_handlePointer to a variable where the associated netkey handle can be stored.
Return values
NRF_SUCCESSThe index of the network key associated with the specified application key was successfully retrieved.
NRF_ERROR_NULLp_netkey_handle was NULL.
NRF_ERROR_NOT_FOUNDThe specified application handle is invalid.

◆ dsm_appkey_add()

uint32_t dsm_appkey_add ( mesh_key_index_t  app_key_id,
dsm_handle_t  subnet_handle,
const uint8_t *  p_key,
dsm_handle_t p_app_handle 
)

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 Mesh Profile Bluetooth Specification v1.0, section 3.8.6
Parameters
[in]app_key_idThe application key index of the application key being added.
[in]subnet_handleThe handle of the subnetwork the application key belongs to.
[in]p_keyThe application key, it must be NRF_MESH_KEY_SIZE bytes long.
[in,out]p_app_handleThe assigned handle to the stored application key.
Return values
NRF_SUCCESSThe application key and its associated appplication key index have been added and bound to the given subnetwork successfully.
NRF_ERROR_NULLUnexpected NULL pointer is given.
NRF_ERROR_NOT_FOUNDThe given subnetwork handle is not valid.
NRF_ERROR_INVALID_PARAMInvalid application key index is given,
See also
DSM_KEY_INDEX_MAX.
Return values
NRF_ERROR_FORBIDDENThe given application key index has already been added before.
NRF_ERROR_INTERNALThe given application key index has already been added before and keys are the same.
NRF_ERROR_NO_MEMThe application key storage is out of space,
See also
DSM_APP_MAX.

◆ dsm_appkey_update()

uint32_t dsm_appkey_update ( dsm_handle_t  app_handle,
const uint8_t *  p_key 
)

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_handleThe handle for the existing application key.
[in]p_keyThe new application key to use.
Return values
NRF_SUCCESSThe application key for the given handle was updated successfully.
NRF_ERROR_NULLUnexpected NULL pointer is given.
NRF_ERROR_INVALID_STATEThe key could not be updated because the key's subnet was not in the correct key refresh phase.
NRF_ERROR_NOT_FOUNDThe given application handle is not valid.

◆ dsm_appkey_delete()

uint32_t dsm_appkey_delete ( dsm_handle_t  app_handle)

Removes an existing application key from the device state storage.

Parameters
[in]app_handleThe handle for the existing application key.
Return values
NRF_SUCCESSThe given application handle has been freed successfully.
NRF_ERROR_NOT_FOUNDThe given application handle is not valid.

◆ dsm_appkey_get_all()

uint32_t dsm_appkey_get_all ( dsm_handle_t  subnet_handle,
mesh_key_index_t p_key_list,
uint32_t *  p_count 
)

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

Parameters
[in]subnet_handleThe handle of the subnetwork the application key belongs to.
[in,out]p_key_listPointer to the array for storing the application key indices.
[in,out]p_countThe 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_SUCCESSThe p_key_list has been successfully populated by all the application key indices of the requested subnetwork.
NRF_ERROR_NOT_FOUNDThe given subnetwork handle is not valid.
NRF_ERROR_NULLAn unexpected NULL pointer is given.
NRF_ERROR_INVALID_LENGTHThe 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.