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

Network key management. More...

Functions

dsm_handle_t dsm_net_key_index_to_subnet_handle (mesh_key_index_t net_key_index)
 Retrieves the subnetwork handle for a given network key index. More...
 
dsm_handle_t dsm_subnet_handle_get (const nrf_mesh_network_secmat_t *p_secmat)
 Retrieves the subnetwork handle for a given network security material structure. More...
 
uint32_t dsm_subnet_handle_to_netkey_index (dsm_handle_t subnet_handle, mesh_key_index_t *p_netkey_index)
 Retrieves the key index for a subnetwork. More...
 
uint32_t dsm_subnet_add (mesh_key_index_t net_key_id, const uint8_t *p_key, dsm_handle_t *p_subnet_handle)
 Adds a subnetwork and its associated network key index to the device state storage. More...
 
uint32_t dsm_subnet_kr_phase_get (dsm_handle_t subnet_handle, nrf_mesh_key_refresh_phase_t *p_phase)
 Retrieves the current key refresh phase for a subnetwork. More...
 
uint32_t dsm_subnet_update (dsm_handle_t subnet_handle, const uint8_t *p_key)
 Updates an existing subnetwork key. More...
 
uint32_t dsm_subnet_update_swap_keys (dsm_handle_t subnet_handle)
 Starts using the new subnetwork key. More...
 
uint32_t dsm_subnet_update_commit (dsm_handle_t subnet_handle)
 Commits to using the new subnetwork key. More...
 
uint32_t dsm_subnet_delete (dsm_handle_t subnet_handle)
 Removes an existing subnetwork from the device state storage. More...
 
uint32_t dsm_subnet_get_all (mesh_key_index_t *p_key_list, uint32_t *p_count)
 Retrieves all the network key indices of the stored subnetworks. More...
 
uint32_t dsm_subnet_key_get (dsm_handle_t subnet_handle, uint8_t *p_key)
 Gets the (root) network key for a given subnet handle. More...
 

Detailed Description

Network key management.

Function Documentation

◆ dsm_net_key_index_to_subnet_handle()

dsm_handle_t dsm_net_key_index_to_subnet_handle ( mesh_key_index_t  net_key_index)

Retrieves the subnetwork handle for a given network key index.

Parameters
[in]net_key_indexThe network key index used in looking up for the handle.
Returns
The handle for the subnetwork if found, otherwise DSM_HANDLE_INVALID.

◆ dsm_subnet_handle_get()

dsm_handle_t dsm_subnet_handle_get ( const nrf_mesh_network_secmat_t p_secmat)

Retrieves the subnetwork handle for a given network security material structure.

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

◆ dsm_subnet_handle_to_netkey_index()

uint32_t dsm_subnet_handle_to_netkey_index ( dsm_handle_t  subnet_handle,
mesh_key_index_t p_netkey_index 
)

Retrieves the key index for a subnetwork.

Parameters
[in]subnet_handleHandle for the subnetwork.
[out]p_netkey_indexIndex of the network key associated with the subnetwork.
Return values
NRF_SCUCESSThe network key index was successfully returned.
NRF_ERROR_NULLThe p_netkey_index parameter was NULL.
NRF_ERROR_NOT_FOUNDThe specified subnetwork was not found.

◆ dsm_subnet_add()

uint32_t dsm_subnet_add ( mesh_key_index_t  net_key_id,
const uint8_t *  p_key,
dsm_handle_t p_subnet_handle 
)

Adds a subnetwork and its associated network key index to the device state storage.

Parameters
[in]net_key_idThe network key index of the subnetwork being added.
[in]p_keyThe network key, it must be NRF_MESH_KEY_SIZE bytes long.
[in,out]p_subnet_handleThe assigned handle to the stored subnetwork.
Return values
NRF_SUCCESSThe subnetwork and its associated index have been added successfully.
NRF_ERROR_NULLUnexpected NULL pointer is given.
NRF_ERROR_INVALID_PARAMInvalid network key index is given,
See also
DSM_KEY_INDEX_MAX.
Return values
NRF_ERROR_FORBIDDENThe given network key index has already been added before.
NRF_ERROR_INTERNALThe given network key index has already been added before and keys are the same.
NRF_ERROR_NO_MEMThe subnetwork storage is out of space,
See also
DSM_SUBNET_MAX.

◆ dsm_subnet_kr_phase_get()

uint32_t dsm_subnet_kr_phase_get ( dsm_handle_t  subnet_handle,
nrf_mesh_key_refresh_phase_t p_phase 
)

