nRF5 SDK v13.0.0
Modules | Enumerations | Functions
BLE pairing messages

Generation of NFC NDEF messages used for BLE pairing. More...

Modules

 Alternative Carrier records parser
 Functions for parsing and decoding Alternative Carrier records.
 
 Advertising and Scan Response Data Parser for NFC OOB pairing
 Functions for parsing and decoding data in the Advertising and Scan Response Data format for NFC OOB pairing.
 
 LE OOB records parser
 Functions for parsing and decoding LE OOB records.
 
 ac (Alternative carrier) records
 Generation of NFC NDEF Alternative Carrier records for NDEF messages.
 
 Advertising and Scan Response Data Encoder for NFC OOB pairing
 Function for encoding data in the Advertising and Scan Response Data format, which can be used to create payload of NFC message intended for initiating the Out-of-Band pairing.
 
 EP OOB records
 Generation of NFC NDEF EP OOB records for NDEF messages.
 
 Hs (Handover Select) records
 Generation of NFC NDEF Handover Select records for NDEF messages.
 
 LE OOB records
 Generation of NFC NDEF LE OOB records for NDEF messages.
 

Enumerations

enum  nfc_ble_pair_type_t {
  NFC_BLE_PAIR_MSG_BLUETOOTH_LE_SHORT,
  NFC_BLE_PAIR_MSG_BLUETOOTH_EP_SHORT,
  NFC_BLE_PAIR_MSG_FULL
}
 Types of BLE pairing message. More...
 

Functions

ret_code_t nfc_ble_simplified_le_oob_msg_encode (ble_advdata_t const *const p_le_advdata, uint8_t *p_buf, uint32_t *p_len)
 Function for encoding simplified LE OOB messages. More...
 
ret_code_t nfc_ble_simplified_ep_oob_msg_encode (ble_advdata_t const *const p_ep_advdata, uint8_t *p_buf, uint32_t *p_len)
 Function for encoding simplified EP OOB messages. More...
 
ret_code_t nfc_ble_full_handover_select_msg_encode (ble_advdata_t const *const p_le_advdata, ble_advdata_t const *const p_ep_advdata, uint8_t *p_buf, uint32_t *p_len)
 Function for encoding BLE Handover Select Messages. More...
 
ret_code_t nfc_ble_pair_default_msg_encode (nfc_ble_pair_type_t nfc_ble_pair_type, ble_advdata_tk_value_t *const p_tk_value, ble_gap_lesc_oob_data_t *const p_lesc_data, uint8_t *p_buf, uint32_t *p_len)
 Function for encoding any type of BLE pairing messages with default BLE advertising data structures. More...
 
ret_code_t nfc_ble_pair_msg_updatable_tk_encode (nfc_ble_pair_type_t nfc_ble_pair_type, ble_advdata_tk_value_t *const p_tk_value, ble_gap_lesc_oob_data_t *const p_lesc_data, uint8_t *p_buf, uint32_t *p_len, uint8_t **pp_tk_group, uint8_t max_group_size)
 Function for encoding any type of BLE pairing messages with default BLE advertising data structures and with TK modifier feature. More...
 
ret_code_t nfc_tk_group_modifier_update (ble_advdata_tk_value_t *p_tk_value)
 Function for updating the Connection Handover NDEF message with new TK value. More...
 
ret_code_t nfc_tk_to_group_add (uint8_t *p_tk_location)
 Function for adding new location of TK value to the location description structure. More...
 
ret_code_t nfc_lesc_data_update (ble_gap_lesc_oob_data_t *ble_lesc_oob_data)
 Function for updating the Connection Handover NDEF message with a new LESC OOB values. More...
 
ret_code_t nfc_lesc_pos_set (uint8_t *p_confirm, uint8_t *p_random)
 Function for storing pointers to the LESC OOB data inside NDEF message. More...
 

Detailed Description

Generation of NFC NDEF messages used for BLE pairing.

Enumeration Type Documentation

Types of BLE pairing message.

Use one of these values to choose the type of NDEF BLE pairing message.

Enumerator
NFC_BLE_PAIR_MSG_BLUETOOTH_LE_SHORT 

Simplified LE OOB message.

NFC_BLE_PAIR_MSG_BLUETOOTH_EP_SHORT 

Simplified EP OOB message.

NFC_BLE_PAIR_MSG_FULL 

BLE Handover Select Message.

Function Documentation

ret_code_t nfc_ble_full_handover_select_msg_encode ( ble_advdata_t const *const  p_le_advdata,
ble_advdata_t const *const  p_ep_advdata,
uint8_t *  p_buf,
uint32_t *  p_len 
)

