APIs to set up or read status of security on a link.

This section describes APIs to set up Security. These APIs require that the peer is connected before the procedures can be requested. More...

Functions
ret_code_t	dm_security_setup_req (dm_handle_t *p_handle)
	Function for requesting setting up security on a link. More...
ret_code_t	dm_security_status_req (dm_handle_t const *p_handle, dm_security_status_t *p_status)
	Function for reading the status of the security on a link. More...
ret_code_t	dm_whitelist_create (dm_application_instance_t const *p_handle, ble_gap_whitelist_t *p_whitelist)
	Function for creating the whitelist. More...

Detailed Description

This section describes APIs to set up Security. These APIs require that the peer is connected before the procedures can be requested.

This group allows application to request security procedures or get the status of the security on a link.

Function Documentation

ret_code_t dm_security_setup_req

(

dm_handle_t *

p_handle

)

Function for requesting setting up security on a link.

This API initiates security procedures with a peer device.

Note

For the GAP Central role, in case peer is not bonded, request to bond/pair is initiated. If it is bonded, the link is re-encrypted using the existing bond information. For the GAP peripheral role, a Slave security request is sent.

If a pairing procedure is initiated successfully, application is notified of DM_EVT_SECURITY_SETUP_COMPLETE. A result indicating success or failure is notified along with the event. In case the link is re-encrypted using existing bond information, DM_EVT_LINK_SECURED is notified to the application.

Parameters

[in]

p_handle

Identifies the link on which security is desired.

Return values

NRF_SUCCESS	On success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATE	If the API is called without module initialization and/or application registration.
NRF_ERROR_NULL	If p_handle is NULL.
NRF_ERROR_INVALID_ADDR	If the peer is not identified by the handle provided by the application or if the peer is not connected when this procedure is requested.

ret_code_t dm_security_status_req	(	dm_handle_t const *	p_handle,
		dm_security_status_t *	p_status
	)

Function for reading the status of the security on a link.

This API allows application to query status of security on a link.

Parameters

[in]	p_handle	Identifies the link on which security is desired.
[out]	p_status	Pointer where security status is provided to the application. See dm_security_status_t for possible statuses that can be expected.

Return values

NRF_SUCCESS	Or appropriate error code indicating reason for failure.
NRF_ERROR_INVALID_STATE	If the API is called without module initialization and/or application registration.
NRF_ERROR_NULL	If p_handle or p_status is NULL.
NRF_ERROR_INVALID_ADDR	If peer is not identified by the handle provided by the application or if peer is not connected when this procedure is requested.

ret_code_t dm_whitelist_create	(	dm_application_instance_t const *	p_handle,
		ble_gap_whitelist_t *	p_whitelist
	)

Function for creating the whitelist.

This API allows application to create whitelist based on bonded peer devices in module data base.

Parameters

[in]	p_handle	Identifies the application requesting whitelist creation.
[in,out]	p_whitelist	Pointer where created whitelist is provided to the application.

Note

'addr_count' and 'irk_count' fields of the structure should be populated with the maximum number of devices that the application wishes to request in the whitelist. If the number of bonded devices is less than requested, the fields are updated with that number of devices. If the number of devices are more than requested, the module will populate the list with devices in the order the bond was established with the peer devices. Also, if this routine is called when a connection exists with one or more peer devices, those connected devices are not added to the whitelist.

Return values

NRF_SUCCESS	On success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATE	If the API is called without module initialization and/or application registration.
NRF_ERROR_NULL	If p_handle or p_whitelist is NULL.