GAP Bond Manager and LE Secure Connections¶
The GAP Bond Manager (GAPBondMgr) is a configurable module that offloads most of the Pairing & Bonding security mechanisms associated with the Security Manager (SM) protocol from the application. The GAPBongMgr executes in the protocol stack task’s context. Table 6. lists the terminology.
Term | Description |
Pairing | The process of generating & exchanging keys. Not to be confused with forming or establishing a BLE connection between two devices |
Encryption | Data is encrypted after pairing, or re-encryption (a subsequent connection where keys are looked up from nonvolatile memory). |
Association | The pairing method used based on the I/O Capabilities of both devices. For LE devices, Just Works, Numeric Comparison, Passkey Entry and Out-Of-Band are supported. |
Authentication | The pairing process using an association method that supports MITM (Man in the Middle) protection. |
Bonding | Storing the keys generated during the pairing process in nonvolatile memory to use for the next encryption sequence. |
Authorization | An additional application level verification in addition to authentication. |
OOB | Out of Band. Pairing keys are not exchanged over the air, but rather over some other source such as serial port or NFC. This also provides MITM protection. |
MITM | Man in the Middle protection. MITM provides authentication during the pairing process which helps prevent a malicious attacker from impersonating the peer device during the key exchange. |
Just Works | Unauthenticated pairing association method where keys are exchanged without MITM protection. |
The general process that the GAPBondMgr uses is as follows:
1. The pairing process: exchange keys through the methods described in Selection of Pairing Method.
- The encryption process: Encrypt the link using keys Step 1.
3. The bonding process: store keys in secure flash (Simple Non Volatile memory, SNV).
- Reconnecting: Use the keys stored in SNV to encrypt the link.
Tip
Performing all of these steps is not necessary. For example, two devices may choose to pair but not bond.
Selection of Pairing Method¶
Bluetooth Core Specification Version 4.2 added support for the LE Secure Connections feature to enable additional strength to the BLE pairing process. For a detailed description of the algorithms used for LE Secure Connections, see the Security Architecture section ([Vol 1], Part A, Section 5.1) of the Bluetooth Core Specification Version 5.1. The previous pairing methods used in the Bluetooth Core Specification Versions 4.1 and 4.0 are still available, and are now defined as LE Legacy Pairing. The main difference is that Secure Connection uses Elliptic Curve Diffie-Hellman (ECDH) cryptography, while LE Legacy Pairing does not.
There are four types of pairing methods which are referred to as “Association Models” in the core specification. Each pairing method is described in detail in GAPBondMgr Examples for Different Pairing Methods.
- Just Works (LE Secure Connections or LE Legacy)
- Passkey Entry (LE Secure Connections or LE Legacy)
- Numeric Comparison (LE Secure Connections)
- Out Of Band (LE Secure Connections or LE Legacy)
Which pairing method is selected, and whether or not pairing will succeed depends on the following parameters from both peer devices during the pairing process:
- Out Of Band (OOB) set / not set
- Man In The Middle (MITM) set / not set
- Input/Output (IO) Capabilities
- LE Secure Connections supported / not supported
The GAPBondMgr parameters, as they map to the table parameters below are listed here. For more information on these parameters, see BLE Stack API Reference (GAPBondMgr section).
GAPBOND_OOB_ENABLED: Out of band (OOB) set / not set
GAPBOND_MITM_PROTECTION: Man in the middle (MITM) set / not set
GAPBOND_IO_CAPABILITIES: Input/Output (IO) Capabilities
GAPBOND_SECURE_CONNECTION: LE Secure connections supported / not supported
Beyond what the Bluetooth Core Specification Version 5.1 defines, this parameter also affects whether or not pairing succeeds, as described in BLE Stack API Reference (GAPBondMgr section).
The tables below are from the Selecting Key Generation Method section ([Vol 3], Part H, Section 2.3.5.1) of the Bluetooth Core Specification Version 5.1. Use these tables to determine which pairing mode is selected for any set of parameters.
If both devices support LE Secure Connections, use Figure 67. to decide upon the next step.
If at least one device does not support LE Secure Connections, use Figure 68. to decide upon the next step.
If, based on one of the previous tables, IO capabilities are to be used to determine the association model, use Figure 69.
Using GAPBondMgr¶
This section describes what the application must do to configure, start, and use
the GAPBondMgr. The GAPBondMgr is defined in gapbondmgr.c
and gapbondmgr.h
.
BLE Stack API Reference (GAPBondMgr section) describes the full API including
commands, configurable parameters, events, and callbacks.
The general steps to use the GAPBondMgr module are as follows:
1. Configure the stack to include GAPBondMgr functionality by defining the
following in build_config.opt
in the stack project:
-DGAP_BOND_MGR
2. The stack must also be configured to use OSAL_SNV, by ensuring that NO_OSAL_SNV is not defined.
3. If using LE Secure Connections, the PDU size must be >= 69. This can be set by
defining the following preprocessor symbol in the application
project: MAX_PDU_SIZE=69
. Also, the minimum heap size that can be used with
LE Secure Connections is 3690. (See Dynamic Memory Allocation for heap size
management.)
4. Configure the GAPBondMgr by initializing its parameters as desired. GAPBondMgr configuration parameters are not persistent and must be configured after the device is reset. See BLE Stack API Reference (GAPBondMgr section) for a complete list of parameters with functionality described. There are examples of this for the various pairing/bonding modes in GAPBondMgr Examples for Different Pairing Methods.
5. Register application callbacks with the GAPBondMgr, so that the application can communicate with the GAPBondMgr and be notified of events.
// Register with bond manager after starting device GAPBondMgr_Register(&bondmanager_callbacks);
Here bondmanager_callbacks
is defined as a structure containing the
GAPBondMgr Callbacks. A passcode callback function is mandatory.
// Bond Manager Callbacks static gapBondCBs_t bondMgrCBs = { SimpleCentral_passcodeCb, // Passcode callback SimpleCentral_pairStateCb // Pairing/Bonding state Callback };
6. Once the GAPBondMgr is configured, it operates mostly autonomously from the perspective of the application. When a connection is established, the GAPBondMgr manages pairing and bonding depending on the configuration parameters set during initialization. It also communicates with the application as needed through the defined callbacks.
A few parameters can be set and functions can be called asynchronously at any time from the application. See BLE Stack API Reference (GAPBondMgr section) for more information.
Most communication between the GAPBondMgr and the application at this point occurs through the callbacks which were registered in Step 5. Figure 70. is a flow diagram example of the GAPBondMgr notifying the application that pairing has been completed. The same method occurs for various other events and will be expanded upon in the following section.
GAPBondMgr Examples for Different Pairing Methods¶
This section provides message diagrams for the types of security that can be implemented. These modes assume acceptable I/O capabilities are available for the security mode, and that the selection of whether or not to support LE Secure Connections allows for the pairing method. See the Selection of Pairing Method on how these parameters affect pairing. These examples only consider the pairing aspect. Bonding can be added to each type of pairing in the same manner and is shown in the next section.
Caution
The code snippets here are not complete functioning examples, and are only intended for illustration purposes.
Disabling Pairing¶
With pairing mode set to GAPBOND_PAIRING_MODE_NO_PAIRING
, the BLE stack
automatically rejects any attempt at pairing.
Configure the GAPBondMgr as follows to disable pairing:
// Pairing is not allowed
uint8_t pairMode = GAPBOND_PAIRING_MODE_NO_PAIRING;
GAPBondMgr_SetParameter(GAPBOND_PAIRING_MODE, sizeof(uint8_t), &pairMode);
Enabling Pairing¶
To start or allow the pairing process after a connection is formed, the GAPBondMgr can be
configured to automatically request pairing or wait for pairing request from the
peer device. The actual behavior depends on the device’s GAP role (Central or Peripheral)
and the setting of the GAPBondMgr pairing mode (GAPBOND_PAIRING_MODE
).
To initiate the pairing process on Peripheral role devices, GAPBOND_PAIRING_MODE_INITIATE
will
send a Slave Security Request shortly after the GAPBondMgr is informed that the connection is formed.
For Central role devices, GAPBOND_PAIRING_MODE_INITIATE
will send a Pairing Request or request
the Link Layer to encrypt the link if the device has previously paired/bonded:
// Initiate pairing request
uint8_t pairMode = GAPBOND_PAIRING_MODE_INITIATE;
GAPBondMgr_SetParameter(GAPBOND_PAIRING_MODE, sizeof(uint8_t), &pairMode);
The Peripheral can be configured to wait for a Pairing Request from the Central when the pairing mode
is set to GAPBOND_PAIRING_MODE_WAIT_FOR_REQ
. When this pairing mode is selected, the GAPBondMgr will
automatically respond with a Pairing Response based on other GAPBondMgr configured parameters.
// Wait for a pairing request
uint8_t pairMode = GAPBOND_PAIRING_MODE_WAIT_FOR_REQ;
GAPBondMgr_SetParameter(GAPBOND_PAIRING_MODE, sizeof(uint8_t), &pairMode);
Tip
When pairing with smartphone Central devices, it is recommended to use GAPBOND_PAIRING_MODE_WAIT_FOR_REQ
as undefined behavior may occur when a Slave Security Request is sent by the Peripheral. Both iOS
and Android will initiate pairing when the peripheral responds with an Insufficient Authentication error
response when a GATT secure characteristic is accessed.
LE Secure Connections¶
LE Secure Connections is enabled by default in BLE5-Stack. If you don’t want to use
LE Secure Connections, set the GAPBOND_SECURE_CONNECTION
variable
to GAPBOND_SECURE_CONNECTION_NONE
during the GAPBondMgr initialization.
uint8_t gapbondSecure = GAPBOND_SECURE_CONNECTION_NONE;
GAPBondMgr_SetParameter(GAPBOND_SECURE_CONNECTION, sizeof(uint8_t), &gapbondSecure);
It is important when trying to decipher over-the-air sniffer logs with LE Secure
Connections enabled, you need to use a specific “debug” key as defined by Vol 3
Part H section 2.3.5.6.1 of the Bluetooth Core Specification Version 5.1. In the BLE5-Stack, this key is
enabled when the GAPBondMgr has SC_HOST_DEBUG
defined in the app project.
When either the initiating or non-initiating device uses this specific debug
key, it enables over-the-air sniffer equipment that supports LE Secure Connections to
determine the LTK and therefore monitor/decrypt encrypted traffic throughout
the connection.
LESC Limitations & Recommendations¶
LE Secure Connections uses an ECDH public-private key pair as part of the pairing process. See Selection of Pairing Method and the LE Secure Connections Pairing Phase 2 section of the Bluetooth Core Specification Version 5.1 for more information about how these keys and how they are used in the pairing process.
To summarize, as part of LESC pairing Phase 1 each device will generate its own ECDH public-private key pair. As part of LESC pairing Phase 2 each device will compute the Diffie-Hellman (DH) Key based on the public keys that are exchanged.
ECC public-private and DH key generation is implemented in the ROM software on the CC2640R2. These routines are blocking by nature and take around 160ms to execute. During LESC pairing, the ECC ROM will be accessed twice by the link layer (LL) once to generate the public/private key pair and again to generate the DH key. This means the user task and other OSAL tasks within the stack task will be blocked for around 160ms twice during pairing.
Because of this, TI recommends the following when using LESC:
- Supervision timeout >= 165ms
- Expect/design for at least 160ms of app and stack blocking during LESC pairing
To alleviate the amount of blocking required, the user application can generate the public-private key pair ahead of the pairing process, or it can define when the keys should be recycled by using the following parameters of the GapBondMgr. These options are mutually exclusive, as generation of keys by the application bypasses the recycle parameter. To truly minimize the affect of ECC on the BLE connection, perform ECC before any connections are established.
Just Works Pairing¶
Just Works pairing allows encryption without man in the middle (MITM) authentication and is vulnerable to MITM attacks. Just Works pairing can be LE Legacy or LE Secure Connections pairing. The GAPBondMgr does not need any additional input from the application for Just Works pairing. Configure the GAPBondMgr for Just Works pairing as follows.
uint8_t mitm = FALSE;
GAPBondMgr_SetParameter( GAPBOND_MITM_PROTECTION, sizeof (uint8_t), &mitm);
Figure 71. describes the interaction between the GAPBondMgr and
the application for Just Works pairing. As shown, the application receives
a GAPBOND_PAIRING_STATE_STARTED
event once the pairing request has been sent,
and a GAPBOND_PAIRING_STATE_COMPLETE
event once the pairing process has been
completed. At this time, the link is encrypted.
Passcode Entry¶
Passkey entry is a type of authenticated pairing that can prevent man in the middle (MITM) attacks. It can be used with either LE Legacy pairing or Secure Connections pairing. In this pairing method, one device displays a 6-digit passcode, and the other device enters the passcode. As described in Selection of Pairing Method, the IO capabilities decide which device performs which role. The passcode callback registered with the GAPBondMgr when it was started is used to enter or display the passcode. The following is an example of initiating Passcode Entry pairing where the passcode is displayed.
- Define passcode callback
// Bond Manager Callbacks
static gapBondCBs_t bondMgrCBs =
{
SimpleCentral_passcodeCb, // Passcode callback
SimpleCentral_pairStateCb // Pairing/Bonding state Callback
};
/*********************************************************************
* @fn SimpleCentral_passcodeCb
*
* @brief Passcode callback.
*
* @return none
*/
static void SimpleCentral_passcodeCb(uint8_t *deviceAddr, uint16_t connHandle,
uint8_t uiInputs, uint8_t uiOutputs,
uint32_t numComparison)
{
uint8_t *pData;
// Allocate space for the passcode event.
if ((pData = ICall_malloc(sizeof(uint8_t))))
{
*pData = uiOutputs;
// Enqueue the event.
SimpleCentral_enqueueMsg(SC_EVT_PASSCODE_NEEDED, 0, pData);
}
}
- Configure GAPBondMgr
uint8_t pairMode = GAPBOND_PAIRING_MODE_INITIATE;
uint8_t mitm = TRUE;
GAPBondMgr_SetParameter(GAPBOND_PAIRING_MODE, sizeof(uint8_t), &pairMode);
GAPBondMgr_SetParameter(GAPBOND_MITM_PROTECTION, sizeof(uint8_t), &mitm);
- Process passcode callback and send the response to the stack.
//! BLE Default Passcode
#define B_APP_DEFAULT_PASSCODE 123456
/*********************************************************************
* @fn SimpleCentral_processPasscode
*
* @brief Process the Passcode request.
*
* @return none
*/
static void SimpleCentral_processPasscode(uint16_t connHandle,
uint8_t uiOutputs)
{
// Display passcode to user
if (uiOutputs != 0)
{
Display_printf(dispHandle, SC_ROW_CUR_CONN, 0, "Passcode: %d",
B_APP_DEFAULT_PASSCODE);
}
// Send passcode response
GAPBondMgr_PasscodeRsp(connHandle , SUCCESS, B_APP_DEFAULT_PASSCODE);
}
Depending on the uiInputs
and uiOutputs
returned from the GAPBondMgr,
the passcode must either be displayed or entered. The passcode is
then sent to the GAPBondMgr using GAPBondMgr_PasscodeRsp(), so that
pairing can continue. In this case, the password is statically set to 123456.
In a real product, the password will likely be randomly generated, and the
device must expose a way for the user to enter the passcode, then send it to the
GAPBondMgr using GAPBondMgr_PasscodeRsp(). An example interaction
between the GAPBondMgr and the application is shown in
Figure 72..
Numeric Comparison¶
Numeric comparison is a type of authenticated pairing that protects from MITM attacks. It is only possible as a LE Secure Connections pairing; not LE legacy. For numeric comparison pairing, both devices display a 6-digit code. Each device must then indicate, through a button press or some other Yes-No input, whether the codes match. The passcode callback registered with the GAPBondMgr when it was started is used to display the 6-digit code. The following is an example of initiating Numeric Comparison pairing where the passcode is displayed. The IO capabilities must be set appropriately to select numeric comparison (that is, Display/Yes-No on both sides).
- Define passcode callback to display code.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | // Bond Manager Callbacks
static gapBondCBs_t bondMgrCBs =
{
SimpleCentral_passcodeCb, // Passcode callback
SimpleCentral_pairStateCb // Pairing/Bonding state Callback
};
static void SimpleCentral_passcodeCb(uint8_t *deviceAddr, uint16_t connHandle, uint8_t uiInputs, uint8_t uiOutputs, uint32_t numComparison)
{
gapPasskeyNeededEvent_t *pData;
// Allocate space for the passcode event.
if ((pData = ICall_malloc(sizeof(gapPasskeyNeededEvent_t))))
{
memcpy(pData->deviceAddr, deviceAddr, B_ADDR_LEN);
pData->connectionHandle = connHandle;
pData->numComparison = numComparison;
// Enqueue the event.
SimpleCentral_enqueueMsg(SC_EVT_PASSCODE_NEEDED, 0, pData);
|
- Configure GAPBondMgr
1 2 3 4 5 6 7 8 9 | uint8_t pairMode = GAPBOND_PAIRING_MODE_WAIT_FOR_REQ;
uint8_t scMode = GAPBOND_SECURE_CONNECTION_ONLY;
uint8_t mitm = TRUE;
uint8_t ioCap = GAPBOND_IO_CAP_DISPLAY_YES_NO;
GAPBondMgr_SetParameter(GAPBOND_IO_CAPABILITIES, sizeof(uint8_t), &ioCap);
GAPBondMgr_SetParameter(GAPBOND_PAIRING_MODE, sizeof(uint8_t), &pairMode);
GAPBondMgr_SetParameter(GAPBOND_MITM_PROTECTION, sizeof(uint8_t), &mitm);
GAPBondMgr_SetParameter(GAPBOND_SECURE_CONNECTION, sizeof(uint8_t), &scMode);
|
- Process passcode callback and display code.
1 2 3 4 5 6 7 8 9 10 11 12 13 | static void SimpleCentral_processPasscode(uint16_t connHandle,
uint8_t uiOutputs)
{
// Display passcode to user
if (uiOutputs != 0)
{
Display_printf(dispHandle, SC_ROW_CUR_CONN, 0, "Passcode: %d",
B_APP_DEFAULT_PASSCODE);
}
// Send passcode response
GAPBondMgr_PasscodeRsp(connHandle, SUCCESS, B_APP_DEFAULT_PASSCODE);
}
|
- Accept Yes-No input from user and send response to GAPBondMgr.
1 2 3 4 5 6 | if (keys & KEY_RIGHT)
{
//Send response to indicate that code matches
GAPBondMgr_PasscodeRsp(connHandle, SUCCESS, TRUE);
return;
}
|
In this case, the third parameter of GAPBondMgr_PasscodeRsp, which usually accepts a passcode, is overloaded to send TRUE to the stack to indicate that the codes match and to continue with pairing. The process of numeric comparison is illustrated in Figure 73.
GAPBondMgr Example With Bonding Enabled¶
Bonding can enabled or disabled for any type of pairing through the
GAPBOND_BONDING_ENABLED
parameter, and occurs after the pairing
process is complete. To enable bonding, configure the GAPBondMgr as
follows:
uint8_t bonding = TRUE;
GAPBondMgr_SetParameter(GAPBOND_BONDING_ENABLED, sizeof(uint8_t), &bonding);
With bonding enabled, the GAPBondMgr stores the long-term key
transferred during the pairing process to SNV. See GAPBondMgr and SNV for more information. After this is completed, the application is notified
through the GAPBOND_PAIRING_STATE_COMPLETE
event. GAPBOND_PAIRING_STATE_BOND_SAVED
is only passed to the application pair
state callback when initially connecting, pairing, and bonding. For
future connections to a bonded device, the security keys are loaded from
flash, thus skipping the pairing process. In this case, only
GAPBOND_PAIRING_STATE_BONDED
is passed to the application pair state callback. This is illustrated in Figure 74.
GAPBondMgr and SNV¶
This section describes how the GAPBondMgr uses the SNV flash area
for storing bonding information. For more information on SNV itself,
see Flash. The amount of bonds that can be stored
is set by the GAP_BONDINGS_MAX
definition, which is set to 6 by default in
gapbondmgr.h, which can be modified as needed by the application.
When you set it GAP_BONDINGS_MAX to be larger than 6, there will be warning shown
in the following code snippet.
#if !defined ( GAP_BONDINGS_MAX )
/// Maximum number of bonds that can be saved in NV.
#define GAP_BONDINGS_MAX 6
#if GAP_BONDINGS_MAX > 6
#warning "Setting bond list size to be bigger than 6 is not supported"
#endif
#endif
The reason for GAP_BONDINGS_MAX = 6 limitation when using privacy is that the latency introduced by the radio core when going through the Resolving List to resolve the address is too much if the list size is larger than 6. Then BLE5-Stack will not resolve in time and will cause unexpected problems.
The functionality of the GAPBondMgr when there are no
more available bonds varies based on whether the “least recently
used” scheme is enabled. See BLE Stack API Reference (GAPBondMgr section) for
more information on the GAPBOND_LRU_BOND_REPLACEMENT
parameter. If this
parameter is set to false, it is not possible to add any more bonds without
manually deleting a bond. If the parameter is set to true, the least
recently used bond is deleted to make room for the new bond.
The following components comprise one bonding entry:
- Bond Record: this consists of the peer’s address, address type, privacy reconnection address, and state flags. This comprises 8 bytes and is defined as such:
// Structure of NV data for the connected device's address information
typedef struct
{
/**
* Peer's address
*
* If identity information exists for this bond, this will be an
* identity address
*/
uint8_t addr[B_ADDR_LEN];
/**
* Peer's address type
*/
GAP_Peer_Addr_Types_t addrType;
/**
* State flags of bond
*
* @ref GAP_BONDED_STATE_FLAGS
*/
uint8_t stateFlags;
} gapBondRec_t;
- Client Characteristic Configurations (CCC): the amount of CCCs stored
in each entry are set by the
GAP_CHAR_CFG_MAX
define. This is set to 4 by default. Each CCC is comprised of 4-bytes and is defined as follows:
// Structure of NV data for the connected device's characteristic configuration
typedef struct
{
uint16 attrHandle; // attribute handle
uint8 value; // attribute value for this device
} gapBondCharCfg_t;
- Local Long Term Key (LTK) info: this stores the local device’s encryption information. This comprises 28 bytes and is composed as such:
typedef struct
{
uint8 LTK[KEYLEN]; // Long Term Key (LTK)
uint16 div; //lint -e754 // LTK eDiv
uint8 rand[B_RANDOM_NUM_SIZE]; // LTK random number
uint8 keySize; // LTK key size
} gapBondLTK_t;
- Connected Device Long Term Key Info: this stores the connected device’s encryption information. This is also a gapBondLTK_t and comprises 28 bytes.
- Connected Device Identity Resolving Key (IRK): this stores the IRK generated during pairing. This is a 16-byte array.
- Connected Device Sign Resolving Key (SRK): this stores the SRK generated during pairing. This is a 16-byte array.
- Connected Device Sign counter: this stores the sign counter generated during pairing. This is a 4-byte word.