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_index The 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_secmat The 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_handle	Handle for the subnetwork.
[out]	p_netkey_index	Index of the network key associated with the subnetwork.

Return values

NRF_SCUCESS	The network key index was successfully returned.
NRF_ERROR_NULL	The `p_netkey_index` parameter was `NULL`.
NRF_ERROR_NOT_FOUND	The 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_id	The network key index of the subnetwork being added.
[in]	p_key	The network key, it must be NRF_MESH_KEY_SIZE bytes long.
[in,out]	p_subnet_handle	The assigned handle to the stored subnetwork.

Return values

NRF_SUCCESS	The subnetwork and its associated index have been added successfully.
NRF_ERROR_NULL	Unexpected NULL pointer is given.
NRF_ERROR_INVALID_PARAM	Invalid network key index is given,

See also: DSM_KEY_INDEX_MAX.

Return values

NRF_ERROR_FORBIDDEN	The given network key index has already been added before.
NRF_ERROR_INTERNAL	The given network key index has already been added before and keys are the same.
NRF_ERROR_NO_MEM	The 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_handle	The handle for the subnetwork to obtain the key refresh phase from.
[out]	p_phase	Pointer to a variable where the key refresh phase is returned.

Return values

NRF_SUCCESS	The current key refresh phase for the network was successfully returned.
NRF_ERROR_NOT_FOUND	The 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_handle	The handle for the existing subnetwork.
[in]	p_key	The new network key to use.

Return values

NRF_SUCCESS	The network key for the given handle was updated successfully.
NRF_ERROR_NULL	Unexpected NULL pointer is given.
NRF_ERROR_INVALID_STATE	The subnet key could not be updated in the current key refresh phase.
NRF_ERROR_NOT_FOUND	The 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_handle The handle for the subnetwork to swap the keys for.

Return values

NRF_SUCCESS	The network key for the given handle was updated successfully.
NRF_ERROR_INVALID_STATE	The network keys could not be swapped in the current key refresh phase.
NRF_ERROR_NOT_FOUND	The 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_handle The handle for the subnetwork to commit the new key to.

Return values

NRF_SUCCESS	The network key was successfully committed.
NRF_ERROR_INVALID_STATE	The network key could not be committed in the current key refresh phase.
NRF_ERROR_NOT_FOUND	The 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_handle The handle for the existing subnetwork.

Return values

NRF_SUCCESS	The given subnetwork has been freed successfully.
NRF_ERROR_FORBIDDEN	The NetList shall contain a minimum of one NetKey.
NRF_ERROR_NOT_FOUND	The 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_list	Pointer to the array for storing all the network key indices.
[in,out]	p_count	The 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_SUCCESS	The `p_key_list` has been successfully populated by all the network key indices.
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 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_handle	Subnet handle.
[out]	p_key	Pointer to NRF_MESH_KEY_SIZE array to store the key.

Return values

NRF_SUCCESS	Successfully copied the key.
NRF_ERROR_NOT_FOUND	Invalid subnet handle.

Functions

Detailed Description

Function Documentation

◆ dsm_net_key_index_to_subnet_handle()

◆ dsm_subnet_handle_get()

◆ dsm_subnet_handle_to_netkey_index()

◆ dsm_subnet_add()

◆ dsm_subnet_kr_phase_get()

◆ dsm_subnet_update()

◆ dsm_subnet_update_swap_keys()

◆ dsm_subnet_update_commit()

◆ dsm_subnet_delete()

◆ dsm_subnet_get_all()

◆ dsm_subnet_key_get()