Provisioning

Provisioning. More...

Data Structures
struct	bt_mesh_dev_capabilities
	Device Capabilities. More...
struct	bt_mesh_prov
	Provisioning properties & capabilities. More...

Enumerations
enum	{ BT_MESH_PROV_AUTH_CMAC_AES128_AES_CCM , BT_MESH_PROV_AUTH_HMAC_SHA256_AES_CCM }
	Available authentication algorithms. More...
enum	{ BT_MESH_STATIC_OOB_AVAILABLE = BIT(0) , BT_MESH_OOB_AUTH_REQUIRED = BIT(1) }
	OOB Type field values. More...
enum	bt_mesh_output_action_t {   BT_MESH_NO_OUTPUT = 0 , BT_MESH_BLINK = BIT(0) , BT_MESH_BEEP = BIT(1) , BT_MESH_VIBRATE = BIT(2) ,   BT_MESH_DISPLAY_NUMBER = BIT(3) , BT_MESH_DISPLAY_STRING = BIT(4) }
	Available Provisioning output authentication actions. More...
enum	bt_mesh_input_action_t {   BT_MESH_NO_INPUT = 0 , BT_MESH_PUSH = BIT(0) , BT_MESH_TWIST = BIT(1) , BT_MESH_ENTER_NUMBER = BIT(2) ,   BT_MESH_ENTER_STRING = BIT(3) }
	Available Provisioning input authentication actions. More...
enum	bt_mesh_prov_bearer_t { BT_MESH_PROV_ADV = BIT(0) , BT_MESH_PROV_GATT = BIT(1) , BT_MESH_PROV_REMOTE = BIT(2) }
	Available Provisioning bearers. More...
enum	bt_mesh_prov_oob_info_t {   BT_MESH_PROV_OOB_OTHER = BIT(0) , BT_MESH_PROV_OOB_URI = BIT(1) , BT_MESH_PROV_OOB_2D_CODE = BIT(2) , BT_MESH_PROV_OOB_BAR_CODE = BIT(3) ,   BT_MESH_PROV_OOB_NFC = BIT(4) , BT_MESH_PROV_OOB_NUMBER = BIT(5) , BT_MESH_PROV_OOB_STRING = BIT(6) , BT_MESH_PROV_OOB_CERTIFICATE = BIT(7) ,   BT_MESH_PROV_OOB_RECORDS = BIT(8) , BT_MESH_PROV_OOB_ON_BOX = BIT(11) , BT_MESH_PROV_OOB_IN_BOX = BIT(12) , BT_MESH_PROV_OOB_ON_PAPER = BIT(13) ,   BT_MESH_PROV_OOB_IN_MANUAL = BIT(14) , BT_MESH_PROV_OOB_ON_DEV = BIT(15) }
	Out of Band information location. More...

Functions
int	bt_mesh_input_string (const char *str)
	Provide provisioning input OOB string.
int	bt_mesh_input_number (uint32_t num)
	Provide provisioning input OOB number.
int	bt_mesh_prov_remote_pub_key_set (const uint8_t public_key[64])
	Provide Device public key.
int	bt_mesh_auth_method_set_input (bt_mesh_input_action_t action, uint8_t size)
	Use Input OOB authentication.
int	bt_mesh_auth_method_set_output (bt_mesh_output_action_t action, uint8_t size)
	Use Output OOB authentication.
int	bt_mesh_auth_method_set_static (const uint8_t *static_val, uint8_t size)
	Use static OOB authentication.
int	bt_mesh_auth_method_set_none (void)
	Don't use OOB authentication.
int	bt_mesh_prov_enable (bt_mesh_prov_bearer_t bearers)
	Enable specific provisioning bearers.
int	bt_mesh_prov_disable (bt_mesh_prov_bearer_t bearers)
	Disable specific provisioning bearers.
int	bt_mesh_provision (const uint8_t net_key[16], uint16_t net_idx, uint8_t flags, uint32_t iv_index, uint16_t addr, const uint8_t dev_key[16])
	Provision the local Mesh Node.
