Network key management.
More...
Network key management.
◆ dsm_net_key_index_to_subnet_handle()
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()
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()
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()
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()
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()
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. |