Function for encoding BLE Handover Select Messages.

This function encodes a BLE Handover Select Message into a buffer. The payload of the LE OOB record and the EP OOB record inside the message can be configured via the advertising data structures.

This function was implemented partially according to "Bluetooth Secure Simple Pairing Using NFC" (denotation "NFCForum-AD-BTSSP_1_1" published on 2014-01-09) chapters 3.1, 3.2, 4.1.1 and 4.1.2 (combined), and according to "Supplement to the Bluetooth Core Specification" (Version 5, adoption date: Dec 02 2014).

Note
To be able to encode the message, a SoftDevice must be enabled and configured.
Parameters
[in]p_le_advdataPointer to the BLE advertising data structure for the LE OOB record.
[in]p_ep_advdataPointer to the BLE advertising data structure for the EP OOB record.
[out]p_bufPointer to the buffer for the message.
[in,out]p_lenSize of the available memory for the message as input. Size of the generated message as output.
Return values
NRF_SUCCESSIf the function completed successfully.
NRF_ERROR_xxxIf an error occurred.
ret_code_t nfc_ble_pair_default_msg_encode ( nfc_ble_pair_type_t  nfc_ble_pair_type,
ble_advdata_tk_value_t *const  p_tk_value,
ble_gap_lesc_oob_data_t *const  p_lesc_data,
uint8_t *  p_buf,
uint32_t *  p_len 
)

Function for encoding any type of BLE pairing messages with default BLE advertising data structures.

This function encodes a BLE pairing message into a buffer. The message can be encoded as one of the three message types (using nfc_ble_simplified_le_oob_msg_encode, nfc_ble_simplified_ep_oob_msg_encode, or nfc_ble_full_handover_select_msg_encode), according to the nfc_ble_pair_type parameter. LE and EP OOB records use the default advertising data structure configuration. Only one field ('Security Manager TK') in the BLE advertising data can be configured for both records by specifying the p_tk_value parameter.

For LE OOB records, the default BLE advertising data structure configuration fills the required fields 'LE Bluetooth Device Address' and 'LE Role' and the optional fields 'Appearance', 'Local Name', and 'Flags'.

For EP OOB records, the default BLE advertising data structure configuration fills the required field 'Security Manager Out Of Band Flags' and the optional fields 'Appearance', 'Local Name', and 'Flags'.

Note
To be able to encode the message, a SoftDevice must be enabled and configured.
Parameters
[in]nfc_ble_pair_typeType of BLE pairing message.
[in]p_tk_valuePointer to the authentication Temporary Key (TK). If NULL, TK value field is not encoded in the NDEF message.
[in]p_lesc_dataPointer to the LESC OOB data. If NULL, LESC OOB fields are not encoded in the NDEF message.
[out]p_bufPointer to the buffer for the message.
[in,out]p_lenSize of the available memory for the message as input. Size of the generated message as output.
Return values
NRF_SUCCESSIf the function completed successfully.
NRF_ERROR_xxxIf an error occurred.
ret_code_t nfc_ble_pair_msg_updatable_tk_encode ( nfc_ble_pair_type_t  nfc_ble_pair_type,
ble_advdata_tk_value_t *const  p_tk_value,
ble_gap_lesc_oob_data_t *const  p_lesc_data,
uint8_t *  p_buf,
uint32_t *  p_len,
uint8_t **  pp_tk_group,
uint8_t  max_group_size 
)

Function for encoding any type of BLE pairing messages with default BLE advertising data structures and with TK modifier feature.

    This function is very similar to @ref nfc_ble_pair_default_msg_encode function, but
    additionaly it enables to track TK locations which were encoded in Connection Handover
    NDEF message. After using this function, you can update TK value in NDEF by calling
    @ref nfc_tk_group_modifier_update.
Parameters
[in]nfc_ble_pair_typeType of BLE pairing message.
[in]p_tk_valuePointer to the authentication Temporary Key (TK). If NULL, TK value field is not encoded in the NDEF message.
[in]p_lesc_dataPointer to the LESC OOB data. If NULL, LESC OOB values are not encoded in the NDEF message.
[out]p_bufPointer to the buffer for the message.
[in,out]p_lenSize of the available memory for the message as input. Size of the generated message as output.
[in]pp_tk_groupPointer to array of TK locations that should be modified with nfc_tk_group_modifier_update function.
[in]max_group_sizeMaximal number of TK locations that can added to pp_tk_group.
Return values
NRF_SUCCESSIf the function completed successfully.
NRF_ERROR_xxxIf an error occurred.
ret_code_t nfc_ble_simplified_ep_oob_msg_encode ( ble_advdata_t const *const  p_ep_advdata,
uint8_t *  p_buf,
uint32_t *  p_len 
)