int	bt_mesh_provision_adv (const uint8_t uuid[16], uint16_t net_idx, uint16_t addr, uint8_t attention_duration)
	Provision a Mesh Node using PB-ADV.
int	bt_mesh_provision_gatt (const uint8_t uuid[16], uint16_t net_idx, uint16_t addr, uint8_t attention_duration)
	Provision a Mesh Node using PB-GATT.
int	bt_mesh_provision_remote (struct bt_mesh_rpr_cli *cli, const struct bt_mesh_rpr_node *srv, const uint8_t uuid[16], uint16_t net_idx, uint16_t addr)
	Provision a Mesh Node using PB-Remote.
int	bt_mesh_reprovision_remote (struct bt_mesh_rpr_cli *cli, struct bt_mesh_rpr_node *srv, uint16_t addr, bool comp_change)
	Reprovision a Mesh Node using PB-Remote.
bool	bt_mesh_is_provisioned (void)
	Check if the local node has been provisioned.

Detailed Description

Provisioning.

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <zephyr/bluetooth/mesh/main.h>

Available authentication algorithms.

Enumerator
BT_MESH_PROV_AUTH_CMAC_AES128_AES_CCM
BT_MESH_PROV_AUTH_HMAC_SHA256_AES_CCM

anonymous enum

anonymous enum

#include <zephyr/bluetooth/mesh/main.h>

OOB Type field values.

Enumerator
BT_MESH_STATIC_OOB_AVAILABLE	Static OOB information available.
BT_MESH_OOB_AUTH_REQUIRED	OOB authentication required.

bt_mesh_input_action_t

enum bt_mesh_input_action_t

#include <zephyr/bluetooth/mesh/main.h>

Available Provisioning input authentication actions.

Enumerator
BT_MESH_NO_INPUT
BT_MESH_PUSH	Push.
BT_MESH_TWIST	Twist.
BT_MESH_ENTER_NUMBER	Input number.
BT_MESH_ENTER_STRING	Input alphanumeric.

bt_mesh_output_action_t

enum bt_mesh_output_action_t

#include <zephyr/bluetooth/mesh/main.h>

Available Provisioning output authentication actions.

Enumerator
BT_MESH_NO_OUTPUT
BT_MESH_BLINK	Blink.
BT_MESH_BEEP	Beep.
BT_MESH_VIBRATE	Vibrate.
BT_MESH_DISPLAY_NUMBER	Output numeric.
BT_MESH_DISPLAY_STRING	Output alphanumeric.

bt_mesh_prov_bearer_t

enum bt_mesh_prov_bearer_t

#include <zephyr/bluetooth/mesh/main.h>

Available Provisioning bearers.

Enumerator
BT_MESH_PROV_ADV	PB-ADV bearer.
BT_MESH_PROV_GATT	PB-GATT bearer.
BT_MESH_PROV_REMOTE	PB-Remote bearer.

bt_mesh_prov_oob_info_t

enum bt_mesh_prov_oob_info_t

#include <zephyr/bluetooth/mesh/main.h>

Out of Band information location.

Enumerator
BT_MESH_PROV_OOB_OTHER	Other.
BT_MESH_PROV_OOB_URI	Electronic / URI.
BT_MESH_PROV_OOB_2D_CODE	2D machine-readable code
BT_MESH_PROV_OOB_BAR_CODE	Bar Code.
BT_MESH_PROV_OOB_NFC	Near Field Communication (NFC)
BT_MESH_PROV_OOB_NUMBER	Number.
BT_MESH_PROV_OOB_STRING	String.
BT_MESH_PROV_OOB_CERTIFICATE	Support for certificate-based provisioning.
BT_MESH_PROV_OOB_RECORDS	Support for provisioning records.
BT_MESH_PROV_OOB_ON_BOX	On box.
BT_MESH_PROV_OOB_IN_BOX	Inside box.
BT_MESH_PROV_OOB_ON_PAPER	On piece of paper.
BT_MESH_PROV_OOB_IN_MANUAL	Inside manual.
BT_MESH_PROV_OOB_ON_DEV	On device.

Function Documentation

