Skip to contentSkip to conversation

mesh: Add APIs for Provisioner and Config Client

PATCH Superseded Brian Gix 2 participants 5 messages Mar 19, 2019 – Mar 20, 2019 Bluetooth drivers

v3 of 6 Superseded Latest is v6 →

lore
Share & tools
lore

Brian Gix

author
#0 lore raw

v3 cover mesh: Add APIs for Provisioner and Config Client

Version 3 of this patch was made after a larger conversation that included Marcel, and focused on preserving the security of all encryption keys in the system including Device Keys, Application Keys and Network Keys. This modified revision therefore avoids all passing of Keys of any kind over the D-Bus interface, and puts off until later the question of how to export a transferable Key and Node database until a later time.

Brian Gix (1):
mesh: Add APIs for Provisioner and Config Client

 doc/mesh-api.txt | 363 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 348 insertions(+), 15 deletions(-)
Signature · 1 line
2.14.5
author
#1 lore raw

PATCH v3 1/1 mesh: Add APIs for Provisioner and Config Client

The added D-Bus APIs enable Applications to function in a Provisioner Initiator role, and as a Configuration Client.

---
 doc/mesh-api.txt | 363 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 348 insertions(+), 15 deletions(-)
doc/mesh-api.txt +348 -15
index 0b341a0f9..85d1f83d2 100644
@@ -30,6 +30,7 @@ Methods:
 			org.bluez.mesh.Error.InvalidArguments
 
 	void Cancel(void)
+
 		Cancels an outstanding provisioning request initiated by Join()
 		method.
 
@@ -109,6 +110,37 @@ Methods:
 		PossibleErrors:
 			org.bluez.mesh.Error.NotFound
 
+	uint64 token CreateNetwork(object app_root, array{byte}[16] uuid)
+
+		This is the first method that an application calls to become
+		a Provisioner node, and a Configuration Client on a newly
+		created Mesh Network.
+
+		The app_root parameter is a D-Bus object root path of the
+		application that implements org.bluez.mesh.Application1
+		interface, and a org.bluez.mesh.Provisioner1 interface. The
+		application represents a node where child mesh elements have
+		their own objects that implement org.bluez.mesh.Element1
+		interface. The application hierarchy also contains a provision
+		agent object that implements org.bluez.mesh.ProvisionAgent1
+		interface. The standard DBus.ObjectManager interface must be
+		available on the app_root path.
+
+		The uuid parameter is a 16-byte array that contains Device UUID.
+
+		The returned token must be preserved by the application in
+		order to authenticate itself to the mesh daemon and attach to
+		the network as a mesh node by calling Attach() method or
+		permanently remove the identity of the mesh node by calling
+		Leave() method.
+
+		The other information the bluetooth-meshd daemon will preserve
+		about the initial node, is to give it the initial primary
+		unicast address (0x0001), and create and assign a net_key as the
+		primary network net_index (0x000).
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
 
 Mesh Node Hierarchy
 ===================
@@ -146,6 +178,30 @@ Methods:
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.NotFound
 
+	void SendWithDeviceKey(object element_path, uint16 destination,
+					uint16 net_index, array{byte} data)
+
+		This method is used to send a message originated by a local
+		model encoded with the device key of the remote node.
+
+		The element_path parameter is the object path of an element from
+		a collection of the application elements (see Mesh Application
+		Hierarchy section).
+
+		The destination parameter contains the destination address. This
+		destination must be a uint16 to a unicast address, or a well
+		known group address.
+
+		The net_index parameter is the subnet index of the network on
+		which the message is to be sent.
+
+		The data parameter is an outgoing message to be encypted by the
+		meshd daemon and sent on.
+
+		Possible errors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotFound
+
 	void Publish(object element_path, uint16 model, array{byte} data)
 
 		This method is used to send a publication originated by a local
@@ -224,12 +280,211 @@ Properties:
 		This property indicates whether the periodic beaconing is
 		enabled (true) or disabled (false).
 
+	uint8 BeaconFlags [read-only]
+
+		This property may be read at any time to determine the flag
+		field setting on sent and received beacons of the primary
+		network key.
+
+	uint32 IvIndex [read-only]
+
+		This property may be read at any time to determine the IV_Index
+		that the current network is on. This information is only useful
+		for provisioning.
+
 	uint32 SecondsSinceLastHeard [read-only]
 
 		This property may be read at any time to determine the number of
 		seconds since mesh network layer traffic was last detected on
 		this node's network.
 
