Add SCEP certificate enrollment and 802.1x port-based network access control (PNAC)

SCEP (Simple Certificate Enrollment Protocol) enables automated certificate
enrollment from a CA server. IEEE 802.1x is a port-based network access control
(PNAC) standard that restricts network access on a switch port until the device
authenticates using a certificate (or other EAP method).

The 802.1x authentication is implemented using wpa_supplicant.
The SCEP client is implemented using github.com/smallstep/scep.

The end-to-end workflow is as follows:
1. Device sends a DHCP request with a vendor class identifier that identifies
   it as EVE OS.
2. The network switch places the port into a non-authenticated VLAN. Because
   it detects EVE OS, it allows the device to reach the controller and fetch
   network and SCEP configuration (needed to bootstrap the enrollment).
3. Device follows the SCEP profile to enroll a certificate, either by talking
   directly to the SCEP server or through a controller-provided SCEP proxy
   (essentially an HTTP proxy).
4. Device uses the enrolled certificate to authenticate the port via 802.1x.
   The switch then moves the port to the authenticated VLAN.
5. The device retries the DHCP request with exponential backoff (2s, 4s, 8s, ...)
   to obtain an IP address from the authenticated VLAN. Retries continue until
   the IP subnet changes (indicating the VLAN transition completed) or the
   configured maximum number of retries (pnac.dhcp.reacquire.max.retries,
   default 4) is reached. Setting this to 0 disables DHCP reacquire.

EVE publishes PNAC status, enrolled certificate status and PNAC metrics
to the controller.

Signed-off-by: Milan Lenco <milan@zededa.com>

Author: milan-zededa

.github/CODEOWNERS

@@ -31,6 +31,7 @@
 /pkg/pillar/cmd/downloader/   @milan-zededa @rouming
 /pkg/pillar/cmd/ledmanager/   @rucoder @rene
 /pkg/pillar/cmd/nim/          @milan-zededa
+/pkg/pillar/cmd/scepclient/   @milan-zededa
 /pkg/pillar/cmd/tpmmgr/       @rucoder @shjala
 /pkg/pillar/cmd/volumemgr/    @OhmSpectator @rouming @europaul
 /pkg/pillar/cmd/zedagent/     @OhmSpectator @milan-zededa @rouming @uncleDecart

docs/CONFIG-PROPERTIES.md

@@ -91,6 +91,9 @@
 | diag.probe.remote.http.endpoint | string | `"http://www.google.com"` | - | - | Remote endpoint (URL, IP instead of hostname is accepted) queried over HTTP to assess the state of network connectivity whenever the controller is not reachable. Used only for diagnostics (no functional impact). Set to an empty string to disable. |
 | diag.probe.remote.https.endpoint | string | `"https://www.google.com"` | - | - | Remote endpoint (URL, IP instead of hostname is NOT accepted) queried over HTTPS to assess the state of network connectivity whenever the controller is not reachable. Used only for diagnostics (no functional impact). Set to an empty string to disable. |
 | app.enable.tcp.mss.clamping | bool | true | - | - | Configuration property that enables EVE to automatically adjust (clamp) the TCP MSS on forwarded application traffic to match the path MTU, preventing fragmentation and connectivity issues on lower-MTU links. |
+| scep.retry.interval | timer in seconds | 300 (5 minutes) | 60 (1 minute) | 3600 (1 hour) | Interval between retry attempts for certificates that previously failed to enroll/renew or returned PENDING from the SCEP server. |
+| pnac.dhcp.reacquire.max.retries | integer | 4 | 0 | 8 | Maximum number of DHCP reacquire retries after a PNAC (802.1X) port authentication state change. When the network switch reassigns the port to a different access VLAN, EVE retries with exponential backoff (2s, 4s, 8s, ...) until the IP subnet changes or the retry limit is reached. Setting this value to 0 disables DHCP reacquire. |
+| dhcp.enable.vendorclassid | bool | true | - | - | Enables sending the DHCP Vendor Class Identifier (Option 60) to identify the device as EVE OS. This allows networks or DHCP servers to apply policies such as VLAN assignment or granting access to the EVE controller. Some badly configured DHCP servers may reject unknown vendor class IDs. Setting this to false disables sending the vendor class ID. |
 
 ## Log levels
 