bt_mesh_auth_method_set_input()

int bt_mesh_auth_method_set_input	(	bt_mesh_input_action_t	action,
		uint8_t	size
	)

#include <zephyr/bluetooth/mesh/main.h>

Use Input OOB authentication.

Provisioner only.

Instruct the unprovisioned device to use the specified Input OOB authentication action. When using BT_MESH_PUSH, BT_MESH_TWIST or BT_MESH_ENTER_NUMBER, the bt_mesh_prov::output_number callback is called with a random number that has to be entered on the unprovisioned device.

When using BT_MESH_ENTER_STRING, the bt_mesh_prov::output_string callback is called with a random string that has to be entered on the unprovisioned device.

Parameters

action	Authentication action used by the unprovisioned device.
size	Authentication size.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_auth_method_set_none()

int bt_mesh_auth_method_set_none

(

void

)

#include <zephyr/bluetooth/mesh/main.h>

Don't use OOB authentication.

Provisioner only.

Don't use any authentication when provisioning new devices. This is the default behavior.

Warning

Not using any authentication exposes the mesh network to impersonation attacks, where attackers can pretend to be the unprovisioned device to gain access to the network. Authentication is strongly encouraged.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_auth_method_set_output()

int bt_mesh_auth_method_set_output	(	bt_mesh_output_action_t	action,
		uint8_t	size
	)

#include <zephyr/bluetooth/mesh/main.h>

Use Output OOB authentication.

Provisioner only.

Instruct the unprovisioned device to use the specified Output OOB authentication action. The bt_mesh_prov::input callback will be called.

When using BT_MESH_BLINK, BT_MESH_BEEP, BT_MESH_VIBRATE or BT_MESH_DISPLAY_NUMBER, and the application has to call bt_mesh_input_number with the random number indicated by the unprovisioned device.

When using BT_MESH_DISPLAY_STRING, the application has to call bt_mesh_input_string with the random string displayed by the unprovisioned device.

Parameters

action	Authentication action used by the unprovisioned device.
size	Authentication size.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_auth_method_set_static()

int bt_mesh_auth_method_set_static	(	const uint8_t *	static_val,
		uint8_t	size
	)

#include <zephyr/bluetooth/mesh/main.h>

Use static OOB authentication.

Provisioner only.

Instruct the unprovisioned device to use static OOB authentication, and use the given static authentication value when provisioning.

Parameters

static_val	Static OOB value.
size	Static OOB value size.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_input_number()

int bt_mesh_input_number

(

uint32_t

num

)

#include <zephyr/bluetooth/mesh/main.h>

Provide provisioning input OOB number.

This is intended to be called after the bt_mesh_prov input callback has been called with BT_MESH_ENTER_NUMBER as the action.

Parameters

num

Number.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_input_string()

int bt_mesh_input_string

(

const char *

str

)

#include <zephyr/bluetooth/mesh/main.h>

Provide provisioning input OOB string.

This is intended to be called after the bt_mesh_prov input callback has been called with BT_MESH_ENTER_STRING as the action.

Parameters

str

String.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_is_provisioned()

bool bt_mesh_is_provisioned

(

void

)

#include <zephyr/bluetooth/mesh/main.h>

Check if the local node has been provisioned.

This API can be used to check if the local node has been provisioned or not. It can e.g. be helpful to determine if there was a stored network in flash, i.e. if the network was restored after calling settings_load().

Returns

True if the node is provisioned. False otherwise.

bt_mesh_prov_disable()

int bt_mesh_prov_disable

(

bt_mesh_prov_bearer_t

bearers

)

#include <zephyr/bluetooth/mesh/main.h>

Disable specific provisioning bearers.

Disable one or more provisioning bearers.

Parameters

bearers

Bit-wise or of provisioning bearers.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_prov_enable()

int bt_mesh_prov_enable

(

bt_mesh_prov_bearer_t

bearers

)

#include <zephyr/bluetooth/mesh/main.h>

Enable specific provisioning bearers.

Enable one or more provisioning bearers.

Parameters

bearers

