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

Commit Message

James Prestwood Sept. 18, 2024, 5:40 p.m. UTC

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

Patch

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