[RFC 1/2] doc: Document new DeviceProvisioningAgent

[RFC 1/2] doc: Document new DeviceProvisioningAgent

[James Prestwood]

This moves the SharedCodeAgent docs into the AgentManager interface
and renames it to DeviceProvisioningAgent. The agent path parameter
was also removed from the StartConfigurator() method.
---
 doc/agent-api.txt               | 56 +++++++++++++++++++++++++++++++++
 doc/device-provisioning-api.txt | 48 ++++------------------------
 2 files changed, 62 insertions(+), 42 deletions(-)

diff --git a/doc/agent-api.txt b/doc/agent-api.txt
index e9bb95ca..dc5529f3 100644
--- a/doc/agent-api.txt
+++ b/doc/agent-api.txt
@@ -67,6 +67,31 @@ Methods		void RegisterAgent(object path)
 					 [service].NotFound
 					 [service].NotAvailable
 
+		void RegisterDeviceProvisioningAgent(object path)
+
+			Register an agent for handling Device Provisioning (DPP)
+			specific requests.
+
+			This includes:
+			 - Requests for shared codes when using shared code
+			   device provisioning.
+			 - Requests for certificate signing requests
+			 - Requests to send a certificate signing request
+
+			The details of these are explained in the DBus method
+			docs below for the
+			net.connman.iwd.DeviceProvisioningAgent interface.
+
+
+			Possible Errors: [service].InvalidArguments
+					 [service].AlreadyExists
+
+		void UnregisterDeviceProvisioningAgent(object path)
+
+			Unregisters an existing Device Provisioning agent
+
+			Possible Errors: [service].InvalidArguments
+					 [service].NotFound
 
 Agent hierarchy
 ===============
@@ -263,3 +288,34 @@ Methods		void Release() [noreply]
 		void CancelIPv6(object device, string reason) [noreply]
 
 			Same as CancelIPv4 above but for IPv6.
+
+DeviceProvisioningAgent hierarchy
+=================================
+
+Service		unique name
+Interface	net.connman.iwd.DeviceProvisioningAgent [Experimental]
+Object path	freely definable
+
+Methods		void Release() [noreply]
+
+			This method gets called when the service daemon
+			unregisteres the agent
+
+		void Cancel(string reason) [noreply]
+
+			This method gets called to indicate that the agent
+			request failed before a reply was returned. The
+			argument will indicate why the request is being
+			cancelled and may be "user-canceled", "timed-out" or
+			"shutdown".
+
+		string RequestSharedCode(string identifier)
+
+			This method gets called when a shared code is requested
+			for a particular enrollee, distingushed by the
+			identifier. The shared code agent should lookup the
+			identifier and return the shared code, or return an
+			error if not found.
+
+			Possible Errors:	[service].Error.Canceled
+						[service].Error.NotFound
diff --git a/doc/device-provisioning-api.txt b/doc/device-provisioning-api.txt
index 6cf16fb8..37d8f67e 100644
--- a/doc/device-provisioning-api.txt
+++ b/doc/device-provisioning-api.txt
@@ -132,14 +132,13 @@ Object path	/net/connman/iwd/{phy0,phy1,...}/{1,2,...}
 			Possible errors:	net.connman.iwd.Busy
 						net.connman.iwd.InvalidArguments
 
-		void StartConfigurator(object agent_path)
+		void StartConfigurator(void)
 
-			Start a shared code configurator using an agent
-			(distingushed by 'agent_path') 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.
+			Start a shared code configurator which depends on an
+			agent (registered via AgentManager). 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.
 
 			If the agent service disappears during the shared code
 			exchange it will be stopped, and the protocol will fail.
@@ -180,38 +179,3 @@ Properties	boolean Started [readonly]
 			Indicates the DPP role. Possible values are "enrollee"
 			or "configurator". This property is only available when
 			Started is true.
-
-SharedCodeAgent hierarchy
-=========================
-
-Service		unique name
-Interface	net.connman.iwd.SharedCodeAgent [Experimental]
-Object path	freely definable
-
-Methods		void Release() [noreply]
-
-			This method gets called when the service daemon
-			unregisters the agent.
-
-		string RequestSharedCode(string identifier)
-
-			This method gets called when a shared code is requested
-			for a particular enrollee, distingushed by the
-			identifier. The shared code agent should lookup the
-			identifier and return the shared code, or return an
-			error if not found.
-
-			Possible Errors:	[service].Error.Canceled
-						[service].Error.NotFound
-
-		void Cancel(string reason) [noreply]
-
-			This method gets called to indicate that the agent
-			request failed before a reply was returned. The
-			argument will indicate why the request is being
-			cancelled and may be "user-canceled", "timed-out" or
-			"shutdown".
-
-Examples	Requesting a shared code for an enrollee identified by "foo"
-
-			RequestSharedCode("foo") ==> "super_secret_code"
-- 
2.34.1

