Merge pull request #13717 from ARMmbed/feature-ble-host-privacy

Feature ble host privacy

Author: 0xc0170

connectivity/FEATURE_BLE/include/ble/Gap.h

@@ -314,6 +314,17 @@ class Gap {
         {
         }
 
+        /**
+         * Called when advertising starts.
+         *
+         * @param event Advertising start event.
+         *
+         * @see startAdvertising()
+         */
+        virtual void onAdvertisingStart(const AdvertisingStartEvent &event)
+        {
+        }
+
         /**
          * Called when advertising ends.
          *
@@ -538,6 +549,14 @@ class Gap {
         )
         {
         }
+
+        /**
+         * Function invoked when the privacy subsystem has been enabled and is
+         * ready to be used.
+         */
+        virtual void onPrivacyEnabled()
+        {
+        }
     protected:
         /**
          * Prevent polymorphic deletion and avoid unnecessary virtual destructor
@@ -724,6 +743,7 @@ class Gap {
      * @param maxEvents Max number of events produced during advertising - 0 means no limit.
      * @return BLE_ERROR_NONE on success.
      *
+     * @see EventHandler::onAdvertisingStart when the advertising starts.
      * @see EventHandler::onScanRequestReceived when a scan request is received.
      * @see EventHandler::onAdvertisingEnd when the advertising ends.
      * @see EventHandler::onConnectionComplete when the device gets connected
@@ -1244,6 +1264,14 @@ class Gap {
      * resolved and advertisement packets are forwarded to the application
      * even if the advertiser private address is unknown.
      *
+     * @par Initialization of the privacy subsystem
+     *
+     * When privacy is enabled, the system generates new resolvable and non
+     * resolvable private addresses. Scan, Advertising and Connecting to a peer
+     * won't be available until the generation process completes. When addresses
+     * have been generated, the application is notified that privacy
+     * initialisation as completed with a call to EventHandler::onPrivacyEnabled .
+     *
      * @param[in] enable Should be set to true to enable the privacy mode and
      * false to disable it.
      *
@@ -1448,6 +1476,8 @@ class Gap {
      * forbidden by the Bluetooth specification.
      */
     ble_error_t setRandomStaticAddress(const ble::address_t& address);
+
+    ble::address_t getRandomStaticAddress();
 #endif // !defined(DOXYGEN_ONLY)
 
 private:

connectivity/FEATURE_BLE/include/ble/SecurityManager.h

@@ -835,6 +835,7 @@ class SecurityManager
     // Privacy
     //
 
+#if BLE_FEATURE_PRIVACY
     /**
      * Sets how often the address is rotated when privacy is enabled.
      *
@@ -845,6 +846,7 @@ class SecurityManager
     ble_error_t setPrivateAddressTimeout(
         uint16_t timeout_in_seconds
     );
+#endif // BLE_FEATURE_PRIVACY
 
     /* Event callback handlers. */
 public:

connectivity/FEATURE_BLE/include/ble/common/Duration.h

@@ -33,10 +33,11 @@ namespace ble {
  * @tparam Min left-bound
  * @tparam Max right-bound
  */
-template<uint32_t Min, uint32_t Max>
+template<uint32_t Min, uint32_t Max, uint32_t Default = Min>
 struct Range {
     static const uint32_t MIN = Min;
     static const uint32_t MAX = Max;
+    static const uint32_t DEFAULT = Default;
 };
 
 /**
@@ -111,7 +112,7 @@ struct Duration {
      *
      * It is initialized with the minimum value acceptable.
      */
-    Duration() : duration(Range::MIN)
+    Duration() : duration(Range::DEFAULT)
     {
     }
 
@@ -598,11 +599,14 @@ bool operator>(Duration<Rep, Us, Range, F> lhs, Duration<Rep, Us, Range, F> rhs)
 
 #if !defined(DOXYGEN_ONLY)
 
-template<uint32_t Min, uint32_t Max>
-const uint32_t Range<Min, Max>::MIN;
+template<uint32_t Min, uint32_t Max, uint32_t Default>
+const uint32_t Range<Min, Max, Default>::MIN;
 
-template<uint32_t Min, uint32_t Max>
-const uint32_t Range<Min, Max>::MAX;
+template<uint32_t Min, uint32_t Max, uint32_t Default>
+const uint32_t Range<Min, Max, Default>::MAX;
+
+template<uint32_t Min, uint32_t Max, uint32_t Default>
+const uint32_t Range<Min, Max, Default>::DEFAULT;
 
 template<typename T, T V>
 const T Value<T, V>::VALUE;

connectivity/FEATURE_BLE/include/ble/gap/Events.h

@@ -69,23 +69,22 @@ struct AdvertisingReportEvent {
         const address_t &directAddress,
         const mbed::Span<const uint8_t> &advertisingData
     ) :
+        peerAddress(peerAddress),
         type(type),
         peerAddressType(peerAddressType),
-        peerAddress(peerAddress),
         primaryPhy(primaryPhy),
         secondaryPhy(secondaryPhy),
         SID(SID),
         txPower(txPower),
-        rssi(rssi),
         periodicInterval(periodicInterval),
+        rssi(rssi),
         directAddressType(directAddressType),
         directAddress(directAddress),
         advertisingData(advertisingData)
     {
     }
 
 #endif
-
     /** Get event type. */
     const advertising_event_t &getType() const
     {
@@ -163,18 +162,44 @@ struct AdvertisingReportEvent {
         return advertisingData;
     }
 
+    /** Set peer address. */
+    void setPeerAddress(
+        const address_t &newPeerAddress
+    )
+    {
+        peerAddress = newPeerAddress;
+    }
+
+
+    /** Set peer address type. */
+    void setPeerAddressType(
+        const peer_address_type_t &newPeerAddressType
+    )
+    {
+        peerAddressType = newPeerAddressType;
+    }
+
+    /** Set new advertising payload. */
+    void setAdvertisingData(
+        const mbed::Span<const uint8_t> &newAdvertisingData
+    )
+    {
+        advertisingData = newAdvertisingData;
+    }
+
 private:
+    address_t peerAddress;
     advertising_event_t type;
     peer_address_type_t peerAddressType;
-    address_t const &peerAddress;
     phy_t primaryPhy;
     phy_t secondaryPhy;
     advertising_sid_t SID;
     advertising_power_t txPower;
-    rssi_t rssi;
     uint16_t periodicInterval;
+    rssi_t rssi;
     peer_address_type_t directAddressType;
-    const address_t &directAddress;
+    address_t directAddress;
+    ble_error_t status;
     mbed::Span<const uint8_t> advertisingData;
 };
 
@@ -215,12 +240,12 @@ struct ConnectionCompleteEvent {
     ) :
         status(status),
         connectionHandle(connectionHandle),
+        peerAddress(peerAddress),
         ownRole(ownRole),
         peerAddressType(peerAddressType),
-        peerAddress(peerAddress),
         localResolvablePrivateAddress(localResolvablePrivateAddress),
-        peerResolvablePrivateAddress(peerResolvablePrivateAddress),
         connectionInterval(connectionInterval),
+        peerResolvablePrivateAddress(peerResolvablePrivateAddress),
         connectionLatency(connectionLatency),
         supervisionTimeout(supervisionTimeout),
         masterClockAccuracy(masterClockAccuracy)
@@ -295,15 +320,46 @@ struct ConnectionCompleteEvent {
         return masterClockAccuracy;
     }
 
+
+    /** Set connection complete event status. */
+    void setStatus(ble_error_t new_status)
+    {
+        status = new_status;
+    }
+
+    /** Set peer address type. */
+    void setPeerAddressType(const peer_address_type_t& address_type)
+    {
+        peerAddressType = address_type;
+    }
+
+    /** Set peer address. */
+    void setPeerAddress(const address_t &address)
+    {
+        peerAddress = address;
+    }
+
+    /** Set get local resolvable random address if privacy is used. */
+    void setLocalResolvablePrivateAddress(const address_t &address)
+    {
+        localResolvablePrivateAddress = address;
+    }
+
+    /** Set peer resolvable private address if privacy is used. */
+    void setPeerResolvablePrivateAddress(const address_t &address)
+    {
+        peerResolvablePrivateAddress = address;
+    }
+
 private:
     ble_error_t status;
     connection_handle_t connectionHandle;
+    address_t peerAddress;
     connection_role_t ownRole;
     peer_address_type_t peerAddressType;
-    const address_t &peerAddress;
-    const address_t &localResolvablePrivateAddress;
-    const address_t &peerResolvablePrivateAddress;
+    address_t localResolvablePrivateAddress;
     conn_interval_t connectionInterval;
+    address_t peerResolvablePrivateAddress;
     slave_latency_t connectionLatency;
     supervision_timeout_t supervisionTimeout;
     uint16_t masterClockAccuracy;
@@ -519,15 +575,47 @@ struct PeriodicAdvertisingSyncLoss {
  */
 struct ScanTimeoutEvent { };
 
+/**
+ * Event produced when advertising start.
+ *
+ * @see ble::Gap::EventHandler::onAdvertisingStart().
+ */
+struct AdvertisingStartEvent {
+#if !defined(DOXYGEN_ONLY)
+
+    /** Create an advertising start event.
+     *
+     * @param advHandle Advertising set handle.
+     */
+    AdvertisingStartEvent(advertising_handle_t advHandle) :
+        advHandle(advHandle)
+    {
+    }
+
+#endif
+
+    /** Get advertising handle. */
+    advertising_handle_t getAdvHandle() const
+    {
+        return advHandle;
+    }
+
+private:
+    advertising_handle_t advHandle;
+};
+
 /**
  * Event produced when advertising ends.
  *
  * @see ble::Gap::EventHandler::onAdvertisingEnd().
+ *
+ * @note The connection handle, connected flag and completed_event fields are
+ * valid if the flag legacy is not set to true.
  */
 struct AdvertisingEndEvent {
 #if !defined(DOXYGEN_ONLY)
 
-    /** Create advertising end event.
+    /** Create an extended advertising end event.
      *
      * @param advHandle Advertising set handle.
      * @param connection Connection handle.
@@ -543,7 +631,19 @@ struct AdvertisingEndEvent {
         advHandle(advHandle),
         connection(connection),
         completed_events(completed_events),
-        connected(connected)
+        connected(connected),
+        legacy(false)
+    {
+    }
+
+    /** Create a legacy advertising end event.
+     */
+    AdvertisingEndEvent() :
+        advHandle(LEGACY_ADVERTISING_HANDLE),
+        connection(),
+        completed_events(0),
+        connected(false),
+        legacy(true)
     {
     }
 
@@ -573,11 +673,22 @@ struct AdvertisingEndEvent {
         return connected;
     }
 
+    /** Is the end of legacy advertising.
+     *
+     * If it is the return of getConnection() getCompleted_events() and isConnected()
+     * must be discarded
+     */
+    bool isLegacy() const
+    {
+        return legacy;
+    }
+
 private:
     advertising_handle_t advHandle;
     connection_handle_t connection;
     uint8_t completed_events;
     bool connected;
+    bool legacy;
 };
 
 /**

connectivity/FEATURE_BLE/include/ble/gap/Types.h

@@ -121,6 +121,16 @@ typedef Duration<uint16_t, 10000, Range<0x0A, 0x4000> > sync_timeout_t;
  */
 typedef Duration<uint16_t, 1250, Range<0x06, 0xFFFF> > periodic_interval_t;
 
+/**
+ * Resolvable address timeout.
+ *
+ * The duration is in seconds and ranges from 1 to 0xA1B8. The default value is
+ * 900 seconds.
+ */
+using resolvable_address_timeout_t = Duration<
+    uint16_t, second_t::TIME_BASE, Range<1, 0xA1B8, 0x0384>
+>;
+
 /**
  * Number of connection events that can be skipped by the slave.
  *
@@ -445,8 +455,8 @@ struct scanning_filter_policy_t : SafeEnum<scanning_filter_policy_t, uint8_t> {
         NO_FILTER = 0x00,
 
         /**
-        * Accept only advertising packets from devices in the whitelist except
-        * directed advertising packets not addressed to this device.
+        * Accept only advertising packets from devices in the whitelist.
+        * Directed advertising packets not addressed to this device will be ignored.
         */
         FILTER_ADVERTISING = 0x01,