Skip to content

Commit 81e6d2e

Browse files
h2zerocsmith-morningstar
h2zero
and
csmith-morningstar
committed
[BREAKING] Asynchronous pin injections for Numeric Comparison and PassKey Input
* Make NimBLEConnInfo functions const. * Update callback functions and update client to use new functions. * Update examples. * Update migration guide. --------- Co-authored-by: Casey Smith <csmith@morningstarcorp.com>
1 parent 27d3253 commit 81e6d2e

File tree

15 files changed

+214
-162
lines changed

15 files changed

+214
-162
lines changed

‎docs/Migration_guide.md

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -383,18 +383,23 @@ The security callback methods are now incorporated in the `NimBLEServerCallbacks
383383

384384
The callback methods are:
385385

386-
> `bool onConfirmPIN(uint32_t pin)`
386+
> `bool onConfirmPIN(const NimBLEConnInfo& connInfo, uint32_t pin)`
387387
388-
Receives the pin when using numeric comparison authentication, `return true;` to accept.
388+
Receives the pin when using numeric comparison authentication.
389+
Call `NimBLEDevice::injectConfirmPIN(connInfo, true);` to accept or `NimBLEDevice::injectConfirmPIN(connInfo, false);` to reject.
389390
<br/>
390391

391-
> `uint32_t onPassKeyRequest()`
392+
> `void onPassKeyEntry(const NimBLEConnInfo& connInfo)`
392393
393-
For server callback; return the passkey expected from the client.
394-
For client callback; return the passkey to send to the server.
394+
Client callback; client should respond with the passkey (pin) by calling `NimBLEDevice::injectPassKey(connInfo, 123456);`
395395
<br/>
396396

397-
> `void onAuthenticationComplete(NimBLEConnInfo& connInfo)`
397+
> `uint32_t onPassKeyDisplay()`
398+
399+
Server callback; should return the passkey (pin) expected from the client.
400+
<br/>
401+
402+
> `void onAuthenticationComplete(const NimBLEConnInfo& connInfo)`
398403
399404
Authentication complete, success or failed information is available from the `NimBLEConnInfo` methods.
400405
<br/>

‎examples/NimBLE_Client/NimBLE_Client.ino

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -56,28 +56,29 @@ class ClientCallbacks : public NimBLEClientCallbacks {
5656

5757
/********************* Security handled here **********************
5858
****** Note: these are the same return values as defaults ********/
59-
uint32_t onPassKeyRequest(){
60-
Serial.println("Client Passkey Request");
61-
/** return the passkey to send to the server */
62-
return 123456;
59+
void onPassKeyEntry(const NimBLEConnInfo& connInfo){
60+
Serial.println("Server Passkey Entry");
61+
/** This should prompt the user to enter the passkey displayed
62+
* on the peer device.
63+
*/
64+
NimBLEDevice::injectPassKey(connInfo, 123456);
6365
};
6466

65-
bool onConfirmPIN(uint32_t pass_key){
66-
Serial.print("The passkey YES/NO number: ");
67-
Serial.println(pass_key);
68-
/** Return false if passkeys don't match. */
69-
return true;
67+
void onConfirmPIN(const NimBLEConnInfo& connInfo, uint32_t pass_key){
68+
Serial.print("The passkey YES/NO number: ");Serial.println(pass_key);
69+
/** Inject false if passkeys don't match. */
70+
NimBLEDevice::injectConfirmPIN(connInfo, true);
7071
};
7172

72-
/** Pairing process complete, we can check the results in NimBLEConnInfo */
73-
void onAuthenticationComplete(NimBLEConnInfo& connInfo){
73+
/** Pairing process complete, we can check the results in connInfo */
74+
void onAuthenticationComplete(const NimBLEConnInfo& connInfo){
7475
if(!connInfo.isEncrypted()) {
7576
Serial.println("Encrypt connection failed - disconnecting");
76-
/** Find the client with the connection handle provided in connInfo */
77+
/** Find the client with the connection handle provided in desc */
7778
NimBLEDevice::getClientByID(connInfo.getConnHandle())->disconnect();
7879
return;
7980
}
80-
};
81+
}
8182
};
8283

8384

‎examples/NimBLE_Secure_Client/NimBLE_Secure_Client.ino

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@
1212

1313
class ClientCallbacks : public NimBLEClientCallbacks
1414
{
15-
uint32_t onPassKeyRequest()
15+
uint32_t onPassKeyEntry()
1616
{
17-
Serial.println("Client Passkey Request");
17+
Serial.println("Client Passkey Entry");
1818
/** return the passkey to send to the server */
1919
/** Change this to be different from NimBLE_Secure_Server if you want to test what happens on key mismatch */
2020
return 123456;

‎examples/NimBLE_Server/NimBLE_Server.ino

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,21 +37,21 @@ class ServerCallbacks: public NimBLEServerCallbacks {
3737

3838
/********************* Security handled here **********************
3939
****** Note: these are the same return values as defaults ********/
40-
uint32_t onPassKeyRequest(){
41-
Serial.println("Server Passkey Request");
40+
uint32_t onPassKeyDisplay() {
41+
Serial.println("Server Passkey Display");
4242
/** This should return a random 6 digit number for security
4343
* or make your own static passkey as done here.
4444
*/
4545
return 123456;
4646
};
4747

48-
bool onConfirmPIN(uint32_t pass_key){
48+
void onConfirmPIN(const NimBLEConnInfo& connInfo, uint32_t pass_key) {
4949
Serial.print("The passkey YES/NO number: ");Serial.println(pass_key);
50-
/** Return false if passkeys don't match. */
51-
return true;
50+
/** Inject false if passkeys don't match. */
51+
NimBLEDevice::injectConfirmPIN(connInfo, true);
5252
};
5353

54-
void onAuthenticationComplete(NimBLEConnInfo& connInfo){
54+
void onAuthenticationComplete(const NimBLEConnInfo& connInfo) {
5555
/** Check that encryption was successful, if not we disconnect the client */
5656
if(!connInfo.isEncrypted()) {
5757
NimBLEDevice::getServer()->disconnect(connInfo.getConnHandle());

‎examples/Refactored_original_examples/BLE_client/BLE_client.ino

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,16 +51,17 @@ class MyClientCallback : public BLEClientCallbacks {
5151
}
5252
/***************** New - Security handled here ********************
5353
****** Note: these are the same return values as defaults ********/
54-
uint32_t onPassKeyRequest(){
55-
Serial.println("Client PassKeyRequest");
56-
return 123456;
54+
void onPassKeyEntry() {
55+
Serial.println("Client PassKey Entry");
56+
NimBLEDevice::injectPassKey(connInfo, 123456);
5757
}
58-
bool onConfirmPIN(uint32_t pass_key){
58+
59+
void onConfirmPIN(const BLEConnInfo& connInfo, uint32_t pass_key) {
5960
Serial.print("The passkey YES/NO number: ");Serial.println(pass_key);
60-
return true;
61+
NimBLEDevice::injectConfirmPIN(connInfo, true);
6162
}
6263

63-
void onAuthenticationComplete(BLEConnInfo& connInfo){
64+
void onAuthenticationComplete(const BLEConnInfo& connInfo){
6465
Serial.println("Starting BLE work!");
6566
}
6667
/*******************************************************************/

‎examples/Refactored_original_examples/BLE_notify/BLE_notify.ino

Lines changed: 24 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ uint32_t value = 0;
4343
#define CHARACTERISTIC_UUID "beb5483e-36e1-4688-b7f5-ea07361b26a8"
4444

4545
/** None of these are required as they will be handled by the library with defaults. **
46-
** Remove as you see fit for your needs */
46+
** Remove as you see fit for your needs */
4747
class MyServerCallbacks: public BLEServerCallbacks {
4848
void onConnect(BLEServer* pServer, BLEConnInfo& connInfo) {
4949
deviceConnected = true;
@@ -54,19 +54,23 @@ class MyServerCallbacks: public BLEServerCallbacks {
5454
}
5555
/***************** New - Security handled here ********************
5656
****** Note: these are the same return values as defaults ********/
57-
uint32_t onPassKeyRequest(){
58-
Serial.println("Server PassKeyRequest");
59-
return 123456;
60-
}
61-
62-
bool onConfirmPIN(uint32_t pass_key){
63-
Serial.print("The passkey YES/NO number: ");Serial.println(pass_key);
64-
return true;
65-
}
66-
67-
void onAuthenticationComplete(BLEConnInfo& connInfo){
68-
Serial.println("Starting BLE work!");
69-
}
57+
uint32_t onPassKeyDisplay() {
58+
Serial.println("Server Passkey Display");
59+
/** This should return a random 6 digit number for security
60+
* or make your own static passkey as done here.
61+
*/
62+
return 123456;
63+
}
64+
65+
void onConfirmPIN(const BLEConnInfo& connInfo, uint32_t pass_key) {
66+
Serial.print("The passkey YES/NO number: ");Serial.println(pass_key);
67+
/** Inject false if passkeys don't match. */
68+
NimBLEDevice::injectConfirmPIN(connInfo, true);
69+
}
70+
71+
void onAuthenticationComplete(const BLEConnInfo& connInfo) {
72+
Serial.println("Starting BLE work!");
73+
}
7074
/*******************************************************************/
7175
};
7276

@@ -87,13 +91,13 @@ void setup() {
8791
// Create a BLE Characteristic
8892
pCharacteristic = pService->createCharacteristic(
8993
CHARACTERISTIC_UUID,
90-
/******* Enum Type NIMBLE_PROPERTY now *******
94+
/******* Enum Type NIMBLE_PROPERTY now *******
9195
BLECharacteristic::PROPERTY_READ |
9296
BLECharacteristic::PROPERTY_WRITE |
9397
BLECharacteristic::PROPERTY_NOTIFY |
9498
BLECharacteristic::PROPERTY_INDICATE
9599
);
96-
**********************************************/
100+
**********************************************/
97101
NIMBLE_PROPERTY::READ |
98102
NIMBLE_PROPERTY::WRITE |
99103
NIMBLE_PROPERTY::NOTIFY |
@@ -102,11 +106,11 @@ void setup() {
102106

103107
// https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.descriptor.gatt.client_characteristic_configuration.xml
104108
// Create a BLE Descriptor
105-
/***************************************************
106-
NOTE: DO NOT create a 2902 descriptor.
107-
it will be created automatically if notifications
109+
/***************************************************
110+
NOTE: DO NOT create a 2902 descriptor.
111+
it will be created automatically if notifications
108112
or indications are enabled on a characteristic.
109-
113+
110114
pCharacteristic->addDescriptor(new BLE2902());
111115
****************************************************/
112116
// Start the service

‎examples/Refactored_original_examples/BLE_server_multiconnect/BLE_server_multiconnect.ino

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ uint32_t value = 0;
4444

4545

4646
/** None of these are required as they will be handled by the library with defaults. **
47-
** Remove as you see fit for your needs */
47+
** Remove as you see fit for your needs */
4848
class MyServerCallbacks: public BLEServerCallbacks {
4949
void onConnect(BLEServer* pServer, BLEConnInfo& connInfo) {
5050
deviceConnected = true;
@@ -56,17 +56,21 @@ class MyServerCallbacks: public BLEServerCallbacks {
5656
}
5757
/***************** New - Security handled here ********************
5858
****** Note: these are the same return values as defaults ********/
59-
uint32_t onPassKeyRequest(){
60-
Serial.println("Server PassKeyRequest");
61-
return 123456;
59+
uint32_t onPassKeyDisplay() {
60+
Serial.println("Server Passkey Display");
61+
/** This should return a random 6 digit number for security
62+
* or make your own static passkey as done here.
63+
*/
64+
return 123456;
6265
}
6366

64-
bool onConfirmPIN(uint32_t pass_key){
67+
void onConfirmPIN(const BLEConnInfo& connInfo, uint32_t pass_key) {
6568
Serial.print("The passkey YES/NO number: ");Serial.println(pass_key);
66-
return true;
69+
/** Inject false if passkeys don't match. */
70+
NimBLEDevice::injectConfirmPIN(connInfo, true);
6771
}
6872

69-
void onAuthenticationComplete(BLEConnInfo& connInfo){
73+
void onAuthenticationComplete(const BLEConnInfo& connInfo) {
7074
Serial.println("Starting BLE work!");
7175
}
7276
/*******************************************************************/
@@ -90,13 +94,13 @@ void setup() {
9094
// Create a BLE Characteristic
9195
pCharacteristic = pService->createCharacteristic(
9296
CHARACTERISTIC_UUID,
93-
/******* Enum Type NIMBLE_PROPERTY now *******
97+
/******* Enum Type NIMBLE_PROPERTY now *******
9498
BLECharacteristic::PROPERTY_READ |
9599
BLECharacteristic::PROPERTY_WRITE |
96100
BLECharacteristic::PROPERTY_NOTIFY |
97101
BLECharacteristic::PROPERTY_INDICATE
98102
);
99-
**********************************************/
103+
**********************************************/
100104
NIMBLE_PROPERTY::READ |
101105
NIMBLE_PROPERTY::WRITE |
102106
NIMBLE_PROPERTY::NOTIFY |
@@ -105,11 +109,11 @@ void setup() {
105109

106110
// https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.descriptor.gatt.client_characteristic_configuration.xml
107111
// Create a BLE Descriptor
108-
/***************************************************
109-
NOTE: DO NOT create a 2902 descriptor
110-
it will be created automatically if notifications
112+
/***************************************************
113+
NOTE: DO NOT create a 2902 descriptor
114+
it will be created automatically if notifications
111115
or indications are enabled on a characteristic.
112-
116+
113117
pCharacteristic->addDescriptor(new BLE2902());
114118
****************************************************/
115119

‎examples/Refactored_original_examples/BLE_uart/BLE_uart.ino

Lines changed: 23 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
66
Create a BLE server that, once we receive a connection, will send periodic notifications.
77
The service advertises itself as: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E
8-
Has a characteristic of: 6E400002-B5A3-F393-E0A9-E50E24DCCA9E - used for receiving data with "WRITE"
8+
Has a characteristic of: 6E400002-B5A3-F393-E0A9-E50E24DCCA9E - used for receiving data with "WRITE"
99
Has a characteristic of: 6E400003-B5A3-F393-E0A9-E50E24DCCA9E - used to send data with "NOTIFY"
1010
1111
The design of creating the BLE server is:
@@ -17,7 +17,7 @@
1717
6. Start advertising.
1818
1919
In this example rxValue is the data received (only accessible inside that function).
20-
And txValue is the data to be sent, in this example just a byte incremented every second.
20+
And txValue is the data to be sent, in this example just a byte incremented every second.
2121
*/
2222

2323
/** NimBLE differences highlighted in comment blocks **/
@@ -45,7 +45,7 @@ uint8_t txValue = 0;
4545

4646

4747
/** None of these are required as they will be handled by the library with defaults. **
48-
** Remove as you see fit for your needs */
48+
** Remove as you see fit for your needs */
4949
class MyServerCallbacks: public BLEServerCallbacks {
5050
void onConnect(BLEServer* pServer, BLEConnInfo& connInfo) {
5151
deviceConnected = true;
@@ -56,17 +56,21 @@ class MyServerCallbacks: public BLEServerCallbacks {
5656
}
5757
/***************** New - Security handled here ********************
5858
****** Note: these are the same return values as defaults ********/
59-
uint32_t onPassKeyRequest(){
60-
Serial.println("Server PassKeyRequest");
61-
return 123456;
59+
uint32_t onPassKeyDisplay() {
60+
Serial.println("Server Passkey Display");
61+
/** This should return a random 6 digit number for security
62+
* or make your own static passkey as done here.
63+
*/
64+
return 123456;
6265
}
6366

64-
bool onConfirmPIN(uint32_t pass_key){
67+
void onConfirmPIN(const BLEConnInfo& connInfo, uint32_t pass_key) {
6568
Serial.print("The passkey YES/NO number: ");Serial.println(pass_key);
66-
return true;
69+
/** Inject false if passkeys don't match. */
70+
NimBLEDevice::injectConfirmPIN(connInfo, true);
6771
}
6872

69-
void onAuthenticationComplete(BLEConnInfo& connInfo){
73+
void onAuthenticationComplete(const BLEConnInfo& connInfo) {
7074
Serial.println("Starting BLE work!");
7175
}
7276
/*******************************************************************/
@@ -105,27 +109,27 @@ void setup() {
105109
// Create a BLE Characteristic
106110
pTxCharacteristic = pService->createCharacteristic(
107111
CHARACTERISTIC_UUID_TX,
108-
/******* Enum Type NIMBLE_PROPERTY now *******
112+
/******* Enum Type NIMBLE_PROPERTY now *******
109113
BLECharacteristic::PROPERTY_NOTIFY
110114
);
111-
**********************************************/
115+
**********************************************/
112116
NIMBLE_PROPERTY::NOTIFY
113117
);
114-
115-
/***************************************************
116-
NOTE: DO NOT create a 2902 descriptor
117-
it will be created automatically if notifications
118+
119+
/***************************************************
120+
NOTE: DO NOT create a 2902 descriptor
121+
it will be created automatically if notifications
118122
or indications are enabled on a characteristic.
119-
123+
120124
pCharacteristic->addDescriptor(new BLE2902());
121-
****************************************************/
125+
****************************************************/
122126

123127
BLECharacteristic * pRxCharacteristic = pService->createCharacteristic(
124128
CHARACTERISTIC_UUID_RX,
125-
/******* Enum Type NIMBLE_PROPERTY now *******
129+
/******* Enum Type NIMBLE_PROPERTY now *******
126130
BLECharacteristic::PROPERTY_WRITE
127131
);
128-
*********************************************/
132+
*********************************************/
129133
NIMBLE_PROPERTY::WRITE
130134
);
131135

0 commit comments

Comments
 (0)