Function for encoding simplified EP OOB messages.

This function encodes a simplified EP OOB message into a buffer. The payload of the EP OOB record inside the message can be configured via the advertising data structure.

This function was implemented partially according to "Bluetooth Secure Simple Pairing Using NFC" (denotation "NFCForum-AD-BTSSP_1_1" published on 2014-01-09) chapters 3.1, 3.2, 4.3.1, and according to "Supplement to the Bluetooth Core Specification" (Version 5, adoption date: Dec 02 2014).

Note
To be able to encode the message, a SoftDevice must be enabled and configured.
Parameters
[in]p_ep_advdataPointer to the BLE advertising data structure for the EP OOB record.
[out]p_bufPointer to the buffer for the message.
[in,out]p_lenSize of the available memory for the message as input. Size of the generated message as output.
Return values
NRF_SUCCESSIf the function completed successfully.
NRF_ERROR_xxxIf an error occurred.
ret_code_t nfc_ble_simplified_le_oob_msg_encode ( ble_advdata_t const *const  p_le_advdata,
uint8_t *  p_buf,
uint32_t *  p_len 
)

Function for encoding simplified LE OOB messages.

This function encodes a simplified LE OOB message into a buffer. The payload of the LE OOB record inside the message can be configured via the advertising data structure.

This function was implemented partially according to "Bluetooth Secure Simple Pairing Using NFC" (denotation "NFCForum-AD-BTSSP_1_1" published on 2014-01-09) chapters 3.1, 3.2, 4.3.2, and according to "Supplement to the Bluetooth Core Specification" (Version 5, adoption date: Dec 02 2014).

Note
To be able to encode the message, a SoftDevice must be enabled and configured.
Parameters
[in]p_le_advdataPointer to the BLE advertising data structure for the LE OOB record.
[out]p_bufPointer to the buffer for the message.
[in,out]p_lenSize of the available memory for the message as input. Size of the generated message as output.
Return values
NRF_SUCCESSIf the function completed successfully.
NRF_ERROR_xxxIf an error occurred.
ret_code_t nfc_lesc_data_update ( ble_gap_lesc_oob_data_t ble_lesc_oob_data)

Function for updating the Connection Handover NDEF message with a new LESC OOB values.

Updates LESC Confirmation and Random Values based on its locations set by the nfc_lesc_pos_set function.

Parameters
[in]ble_lesc_oob_dataPointer to the new LESC OOB data. The NDEF message will be updated with this data.
Return values
NRF_SUCCESSIf the operation was successful.
NRF_ERROR_NULLIf pointer to the new LESC OOB data is NULL.
NRF_ERROR_INVALID_STATEIf pointer to the LESC OOB data location in NDEF message is NULL.
ret_code_t nfc_lesc_pos_set ( uint8_t *  p_confirm,
uint8_t *  p_random 
)

Function for storing pointers to the LESC OOB data inside NDEF message.

It allows LESC OOB data update without regenerating entire CH NDEF message.

Parameters
[in]p_confirmPointer to the LESC Confirmation Value position in the NDEF message.
[in]p_randomPointer to the LESC Random Value position in the NDEF message.
Return values
NRF_SUCCESSIf the operation was successful.
NRF_ERROR_NULLIf either of pointers is set to NULL.
ret_code_t nfc_tk_group_modifier_update ( ble_advdata_tk_value_t p_tk_value)

Function for updating the Connection Handover NDEF message with new TK value.

This function updates NDEF message with new TK value. This update is applied to all of TK locations in the Connection Handover NDEF message. This function can only be used after calling nfc_ble_pair_msg_updatable_tk_encode, which is used to encode Connection Handover NDEF message.

Parameters
[in]p_tk_valuePointer to the new TK value. The NDEF message will be updated with this value.
Return values
NRF_SUCCESSIf the operation was successful.
NRF_ERROR_NULLIf pointer to TK locations was NULL.
ret_code_t nfc_tk_to_group_add ( uint8_t *  p_tk_location)

Function for adding new location of TK value to the location description structure.

Parameters
[in]p_tk_locationNew location of TK value in the Connection Handover NDEF message.
Return values
NRF_SUCCESSIf the operation was successful or if buffer used for holding TK locations is NULL.
NRF_ERROR_NO_MEMIf there is no place in the buffer for the new TK value location.

Documentation feedback | Developer Zone | Subscribe | Updated