NimBLE Host Identity Reference

Introduction

The identity API provides facilities for querying and configuring your device’s addresses. BLE’s addressing scheme is quite involved; the summary that follows is only a brief introduction.

BLE defines four address types:

Type

Description

Identity?

Configured with

Public

Address assigned by manufacturer; the three most significant bytes form the manufacturer’s OUI.

Yes

N/A; read from controller at startup.

Static random

Randomly generated address.

Yes

ble_hs_id_set_rnd()

Resolvable private (RPA)

Address randomly generated from an identity address and an identity resolving key (IRK).

No

N/A; generated by controller periodically.

Non-resolvable private (NRPA)

Randomly generated address.

No

ble_hs_id_set_rnd()

Identity Addresses

The third column in the above table indicates the identity property of each address type. An identity address never changes, and a device can be identified by one of its unique identity addresses.

Non-identity addresses are used by devices supporting BLE privacy. A device using the privacy feature frequently changes its own address to a newly-generated non-identity address. By cycling its address, the device makes it impossible for eavesdroppers to track its location.

A device can have up to two identity addresses at once: one public and one static random. As indicated in the above table, the public identity address cannot be configured; the static random identity address can be set by calling ble_hs_id_set_rnd().

The address type is selected on a per-GAP-procedure basis. Each time you initiate a GAP procedure, you indicate which address type the device should use for the duration of the procedure.

API

int ble_hs_id_gen_rnd(int nrpa, ble_addr_t *out_addr)

Generates a new random address.

This function does not configure the device with the new address; the caller can use the address in subsequent operations.

Parameters:

  • nrpa – The type of random address to generate: 0: static 1: non-resolvable private

  • out_addr – On success, the generated address gets written here.

Returns:

0 on success; nonzero on failure.

int ble_hs_id_set_rnd(const uint8_t *rnd_addr)

Sets the device’s random address.

The address type (static vs. non-resolvable private) is inferred from the most-significant byte of the address. The address is specified in host byte order (little-endian!).

Parameters:

  • rnd_addr – The random address to set.

Returns:

0 on success; BLE_HS_EINVAL if the specified address is not a valid static random or non-resolvable private address. Other nonzero on error.

int ble_hs_id_copy_addr(uint8_t id_addr_type, uint8_t *out_id_addr, int *out_is_nrpa)

Retrieves one of the device’s identity addresses.

The device can have two identity addresses: one public and one random. The id_addr_type argument specifies which of these two addresses to retrieve.

Parameters:

  • id_addr_type – The type of identity address to retrieve. Valid values are: o BLE_ADDR_PUBLIC o BLE_ADDR_RANDOM

  • out_id_addr – On success, the requested identity address is copied into this buffer. The buffer must be at least six bytes in size. Pass NULL if you do not require this information.

  • out_is_nrpa – On success, the pointed-to value indicates whether the retrieved address is a non-resolvable private address. Pass NULL if you do not require this information.

Returns:

0 on success; BLE_HS_EINVAL if an invalid address type was specified; BLE_HS_ENOADDR if the device does not have an identity address of the requested type; Other BLE host core code on error.

int ble_hs_id_infer_auto(int privacy, uint8_t *out_addr_type)

Determines the best address type to use for automatic address type resolution.

Calculation of the best address type is done as follows:

if privacy requested: if we have a random static address: –> RPA with static random ID else –> RPA with public ID end else if we have a random static address: –> random static address else –> public address end end

Parameters:

  • privacy – (0/1) Whether to use a private address.

  • out_addr_type – On success, the “own addr type” code gets written here.

Returns:

0 if an address type was successfully inferred. BLE_HS_ENOADDR if the device does not have a suitable address. Other BLE host core code on error.