Re: [PATCH v2 12/15] doc: PKEX support for DPP

[Denis Kenzior <denkenz@gmail.com>]

Hi James,

On 10/26/23 15:26, James Prestwood wrote:
> PKEX is part of the WFA EasyConnect specification and is
> an additional boostrapping method (like QR codes) for
> exchanging public keys between a configurator and enrollee.
> 
> PKEX operates over wifi and requires a key/code be exchanged
> prior to the protocol. The key is used to encrypt the exchange
> of the boostrapping information, then DPP authentication is
> started immediately aftewards.
> 
> This can be useful for devices which don't have the ability to
> scan a QR code, or even as a more convenient way to share
> wireless credentials if the PSK is very secure (i.e. not a
> human readable string).
> 
> PKEX would be used via the three DBus APIs on a new interface
> SharedCodeDeviceProvisioning.
> 
> ConfigureEnrollee(a{sv}) will start a configurator with a
> static shared code (optionally identifier) passed in with the
> dictionary key.
> 
> StartConfigurator(object agent_path) will start listening and
> wait for an Enrollee to send a PKEX exchange request. Once
> received the configurator will call out to an agent
> (distinguished by 'agent_path') and request the code using the
> identifier sent by the enrollee. If no identifier was sent the
> protocol will fail. This method allows for configuring one of
> several enrollees, assuming the agent has the ability to
> look up the identifier.
> 
> StartEnrollee(a{sv}) will start a PKEX enrollee. Enrollees will
> begin iterating a channel list sending out PKEX exchange
> requests and waiting for a configurator to respond.
> 
> After the PKEX protocol is finished, DPP bootstrapping keys have
> been exchanged and DPP Authentication will start, followed by
> configuration.
> ---
>   doc/device-provisioning-api.txt | 67 +++++++++++++++++++++++++++++++++
>   1 file changed, 67 insertions(+)
> 

Okay, though much of this should be in the API doc itself.

> diff --git a/doc/device-provisioning-api.txt b/doc/device-provisioning-api.txt
> index ac204f46..02856571 100644
> --- a/doc/device-provisioning-api.txt
> +++ b/doc/device-provisioning-api.txt
> @@ -71,3 +71,70 @@ Properties	boolean Started [readonly]
>   
>   			Indicates the DPP URI. This property is only available
>   			when Started is true.
> +
> +
> +Interface	net.connman.iwd.SharedCodeDeviceProvisioning [Experimental]
> +Object path	/net/connman/iwd/{phy0,phy1,...}/{1,2,...}
> +
> +		ConfigureEnrollee(a{sv})
> +			Starts a DPP configurator using a shared code (and
> +			optionally identifier) set in the dictionary argument.
> +			Valid dictionary keys are:
> +
> +			{
> +				Code: <The shared code to use>
> +				Identifier: <Optional identifier>
> +			}

You really need to specify the types of the entries.  Since you repeat this at 
least twice, this may need to be a separate section.

> +
> +			As with the DeviceProvisioning interface, configurators
> +			must be currently connected to start.
> +
> +			Possible errors:	net.connman.iwd.Busy
> +						net.connman.iwd.NotConnected
> +						net.connman.InvalidArguments
> +
> +		StartConfigurator(object agent_path)
> +			Start a shared code configurator using an agent to
> +			obtain the shared code. This method is meant for an
> +			automated use case where a configurator is capable of
> +			configuring multiple enrollees, and distinguishing
> +			between them by their identifier.
> +
> +			After starting the configurator will listen on channel.
> +			Upon receiving an enrollees initial request it will
> +			make an agent call (on 'agent_path') to obtain the
> +			code associated with the enrollee.
> +
> +			As with the DeviceProvisioning interface, configurators
> +			must be currently connected to start.
> +
> +			Possible errors:	net.connman.iwd.Busy
> +						net.connman.iwd.NotConnected
> +						net.connman.iwd.InvalidArguments

Where is the agent documentation?

> +
> +		StartEnrollee(a{sv})
> +			Start a shared code enrollee using the Code and
> +			optionally identifier passed in the dictionary argument.
> +			As with the configurator, valid dictionary keys are:
> +
> +			{
> +				Code: <The shared code to use>
> +				Identifier: <Optional identifier>
> +			}
> +
> +			As with the DeviceProvisioning interface, enrollees
> +			must be disconnected in order to start.
> +
> +			Possible errors:	net.connman.iwd.Busy
> +						net.connman.iwd.InvalidArguments
> +
> +Properties	boolean Started [readonly]
> +
> +			True if shared code device provisioning is currently
> +			active. (configurator or enrollee is started)
> +
> +		string Role [readonly, optional]
> +
> +			Indicates the DPP role. Possible values are "enrollee"
> +			or "configurator". This property is only available when
> +			Started is true.

Regards,
-Denis