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. After a configurable delay, the device repeats the DHCP request to obtain
   an IP address from the authenticated VLAN.

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.delay | integer (seconds) | 5 | 0 | 60 (1 minute) | Delay before the DHCP client reacquires a lease after a PNAC (802.1X) port authentication state change. This is needed when the network switch reassigns the port to a different access VLAN based on the authentication result. 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,102 @@ 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
+
+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 a configurable delay
+   ([`pnac.dhcp.reacquire.delay`](CONFIG-PROPERTIES.md), default 5 seconds), the device
+   repeats the DHCP request to obtain an IP address from the authenticated VLAN.
+   The delay ensures the switch has completed the VLAN transition before the DHCP client
+   attempts to acquire a new lease.
+
+### 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, and trusted CA certificates for verifying the authentication
+  server's TLS certificate.
+
+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.delay` | 5s | Delay before DHCP reacquire 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. associating, authenticating, connected, disconnected), 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,

pkg/edgeview/src/network.go

@@ -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/pillar/base/logobjecttypes.go

@@ -179,6 +179,8 @@ const (
 	KubeAppFailover LogObjectType = "kube_app_failover"
 	// EvalStatusLogType : type for EvalStatus log entries
 	EvalStatusLogType LogObjectType = "eval_status"
+	// EnrolledCertStatusLogType : type for EnrolledCertificateStatus log entries.
+	EnrolledCertStatusLogType LogObjectType = "enrolled_cert_status"
 )
 
 // RelationObjectType :

pkg/pillar/cipher/cipher.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
 }
 

pkg/pillar/cmd/nim/nim.go

@@ -13,6 +13,7 @@ import (
 	"strings"
 	"time"
 
+	eveinfo "github.com/lf-edge/eve-api/go/info"
 	"github.com/lf-edge/eve/pkg/pillar/agentbase"
 	"github.com/lf-edge/eve/pkg/pillar/agentlog"
 	"github.com/lf-edge/eve/pkg/pillar/base"
@@ -80,6 +81,8 @@ type nim struct {
 	subNetworkInstanceConfig pubsub.Subscription
 	subEdgeNodeClusterStatus pubsub.Subscription
 	subKubeUserServices      pubsub.Subscription
+	subVaultStatus           pubsub.Subscription
+	subEnrolledCertStatus    pubsub.Subscription
 
 	// Publications
 	pubDummyDevicePortConfig pubsub.Publication // For logging
@@ -91,10 +94,13 @@ type nim struct {
 	pubCipherMetrics         pubsub.Publication
 	pubCachedResolvedIPs     pubsub.Publication
 	pubWwanConfig            pubsub.Publication
+	pubPNACMetrics           pubsub.Publication
 
 	// Metrics
-	agentMetrics  *controllerconn.AgentMetrics
-	cipherMetrics *cipher.AgentMetrics
+	agentMetrics   *controllerconn.AgentMetrics
+	cipherMetrics  *cipher.AgentMetrics
+	metricInterval uint32 // In seconds
+	publishTicker  *flextimer.FlexTickerHandle
 
 	// Configuration
 	globalConfig       types.ConfigItemValueMap
@@ -219,11 +225,12 @@ func (n *nim) run(ctx context.Context) (err error) {
 	stillRunning := time.NewTicker(stillRunTime)
 	n.PubSub.StillRunning(agentName, warningTime, errorTime)
 
-	// Publish metrics for zedagent every 10 seconds
-	interval := 10 * time.Second
+	// Publish network metrics
+	interval := time.Duration(n.metricInterval) * time.Second
 	max := float64(interval)
 	min := max * 0.3
-	publishTimer := flextimer.NewRangeTicker(time.Duration(min), time.Duration(max))
+	publishTicker := flextimer.NewRangeTicker(time.Duration(min), time.Duration(max))
+	n.publishTicker = &publishTicker
 
 	// Periodically resolve the controller hostname to keep its DNS entry cached,
 	// reducing the need for DNS lookups on every controller API request.
@@ -243,6 +250,8 @@ func (n *nim) run(ctx context.Context) (err error) {
 		n.subWwanStatus,
 		n.subNetworkInstanceConfig,
 		n.subKubeUserServices,
+		n.subVaultStatus,
+		n.subEnrolledCertStatus,
 	}
 	for _, sub := range inactiveSubs {
 		if err = sub.Activate(); err != nil {
@@ -292,8 +301,16 @@ func (n *nim) run(ctx context.Context) (err error) {
 		case change := <-n.subKubeUserServices.MsgChan():
 			n.subKubeUserServices.ProcessChange(change)
 
-		case <-publishTimer.C:
+		case change := <-n.subVaultStatus.MsgChan():
+			n.subVaultStatus.ProcessChange(change)
+
+		case change := <-n.subEnrolledCertStatus.MsgChan():
+			n.subEnrolledCertStatus.ProcessChange(change)
+			n.handleEnrolledCertUpdate()
+
+		case <-publishTicker.C:
 			start := time.Now()
+			n.publishPNACMetrics()
 			err = n.cipherMetrics.Publish(n.Log, n.pubCipherMetrics, "global")
 			if err != nil {
 				n.Log.Error(err)
@@ -408,6 +425,14 @@ func (n *nim) initPublications() (err error) {
 	if err != nil {
 		return err
 	}
+
+	n.pubPNACMetrics, err = n.PubSub.NewPublication(pubsub.PublicationOptions{
+		AgentName: agentName,
+		TopicType: types.PNACMetricsList{},
+	})
+	if err != nil {
+		return err
+	}
 	return nil
 }
 
@@ -613,6 +638,27 @@ func (n *nim) initSubscriptions() (err error) {
 	if err != nil {
 		return err
 	}
+
+	n.subVaultStatus, err = n.PubSub.NewSubscription(pubsub.SubscriptionOptions{
+		AgentName:     "vaultmgr",
+		MyAgentName:   agentName,
+		TopicImpl:     types.VaultStatus{},
+		Activate:      false,
+		CreateHandler: n.handleVaultStatusCreate,
+		ModifyHandler: n.handleVaultStatusModify,
+		WarningTime:   warningTime,
+		ErrorTime:     errorTime,
+	})
+
+	n.subEnrolledCertStatus, err = n.PubSub.NewSubscription(pubsub.SubscriptionOptions{
+		AgentName:   "scepclient",
+		MyAgentName: agentName,
+		TopicImpl:   types.EnrolledCertificateStatus{},
+		Activate:    false,
+		Persistent:  true,
+		WarningTime: warningTime,
+		ErrorTime:   errorTime,
+	})
 	return nil
 }
 
@@ -661,6 +707,17 @@ func (n *nim) applyGlobalConfig(gcp *types.ConfigItemValueMap) {
 	timeout := gcp.GlobalValueInt(types.NetworkTestTimeout)
 	n.connTester.TestTimeout = time.Second * time.Duration(timeout)
 	n.connTester.DiagRemoteEndpoints = types.GetDiagRemoteEndpointURLs(n.Log, gcp)
+	metricInterval := gcp.GlobalValueInt(types.MetricInterval)
+	if metricInterval != 0 && n.metricInterval != metricInterval {
+		if n.publishTicker != nil {
+			interval := time.Duration(metricInterval) * time.Second
+			maxTime := float64(interval)
+			minTime := maxTime * 0.3
+			n.publishTicker.UpdateRangeTicker(
+				time.Duration(minTime), time.Duration(maxTime))
+		}
+		n.metricInterval = metricInterval
+	}
 	n.gcInitialized = true
 }
 
@@ -850,6 +907,31 @@ func (n *nim) handleKubeUserServicesDelete(_ interface{}, _ string, _ interface{
 	n.dpcManager.UpdateKubeUserServices(types.KubeUserServices{})
 }
 
+func (n *nim) handleVaultStatusCreate(_ interface{}, key string, statusArg interface{}) {
+	n.handleVaultStatusImpl(key, statusArg)
+}
+
+func (n *nim) handleVaultStatusModify(_ interface{}, key string, statusArg, _ interface{}) {
+	n.handleVaultStatusImpl(key, statusArg)
+}
+
+func (n *nim) handleVaultStatusImpl(_ string, statusArg interface{}) {
+	status := statusArg.(types.VaultStatus)
+	vaultIsReady := status.Name == types.DefaultVaultName &&
+		status.ConversionComplete &&
+		status.Status != eveinfo.DataSecAtRestStatus_DATASEC_AT_REST_ERROR
+	n.dpcManager.UpdateVaultReadiness(vaultIsReady)
+}
+
+func (n *nim) handleEnrolledCertUpdate() {
+	var enrolledCerts []types.EnrolledCertificateStatus
+	for _, item := range n.subEnrolledCertStatus.GetAll() {
+		certStatus := item.(types.EnrolledCertificateStatus)
+		enrolledCerts = append(enrolledCerts, certStatus)
+	}
+	n.dpcManager.UpdateEnrolledCerts(enrolledCerts)
+}
+
 func (n *nim) listPublishedDPCs(directory string) (dpcFilePaths []string) {
 	locations, err := os.ReadDir(directory)
 	if err != nil {
@@ -962,3 +1044,34 @@ func (n *nim) ingestDevicePortConfigFile(oldDirname string, newDirname string, n
 			filename, err)
 	}
 }
+
+func (n *nim) publishPNACMetrics() {
+	var pnacMetricsList types.PNACMetricsList
+	dnsObj, err := n.pubDeviceNetworkStatus.Get("global")
+	if err != nil {
+		return
+	}
+	dns, ok := dnsObj.(types.DeviceNetworkStatus)
+	if !ok {
+		return
+	}
+	for _, port := range dns.Ports {
+		if port.IfName == "" || !port.PNAC.Enabled {
+			continue
+		}
+		ifIndex, exists, err := n.networkMonitor.GetInterfaceIndex(port.IfName)
+		if !exists || err != nil {
+			continue
+		}
+		metrics, err := n.networkMonitor.GetPNACMetrics(ifIndex)
+		if err != nil {
+			n.Log.Error(err)
+		} else {
+			pnacMetricsList.Ports = append(pnacMetricsList.Ports, metrics)
+		}
+	}
+	err = n.pubPNACMetrics.Publish(pnacMetricsList.Key(), pnacMetricsList)
+	if err != nil {
+		n.Log.Error(err)
+	}
+}