@@ -156,3 +159,4 @@ Right now the following agents support per-agent log level settings:
 * msrv
 * domainmgr
 * diag
+* scepclient

docs/DEVICE-CONNECTIVITY.md

@@ -604,6 +604,104 @@ There are two levels of errors:
 - A particular management port could not be used to reach the controller. In that case
   the `ErrorInfo` for the particular `DevicePort` is set to indicate the error and timestamp.
 
+## Port-Based Network Access Control (802.1X) and SCEP Certificate Enrollment
+
+EVE supports IEEE 802.1X Port-Based Network Access Control (PNAC), allowing network switches
+to restrict port-level access until the device authenticates with a valid certificate.
+IEEE 802.1X is a standard for port-based network access control that works at Layer 2
+of the network stack. A switch port starts in an unauthorized state and only grants full
+network access after the connected device (the supplicant) successfully authenticates
+against an authentication server (typically a RADIUS server) via the switch (the authenticator).
+
+To obtain the certificate required for authentication, EVE implements SCEP (Simple Certificate
+Enrollment Protocol), a protocol designed for automated certificate enrollment from
+a Certificate Authority (CA). SCEP allows a device to generate a key pair, submit
+a Certificate Signing Request (CSR) to a SCEP server, and receive a signed certificate
+in return.
+
+The 802.1X supplicant is implemented using [wpa_supplicant](https://w1.fi/wpa_supplicant/)
+with EAP-TLS as the authentication method. The SCEP client is implemented using
+the [github.com/smallstep/scep](https://github.com/smallstep/scep) Go library.
+
+### Bootstrapping workflow
+
+![SCEP + PNAC Workflow](images/scep-pnac-workflow.png)
+
+The full workflow from an unauthenticated device to an authenticated network port is:
+
+1. **DHCP with vendor class identification**: The device sends a DHCP request that includes
+   a Vendor Class Identifier (DHCP Option 60) set to `LFEDGE-EVE`. This identifies the device
+   as running EVE OS to the network infrastructure.
+
+2. **Non-authenticated VLAN access**: The network switch places the port into a non-authenticated
+   (bootstrap) VLAN. Because the switch detects the EVE OS vendor class identifier, it allows
+   the device to reach the controller and fetch the network configuration including the SCEP
+   enrollment profile. This step is critical for bootstrapping — the device needs connectivity
+   to obtain the certificate it will later use for authentication.
+
+3. **SCEP certificate enrollment**: The device follows the SCEP profile received from
+   the controller to enroll a certificate. It can communicate with the SCEP server in one
+   of two ways:
+   - **Directly**: The device contacts the SCEP server URL specified in the profile.
+   - **Via controller proxy**: The device routes SCEP requests through a controller-provided
+     SCEP proxy (essentially an HTTP proxy), which is useful when the SCEP server is not
+     directly reachable from the bootstrap VLAN.
+
+4. **802.1X port authentication**: Once the certificate is enrolled, the device uses it
+   to authenticate the port via 802.1X EAP-TLS. Upon successful authentication, the switch
+   moves the port to the authenticated VLAN, granting full network access.
+
+5. **DHCP reacquisition**: After the port authentication state changes, the device retries
+   the DHCP request with exponential backoff (2s, 4s, 8s, ...) to obtain an IP address from
+   the authenticated VLAN. Retries continue until the IP subnet changes (indicating the VLAN
+   transition completed) or the configured maximum number of retries
+   ([`pnac.dhcp.reacquire.max.retries`](CONFIG-PROPERTIES.md), default 4) is reached.
+
+### Configuration
+
+PNAC and SCEP are configured through the controller using the device API:
+
+- **SCEP profiles** are defined in `EdgeDevConfig.ScepProfiles` and specify the SCEP server URL,
+  whether to use the controller proxy, a challenge password (encrypted), trusted CA certificates,
+  and CSR parameters (subject DN, SANs, key type, hash algorithm, renewal period).
+
+- **PNAC configurations** are defined in `EdgeDevConfig.Pnacs`, each referencing network adapter
+  and a SCEP profile by logical names. They specify the EAP method (currently EAP-TLS),
+  an optional EAP identity. If no EAP identity is configured, EVE will derive the identity from
+  the enrolled certificate, preferring the subject common name (CN), or the SAN URI if CN is absent.
+
+Relevant [configuration properties](CONFIG-PROPERTIES.md):
+
+| Property | Default | Description |
+|---|---|---|
+| `scep.retry.interval` | 300s (5 min) | Interval between retry attempts for failed or pending SCEP enrollments |
+| `pnac.dhcp.reacquire.max.retries` | 4 | Max DHCP reacquire retries (with exponential backoff) after 802.1X authentication state change. Set to 0 to disable |
+| `dhcp.enable.vendorclassid` | true | Enables sending DHCP Vendor Class Identifier (Option 60) as `LFEDGE-EVE` |
+
+### Certificate lifecycle
+
+The enrolled certificate is stored on the device along with its private key (kept in the vault
+for protection). EVE monitors the certificate's validity and automatically initiates renewal
+when the configured percentage of the certificate's lifetime has elapsed
+(controlled by `RenewPeriodPercent` in the CSR profile). If the SCEP server or CSR profile
+configuration changes, EVE will re-enroll the certificate against the new parameters.
+
+### Status and metrics reporting
+
+EVE publishes the following information to the controller:
+
+- **PNAC status** (per-port): Whether 802.1X is enabled, the current supplicant state
+  (e.g. connecting, authenticating, authenticated, failed), the timestamp of the last
+  successful authentication, and any authentication errors.
+
+- **Enrolled certificate status**: Details of the installed certificate including subject,
+  issuer, SANs, validity period, SHA-256 fingerprint, key type, and current certificate status
+  (e.g. valid, expired, pending enrollment).
+
+- **PNAC metrics** (per-port): EAPOL frame counters including frames received/transmitted,
+  EAPOL-Start and EAPOL-Logoff frames, EAP-Request/Response frames, and counts of invalid
+  or malformed frames.
+
 ## Air-Gap Mode
 
 Air-Gap mode allows a device to operate without connectivity to the main controller,

docs/images/scep-pnac-workflow.mmd

@@ -0,0 +1,87 @@
+sequenceDiagram
+    title EVE: SCEP Certificate Enrollment + IEEE 802.1x PNAC
+
+    participant Controller
+    participant zedagent
+    participant scepclient
+    participant nim
+    participant netmonitor
+    participant dhcpcd
+    participant Switch as Network Switch<br/>(+ RADIUS)
+    participant SCEP as SCEP Server<br/>(CA)
+
+    note over Controller, SCEP: 1. BOOT & DHCP BOOTSTRAP (onboarding VLAN)
+
+    nim ->> dhcpcd: start dhcpcd
+    dhcpcd ->> Switch: DHCP DISCOVER (Option 60: "LFEDGE-EVE")
+    note right of Switch: Switch detects EVE vendor class,<br/>assigns onboarding VLAN<br/>providing access to EVE controller
+    Switch -->> dhcpcd: DHCP OFFER (onboarding VLAN IP)
+
+    note over Controller, SCEP: 2. CONFIG FETCH (controller reachable via onboarding VLAN)
+
+    zedagent ->> Controller: HTTPS GET /config
+    Controller -->> zedagent: EdgeDevConfig { ScepProfiles, Pnacs }
+    zedagent ->> scepclient: pubsub: SCEPProfile
+    zedagent ->> nim: pubsub: DevicePortConfig { Port.PNAC }
+
+    note over Controller, SCEP: 3. SCEP CERTIFICATE ENROLLMENT
+
+    note over scepclient: Generate RSA key + CSR<br/>(subject DN, SAN from CSRProfile)
+    scepclient ->> SCEP: PKIOperation=PKCSReq { CSR, challenge }
+    note over scepclient, SCEP: (direct or via Controller SCEP proxy)
+
+    alt CertRep SUCCESS
+        SCEP -->> scepclient: Signed certificate
+    else CertRep PENDING
+        SCEP -->> scepclient: PENDING
+        note over scepclient: Retry (scep.retry.interval)
+        scepclient ->> SCEP: PKIOperation=GetCertInitial
+        SCEP -->> scepclient: Signed certificate
+    end
+
+    note over scepclient: Save cert -> /persist/pnac/<profile>.cert.pem<br/>Save key -> /persist/vault/pnac/<profile>.key.pem
+    scepclient ->> zedagent: pubsub: EnrolledCertificateStatus
+    scepclient ->> nim: pubsub: EnrolledCertificateStatus
+
+    note over Controller, SCEP: 4. IEEE 802.1x EAP-TLS AUTHENTICATION
+
+    note over nim: Reconcile: create WpaSupplicant item<br/>with enrolled cert + CA chain.<br/>Start wpa_supplicant (-D wired)<br/>Start wpa_cli event watcher
+
+    nim ->> Switch: EAPOL-Start
+    Switch -->> nim: EAP-Request/Identity
+    nim ->> Switch: EAP-Response/Identity (from cert CN)
+    nim -->> Switch: EAP-TLS handshake (mutual certificate auth)
+    Switch -->> nim: EAP-TLS handshake
+    note right of Switch: RADIUS validates client cert
+    Switch -->> nim: EAP-Success
+
+    note right of Switch: Port moved to<br/>authenticated VLAN
+
+    note over nim: wpa_cli watcher script writes<br/>/run/pnac/<ifName>:<br/>STATE: CONNECTED<br/>TIMESTAMP: <unix_time>
+
+    note over Controller, SCEP: 5. DHCP REACQUIRE (authenticated VLAN)
+
+    netmonitor ->> nim: PNACEvent { IsAuthenticated: true }<br/>(fsnotify on /run/pnac/<ifName>)
+    note over nim: Record current IPv4 subnet,<br/>schedule DHCP reacquire retry
+
+    loop Exponential backoff (2s, 4s, 8s, ...)
+        nim ->> dhcpcd: Increment ReacquireCounter<br/>(triggers dhcpcd restart)
+        dhcpcd ->> dhcpcd: release old lease, request new one
+        dhcpcd ->> Switch: DHCP DISCOVER
+        Switch -->> dhcpcd: DHCP OFFER (new VLAN IP)
+        netmonitor ->> nim: AddrChange event
+        alt Subnet changed
+            note over nim: VLAN transition complete, stop retries
+        else Same subnet & retries < pnac.dhcp.reacquire.max.retries (default 4)
+            note over nim: Schedule next retry
+        else Max retries reached
+            note over nim: Give up
+        end
+    end
+
+    note over Controller, SCEP: 6. STATUS REPORTING & CERT RENEWAL
+
+    zedagent ->> Controller: ZInfoMsg { PNACStatus, EnrolledCertStatus }
+    zedagent ->> Controller: ZMetricMsg { EAPOLFramesRx/Tx, ... }
+
+    note over scepclient: Monitor cert lifetime.<br/>At RenewPeriodPercent threshold:<br/>re-enroll -> re-authenticate

docs/images/scep-pnac-workflow.png

@@ -1415,7 +1415,7 @@ func runWireless() {
 		_, _ = runCmd(prog, args, true)
 
 		retbytes, err = os.ReadFile(
-			fmt.Sprintf("/run/nim/wpa_supplicant.%s.conf", port.IfName))
+			fmt.Sprintf("/run/nim/wpa_supplicant-%s.conf", port.IfName))
 		if err != nil {
 			continue
 		}

pkg/edgeview/src/network.go

@@ -31,6 +31,7 @@ func getEncryptionBlock(
 	decBlock.ProtectedUserData = zconfigDecBlockPtr.ProtectedUserData
 	decBlock.ClusterToken = zconfigDecBlockPtr.ClusterToken
 	decBlock.GzipRegistrationManifestYaml = zconfigDecBlockPtr.GzipRegistrationManifestYaml
+	decBlock.SCEPChallengePassword = zconfigDecBlockPtr.ScepChallengePassword
 	return decBlock
 }