sd_ble_gap_authenticate()

uint32_t sd_ble_gap_authenticate	(	uint16_t	conn_handle,
		ble_gap_sec_params_t const *	p_sec_params )

#include <ble_gap.h>

Initiate the GAP Authentication procedure.

In the peripheral role, this function will send an SMP Security Request.

In the central role, this function will send an SMP Pairing Request (or an SMP Pairing Failed if rejected).

Events generated

Depending on the security parameters set and the packet exchanges with the peer, the following events may be generated:

BLE_GAP_EVT_SEC_PARAMS_REQUEST

BLE_GAP_EVT_SEC_INFO_REQUEST

BLE_GAP_EVT_PASSKEY_DISPLAY

BLE_GAP_EVT_KEY_PRESSED

BLE_GAP_EVT_AUTH_KEY_REQUEST

BLE_GAP_EVT_LESC_DHKEY_REQUEST

BLE_GAP_EVT_CONN_SEC_UPDATE

BLE_GAP_EVT_AUTH_STATUS

BLE_GAP_EVT_TIMEOUT

Relevant Message Sequence Charts

Peripheral Security Request

Security Request Reception

Central Encryption and Authentication mutual exclusion

Central Legacy Pairing: Just Works

Central Legacy Bonding: Just Works

Central Legacy Bonding: Passkey Entry, Central displays

Central Legacy Bonding: Passkey Entry, User Inputs on Central

Central Legacy Bonding: Out Of Band

Central LESC Pairing: Just Works

Central LESC Bonding: Numeric Comparison

Central LESC Bonding: Passkey Entry, Central Displays

Central LESC Bonding: Passkey Entry, User Inputs on Central

Central LESC Bonding: Out of Band

Parameters

[in]	conn_handle	Connection handle.
[in]	p_sec_params	Pointer to the ble_gap_sec_params_t structure with the security parameters to be used during the pairing or bonding procedure. In the peripheral role, only the bond, mitm, lesc and keypress fields of this structure are used. In the central role, this pointer may be NULL to reject a Security Request.

Return values

NRF_SUCCESS	Successfully initiated authentication procedure.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied.
NRF_ERROR_INVALID_STATE	Invalid state to perform operation. Either: No link has been established. An encryption is already executing or queued.
NRF_ERROR_NO_MEM	The maximum number of authentication procedures that can run in parallel for the given role is reached.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid connection handle supplied.
NRF_ERROR_NOT_SUPPORTED	Distribution of own Identity Information is only supported if the Central Address Resolution characteristic is configured to be included or the Softdevice is configured to support peripheral roles only. See ble_gap_cfg_car_incl_cfg_t and ble_gap_cfg_role_count_t.
NRF_ERROR_TIMEOUT	A SMP timeout has occurred, and further SMP operations on this link is prohibited.