Retrieves the current key refresh phase for a subnetwork.

Parameters
[in]subnet_handleThe handle for the subnetwork to obtain the key refresh phase from.
[out]p_phasePointer to a variable where the key refresh phase is returned.
Return values
NRF_SUCCESSThe current key refresh phase for the network was successfully returned.
NRF_ERROR_NOT_FOUNDThe specified subnet handle is not valid.

◆ dsm_subnet_update()

uint32_t dsm_subnet_update ( dsm_handle_t  subnet_handle,
const uint8_t *  p_key 
)

Updates an existing subnetwork key.

This starts the key refresh procedure for this subnetwork, and causes the subnetwork to enter phase 1 of the procedure. In phase 1, the old keys are still used to transmit messages, but messages can be received using either the old or the new keys.

Parameters
[in]subnet_handleThe handle for the existing subnetwork.
[in]p_keyThe new network key to use.
Return values
NRF_SUCCESSThe network key for the given handle was updated successfully.
NRF_ERROR_NULLUnexpected NULL pointer is given.
NRF_ERROR_INVALID_STATEThe subnet key could not be updated in the current key refresh phase.
NRF_ERROR_NOT_FOUNDThe given subnet handle is not valid.

◆ dsm_subnet_update_swap_keys()

uint32_t dsm_subnet_update_swap_keys ( dsm_handle_t  subnet_handle)

Starts using the new subnetwork key.

This switches the key refresh procedure into phase 2. In phase 2, the key refresh flag is set, and the new keys are used to transmit messages. Messages can still be received using either the old or the new keys.

Parameters
[in]subnet_handleThe handle for the subnetwork to swap the keys for.
Return values
NRF_SUCCESSThe network key for the given handle was updated successfully.
NRF_ERROR_INVALID_STATEThe network keys could not be swapped in the current key refresh phase.
NRF_ERROR_NOT_FOUNDThe specified subnet handle is not valid.

◆ dsm_subnet_update_commit()

uint32_t dsm_subnet_update_commit ( dsm_handle_t  subnet_handle)

Commits to using the new subnetwork key.

This switches the key refresh procedure into phase 3. In phase 3, the key refresh flag is cleared and only the new keys are used to send and receive messages. The old keys are cleared from memory. After the new keys have been set up, phase 0 is automatically entered.

Parameters
[in]subnet_handleThe handle for the subnetwork to commit the new key to.
Return values
NRF_SUCCESSThe network key was successfully committed.
NRF_ERROR_INVALID_STATEThe network key could not be committed in the current key refresh phase.
NRF_ERROR_NOT_FOUNDThe specified subnet handle is not valid.

◆ dsm_subnet_delete()

uint32_t dsm_subnet_delete ( dsm_handle_t  subnet_handle)

Removes an existing subnetwork from the device state storage.

All applications bound to the specified subnetwork will also be deleted.

Parameters
[in]subnet_handleThe handle for the existing subnetwork.
Return values
NRF_SUCCESSThe given subnetwork has been freed successfully.
NRF_ERROR_FORBIDDENThe NetList shall contain a minimum of one NetKey.
NRF_ERROR_NOT_FOUNDThe given subnetwork handle is not valid.

◆ dsm_subnet_get_all()

uint32_t dsm_subnet_get_all ( mesh_key_index_t p_key_list,
uint32_t *  p_count 
)

Retrieves all the network key indices of the stored subnetworks.

Parameters
[in,out]p_key_listPointer to the array for storing all the network key indices.
[in,out]p_countThe size of the p_key_list array. Will be changed to the number of network key indices returned via the p_key_list.
Return values
NRF_SUCCESSThe p_key_list has been successfully populated by all the network key indices.
NRF_ERROR_NULLAn unexpected NULL pointer is given.
NRF_ERROR_INVALID_LENGTHThe p_key_list is not large enough to store all the network key indices, so only a partial list (the first *p_count indices) is returned.

◆ dsm_subnet_key_get()

uint32_t dsm_subnet_key_get ( dsm_handle_t  subnet_handle,
uint8_t *  p_key 
)

Gets the (root) network key for a given subnet handle.

Note
In NRF_MESH_KEY_REFRESH_PHASE_2 and NRF_MESH_KEY_REFRESH_PHASE_3 this will return the updated key.
Parameters
[in]subnet_handleSubnet handle.
[out]p_keyPointer to NRF_MESH_KEY_SIZE array to store the key.
Return values
NRF_SUCCESSSuccessfully copied the key.
NRF_ERROR_NOT_FOUNDInvalid subnet handle.