diff mbox series

[BlueZ,2/4] doc/mesh: Change API to deliver tokens via JoinComplete

Message ID 20200408205255.45112-3-michal.lowas-rzechonek@silvair.com (mailing list archive)
State Superseded
Delegated to: Brian Gix
Headers show
Series mesh: Always deliver tokens via JoinComplete | expand

Commit Message

Michał Lowas-Rzechonek April 8, 2020, 8:52 p.m. UTC 
If Application is not be able to reliably store the token, the daemon
will end up with a uncontrollable node in its database.

Let's fix the issue by always delivering tokens using JoinComplete call,
and expecting a reply - if the application return an error, daemon will
get rid of the node.
---
 doc/mesh-api.txt | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

Comments

Stotland, Inga April 8, 2020, 11:04 p.m. UTC | #1 
Hi Michal,

On Wed, 2020-04-08 at 22:52 +0200, Michał Lowas-Rzechonek wrote:
> If Application is not be able to reliably store the token, the daemon
> will end up with a uncontrollable node in its database.
> 
> Let's fix the issue by always delivering tokens using JoinComplete call,
> and expecting a reply - if the application return an error, daemon will
> get rid of the node.
> ---
>  doc/mesh-api.txt | 22 +++++++++++++++-------
>  1 file changed, 15 insertions(+), 7 deletions(-)
> 
> diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt
> index c7374703b..08e34096d 100644
> --- a/doc/mesh-api.txt
> +++ b/doc/mesh-api.txt
> @@ -29,6 +29,10 @@ Methods:
>  		therefore attempting to call this function using already
>  		registered UUID results in an error.
>  
> +		When provisioning finishes, the daemon will call either
> +		JoinComplete or JoinFailed method on object implementing
> +		org.bluez.mesh.Application1 interface.
> +
>  		PossibleErrors:
>  			org.bluez.mesh.Error.InvalidArguments
>  			org.bluez.mesh.Error.AlreadyExists,
> @@ -123,7 +127,7 @@ Methods:
>  		PossibleErrors:
>  			org.bluez.mesh.Error.InvalidArguments
>  
> -	uint64 token CreateNetwork(object app_root, array{byte}[16] uuid)
> +	void 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
> @@ -155,11 +159,14 @@ Methods:
>  		unicast address (0x0001), and create and assign a net_key as the
>  		primary network net_index (0x000).
>  
> +		When creation finishes, the daemon will call JoinComplete method
> +		on object implementing org.bluez.mesh.Application1 interface.
> +
>  		PossibleErrors:
>  			org.bluez.mesh.Error.InvalidArguments
>  			org.bluez.mesh.Error.AlreadyExists,
>  
> -	uint64 token Import(object app_root, array{byte}[16] uuid,
> +	void Import(object app_root, array{byte}[16] uuid,

I would like to better understand the rationale behind this API change.

What situation exactly are we trying to address here:
- an app calling ImportNode or Create methods without the capacity to
actually store the returned token?
- an app calling ImportNode or Create methods and crashing before
receiving/storing the token?


>  				array{byte}[16] dev_key,
>  				array{byte}[16] net_key, uint16 net_index,
>  				dict flags, uint32 iv_index, uint16 unicast)
> @@ -204,11 +211,8 @@ Methods:
>  		The unicast parameter is the primary unicast address of the
>  		imported node.
>  
> -		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.
> +		When import finishes, the daemon will call JoinComplete method
> +		on object implementing org.bluez.mesh.Application1 interface.
>  
>  		PossibleErrors:
>  			org.bluez.mesh.Error.InvalidArguments,
> @@ -770,6 +774,10 @@ Methods:
>  		permanently remove the identity of the mesh node by calling
>  		Leave() method.
>  
> +		If this method returns an error, the daemon will assume that the
> +		application failed to preserve the token, and will remove the
> +		freshly created node.
> +
>  	void JoinFailed(string reason)
>  
>  		This method is called when the node provisioning initiated by
diff mbox series

Patch

diff --git a/doc/mesh-api.txt b/doc/mesh-api.txt
index c7374703b..08e34096d 100644
--- a/doc/mesh-api.txt
+++ b/doc/mesh-api.txt
@@ -29,6 +29,10 @@  Methods:
 		therefore attempting to call this function using already
 		registered UUID results in an error.
 
+		When provisioning finishes, the daemon will call either
+		JoinComplete or JoinFailed method on object implementing
+		org.bluez.mesh.Application1 interface.
+
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.AlreadyExists,
@@ -123,7 +127,7 @@  Methods:
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments
 
-	uint64 token CreateNetwork(object app_root, array{byte}[16] uuid)
+	void 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
@@ -155,11 +159,14 @@  Methods:
 		unicast address (0x0001), and create and assign a net_key as the
 		primary network net_index (0x000).
 
+		When creation finishes, the daemon will call JoinComplete method
+		on object implementing org.bluez.mesh.Application1 interface.
+
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments
 			org.bluez.mesh.Error.AlreadyExists,
 
-	uint64 token Import(object app_root, array{byte}[16] uuid,
+	void Import(object app_root, array{byte}[16] uuid,
 				array{byte}[16] dev_key,
 				array{byte}[16] net_key, uint16 net_index,
 				dict flags, uint32 iv_index, uint16 unicast)
@@ -204,11 +211,8 @@  Methods:
 		The unicast parameter is the primary unicast address of the
 		imported node.
 
-		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.
+		When import finishes, the daemon will call JoinComplete method
+		on object implementing org.bluez.mesh.Application1 interface.
 
 		PossibleErrors:
 			org.bluez.mesh.Error.InvalidArguments,
@@ -770,6 +774,10 @@  Methods:
 		permanently remove the identity of the mesh node by calling
 		Leave() method.
 
+		If this method returns an error, the daemon will assume that the
+		application failed to preserve the token, and will remove the
+		freshly created node.
+
 	void JoinFailed(string reason)
 
 		This method is called when the node provisioning initiated by