feature(BLE): Update NimBLE, BleGattServer, and GfpsService to support Passkey Injection (#258)

* feat(ble): Support passkey injection via esp-nimble-cpp
* Update `espp::BleGattServer` for breaking API changes to esp-nimble-cpp which add support for passkey injection
* Update `espp::GfpsService` to use new esp-nimble-cpp APIs to perform passkey injection as part of the GFPS pairing / security process

* update examples

* submodule: update esp-nimble-cpp submodule for asynchronous pin injections

Author: finger563

components/ble_gatt_server/example/main/ble_gatt_server_example.cpp

@@ -27,7 +27,7 @@ extern "C" void app_main(void) {
       .disconnect_callback = [&](auto &conn_info,
                                  auto reason) { logger.info("Device disconnected: {}", reason); },
       .authentication_complete_callback =
-          [&](NimBLEConnInfo &conn_info) { logger.info("Device authenticated"); },
+          [&](const NimBLEConnInfo &conn_info) { logger.info("Device authenticated"); },
       // NOTE: this is optional, if you don't provide this callback, it will
       // perform the exactly function as below:
       .get_passkey_callback =
@@ -38,9 +38,10 @@ extern "C" void app_main(void) {
       // NOTE: this is optional, if you don't provide this callback, it will
       // perform the exactly function as below:
       .confirm_passkey_callback =
-          [&](uint32_t passkey) {
+          [&](const NimBLEConnInfo &conn_info, uint32_t passkey) {
             logger.info("Confirming passkey: {}", passkey);
-            return passkey == NimBLEDevice::getSecurityPasskey();
+            NimBLEDevice::injectConfirmPIN(conn_info,
+                                           passkey == NimBLEDevice::getSecurityPasskey());
           },
   });
   ble_gatt_server.init(device_name);

components/ble_gatt_server/include/ble_gatt_server.hpp

@@ -66,16 +66,16 @@ class BleGattServer : public BaseComponent {
 
   /// @brief Callback for when a device completes authentication.
   /// @param conn_info The connection information for the device.
-  typedef std::function<void(NimBLEConnInfo &)> authentication_complete_callback_t;
+  typedef std::function<void(const NimBLEConnInfo &)> authentication_complete_callback_t;
 
-  /// @brief Callback for the passkey.
+  /// @brief Callback to retrieve the passkey for the device.
   /// @return The passkey for the device.
   typedef std::function<uint32_t(void)> get_passkey_callback_t;
 
   /// @brief Callback for confirming the passkey.
+  /// @param conn_info The connection information for the device.
   /// @param passkey The passkey for the device.
-  /// @return Whether the passkey is confirmed.
-  typedef std::function<bool(uint32_t)> confirm_passkey_callback_t;
+  typedef std::function<void(const NimBLEConnInfo &conn_info, uint32_t)> confirm_passkey_callback_t;
 
 #if CONFIG_BT_NIMBLE_EXT_ADV || defined(_DOXYGEN_)
   /// @brief Callback for when advertising is stopped.
@@ -131,11 +131,18 @@ class BleGattServer : public BaseComponent {
     authentication_complete_callback_t authentication_complete_callback =
         nullptr; ///< Callback for when a device completes authentication.
     get_passkey_callback_t get_passkey_callback =
-        nullptr; ///< Callback for getting the passkey. If not set, will simply
-                 ///  return NimBLEDevice::getSecurityPasskey().
+        nullptr; ///< Callback for getting the passkey.
+                 /// @note If not provided, will simply return
+                 /// NimBLEDevice::getSecurityPasskey().
     confirm_passkey_callback_t confirm_passkey_callback =
-        nullptr; ///< Callback for confirming the passkey. If not set, will
-                 ///  simply compare the passkey to NimBLEDevice::getSecurityPasskey().
+        nullptr; ///< Callback for confirming the passkey.
+                 /// @note Within this function or some point after this call,
+                 /// the user should call
+                 /// NimBLEDevice::injectConfirmPIN(conn_info, true/false) to
+                 /// confirm or reject the passkey.
+                 /// @note If not provided, will simply call
+                 /// NimBLEDevice::injectConfirmPIN(conn_info, passkey ==
+                 /// NimBLEDevice::getSecurityPasskey()).
 #if !CONFIG_BT_NIMBLE_EXT_ADV || defined(_DOXYGEN_)
     advertisement_complete_callback_t advertisement_complete_callback =
         nullptr; ///< Callback for when advertising is complete.

components/ble_gatt_server/include/ble_gatt_server_callbacks.hpp

@@ -15,9 +15,9 @@ class BleGattServerCallbacks : public NimBLEServerCallbacks {
 public:
   virtual void onConnect(NimBLEServer *server, NimBLEConnInfo &conn_info) override;
   virtual void onDisconnect(NimBLEServer *server, NimBLEConnInfo &conn_info, int reason) override;
-  virtual void onAuthenticationComplete(NimBLEConnInfo &conn_info) override;
-  virtual uint32_t onPassKeyRequest() override;
-  virtual bool onConfirmPIN(uint32_t pass_key) override;
+  virtual void onAuthenticationComplete(const NimBLEConnInfo &conn_info) override;
+  virtual uint32_t onPassKeyDisplay() override;
+  virtual void onConfirmPIN(const NimBLEConnInfo &conn_info, uint32_t pass_key) override;
 
 protected:
   friend class BleGattServer;

components/ble_gatt_server/src/ble_gatt_server_callbacks.cpp

@@ -52,23 +52,23 @@ void BleGattServerCallbacks::onDisconnect(NimBLEServer *server, NimBLEConnInfo &
   }
 }
 
-void BleGattServerCallbacks::onAuthenticationComplete(NimBLEConnInfo &conn_info) {
+void BleGattServerCallbacks::onAuthenticationComplete(const NimBLEConnInfo &conn_info) {
   if (server_ && server_->callbacks_.authentication_complete_callback) {
     server_->callbacks_.authentication_complete_callback(conn_info);
   }
 }
-uint32_t BleGattServerCallbacks::onPassKeyRequest() {
+uint32_t BleGattServerCallbacks::onPassKeyDisplay() {
   if (server_ && server_->callbacks_.get_passkey_callback) {
     return server_->callbacks_.get_passkey_callback();
   } else {
     return NimBLEDevice::getSecurityPasskey();
   }
 }
-bool BleGattServerCallbacks::onConfirmPIN(uint32_t pass_key) {
+void BleGattServerCallbacks::onConfirmPIN(const NimBLEConnInfo &conn_info, uint32_t pass_key) {
   if (server_ && server_->callbacks_.confirm_passkey_callback) {
-    return server_->callbacks_.confirm_passkey_callback(pass_key);
+    server_->callbacks_.confirm_passkey_callback(conn_info, pass_key);
   } else {
-    return pass_key == NimBLEDevice::getSecurityPasskey();
+    NimBLEDevice::injectConfirmPIN(conn_info, pass_key == NimBLEDevice::getSecurityPasskey());
   }
 }
 

components/esp-nimble-cpp

@@ -25,16 +25,13 @@ extern "C" void app_main(void) {
       .disconnect_callback = [&](auto &conn_info,
                                  auto reason) { logger.info("Device disconnected: {}", reason); },
       .authentication_complete_callback =
-          [&](NimBLEConnInfo &conn_info) { logger.info("Device authenticated"); },
+          [&](const NimBLEConnInfo &conn_info) { logger.info("Device authenticated"); },
       .get_passkey_callback = [&]() { return NimBLEDevice::getSecurityPasskey(); },
       .confirm_passkey_callback =
-          [&](uint32_t passkey) {
-            // NOTE: right now we have no way to do asynchronous passkey injection
-            // (see: https://github.com/h2zero/esp-nimble-cpp/pull/117), so we
-            // have to blindly return true here AND set the passkey since it will
-            // be used by the GFPS BLE stack through the side channel.
+          [&](const NimBLEConnInfo &conn_info, uint32_t passkey) {
+            // set the passkey here, so that GFPS can later compare against it
+            // and inject confirmation/rejection
             NimBLEDevice::setSecurityPasskey(passkey);
-            return true;
           },
   });
   ble_gatt_server.init(device_name);

components/gfps_service/example/main/gfps_service_example.cpp

@@ -79,16 +79,6 @@ int espp::gfps::ble_gap_event_handler(ble_gap_event *event, void *arg) {
     NimBLEDevice::setSecurityIOCap(BLE_HS_IO_NO_INPUT_OUTPUT);
     break;
   }
-  case BLE_GAP_EVENT_PASSKEY_ACTION: {
-    logger.info("BLE_GAP_EVENT_PASSKEY_ACTION");
-    if (event->passkey.params.action == BLE_SM_IOACT_NUMCMP) {
-      // this is the kind of event that GFPS should expect but for some reason
-      // it doesn't seem to be triggering (no BLE_GAP_EVENT_PASSKEY_ACTION
-      // events are being triggered, only the ones in the NimBLEServer class are
-      // triggered...)
-    }
-    break;
-  }
   default:
     break;
   }
@@ -273,12 +263,11 @@ void nearby_platform_SetRemotePasskey(uint32_t passkey) {
   } else {
     logger.error("Declining pairing request, passkey does not match");
   }
-  // TODO: in the original implementation we set the pairing success/failure
-  // here, but our current esp-nimble-cpp NimBLEServer doesn't have a
-  // mechanism right now which would allow us to respond success/failure here
-  // without responding within the onConfirmPIN callback.
-  logger.info("TODO: implement pairing success/failure here after esp-nimble-ble adds support for "
-              "asynchronous pin injections");
+  // get the connection info for the remote party (assume only one, so first
+  // index)
+  auto conn_info = NimBLEDevice::getServer()->getPeerInfo(0);
+  // Now actually respond to the pairing request
+  NimBLEDevice::injectConfirmPIN(conn_info, accept);
 #endif // CONFIG_BT_NIMBLE_ENABLED
 }
 

components/gfps_service/src/nearby_ble.cpp

@@ -27,7 +27,7 @@ extern "C" void app_main(void) {
       .disconnect_callback = [&](auto &conn_info,
                                  auto reason) { logger.info("Device disconnected: {}", reason); },
       .authentication_complete_callback =
-          [&](NimBLEConnInfo &conn_info) { logger.info("Device authenticated"); },
+          [&](const NimBLEConnInfo &conn_info) { logger.info("Device authenticated"); },
       // NOTE: this is optional, if you don't provide this callback, it will
       // perform the exactly function as below:
       .get_passkey_callback =
@@ -38,9 +38,10 @@ extern "C" void app_main(void) {
       // NOTE: this is optional, if you don't provide this callback, it will
       // perform the exactly function as below:
       .confirm_passkey_callback =
-          [&](uint32_t passkey) {
+          [&](const NimBLEConnInfo &conn_info, uint32_t passkey) {
             logger.info("Confirming passkey: {}", passkey);
-            return passkey == NimBLEDevice::getSecurityPasskey();
+            NimBLEDevice::injectConfirmPIN(conn_info,
+                                           passkey == NimBLEDevice::getSecurityPasskey());
           },
   });
   ble_gatt_server.init(device_name);