From a8ac925b4f0781937a99bb4258fa8f806dc4aed4 Mon Sep 17 00:00:00 2001
From: paul-szczepanek-arm
 <33840200+paul-szczepanek-arm@users.noreply.github.com>
Date: Thu, 17 May 2018 16:48:49 +0100
Subject: [PATCH] privacy doxygen overview

---
 features/FEATURE_BLE/ble/Gap.h | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/features/FEATURE_BLE/ble/Gap.h b/features/FEATURE_BLE/ble/Gap.h
index 052931b801..bb4f264cf3 100644
--- a/features/FEATURE_BLE/ble/Gap.h
+++ b/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