Security APIs

This group includes security APIs.

Functions
at_ble_status_t	at_ble_authenticate (at_ble_handle_t conn_handle, at_ble_pair_features_t *features, at_ble_LTK_t *ltk, at_ble_CSRK_t *csrk)
	Starts Pairing procedure for a given connection. More...
at_ble_status_t	at_ble_encryption_request_reply (at_ble_handle_t conn_handle, at_ble_auth_t auth, bool key_found, at_ble_LTK_t *key)
	Responds to encryption start request from master device AT_BLE_ENCRYPTION_REQUEST, once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered. More...
at_ble_status_t	at_ble_encryption_start (at_ble_handle_t conn_handle, at_ble_LTK_t *key, at_ble_auth_t auth)
	Starts encryption, once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered. More...
at_ble_status_t	at_ble_pair_key_reply (at_ble_handle_t conn_handle, at_ble_pair_key_type_t type, uint8_t *key)
	Provides a passkey or OOB data that was requested via AT_BLE_PAIR_KEY_REQUEST event, If key type is AT_BLE_PAIR_PASSKEY, then a 6-byte ASCII string (digit 0..9 only). More...
at_ble_status_t	at_ble_send_sec_config (at_ble_signature_info_t *signature_info, at_ble_auth_t authen, bool service_changed)
	Set specific link security configuration and bonding data. More...
at_ble_status_t	at_ble_send_slave_sec_request (at_ble_handle_t conn_handle, bool mitm_protection, bool bond)
	Send slave security request to master. More...

at_ble_status_t at_ble_authenticate	(	at_ble_handle_t	conn_handle,
		at_ble_pair_features_t *	features,
		at_ble_LTK_t *	ltk,
		at_ble_CSRK_t *	csrk
	)

Starts Pairing procedure for a given connection.

This API will initiate the authentication procedure, given local device requirements and IO capabilities the authentication will proceed in a number of ways, progress is monitored and controlled via the events : AT_BLE_PAIR_KEY_REQUEST ,AT_BLE_PAIR_DONE

In the central role, this function will send an SMP Pairing Request, otherwise in the peripheral role, this function will reply to AT_BLE_PAIR_REQUEST.

Note

• The authentication procedure with this API shall only be initiated after a connection has been established in master mode or as a response in case of receiving AT_BLE_PAIR_REQUEST event in slave mode.
• Bonding information(information exchanged during pairing)such as key, authentication level should be stored by application in order to be reused during another connection at_ble_send_sec_config .
• If the device acts as a master, so initiator_keys is the device itself and responder_keys for peer and in case of acting as a slave, responder_keys for the device itself and initiator_keys for peer.
• According to IO capabilities or Out Of Band (OOB), if it is possible to perform a pairing using PIN code or OOB data then AT_BLE_PAIR_KEY_REQUEST event will be received by application.
• If no security message is exchange during more than 30s, bonding procedure is cancelled and no new bond procedure can be started for this link. For your security and in case of a timeout error, it is optional for the application to disconnect the current connection.

Parameters

[in]	conn_handle	handle of the ongoing connection
[in]	features	local device requirements and IO capabilities, should be NULL to reject the pairing request in case of pairing as SLAVE connection ONLY.
[in]	ltk	Local device Long Term Key, null if not available
[in]	csrk	Local device Connection Signature Resolution Key, null if not available

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t.

This API will initiate the authentication procedure, given local device requirements and IO capabilities the authentication will proceed in a number of ways, progress is monitored and controlled via the events : AT_BLE_PAIR_KEY_REQUEST ,AT_BLE_PAIR_DONE

In the central role, this function will send an SMP Pairing Request, otherwise in the peripheral role, this function will reply to AT_BLE_PAIR_REQUEST.

Note

• Bonding information(information exchanged during pairing)such as key , authentication level should be stored by application in order to be reused during another connection
• According to IO capabilities or Out Of Band (OOB), if it is possible to perform a pairing using PIN code or OOB data then AT_BLE_PAIR_KEY_REQUEST event will be received by application.

Parameters

[in]	conn_handle	Handle of the ongoing connection
[in]	features	Local device requirements and IO capabilities
[in]	ltk	Local device Long Term Key, null if not available
[in]	csrk	Local device Connection Signature Resolution Key , null if not available

Returns

AT_BLE_SUCCESS Operation programmed successfully

AT_BLE_FAILURE Generic error

References AT_BLE_FAILURE, AT_BLE_INVALID_PARAM, AT_BLE_KEY_DIST_ENC, AT_BLE_KEY_DIST_SIGN, at_ble_pair_features_t::bond, device_info::csrk, at_ble_pair_features_t::desired_auth, device, GAP_AUTH_REQ_MITM_BOND, GAP_AUTH_REQ_MITM_NO_BOND, GAP_AUTH_REQ_NO_MITM_BOND, GAP_AUTH_REQ_NO_MITM_NO_BOND, gapc_bond_cfm_handler_pair_resp(), gapc_bond_cmd_handler(), at_ble_pair_features_t::initiator_keys, at_ble_pair_features_t::io_capabilities, device_info::ltk, at_ble_pair_features_t::max_key_size, at_ble_pair_features_t::mitm_protection, NULL, at_ble_pair_features_t::oob_available, at_ble_pair_features_t::responder_keys, device_info::role, ROLE_MASTER, ROLE_SLAVE, and status.