+Mesh Provisioning Hierarchy
+============================
+Service		org.bluez.mesh
+Interface	org.bluez.mesh.Provisioning1
+Object path	/org/bluez/mesh/node<xxxx>
+		where xxxx is a 4-digit hexadecimal number generated by daemon
+
+Methods:
+	void UnprovisionedScan(uint16 seconds)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to start listening
+		(scanning) for unprovisioned devices in the area. Scanning
+		will continue for the specified number of seconds, or, if 0 is
+		specified, then continuously until UnprovisionedScanCancel() is
+		called or if AddNode() method is called.
+
+		Each time a unique unprovisioned beacon is heard, the
+		ScanResult() method on the app will be called with the result.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.NotAuthorized
+
+	void UnprovisionedScanCancel(void)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to stop listening
+		(scanning) for unprovisioned devices in the area.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.NotAuthorized
+
+	void AddNode(array{byte}[16] uuid)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to add the
+		unprovisioned device specified by uuid, to the Network.
+
+		The uuid parameter is a 16-byte array that contains Device UUID
+		of the unprovisioned device to be added to the network.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+
+	void AddNetKey(uint16 net_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate and add a new
+		network subnet key.
+
+		The net_index parameter is a 12-bit value (0x001-0xFFF)
+		specifying which net key to add.
+
+		This call affects the local bluetooth-daemon key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.AlreadyExists
+
+	void UpdateNetKey(uint16 net_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate a new network
+		subnet key, and set it's key refresh state to Phase 1.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which net key to update. Note that the subnet must
+		exist prior to updating.
+
+		This call affects the local bluetooth-daemon key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteNetKey(uint16 net_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete a subnet.
+
+		The net_index parameter is a 12-bit value (0x001-0xFFF)
+		specifying which net key to delete. The primary net key (0x000)
+		may not be deleted.
+
+		This call affects the local bluetooth-daemon key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void SetKeyPhase(uint16 net_index, uint8 phase)
+		This method is used to set the master key update phase of the
+		given subnet.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which subnet phase to set.
+
+		The phase parameter is used to cycle the local key database
+		through the phases as defined by the Mesh Profile Specification.
+		Allowed values:
+			0 - Cancel Key Refresh (May only be called from Phase 1,
+				and should never be called once the new key has
+				started propagating)
+			1 - Invalid Argument (see NetKeyUpdate method)
+			2 - Go to Phase 2 (May only be called from Phase 1)
+			3 - Complete Key Refresh procedure (May only be called
+				from Phase 2)
+
+		This call affects the local bluetooth-daemon key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void AddAppKey(uint16 net_index, uint16 app_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate and add a new
+		application key.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which net key to bind the application key to.
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to add.
+
+		This call affects the local bluetooth-daemon key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.AlreadyExists
+
+	void UpdateAppKey(uint16 app_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate a new
+		application key.
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to update. Note that the subnet that
+		the key is bound to must exist and be in Phase 1.
+
+		This call affects the local bluetooth-daemon key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteAppKey(uint16 app_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete an application
+		key.
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to delete.
+
+		This call affects the local bluetooth-daemon key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteRemoteNode(uint16 primary, uint8 cnt)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete a remote node
+		from the local device key database.
+
+		The primary parameter specifies the unicast address of the
+		the node being deleted, and the number of elements that were
+		assigned to it.
+
+		This call affects the local bluetooth-daemon key database only.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
 
 Mesh Application Hierarchy
 ==========================
@@ -247,6 +502,7 @@ An example mesh application hierarchy may look like this:
 			|   - org.freedesktop.DBus.ObjectManager
 			|   - org.bluez.mesh.Application1
 			|   - org.bluez.mesh.Attention1 (optional)
+			|   - org.bluez.mesh.Provisioner1 (optional,Provisioner)
 			|
 			-> /com/example/agent
 			| |   - org.bluez.mesh.ProvisionAgent1
@@ -325,6 +581,22 @@ Methods:
 
 		The data parameter is the incoming message.
 
+	void DevKeyMessageReceived(uint16 source, uint16 net_index,
+							array{byte} data)
+
+		This method is called by meshd daemon when a message arrives
+		addressed to the application, which was sent with the remote
+		node's device key.
+
+		The source parameter is unicast address of the remote
+		node-element that sent the message.
+
+		The net_index parameter indicates what subnet the message was
+		received on, and if a response is required, the same subnet
+		must be used to send the response.
+
+		The data parameter is the incoming message.
+
 	void UpdateModelConfiguration(uint16 model_id, dict config)
 
 		This method is called by bluetooth-meshd daemon when a model's
@@ -383,7 +655,7 @@ Object path	freely definable
 This is an optional interface that implements health attention timer.
 
 Methods:
-	void SetTimer(uint8 element_index,  uint16 time)
+	void SetTimer(uint8 element_index, uint16 time)
 
 		The element_index parameter is the element's index within the
 		node where the health server model is hosted.
@@ -406,6 +678,76 @@ Methods:
 			org.bluez.mesh.Error.NotSupported
 
 
+Mesh Provisioner Hierarchy
+============================
+Service		unique name
+Interface	org.bluez.mesh.Provisioner1
+Object path	freely definable
+
+	ScanResult(int8 rssi, array{byte} data)
+
+		The method is called from the bluetooth-meshd daemon when a
+		unique UUID has been seen during UnprovisionedScan() for
+		unprovsioned devices.
+
+		The rssi parameter is a signed, normalized measurement of the
+		signal strength of the recieved unprovisioned beacon.
+
+		The data parameter is a variable length byte array, that may
+		have 1, 2 or 3 distinct fields contained in it including the 16
+		byte remote device UUID (always), a 32 bit mask of OOB
+		authentication flags (optional), and a 32 bit URI hash (if URI
+		bit set in OOB mask). Whether these fields exist or not is a
+		decision of the remote device.
+
+		If a beacon with a UUID that has already been reported is
+		recieved by the daemon, it will be silently discarded unless it
+		was recieved at a higher rssi power level.
+
+
+	uint16 net_index, uint8 flags, uint32 iv_index, uint16 unicast
+							RequestProvData()
+
+		This method is implemented by a Provisioner capable application
+		and is called when the remote device has been fully
+		authenticated and confirmed.
+
+		Return Parameters are from the Mesh Profile Spec:
+		net_index - Subnet index of the net_key
+		flags - Flags for IV_Update and Key Refresh
+		iv_index - Current IvIndex being used on the network
+		unicast - Primary Unicast address of the new node
+
+		PossibleErrors:
+			org.bluez.mesh.Error.Abort
+
+	void AddNodeComplete(array{byte}[16] uuid, uint16 unicast, uint8 count)
+
+		This method is called when the node provisioning initiated
+		by an AddNode() method call successfully completed.
+
+		The unicast parameter is the primary address that has been
+		assigned to the new node, and the address of it's config server.
+
+		The count parameter is the number of unicast addresses assigned
+		to the new node.
+
+		The new node may now be sent messages using the credentials
+		supplied by the RequestProvData method.
+
+	void AddNodeFailed(array{byte}[16] uuid, string reason)
+
+		This method is called when the node provisioning initiated by
+		AddNode() has failed. Depending on how far Provisioning
+		proceeded before failing, some cleanup of cached data may be
+		required.
+
+		The reason parameter identifies the reason for provisioning
+		failure. The defined values are: "aborted", "timeout",
+		"bad-pdu", "confirmation-failed", "out-of-resources",
+		"decryption-error", "unexpected-error",
+		"cannot-assign-addresses".
+
 Provisioning Agent Hierarchy
 ============================
 Service		unique name
@@ -441,6 +783,7 @@ Methods:
 		the local role is Provisioner.
 
 	void DisplayString(string value)
+
 		This method is called when the Daemon has something important
 		for the Agent to Display, but does not require any additional
 		input locally. For instance: "Enter "ABCDE" on remote device".
@@ -451,9 +794,8 @@ Methods:
 		for the Agent to Display, but does not require any additional
 		input locally. For instance: "Enter 14939264 on remote device".
 
-		The type parameter indicates the display method.  Allowed values
+		The type parameter indicates the display method. Allowed values
 		are:
-
 			"blink" - Locally blink LED
 			"beep" - Locally make a noise
 			"vibrate" - Locally vibrate
@@ -466,12 +808,11 @@ Methods:
 
 	uint32 PromptNumeric(string type)
 
-		This method is called when the Daemon has requires the user to
-		enter a 1-99999999 digit decimal value.
+		This method is called when the Daemon requests the user to
+		enter a decimal value between 1-99999999.
 
 		The type parameter indicates the input method. Allowed values
 		are:
-
 			"blink" - Enter times remote LED blinked
 			"beep" - Enter times remote device beeped
 			"vibrate" - Enter times remote device vibrated
@@ -483,14 +824,13 @@ Methods:
 		This agent should prompt the user for specific input. For
 		instance: "Enter value being displayed by remote device".
 
-	array{byte} PromptStatic(string type)
+	array{byte}[16] PromptStatic(string type)
 
 		This method is called when the Daemon requires a 16 octet byte
 		array, as an Out-of-Band authentication.
 
 		The type parameter indicates the input method. Allowed values
 		are:
-
 			"static-oob" - return 16 octet array
 			"in-alpha" - return 16 octet alpha array
 
@@ -511,7 +851,6 @@ Properties:
 	array{string} Capabilities [read-only]
 
 		An array of strings with the following allowed values:
-
 			"blink"
 			"beep"
 			"vibrate"
@@ -528,7 +867,6 @@ Properties:
 
 		Indicates availability of OOB data. An array of strings with the
 		following allowed values:
-
 			"other"
 			"uri"
 			"machine-code-2d"
@@ -546,8 +884,3 @@ Properties:
 
 		Uniform Resource Identifier points to out-of-band (OOB)
 		information (e.g., a public key)
-
-
-Mesh Provisioner Hierarchy
-==========================
-<TBD>
Signature · 1 line
2.14.5
#2 lore raw

Hi Brian,

Quoted 144 lines · Brian Gix

The added D-Bus APIs enable Applications to function in a Provisioner Initiator role, and as a Configuration Client.

---
 doc/mesh-api.txt | 363
++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 348 insertions(+), 15 deletions(-)
doc/mesh-api.txt +4 -0
index 0b341a0f9..85d1f83d2 100644
@@ -30,6 +30,7 @@ Methods:
 			org.bluez.mesh.Error.InvalidArguments
 
 	void Cancel(void)
+
 		Cancels an outstanding provisioning request initiated
 by Join()
 		method.
@@ -109,6 +110,37 @@ Methods:
 		PossibleErrors:
 			org.bluez.mesh.Error.NotFound
 
+	uint64 token CreateNetwork(object app_root, array{byte}[16]
 uuid)
+
+		This is the first method that an application calls to

become

doc/mesh-api.txt +1 -0
+		a Provisioner node, and a Configuration Client on a

newly

doc/mesh-api.txt +3 -0
+		created Mesh Network.
+
+		The app_root parameter is a D-Bus object root path of

the

doc/mesh-api.txt +2 -0
+		application that implements org.bluez.mesh.Application1
+		interface, and a org.bluez.mesh.Provisioner1 interface.

The

doc/mesh-api.txt +1 -0
+		application represents a node where child mesh elements

have

doc/mesh-api.txt +1 -0
+		their own objects that implement

org.bluez.mesh.Element1

doc/mesh-api.txt +1 -0
+		interface. The application hierarchy also contains a

provision

doc/mesh-api.txt +1 -0
+		agent object that implements

org.bluez.mesh.ProvisionAgent1

doc/mesh-api.txt +1 -0
+		interface. The standard DBus.ObjectManager interface

must be

doc/mesh-api.txt +3 -0
+		available on the app_root path.
+
+		The uuid parameter is a 16-byte array that contains

Device UUID.

doc/mesh-api.txt +2 -0
+
+		The returned token must be preserved by the application

in

doc/mesh-api.txt +1 -0
+		order to authenticate itself to the mesh daemon and

attach to

doc/mesh-api.txt +1 -0
+		the network as a mesh node by calling Attach() method

or

doc/mesh-api.txt +1 -0
+		permanently remove the identity of the mesh node by

calling

doc/mesh-api.txt +3 -0
+		Leave() method.
+
+		The other information the bluetooth-meshd daemon will

preserve

doc/mesh-api.txt +1 -0
+		about the initial node, is to give it the initial

primary

doc/mesh-api.txt +1 -0
+		unicast address (0x0001), and create and assign a

net_key as the

doc/mesh-api.txt +8 -0
+		primary network net_index (0x000).
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
 
 Mesh Node Hierarchy
 ===================
@@ -146,6 +178,30 @@ Methods:
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.NotFound
 
+	void SendWithDeviceKey(object element_path, uint16 destination,
+					uint16 net_index, array{byte}
 data)
+
+		This method is used to send a message originated by a

local

doc/mesh-api.txt +3 -0
+		model encoded with the device key of the remote node.
+
+		The element_path parameter is the object path of an

element from

doc/mesh-api.txt +1 -0
+		a collection of the application elements (see Mesh

Application

doc/mesh-api.txt +3 -0
+		Hierarchy section).
+
+		The destination parameter contains the destination

address. This

doc/mesh-api.txt +1 -0
+		destination must be a uint16 to a unicast address, or a

well

doc/mesh-api.txt +3 -0
+		known group address.
+
+		The net_index parameter is the subnet index of the

network on

doc/mesh-api.txt +3 -0
+		which the message is to be sent.
+
+		The data parameter is an outgoing message to be

encypted by the

doc/mesh-api.txt +6 -0
+		meshd daemon and sent on.
+
+		Possible errors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotFound
+
 	void Publish(object element_path, uint16 model, array{byte}

data)

This method is used to send a publication originated by
a local

doc/mesh-api.txt +0 -0
@@ -224,12 +280,211 @@ Properties:
 		This property indicates whether the periodic beaconing

is

doc/mesh-api.txt +3 -0
 		enabled (true) or disabled (false).
 
+	uint8 BeaconFlags [read-only]
+
+		This property may be read at any time to determine the

flag

doc/mesh-api.txt +1 -0
+		field setting on sent and received beacons of the

primary

doc/mesh-api.txt +5 -0
+		network key.
+
+	uint32 IvIndex [read-only]
+
+		This property may be read at any time to determine the

IV_Index

doc/mesh-api.txt +1 -0
+		that the current network is on. This information is

only useful

doc/mesh-api.txt +2 -0
+		for provisioning.
+
 	uint32 SecondsSinceLastHeard [read-only]
 
 		This property may be read at any time to determine the

number of
seconds since mesh network layer traffic was last
detected on

doc/mesh-api.txt Properties: · line 304

Quoted 6 lines
doc/mesh-api.txt +4 -0
 		this node's network.
 
+Mesh Provisioning Hierarchy
+============================
+Service		org.bluez.mesh
+Interface	org.bluez.mesh.Provisioning1

We may want to call this interface "org.bluez.mesh.Manager1", because it contains methods surpassing
provisioning procedure

Quoted 42 lines
doc/mesh-api.txt +2 -0
+Object path	/org/bluez/mesh/node<xxxx>
+		where xxxx is a 4-digit hexadecimal number generated by

daemon

doc/mesh-api.txt +6 -0
+
+Methods:
+	void UnprovisionedScan(uint16 seconds)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to start

listening

doc/mesh-api.txt +1 -0
+		(scanning) for unprovisioned devices in the area.

Scanning

doc/mesh-api.txt +1 -0
+		will continue for the specified number of seconds, or,

if 0 is

doc/mesh-api.txt +1 -0
+		specified, then continuously until

UnprovisionedScanCancel() is

doc/mesh-api.txt +4 -0
+		called or if AddNode() method is called.
+
+		Each time a unique unprovisioned beacon is heard, the
+		ScanResult() method on the app will be called with the

result.

doc/mesh-api.txt +20 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.NotAuthorized
+
+	void UnprovisionedScanCancel(void)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to stop listening
+		(scanning) for unprovisioned devices in the area.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.NotAuthorized
+
+	void AddNode(array{byte}[16] uuid)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to add the
+		unprovisioned device specified by uuid, to the Network.
+
+		The uuid parameter is a 16-byte array that contains

Device UUID

doc/mesh-api.txt Properties: · line 346

Quoted 7 lines
doc/mesh-api.txt +7 -0
+		of the unprovisioned device to be added to the network.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+
+	void AddNetKey(uint16 net_index)

I suggest we change this method to
AddNetKey(uint16 dest, uint16 net_index)

Since in the current proposed approach the daemon is the only entity in possession of key vaues, the configuration messages that contain the key values in their payload will need to be generated by the daemon. The modified method will allow to send the network key(s) to any node. If a network key specified by the net_index, does not exist, it will be generated and recorded, effectively creating a new subnet. Alternatively, this functionality can be covered by two methods:
CreateSubnet(uint16 net_index) to generate a key value and AddNetKey(uint16 dest, uint16 net_index) to send the keys to a remote or local node

Quoted 11 lines
doc/mesh-api.txt +3 -0
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate and

add a new

doc/mesh-api.txt +6 -0
+		network subnet key.
+
+		The net_index parameter is a 12-bit value (0x001-0xFFF)
+		specifying which net key to add.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt Properties: · line 362

Quoted 7 lines
doc/mesh-api.txt +7 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.AlreadyExists
+
+	void UpdateNetKey(uint16 net_index)

I suggest we change this method to UpdateNetKey(uint16 dest, uint16 net_index)
This will allow to send an updated value of the network key to any node. If the updated network key value specified by the net_index, does not exist, it will be generated and recorded.

Quoted 65 lines
doc/mesh-api.txt +3 -0
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate a new

network

doc/mesh-api.txt +4 -0
+		subnet key, and set it's key refresh state to Phase 1.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which net key to update. Note that the

subnet must

doc/mesh-api.txt +3 -0
+		exist prior to updating.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +10 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteNetKey(uint16 net_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete a

subnet.

doc/mesh-api.txt +3 -0
+
+		The net_index parameter is a 12-bit value (0x001-0xFFF)
+		specifying which net key to delete. The primary net key

(0x000)

doc/mesh-api.txt +3 -0
+		may not be deleted.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +8 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void SetKeyPhase(uint16 net_index, uint8 phase)
+		This method is used to set the master key update phase

of the

doc/mesh-api.txt +6 -0
+		given subnet.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which subnet phase to set.
+
+		The phase parameter is used to cycle the local key

database

doc/mesh-api.txt +1 -0
+		through the phases as defined by the Mesh Profile

Specification.

doc/mesh-api.txt +2 -0
+		Allowed values:
+			0 - Cancel Key Refresh (May only be called from

Phase 1,

doc/mesh-api.txt +1 -0
+				and should never be called once the new

key has

doc/mesh-api.txt +3 -0
+				started propagating)
+			1 - Invalid Argument (see NetKeyUpdate method)
+			2 - Go to Phase 2 (May only be called from

Phase 1)

doc/mesh-api.txt +1 -0
+			3 - Complete Key Refresh procedure (May only be

called

doc/mesh-api.txt +3 -0
+				from Phase 2)
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt Properties: · line 420

Quoted 7 lines
doc/mesh-api.txt +7 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void AddAppKey(uint16 net_index, uint16 app_index)

Similar to the network key methods, needs to include dest parameter

Quoted 52 lines
doc/mesh-api.txt +3 -0
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate and

add a new

doc/mesh-api.txt +4 -0
+		application key.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which net key to bind the application key

to.

doc/mesh-api.txt +5 -0
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to add.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +14 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.AlreadyExists
+
+	void UpdateAppKey(uint16 app_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate a new
+		application key.
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to update. Note that the

subnet that

doc/mesh-api.txt +3 -0
+		the key is bound to must exist and be in Phase 1.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +10 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteAppKey(uint16 app_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete an

application

doc/mesh-api.txt +6 -0
+		key.
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to delete.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt Properties: · line 472

Quoted 7 lines
doc/mesh-api.txt +7 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteRemoteNode(uint16 primary, uint8 cnt)

Let's call this method DeleteNode()
Do we need to specify the element count?

Quoted 253 lines
doc/mesh-api.txt +3 -0
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete a

remote node

doc/mesh-api.txt +3 -0
+		from the local device key database.
+
+		The primary parameter specifies the unicast address of

the

doc/mesh-api.txt +1 -0
+		the node being deleted, and the number of elements that

were

doc/mesh-api.txt +3 -0
+		assigned to it.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +5 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
 
 Mesh Application Hierarchy
 ==========================
@@ -247,6 +502,7 @@ An example mesh application hierarchy may look

like this:

doc/mesh-api.txt +1 -0
 			|   - org.freedesktop.DBus.ObjectManager
 			|   - org.bluez.mesh.Application1
 			|   - org.bluez.mesh.Attention1 (optional)
+			|   - org.bluez.mesh.Provisioner1

(optional,Provisioner)

doc/mesh-api.txt +4 -0
 			|
 			-> /com/example/agent
 			| |   - org.bluez.mesh.ProvisionAgent1
@@ -325,6 +581,22 @@ Methods:
 
 		The data parameter is the incoming message.
 
+	void DevKeyMessageReceived(uint16 source, uint16 net_index,
+							array{byte}
 data)
+
+		This method is called by meshd daemon when a message

arrives

doc/mesh-api.txt +1 -0
+		addressed to the application, which was sent with the

remote

doc/mesh-api.txt +6 -0
+		node's device key.
+
+		The source parameter is unicast address of the remote
+		node-element that sent the message.
+
+		The net_index parameter indicates what subnet the

message was

doc/mesh-api.txt +1 -0
+		received on, and if a response is required, the same

subnet

doc/mesh-api.txt +4 -0
+		must be used to send the response.
+
+		The data parameter is the incoming message.
+
 	void UpdateModelConfiguration(uint16 model_id, dict config)
 
 		This method is called by bluetooth-meshd daemon when a

model's

doc/mesh-api.txt +0 -0
@@ -383,7 +655,7 @@ Object path	freely definable
 This is an optional interface that implements health attention

timer.

Methods:

doc/mesh-api.txt +1 -1
-	void SetTimer(uint8 element_index,  uint16 time)
+	void SetTimer(uint8 element_index, uint16 time)
 
 		The element_index parameter is the element's index

within the

doc/mesh-api.txt +9 -0
 		node where the health server model is hosted.
@@ -406,6 +678,76 @@ Methods:
 			org.bluez.mesh.Error.NotSupported
 
 
+Mesh Provisioner Hierarchy
+============================
+Service		unique name
+Interface	org.bluez.mesh.Provisioner1
+Object path	freely definable
+
+	ScanResult(int8 rssi, array{byte} data)
+
+		The method is called from the bluetooth-meshd daemon

when a

doc/mesh-api.txt +1 -0
+		unique UUID has been seen during UnprovisionedScan()

for

doc/mesh-api.txt +3 -0
+		unprovsioned devices.
+
+		The rssi parameter is a signed, normalized measurement

of the

doc/mesh-api.txt +3 -0
+		signal strength of the recieved unprovisioned beacon.
+
+		The data parameter is a variable length byte array,

that may

doc/mesh-api.txt +1 -0
+		have 1, 2 or 3 distinct fields contained in it

including the 16

doc/mesh-api.txt +2 -0
+		byte remote device UUID (always), a 32 bit mask of OOB
+		authentication flags (optional), and a 32 bit URI hash

(if URI

doc/mesh-api.txt +1 -0
+		bit set in OOB mask). Whether these fields exist or not

is a

doc/mesh-api.txt +3 -0
+		decision of the remote device.
+
+		If a beacon with a UUID that has already been reported

is

doc/mesh-api.txt +1 -0
+		recieved by the daemon, it will be silently discarded

unless it

doc/mesh-api.txt +5 -0
+		was recieved at a higher rssi power level.
+
+
+	uint16 net_index, uint8 flags, uint32 iv_index, uint16 unicast
+							RequestProvData

()

doc/mesh-api.txt +2 -0
+
+		This method is implemented by a Provisioner capable

application

doc/mesh-api.txt +13 -0
+		and is called when the remote device has been fully
+		authenticated and confirmed.
+
+		Return Parameters are from the Mesh Profile Spec:
+		net_index - Subnet index of the net_key
+		flags - Flags for IV_Update and Key Refresh
+		iv_index - Current IvIndex being used on the network
+		unicast - Primary Unicast address of the new node
+
+		PossibleErrors:
+			org.bluez.mesh.Error.Abort
+
+	void AddNodeComplete(array{byte}[16] uuid, uint16 unicast,

uint8 count)

doc/mesh-api.txt +2 -0
+
+		This method is called when the node provisioning

initiated

doc/mesh-api.txt +3 -0
+		by an AddNode() method call successfully completed.
+
+		The unicast parameter is the primary address that has

been

doc/mesh-api.txt +1 -0
+		assigned to the new node, and the address of it's

config server.

doc/mesh-api.txt +2 -0
+
+		The count parameter is the number of unicast addresses

assigned

doc/mesh-api.txt +3 -0
+		to the new node.
+
+		The new node may now be sent messages using the

credentials

doc/mesh-api.txt +5 -0
+		supplied by the RequestProvData method.
+
+	void AddNodeFailed(array{byte}[16] uuid, string reason)
+
+		This method is called when the node provisioning

initiated by

doc/mesh-api.txt +2 -0
+		AddNode() has failed. Depending on how far Provisioning
+		proceeded before failing, some cleanup of cached data

may be

doc/mesh-api.txt +3 -0
+		required.
+
+		The reason parameter identifies the reason for

provisioning

doc/mesh-api.txt +6 -0
+		failure. The defined values are: "aborted", "timeout",
+		"bad-pdu", "confirmation-failed", "out-of-resources",
+		"decryption-error", "unexpected-error",
+		"cannot-assign-addresses".
+
 Provisioning Agent Hierarchy
 ============================
 Service		unique name
@@ -441,6 +783,7 @@ Methods:
 		the local role is Provisioner.
 
 	void DisplayString(string value)
+
 		This method is called when the Daemon has something

important
for the Agent to Display, but does not require any
additional
input locally. For instance: "Enter "ABCDE" on remote
device".

doc/mesh-api.txt +0 -0
@@ -451,9 +794,8 @@ Methods:
 		for the Agent to Display, but does not require any

additional
input locally. For instance: "Enter 14939264 on remote
device".

doc/mesh-api.txt +0 -1
-		The type parameter indicates the display

method. Allowed values

doc/mesh-api.txt +1 -0
+		The type parameter indicates the display method.

Allowed values

doc/mesh-api.txt +0 -2
 		are:
-
 			"blink" - Locally blink LED
 			"beep" - Locally make a noise
 			"vibrate" - Locally vibrate
@@ -466,12 +808,11 @@ Methods:
 
 	uint32 PromptNumeric(string type)
 
-		This method is called when the Daemon has requires the

user to

doc/mesh-api.txt +1 -1
-		enter a 1-99999999 digit decimal value.
+		This method is called when the Daemon requests the user

to

doc/mesh-api.txt +1 -0
+		enter a decimal value between 1-99999999.
 
 		The type parameter indicates the input method. Allowed

values

doc/mesh-api.txt +0 -1
 		are:
-
 			"blink" - Enter times remote LED blinked
 			"beep" - Enter times remote device beeped
 			"vibrate" - Enter times remote device vibrated
@@ -483,14 +824,13 @@ Methods:
 		This agent should prompt the user for specific input.

For
instance: "Enter value being displayed by remote
device".

doc/mesh-api.txt +1 -1
-	array{byte} PromptStatic(string type)
+	array{byte}[16] PromptStatic(string type)
 
 		This method is called when the Daemon requires a 16

octet byte

doc/mesh-api.txt +0 -0
 		array, as an Out-of-Band authentication.
 
 		The type parameter indicates the input method. Allowed

values

doc/mesh-api.txt +0 -2
 		are:
-
 			"static-oob" - return 16 octet array
 			"in-alpha" - return 16 octet alpha array
@@ -511,7 +851,6 @@ Properties:
 	array{string} Capabilities [read-only]
 
 		An array of strings with the following allowed values:
-
 			"blink"
 			"beep"
 			"vibrate"
@@ -528,7 +867,6 @@ Properties:
 
 		Indicates availability of OOB data. An array of strings

with the

doc/mesh-api.txt +0 -1
 		following allowed values:
-
 			"other"
 			"uri"
 			"machine-code-2d"

doc/mesh-api.txt Properties: · line 553

Quoted 8 lines
doc/mesh-api.txt +0 -5
@@ -546,8 +884,3 @@ Properties:
 
 		Uniform Resource Identifier points to out-of-band (OOB)
 		information (e.g., a public key)
-
-
-Mesh Provisioner Hierarchy
-==========================
-<TBD>

Inga

author
#3 lore raw

Hi Inga,

Quoted 212 lines

From: Stotland, Inga

Hi Brian,

Quoted 12 lines · Brian Gix

The added D-Bus APIs enable Applications to function in a Provisioner Initiator role, and as a Configuration Client.

---
 doc/mesh-api.txt | 363
++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 348 insertions(+), 15 deletions(-)
doc/mesh-api.txt index renamed from doc/mesh-api.txt +0 -0

0b341a0f9..85d1f83d2 100644

doc/mesh-api.txt Methods: · line 34

Quoted 5 lines
doc/mesh-api.txt +1 -0
@@ -30,6 +30,7 @@ Methods:
 			org.bluez.mesh.Error.InvalidArguments
 
 	void Cancel(void)
+
 		Cancels an outstanding provisioning request initiated by

Join()

Quoted 97 lines
doc/mesh-api.txt +3 -0
 		method.
 
@@ -109,6 +110,37 @@ Methods:
 		PossibleErrors:
 			org.bluez.mesh.Error.NotFound
 
+	uint64 token CreateNetwork(object app_root, array{byte}[16]
 uuid)
+
+		This is the first method that an application calls to

become

doc/mesh-api.txt +1 -0
+		a Provisioner node, and a Configuration Client on a

newly

doc/mesh-api.txt +3 -0
+		created Mesh Network.
+
+		The app_root parameter is a D-Bus object root path of

the

doc/mesh-api.txt +2 -0
+		application that implements org.bluez.mesh.Application1
+		interface, and a org.bluez.mesh.Provisioner1 interface.

The

doc/mesh-api.txt +1 -0
+		application represents a node where child mesh elements

have

doc/mesh-api.txt +1 -0
+		their own objects that implement

org.bluez.mesh.Element1

doc/mesh-api.txt +1 -0
+		interface. The application hierarchy also contains a

provision

doc/mesh-api.txt +1 -0
+		agent object that implements

org.bluez.mesh.ProvisionAgent1

doc/mesh-api.txt +1 -0
+		interface. The standard DBus.ObjectManager interface

must be

doc/mesh-api.txt +3 -0
+		available on the app_root path.
+
+		The uuid parameter is a 16-byte array that contains

Device UUID.

doc/mesh-api.txt +2 -0
+
+		The returned token must be preserved by the application

in

doc/mesh-api.txt +1 -0
+		order to authenticate itself to the mesh daemon and

attach to

doc/mesh-api.txt +1 -0
+		the network as a mesh node by calling Attach() method

or

doc/mesh-api.txt +1 -0
+		permanently remove the identity of the mesh node by

calling

doc/mesh-api.txt +3 -0
+		Leave() method.
+
+		The other information the bluetooth-meshd daemon will

preserve

doc/mesh-api.txt +1 -0
+		about the initial node, is to give it the initial

primary

doc/mesh-api.txt +1 -0
+		unicast address (0x0001), and create and assign a

net_key as the

doc/mesh-api.txt +8 -0
+		primary network net_index (0x000).
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
 
 Mesh Node Hierarchy
 ===================
@@ -146,6 +178,30 @@ Methods:
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.NotFound
 
+	void SendWithDeviceKey(object element_path, uint16 destination,
+					uint16 net_index, array{byte}
 data)
+
+		This method is used to send a message originated by a

local

doc/mesh-api.txt +3 -0
+		model encoded with the device key of the remote node.
+
+		The element_path parameter is the object path of an

element from

doc/mesh-api.txt +1 -0
+		a collection of the application elements (see Mesh

Application

doc/mesh-api.txt +3 -0
+		Hierarchy section).
+
+		The destination parameter contains the destination

address. This

doc/mesh-api.txt +1 -0
+		destination must be a uint16 to a unicast address, or a

well

doc/mesh-api.txt +3 -0
+		known group address.
+
+		The net_index parameter is the subnet index of the

network on

doc/mesh-api.txt +3 -0
+		which the message is to be sent.
+
+		The data parameter is an outgoing message to be

encypted by the

doc/mesh-api.txt +6 -0
+		meshd daemon and sent on.
+
+		Possible errors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotFound
+
 	void Publish(object element_path, uint16 model, array{byte}

data)

Quoted 1 line

This method is used to send a publication originated by a local

@@

Quoted 18 lines

-224,12 +280,211 @@ Properties:

doc/mesh-api.txt +3 -0
 		This property indicates whether the periodic beaconing is
 		enabled (true) or disabled (false).
 
+	uint8 BeaconFlags [read-only]
+
+		This property may be read at any time to determine the

flag

doc/mesh-api.txt +1 -0
+		field setting on sent and received beacons of the

primary

doc/mesh-api.txt +5 -0
+		network key.
+
+	uint32 IvIndex [read-only]
+
+		This property may be read at any time to determine the

IV_Index

doc/mesh-api.txt +1 -0
+		that the current network is on. This information is

only useful

doc/mesh-api.txt Properties:

Quoted 5 lines
doc/mesh-api.txt +2 -0
+		for provisioning.
+
 	uint32 SecondsSinceLastHeard [read-only]
 
 		This property may be read at any time to determine the

number of

Quoted 1 line

seconds since mesh network layer traffic was last detected

on

doc/mesh-api.txt Properties: · line 304

Quoted 6 lines
doc/mesh-api.txt +4 -0
 		this node's network.
 
+Mesh Provisioning Hierarchy
+============================
+Service		org.bluez.mesh
+Interface	org.bluez.mesh.Provisioning1

We may want to call this interface "org.bluez.mesh.Manager1", because it contains methods surpassing provisioning procedure

Quoted 42 lines
doc/mesh-api.txt +2 -0
+Object path	/org/bluez/mesh/node<xxxx>
+		where xxxx is a 4-digit hexadecimal number generated by

daemon

doc/mesh-api.txt +6 -0
+
+Methods:
+	void UnprovisionedScan(uint16 seconds)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to start

listening

doc/mesh-api.txt +1 -0
+		(scanning) for unprovisioned devices in the area.

Scanning

doc/mesh-api.txt +1 -0
+		will continue for the specified number of seconds, or,

if 0 is

doc/mesh-api.txt +1 -0
+		specified, then continuously until

UnprovisionedScanCancel() is

doc/mesh-api.txt +4 -0
+		called or if AddNode() method is called.
+
+		Each time a unique unprovisioned beacon is heard, the
+		ScanResult() method on the app will be called with the

result.

doc/mesh-api.txt +20 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.NotAuthorized
+
+	void UnprovisionedScanCancel(void)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to stop listening
+		(scanning) for unprovisioned devices in the area.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.NotAuthorized
+
+	void AddNode(array{byte}[16] uuid)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to add the
+		unprovisioned device specified by uuid, to the Network.
+
+		The uuid parameter is a 16-byte array that contains

Device UUID

doc/mesh-api.txt Properties: · line 346

Quoted 7 lines
doc/mesh-api.txt +7 -0
+		of the unprovisioned device to be added to the network.
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+
+	void AddNetKey(uint16 net_index)

I suggest we change this method to
AddNetKey(uint16 dest, uint16 net_index)

Quoted 10 lines

Since in the current proposed approach the daemon is the only entity in possession of key vaues, the configuration messages that contain the key values in their payload will need to be generated by the daemon. The modified method will allow to send the network key(s) to any node. If a network key specified by the net_index, does not exist, it will be generated and recorded, effectively creating a new subnet. Alternatively, this functionality can be covered by two methods:
CreateSubnet(uint16 net_index) to generate a key value and AddNetKey(uint16 dest, uint16 net_index) to send the keys to a remote or local node

So I think the biggest problem with having methods *sometimes* add a key to the *local* database, but always add the key to a remote node is Indeterminacies. We are trying to potentially do two things at once, and either one or both can fail.

I strongly believe that the method calls to add a key (or delete it or update it) to our local key storage needs to be a distinct requests... Yes, we only save *one* method call by overloading the functionality into a single call. But separating Local operations from Remote operations keeps it clear, if there is a failure, at exactly which step the failure occurred. The Application is not left wondering if there is an unused key in the local database, or if the remote device now has a key that nobody else does.

Quoted 17 lines
Quoted 17 lines
doc/mesh-api.txt +3 -0
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate and

add a new

doc/mesh-api.txt +6 -0
+		network subnet key.
+
+		The net_index parameter is a 12-bit value (0x001-0xFFF)
+		specifying which net key to add.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +5 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.AlreadyExists
Quoted 9 lines

doc/mesh-api.txt

Quoted 2 lines
doc/mesh-api.txt +2 -0
+
+	void UpdateNetKey(uint16 net_index)

I suggest we change this method to UpdateNetKey(uint16 dest, uint16 net_index)
This will allow to send an updated value of the network key to any node. If the updated network key value specified by the net_index, does not exist, it will be generated and recorded.

Same comment here... I intended this for this method to modify the local key database only, with no overloaded functionality of sending the update key to one of the potentially hundreds of other nodes.

Quoted 58 lines
Quoted 58 lines
doc/mesh-api.txt +3 -0
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate a new

network

doc/mesh-api.txt +4 -0
+		subnet key, and set it's key refresh state to Phase 1.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which net key to update. Note that the

subnet must

doc/mesh-api.txt +3 -0
+		exist prior to updating.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +10 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteNetKey(uint16 net_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete a

subnet.

doc/mesh-api.txt +3 -0
+
+		The net_index parameter is a 12-bit value (0x001-0xFFF)
+		specifying which net key to delete. The primary net key

(0x000)

doc/mesh-api.txt +3 -0
+		may not be deleted.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +8 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void SetKeyPhase(uint16 net_index, uint8 phase)
+		This method is used to set the master key update phase

of the

doc/mesh-api.txt +6 -0
+		given subnet.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which subnet phase to set.
+
+		The phase parameter is used to cycle the local key

database

doc/mesh-api.txt +1 -0
+		through the phases as defined by the Mesh Profile

Specification.

doc/mesh-api.txt +2 -0
+		Allowed values:
+			0 - Cancel Key Refresh (May only be called from

Phase 1,

doc/mesh-api.txt +1 -0
+				and should never be called once the new

key has

doc/mesh-api.txt +2 -0
+				started propagating)
+			1 - Invalid Argument (see NetKeyUpdate method)
Quoted 8 lines
Quoted 8 lines
doc/mesh-api.txt +1 -0
+			2 - Go to Phase 2 (May only be called from

Phase 1)

doc/mesh-api.txt +1 -0
+			3 - Complete Key Refresh procedure (May only be

called

doc/mesh-api.txt +3 -0
+				from Phase 2)
+
+		This call affects the local bluetooth-daemon key

database only.

This method is also intended to modify the state of the keys locally only. Only after the local phase has been recorded would the phase change be propogated to the wider mesh

Quoted 64 lines

doc/mesh-api.txt Properties: · line 420

Quoted 7 lines
doc/mesh-api.txt +7 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void AddAppKey(uint16 net_index, uint16 app_index)

Similar to the network key methods, needs to include dest parameter

Quoted 54 lines
doc/mesh-api.txt +3 -0
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate and

add a new

doc/mesh-api.txt +4 -0
+		application key.
+
+		The net_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which net key to bind the application key

to.

doc/mesh-api.txt +5 -0
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to add.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +14 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.AlreadyExists
+
+	void UpdateAppKey(uint16 app_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to generate a new
+		application key.
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to update. Note that the

subnet that

doc/mesh-api.txt +3 -0
+		the key is bound to must exist and be in Phase 1.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +10 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteAppKey(uint16 app_index)
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete an

application

doc/mesh-api.txt +6 -0
+		key.
+
+		The app_index parameter is a 12-bit value (0x000-0xFFF)
+		specifying which app key to delete.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +2 -0
+
+		PossibleErrors:
Quoted 8 lines

doc/mesh-api.txt Properties: · line 472

Quoted 5 lines
doc/mesh-api.txt +5 -0
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
+
+	void DeleteRemoteNode(uint16 primary, uint8 cnt)

Let's call this method DeleteNode()
Do we need to specify the element count?

I want to be clear that this again only affects the local key database. We do have the ability to delete Local nodes with the Leave() method. I want to be clear with this method that again, no communication is made... This simply deletes a Remote Node Device key from the local database. I included a count parameter so that storage of the device keys could be optimized such that all element unicast addresses are accounted for. It is 100% legal to send a Device Key encoded message to a non-primary element of a Node, so we might have redundant storages of the device keys under every unicast address, in the local database.

Quoted 261 lines
Quoted 54 lines
doc/mesh-api.txt +3 -0
+
+		This method is used by the application that supports
+		org.bluez.mesh.Provisioner1 interface to delete a

remote node

doc/mesh-api.txt +3 -0
+		from the local device key database.
+
+		The primary parameter specifies the unicast address of

the

doc/mesh-api.txt +1 -0
+		the node being deleted, and the number of elements that

were

doc/mesh-api.txt +3 -0
+		assigned to it.
+
+		This call affects the local bluetooth-daemon key

database only.

doc/mesh-api.txt +5 -0
+
+		PossibleErrors:
+			org.bluez.mesh.Error.InvalidArguments
+			org.bluez.mesh.Error.NotAuthorized
+			org.bluez.mesh.Error.DoesNotExist
 
 Mesh Application Hierarchy
 ==========================
@@ -247,6 +502,7 @@ An example mesh application hierarchy may look

like this:

doc/mesh-api.txt +1 -0
 			|   - org.freedesktop.DBus.ObjectManager
 			|   - org.bluez.mesh.Application1
 			|   - org.bluez.mesh.Attention1 (optional)
+			|   - org.bluez.mesh.Provisioner1

(optional,Provisioner)

doc/mesh-api.txt +4 -0
 			|
 			-> /com/example/agent
 			| |   - org.bluez.mesh.ProvisionAgent1
@@ -325,6 +581,22 @@ Methods:
 
 		The data parameter is the incoming message.
 
+	void DevKeyMessageReceived(uint16 source, uint16 net_index,
+							array{byte}
 data)
+
+		This method is called by meshd daemon when a message

arrives

doc/mesh-api.txt +1 -0
+		addressed to the application, which was sent with the

remote

doc/mesh-api.txt +6 -0
+		node's device key.
+
+		The source parameter is unicast address of the remote
+		node-element that sent the message.
+
+		The net_index parameter indicates what subnet the

message was

doc/mesh-api.txt +1 -0
+		received on, and if a response is required, the same

subnet

doc/mesh-api.txt Methods:

Quoted 7 lines
doc/mesh-api.txt +4 -0
+		must be used to send the response.
+
+		The data parameter is the incoming message.
+
 	void UpdateModelConfiguration(uint16 model_id, dict config)
 
 		This method is called by bluetooth-meshd daemon when a

model's

doc/mesh-api.txt Object path freely definable · line 660

Quoted 8 lines
doc/mesh-api.txt +1 -1
@@ -383,7 +655,7 @@ Object path	freely definable
 This is an optional interface that implements health attention timer.
 
 Methods:
-	void SetTimer(uint8 element_index,  uint16 time)
+	void SetTimer(uint8 element_index, uint16 time)
 
 		The element_index parameter is the element's index within

the

Quoted 99 lines
doc/mesh-api.txt +9 -0
 		node where the health server model is hosted.
@@ -406,6 +678,76 @@ Methods:
 			org.bluez.mesh.Error.NotSupported
 
 
+Mesh Provisioner Hierarchy
+============================
+Service		unique name
+Interface	org.bluez.mesh.Provisioner1
+Object path	freely definable
+
+	ScanResult(int8 rssi, array{byte} data)
+
+		The method is called from the bluetooth-meshd daemon

when a

doc/mesh-api.txt +1 -0
+		unique UUID has been seen during UnprovisionedScan()

for

doc/mesh-api.txt +3 -0
+		unprovsioned devices.
+
+		The rssi parameter is a signed, normalized measurement

of the

doc/mesh-api.txt +3 -0
+		signal strength of the recieved unprovisioned beacon.
+
+		The data parameter is a variable length byte array,

that may

doc/mesh-api.txt +1 -0
+		have 1, 2 or 3 distinct fields contained in it

including the 16

doc/mesh-api.txt +2 -0
+		byte remote device UUID (always), a 32 bit mask of OOB
+		authentication flags (optional), and a 32 bit URI hash

(if URI

doc/mesh-api.txt +1 -0
+		bit set in OOB mask). Whether these fields exist or not

is a

doc/mesh-api.txt +3 -0
+		decision of the remote device.
+
+		If a beacon with a UUID that has already been reported

is

doc/mesh-api.txt +1 -0
+		recieved by the daemon, it will be silently discarded

unless it

doc/mesh-api.txt +5 -0
+		was recieved at a higher rssi power level.
+
+
+	uint16 net_index, uint8 flags, uint32 iv_index, uint16 unicast
+							RequestProvData

()

doc/mesh-api.txt +2 -0
+
+		This method is implemented by a Provisioner capable

application

doc/mesh-api.txt +13 -0
+		and is called when the remote device has been fully
+		authenticated and confirmed.
+
+		Return Parameters are from the Mesh Profile Spec:
+		net_index - Subnet index of the net_key
+		flags - Flags for IV_Update and Key Refresh
+		iv_index - Current IvIndex being used on the network
+		unicast - Primary Unicast address of the new node
+
+		PossibleErrors:
+			org.bluez.mesh.Error.Abort
+
+	void AddNodeComplete(array{byte}[16] uuid, uint16 unicast,

uint8 count)

doc/mesh-api.txt +2 -0
+
+		This method is called when the node provisioning

initiated

doc/mesh-api.txt +3 -0
+		by an AddNode() method call successfully completed.
+
+		The unicast parameter is the primary address that has

been

doc/mesh-api.txt +1 -0
+		assigned to the new node, and the address of it's

config server.

doc/mesh-api.txt +2 -0
+
+		The count parameter is the number of unicast addresses

assigned

doc/mesh-api.txt +3 -0
+		to the new node.
+
+		The new node may now be sent messages using the

credentials

doc/mesh-api.txt +5 -0
+		supplied by the RequestProvData method.
+
+	void AddNodeFailed(array{byte}[16] uuid, string reason)
+
+		This method is called when the node provisioning

initiated by

doc/mesh-api.txt +2 -0
+		AddNode() has failed. Depending on how far Provisioning
+		proceeded before failing, some cleanup of cached data

may be

doc/mesh-api.txt +3 -0
+		required.
+
+		The reason parameter identifies the reason for

provisioning

doc/mesh-api.txt +5 -0
+		failure. The defined values are: "aborted", "timeout",
+		"bad-pdu", "confirmation-failed", "out-of-resources",
+		"decryption-error", "unexpected-error",
+		"cannot-assign-addresses".
+
 Provisioning Agent Hierarchy
 ============================
 Service		unique name

doc/mesh-api.txt Methods: · line 787

Quoted 5 lines
doc/mesh-api.txt +1 -0
@@ -441,6 +783,7 @@ Methods:
 		the local role is Provisioner.
 
 	void DisplayString(string value)
+
 		This method is called when the Daemon has something

important

doc/mesh-api.txt Methods: · line 789

Quoted 2 lines
doc/mesh-api.txt +0 -0
 		for the Agent to Display, but does not require any additional
 		input locally. For instance: "Enter "ABCDE" on remote

device".

doc/mesh-api.txt Methods: · line 795

Quoted 3 lines
doc/mesh-api.txt +0 -0
@@ -451,9 +794,8 @@ Methods:
 		for the Agent to Display, but does not require any additional
 		input locally. For instance: "Enter 14939264 on remote

device".

Quoted 19 lines
doc/mesh-api.txt +0 -1
-		The type parameter indicates the display

method. Allowed values

doc/mesh-api.txt +1 -0
+		The type parameter indicates the display method.

Allowed values

doc/mesh-api.txt +0 -2
 		are:
-
 			"blink" - Locally blink LED
 			"beep" - Locally make a noise
 			"vibrate" - Locally vibrate
@@ -466,12 +808,11 @@ Methods:
 
 	uint32 PromptNumeric(string type)
 
-		This method is called when the Daemon has requires the

user to

doc/mesh-api.txt +1 -1
-		enter a 1-99999999 digit decimal value.
+		This method is called when the Daemon requests the user

to

doc/mesh-api.txt Methods:

Quoted 3 lines
doc/mesh-api.txt +1 -0
+		enter a decimal value between 1-99999999.
 
 		The type parameter indicates the input method. Allowed

values

doc/mesh-api.txt Methods:

Quoted 5 lines
doc/mesh-api.txt +0 -1
 		are:
-
 			"blink" - Enter times remote LED blinked
 			"beep" - Enter times remote device beeped
 			"vibrate" - Enter times remote device vibrated @@ -

483,14 +824,13

doc/mesh-api.txt Methods:

Quoted 9 lines

@@ Methods:
This agent should prompt the user for specific input.
For

doc/mesh-api.txt +1 -1
 		instance: "Enter value being displayed by remote device".
 
-	array{byte} PromptStatic(string type)
+	array{byte}[16] PromptStatic(string type)
 
 		This method is called when the Daemon requires a 16 octet

byte

doc/mesh-api.txt Methods:

Quoted 3 lines
doc/mesh-api.txt +0 -0
 		array, as an Out-of-Band authentication.
 
 		The type parameter indicates the input method. Allowed

values

Quoted 24 lines
doc/mesh-api.txt +0 -3
 		are:
-
 			"static-oob" - return 16 octet array
 			"in-alpha" - return 16 octet alpha array
@@ -511,7 +851,6 @@ Properties:
 	array{string} Capabilities [read-only]
 
 		An array of strings with the following allowed values:
-
 			"blink"
 			"beep"
 			"vibrate"
@@ -528,7 +867,6 @@ Properties:
 
 		Indicates availability of OOB data. An array of strings with the
 		following allowed values:
-
 			"other"
 			"uri"
 			"machine-code-2d"

doc/mesh-api.txt Properties: · line 553

Quoted 8 lines
doc/mesh-api.txt +0 -5
@@ -546,8 +884,3 @@ Properties:
 
 		Uniform Resource Identifier points to out-of-band (OOB)
 		information (e.g., a public key)
-
-
-Mesh Provisioner Hierarchy
-==========================
-<TBD>

Inga

#4 lore raw

Hi Brian,

On Wed, 2019-03-20 at 10:56 -0700, Gix, Brian wrote:
Hi Inga,

From: Stotland, Inga

Hi Brian,

On Tue, 2019-03-19 at 14:00 -0700, Brian Gix wrote:
The added D-Bus APIs enable Applications to function in a Provisioner Initiator role, and as a Configuration Client.

---
 doc/mesh-api.txt | 363
++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 348 insertions(+), 15 deletions(-)
doc/mesh-api.txt index renamed from doc/mesh-api.txt +0 -0

0b341a0f9..85d1f83d2 100644

doc/mesh-api.txt +1 -0
@@ -30,6 +30,7 @@ Methods:
 			org.bluez.mesh.Error.InvalidArguments
 
 	void Cancel(void)
+
 		Cancels an outstanding provisioning request initiated by

Join()
method.

@@ -109,6 +110,37 @@ Methods:
PossibleErrors:
org.bluez.mesh.Error.NotFound

+ uint64 token CreateNetwork(object app_root, array{byte}[16]
uuid)
+
+ This is the first method that an application calls to
become
+ a Provisioner node, and a Configuration Client on a
newly
+ created Mesh Network.
+
+ The app_root parameter is a D-Bus object root path of
the
+ application that implements org.bluez.mesh.Application1
+ interface, and a org.bluez.mesh.Provisioner1 interface.
The
+ application represents a node where child mesh elements
have
+ their own objects that implement
org.bluez.mesh.Element1
+ interface. The application hierarchy also contains a
provision
+ agent object that implements
org.bluez.mesh.ProvisionAgent1
+ interface. The standard DBus.ObjectManager interface
must be
+ available on the app_root path.
+
+ The uuid parameter is a 16-byte array that contains
Device UUID.
+
+ The returned token must be preserved by the application
in
+ order to authenticate itself to the mesh daemon and
attach to
+ the network as a mesh node by calling Attach() method
or
+ permanently remove the identity of the mesh node by
calling
+ Leave() method.
+
+ The other information the bluetooth-meshd daemon will
preserve
+ about the initial node, is to give it the initial
primary
+ unicast address (0x0001), and create and assign a
net_key as the
+ primary network net_index (0x000).
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments

Mesh Node Hierarchy
===================
@@ -146,6 +178,30 @@ Methods:
org.bluez.mesh.Error.InvalidArguments org.bluez.mesh.Error.NotFound

+ void SendWithDeviceKey(object element_path, uint16 destination,
+ uint16 net_index, array{byte}
data)
+
+ This method is used to send a message originated by a
local
+ model encoded with the device key of the remote node.
+
+ The element_path parameter is the object path of an
element from
+ a collection of the application elements (see Mesh
Application
+ Hierarchy section).
+
+ The destination parameter contains the destination
address. This
+ destination must be a uint16 to a unicast address, or a
well
+ known group address.
+
+ The net_index parameter is the subnet index of the
network on
+ which the message is to be sent.
+
+ The data parameter is an outgoing message to be
encypted by the
+ meshd daemon and sent on.
+
+ Possible errors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotFound
+
void Publish(object element_path, uint16 model, array{byte}
data)

This method is used to send a publication originated by a local
@@
-224,12 +280,211 @@ Properties:
This property indicates whether the periodic beaconing is enabled (true) or disabled (false).

+ uint8 BeaconFlags [read-only]
+
+ This property may be read at any time to determine the
flag
+ field setting on sent and received beacons of the
primary
+ network key.
+
+ uint32 IvIndex [read-only]
+
+ This property may be read at any time to determine the
IV_Index
+ that the current network is on. This information is
only useful
+ for provisioning.
+
uint32 SecondsSinceLastHeard [read-only]

This property may be read at any time to determine the
number of
seconds since mesh network layer traffic was last detected
on
this node's network.

+Mesh Provisioning Hierarchy
+============================
+Service org.bluez.mesh
+Interface org.bluez.mesh.Provisioning1

We may want to call this interface "org.bluez.mesh.Manager1", because it contains methods surpassing provisioning procedure

+Object path /org/bluez/mesh/node<xxxx>
+ where xxxx is a 4-digit hexadecimal number generated by
daemon
+
+Methods:
+ void UnprovisionedScan(uint16 seconds)
+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to start
listening
+ (scanning) for unprovisioned devices in the area.
Scanning
+ will continue for the specified number of seconds, or,
if 0 is
+ specified, then continuously until
UnprovisionedScanCancel() is
+ called or if AddNode() method is called.
+
+ Each time a unique unprovisioned beacon is heard, the
+ ScanResult() method on the app will be called with the
result.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.NotAuthorized
+
+ void UnprovisionedScanCancel(void)
+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to stop listening
+ (scanning) for unprovisioned devices in the area.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.NotAuthorized
+
+ void AddNode(array{byte}[16] uuid)
+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to add the
+ unprovisioned device specified by uuid, to the Network.
+
+ The uuid parameter is a 16-byte array that contains
Device UUID
+ of the unprovisioned device to be added to the network.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+
+ void AddNetKey(uint16 net_index)

I suggest we change this method to
AddNetKey(uint16 dest, uint16 net_index)

Since in the current proposed approach the daemon is the only entity in possession of key vaues, the configuration messages that contain the key values in their payload will need to be generated by the daemon. The modified method will allow to send the network key(s) to any node. If a network key specified by the net_index, does not exist, it will be generated and recorded, effectively creating a new subnet. Alternatively, this functionality can be covered by two methods:
CreateSubnet(uint16 net_index) to generate a key value and AddNetKey(uint16 dest, uint16 net_index) to send the keys to a remote or local node

So I think the biggest problem with having methods *sometimes* add a key to the *local* database, but always add the key to a remote node is Indeterminacies. We are trying to potentially do two things at once, and either one or both can fail.

I strongly believe that the method calls to add a key (or delete it or update it) to our local key storage needs to be a distinct requests... Yes, we only save *one* method call by overloading the functionality into a single call. But separating Local operations from Remote operations keeps it clear, if there is a failure, at exactly which step the failure occurred. The Application is not left wondering if there is an unused key in the local database, or if the remote device now has a key that nobody else does.

In order to separate "local" form "remote node" operations:

Rename: AddNetKey(idx) -> CreateSubnet(idx) UpdateNetKey(idx) -> UpdateSubnet(idx) DeleteKey(idx) -> DeleteSubnet(idx) AddAppKey(net_idx, app_idx) -> CreateAppKey(net_idx, app_idx) UpdateAppKey(net_idx, app_idx) -> UpdateAppKey(app_idx)

New methods to send the keys to nodes:
             AddNetKey(uint16 dest, uint16 net_idx, boolean update) AddAppKey(uint16 dest, uint16 app_idx, boolean update)

+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to generate and
add a new
+ network subnet key.
+
+ The net_index parameter is a 12-bit value (0x001-0xFFF)
+ specifying which net key to add.
+
+ This call affects the local bluetooth-daemon key
database only.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+ org.bluez.mesh.Error.AlreadyExists
+
+ void UpdateNetKey(uint16 net_index)

I suggest we change this method to UpdateNetKey(uint16 dest, uint16 net_index)
This will allow to send an updated value of the network key to any node. If the updated network key value specified by the net_index, does not exist, it will be generated and recorded.

Same comment here... I intended this for this method to modify the local key database only, with no overloaded functionality of sending the update key to one of the potentially hundreds of other nodes.

So, when the network key is updated locally, shouldn't the phase change automatically?

+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to generate a new
network
+ subnet key, and set it's key refresh state to Phase 1.
+
+ The net_index parameter is a 12-bit value (0x000-0xFFF)
+ specifying which net key to update. Note that the
subnet must
+ exist prior to updating.
+
+ This call affects the local bluetooth-daemon key
database only.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+ org.bluez.mesh.Error.DoesNotExist
+
+ void DeleteNetKey(uint16 net_index)
+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to delete a
subnet.
+
+ The net_index parameter is a 12-bit value (0x001-0xFFF)
+ specifying which net key to delete. The primary net key
(0x000)
+ may not be deleted.
+
+ This call affects the local bluetooth-daemon key
database only.

Just curious what would happen if there are remote nodes in possession of this network key and this method is called? Potentially this may lead to an "unconfigurable" subnet...

+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+ org.bluez.mesh.Error.DoesNotExist
+
+ void SetKeyPhase(uint16 net_index, uint8 phase)
+ This method is used to set the master key update phase
of the
+ given subnet.
+
+ The net_index parameter is a 12-bit value (0x000-0xFFF)
+ specifying which subnet phase to set.
+
+ The phase parameter is used to cycle the local key
database
+ through the phases as defined by the Mesh Profile
Specification.
+ Allowed values:
+ 0 - Cancel Key Refresh (May only be called from
Phase 1,
+ and should never be called once the new
key has
+ started propagating)
+ 1 - Invalid Argument (see NetKeyUpdate method)
+ 2 - Go to Phase 2 (May only be called from
Phase 1)
+ 3 - Complete Key Refresh procedure (May only be
called
+ from Phase 2)
+
+ This call affects the local bluetooth-daemon key
database only.

This method is also intended to modify the state of the keys locally only. Only after the local phase has been recorded would the phase change be propogated to the wider mesh

+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+ org.bluez.mesh.Error.DoesNotExist
+
+ void AddAppKey(uint16 net_index, uint16 app_index)

Similar to the network key methods, needs to include dest parameter

+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to generate and
add a new
+ application key.
+
+ The net_index parameter is a 12-bit value (0x000-0xFFF)
+ specifying which net key to bind the application key
to.
+
+ The app_index parameter is a 12-bit value (0x000-0xFFF)
+ specifying which app key to add.
+
+ This call affects the local bluetooth-daemon key
database only.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+ org.bluez.mesh.Error.AlreadyExists
+
+ void UpdateAppKey(uint16 app_index)
+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to generate a new
+ application key.
+
+ The app_index parameter is a 12-bit value (0x000-0xFFF)
+ specifying which app key to update. Note that the
subnet that
+ the key is bound to must exist and be in Phase 1.
+
+ This call affects the local bluetooth-daemon key
database only.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+ org.bluez.mesh.Error.DoesNotExist
+
+ void DeleteAppKey(uint16 app_index)
+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to delete an
application
+ key.
+
+ The app_index parameter is a 12-bit value (0x000-0xFFF)
+ specifying which app key to delete.
+
+ This call affects the local bluetooth-daemon key
database only.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+ org.bluez.mesh.Error.DoesNotExist
+
+ void DeleteRemoteNode(uint16 primary, uint8 cnt)

Let's call this method DeleteNode()
Do we need to specify the element count?

I want to be clear that this again only affects the local key database. We do have the ability to delete Local nodes with the Leave() method. I want to be clear with this method that again, no communication is made... This simply deletes a Remote Node Device key from the local database. I included a count parameter so that storage of the device keys could be optimized such that all element unicast addresses are accounted for. It is 100% legal to send a Device Key encoded message to a non-primary element of a Node, so we might have redundant storages of the device keys under every unicast address, in the local database.

+
+ This method is used by the application that supports
+ org.bluez.mesh.Provisioner1 interface to delete a
remote node
+ from the local device key database.
+
+ The primary parameter specifies the unicast address of
the
+ the node being deleted, and the number of elements that
were
+ assigned to it.
+
+ This call affects the local bluetooth-daemon key
database only.
+
+ PossibleErrors:
+ org.bluez.mesh.Error.InvalidArguments
+ org.bluez.mesh.Error.NotAuthorized
+ org.bluez.mesh.Error.DoesNotExist

Mesh Application Hierarchy
==========================
@@ -247,6 +502,7 @@ An example mesh application hierarchy may look like this:

 			|   - org.freedesktop.DBus.ObjectManager
 			|   - org.bluez.mesh.Application1
 			|   - org.bluez.mesh.Attention1 (optional)
+			|   - org.bluez.mesh.Provisioner1

(optional,Provisioner)
|
-> /com/example/agent
| | - org.bluez.mesh.ProvisionAgent1
@@ -325,6 +581,22 @@ Methods:

The data parameter is the incoming message.

+ void DevKeyMessageReceived(uint16 source, uint16 net_index,
+ array{byte}
data)
+
+ This method is called by meshd daemon when a message
arrives
+ addressed to the application, which was sent with the
remote
+ node's device key.
+
+ The source parameter is unicast address of the remote
+ node-element that sent the message.
+
+ The net_index parameter indicates what subnet the
message was
+ received on, and if a response is required, the same
subnet
+ must be used to send the response.
+
+ The data parameter is the incoming message.
+
void UpdateModelConfiguration(uint16 model_id, dict config)

This method is called by bluetooth-meshd daemon when a
model's
@@ -383,7 +655,7 @@ Object path freely definable
This is an optional interface that implements health attention timer.

Methods:
- void SetTimer(uint8 element_index, uint16 time)
+ void SetTimer(uint8 element_index, uint16 time)

The element_index parameter is the element's index within
the
node where the health server model is hosted.
@@ -406,6 +678,76 @@ Methods:
org.bluez.mesh.Error.NotSupported

+Mesh Provisioner Hierarchy
+============================
+Service unique name
+Interface org.bluez.mesh.Provisioner1
+Object path freely definable
+
+ ScanResult(int8 rssi, array{byte} data)
+
+ The method is called from the bluetooth-meshd daemon
when a
+ unique UUID has been seen during UnprovisionedScan()
for
+ unprovsioned devices.
+
+ The rssi parameter is a signed, normalized measurement
of the
+ signal strength of the recieved unprovisioned beacon.
+
+ The data parameter is a variable length byte array,
that may
+ have 1, 2 or 3 distinct fields contained in it
including the 16
+ byte remote device UUID (always), a 32 bit mask of OOB
+ authentication flags (optional), and a 32 bit URI hash
(if URI
+ bit set in OOB mask). Whether these fields exist or not
is a
+ decision of the remote device.
+
+ If a beacon with a UUID that has already been reported
is
+ recieved by the daemon, it will be silently discarded
unless it
+ was recieved at a higher rssi power level.
+
+
+ uint16 net_index, uint8 flags, uint32 iv_index, uint16 unicast
+ RequestProvData
()
+
+ This method is implemented by a Provisioner capable
application
+ and is called when the remote device has been fully
+ authenticated and confirmed.
+
+ Return Parameters are from the Mesh Profile Spec:
+ net_index - Subnet index of the net_key
+ flags - Flags for IV_Update and Key Refresh
+ iv_index - Current IvIndex being used on the network
+ unicast - Primary Unicast address of the new node
+
+ PossibleErrors:
+ org.bluez.mesh.Error.Abort
+
+ void AddNodeComplete(array{byte}[16] uuid, uint16 unicast,
uint8 count)
+
+ This method is called when the node provisioning
initiated
+ by an AddNode() method call successfully completed.
+
+ The unicast parameter is the primary address that has
been
+ assigned to the new node, and the address of it's
config server.
+
+ The count parameter is the number of unicast addresses
assigned
+ to the new node.
+
+ The new node may now be sent messages using the
credentials
+ supplied by the RequestProvData method.
+
+ void AddNodeFailed(array{byte}[16] uuid, string reason)
+
+ This method is called when the node provisioning
initiated by
+ AddNode() has failed. Depending on how far Provisioning
+ proceeded before failing, some cleanup of cached data
may be
+ required.
+
+ The reason parameter identifies the reason for
provisioning
+ failure. The defined values are: "aborted", "timeout",
+ "bad-pdu", "confirmation-failed", "out-of-resources",
+ "decryption-error", "unexpected-error",
+ "cannot-assign-addresses".
+
Provisioning Agent Hierarchy
============================
Service unique name
@@ -441,6 +783,7 @@ Methods:
the local role is Provisioner.

void DisplayString(string value)
+
This method is called when the Daemon has something
important
for the Agent to Display, but does not require any additional input locally. For instance: "Enter "ABCDE" on remote
device".
@@ -451,9 +794,8 @@ Methods:
for the Agent to Display, but does not require any additional input locally. For instance: "Enter 14939264 on remote
device".

- The type parameter indicates the display
method. Allowed values
+ The type parameter indicates the display method.
Allowed values
are:
-
"blink" - Locally blink LED "beep" - Locally make a noise "vibrate" - Locally vibrate
@@ -466,12 +808,11 @@ Methods:

uint32 PromptNumeric(string type)

- This method is called when the Daemon has requires the
user to
- enter a 1-99999999 digit decimal value.
+ This method is called when the Daemon requests the user
to
+ enter a decimal value between 1-99999999.

The type parameter indicates the input method. Allowed
values
are:
-
"blink" - Enter times remote LED blinked "beep" - Enter times remote device beeped "vibrate" - Enter times remote device vibrated @@ -
483,14 +824,13
@@ Methods:
This agent should prompt the user for specific input.
For
instance: "Enter value being displayed by remote device".

- array{byte} PromptStatic(string type)
+ array{byte}[16] PromptStatic(string type)

This method is called when the Daemon requires a 16 octet
byte
array, as an Out-of-Band authentication.

The type parameter indicates the input method. Allowed
values
are:
-
"static-oob" - return 16 octet array "in-alpha" - return 16 octet alpha array

@@ -511,7 +851,6 @@ Properties:
array{string} Capabilities [read-only]

An array of strings with the following allowed values:
-
"blink"
"beep"
"vibrate"
@@ -528,7 +867,6 @@ Properties:

Indicates availability of OOB data. An array of strings with the following allowed values:
-
"other"
"uri"
"machine-code-2d"
@@ -546,8 +884,3 @@ Properties:

Uniform Resource Identifier points to out-of-band (OOB) information (e.g., a public key)
-
-
-Mesh Provisioner Hierarchy
-==========================
-<TBD>

Inga