Bit-wise or of provisioning bearers.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_prov_remote_pub_key_set()

int bt_mesh_prov_remote_pub_key_set

(

const uint8_t

public_key[64]

)

#include <zephyr/bluetooth/mesh/main.h>

Provide Device public key.

Parameters

public_key

Device public key in big-endian.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_provision()

int bt_mesh_provision	(	const uint8_t	net_key[16],
		uint16_t	net_idx,
		uint8_t	flags,
		uint32_t	iv_index,
		uint16_t	addr,
		const uint8_t	dev_key[16]
	)

#include <zephyr/bluetooth/mesh/main.h>

Provision the local Mesh Node.

This API should normally not be used directly by the application. The only exception is for testing purposes where manual provisioning is desired without an actual external provisioner.

Parameters

net_key	Network Key
net_idx	Network Key Index
flags	Provisioning Flags
iv_index	IV Index
addr	Primary element address
dev_key	Device Key

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_provision_adv()

int bt_mesh_provision_adv	(	const uint8_t	uuid[16],
		uint16_t	net_idx,
		uint16_t	addr,
		uint8_t	attention_duration
	)

#include <zephyr/bluetooth/mesh/main.h>

Provision a Mesh Node using PB-ADV.

Parameters

uuid	UUID
net_idx	Network Key Index
addr	Address to assign to remote device. If addr is 0, the lowest available address will be chosen.
attention_duration	The attention duration to be send to remote device

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_provision_gatt()

int bt_mesh_provision_gatt	(	const uint8_t	uuid[16],
		uint16_t	net_idx,
		uint16_t	addr,
		uint8_t	attention_duration
	)

#include <zephyr/bluetooth/mesh/main.h>

Provision a Mesh Node using PB-GATT.

Parameters

uuid	UUID
net_idx	Network Key Index
addr	Address to assign to remote device. If addr is 0, the lowest available address will be chosen.
attention_duration	The attention duration to be send to remote device

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_provision_remote()

int bt_mesh_provision_remote	(	struct bt_mesh_rpr_cli *	cli,
		const struct bt_mesh_rpr_node *	srv,
		const uint8_t	uuid[16],
		uint16_t	net_idx,
		uint16_t	addr
	)

#include <zephyr/bluetooth/mesh/main.h>

Provision a Mesh Node using PB-Remote.

Parameters

cli	Remote Provisioning Client Model to provision with.
srv	Remote Provisioning Server that should be used to tunnel the provisioning.
uuid	UUID of the unprovisioned node
net_idx	Network Key Index to give to the unprovisioned node.
addr	Address to assign to remote device. If addr is 0, the lowest available address will be chosen.

Returns

Zero on success or (negative) error code otherwise.

bt_mesh_reprovision_remote()

int bt_mesh_reprovision_remote	(	struct bt_mesh_rpr_cli *	cli,
		struct bt_mesh_rpr_node *	srv,
		uint16_t	addr,
		bool	comp_change
	)

#include <zephyr/bluetooth/mesh/main.h>

Reprovision a Mesh Node using PB-Remote.

Reprovisioning can be used to change the device key, unicast address and composition data of another device. The reprovisioning procedure uses the same protocol as normal provisioning, with the same level of security.

There are three tiers of reprovisioning:

1. Refreshing the device key
2. Refreshing the device key and node address. Composition data may change, including the number of elements.
3. Refreshing the device key and composition data, in case the composition data of the target node changed due to a firmware update or a similar procedure.

The target node indicates that its composition data changed by instantiating its composition data page 128. If the number of elements have changed, it may be necessary to move the unicast address of the target node as well, to avoid overlapping addresses.

Note

Changing the unicast addresses of the target node requires changes to all nodes that publish directly to any of the target node's models.

Parameters

cli	Remote Provisioning Client Model to provision on
srv	Remote Provisioning Server to reprovision
addr	Address to assign to remote device. If addr is 0, the lowest available address will be chosen.
comp_change	The target node has indicated that its composition data has changed. Note that the target node will reject the update if this isn't true.

Returns

Zero on success or (negative) error code otherwise.