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

[James Prestwood <prestwoj@gmail.com>]

Hi Denis,

On 10/29/23 3:27 PM, Denis Kenzior wrote:
> 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?

I wanted to get your preference, I can add a separate agent API 
specifically for shared code (RequestSharedCode), or we can piggy back 
off (since its the same signature):

RequestUserPassword(object network, string user)

Either way, I'll add more information about the agent interaction.

> 
>> +
>> +        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