| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
BLE pairing message generation

BLE pairing messages contain information that tells a polling device how to pair with the device that contains the NFC tag through Bluetooth low energy. There are different types of messages depending on what devices are targeted and what kind of pairing is used. The message format is party based on the NFC Forum Application Document Bluetooth Secure Simple Pairing Using NFC, extended with non-standard messages that work with Windows Phone.

A BLE pairing message that works with Android devices contains one Bluetooth LE OOB record (see LE OOB records), which contains the BLE advertising data structure that is used to establish the connection. This message has the type NFC_BLE_PAIR_MSG_BLUETOOTH_LE_SHORT.

A non-standard BLE pairing message that works with Windows Phone devices contains one Bluetooth EP OOB record (see EP OOB records). Note that this message does not comply to the Bluetooth Secure Simple Pairing Using NFC document and Bluetooth EP OOB records are usually used for classic Bluetooth handover. The record contains the BLE advertising data structure that is used to establish the connection. This message has the type NFC_BLE_PAIR_MSG_BLUETOOTH_EP_SHORT.

A full BLE pairing message that works with both Android and Windows Phone devices contains one Bluetooth LE OOB record, one non-standard Bluetooth EP OOB record, and one Handover Select record (see Hs (Handover Select) records), which contains two Alternative Carrier records (see ac (Alternative carrier) records) that point to the two other records. This message is called a Handover Select Message and has the type NFC_BLE_PAIR_MSG_FULL.

Structure of a Handover Select Message

Each BLE pairing messages can be generated in two variants: using Just Works pairing (the default) or Out-of-Band pairing. Out-of-Band pairing requires a random Temporary Key, while Just Works pairing does not use any authentication key.

The LE OOB records, EP OOB records, and Hs (Handover Select) records modules provide functions for creating the records, and the BLE pairing messages module provides functions for creating and encoding the messages. Additionally, the LE OOB and the EP OOB records use the Advertising and Scan Response Data Encoder for NFC OOB pairing module to create their payload.

The following code snippet shows how to define appropriate parameters for Out-of-Band pairing:

#define SEC_PARAM_BOND 1 /**< Perform bonding. */
#define SEC_PARAM_LESC 0 /**< LE Secure Connections not enabled. */
#define SEC_PARAM_KEYPRESS 0 /**< Keypress notifications not enabled. */
#define SEC_PARAM_IO_CAPABILITIES BLE_GAP_IO_CAPS_NONE /**< No I/O capabilities. */
#define SEC_PARAM_OOB 1 /**< Out Of Band data available. */
#define SEC_PARAM_MITM 1 /**< Man In The Middle protection supported (via OOB). */
// Hardcoded authentication OOB key
// In this example, this value is constant. However, to be compatible with
// the BLE Core Specification for OOB pairing, generate a random value for the Temporary Key.
#define OOB_AUTH_KEY { \
{ \
0xAA, 0xBB, 0xCC, 0xDD, \
0xEE, 0xFF, 0x99, 0x88, \
0x77, 0x66, 0x55, 0x44, \
0x33, 0x22, 0x11, 0x00 \
} \
}
static ble_advdata_tk_value_t m_oob_auth_key = OOB_AUTH_KEY;

Next, generate the BLE pairing message. The following code snippet shows how to create a message for both Android and Windows Phone devices (thus of type NFC_BLE_PAIR_MSG_FULL), using either Just Works or Out-of-Band pairing:

/* Provide information about available buffer size to encoding function. */
uint32_t ndef_msg_len = sizeof(m_ndef_msg_buf);
/* Encode BLE pairing message into the buffer. */
err_code = nfc_ble_pair_default_msg_encode(NFC_BLE_PAIR_MSG_FULL,
&m_oob_auth_key,
m_ndef_msg_buf,
&ndef_msg_len);
APP_ERROR_CHECK(err_code);

Note that Just Works pairing using NFC can be distinguished from Out-of-Band pairing by passing NULL to the encoding function, instead of a Temporary Key. In addition, the security parameters must be set differently for Just Works pairing (see the first code snippet).