1.. _bluetooth_mesh_provisioning:
2
3Provisioning
4############
5
6Provisioning is the process of adding devices to a mesh network. It requires
7two devices operating in the following roles:
8
9* The *provisioner* represents the network owner, and is responsible for
10  adding new nodes to the mesh network.
11* The *provisionee* is the device that gets added to the network through the
12  Provisioning process. Before the provisioning process starts, the
13  provisionee is an *unprovisioned device*.
14
15The Provisioning module in the Zephyr Bluetooth mesh stack supports both the
16Advertising and GATT Provisioning bearers for the provisionee role, as well as
17the Advertising Provisioning bearer for the provisioner role.
18
19The Provisioning process
20************************
21
22All Bluetooth mesh nodes must be provisioned before they can participate in a
23Bluetooth mesh network. The Provisioning API provides all the functionality
24necessary for a device to become a provisioned mesh node.
25Provisioning is a five-step process, involving the following steps:
26
27* Beaconing
28* Invitation
29* Public key exchange
30* Authentication
31* Provisioning data transfer
32
33Beaconing
34=========
35
36To start the provisioning process, the unprovisioned device must first start
37broadcasting the Unprovisioned Beacon. This makes it visible to nearby
38provisioners, which can initiate the provisioning. To indicate that the device
39needs to be provisioned, call :c:func:`bt_mesh_prov_enable`. The device
40starts broadcasting the Unprovisioned Beacon with the device UUID and the
41``OOB information`` field, as specified in the ``prov`` parameter passed to
42:c:func:`bt_mesh_init`. Additionally, a Uniform Resource Identifier (URI)
43may be specified, which can point the provisioner to the location of some Out
44Of Band information, such as the device's public key or an authentication
45value database. The URI is advertised in a separate beacon, with a URI hash
46included in the unprovisioned beacon, to tie the two together.
47
48
49Uniform Resource Identifier
50---------------------------
51
52The Uniform Resource Identifier shall follow the format specified in the
53Bluetooth Core Specification Supplement. The URI must start with a URI scheme,
54encoded as a single utf-8 data point, or the special ``none`` scheme, encoded
55as ``0x01``. The available schemes are listed on the `Bluetooth website
56<https://www.bluetooth.com/specifications/assigned-numbers/>`_.
57
58Examples of encoded URIs:
59
60.. list-table:: URI encoding examples
61
62  * - URI
63    - Encoded
64  * - ``http://example.com``
65    - ``\x16//example.com``
66  * - ``https://www.zephyrproject.org/``
67    - ``\x17//www.zephyrproject.org/``
68  * - ``just a string``
69    - ``\x01just a string``
70
71Provisioning invitation
72=======================
73
74The provisioner initiates the Provisioning process by sending a Provisioning
75invitation. The invitations prompts the provisionee to call attention to
76itself using the Health Server
77:ref:`bluetooth_mesh_models_health_srv_attention`, if available.
78
79The Unprovisioned device automatically responds to the invite by presenting a
80list of its capabilities, including the supported Out of Band Authentication
81methods and algorithms.
82
83Public key exchange
84===================
85
86Before the provisioning process can begin, the provisioner and the unprovisioned
87device exchange public keys, either in-band or Out of Band (OOB).
88
89In-band public key exchange is a part of the provisioning process and always
90supported by the unprovisioned device and provisioner.
91
92If the application wants to support public key exchange via OOB, it needs to
93provide public and private keys to the mesh stack. The unprovisioned device
94will reflect this in its capabilities. The provisioner obtains the public key
95via any available OOB mechanism (e.g. the device may advertise a packet
96containing the public key or it can be encoded in a QR code printed on the
97device packaging). Note that even if the unprovisioned device has specified
98the public key for the Out of Band exchange, the provisioner may choose to
99exchange the public key in-band if it can't retrieve the public key via OOB
100mechanism. In this case, a new key pair will be generated by the mesh stack
101for each Provisioning process.
102
103To enable support of OOB public key on the unprovisioned device side,
104:kconfig:option:`CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY` needs to be enabled. The
105application must provide public and private keys before the Provisioning
106process is started by initializing pointers to
107:c:member:`bt_mesh_prov.public_key_be`
108and :c:member:`bt_mesh_prov.private_key_be`. The keys needs to be
109provided in big-endian bytes order.
110
111To provide the device's public key obtained via OOB,
112call :c:func:`bt_mesh_prov_remote_pub_key_set` on the provisioner side.
113
114Authentication
115==============
116
117After the initial exchange, the provisioner selects an Out of Band (OOB)
118Authentication method. This allows the user to confirm that the device the
119provisioner connected to is actually the device they intended, and not a
120malicious third party.
121
122The Provisioning API supports the following authentication methods for the
123provisionee:
124
125* **Static OOB:** An authentication value is assigned to the device in
126  production, which the provisioner can query in some application specific
127  way.
128* **Input OOB:** The user inputs the authentication value. The available input
129  actions are listed in :c:enum:`bt_mesh_input_action_t`.
130* **Output OOB:** Show the user the authentication value. The available output
131  actions are listed in :c:enum:`bt_mesh_output_action_t`.
132
133The application must provide callbacks for the supported authentication
134methods in :c:struct:`bt_mesh_prov`, as well as enabling the supported actions
135in :c:member:`bt_mesh_prov.output_actions` and
136:c:member:`bt_mesh_prov.input_actions`.
137
138When an Output OOB action is selected, the authentication value should be
139presented to the user when the output callback is called, and remain until the
140:c:member:`bt_mesh_prov.input_complete` or :c:member:`bt_mesh_prov.complete`
141callback is called. If the action is ``blink``, ``beep`` or ``vibrate``, the
142sequence should be repeated after a delay of three seconds or more.
143
144When an Input OOB action is selected, the user should be prompted when the
145application receives the :c:member:`bt_mesh_prov.input` callback. The user
146response should be fed back to the Provisioning API through
147:c:func:`bt_mesh_input_string` or :c:func:`bt_mesh_input_number`. If
148no user response is recorded within 60 seconds, the Provisioning process is
149aborted.
150
151If Provisionee wants to mandate OOB authentication, it is mandatory to use
152the BT_MESH_ECDH_P256_HMAC_SHA256_AES_CCM algorithm.
153
154Data transfer
155=============
156
157After the device has been successfully authenticated, the provisioner
158transfers the Provisioning data:
159
160* Unicast address
161* A network key
162* IV index
163* Network flags
164
165  * Key refresh
166  * IV update
167
168Additionally, a device key is generated for the node. All this data is stored
169by the mesh stack, and the provisioning :c:member:`bt_mesh_prov.complete`
170callback gets called.
171
172Provisioning security
173*********************
174
175Depending on the choice of public key exchange mechanism and authentication method,
176the provisioning process can be secure or insecure.
177
178On May 24th 2021, ANSSI `disclosed <https://kb.cert.org/vuls/id/799380>`_
179a set of vulnerabilities in the Bluetooth mesh provisioning protocol that showcased
180how the low entropy provided by the Blink, Vibrate, Push, Twist and
181Input/Output numeric OOB methods could be exploited in impersonation and MITM
182attacks. In response, the Bluetooth SIG has reclassified these OOB methods as
183insecure in the Mesh Profile specification `erratum 16350 <https://www.bluetooth.org/docman/handlers/DownloadDoc.ashx?doc_id=516072>`_,
184as AuthValue may be brute forced in real time. To ensure secure provisioning, applications
185should use a static OOB value and OOB public key transfer.
186
187API reference
188*************
189
190.. doxygengroup:: bt_mesh_prov
191