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

[James Prestwood <prestwoj@gmail.com>]

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

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>
+			}
+
+			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
+
+		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.
-- 
2.25.1