[RFC 2/2] doc: introduce DPP 802.1x agent APIs

[James Prestwood]

Introduces agent DBus APIs to support 802.1x provisioning via
DPP. Much of the 802.1x configuration process relies on
concepts that are out of IWD's scope to implement, hence an
agent can be used to enable that functionality.

There are 3 operations being offloaded from IWD into the
DeviceProvisioningAgent:

1. Generating a Certificate Signing Request (CSR):

  The CSR's themselves can use arbitrary OID's that contain
  device specific details. These details may be required
  by a CA server in order to issue client certificates. Trying
  to support this within IWD is not possible to do in a way
  that would work for all use-cases.

2. Sending the CSR to a CA server:

  Besides the fact that IWD should not be doing any TCP/IP
  communications directly, there are a number of protocols that
  wrap CSR's which CA servers can use.

3. Generating the 8021x network profile.

  There are two reasons for this. One is that the CSR generation
  is signed by a private key which IWD does not have access to.
  Since the agent signed the CSR it knows where the private key is
  and potentially what the password is if its encrypted.

  Second, offloading 802.1x profile generation is consistent with
  how IWD treats 802.1x profiles i.e. it does not modify or
  generate them.
---
 doc/agent-api.txt | 90 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/doc/agent-api.txt b/doc/agent-api.txt
index dc5529f3..338d4df0 100644
--- a/doc/agent-api.txt
+++ b/doc/agent-api.txt
@@ -319,3 +319,93 @@ Methods		void Release() [noreply]
 
 			Possible Errors:	[service].Error.Canceled
 						[service].Error.NotFound
+
+		string GenerateCertificateSigningRequest(void)
+
+			This is used by enrollees to request client certificates
+			for the network. When called the agent should generate a
+			CSR containing any fields required for the network (this
+			is all dependent on the network/infrastructure). The
+			agent should then return the CSR from this method,
+			base64-encoded in PKCS10 format.
+
+			To support enrolling to enterprise networks through
+			device provisioning an agent must implement this method.
+
+		void GenerateEnterpriseProfile(string ssid, dict creds)
+
+			This is used by enrollees being provisioned for an
+			802.1x network. This is the last step after the DPP
+			protocol has completed and IWD obtained client
+			certificates (following the CSR).
+
+			Requests that the agent generate an enterprise network
+			profile for the SSID, given some credentials obtained
+			via DPP. The contents of the credentials dictionary are
+			parsed from the DPP configuration response:
+
+			"EAPMethod" :	String value of the EAP method being
+					configured. Note: DPP only supports
+					EAP-TLS currently.
+
+			"ClientCert" :	A base64 DER-encoded certificate (or
+					list) for the client. This should be in
+					PKCS7 format. This is a mandatory
+					value.
+
+			"CACert" :	A base64 DER-encoded CA Certificate
+					(or list). This should be in PKCS7
+					format. This is an optional value.
+
+			"ServerDomainMask" :	Domain name contained in the
+						servers certificate, used to
+						validate the authenticity of the
+						server. This is an optional
+						value.
+
+			The agent is responsible for generating the enterprise
+			profile and placing it in IWD's profile directory.
+
+			To support enrolling to enterprise networks through
+			device provisioning an agent must implement this method.
+
+		a{sv} SendCertificateSigningRequest(string csr)
+
+			Requests that the agent send the certificate signing
+			request to the CA server. How this is done is entirely
+			up to the agent as there are many protocols/wrappers
+			around CSRs to accomplish this. Once the CA server
+			responds with the client certificates they should be
+			returned to IWD as the method return value.
+
+			The return value should contain a dictionary of
+			representing the enterprise credentials. This ultimately
+			gets converted into an "Enterprise Credentials" JSON
+			object (defined in the DPP spec 4.3.5.9) but for
+			API convenience/consistency the dictionary keys are
+			similar to what an IWD 8021x profile expects:
+
+			"ClientCert" :	A base64 DER-encoded certificate (or
+					list) for the client. This should be in
+					PKCS7 format. This is a mandatory
+					value.
+
+			"CACert" :	A base64 DER-encoded CA Certificate
+					(or list). This should be in PKCS7
+					format. This is an optional value.
+
+			"ServerDomainMask" :	Domain name contained in the
+						servers certificate, used to
+						validate the authenticity of the
+						server. This is an optional
+						value.
+
+			The EAP method is assumed to be the same as the current
+			connection the configurator is using. For this reason
+			the EAP method is not required.
+
+			To support configuring clients to an enterprise networks
+			through device provisioning an agent must implement this
+			method.
+
+			Possible Errors:	[service].Error.Failed
-- 
2.34.1