feat: rename Pair to PairAndBond (#907)

* Work towards improving pairing security requirements

* Better enum naming for ConnectionMode and ManInTheMiddleMode

* Renamed notRequired to Disabled

* Rename values in SecureConnectionMode enum

* Refactoring SecureConnectionMode and MITMMODE into 2 functions

* refactoring

* fixed compile error

* Removed bracket

* Merge commit 'c20c83ea909ca2e1a7ef8a07bb5cfe91144bf3a7'

* Refactored Pair to Bond in Gap.proto

* revert changes to gap

* cleanup

* cleanup

* Renamed to PairAndBond

* pr comments

* Added some void trace functions

* Renamed to PairAndBond

* Moving logging functions away from root class

* Update services/ble/Gap.hpp

Co-authored-by: Richard Peters <richard.peters@philips.com>

---------

Co-authored-by: MiquelJayson-Philips <miqueljayson.de.leeuw@philips.com>
Co-authored-by: Richard Peters <richard.peters@philips.com>

Author: 3 people

services/ble/Gap.cpp

@@ -44,9 +44,9 @@ namespace services
             });
     }
 
-    void GapPairingDecorator::Pair()
+    void GapPairingDecorator::PairAndBond()
     {
-        GapPairingObserver::Subject().Pair();
+        GapPairingObserver::Subject().PairAndBond();
     }
 
     void GapPairingDecorator::AllowPairing(bool allow)

services/ble/Gap.hpp

@@ -128,13 +128,13 @@ namespace services
             level4,
         };
 
-        virtual void Pair() = 0;
+        // 1. If there is a pre-existing bond, then the connection will be encrypted.
+        // 2. If there is no pre-existing bond, then pairing, encrypting, and bonding (storing the keys) will take place.
+        virtual void PairAndBond() = 0;
 
         virtual void AllowPairing(bool allow) = 0;
-
         virtual void SetSecurityMode(SecurityMode mode, SecurityLevel level) = 0;
         virtual void SetIoCapabilities(IoCapabilities caps) = 0;
-
         virtual void AuthenticateWithPasskey(uint32_t passkey) = 0;
         virtual void NumericComparisonConfirm(bool accept) = 0;
     };
@@ -152,7 +152,7 @@ namespace services
         void PairingFailed(PairingErrorType error) override;
 
         // Implementation of GapPairing
-        void Pair() override;
+        void PairAndBond() override;
         void AllowPairing(bool allow) override;
         void SetSecurityMode(SecurityMode mode, SecurityLevel level) override;
         void SetIoCapabilities(IoCapabilities caps) override;

services/ble/Gap.proto

@@ -222,16 +222,22 @@ service GapCentral
     // Allowed states: connected
     rpc Disconnect(Nothing) returns (Nothing) { option (method_id) = 5; }
 
-    // Allowed states: connected
-    rpc Pair(Nothing) returns (Nothing) { option (method_id) = 6; }
+    // Allowed states: connected 
+    // 1. If there is a pre-existing bond, then the connection will be encrypted.
+    // 2. If there is no pre-existing bond, then pairing, encrypting, and bonding (storing the keys) will take place.
+    rpc PairAndBond(Nothing) returns (Nothing) { option (method_id) = 6; }
 
     rpc SetSecurityMode(SecurityModeAndLevel) returns (Nothing) { option (method_id) = 7; }
     rpc SetIoCapabilities(IoCapabilities) returns (Nothing) { option (method_id) = 8; }
     rpc AuthenticateWithPasskey(UInt32Value) returns (Nothing) { option (method_id) = 9; }
     rpc NumericComparisonConfirm(BoolValue) returns (Nothing) { option (method_id) = 10; }
     rpc RemoveAllBonds(Nothing) returns (Nothing) { option (method_id) = 11; }
     rpc SetDeviceDiscoveryFilter(DeviceDiscoveryFilter) returns (Nothing) { option (method_id) = 12; }
-    rpc ResolvePrivateAddress(Address) returns (Nothing) { option (method_id) = 13; }
+
+    // This will only succeed if Address is a private resolvable address, and if the device is bonded
+    rpc ResolvePrivateAddress(Address) returns (Nothing) { option (method_id) = 13; } 
+
+    // This will work with both public and random addresses
     rpc IsDeviceBonded(PeerNodeParameters) returns (Nothing) { option (method_id) = 14; }
 }
 

services/ble/test/TestGapPairing.cpp

@@ -34,8 +34,8 @@ namespace services
 
     TEST_F(GapPairingDecoratorTest, forward_all_calls_to_subject)
     {
-        EXPECT_CALL(gapPairing, Pair());
-        decorator.Pair();
+        EXPECT_CALL(gapPairing, PairAndBond());
+        decorator.PairAndBond();
 
         EXPECT_CALL(gapPairing, AllowPairing(::testing::IsTrue()));
         decorator.AllowPairing(true);

services/ble/test_doubles/GapPairingMock.hpp

@@ -10,7 +10,7 @@ namespace services
         : public GapPairing
     {
     public:
-        MOCK_METHOD(void, Pair, ());
+        MOCK_METHOD(void, PairAndBond, ());
         MOCK_METHOD(void, AllowPairing, (bool allow));
         MOCK_METHOD(void, SetSecurityMode, (SecurityMode mode, SecurityLevel level));
         MOCK_METHOD(void, SetIoCapabilities, (IoCapabilities caps));