xref: /nrf52832-nimble/packages/NimBLE-latest/docs/ble_hs/ble_hs_id.rst (revision 042d53a763ad75cb1465103098bb88c245d95138) 
1NimBLE Host Identity Reference
2------------------------------
3
4Introduction
5~~~~~~~~~~~~
6
7The identity API provides facilities for querying and configuring your device's addresses. BLE's addressing scheme is
8quite involved; the summary that follows is only a brief introduction.
9
10BLE defines four address types:
11
12+---------------------------------+---------------------------------------------------------------------------------------------------+-------------+----------------------------------------------+
13| Type                            | Description                                                                                       | Identity?   | Configured with                              |
14+=================================+===================================================================================================+=============+==============================================+
15| Public                          | Address assigned by manufacturer; the three most significant bytes form the manufacturer's OUI.   | Yes         | N/A; read from controller at startup.        |
16+---------------------------------+---------------------------------------------------------------------------------------------------+-------------+----------------------------------------------+
17| Static random                   | Randomly generated address.                                                                       | Yes         | *ble_hs_id_set_rnd()*                        |
18+---------------------------------+---------------------------------------------------------------------------------------------------+-------------+----------------------------------------------+
19| Resolvable private (RPA)        | Address randomly generated from an identity address and an identity resolving key (IRK).          | No          | N/A; generated by controller periodically.   |
20+---------------------------------+---------------------------------------------------------------------------------------------------+-------------+----------------------------------------------+
21| Non-resolvable private (NRPA)   | Randomly generated address.                                                                       | No          | *ble_hs_id_set_rnd()*                        |
22+---------------------------------+---------------------------------------------------------------------------------------------------+-------------+----------------------------------------------+
23
24Identity Addresses
25^^^^^^^^^^^^^^^^^^
26
27The third column in the above table indicates the *identity* property of each address type. An identity address never
28changes, and a device can be identified by one of its unique identity addresses.
29
30Non-identity addresses are used by devices supporting BLE privacy. A device using the privacy feature frequently changes
31its own address to a newly-generated non-identity address. By cycling its address, the device makes it impossible for
32eavesdroppers to track its location.
33
34A device can have up to two identity addresses at once: one public and one static random. As indicated in the above table,
35the public identity address cannot be configured; the static random identity address can be set by calling *ble_hs_id_set_rnd()*.
36
37The address type is selected on a per-GAP-procedure basis. Each time you initiate a GAP procedure, you indicate which
38address type the device should use for the duration of the procedure.
39
40Header
41~~~~~~
42
43.. code-block:: cpp
44
45    #include "host/ble_hs.h"
46