at_ble_status_t at_ble_encryption_request_reply	(	at_ble_handle_t	conn_handle,
		at_ble_auth_t	auth,
		bool	key_found,
		at_ble_LTK_t *	key
	)

Responds to encryption start request from master device AT_BLE_ENCRYPTION_REQUEST, once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered.

Parameters

[in]	conn_handle	handle of the connection to be updated
[in]	key_found	If true then a valid key is found in device database and will be used
[in]	auth	authentication level
[in]	key	LTK key used for encryption

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Responds to encryption start request from master device AT_BLE_ENCRYPTION_REQUEST, once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered.

Parameters

[in]	conn_handle	Handle of the connection to be updated
[in]	key_found	If true then a valid key is found in device database and will be used
[in]	auth	Authentication level
[in]	key	LTK key used for encryption

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

References AT_BLE_FAILURE, gapc_encrypt_cfm_handler(), at_ble_LTK_t::key, at_ble_LTK_t::key_size, and NULL.

at_ble_status_t at_ble_encryption_start	(	at_ble_handle_t	conn_handle,
		at_ble_LTK_t *	key,
		at_ble_auth_t	auth
	)

Starts encryption, once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered.

Parameters

[in]	conn_handle	handle of the connection to be updated
[in]	key	LTK key used for encryption
[in]	auth	authentication level , this information must be stored in device database after each pairing process at_ble_pair_done_t

Note

• This procedure can be initiated only by master of the connection.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Parameters

[in]	conn_handle	Handle of the connection to be updated
[in]	key	LTK key used for encryption
[in]	auth	Authentication level , this information must be stored in device database after each pairing process at_ble_pair_done_t

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

References AT_BLE_FAILURE, at_ble_LTK_t::ediv, gapc_encrypt_cmd_handler(), at_ble_LTK_t::key, at_ble_LTK_t::key_size, at_ble_LTK_t::nb, and NULL.

at_ble_status_t at_ble_pair_key_reply	(	at_ble_handle_t	conn_handle,
		at_ble_pair_key_type_t	type,
		uint8_t *	key
	)

Provides a passkey or OOB data that was requested via AT_BLE_PAIR_KEY_REQUEST event, If key type is AT_BLE_PAIR_PASSKEY, then a 6-byte ASCII string (digit 0..9 only).

If key type is AT_BLE_PAIR_OOB , then a 16-byte OOB key value in Little Endian format

Parameters

[in]	conn_handle	handle of the ongoing connection
[in]	type	type of requested key, must match the one asked for in AT_BLE_PAIR_KEY_REQUEST
[in]	key	the key requested, should be NULL to reject the pairing TK exchange and terminate pairing procedure.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t.

If key type is AT_BLE_PAIR_OOB , then a 16-byte OOB key value in Little Endian format

Parameters

[in]	conn_handle	Handle of the ongoing connection
[in]	type	Type of requested key, must match the one asked for in AT_BLE_PAIR_KEY_REQUEST
[in]	key	The key requested

Returns

AT_BLE_SUCCESS Operation programmed successfully

AT_BLE_FAILURE Generic error

References AT_BLE_FAILURE, AT_BLE_PAIR_OOB, AT_BLE_PAIR_PASSKEY, AT_BLE_PASSKEY_LEN, gapc_bond_cfm_handler_key_exch(), GAPC_TK_EXCH, i, KEY_LEN, and NULL.

at_ble_status_t at_ble_send_sec_config	(	at_ble_signature_info_t *	signature_info,
		at_ble_auth_t	authen,
		bool	service_changed
	)

Set specific link security configuration and bonding data.

Parameters

[in]	signature_info	signature_info, more info at at_ble_signature_info_t
[in]	authen	Authentication value, one of at_ble_auth_t
[in]	service_changed	Service Changed Indication enabled

Note

• This function must be called before signed write operation to exchange CSR Keys first.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

at_ble_status_t at_ble_send_slave_sec_request	(	at_ble_handle_t	conn_handle,
		bool	mitm_protection,
		bool	bond
	)

Send slave security request to master.

Parameters

[in]	conn_handle	handle of the ongoing connection
[in]	mitm_protection	Boolean value for Man-In-The-Middle protection FALSE -> Disable, TRUE -> Enable
[in]	bond

Note

• This function should be called in slave mode only to notify master to initiate a security request. In this case, the application should receive AT_BLE_SLAVE_SEC_REQUEST and send at_ble_authenticate.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t.

Parameters

[in]	conn_handle	Handle of the ongoing connection
[in]	mitm_protection	Boolean value for Man-In-The-Middle protection 0 -> Disable, 1 -> Enable
[in]	bond	Boolean value for bonding 0 -> Disable, 1 -> Enable

Returns

AT_BLE_SUCCESS Operation programmed successfully

AT_BLE_FAILURE Generic error

References GAP_AUTH_REQ_MITM_BOND, GAP_AUTH_REQ_MITM_NO_BOND, GAP_AUTH_REQ_NO_MITM_BOND, GAP_AUTH_REQ_NO_MITM_NO_BOND, and gapc_security_cmd_handler().