privacy doxygen overview

features/FEATURE_BLE/ble/Gap.h

@@ -121,6 +121,27 @@ class GapAdvertisingData;
  * gap.startAdvertising();
  * @endcode
  *
+ * @par Privacy
+ *
+ * Privacy is a feature that allows a device to avoid being tracked by other
+ * (untrusted) devices. The device achieves it by periodically generating a
+ * new random address. The random address may be a resolvable random address,
+ * enabling trusted devices to recognise it as belonging to the same
+ * device. These trusted devices receive an Identity Resolution Key (IRK)
+ * during pairing. This is handled by the SecurityManager and relies on the
+ * other device accepting and storing the IRK.
+ *
+ * Privacy needs to be enabled by calling enablePrivacy() after having
+ * initialised the SecurityManager since privacy requires SecurityManager
+ * to handle IRKs. The behaviour of privacy enabled devices is set by
+ * using setCentralPrivacyConfiguration() which specifies what the device
+ * should be with devices using random addresses. Random addresses
+ * generated by privacy enabled device can be of two types: resolvable
+ * (by devices who have the IRK) and unresolvable. Unresolvable addresses
+ * can't be used for connecting and connectable advertising therefore a
+ * resolvable one will be used for these regardless of the privacy
+ * configuration.
+ *
  * @par Scanning
  *
  * Scanning consist of listening for peer advertising packets. From a scan, a