From 54d7287a4eb286ced57ea8afdc3355dbf5c1a8dc Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan Date: Tue, 2 Mar 2021 03:02:49 -0800 Subject: [PATCH 01/47] Initial draft --- L2/PAC/PortAccessControl.md | 334 ++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) create mode 100644 L2/PAC/PortAccessControl.md diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md new file mode 100644 index 000000000000..edec1e2defc7 --- /dev/null +++ b/L2/PAC/PortAccessControl.md @@ -0,0 +1,334 @@ + +# Port Access Control in SONiC + +High level design document version 0.1 + +# Table of Contents +- **[List of Tables](#list-of-tables)** +- **[Revision](#revision)** +- **[About this Manual](#about-this-manual)** +- **[Scope](#scope)** +- **[Definition / Abbreviation](#definition--abbreviation)** + - [Table 1 Abbreviations](#table-1-abbreviations) +- **[1 Feature Overview](#1-feature-overview)** + - [1.1 Port Access Control](#11-port-access-control) + - [1.1.1 Dot1x](#111-dot1x) + - [1.1.2 MAC Authentication Bypass](#112-mac-autentication-bypass) + - [1.3 Requirements](#13-requirements) + - [1.3.1 Functional Requirements](#131-functional-requirements) + - [1.3.2 Configuration and Management Requirements](#132-configuration-and-management-requirements) + - [1.3.3 Scalability Requirements](#133-scalability-requirements) + - [1.3.4 Warm Boot Requirements](#134-warm-boot-requirements) + - [1.4 Design Overview](#14-design-overview) + - [1.4.1 Basic Approach](#141-basic-approach) + - [1.4.2 Container](#142-container) + - [1.4.3 SAI Support](#143-sai-support) +- **[2 Functionality](#2-functionality)** + - [2.1 Target Deployment Use Cases](#21-target-deployment-use-cases) + - [2.2 Functional Description](#22-functional-description) +- **[3 Design](#3-design)** + - [3.1 Overview](#31-overview) + - [3.2 DB Changes](#32-db-changes) + - [3.2.1 Config DB](#321-config-db) + - [3.2.2 App DB](#322-app-db) + - [3.2.3 State DB](#323-state-db) + - [3.2.4 ASIC DB](#324-asic-db) + - [3.2.5 Counter DB](#325-counter-db) + - [3.3 Switch State Service Design](#33-switch-state-service-design) + - [3.3.1 Orchestration Agent](#331-orchestration-agent) + - [3.3.2 PAC daemons](#332-pac-daemons) + - [3.3.2.1 PAC Manager](#3321-pac-manager) + - [3.3.2.2 Authentication Manager](#3322-authentication-manager) + - [3.3.3 Other Process](#333-other-process) + - [3.4 SyncD](#34-syncd) + - [3.5 SAI](#35-sai) + - [3.6 Manageability](#36-manageability) + - [3.6.1 Data Models](#361-data-models) + - [3.6.2 Configuration Commands](#362-configuration-commands) + - [3.6.3 Show Commands](#363-show-commands) +- **[4 Flow Diagrams](#4-flow-diagrams)** +- **[5 Error Handling](#5-error-handling)** +- **[6 Serviceability and Debug](#6-serviceability-and-debug)** +- **[7 Warm Boot Support](#7-warm-boot-support)** +- **[8 Scalability](#8-scalability)** + - [8.1 Software scalability](#81-software-scalability) +- **[9 Limitation](#9-limitation)** +- **[10 Upgrade / Downgrade considerations](#10-upgrade--downgrade-considerations)** +- **[11 Unit Test](#11-unit-test)** +- **[12 Appendix: Sample configuration](#12-appendix-sample-configuration)** +- **[13 Internal Design Information](#13-internal-design-information)** + - [13.1 Future Design Enhancements](#131-future-design-enhancements) + +# List of Tables +[Table 1 Abbreviations](#table-1-abbreviations) + +# Revision +| Rev | Date | Author | Change Description | +| ---- | ---------- | ---------| ------------------ | +| 0.1 | 02/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Initial version | + +# About this Manual +This document provides general information about the Port Access Control feature in SONiC. + +# Scope +This document provides general information about the Port Access Control feature implementation in SONiC. + +# Definition / Abbreviation + +## Table 1 Abbreviations +| **Term** | **Meaning** | +| -------- | -------------------- | +| CoPP | Control Plane Policing | +| Dot1x | IEEE 802.1 standard | +| EAPOL | Extensible Authentication Protocol over LAN | +| MAB | MAC Authentication Bypass| +| PAC | Port Access Control | +| RADIUS | Remote Authentication Dial In User service | +| SONiC-CLI | Klish CLI used by management framework | + +# 1 Feature Overview + +## 1.1 Port Access Control +Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specified switch port. + +Local Area Networks (LANs) are often deployed in environments that permit unauthorized devices to be physically attached to the LAN infrastructure, or permit unauthorized users to attempt to access the LAN through equipment already attached. In such environments, it may be desirable to restrict access to the services offered by the LAN to those users and devices that are permitted to use those services. Port access control makes use of the physical characteristics of LAN infrastructures in order to provide a means of authenticating and authorizing devices attached to a LAN port that has point-to-point connection characteristics and of preventing access to that port in cases in which the authentication and authorization process fails. In this context, a port is a single point of attachment to the LAN, such as Ports of MAC bridges and associations between stations or access points in IEEE 802.11 Wireless LANs. + +### 1.1.1 Dot1x + +IEEE 802.1X is an IEEE Standard for Port Access Control (PAC) that provides an authentication mechanism to devices wishing to attach to a LAN. The standard defines Extensible Authentication Protocol Over LAN (EAPOL). The 802.1X standard describes an architectural framework within with authentication and consequent actions take place. It also establishes the requirements for a protocol between the authenticator and the supplicant, as well as between the authenticator and the authentication server. + +### 1.1.2 MAC Authentication Bypass +Simple devices like camera or printers which do not support 802.1x autentication can make use of MAB feature where the device gets authenticated based on the device MAC address. + +## 1.3 Requirements + +### 1.3.1 Functional Requirements +The following are the requirements for Port Access Control feature: +1. 802.1X is supported on physical interfaces only. +2. The interfaces cannot be part of a port-channel. +3. 802.1X is not supported on service port. +4. One can configure 802.1X interfaces for bridges using the following features: + Parking VLAN. + Dynamic VLAN. + MAB (MAC-based authentication bypass). +5. MAB, parking VLAN, and dynamic VLAN all require a bridge access port. +6. In traditional bridge mode, parking VLANs and dynamic VLANs both require the destination bridge to have a parking VLAN ID or dynamic VLAN ID tagged subinterface. +7. When you enable or disable 802.1X on ports, hostapd reloads; however, existing authorized sessions do not reset. +8. Changing the 802.1X interface, MAB, or parking VLAN settings do not reset existing authorized user ports. However, removing all 802.1X interfaces or changing any of the following RADIUS parameters restarts hostapd, which forces existing, authorized users to re-authenticate: + - RADIUS server IP address, shared secret, authentication port or accounting port. + - Parking VLAN ID. + - MAB activation delay. + - EAP re authentication period. +9. You can configure up to three RADIUS servers (in case of failover). However, do not use a SONiC switch as the RADIUS server. +10. You can configure 802.1X interfaces with dynamic ACLs in VLAN-aware bridge mode only. +Note: 802.1X on SONiC to be tested with only a few wpa_supplicant (Debian), Windows 10 and Windows 7 supplicants. +11. RADIUS authentication is supported with FreeRADIUS and Cisco ISE. +12. 802.1X supports simple login and password, PEAP/MSCHAPv2 (Win7) and EAP-TLS (Debian). +13. 802.1X supports RFC 5281 for EAP-TTLS, which provides more secure transport layer security. +14. Mako template-based configurations are not supported. +15. SONiC supports Multi Domain Authentication (MDA), where 802.1X is extended to allow authorization of multiple devices (a data and a voice device) on a single port and assign different VLANs to the devices based on authorization. + - MDA is enabled by default; however, you need to assign a tagged VLAN for voice devices (see Configure 802.1X Interfaces for a VLAN-aware Bridge). + - A maximum of four authorized devices (MAB + EAPOL) per port are supported. + - The 802.1X-enabled port must be a trunk port to allow tagged voice traffic from a phone; you cannot enable 802.1X on an access port. + - Only one untagged VLAN and one tagged VLAN is supported on the 802.1X enabled ports. + - Multiple MAB (non voice) devices on a port are supported for VLAN-aware bridges only. Authorization of multiple MAB devices for different VLANs is not supported. + + + +The following are the requirements for MAB feature: +1. A port can be configured to be either doing port-based authentication or doing Mac-based authentication. But only one mode at a given instance. +2. A port when enabled for Dot1x authentication needs to explicitly mention whether it is being enabled for port-based authentication mode or Mac-based authentication mode. +3. When a port is configured for Mac-based Dot1x Authentication, then if at least one client has actively authentication itself then port is placed in authorized state for other components. +4. When a port is configured for Mac-based Dot1x Authentication, then port is placed in un-authorized state if the last active authorized client ceases to exist. +5. When a port is operational in Mac-based Dot1x Authentication, then only the data traffic arriving on the port from authorized clients need to be forwarded. +6. When a port is operational in Mac-based Dot1x Authentication, accept EAPOL packets from all the clients (both authorized and unauthorized as well). +7. When a port is enabled for Guest vlan, then Mac-based dot1x authentication can not be enabled on that port. +8. When a port is enabled for vlan assignment, then Mac-based dot1x authentication could also be enabled on that port. As the vlan assignment is based on the user details of the client. +9. To enable Mac-based dot1x authentication on port it needs to be an Edge port. (Dot1s Configuration). +10. If Mac-based dot1x authentication is enabled on a port and if Mac-based VLANs or Subnet VLANs or Protocol VLANs are also enabled, then Mac-based dot1x authentication is disabled. +11. If Port-Mac Locking is enabled on the port and if Mac-based dot1x authentication is also enabled on the port. Then Port-Mac Locking needs to be disabled. +12. If a client already authentication on one port has roamed to another port on the switch, then the state (status, vlan etc) of the client on the prior port needs to be cleaned. +13. Timeout mechanism needs to be maintained per client so that inactive client.s status can be removed on the switch. +14. Multicast/Broadcast traffic arriving on the port that is enabled for Mac-based authentication would be forwarded accordingly. If the source Mac-address of the packet is from a authenticated user. +15. Even when the port is authorized, dot1x would still continue to send EAPOL for authentication as more users could join on the port. +16. Unauthenticated Vlan is per port configuration. By default unauthenticated vlan is zero (invalid and not operational). +17. In port-based dot1x, if the client fails authentication then port is placed in the unauthenticated vlan (if configured) +18. In mac-based dot1x, if the client fails authentication then client-mac is associated to the unauthenticated vlan (if configured). +19. Unauthenticated vlan deprecates the Guest vlan feature of supplicant mode, as it would be redundant. + +### 1.3.2 Configuration and Management Requirements + +### 1.3.3 Scalability Requirements + +### 1.3.4 Warm Boot Requirements +Port Access Control feature should work seamlessly across warmboot. Statistics must be preserved across warmboot. + +## 1.4 Design Overview + +### 1.4.1 Basic Approach + +### 1.4.2 Container +A new container sonic-security is introduced to hold all the port security applications. Apart from sonic-security container, code changes are made to SWSS container. + +### 1.4.3 SAI Overview + + +# 2 Functionality + +## 2.1 Target Deployment Use Cases + +When a client authenticates itself initially on the network, the Switch acts as the authenticator to the clients on the network and forwards the authentication request to the Radius server in the network. If the authentication succeeds then the port is placed in authorized state and the client is able to forward or receive traffic through the port. + +In a standard dot1x scenario, all the subsequent clients in the network that are connected to the same port need not authenticate to utilize the port on the switch. When Mac-based dot1x authentication is enabled, all the subsequent clients in the network that are connected to the same port need to authenticate themselves to utilize the port on the switch. + +If the vlan assignment is enabled in the Radius server then as part of the response message Radius server sends the vlan id the client is supposed to be in the 802.1x tunnel attributes. In the diagram above, the switch has placed three clients belonging to same port in the different vlans (vlan10 and vlan20) based on the user details of the clients. This implies that the client can connect from any port and can get assigned to the appropriate vlan that it is supposed to be in, this is configured in the radius server. This gives flexibility for the clients to move around the network with out much configuration need to be done by the administrator. + + +## 2.2 Functional Description + +The Ports of an 802.1X Authenticator switch provide the means in which it can offer services to other systems reachable via the LAN. Port-based network access control allows the operation of a System.s Port(s) to be controlled in order to ensure that access to its services is only permitted by Systems that are authorized to do so. + +Port Access Control provides a means of preventing unauthorized access by Supplicants to the services offered by a System. Control over the access to a switch and the LAN to which it is connected can be desirable in order to restrict access to publicly accessible bridge ports or to restrict access to departmental LANs. + +Access control is achieved by enforcing authentication of Supplicants that are attached to an Authenticator.s controlled Ports. The result of the authentication process determines whether the Supplicant is authorized to access services on that controlled Port. + +A PAE is able to adopt one of two distinct roles within an access control interaction: + +1. authenticator: A Port that enforces authentication before allowing access to services available via that Port. + +2. supplicant: A Port that attempts to access services offered by the Authenticator. + +Additionally, there exists a third role: +3. authentication server: Performs the authentication function necessary to check the credentials of the Supplicant on behalf of the Authenticator. + +All three roles are required in order to complete an authentication exchange. SONiC supports the Authenticator role only, in which the PAE is responsible for communicating with the Supplicant. The Authenticator PAE is also responsible for submitting the information received from the Supplicant to the Authentication Server in order for the credentials to be checked, which will determine the authorization state of the Port. The Authenticator PAE controls the authorized/unauthorized state of the controlled Port depending on the outcome of the authentication process. + +Local vs. RADIUS Authentication +There are two methods that can be used for authenticating a user for a particular port on a switch. These methods are described in the following sections. + +Local Authentication +Local authentication consists of matching a user ID/password combination from the Supplicant to a locally-stored user database. The user ID that is returned in response to an EAP-Request/Identity is matched against the database. If a match is found, an EAP-Request/MD5 challenge request is sent to the Supplicant. The Supplicant then takes the challenge, its password and the EAP ID and derives an MD5 response. The MD5 response is then send to the Authenticator which uses the locally stored password to derive the answer and compare it to the Supplicants response. A match results in a successful authentication of the port. + +Note that the SONiC Authenticator supports only the EAP-MD5 authentication type for local authentication. + + +ADIUS Authentication + +When RADIUS authentication is used, the Authenticator basically becomes a passthrough between. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section labelled "RADIUS Authentication Attributes" in this document. + +Per IEEE 802.1X-2001, the SONiC Authenticator supports EAP types that support RFC2284 (i.e. MD5, TLS, PEAP). For certain authentication types, such as EAP-TLS, key information can also be sent from the Authentication Server to the Authenticator as a RADIUS attribute in a RADIUS Access-Accept packet (i.e. the MS-MPPE-Send-Key and MS-MPPE-Recv-Key attributes). The SONiC Authenticator provides the state machines and outcalls to handle keys, but, key distribution has not been fully implemented. The mechanisms provided could be used to extend platforms that support key distribution. Note that re-keying of Supplicants authentication types could be accomplished by enabling reauthentication on the SONiC Authenticator. + + +Unidirectional and bidirectional control +The controlled directions can be configured by management to dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The management setting of the controlled directions parameter can take on one of the following values: +1. Both: Control is exerted over both incoming and outgoing frames. +2. In: Control is only exerted over incoming traffic. Per 802.1X, if the Port is bridge Port, the operational status of controlled directions will be set to Both. However, unidirectional control is not supported in SONiC. Please see "Limitations and Restrictions" section. + +# 3 Design + +## 3.1 Overview + +**Dot1x - multi host mode control flow** +0. User enables authentication + ACL - "deny ip any any" installed + PortMgr - L2 Learning disabled (hardware) + Rules for EAP packets comes to hostapd +1. Client sends an EAP Packet (EAP Start). +2. Hostapd informs pacd that there is a new client (IPC) +3. pacd informs hostapd to authenticate new client +4. hostapd authenticates the client using RADIUS +5. hostapd communicates authorization parameters to pacd + Auth Success/Failure + Authorization parameters (VLAN, DACL, Redirect, Voice, etc.) +6. pacd communicates with aclmgrd via STATE_DB + (a) remove existing ACLs (deny ip any any) + (b) install new ACLs permitting traffic for the new client +7. pacd communicates with PortMgr + PortMgr - L2 Learning enabled (hardware) +8. pacd communicates with vlanmgrd + clean-up existing port vlan config - operationally + update Port membership with client VLAN + update port PVID to client VLAN +9. (10), (11) -- Future component interaction based on Auth parameters received (like Voice VLAN, Redirect, DACL, etc.) +12. pacd informs hostapd success/failure depending on results of 6-11 +13. hostapd sends EAP_SUCCESS/EAP_FAILURE + + + +## 3.2 DB Changes + +### 3.2.1 Config DB + + +### 3.2.2 App DB + +### 3.2.4 ASIC DB + +None + +### 3.2.5 Counter DB + +## 3.3 Switch State Service Design + +### 3.3.1 Orchestration Agent + +#### 3.3.1.1 PAC Orchestration agent + +### 3.3.2 PAC daemons + +#### 3.3.2.1 PAC Manager + +#### 3.3.2.2 Authentication Manager + +### 3.3.3 Other Process + +No change to other process. + +## 3.4 SyncD +No changes to SyncD. + +## 3.5 SAI +No change to SAI. + +## 3.6 Manageability + +### 3.6.1 Data Models + +### 3.6.2 Configuration Commands + +The following commands are used to configure PAC + + +# 4 Flow Diagrams + +# 5 Error Handling + + +# 6 Serviceability and Debug + +# 7 Warm Boot Support +Configured actions and counters should continue to work across warm reboot. + +# 8 Scalability + +## 8.1 Software scalability + +# 9 Limitation + +# 10 Upgrade / Downgrade considerations + +# 11 Unit Test + + +# 12 Appendix: Sample configuration + + +**Using Sonic-CLI** + + +# 13 Internal Design Information + +Internal BRCM information to be removed before sharing with the community + +## 13.1 Future Design Enhancements + From 453c445e94fc7fb85810ab6ed4392f86c6d07a17 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 29 Mar 2021 13:24:18 +0530 Subject: [PATCH 02/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 128 +++++++++++++++++++++++++++++++++++- 1 file changed, 127 insertions(+), 1 deletion(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index edec1e2defc7..9c62d745eb40 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -293,10 +293,136 @@ No change to SAI. ## 3.6 Manageability ### 3.6.1 Data Models +Since Openconfig models are not available, Openconfig dot1x and mab are proprietary yang model following openconfig style. ### 3.6.2 Configuration Commands -The following commands are used to configure PAC +The following commands are used to configure PAC. + + +#### 3.6.2.1 Configuring dot1x adminmode +This command enables or disables authentication support on the switch. The default value is disable. While disabled, the dot1x configuration is retained and can be changed, but it is not activated. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x adminmode | +|Default | disable | +| Change history | SONiC 4.0 - Introduced | + + +#### 3.6.2.2 Configuring dot1x port initialize +This command begins the initialization sequence on the specified port. This command is only valid if the control mode for the specified port is ‘auto’. If the control mode is not ‘auto’, an error will be returned. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port initialize | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.3 Configuring dot1x port reauthenticate +This command begins the reauthentication sequence on the specified port. This command is only valid if the control mode for the specified port is ‘auto’. If the control mode is not ‘auto’, an error will be returned. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port reauthenticate | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.4 Config dot1x port controldir +This command configures the control direction for the specified port or ports. The control direction dictates the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port controldir | +| Default | both | +| Change history | SONiC 4.0 - Introduced | + + +#### 3.6.2.5 Configuring dot1x port controlmode +This command sets the authentication mode to be used on the specified port or ports. The control mode may be one of the following: +forceunauthorized: The authenticator PAE unconditionally sets the controlled port to unauthorized. +forceauthorized: The authenticator PAE unconditionally sets the controlled port to authorized. +auto: The authenticator PAE sets the controlled port mode to reflect the outcome of the authentication exchanges between the supplicant, authenticator, and the authentication server. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port controlmode | +| Default | auto | +| Change history | SONiC 4.0 - Introduced | + + +#### 3.6.2.6 Configuring dot1x port quietperiod +This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. The quiet period must be a value in the range of 0 and 65535. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port quietperiod <0-65535> | +| Default | 60 | +| Change history | SONiC 4.0 - Introduced | + + +#### 3.6.2.7 Configuring dot1x port transmitperiod +This command sets the value, in seconds, of the timer used by the authenticator state machine on the specified port to determine when to send an EAPOL EAP Request/Identity frame to the supplicant. The transmit period must be a value in the range of 1 and 65535. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port transmitperiod <1-65535> | +| Default | 30 | +| Change history | SONiC 4.0 - Introduced | + + +#### 3.6.2.8 Configuring dot1x port supptimeout +This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to timeout the supplicant. The supplicant timeout must be a value in the range of 1 and 65535. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port supptimeout <1-65535>| +| Default | 30 | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.9 Configuring dot1x port servertimeout +This command sets the value, in seconds, of the timer used by the authenticator on this port to timeout the authentication server. The server timeout must be a value in the range of 1 and 65535. + + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port servertimeout <1-65535> | +| Default | 30 | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.10 Configuring dot1x port maxrequests +This command sets the maximum number of times the authenticator state machine on this port will retransmit an EAPOL EAP Request/Identity before timing out the supplicant. The max requests value must be in the range of 1 and 10. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port maxrequests <1-10> | +| Default | 2 | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.11 Configuring dot1x port reauthperiod +This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to determine when reauthentication of the supplicant takes place. The reauthperiod must be a value in the range of 1 and 65535. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port reauthperiod <1-65535> | +| Default | 3600 | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.10 Configuring dot1x port reauthenabled +This command enables or disables reauthentication of the supplicant for the specified port. The reauthenabled value must be ‘true’ or ‘false’. If the value is ‘true’ reauthentication will occur. Otherwise, reauthentication will not be allowed. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port reauthenabled | +| Default | false | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.10 Configuring dot1x port keytxenabled +This command enables or disables key transmission to the supplicant. The keytransmissionenabled value must be ‘true’ or ‘false’. If the value is ‘true’, keys will be transmitted to the supplicant. + +| Mode | Config | +| ---- | ------ | +| Syntax | config dot1x port keytxenabled | +| Default | false | +| Change history | SONiC 4.0 - Introduced | # 4 Flow Diagrams From 8420949d6b892d4b2683bb62a98b49a1b421514a Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 29 Mar 2021 13:50:31 +0530 Subject: [PATCH 03/47] added show commands --- L2/PAC/PortAccessControl.md | 88 ++++++++++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 2 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 9c62d745eb40..4cd48420ee07 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -406,7 +406,7 @@ This command sets the value, in seconds, of the timer used by the authenticator | Default | 3600 | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.10 Configuring dot1x port reauthenabled +#### 3.6.2.12 Configuring dot1x port reauthenabled This command enables or disables reauthentication of the supplicant for the specified port. The reauthenabled value must be ‘true’ or ‘false’. If the value is ‘true’ reauthentication will occur. Otherwise, reauthentication will not be allowed. | Mode | Config | @@ -415,7 +415,7 @@ This command enables or disables reauthentication of the supplicant for the spec | Default | false | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.10 Configuring dot1x port keytxenabled +#### 3.6.2.13 Configuring dot1x port keytxenabled This command enables or disables key transmission to the supplicant. The keytransmissionenabled value must be ‘true’ or ‘false’. If the value is ‘true’, keys will be transmitted to the supplicant. | Mode | Config | @@ -425,6 +425,90 @@ This command enables or disables key transmission to the supplicant. The keytra | Change history | SONiC 4.0 - Introduced | +### 3.6.3 Show Commands + +#### 3.6.3.1 Show dot1x summary +This command displays a summary of the global dot1x configuration. + +| Mode | Exec | +| ------ | ------------------- | +| Syntax | SONiC# show dot1x summary | +| Change history | SONiC 4.0 - Introduced | + +| Field | Description | +| ------ | ------------------- | +| Administrative mode | Indicates if authentication control is enabled on the switch. Possible values are “Enabled” and “Disabled”. | + +#### 3.6.3.2 Show dot1x port summary +This command displays a summary of the dot1x configuration for a specified port or for all ports. + +| Mode | Exec | +| ------ | ------------------- | +| Syntax | show dot1x port summary | +| Change history | SONiC 4.0 - Introduced | + +| Field | Description | +| ------ | ------------------- | +| Port | The interface whose configuration is displayed in this row. | +| Control Mode | The configured control mode for this port. Possible values are “ForceUnauthorized”, “ForceAuthorized”, or “Auto”. | +| Operating Control Mode | The control mode under which this port is operating. Possible values are “Authorized” or “Unauthorized”. | +| Reauthentication Enabled | Indicates if reauthentication is enabled on this port. Possible values are “True” or “False”. | +| Key Transmission Enabled | Indicates if the key is transmitted to the supplicant for the specified port. Possible values are “True” or “False”. | + + + +#### 3.6.3.3 Show dot1x port detailed +This command displays the details of the dot1x configuration for a specified port. + +| Mode | Exec | +| ------ | ------------------- | +| Syntax | show dot1x port detailed | +| Change history | SONiC 4.0 - Introduced | + +| Field | Description | +| ------ | ------------------- | +| Port | The interface whose configuration is displayed | +| Protocol Version | The protocol version associated with this port. The only possible value is 1, corresponding to the first version of the dot1x specification. | +| PAE Capabilities | The PAE functionality of this port. Possible values are “Authenticator” or “Supplicant”. | +| Authenticator PAE State | Current state of the authenticator PAE state machine. Possible values are “Initialize”, “Disconnected”, “Connecting”, “Authenticating”, “Authenticated”, “Aborting”, “Held”, “ForceAuthorized”, and “ForceUnauthorized”. | +| Backend Authentication State | Current state of the backend authentication state machine. Possible values are “Request”, “Response”, “Success”, “Fail”, “Timeout”, “Idle”, and “Initialize”. | +| Quiet Period | The timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. The value is expressed in seconds and will be in the range 0 and 65535. | +| Transmit Period | The timer used by the authenticator state machine on the specified port to determine when to send an EAPOL EAP Request/Identity frame to the supplicant. The value is expressed in seconds and will be in the range of 1 and 65535. | +| Supplicant Timeout | The timer used by the authenticator state machine on this port to timeout the supplicant. . The value is expressed in seconds and will be in the range of 1 and 65535. +| Server Timeout | The timer used by the authenticator on this port to timeout the authentication server. The value is expressed in seconds and will be in the range of 1 and 65535. | +| Maximum Requests | The maximum number of times the authenticator state machine on this port will retransmit an EAPOL EAP Request/Identity before timing out the supplicant. The value will be in the range of 1 and 10. | +| Reauthentication Period | The timer used by the authenticator state machine on this port to determine when reauthentication of the supplicant takes place. The value is expressed in seconds and will be in the range of 1 and 65535. | +| Reauthentication Enabled | Indicates if reauthentication is enabled on this port. Possible values are “True” or “False”. | +| Key Transmission Enabled | Indicates if the key is transmitted to the supplicant for the specified port. Possible values are “True” or “False”. | + + + +#### 3.6.3.4 Show dot1x port stats +This command displays the dot1x statistics for a specified port. + +| Mode | Exec | +| ------ | ------------------- | +| Syntax | show dot1x port stats | +| Change history | SONiC 4.0 - Introduced | + +| Field | Description | +| ------ | ------------------- | +| Port | The interface whose statistics are displayed. | +| EAPOL Frames Transmitted | The number of EAPOL frames of any type that have been transmitted by this authenticator. | +| EAPOL Start Frames Received | The number of EAPOL start frames that have been received by this authenticator. | +| EAPOL Logoff Frames Received | The number of EAPOL logoff frames that have been received by this authenticator. | +| Last EAPOL Frame Version | The protocol version number carried in the most recently received EAPOL frame. | +| Last EAPOL Frame Source | The source MAC address carried in the most recently received EAPOL frame. | +| EAP Response/Id Frames Received | The number of EAP response/identity frames that have been received by this authenticator. | +| EAP Response Frames Received | The number of valid EAP response frames (other than resp/id frames) that have been received by this authenticator. | +| EAP Request/Id Frames Transmitted | The number of EAP request/identity frames that have been transmitted by this authenticator. | +| EAP Request Frames Transmitted | The number of EAP request frames (other than request/identity frames) that have been transmitted by this authenticator.| +| Invalid EAPOL Frames Received | The number of EAPOL frames that have been received by this authenticator in which the frame type is not recognized. | +| EAP Length Error Frames Received | The number of EAPOL frames that have been received by this authenticator in which the frame type is not recognized. | + + + + # 4 Flow Diagrams # 5 Error Handling From f853addbc2b01782ec593ff50e517765413aa4ea Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 29 Mar 2021 15:23:27 +0530 Subject: [PATCH 04/47] updated table of contents --- L2/PAC/PortAccessControl.md | 69 ++++++++++++++++++++++++++----------- 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 4cd48420ee07..ab5652f2ef10 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -45,7 +45,26 @@ High level design document version 0.1 - [3.6 Manageability](#36-manageability) - [3.6.1 Data Models](#361-data-models) - [3.6.2 Configuration Commands](#362-configuration-commands) + - [3.6.2.1 Config dot1x adminmode](#3621-config-dot1x-adminmode) + - [3.6.2.2 Config dot1x port initialize](#3622-config-dot1x-port-initialize) + - [3.6.2.3 Config dot1x port reauthenticate](#3623-config-dot1x-port-reauthenticate) + - [3.6.2.4 Config dot1x port controldir](#3624-config-dot1x-port-controldir) + - [3.6.2.5 Config dot1x port controlmode](#3625-config-dot1x-port-controlmode) + - [3.6.2.6 Config dot1x port quietperiod](#3626-config-dot1x-port-quietperiod) + - [3.6.2.7 Config dot1x port transmitperiod](#3627-config-dot1x-port-transmitperiod) + - [3.6.2.8 Config dot1x port supptimeout](#3628-config-dot1x-port-supptimeout) + - [3.6.2.9 Config dot1x port servertimeout](#3629-config-dot1x-port-servertimeout) + - [3.6.2.10 Config dot1x port maxrequests](#36210-config-dot1x-port-maxrequests) + - [3.6.2.11 Config dot1x port reauthperiod](#36211-config-dot1x-port-reauthperiod) + - [3.6.2.12 Config dot1x port reauthenabled](#36212-config-dot1x-port-reauthenabled) + - [3.6.2.13 Config dot1x port keytxenabled](#36213-config-dot1x-port-keytxenabled) - [3.6.3 Show Commands](#363-show-commands) + - [3.6.3.1 Show dot1x summary](#3631-show-dot1x-summary) + - [3.6.3.2 Show dot1x port summary](#3632-show-dot1x-port-summary) + - [3.6.3.3 Show dot1x port detailed](#3633-show-dot1x-port-detailed) + - [3.6.3.4 Show dot1x port stats](#3634-show-dot1x-port-stats) + - [3.6.4 Clear Commands](#364-clear-commands) + - [3.6.4.1 Clear dot1x port stats](#364-clear-dot1x-port-stats) - **[4 Flow Diagrams](#4-flow-diagrams)** - **[5 Error Handling](#5-error-handling)** - **[6 Serviceability and Debug](#6-serviceability-and-debug)** @@ -300,17 +319,17 @@ Since Openconfig models are not available, Openconfig dot1x and mab are propriet The following commands are used to configure PAC. -#### 3.6.2.1 Configuring dot1x adminmode +#### 3.6.2.1 Config dot1x adminmode This command enables or disables authentication support on the switch. The default value is disable. While disabled, the dot1x configuration is retained and can be changed, but it is not activated. | Mode | Config | | ---- | ------ | -| Syntax | config dot1x adminmode | +| Syntax | config dot1x adminmode | |Default | disable | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.2 Configuring dot1x port initialize +#### 3.6.2.2 Config dot1x port initialize This command begins the initialization sequence on the specified port. This command is only valid if the control mode for the specified port is ‘auto’. If the control mode is not ‘auto’, an error will be returned. | Mode | Config | @@ -318,7 +337,7 @@ This command begins the initialization sequence on the specified port. This com | Syntax | config dot1x port initialize | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.3 Configuring dot1x port reauthenticate +#### 3.6.2.3 Config dot1x port reauthenticate This command begins the reauthentication sequence on the specified port. This command is only valid if the control mode for the specified port is ‘auto’. If the control mode is not ‘auto’, an error will be returned. | Mode | Config | @@ -331,12 +350,12 @@ This command configures the control direction for the specified port or ports. | Mode | Config | | ---- | ------ | -| Syntax | config dot1x port controldir | +| Syntax | config dot1x port controldir | | Default | both | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.5 Configuring dot1x port controlmode +#### 3.6.2.5 Config dot1x port controlmode This command sets the authentication mode to be used on the specified port or ports. The control mode may be one of the following: forceunauthorized: The authenticator PAE unconditionally sets the controlled port to unauthorized. forceauthorized: The authenticator PAE unconditionally sets the controlled port to authorized. @@ -344,12 +363,12 @@ auto: The authenticator PAE sets the controlled port mode to reflect the outcome | Mode | Config | | ---- | ------ | -| Syntax | config dot1x port controlmode | +| Syntax | config dot1x port controlmode | | Default | auto | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.6 Configuring dot1x port quietperiod +#### 3.6.2.6 Config dot1x port quietperiod This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. The quiet period must be a value in the range of 0 and 65535. | Mode | Config | @@ -359,7 +378,7 @@ This command sets the value, in seconds, of the timer used by the authenticator | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.7 Configuring dot1x port transmitperiod +#### 3.6.2.7 Config dot1x port transmitperiod This command sets the value, in seconds, of the timer used by the authenticator state machine on the specified port to determine when to send an EAPOL EAP Request/Identity frame to the supplicant. The transmit period must be a value in the range of 1 and 65535. | Mode | Config | @@ -369,7 +388,7 @@ This command sets the value, in seconds, of the timer used by the authenticator | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.8 Configuring dot1x port supptimeout +#### 3.6.2.8 Config dot1x port supptimeout This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to timeout the supplicant. The supplicant timeout must be a value in the range of 1 and 65535. | Mode | Config | @@ -378,7 +397,7 @@ This command sets the value, in seconds, of the timer used by the authenticator | Default | 30 | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.9 Configuring dot1x port servertimeout +#### 3.6.2.9 Config dot1x port servertimeout This command sets the value, in seconds, of the timer used by the authenticator on this port to timeout the authentication server. The server timeout must be a value in the range of 1 and 65535. @@ -388,7 +407,7 @@ This command sets the value, in seconds, of the timer used by the authenticator | Default | 30 | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.10 Configuring dot1x port maxrequests +#### 3.6.2.10 Config dot1x port maxrequests This command sets the maximum number of times the authenticator state machine on this port will retransmit an EAPOL EAP Request/Identity before timing out the supplicant. The max requests value must be in the range of 1 and 10. | Mode | Config | @@ -397,7 +416,7 @@ This command sets the maximum number of times the authenticator state machine on | Default | 2 | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.11 Configuring dot1x port reauthperiod +#### 3.6.2.11 Config dot1x port reauthperiod This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to determine when reauthentication of the supplicant takes place. The reauthperiod must be a value in the range of 1 and 65535. | Mode | Config | @@ -406,21 +425,21 @@ This command sets the value, in seconds, of the timer used by the authenticator | Default | 3600 | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.12 Configuring dot1x port reauthenabled +#### 3.6.2.12 Config dot1x port reauthenabled This command enables or disables reauthentication of the supplicant for the specified port. The reauthenabled value must be ‘true’ or ‘false’. If the value is ‘true’ reauthentication will occur. Otherwise, reauthentication will not be allowed. | Mode | Config | | ---- | ------ | -| Syntax | config dot1x port reauthenabled | +| Syntax | config dot1x port reauthenabled | | Default | false | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.13 Configuring dot1x port keytxenabled +#### 3.6.2.13 Config dot1x port keytxenabled This command enables or disables key transmission to the supplicant. The keytransmissionenabled value must be ‘true’ or ‘false’. If the value is ‘true’, keys will be transmitted to the supplicant. | Mode | Config | | ---- | ------ | -| Syntax | config dot1x port keytxenabled | +| Syntax | config dot1x port keytxenabled | | Default | false | | Change history | SONiC 4.0 - Introduced | @@ -444,7 +463,7 @@ This command displays a summary of the dot1x configuration for a specified port | Mode | Exec | | ------ | ------------------- | -| Syntax | show dot1x port summary | +| Syntax | show dot1x port summary | | Change history | SONiC 4.0 - Introduced | | Field | Description | @@ -456,7 +475,6 @@ This command displays a summary of the dot1x configuration for a specified port | Key Transmission Enabled | Indicates if the key is transmitted to the supplicant for the specified port. Possible values are “True” or “False”. | - #### 3.6.3.3 Show dot1x port detailed This command displays the details of the dot1x configuration for a specified port. @@ -483,7 +501,7 @@ This command displays the details of the dot1x configuration for a specified por -#### 3.6.3.4 Show dot1x port stats +#### 3.6.3.4 Show dot1x port stats This command displays the dot1x statistics for a specified port. | Mode | Exec | @@ -507,7 +525,18 @@ This command displays the dot1x statistics for a specified port. | EAP Length Error Frames Received | The number of EAPOL frames that have been received by this authenticator in which the frame type is not recognized. | +### 3.6.4 Clear Commands + +#### 3.6.4.1 Clear dot1x port stats +This command resets the dot1x statistics for the specified port or for all ports. + +| Mode | Exec | +| ------ | ------------------- | +| Syntax | clear dot1x port stats | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.4.1 Clear dot1x port stats # 4 Flow Diagrams From aadd69c849648fa26b90dbaeeba3ff396fd6339d Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 29 Mar 2021 15:54:28 +0530 Subject: [PATCH 05/47] updated flow diagrams --- L2/PAC/PortAccessControl.md | 105 +++++++++++++++++++++--------------- 1 file changed, 62 insertions(+), 43 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index ab5652f2ef10..6fbe7600c719 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -45,26 +45,26 @@ High level design document version 0.1 - [3.6 Manageability](#36-manageability) - [3.6.1 Data Models](#361-data-models) - [3.6.2 Configuration Commands](#362-configuration-commands) - - [3.6.2.1 Config dot1x adminmode](#3621-config-dot1x-adminmode) - - [3.6.2.2 Config dot1x port initialize](#3622-config-dot1x-port-initialize) - - [3.6.2.3 Config dot1x port reauthenticate](#3623-config-dot1x-port-reauthenticate) - - [3.6.2.4 Config dot1x port controldir](#3624-config-dot1x-port-controldir) - - [3.6.2.5 Config dot1x port controlmode](#3625-config-dot1x-port-controlmode) - - [3.6.2.6 Config dot1x port quietperiod](#3626-config-dot1x-port-quietperiod) - - [3.6.2.7 Config dot1x port transmitperiod](#3627-config-dot1x-port-transmitperiod) - - [3.6.2.8 Config dot1x port supptimeout](#3628-config-dot1x-port-supptimeout) - - [3.6.2.9 Config dot1x port servertimeout](#3629-config-dot1x-port-servertimeout) - - [3.6.2.10 Config dot1x port maxrequests](#36210-config-dot1x-port-maxrequests) - - [3.6.2.11 Config dot1x port reauthperiod](#36211-config-dot1x-port-reauthperiod) - - [3.6.2.12 Config dot1x port reauthenabled](#36212-config-dot1x-port-reauthenabled) - - [3.6.2.13 Config dot1x port keytxenabled](#36213-config-dot1x-port-keytxenabled) + - [3.6.2.1 Config dot1x adminmode](#3621-config-dot1x-adminmode) + - [3.6.2.2 Config dot1x port initialize](#3622-config-dot1x-port-initialize) + - [3.6.2.3 Config dot1x port reauthenticate](#3623-config-dot1x-port-reauthenticate) + - [3.6.2.4 Config dot1x port controldir](#3624-config-dot1x-port-controldir) + - [3.6.2.5 Config dot1x port controlmode](#3625-config-dot1x-port-controlmode) + - [3.6.2.6 Config dot1x port quietperiod](#3626-config-dot1x-port-quietperiod) + - [3.6.2.7 Config dot1x port transmitperiod](#3627-config-dot1x-port-transmitperiod) + - [3.6.2.8 Config dot1x port supptimeout](#3628-config-dot1x-port-supptimeout) + - [3.6.2.9 Config dot1x port servertimeout](#3629-config-dot1x-port-servertimeout) + - [3.6.2.10 Config dot1x port maxrequests](#36210-config-dot1x-port-maxrequests) + - [3.6.2.11 Config dot1x port reauthperiod](#36211-config-dot1x-port-reauthperiod) + - [3.6.2.12 Config dot1x port reauthenabled](#36212-config-dot1x-port-reauthenabled) + - [3.6.2.13 Config dot1x port keytxenabled](#36213-config-dot1x-port-keytxenabled) - [3.6.3 Show Commands](#363-show-commands) - - [3.6.3.1 Show dot1x summary](#3631-show-dot1x-summary) - - [3.6.3.2 Show dot1x port summary](#3632-show-dot1x-port-summary) - - [3.6.3.3 Show dot1x port detailed](#3633-show-dot1x-port-detailed) - - [3.6.3.4 Show dot1x port stats](#3634-show-dot1x-port-stats) - - [3.6.4 Clear Commands](#364-clear-commands) - - [3.6.4.1 Clear dot1x port stats](#364-clear-dot1x-port-stats) + - [3.6.3.1 Show dot1x summary](#3631-show-dot1x-summary) + - [3.6.3.2 Show dot1x port summary](#3632-show-dot1x-port-summary) + - [3.6.3.3 Show dot1x port detailed](#3633-show-dot1x-port-detailed) + - [3.6.3.4 Show dot1x port stats](#3634-show-dot1x-port-stats) + - [3.6.4 Clear Commands](#364-clear-commands) + - [3.6.4.1 Clear dot1x port stats](#364-clear-dot1x-port-stats) - **[4 Flow Diagrams](#4-flow-diagrams)** - **[5 Error Handling](#5-error-handling)** - **[6 Serviceability and Debug](#6-serviceability-and-debug)** @@ -92,6 +92,7 @@ This document provides general information about the Port Access Control feature # Scope This document provides general information about the Port Access Control feature implementation in SONiC. + # Definition / Abbreviation ## Table 1 Abbreviations @@ -247,30 +248,48 @@ The controlled directions can be configured by management to dictate the degree ## 3.1 Overview -**Dot1x - multi host mode control flow** -0. User enables authentication - ACL - "deny ip any any" installed - PortMgr - L2 Learning disabled (hardware) - Rules for EAP packets comes to hostapd -1. Client sends an EAP Packet (EAP Start). -2. Hostapd informs pacd that there is a new client (IPC) -3. pacd informs hostapd to authenticate new client -4. hostapd authenticates the client using RADIUS -5. hostapd communicates authorization parameters to pacd - Auth Success/Failure - Authorization parameters (VLAN, DACL, Redirect, Voice, etc.) -6. pacd communicates with aclmgrd via STATE_DB - (a) remove existing ACLs (deny ip any any) - (b) install new ACLs permitting traffic for the new client -7. pacd communicates with PortMgr - PortMgr - L2 Learning enabled (hardware) -8. pacd communicates with vlanmgrd - clean-up existing port vlan config - operationally - update Port membership with client VLAN - update port PVID to client VLAN -9. (10), (11) -- Future component interaction based on Auth parameters received (like Voice VLAN, Redirect, DACL, etc.) -12. pacd informs hostapd success/failure depending on results of 6-11 -13. hostapd sends EAP_SUCCESS/EAP_FAILURE +### 3.1.1 Configuration flow + +![pac-config-flow](https://user-images.githubusercontent.com/45380242/112821782-bd4e6580-90a4-11eb-93bb-b453b97da456.PNG) + +1. Mgmt interfaces like CLI and REST writes the user provided configuration to CONFIG_DB. +2. The pacd, mabd and hostApdMgr gets notified about their respective configuration. +3. hostApd being a standard Linux application gets its configuration from hostapd.conf file. hostApdMgr makes use of Jinja2 templates to generates the hostapd.conf file based on the relevant CONFIG_DB tables. +4. Pacd gets to know about the list of ports that needs to be authenticated via DOT1X and MAB and their priority from PAC_PORT_CONF_TABLE on CONFIG_DB. Based on the priority and authentication failure status, pacd decides on the list of ports to be authenticated via DOT1X and MAB and It communicates the list of interfaces to hostApd and mabd respectively via netlink messages. +5. hostApd listen to EAPOL PDUs on the provided interface list and proceeds to authenticate the client when it receives a PDU. mabd listens to DHCP and EAPOL PDUs on the provided interface list and proceeds to authenticate the client when it receives a PDU. + + + +### 3.1.2 EAPOL receive flow + + +![EAPOL-receive-flow](https://user-images.githubusercontent.com/45380242/112822933-369a8800-90a6-11eb-9dfa-c8eaecbb681e.PNG) + +1. EAPOL packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to hostApd socket listening on EtherType 0x888E on kernel interface associated with the given front panel interface. +2. In a multi-step process, hostApd runs the Dot1x state machine to Authenticate the client via RADIUS. +3. On successful authentication of a client, hostApd sends an Client Authenticated netlink message to pacd with all the authorization parameters like VLAN and DACL. +4. pacd proceeds to authorize the client by writing PAC_AUTHORIZE_TABLE on APPL_DB. RADIUS authorization parameters like dynamic VLAN, dynamic ACL are created by writing on their tables on STATE_DB. +5. Orchagent in SWSS docker gets notified about changes in APPL_DB and responds by translating the APPL_DB changes to respective sairedis calls. +6. Sairedis APIs write into ASIC_DB. +7. Syncd gets notified on changes to ASIC_DB and in turn calls respective SAI calls. +8. The SAI calls translate to respective SDK calls to program hardware. +9. EAP success message (EAPOL PDU) is sent to client. + + +### 3.1.3 MAB PDU receive flow + +![mab-pdu-receive-flow](https://user-images.githubusercontent.com/45380242/112823181-94c76b00-90a6-11eb-8a5e-19ccb525dcef.PNG) + +1. DHCP packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to pacd socket listening on the kernel interface associated with the given front panel interface. +2. Pacd sends an Client Authenticate netlink message along with the received PDU MAC. +3. mabd interacts with RADIUS server to authenticate the given client based on the MAC. +4. On successful authentication of a client, mabd sends an Client Authenticated netlink message to pacd with all the atheization parameters like VLAN and DACL. +5. pacd proceeds to authorize the client by writing PAC_AUTHORIZE_TABLE on APPL_DB. RADIUS authorization parameters like dynamic VLAN, dynamic ACL are created by writing on their tables on STATE_DB. +6. Orchagent in SWSS docker gets notified about changes in APPL_DB and responds by translating the APPL_DB changes to respective sairedis calls. +7. Sairedis APIs write into ASIC_DB. +8. Syncd gets notified on changes to ASIC_DB and in turn calls respective SAI calls. +9. The SAI calls translate to respective SDK calls to program hardware. +10. EAP success message (EAPOL PDU) is sent to client. From db216da666af8e59ba9a15e1e276c954c3d5fed6 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 29 Mar 2021 17:40:39 +0530 Subject: [PATCH 06/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 49 ++++++++++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 6fbe7600c719..459385826c0f 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -223,7 +223,7 @@ Additionally, there exists a third role: All three roles are required in order to complete an authentication exchange. SONiC supports the Authenticator role only, in which the PAE is responsible for communicating with the Supplicant. The Authenticator PAE is also responsible for submitting the information received from the Supplicant to the Authentication Server in order for the credentials to be checked, which will determine the authorization state of the Port. The Authenticator PAE controls the authorized/unauthorized state of the controlled Port depending on the outcome of the authentication process. -Local vs. RADIUS Authentication +### 2.2.1 Local vs. RADIUS Authentication There are two methods that can be used for authenticating a user for a particular port on a switch. These methods are described in the following sections. Local Authentication @@ -232,26 +232,65 @@ Local authentication consists of matching a user ID/password combination from th Note that the SONiC Authenticator supports only the EAP-MD5 authentication type for local authentication. -ADIUS Authentication +### 2.2.2 RADIUS Authentication When RADIUS authentication is used, the Authenticator basically becomes a passthrough between. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section labelled "RADIUS Authentication Attributes" in this document. Per IEEE 802.1X-2001, the SONiC Authenticator supports EAP types that support RFC2284 (i.e. MD5, TLS, PEAP). For certain authentication types, such as EAP-TLS, key information can also be sent from the Authentication Server to the Authenticator as a RADIUS attribute in a RADIUS Access-Accept packet (i.e. the MS-MPPE-Send-Key and MS-MPPE-Recv-Key attributes). The SONiC Authenticator provides the state machines and outcalls to handle keys, but, key distribution has not been fully implemented. The mechanisms provided could be used to extend platforms that support key distribution. Note that re-keying of Supplicants authentication types could be accomplished by enabling reauthentication on the SONiC Authenticator. -Unidirectional and bidirectional control +### 2.2.3 Unidirectional and bidirectional control The controlled directions can be configured by management to dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The management setting of the controlled directions parameter can take on one of the following values: 1. Both: Control is exerted over both incoming and outgoing frames. 2. In: Control is only exerted over incoming traffic. Per 802.1X, if the Port is bridge Port, the operational status of controlled directions will be set to Both. However, unidirectional control is not supported in SONiC. Please see "Limitations and Restrictions" section. + +### 2.2.4 Downloadable ACL +PAC (Port access control) feature brings in DACL (downloadable ACL) support into SONiC. As a part of PAC, once a client on an access controlled port is authenticated, the external RADIUS server can send ACL attributes based on user profile configuration on the RADIUS server. These are called Downloadable ACL’s. IPv6 and IPv4 ACLs are supported for DACL. The downloadable ACL rules per client are sent in extended ACL syntax style. The switch applies the client specific DACL for the duration of the authenticated session. + +The switch does not display RADIUS specified DACL’s in the running configuration. The ACL however shows up in the user interface show commands. Essentially, the DACL configuration is temporary (applied for the duration of the authenticated client session) and not persistent. The downloadable ACLs sent by RADIUS are in extended ACL syntax style and are validated just like user created ACLs. The ACLs created by the applications are owned by the internal application and hence cannot be deleted by a user. + +Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. Amoung DACLs IPv6 ACL have higher prority over IPv4. In sitialtions where the client IP address changes, the application created ACLs are automatically updated to accomodate the operational change like a changed client IP address. + + +### 2.2.5 Named ACLs +RADIUS server can also provide an attribute (filter name/filter id) to have PAC apply a pre-configured ACL on the switch to the client. These pre-configured ACLs are named ACLs. These ACLs are created by the user on the switch. Once RADIUS indicates a named ACL is to be applied for a client, PAC replicates the ACL rules, modifies the rules to incorporate the client IP and then provide them as dynamic ACL rules. + +### 2.2.6 RADIUS suplied VLANs +PAC (port access control) brings in support for access control with the ability to control user profiles from a RADIUS server. Once a client is authenticated, the client authorization parameters from RADIUS can indicate VLAN association for client traffic. The VLAN associated to the client could be a pre-created VLAN on the switch (static VLAN) in which case port membership of the VLAN are modified. In the absence of the VLAN on the switch, the VLAN are created on the switch (dynamic VLANs). + +Default VLAN on port +A port should not be part of user configured VLAN When PAC is enabled on the port. The port gets configured for a default VLAN (VLAN 1 - configurable) when PAC is enabled on the port. Once PAC is disabled on the port, the port is removed from the default VLAN. + +### 2.2.7 FDB interation +PAC interacts with FDB to modify the learning mode of a port and add static FDB entries. The FDB related interactions for PAC are outlined below: +- PAC adds a static FDB entry for every authenticated client. +- SONiC today allows addition of static FDB entries from CLI which are persistent across reloads. The same is enhanced so that PAC SONiC applications can add static FDB entries. +- Note that FDB entries thus added are not persistent and are operational config only (entries added as a result of the client getting authenticated). +- The entries get removed once the client logs off. +- FDB entries added operationally follows a similar config sequence like user created FDB entries. +- The learning mode of a port (or bridge port) was configured and controlled completely at the orchestration layer. With PAC, the application layer (pacd) also manages the learning mode to + 1. Once PAC is enabled on a port, all incoming and outgoing traffic on the port are blocked/dropped except certain protocol traffic. + 2. PAC turns off learning on the port essentially dropping all unknown source MAC packets. This achieves the requirement of blocking ingress traffic. + 3. Egress traffic on the port is not blocked. + 4. Once a client starts the authentication process, the client is no longer unknown (unknown source MAC). However, since authentication is yet to be completed, +traffic for the client must still get dropped. To acheive the same, PAC installs a static FDB entry in drop state to drop the client’s traffic but get classified as L2SrcHit. +- For MAC based authentication mode of PAC, unknown source MAC packets are trapped to the CPU. +- Station movement is also handled i.e if a packet is received from another port on a MAC, VLAN pair for which PAC installed a static FDB entry, such packets also get trapped to the CPU. + + # 3 Design ## 3.1 Overview +[Figure 1](#pac-config-flow) shows the high level design overview of PAC services in SONiC. PAC Services Daemon is composed of multiple sub-modules. The main module i.e. PAC daemon handles the authentication related commands and makes use of hostApd and mabd dameons to authenticate a client via dot1x and mab respectively. hostApd being a standard linux application takes hostapd.con as a config file. hostApdMgr takes care of listenting to dot1x specific configuration and translating them to respective hostapd.conf file config entires. pacd daemon being the main module decides which autnetication protocol needs to be used for a given port and also calls APIs to program the polices in hardware. + ### 3.1.1 Configuration flow ![pac-config-flow](https://user-images.githubusercontent.com/45380242/112821782-bd4e6580-90a4-11eb-93bb-b453b97da456.PNG) +**Figure 1: PAC service daemon and configuration flow** + 1. Mgmt interfaces like CLI and REST writes the user provided configuration to CONFIG_DB. 2. The pacd, mabd and hostApdMgr gets notified about their respective configuration. 3. hostApd being a standard Linux application gets its configuration from hostapd.conf file. hostApdMgr makes use of Jinja2 templates to generates the hostapd.conf file based on the relevant CONFIG_DB tables. @@ -265,6 +304,8 @@ The controlled directions can be configured by management to dictate the degree ![EAPOL-receive-flow](https://user-images.githubusercontent.com/45380242/112822933-369a8800-90a6-11eb-9dfa-c8eaecbb681e.PNG) +**Figure 2: EAPOL receive flow** + 1. EAPOL packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to hostApd socket listening on EtherType 0x888E on kernel interface associated with the given front panel interface. 2. In a multi-step process, hostApd runs the Dot1x state machine to Authenticate the client via RADIUS. 3. On successful authentication of a client, hostApd sends an Client Authenticated netlink message to pacd with all the authorization parameters like VLAN and DACL. @@ -280,6 +321,8 @@ The controlled directions can be configured by management to dictate the degree ![mab-pdu-receive-flow](https://user-images.githubusercontent.com/45380242/112823181-94c76b00-90a6-11eb-8a5e-19ccb525dcef.PNG) +**Figure 3: MAB PDU receive flow** + 1. DHCP packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to pacd socket listening on the kernel interface associated with the given front panel interface. 2. Pacd sends an Client Authenticate netlink message along with the received PDU MAC. 3. mabd interacts with RADIUS server to authenticate the given client based on the MAC. From 35f7d6f579846b358bf3ffb1903fc55614711fe3 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Tue, 30 Mar 2021 12:01:15 +0530 Subject: [PATCH 07/47] updated authmgr section --- L2/PAC/PortAccessControl.md | 75 +++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 459385826c0f..f310f1c0f1a0 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -360,6 +360,81 @@ None #### 3.3.2.1 PAC Manager #### 3.3.2.2 Authentication Manager +Authentication Manager primarily manages the order of authentication methods during a failover scenario. Majority of authentication functionalities are managed by 802.1X. These include interaction with a AAA server, applying client authorization parameters to allow authenticated client traffic, etc. These are strictly speaking not specific to 802.1X and are applicable to any authenticated methods like MAB. + +Authentication Manager allows enforcing authentication on a port. Authentication Manager needs to be enabled for the same. This is the first step to enabling port based access control. Once authentication is enabled, the port is marked Unauthorized and traffic is blocked through it. + +Authentication Manager enables configuring various Authentication Host modes. This is configured per port. These modes determine the number of clients and the type of clients that can be authenticated and authorized on the ports. Distinction is made between Data and Voice clients. + +Authentication Manager also enables configuring the authentication methods to be used for authenticating clients on a port. By default the configured authentication methods are tried in order for that port. SONiC allows the below authentication methods to get configured for each port. +- 802.1X +- MAB + +In the event that a port is configured for 802.1X and MAB in this sequence, the port will first attempt to authenticate the user through 802.1X. If 802.1X authentication times out, the switch will attempt MAB. The automatic sequencing of authentication methods allows the network administrator to apply the same configuration to every access port without having to know in advance what kind of device (employee or guest, printer or PC, IEEE 802.1X capable or not, etc.) will be attached to it. + +Authentication Manager allows configuring priority for each authentication method on the port. The default priority of a method is equivalent to its position in the order of the default authentication list. + +After successful authentication, the authentication method returns the Authorization parameters for the client. Authentication Manager uses these parameters for configuring the switch for allowing traffic for authenticated clients. + +**Authentication Manager port modes** + +*Auto* +This mode is used to enforce authentication on a port. The port is unauthorized and blocked for traffic unless a client is authenticated. + +*Force-Authorized* +This mode is used to disable authentication on a port. All client traffic is allowed. + +*Force-Unauthorized* +This mode is used to un-authorize a port and block any client traffic + + +**Authentication Manager port host modes** + +*Single-Host mode* +In this mode only one data client can be authenticated on a port and the client is granted access to the port. Access is allowed only for this client and no one else. Only when this client logs off, can another client get authenticated and authorized on the port and granted port access. + +*Multiple Hosts mode* +In this mode only one data client can be authenticated on a port. However once authentication succeeds, access is granted to all clients connected to the port. Typical use case is a wireless access point which is connected to an access controlled port of a NAS. Once the access point is authenticated by the NAS, the port is authorized for traffic from not just the access point but also from all the wireless clients connected to the access point. Once this client gets authenticated, the port is open for all clients connected to the port. + +*Multiple Domain Authentication mode* +In this mode one data client and one voice client can be authenticated on a port and these clients are then granted access. Typical use case is an IP phone connected to a NAS port and a laptop connected to the hub port of the IP phone. Both the devices need to be authenticated to access the network services behind the NAS. The voice and data domains are segregated. The RADIUS server attribute “Cisco-AVPair = "device-traffic-class=voice"” is used to identify a voice client. + +*Multiple Authentication mode* +In this mode one voice client and multiple data clients can be authenticated on a port and these clients are then granted access. Typical use case is a network of laptops and an IP phone connected to the NAS port via a hub. + +*Multiple Domain Multi Host mode* +In this mode one voice client and one data client can be authenticated on a port and these clients are then granted access. However once a data client is authenticated, access is granted to all clients connected to the port and they are considered data clients. Typical use case is an IP phone connected to a NAS port and a Virtual Machine Controller connected to the hub port of the IP phone. The Virtual Machine Controller hosts multiple Virtual Machines. Both the VM Controller and the IP phone need to be authenticated to access the network services behind the NAS. The voice and data domains are segregated. Once the VM Controller is authenticated, it allows traffic from all the VMs hosted by the VM Controller. Once this client gets authenticated, the port is open for all clients connected to the port. Authentication and port access is also allowed for a Voice device. + +Note: If the data client gets authenticated first, the Voice client can only be authenticated using 802.1x. + +**Authentication Manager Authentication method fallback and priorities** + +Authentication manager controls the order in which the authentication methods are executed. Authentication manager does not make any required configuration for the respective methods to authenticate successfully. User or Administrator needs to ensure that the correct and appropriate configuration is present in the system. +Using the Authentication manager, user can configure an authentication method fallback list, which is configured per port. If authentication using any of the method fails, then authentication of the client on the port is tried using the next or subsequent methods. + +The default priority of a method is equivalent to its position in the order of the default authentication list, which is configured per port. If authentication method priorities are not configured, then the relative priorities (highest first) are in the same order as that of per port based authentication list. By configuring the authentication priority, user can over-ride the default priority. + +If the client is already authenticated using methods such as MAB and 802.1X happens to have higher priority than the authenticated method, if a 802.1X frame is received, then the existing authenticated client will be removed and authentication process would begin for the client using 802.1X.However if 802.1X is configured at a lower priority than the authenticated method, then the client will not be removed and the 802.1X frames will be ignored. + +Authentication manager allows user to modify the default method priorities using configuration. This is supported by configuring the priority order list for the authentication methods using the command authentication priority. + +If administrator changes the priority of the methods, then all the users who are authenticated using a lower priority method will be forced to re-authenticate. If an authentication session is in progress and administrator changes the order of the authentication methods then the configuration will take effect for the next session onwards. + +**Authorization parameters** + +Upon successful authentication, the authentication methods inform Authentication Manager about the result. Authentication Manager then authorizes the port and configures it for allowing traffic from and to the client. + +Authentication Manager receives the client authorization parameters from the authentication method after successful authentication of a client. The following parameters are acted upon: + +- *VLAN Id*: This is the VLAN ID sent by a RADIUS server. Authentication Manager configures the port membership accordingly so that the client traffic is associated with the VLAN. Refer [3] for further details. +- *Session Timeout*: This is the timeout attribute of the authenticated client session. +- *Session Termination Action*: Upon session timeout, the Session Termination Action determines the action on the client session. The following actions are defined: +- *Default*: The client session is torn down and authentication needs to be restarted for the client. +- *RADIUS*: Re-authentication is initiated for the client. +- *Filter-Id*: Specifies an ACL of Diffserv policy name. This is used to apply a Static ACL or DiffServ policy on the port for the client. IPv4 and IPv6 ACLs in the “IN” direction is supported. If the Differv policy or ACL is not present in the system, or if a Diffserv policy is already configured on the port, authentication for the client is rejected. These are subject to Monitor Mode configuration. Filter-Id is supported on all Authentication Manager host modes. +- *Downloadable ACL*: DACLs are supported on all host modes. +- *Redirect ACL*: This is used to apply an ACL that traps matching packets to the CPU for redirection. It is typically used to match on HTTP packets from a client. +- *Redirect URL*: This is used to specify a redirect URL and works in conjunction with the Redirect ACL. ### 3.3.3 Other Process From 418d46fe2099dd720d4553baed8398f0e3df5aa0 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Tue, 30 Mar 2021 12:21:19 +0530 Subject: [PATCH 08/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index f310f1c0f1a0..95fc72e9e1ce 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -672,9 +672,6 @@ This command resets the dot1x statistics for the specified port or for all ports | Syntax | clear dot1x port stats | | Change history | SONiC 4.0 - Introduced | - -#### 3.6.4.1 Clear dot1x port stats - # 4 Flow Diagrams # 5 Error Handling @@ -691,6 +688,19 @@ Configured actions and counters should continue to work across warm reboot. # 9 Limitation +- Authentication Manager does not make any required configuration for the respective methods to authenticate successfully. The administrator needs to ensure that the correct and appropriate configuration is present in the system. For example, if the authentication order method includes the 802.1x port authentication method, 802.1X should be enabled for the authentication to succeed. Authentication manager will not enable/disable and make the configurations related to 802.1X. Administrator should make the necessary configurations. + +- If the authentication order includes web authentication, then fallback profile that enables web authentication on the switch and the interface should be configured. Similarly all the required ACLs should be configured by the administrator or user. + +- In the default configuration, all traffic that is not EAP over LAN (EAPoL) traffic (including DHCP) is dropped until 802.1X and MAB times out. Therefore, the value of the timeout can significantly affect the DHCP client on the end host. Longer 802.1X timeouts may prevent DHCP from functioning correctly after the 802.1X timeout expires. + +- To prevent DHCP clients from timing out, SONiC recommends testing the DHCP clients in respective network to discover how long they take to time out and setting the 802.1X timers accordingly. + +- After configuration Save and reload, if the session Id in the PDU, that is sent by the client doesn’t match with the session Id expected by the 802.1X, then the received PDU is ignored and SONiC will re-try for 802.1X authentication. If the PDU is processed and the authentication fails or times out, then only the authentication moves to the next method. + +- Authentication Manager cannot be enabled on LAG interfaces. Enabling Authentication Manager on ports which are member of LAGs or including an Unauthorized port into a LAG will result in unpredictable results. + + # 10 Upgrade / Downgrade considerations # 11 Unit Test From c5ee48a93107cb209cbc382ccf7ba8374b82ff0b Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Tue, 30 Mar 2021 13:21:12 +0530 Subject: [PATCH 09/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 95fc72e9e1ce..f9699651592b 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -39,6 +39,7 @@ High level design document version 0.1 - [3.3.2 PAC daemons](#332-pac-daemons) - [3.3.2.1 PAC Manager](#3321-pac-manager) - [3.3.2.2 Authentication Manager](#3322-authentication-manager) + - [3.3.2.3 mabd](#3323-mabd) - [3.3.3 Other Process](#333-other-process) - [3.4 SyncD](#34-syncd) - [3.5 SAI](#35-sai) @@ -436,6 +437,30 @@ Authentication Manager receives the client authorization parameters from the aut - *Redirect ACL*: This is used to apply an ACL that traps matching packets to the CPU for redirection. It is typically used to match on HTTP packets from a client. - *Redirect URL*: This is used to specify a redirect URL and works in conjunction with the Redirect ACL. +#### 3.3.2.3 mabd +MAB is intended to provide 802.1x unaware clients controlled access to the network using the devices’ MAC address as an identifier. This requires that the known and allowable MAC address and corresponding access rights be pre-populated in the authentication server. + +Today, 802.1x has become the recommended port-based authentication method at the access layer in enterprise networks. However, there may be 802.1x unaware devices such as printers, fax-machines etc that would require access to the network without 802.1x authentication. MAB is a supplemental authentication mechanism to allow 802.1x unaware clients to authenticate to the network. SONiC supported authentication methods are as below: +- CHAP +- EAP-MD5 +- PAP + +SONiC provides a mechanism to format the attribute1 as part of MAB configuration. This mechanism decouples the formats of attribute1 and attribute31 sent in the RADIUS packets and enables separate controls for both. + +Mac-based Authentication Bypass (MAB) is configured per port. For MAB to be used for authentication it needs to be is configured as an authentication method in method list for the port by Authentication Manager, MAB authentication is done in the order in which the methods are configured. If first in the list, MAB occurs first. If second in the list after 802.1x, MAB will occur if 802.1X times out or fails. 802.1X timeout is determined by the following time period: + +Timeout = (maxReAuthReqIdentity + 1) * txPeriod + +Authentication Manager initiates MAB authentication by conveying the MAC address of the client attempting to authenticate as the username. MAB then sends a request to the authentication server with the MAC address of the client in the user configured attribute 1 format (by default ‘hhXX:XXhh:hhXX:hhXX:hhXX:hhXX’) as the User-Name (Radius Attribute 1). This attribute is sent irrespective of the authentication type configured on that interface for MAB. + +The type of RADIUS attributes included in the Access-Request varies with the type of authentication type selected for MAB on a physical interface. An Access-Request MUST contain either an EAP-Message (Radius Attribute 79) or a User-Password (Radius Attribute 2) or a CHAP-Password (Radius Attribute 3). An Access-Request MUST NOT contain all 3 or any 2 of the above listed attributes. +If authentication type is configured as EAP-MD5 (also the default), the MD5 hash of the Mac address as the password in the EAP-Message (Radius Attribute 79) is sent to the authentication server. +If authentication type is configured as PAP, MAC address of the client is sent as the password similar to the format of Attribute 1 as clear text as part of the User-Password (Radius Attribute 2). +If authentication type is configured as CHAP, a randomly generated 16-octet challenge is sent as the CHAP-Challenge (Radius Attribute 60) along with the CHAP-Password (Radius Attribute 3). CHAP-ID is a unique number which is used to identify the session. MAC address of the client is taken and formatted using the configured Attribute 1 format and is used as ‘secret’ in deriving the CHAP-Password. CHAP-Password is calculated as MD5 (CHAP-ID | secret | CHAP-Challenge). + +The authentication server checks its pre-populated database for the authorized Mac addresses and returns an ‘Access-Accept’ or an ‘Access-Reject’ depending on if the Mac address has been found in the database. This also makes it possible for the client to be placed in a RADIUS assigned VLAN or apply a specific Filter ID to the client traffic. + + ### 3.3.3 Other Process No change to other process. From b924cd80c8bea65fc43d41c6f5cb3c27827a3028 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Tue, 30 Mar 2021 14:57:07 +0530 Subject: [PATCH 10/47] corrected spelling mistakes --- L2/PAC/PortAccessControl.md | 73 +++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 39 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index f9699651592b..b5e4eafc7e2e 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -110,7 +110,7 @@ This document provides general information about the Port Access Control feature # 1 Feature Overview ## 1.1 Port Access Control -Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specified switch port. +Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. Local Area Networks (LANs) are often deployed in environments that permit unauthorized devices to be physically attached to the LAN infrastructure, or permit unauthorized users to attempt to access the LAN through equipment already attached. In such environments, it may be desirable to restrict access to the services offered by the LAN to those users and devices that are permitted to use those services. Port access control makes use of the physical characteristics of LAN infrastructures in order to provide a means of authenticating and authorizing devices attached to a LAN port that has point-to-point connection characteristics and of preventing access to that port in cases in which the authentication and authorization process fails. In this context, a port is a single point of attachment to the LAN, such as Ports of MAC bridges and associations between stations or access points in IEEE 802.11 Wireless LANs. @@ -119,35 +119,30 @@ Local Area Networks (LANs) are often deployed in environments that permit unauth IEEE 802.1X is an IEEE Standard for Port Access Control (PAC) that provides an authentication mechanism to devices wishing to attach to a LAN. The standard defines Extensible Authentication Protocol Over LAN (EAPOL). The 802.1X standard describes an architectural framework within with authentication and consequent actions take place. It also establishes the requirements for a protocol between the authenticator and the supplicant, as well as between the authenticator and the authentication server. ### 1.1.2 MAC Authentication Bypass -Simple devices like camera or printers which do not support 802.1x autentication can make use of MAB feature where the device gets authenticated based on the device MAC address. +Simple devices like camera or printers which do not support 802.1x authentication can make use of MAB feature where the device gets authenticated based on the device MAC address. ## 1.3 Requirements ### 1.3.1 Functional Requirements The following are the requirements for Port Access Control feature: -1. 802.1X is supported on physical interfaces only. -2. The interfaces cannot be part of a port-channel. -3. 802.1X is not supported on service port. -4. One can configure 802.1X interfaces for bridges using the following features: - Parking VLAN. - Dynamic VLAN. - MAB (MAC-based authentication bypass). -5. MAB, parking VLAN, and dynamic VLAN all require a bridge access port. -6. In traditional bridge mode, parking VLANs and dynamic VLANs both require the destination bridge to have a parking VLAN ID or dynamic VLAN ID tagged subinterface. -7. When you enable or disable 802.1X on ports, hostapd reloads; however, existing authorized sessions do not reset. -8. Changing the 802.1X interface, MAB, or parking VLAN settings do not reset existing authorized user ports. However, removing all 802.1X interfaces or changing any of the following RADIUS parameters restarts hostapd, which forces existing, authorized users to re-authenticate: +1. PAC is supported on physical interfaces only. +2. The interfaces cannot be part of a port-channel / LAG. +3. PAC is not supported on service port. +4. User can configure PAC interfaces for switches using the following features: + - 802.1x + - MAB (MAC-based authentication bypass). +5. MAB, and dot1x need support for access port. +6. User enable or disable of 802.1X on ports can cause PAC daemons (hostapd) to reload; however, existing authorized sessions do not reset. +7. Changing the 802.1X interface, MAB do not reset existing authorized user ports. However, removing all 802.1X interfaces or changing any of the following RADIUS parameters restarts hostapd, which forces existing, authorized users to re-authenticate: - RADIUS server IP address, shared secret, authentication port or accounting port. - - Parking VLAN ID. - MAB activation delay. - EAP re authentication period. -9. You can configure up to three RADIUS servers (in case of failover). However, do not use a SONiC switch as the RADIUS server. -10. You can configure 802.1X interfaces with dynamic ACLs in VLAN-aware bridge mode only. -Note: 802.1X on SONiC to be tested with only a few wpa_supplicant (Debian), Windows 10 and Windows 7 supplicants. -11. RADIUS authentication is supported with FreeRADIUS and Cisco ISE. -12. 802.1X supports simple login and password, PEAP/MSCHAPv2 (Win7) and EAP-TLS (Debian). -13. 802.1X supports RFC 5281 for EAP-TTLS, which provides more secure transport layer security. -14. Mako template-based configurations are not supported. -15. SONiC supports Multi Domain Authentication (MDA), where 802.1X is extended to allow authorization of multiple devices (a data and a voice device) on a single port and assign different VLANs to the devices based on authorization. +8. User can configure up to three RADIUS servers (in case of failover). However, do not use a SONiC switch as the RADIUS server. +9. User can configure 802.1X interfaces with dynamic ACLs in VLAN-aware bridge mode only. +10. RADIUS authentication is supported with FreeRADIUS and Cisco ISE. +11. 802.1X supports simple login and password, PEAP/MSCHAPv2 (Win7) and EAP-TLS (Debian). +12. 802.1X supports RFC 5281 for EAP-TTLS, which provides more secure transport layer security. +13. SONiC supports Multi Domain Authentication (MDA), where 802.1X is extended to allow authorization of multiple devices (a data and a voice device) on a single port and assign different VLANs to the devices based on authorization. - MDA is enabled by default; however, you need to assign a tagged VLAN for voice devices (see Configure 802.1X Interfaces for a VLAN-aware Bridge). - A maximum of four authorized devices (MAB + EAPOL) per port are supported. - The 802.1X-enabled port must be a trunk port to allow tagged voice traffic from a phone; you cannot enable 802.1X on an access port. @@ -169,7 +164,7 @@ The following are the requirements for MAB feature: 10. If Mac-based dot1x authentication is enabled on a port and if Mac-based VLANs or Subnet VLANs or Protocol VLANs are also enabled, then Mac-based dot1x authentication is disabled. 11. If Port-Mac Locking is enabled on the port and if Mac-based dot1x authentication is also enabled on the port. Then Port-Mac Locking needs to be disabled. 12. If a client already authentication on one port has roamed to another port on the switch, then the state (status, vlan etc) of the client on the prior port needs to be cleaned. -13. Timeout mechanism needs to be maintained per client so that inactive client.s status can be removed on the switch. +13. Timeout mechanism needs to be maintained per client so that inactive client's status can be removed on the switch. 14. Multicast/Broadcast traffic arriving on the port that is enabled for Mac-based authentication would be forwarded accordingly. If the source Mac-address of the packet is from a authenticated user. 15. Even when the port is authorized, dot1x would still continue to send EAPOL for authentication as more users could join on the port. 16. Unauthenticated Vlan is per port configuration. By default unauthenticated vlan is zero (invalid and not operational). @@ -189,10 +184,10 @@ Port Access Control feature should work seamlessly across warmboot. Statistics m ### 1.4.1 Basic Approach ### 1.4.2 Container -A new container sonic-security is introduced to hold all the port security applications. Apart from sonic-security container, code changes are made to SWSS container. +A new container sonic-security is introduced to hold all the port security applications. Apart from sonic-security container, code changes are made to SWSS, mgmt-frameowrk containers. ### 1.4.3 SAI Overview - +No changes to SAI spec for supporting PAC. # 2 Functionality @@ -207,11 +202,11 @@ If the vlan assignment is enabled in the Radius server then as part of the respo ## 2.2 Functional Description -The Ports of an 802.1X Authenticator switch provide the means in which it can offer services to other systems reachable via the LAN. Port-based network access control allows the operation of a System.s Port(s) to be controlled in order to ensure that access to its services is only permitted by Systems that are authorized to do so. +The Ports of an 802.1X Authenticator switch provide the means in which it can offer services to other systems reachable via the LAN. Port-based network access control allows the operation of a System's Port(s) to be controlled in order to ensure that access to its services is only permitted by Systems that are authorized to do so. Port Access Control provides a means of preventing unauthorized access by Supplicants to the services offered by a System. Control over the access to a switch and the LAN to which it is connected can be desirable in order to restrict access to publicly accessible bridge ports or to restrict access to departmental LANs. -Access control is achieved by enforcing authentication of Supplicants that are attached to an Authenticator.s controlled Ports. The result of the authentication process determines whether the Supplicant is authorized to access services on that controlled Port. +Access control is achieved by enforcing authentication of Supplicants that are attached to an Authenticator's controlled Ports. The result of the authentication process determines whether the Supplicant is authorized to access services on that controlled Port. A PAE is able to adopt one of two distinct roles within an access control interaction: @@ -222,48 +217,48 @@ A PAE is able to adopt one of two distinct roles within an access control intera Additionally, there exists a third role: 3. authentication server: Performs the authentication function necessary to check the credentials of the Supplicant on behalf of the Authenticator. -All three roles are required in order to complete an authentication exchange. SONiC supports the Authenticator role only, in which the PAE is responsible for communicating with the Supplicant. The Authenticator PAE is also responsible for submitting the information received from the Supplicant to the Authentication Server in order for the credentials to be checked, which will determine the authorization state of the Port. The Authenticator PAE controls the authorized/unauthorized state of the controlled Port depending on the outcome of the authentication process. +All three roles are required in order to complete an authentication exchange. SONiC supports the Authenticator role only, in which the PAE is responsible for communicating with the Supplicant. The Authenticator PAE is also responsible for submitting the information received from the Supplicant to the Authentication Server in order for the credentials to be checked, which will determine the authorization state of the Port. The Authenticator PAE controls the authorized/unauthorized state of the controlled Port depending on the outcome of the authentication process. ### 2.2.1 Local vs. RADIUS Authentication There are two methods that can be used for authenticating a user for a particular port on a switch. These methods are described in the following sections. -Local Authentication -Local authentication consists of matching a user ID/password combination from the Supplicant to a locally-stored user database. The user ID that is returned in response to an EAP-Request/Identity is matched against the database. If a match is found, an EAP-Request/MD5 challenge request is sent to the Supplicant. The Supplicant then takes the challenge, its password and the EAP ID and derives an MD5 response. The MD5 response is then send to the Authenticator which uses the locally stored password to derive the answer and compare it to the Supplicants response. A match results in a successful authentication of the port. +*Local Authentication* +Local authentication consists of matching a user ID/password combination from the Supplicant to a locally-stored user database. The user ID that is returned in response to an EAP-Request/Identity is matched against the database. If a match is found, an EAP-Request/MD5 challenge request is sent to the Supplicant. The Supplicant then takes the challenge, its password and the EAP ID and derives an MD5 response. The MD5 response is then send to the Authenticator which uses the locally stored password to derive the answer and compare it to the Supplicants response. A match results in a successful authentication of the port. Note that the SONiC Authenticator supports only the EAP-MD5 authentication type for local authentication. -### 2.2.2 RADIUS Authentication +*RADIUS Authentication* When RADIUS authentication is used, the Authenticator basically becomes a passthrough between. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section labelled "RADIUS Authentication Attributes" in this document. Per IEEE 802.1X-2001, the SONiC Authenticator supports EAP types that support RFC2284 (i.e. MD5, TLS, PEAP). For certain authentication types, such as EAP-TLS, key information can also be sent from the Authentication Server to the Authenticator as a RADIUS attribute in a RADIUS Access-Accept packet (i.e. the MS-MPPE-Send-Key and MS-MPPE-Recv-Key attributes). The SONiC Authenticator provides the state machines and outcalls to handle keys, but, key distribution has not been fully implemented. The mechanisms provided could be used to extend platforms that support key distribution. Note that re-keying of Supplicants authentication types could be accomplished by enabling reauthentication on the SONiC Authenticator. -### 2.2.3 Unidirectional and bidirectional control +### 2.2.2 Unidirectional and bidirectional control The controlled directions can be configured by management to dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The management setting of the controlled directions parameter can take on one of the following values: 1. Both: Control is exerted over both incoming and outgoing frames. 2. In: Control is only exerted over incoming traffic. Per 802.1X, if the Port is bridge Port, the operational status of controlled directions will be set to Both. However, unidirectional control is not supported in SONiC. Please see "Limitations and Restrictions" section. -### 2.2.4 Downloadable ACL +### 2.2.3 Downloadable ACL PAC (Port access control) feature brings in DACL (downloadable ACL) support into SONiC. As a part of PAC, once a client on an access controlled port is authenticated, the external RADIUS server can send ACL attributes based on user profile configuration on the RADIUS server. These are called Downloadable ACL’s. IPv6 and IPv4 ACLs are supported for DACL. The downloadable ACL rules per client are sent in extended ACL syntax style. The switch applies the client specific DACL for the duration of the authenticated session. The switch does not display RADIUS specified DACL’s in the running configuration. The ACL however shows up in the user interface show commands. Essentially, the DACL configuration is temporary (applied for the duration of the authenticated client session) and not persistent. The downloadable ACLs sent by RADIUS are in extended ACL syntax style and are validated just like user created ACLs. The ACLs created by the applications are owned by the internal application and hence cannot be deleted by a user. -Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. Amoung DACLs IPv6 ACL have higher prority over IPv4. In sitialtions where the client IP address changes, the application created ACLs are automatically updated to accomodate the operational change like a changed client IP address. +Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. Amoung DACLs IPv6 ACL have higher prority over IPv4. In situations where the client IP address changes, the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. -### 2.2.5 Named ACLs +### 2.2.4 Named ACLs RADIUS server can also provide an attribute (filter name/filter id) to have PAC apply a pre-configured ACL on the switch to the client. These pre-configured ACLs are named ACLs. These ACLs are created by the user on the switch. Once RADIUS indicates a named ACL is to be applied for a client, PAC replicates the ACL rules, modifies the rules to incorporate the client IP and then provide them as dynamic ACL rules. -### 2.2.6 RADIUS suplied VLANs +### 2.2.5 RADIUS supplied VLANs PAC (port access control) brings in support for access control with the ability to control user profiles from a RADIUS server. Once a client is authenticated, the client authorization parameters from RADIUS can indicate VLAN association for client traffic. The VLAN associated to the client could be a pre-created VLAN on the switch (static VLAN) in which case port membership of the VLAN are modified. In the absence of the VLAN on the switch, the VLAN are created on the switch (dynamic VLANs). Default VLAN on port A port should not be part of user configured VLAN When PAC is enabled on the port. The port gets configured for a default VLAN (VLAN 1 - configurable) when PAC is enabled on the port. Once PAC is disabled on the port, the port is removed from the default VLAN. -### 2.2.7 FDB interation +### 2.2.6 FDB interaction PAC interacts with FDB to modify the learning mode of a port and add static FDB entries. The FDB related interactions for PAC are outlined below: - PAC adds a static FDB entry for every authenticated client. - SONiC today allows addition of static FDB entries from CLI which are persistent across reloads. The same is enhanced so that PAC SONiC applications can add static FDB entries. @@ -275,7 +270,7 @@ PAC interacts with FDB to modify the learning mode of a port and add static FDB 2. PAC turns off learning on the port essentially dropping all unknown source MAC packets. This achieves the requirement of blocking ingress traffic. 3. Egress traffic on the port is not blocked. 4. Once a client starts the authentication process, the client is no longer unknown (unknown source MAC). However, since authentication is yet to be completed, -traffic for the client must still get dropped. To acheive the same, PAC installs a static FDB entry in drop state to drop the client’s traffic but get classified as L2SrcHit. +traffic for the client must still get dropped. To achieve the same, PAC installs a static FDB entry in drop state to drop the client’s traffic but get classified as L2SrcHit. - For MAC based authentication mode of PAC, unknown source MAC packets are trapped to the CPU. - Station movement is also handled i.e if a packet is received from another port on a MAC, VLAN pair for which PAC installed a static FDB entry, such packets also get trapped to the CPU. @@ -284,7 +279,7 @@ traffic for the client must still get dropped. To acheive the same, PAC installs ## 3.1 Overview -[Figure 1](#pac-config-flow) shows the high level design overview of PAC services in SONiC. PAC Services Daemon is composed of multiple sub-modules. The main module i.e. PAC daemon handles the authentication related commands and makes use of hostApd and mabd dameons to authenticate a client via dot1x and mab respectively. hostApd being a standard linux application takes hostapd.con as a config file. hostApdMgr takes care of listenting to dot1x specific configuration and translating them to respective hostapd.conf file config entires. pacd daemon being the main module decides which autnetication protocol needs to be used for a given port and also calls APIs to program the polices in hardware. +[Figure 1](#pac-config-flow) shows the high level design overview of PAC services in SONiC. PAC Services Daemon is composed of multiple sub-modules. The main module i.e. PAC daemon handles the authentication related commands and makes use of hostApd and mabd daemons to authenticate a client via dot1x and mab respectively. hostApd being a standard Linux application takes hostapd.con as its config file. hostApdMgr takes care of listenting to dot1x specific configuration and translating them to respective hostapd.conf file config entries. pacd daemon being the main module decides which authentication protocol needs to be used for a given port and also calls APIs to program the polices in hardware. ### 3.1.1 Configuration flow From a526c3bdea7e2ff871e671e3badc20d4213be6cf Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 5 Apr 2021 13:10:30 +0530 Subject: [PATCH 11/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 149 ++++++++++++++++++++---------------- 1 file changed, 81 insertions(+), 68 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index b5e4eafc7e2e..f0864d7f8cd6 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -124,6 +124,8 @@ Simple devices like camera or printers which do not support 802.1x authenticatio ## 1.3 Requirements ### 1.3.1 Functional Requirements + +*PAC* The following are the requirements for Port Access Control feature: 1. PAC is supported on physical interfaces only. 2. The interfaces cannot be part of a port-channel / LAG. @@ -132,45 +134,61 @@ The following are the requirements for Port Access Control feature: - 802.1x - MAB (MAC-based authentication bypass). 5. MAB, and dot1x need support for access port. -6. User enable or disable of 802.1X on ports can cause PAC daemons (hostapd) to reload; however, existing authorized sessions do not reset. -7. Changing the 802.1X interface, MAB do not reset existing authorized user ports. However, removing all 802.1X interfaces or changing any of the following RADIUS parameters restarts hostapd, which forces existing, authorized users to re-authenticate: - - RADIUS server IP address, shared secret, authentication port or accounting port. - - MAB activation delay. - - EAP re authentication period. -8. User can configure up to three RADIUS servers (in case of failover). However, do not use a SONiC switch as the RADIUS server. -9. User can configure 802.1X interfaces with dynamic ACLs in VLAN-aware bridge mode only. -10. RADIUS authentication is supported with FreeRADIUS and Cisco ISE. -11. 802.1X supports simple login and password, PEAP/MSCHAPv2 (Win7) and EAP-TLS (Debian). -12. 802.1X supports RFC 5281 for EAP-TTLS, which provides more secure transport layer security. -13. SONiC supports Multi Domain Authentication (MDA), where 802.1X is extended to allow authorization of multiple devices (a data and a voice device) on a single port and assign different VLANs to the devices based on authorization. +6. PAC supports the following Dynamic ACLs: + - Named ACLs + - Dynamic ACLs + - Filter Id +7. SONiC supports Single-Host mode where only one data client can be authenticated on a port and is granted access to the port at a given time. +8. SONiC supports Multiple Hosts mode where only one data client can be authenticated on a port and after that access is granted to all clients connected to the port +9. SONiC supports Multi Domain Authentication (MDA), where 802.1X is extended to allow authorization of multiple devices (a data and a voice device) on a single port and assign different VLANs to the devices based on authorization. - MDA is enabled by default; however, you need to assign a tagged VLAN for voice devices (see Configure 802.1X Interfaces for a VLAN-aware Bridge). - A maximum of four authorized devices (MAB + EAPOL) per port are supported. - The 802.1X-enabled port must be a trunk port to allow tagged voice traffic from a phone; you cannot enable 802.1X on an access port. - Only one untagged VLAN and one tagged VLAN is supported on the 802.1X enabled ports. - Multiple MAB (non voice) devices on a port are supported for VLAN-aware bridges only. Authorization of multiple MAB devices for different VLANs is not supported. - - - +10. SONiC supports Multiple Authentication mode where one voice client and multiple data clients can be authenticated on a port and these clients are then granted access. +11. SONiC supports the following specical VLANs: + - Unauthenticated VLAN + - Guest VLAN + - Monitor VLAN + - Open VLAN + - Critical VLAN + - Voice VLAN +12. The following PAC port modes are supported on SONiC: + - Auto + - Force Authorized + - Force Unauthorized + +*802.1x* +1. SONiC shall make use of opensource 802.1x implementation **hostapd** suppied with **wpa_supplicant** package. + +*MAB* The following are the requirements for MAB feature: -1. A port can be configured to be either doing port-based authentication or doing Mac-based authentication. But only one mode at a given instance. -2. A port when enabled for Dot1x authentication needs to explicitly mention whether it is being enabled for port-based authentication mode or Mac-based authentication mode. -3. When a port is configured for Mac-based Dot1x Authentication, then if at least one client has actively authentication itself then port is placed in authorized state for other components. -4. When a port is configured for Mac-based Dot1x Authentication, then port is placed in un-authorized state if the last active authorized client ceases to exist. -5. When a port is operational in Mac-based Dot1x Authentication, then only the data traffic arriving on the port from authorized clients need to be forwarded. -6. When a port is operational in Mac-based Dot1x Authentication, accept EAPOL packets from all the clients (both authorized and unauthorized as well). -7. When a port is enabled for Guest vlan, then Mac-based dot1x authentication can not be enabled on that port. -8. When a port is enabled for vlan assignment, then Mac-based dot1x authentication could also be enabled on that port. As the vlan assignment is based on the user details of the client. -9. To enable Mac-based dot1x authentication on port it needs to be an Edge port. (Dot1s Configuration). -10. If Mac-based dot1x authentication is enabled on a port and if Mac-based VLANs or Subnet VLANs or Protocol VLANs are also enabled, then Mac-based dot1x authentication is disabled. -11. If Port-Mac Locking is enabled on the port and if Mac-based dot1x authentication is also enabled on the port. Then Port-Mac Locking needs to be disabled. -12. If a client already authentication on one port has roamed to another port on the switch, then the state (status, vlan etc) of the client on the prior port needs to be cleaned. -13. Timeout mechanism needs to be maintained per client so that inactive client's status can be removed on the switch. -14. Multicast/Broadcast traffic arriving on the port that is enabled for Mac-based authentication would be forwarded accordingly. If the source Mac-address of the packet is from a authenticated user. -15. Even when the port is authorized, dot1x would still continue to send EAPOL for authentication as more users could join on the port. -16. Unauthenticated Vlan is per port configuration. By default unauthenticated vlan is zero (invalid and not operational). -17. In port-based dot1x, if the client fails authentication then port is placed in the unauthenticated vlan (if configured) -18. In mac-based dot1x, if the client fails authentication then client-mac is associated to the unauthenticated vlan (if configured). -19. Unauthenticated vlan deprecates the Guest vlan feature of supplicant mode, as it would be redundant. +1. MAB can be used to authenticate clients that do not support EAP. +2. A port can be configured to be either doing port-based authentication or doing Mac-based authentication. But only one mode at a given instance. +3. A port when enabled for Dot1x authentication needs to explicitly mention whether it is being enabled for port-based authentication mode or Mac-based authentication mode. +4. When a port is configured for Mac-based Dot1x Authentication, then if at least one client has actively authentication itself then port is placed in authorized state for other components. +5. When a port is configured for Mac-based Dot1x Authentication, then port is placed in un-authorized state if the last active authorized client ceases to exist. +6. When a port is operational in Mac-based Dot1x Authentication, then only the data traffic arriving on the port from authorized clients need to be forwarded. +7. When a port is operational in Mac-based Dot1x Authentication, accept EAPOL packets from all the clients (both authorized and unauthorized as well). +8. When a port is enabled for Guest vlan, then Mac-based dot1x authentication can not be enabled on that port. +9. When a port is enabled for vlan assignment, then Mac-based dot1x authentication could also be enabled on that port. As the vlan assignment is based on the user details of the client. +10. To enable Mac-based dot1x authentication on port it needs to be an Edge port. (Dot1s Configuration). +11. If Mac-based dot1x authentication is enabled on a port and if Mac-based VLANs or Subnet VLANs or Protocol VLANs are also enabled, then Mac-based dot1x authentication is disabled. +12. If Port-Mac Locking is enabled on the port and if Mac-based dot1x authentication is also enabled on the port. Then Port-Mac Locking needs to be disabled. +13. If a client already authentication on one port has roamed to another port on the switch, then the state (status, vlan etc) of the client on the prior port needs to be cleaned. +14. Timeout mechanism needs to be maintained per client so that inactive client's status can be removed on the switch. +15. Multicast/Broadcast traffic arriving on the port that is enabled for Mac-based authentication would be forwarded accordingly. If the source Mac-address of the packet is from a authenticated user. +16. Even when the port is authorized, dot1x would still continue to send EAPOL for authentication as more users could join on the port. +17. Unauthenticated Vlan is per port configuration. By default unauthenticated vlan is zero (invalid and not operational). +18. In port-based dot1x, if the client fails authentication then port is placed in the unauthenticated vlan (if configured) +19. In mac-based dot1x, if the client fails authentication then client-mac is associated to the unauthenticated vlan (if configured). +20. Unauthenticated vlan deprecates the Guest vlan feature of supplicant mode, as it would be redundant. + +*RADIUS* +1. User can configure up to three RADIUS servers (in case of failover). However, do not use a SONiC switch as the RADIUS server. +2. RADIUS authentication is supported with FreeRADIUS and Cisco ISE. + ### 1.3.2 Configuration and Management Requirements @@ -193,11 +211,9 @@ No changes to SAI spec for supporting PAC. ## 2.1 Target Deployment Use Cases -When a client authenticates itself initially on the network, the Switch acts as the authenticator to the clients on the network and forwards the authentication request to the Radius server in the network. If the authentication succeeds then the port is placed in authorized state and the client is able to forward or receive traffic through the port. - -In a standard dot1x scenario, all the subsequent clients in the network that are connected to the same port need not authenticate to utilize the port on the switch. When Mac-based dot1x authentication is enabled, all the subsequent clients in the network that are connected to the same port need to authenticate themselves to utilize the port on the switch. +When a client authenticates itself initially on the network, the Switch acts as the authenticator to the clients on the network and forwards the authentication request to the Radius server in the network. If the authentication succeeds then the client is placed in authorized state and the client is able to forward or receive traffic through the port. -If the vlan assignment is enabled in the Radius server then as part of the response message Radius server sends the vlan id the client is supposed to be in the 802.1x tunnel attributes. In the diagram above, the switch has placed three clients belonging to same port in the different vlans (vlan10 and vlan20) based on the user details of the clients. This implies that the client can connect from any port and can get assigned to the appropriate vlan that it is supposed to be in, this is configured in the radius server. This gives flexibility for the clients to move around the network with out much configuration need to be done by the administrator. +If the vlan assignment is enabled in the Radius server, then as part of the response message, Radius server sends the vlan id the client is supposed to be in the 802.1x tunnel attributes. This implies that the client can connect from any port and can get assigned to the appropriate vlan that it is supposed to be in; this is configured in the radius server. This gives flexibility for the clients to move around the network with out much configuration need to be done by the administrator. ## 2.2 Functional Description @@ -230,15 +246,13 @@ Note that the SONiC Authenticator supports only the EAP-MD5 authentication type *RADIUS Authentication* -When RADIUS authentication is used, the Authenticator basically becomes a passthrough between. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section labelled "RADIUS Authentication Attributes" in this document. - -Per IEEE 802.1X-2001, the SONiC Authenticator supports EAP types that support RFC2284 (i.e. MD5, TLS, PEAP). For certain authentication types, such as EAP-TLS, key information can also be sent from the Authentication Server to the Authenticator as a RADIUS attribute in a RADIUS Access-Accept packet (i.e. the MS-MPPE-Send-Key and MS-MPPE-Recv-Key attributes). The SONiC Authenticator provides the state machines and outcalls to handle keys, but, key distribution has not been fully implemented. The mechanisms provided could be used to extend platforms that support key distribution. Note that re-keying of Supplicants authentication types could be accomplished by enabling reauthentication on the SONiC Authenticator. - +When RADIUS authentication is used, the Authenticator basically becomes a passthrough. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section labelled "RADIUS Authorization Attributes" in this document. ### 2.2.2 Unidirectional and bidirectional control -The controlled directions can be configured by management to dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The management setting of the controlled directions parameter can take on one of the following values: +The controlled directions dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control direction are of two type: 1. Both: Control is exerted over both incoming and outgoing frames. -2. In: Control is only exerted over incoming traffic. Per 802.1X, if the Port is bridge Port, the operational status of controlled directions will be set to Both. However, unidirectional control is not supported in SONiC. Please see "Limitations and Restrictions" section. +2. In: Control is only exerted over incoming traffic. +SONiC supports on the unidirection(In) control. Please see "Limitations and Restrictions" section. ### 2.2.3 Downloadable ACL @@ -250,28 +264,28 @@ Generally, any static ACLs (created by user) applied on the port are removed pri ### 2.2.4 Named ACLs -RADIUS server can also provide an attribute (filter name/filter id) to have PAC apply a pre-configured ACL on the switch to the client. These pre-configured ACLs are named ACLs. These ACLs are created by the user on the switch. Once RADIUS indicates a named ACL is to be applied for a client, PAC replicates the ACL rules, modifies the rules to incorporate the client IP and then provide them as dynamic ACL rules. +RADIUS server can also provide an attribute (filter name/filter id) to have PAC apply a pre-configured ACL on the switch to the client. These pre-configured ACLs are *named ACLs*. These ACLs are created by the user on the switch. Once RADIUS indicates a named ACL is to be applied for a client, PAC replicates the ACL rules, modifies the rules to incorporate the client IP and then provide them as dynamic ACL rules. ### 2.2.5 RADIUS supplied VLANs -PAC (port access control) brings in support for access control with the ability to control user profiles from a RADIUS server. Once a client is authenticated, the client authorization parameters from RADIUS can indicate VLAN association for client traffic. The VLAN associated to the client could be a pre-created VLAN on the switch (static VLAN) in which case port membership of the VLAN are modified. In the absence of the VLAN on the switch, the VLAN are created on the switch (dynamic VLANs). +PAC (port access control) brings in support for access control with the ability to control user profiles from a RADIUS server. Once a client is authenticated, the client authorization parameters from RADIUS can indicate VLAN association for client traffic. The VLAN associated to the client could be a pre-created VLAN on the switch (static VLAN). In the absence of the VLAN on the switch, the VLAN are created on the switch (dynamic VLANs). Default VLAN on port A port should not be part of user configured VLAN When PAC is enabled on the port. The port gets configured for a default VLAN (VLAN 1 - configurable) when PAC is enabled on the port. Once PAC is disabled on the port, the port is removed from the default VLAN. ### 2.2.6 FDB interaction -PAC interacts with FDB to modify the learning mode of a port and add static FDB entries. The FDB related interactions for PAC are outlined below: -- PAC adds a static FDB entry for every authenticated client. +PAC interacts with FDB to modify the learning mode of a port and add static FDB entries. The FDB related interactions for PAC are outlined below: +- PAC adds a static FDB entry for every authenticated client on Multi-Auth, Single-Host and Multi-Domain host modes. - SONiC today allows addition of static FDB entries from CLI which are persistent across reloads. The same is enhanced so that PAC SONiC applications can add static FDB entries. - Note that FDB entries thus added are not persistent and are operational config only (entries added as a result of the client getting authenticated). - The entries get removed once the client logs off. - FDB entries added operationally follows a similar config sequence like user created FDB entries. - The learning mode of a port (or bridge port) was configured and controlled completely at the orchestration layer. With PAC, the application layer (pacd) also manages the learning mode to - 1. Once PAC is enabled on a port, all incoming and outgoing traffic on the port are blocked/dropped except certain protocol traffic. + 1. Once PAC is enabled on a port, all incoming traffic on the port are blocked/dropped except certain protocol traffic. 2. PAC turns off learning on the port essentially dropping all unknown source MAC packets. This achieves the requirement of blocking ingress traffic. 3. Egress traffic on the port is not blocked. 4. Once a client starts the authentication process, the client is no longer unknown (unknown source MAC). However, since authentication is yet to be completed, -traffic for the client must still get dropped. To achieve the same, PAC installs a static FDB entry in drop state to drop the client’s traffic but get classified as L2SrcHit. -- For MAC based authentication mode of PAC, unknown source MAC packets are trapped to the CPU. +traffic for the client must still get dropped. To achieve the same, PAC installs a static FDB entry with discard bits set, is installed to mark the client "known" so that the incoming traffic does not flood the CPU. +- For MAB, unknown source MAC packets are trapped to the CPU. - Station movement is also handled i.e if a packet is received from another port on a MAC, VLAN pair for which PAC installed a static FDB entry, such packets also get trapped to the CPU. @@ -279,7 +293,7 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ## 3.1 Overview -[Figure 1](#pac-config-flow) shows the high level design overview of PAC services in SONiC. PAC Services Daemon is composed of multiple sub-modules. The main module i.e. PAC daemon handles the authentication related commands and makes use of hostApd and mabd daemons to authenticate a client via dot1x and mab respectively. hostApd being a standard Linux application takes hostapd.con as its config file. hostApdMgr takes care of listenting to dot1x specific configuration and translating them to respective hostapd.conf file config entries. pacd daemon being the main module decides which authentication protocol needs to be used for a given port and also calls APIs to program the polices in hardware. +[Figure 1](#pac-config-flow) shows the high level design overview of PAC services in SONiC. PAC Services Daemon is composed of multiple sub-modules. The main module i.e. PAC daemon handles the authentication related commands and makes use of hostApd and mabd daemons to authenticate a client via dot1x and mab respectively. hostApd being a standard Linux application takes hostapd.conf as its config file. hostApdMgr takes care of listening to dot1x specific configuration and translating them to respective hostapd.conf file config entries. pacd daemon being the main module decides which authentication protocol needs to be used for a given port and also calls APIs to program the polices in hardware. ### 3.1.1 Configuration flow @@ -290,8 +304,8 @@ traffic for the client must still get dropped. To achieve the same, PAC installs 1. Mgmt interfaces like CLI and REST writes the user provided configuration to CONFIG_DB. 2. The pacd, mabd and hostApdMgr gets notified about their respective configuration. 3. hostApd being a standard Linux application gets its configuration from hostapd.conf file. hostApdMgr makes use of Jinja2 templates to generates the hostapd.conf file based on the relevant CONFIG_DB tables. -4. Pacd gets to know about the list of ports that needs to be authenticated via DOT1X and MAB and their priority from PAC_PORT_CONF_TABLE on CONFIG_DB. Based on the priority and authentication failure status, pacd decides on the list of ports to be authenticated via DOT1X and MAB and It communicates the list of interfaces to hostApd and mabd respectively via netlink messages. -5. hostApd listen to EAPOL PDUs on the provided interface list and proceeds to authenticate the client when it receives a PDU. mabd listens to DHCP and EAPOL PDUs on the provided interface list and proceeds to authenticate the client when it receives a PDU. +4. Pacd gets to know about the list of ports that needs to be authenticated from PAC_PORT_CONFIG_TABLE on CONFIG_DB. The same table provides info on which ports supporrts DOT1X and which supports MAB and priority amoung the authentication methods. Based on the priority and authentication failure status, pacd decides on the list of ports to be authenticated via DOT1X and the list of ports that needs to be authenticated via MAB. It communicates the respective list of interfaces to hostApd and mabd via netlink messages. +5. hostApd listens to EAPOL PDUs on the provided interface list and proceeds to authenticate the client when it receives a PDU. mabd listens to DHCP and EAPOL PDUs on the provided interface list and proceeds to authenticate the client when it receives a PDU. @@ -322,7 +336,7 @@ traffic for the client must still get dropped. To achieve the same, PAC installs 1. DHCP packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to pacd socket listening on the kernel interface associated with the given front panel interface. 2. Pacd sends an Client Authenticate netlink message along with the received PDU MAC. 3. mabd interacts with RADIUS server to authenticate the given client based on the MAC. -4. On successful authentication of a client, mabd sends an Client Authenticated netlink message to pacd with all the atheization parameters like VLAN and DACL. +4. On successful authentication of a client, mabd sends an Client Authenticated netlink message to pacd with all the authorization parameters like VLAN and DACL. 5. pacd proceeds to authorize the client by writing PAC_AUTHORIZE_TABLE on APPL_DB. RADIUS authorization parameters like dynamic VLAN, dynamic ACL are created by writing on their tables on STATE_DB. 6. Orchagent in SWSS docker gets notified about changes in APPL_DB and responds by translating the APPL_DB changes to respective sairedis calls. 7. Sairedis APIs write into ASIC_DB. @@ -398,11 +412,6 @@ In this mode one data client and one voice client can be authenticated on a port *Multiple Authentication mode* In this mode one voice client and multiple data clients can be authenticated on a port and these clients are then granted access. Typical use case is a network of laptops and an IP phone connected to the NAS port via a hub. -*Multiple Domain Multi Host mode* -In this mode one voice client and one data client can be authenticated on a port and these clients are then granted access. However once a data client is authenticated, access is granted to all clients connected to the port and they are considered data clients. Typical use case is an IP phone connected to a NAS port and a Virtual Machine Controller connected to the hub port of the IP phone. The Virtual Machine Controller hosts multiple Virtual Machines. Both the VM Controller and the IP phone need to be authenticated to access the network services behind the NAS. The voice and data domains are segregated. Once the VM Controller is authenticated, it allows traffic from all the VMs hosted by the VM Controller. Once this client gets authenticated, the port is open for all clients connected to the port. Authentication and port access is also allowed for a Voice device. - -Note: If the data client gets authenticated first, the Voice client can only be authenticated using 802.1x. - **Authentication Manager Authentication method fallback and priorities** Authentication manager controls the order in which the authentication methods are executed. Authentication manager does not make any required configuration for the respective methods to authenticate successfully. User or Administrator needs to ensure that the correct and appropriate configuration is present in the system. @@ -418,15 +427,15 @@ If administrator changes the priority of the methods, then all the users who are **Authorization parameters** -Upon successful authentication, the authentication methods inform Authentication Manager about the result. Authentication Manager then authorizes the port and configures it for allowing traffic from and to the client. +Upon successful authentication, the authentication methods inform Authentication Manager about the result. Authentication Manager then authorizes the port and configures it for allowing traffic from the client. Authentication Manager receives the client authorization parameters from the authentication method after successful authentication of a client. The following parameters are acted upon: - *VLAN Id*: This is the VLAN ID sent by a RADIUS server. Authentication Manager configures the port membership accordingly so that the client traffic is associated with the VLAN. Refer [3] for further details. - *Session Timeout*: This is the timeout attribute of the authenticated client session. - *Session Termination Action*: Upon session timeout, the Session Termination Action determines the action on the client session. The following actions are defined: -- *Default*: The client session is torn down and authentication needs to be restarted for the client. -- *RADIUS*: Re-authentication is initiated for the client. + - *Default*: The client session is torn down and authentication needs to be restarted for the client. + - *RADIUS*: Re-authentication is initiated for the client. - *Filter-Id*: Specifies an ACL of Diffserv policy name. This is used to apply a Static ACL or DiffServ policy on the port for the client. IPv4 and IPv6 ACLs in the “IN” direction is supported. If the Differv policy or ACL is not present in the system, or if a Diffserv policy is already configured on the port, authentication for the client is rejected. These are subject to Monitor Mode configuration. Filter-Id is supported on all Authentication Manager host modes. - *Downloadable ACL*: DACLs are supported on all host modes. - *Redirect ACL*: This is used to apply an ACL that traps matching packets to the CPU for redirection. It is typically used to match on HTTP packets from a client. @@ -440,8 +449,6 @@ Today, 802.1x has become the recommended port-based authentication method at the - EAP-MD5 - PAP -SONiC provides a mechanism to format the attribute1 as part of MAB configuration. This mechanism decouples the formats of attribute1 and attribute31 sent in the RADIUS packets and enables separate controls for both. - Mac-based Authentication Bypass (MAB) is configured per port. For MAB to be used for authentication it needs to be is configured as an authentication method in method list for the port by Authentication Manager, MAB authentication is done in the order in which the methods are configured. If first in the list, MAB occurs first. If second in the list after 802.1x, MAB will occur if 802.1X times out or fails. 802.1X timeout is determined by the following time period: Timeout = (maxReAuthReqIdentity + 1) * txPeriod @@ -710,8 +717,6 @@ Configured actions and counters should continue to work across warm reboot. - Authentication Manager does not make any required configuration for the respective methods to authenticate successfully. The administrator needs to ensure that the correct and appropriate configuration is present in the system. For example, if the authentication order method includes the 802.1x port authentication method, 802.1X should be enabled for the authentication to succeed. Authentication manager will not enable/disable and make the configurations related to 802.1X. Administrator should make the necessary configurations. -- If the authentication order includes web authentication, then fallback profile that enables web authentication on the switch and the interface should be configured. Similarly all the required ACLs should be configured by the administrator or user. - - In the default configuration, all traffic that is not EAP over LAN (EAPoL) traffic (including DHCP) is dropped until 802.1X and MAB times out. Therefore, the value of the timeout can significantly affect the DHCP client on the end host. Longer 802.1X timeouts may prevent DHCP from functioning correctly after the 802.1X timeout expires. - To prevent DHCP clients from timing out, SONiC recommends testing the DHCP clients in respective network to discover how long they take to time out and setting the 802.1X timers accordingly. @@ -724,7 +729,8 @@ Configured actions and counters should continue to work across warm reboot. # 10 Upgrade / Downgrade considerations # 11 Unit Test - +*fpinfra* +This being a library that provides C APIs is unit tested via a C/C++ based test utility that exercises those APIs. The unit test is build up on the google test (gtest) infra. The test infra relies on the automake "make check" and gets executed during the compliation of sonic-secutity docker. # 12 Appendix: Sample configuration @@ -734,7 +740,14 @@ Configured actions and counters should continue to work across warm reboot. # 13 Internal Design Information -Internal BRCM information to be removed before sharing with the community +Internal BRCM information to be removed before sharing with the community. + +Feature shall be supported on below mentioned platforms. +*AS4630* +- 4 Core CPU +- 8 GB RAM +- 16G Disc +- TD3-X3 ## 13.1 Future Design Enhancements From 52b2ea5e0705c4e31127ffcf95f284b41a80773e Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 5 Apr 2021 13:42:48 +0530 Subject: [PATCH 12/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 169 +++++++++++++++++++++++++++++++----- 1 file changed, 147 insertions(+), 22 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index f0864d7f8cd6..7fcc2583fe7e 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -86,6 +86,7 @@ High level design document version 0.1 | Rev | Date | Author | Change Description | | ---- | ---------- | ---------| ------------------ | | 0.1 | 02/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Initial version | +| 0.2 | 04/05/2021 | Prabhu Sreenivasan | Initial Review comments | # About this Manual This document provides general information about the Port Access Control feature in SONiC. @@ -125,7 +126,7 @@ Simple devices like camera or printers which do not support 802.1x authenticatio ### 1.3.1 Functional Requirements -*PAC* +*PAC* The following are the requirements for Port Access Control feature: 1. PAC is supported on physical interfaces only. 2. The interfaces cannot be part of a port-channel / LAG. @@ -159,10 +160,10 @@ The following are the requirements for Port Access Control feature: - Force Authorized - Force Unauthorized -*802.1x* +*802.1x* 1. SONiC shall make use of opensource 802.1x implementation **hostapd** suppied with **wpa_supplicant** package. -*MAB* +*MAB* The following are the requirements for MAB feature: 1. MAB can be used to authenticate clients that do not support EAP. 2. A port can be configured to be either doing port-based authentication or doing Mac-based authentication. But only one mode at a given instance. @@ -185,7 +186,7 @@ The following are the requirements for MAB feature: 19. In mac-based dot1x, if the client fails authentication then client-mac is associated to the unauthenticated vlan (if configured). 20. Unauthenticated vlan deprecates the Guest vlan feature of supplicant mode, as it would be redundant. -*RADIUS* +*RADIUS* 1. User can configure up to three RADIUS servers (in case of failover). However, do not use a SONiC switch as the RADIUS server. 2. RADIUS authentication is supported with FreeRADIUS and Cisco ISE. @@ -218,30 +219,28 @@ If the vlan assignment is enabled in the Radius server, then as part of the resp ## 2.2 Functional Description -The Ports of an 802.1X Authenticator switch provide the means in which it can offer services to other systems reachable via the LAN. Port-based network access control allows the operation of a System's Port(s) to be controlled in order to ensure that access to its services is only permitted by Systems that are authorized to do so. +The Ports of an 802.1X Authenticator switch provide the means in which it can offer services to other systems reachable via the LAN. Port-based network access control allows the operation of a System's Port(s) to be controlled in order to ensure that access to its services is only permitted by Systems that are authorized to do so. -Port Access Control provides a means of preventing unauthorized access by Supplicants to the services offered by a System. Control over the access to a switch and the LAN to which it is connected can be desirable in order to restrict access to publicly accessible bridge ports or to restrict access to departmental LANs. +Port Access Control provides a means of preventing unauthorized access by Supplicants to the services offered by a System. Control over the access to a switch and the LAN to which it is connected can be desirable in order to restrict access to publicly accessible bridge ports or to restrict access to departmental LANs. -Access control is achieved by enforcing authentication of Supplicants that are attached to an Authenticator's controlled Ports. The result of the authentication process determines whether the Supplicant is authorized to access services on that controlled Port. - -A PAE is able to adopt one of two distinct roles within an access control interaction: +Access control is achieved by enforcing authentication of Supplicants that are attached to an Authenticator's controlled Ports. The result of the authentication process determines whether the Supplicant is authorized to access services on that controlled Port. +A PAE is able to adopt one of two distinct roles within an access control interaction: 1. authenticator: A Port that enforces authentication before allowing access to services available via that Port. +2. supplicant: A Port that attempts to access services offered by the Authenticator. -2. supplicant: A Port that attempts to access services offered by the Authenticator. - -Additionally, there exists a third role: +Additionally, there exists a third role: 3. authentication server: Performs the authentication function necessary to check the credentials of the Supplicant on behalf of the Authenticator. All three roles are required in order to complete an authentication exchange. SONiC supports the Authenticator role only, in which the PAE is responsible for communicating with the Supplicant. The Authenticator PAE is also responsible for submitting the information received from the Supplicant to the Authentication Server in order for the credentials to be checked, which will determine the authorization state of the Port. The Authenticator PAE controls the authorized/unauthorized state of the controlled Port depending on the outcome of the authentication process. ### 2.2.1 Local vs. RADIUS Authentication -There are two methods that can be used for authenticating a user for a particular port on a switch. These methods are described in the following sections. +There are two methods that can be used for authenticating a user for a particular port on a switch. These methods are described in the following sections. *Local Authentication* Local authentication consists of matching a user ID/password combination from the Supplicant to a locally-stored user database. The user ID that is returned in response to an EAP-Request/Identity is matched against the database. If a match is found, an EAP-Request/MD5 challenge request is sent to the Supplicant. The Supplicant then takes the challenge, its password and the EAP ID and derives an MD5 response. The MD5 response is then send to the Authenticator which uses the locally stored password to derive the answer and compare it to the Supplicants response. A match results in a successful authentication of the port. -Note that the SONiC Authenticator supports only the EAP-MD5 authentication type for local authentication. +Note that the SONiC Authenticator supports only the EAP-MD5 authentication type for local authentication. *RADIUS Authentication* @@ -249,18 +248,18 @@ Note that the SONiC Authenticator supports only the EAP-MD5 authentication type When RADIUS authentication is used, the Authenticator basically becomes a passthrough. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section labelled "RADIUS Authorization Attributes" in this document. ### 2.2.2 Unidirectional and bidirectional control -The controlled directions dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control direction are of two type: +The controlled directions dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control direction are of two type: 1. Both: Control is exerted over both incoming and outgoing frames. -2. In: Control is only exerted over incoming traffic. +2. In: Control is only exerted over incoming traffic. SONiC supports on the unidirection(In) control. Please see "Limitations and Restrictions" section. ### 2.2.3 Downloadable ACL -PAC (Port access control) feature brings in DACL (downloadable ACL) support into SONiC. As a part of PAC, once a client on an access controlled port is authenticated, the external RADIUS server can send ACL attributes based on user profile configuration on the RADIUS server. These are called Downloadable ACL’s. IPv6 and IPv4 ACLs are supported for DACL. The downloadable ACL rules per client are sent in extended ACL syntax style. The switch applies the client specific DACL for the duration of the authenticated session. +PAC (Port access control) feature brings in DACL (downloadable ACL) support into SONiC. As a part of PAC, once a client on an access controlled port is authenticated, the external RADIUS server can send ACL attributes based on user profile configuration on the RADIUS server. These are called Downloadable ACL’s. IPv6 and IPv4 ACLs are supported for DACL. The downloadable ACL rules per client are sent in extended ACL syntax style. The switch applies the client specific DACL for the duration of the authenticated session. -The switch does not display RADIUS specified DACL’s in the running configuration. The ACL however shows up in the user interface show commands. Essentially, the DACL configuration is temporary (applied for the duration of the authenticated client session) and not persistent. The downloadable ACLs sent by RADIUS are in extended ACL syntax style and are validated just like user created ACLs. The ACLs created by the applications are owned by the internal application and hence cannot be deleted by a user. +The switch does not display RADIUS specified DACL’s in the running configuration. The ACL however shows up in the user interface show commands. Essentially, the DACL configuration is temporary (applied for the duration of the authenticated client session) and not persistent. The downloadable ACLs sent by RADIUS are in extended ACL syntax style and are validated just like user created ACLs. The ACLs created by the applications are owned by the internal application and hence cannot be deleted by a user. -Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. Amoung DACLs IPv6 ACL have higher prority over IPv4. In situations where the client IP address changes, the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. +Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. Amoung DACLs IPv6 ACL have higher prority over IPv4. In situations where the client IP address changes, the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. ### 2.2.4 Named ACLs @@ -275,7 +274,7 @@ A port should not be part of user configured VLAN When PAC is enabled on the por ### 2.2.6 FDB interaction PAC interacts with FDB to modify the learning mode of a port and add static FDB entries. The FDB related interactions for PAC are outlined below: - PAC adds a static FDB entry for every authenticated client on Multi-Auth, Single-Host and Multi-Domain host modes. -- SONiC today allows addition of static FDB entries from CLI which are persistent across reloads. The same is enhanced so that PAC SONiC applications can add static FDB entries. +- SONiC today allows addition of static FDB entries from CLI which are persistent across reloads. The same is enhanced so that PAC SONiC applications can add static FDB entries. - Note that FDB entries thus added are not persistent and are operational config only (entries added as a result of the client getting authenticated). - The entries get removed once the client logs off. - FDB entries added operationally follows a similar config sequence like user created FDB entries. @@ -350,6 +349,68 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ### 3.2.1 Config DB +``` + "PAC_PORT_CONFIG_TABLE": { +"ethernet1": { +"method_list": [ +"802.1x", +"mab" +], +"priority_list": [ +"802.1x", +"mab" +], +"port_control_mode": "auto", +"host_control_mode": "multi_auth", +"quiet_period": 10, +"reauth_period": 60, +"reauth_enable": "true", +"max_users_per_port": 48, +"max_reauth_attempts": 1, +"guest_vlan": 10, +"auth_fail_vlan": 100 +} +} + + +key = PAC_PORT_CONFIG_TABLE:port ; Physical port +;field = value +method_list = "dot1x"/"mab" ; List of methods to be used for authentication +priority_list= "dot1x"/"mab"; Relative priority of methods to be used for authentication +port_control_mode = "auto"/"force_authorized"/"force_unauthorized"; Port control mode + ; 'auto": authentication enforced on port + ; 'force_authorized": authentication not enforced on port + ; 'force_unauthorized": authentication not enforced on port but port is blocked for all traffic +host_control_mode = "multi-host"/"multi-domain"/"multi-auth"/"single-auth" ; Host control mode + ; "multi-host": One data client can be authenticated on the port. Rest of the clients tailgate once the first client is authenticated. + ; "multi-domain": One data client and one voice client can be authenticated on the port. + ; "multi-auth": Multiple data client and one voice client can be authenticated on the port. + ; "single-auth": One data client or one voice client can be authenticated on the port. + +quiet_period = 1*5DIGIT ; The initial value of the timer that defines the period during which the Authenticator will not attempt to authenticate the Supplicant. Range is 0-65535 seconds. +reauth_period = 1*10DIGIT;The initial value of the timer that defines the period after which the Authenticator will reauthenticate the Supplicant. Range is 3600 - 4294967296 seconds. +reauth_enable = "true"/"false";Indicates whether Reauthentication is enabled on the port. +max_users_per_port=1*2DIGIT; Maximum number of clients that can be authenticated on the port. This is applicable only for "multi-auth" host mode.Range is 1 - 64 clients. +guest_vlan_id= 1*4DIGIT;The Guest VLAN Id for the port. Range is 1 - 4093 +auth_fail_vlan_id=1*4DIGIT;The Authentication Fail VLAN Id for the port. Range is 1 - 4093 +max_auth_attempts=1DIGIT;The maximum number of authentication retries in the event of authentication failure.Range is 1 - 5 + +``` + +``` + +"PAC_GLOBAL_CONFIG_TABLE": { +"authentication_enable": "true", +"monitor_mode_enable": "false" +} + + +;field=value +authentication_enable="true"/"false";Indicates whether PAC is enabled in the system. +monitor_mode_enable="true"/"false";Indicates whether monitor mode is enabled in the system. + +``` + ### 3.2.2 App DB @@ -358,6 +419,68 @@ traffic for the client must still get dropped. To achieve the same, PAC installs None ### 3.2.5 Counter DB +None +### 3.2.6 State DB +``` +" PAC_PORT_OPER_TABLE ": { +"ethernet1": { +"enabled_method_list": [ +"802.1x", +"mab" +], +"enabled_priority_list": [ +"802.1x", +"mab" +], +"num_clients_authenticated": 10 +} +} + +auth_fail_vlan_id = 1*4DIGIT ; The Authentication Fail VLAN Id for the port. Range is 1 - 4093 +max_auth_attempts = 1DIGIT ; The maximum number of authentication retries in the event of authentication failure. Range is 1 - 5 +;field = value +authentication_enable = "true"/"false" ; Indicates whether PAC is enabled in the system. +monitor_mode_enable = "true"/"false" ; Indicates whether monitor mode is enabled in the system. + +``` + +``` +" PAC_AUTHENTICATED_CLIENT_OPER_TABLE ": { +"ethernet1": [{ +"00:00:00:11:02:33": { +"current_id": 21, +"auth_status": "authorized", +"authenticated_method": "802.1X", +"server_state": "36 34 43 50 4d 53 65 73 73 69 6f 6e 49 44 3d 30 61 38 32 62 39 37 36 4c 49 +50 5a 44 45 4d 32 74 64 35 55 39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d +6e 4a 33 31 42 6a 5a 34 51 49 3b 33 34 53 65 73 73 69 6f 6e 49 44 3d 43 69 73 63 6f 49 53 45 +2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35 3b", +"server_state_len": 106, +"server_class": "43 41 43 53 3a 30 61 38 32 62 39 37 36 4c 49 50 5a 44 45 4d 32 74 64 35 55 +39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d 6e 4a 33 31 42 6a 5a 34 51 49 +3a 43 69 73 63 6f 49 53 45 2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35", +"server_class_len": 83, +"session_timeout": 60, +"user_name": "sonic_user", +"user_name_len": 9, +"termination_action": 0, +"vlan_id": 194, +"vlan_type": "radius", +"backend_auth_method": "radius", +"session_time": 511 +} +}, +{ +"00:00:00:21:00:30": { +"current_id": 28, +"auth_status": "authorized", +"authenticated_method": "802.1X", +key = PAC_PORT_OPER_TABLE : port ; Physical port +;field = value +enabled_method_list = "dot1x"/"mab" ; List of methods to be used for authentication +enabled_priority_list = "dot1x"/"mab" ; Relative priority of methods to be used for authentication +num_clients_authenticated = 1*2DIGIT ; Number of clients authenticated on the port. +``` ## 3.3 Switch State Service Design @@ -729,8 +852,10 @@ Configured actions and counters should continue to work across warm reboot. # 10 Upgrade / Downgrade considerations # 11 Unit Test -*fpinfra* -This being a library that provides C APIs is unit tested via a C/C++ based test utility that exercises those APIs. The unit test is build up on the google test (gtest) infra. The test infra relies on the automake "make check" and gets executed during the compliation of sonic-secutity docker. + +*fpinfra* + +fpinfra being a shared library that provides C APIs is unit tested via a C/C++ based test utility that exercises those APIs. The unit test is build up on the google test (gtest) infrastructure. The test infra relies on the automake "make check" and gets executed during the compliation of sonic-secutity docker. # 12 Appendix: Sample configuration From 3df948912c67f01b7985312dda9229a6cd99b5c9 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 5 Apr 2021 15:12:57 +0530 Subject: [PATCH 13/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 244 ++++++++++++++++++++++++++++++++---- 1 file changed, 218 insertions(+), 26 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 7fcc2583fe7e..39f613741fdf 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.1 +High level design document version 0.2 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -86,7 +86,7 @@ High level design document version 0.1 | Rev | Date | Author | Change Description | | ---- | ---------- | ---------| ------------------ | | 0.1 | 02/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Initial version | -| 0.2 | 04/05/2021 | Prabhu Sreenivasan | Initial Review comments | +| 0.2 | 04/05/2021 | Prabhu Sreenivasan | DB schema update and Review comments | # About this Manual This document provides general information about the Port Access Control feature in SONiC. @@ -349,7 +349,8 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ### 3.2.1 Config DB -``` +*PAC* +``` "PAC_PORT_CONFIG_TABLE": { "ethernet1": { "method_list": [ @@ -375,13 +376,14 @@ traffic for the client must still get dropped. To achieve the same, PAC installs key = PAC_PORT_CONFIG_TABLE:port ; Physical port ;field = value -method_list = "dot1x"/"mab" ; List of methods to be used for authentication -priority_list= "dot1x"/"mab"; Relative priority of methods to be used for authentication -port_control_mode = "auto"/"force_authorized"/"force_unauthorized"; Port control mode +method_list = "dot1x"/"mab" ; List of methods to be used for authentication +priority_list = "dot1x"/"mab"; Relative priority of methods to be used for authentication +port_control_mode = "auto"/"force_authorized"/"force_unauthorized"; Port control mode ; 'auto": authentication enforced on port ; 'force_authorized": authentication not enforced on port ; 'force_unauthorized": authentication not enforced on port but port is blocked for all traffic -host_control_mode = "multi-host"/"multi-domain"/"multi-auth"/"single-auth" ; Host control mode + +host_control_mode = "multi-host"/"multi-domain"/"multi-auth"/"single-auth" ; Host control mode ; "multi-host": One data client can be authenticated on the port. Rest of the clients tailgate once the first client is authenticated. ; "multi-domain": One data client and one voice client can be authenticated on the port. ; "multi-auth": Multiple data client and one voice client can be authenticated on the port. @@ -394,23 +396,29 @@ max_users_per_port=1*2DIGIT; Maximum number of clients that can be authenticated guest_vlan_id= 1*4DIGIT;The Guest VLAN Id for the port. Range is 1 - 4093 auth_fail_vlan_id=1*4DIGIT;The Authentication Fail VLAN Id for the port. Range is 1 - 4093 max_auth_attempts=1DIGIT;The maximum number of authentication retries in the event of authentication failure.Range is 1 - 5 +``` -``` - -``` - +``` "PAC_GLOBAL_CONFIG_TABLE": { "authentication_enable": "true", "monitor_mode_enable": "false" } - - + ;field=value -authentication_enable="true"/"false";Indicates whether PAC is enabled in the system. -monitor_mode_enable="true"/"false";Indicates whether monitor mode is enabled in the system. +authentication_enable = "true"/"false";Indicates whether PAC is enabled in the system. +monitor_mode_enable = "true"/"false";Indicates whether monitor mode is enabled in the system. + +``` +*hostapd* ``` +" HOSTAPD_GLOBAL_CONFIG_TABLE ": { +"dot1x_system_auth_control": "enable" +} +;field = value +dot1x_system_auth_control "true"/"false" ; Indicates whether dot1x is enabled in the system. +``` ### 3.2.2 App DB @@ -419,9 +427,60 @@ monitor_mode_enable="true"/"false";Indicates whether monitor mode is enabled in None ### 3.2.5 Counter DB -None -### 3.2.6 State DB + ``` +"HOST_APD_STATS_TABLE": [{ +"00:00:00:11:22:33": { +"dot1xAuthEapolFramesRx": 311, +"dot1xAuthEapolFramesTx": 380, +"dot1xAuthEapolStartFramesRx": 71, +"dot1xAuthEapolLogoffFramesRx": 15, +"dot1xAuthEapolRespIdFramesRx": 67, +"dot1xAuthEapolRespFramesRx": 212, +"dot1xAuthEapolReqIdFramesTx": 250, +"dot1xAuthEapolReqFramesTx": 250, +"dot1xAuthInvalidEapolFramesRx": 250, +"dot1xAuthEapLengthErrorFramesRx": 250, +"dot1xAuthLastEapolFrameVersion": 2 +} +}, +{ +"00:00:00:22:22:34": { +"dot1xAuthEapolFramesRx": 311, +"dot1xAuthEapolFramesTx": 380, +"dot1xAuthEapolStartFramesRx": 71, +"dot1xAuthEapolLogoffFramesRx": 15, +"dot1xAuthEapolRespIdFramesRx": 67, +"dot1xAuthEapolRespFramesRx": 212, +"dot1xAuthEapolReqIdFramesTx": 250, +"dot1xAuthEapolReqFramesTx": 250, +"dot1xAuthInvalidEapolFramesRx": 250, +"dot1xAuthEapLengthErrorFramesRx": 250, +"dot1xAuthLastEapolFrameVersion": 2 +} +} +] + +key = HOST_APD_STATS_TABLE : client mac; Client MAC +;field = value +dot1xAuthEapolFramesRx = 1*10DIGIT ; The number of valid EAPOL frames of any type that have been received by this Authenticator. +dot1xAuthEapolFramesTx = 1*10DIGIT ; The number of EAPOL frames of any type that have been transmitted by this Authenticator. +dot1xAuthEapolStartFramesRx = 1*10DIGIT ; The number of EAPOL Start frames that have been received by this Authenticator. +dot1xAuthEapolLogoffFramesRx = 1*10DIGIT ; The number of EAPOL Logoff frames that have been received by this Authenticator. +dot1xAuthEapolRespIdFramesRx = 1*10DIGIT ; The number of EAP Resp/Id frames that have been received by this Authenticator. +dot1xAuthEapolRes pFramesRx = 1*10DIGIT ; The number of valid EAP Response frames (other than Resp/Id frames) that have been received by this Authenticator. +dot1xAuthEapolReqIdFramesTx = 1*10DIGIT ; The number of EAP Req/Id frames that have been transmitted by this Authenticator. +dot1xAuthEapolReqFramesTx = 1*10DIGIT ; The number of EAP Request frames (other than Rq/Id frames) that have been transmitted by this Authenticator. +dot1xAuthInvalidEapolFramesRx = 1*10DIGIT ; The number of EAPOL frames that have been received by this Authenticator in which the frame type is not recognized. +dot1xAuthEapLengthErrorFramesRx = 1*10DIGIT ; The number of EAPOL frames that have been received by this Authenticator in which the Packet Body Length field is invalid. +dot1xAuthLastEapolFrameVersion = 1*10DIGIT ; The protocol version number carried in the most recently received EAPOL frame. +``` + + +### 3.2.6 State DB + +*PAC* +``` " PAC_PORT_OPER_TABLE ": { "ethernet1": { "enabled_method_list": [ @@ -436,11 +495,12 @@ None } } -auth_fail_vlan_id = 1*4DIGIT ; The Authentication Fail VLAN Id for the port. Range is 1 - 4093 -max_auth_attempts = 1DIGIT ; The maximum number of authentication retries in the event of authentication failure. Range is 1 - 5 +key = PAC_PORT_OPER_TABLE : port ; Physical port ;field = value -authentication_enable = "true"/"false" ; Indicates whether PAC is enabled in the system. -monitor_mode_enable = "true"/"false" ; Indicates whether monitor mode is enabled in the system. +enabled_method_list = "dot1x"/"mab" ; List of methods to be used for authentication +enabled_priority_list = "dot1x"/"mab" ; Relative priority of methods to be used for authentication +num_clients_authenticated = 1*2DIGIT ; Number of clients authenticated on the port. + ``` @@ -475,12 +535,137 @@ monitor_mode_enable = "true"/"false" ; Indicates whether monitor mode is enabled "current_id": 28, "auth_status": "authorized", "authenticated_method": "802.1X", -key = PAC_PORT_OPER_TABLE : port ; Physical port +"server_state": "36 34 43 50 4d 53 65 73 73 69 6f 6e 49 44 3d 30 61 38 32 62 39 37 36 4c 49 +50 5a 44 45 4d 32 74 64 35 55 39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d +6e 4a 33 31 42 6a 5a 34 51 49 3b 33 34 53 65 73 73 69 6f 6e 49 44 3d 43 69 73 63 6f 49 53 45 +2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35 3b", +"server_state_len": 106, +"server_class": "43 41 43 53 3a 30 61 38 32 62 39 37 36 4c 49 50 5a 44 45 4d 32 74 64 35 55 +39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d 6e 4a 33 31 42 6a 5a 34 51 49 +3a 43 69 73 63 6f 49 53 45 2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35", +"server_class_len": 83, +"session_timeout": 60, +"user_name": "sonic_user1", +"user_name_len": 9, +"termination_action": 0, +"vlan_id": 194, +"vlan_type": "radius", +"backend_auth_method": "radius", +"session_time": 51 +} +} +] +} + + +key = PAC_AUTHENTICATED_CLIENTS_OPER_TABLE: mac ; Client MAC address +;field = value ; +current_id = 1*3DIGIT ; EAP Packet Id +auth_status = "authorized"/"unauthorized" ; Authorization status of the client. +authenticated_method = "802.1x"/'mab" ; Method used to authenticate the client +server_state = 1*506VCHARS ; Server State used in RADIUS Challenge packets +server_state_len = 1*3DIGIT ; Server State Length +server_class = 1*506VCHARS ; Server Class used in RADIUS Access Accept packets +server_class_len = 1*3DIGIT ; Server Class Length +session_timeout = 1*10DIGIT ; Client session timeou +user_name = 1*255VCHARS ; Client user name +user_name_len = 1*3DIGIT ; Client user name length +termination_action = 1DIGIT ; Client action on session timeout: + ;0: Terminate the client + ;1: Reauthenticate the client +vlan_id = 1*4DIGIT ; VLAN associated with the authorized client +vlan_type = "RADIUS"/"Default"/"Voice"/"Critical"/"Unauthenticated"/"Guest"/"Monitor"; Type of VLANs associated with anauthorized client. + ; Default VLAN: The client has been authenticated on the port default VLAN and the authentication server is not RADIUS. + ; RADIUS: RADIUS is used for authenticating the client. + ; Voice VLAN: The client is identified as a Voice device. + ; Critical VLAN: The client has been authenticated on the Critical VLAN. + ; Unauthenticated VLAN: The client has been authenticated on the Unauthenticated VLAN. + ; Guest VLAN: The client has been authenticated on the Guest VLAN. + ; Monitor Mode: The client has been authenticated by Monitor mode. +backend_auth_method = "radius" ; Backend authentication method used to authorize the client. +session_time = 1*10DIGIT ; Client session time. + +``` + + +``` +" PAC_CLIENT_HISTORY_TABLE ": { +"ethernet1": [{ +"31-March-2021-13:46:02": { +"client_mac_addr": "00:00:00:11:22:33", +"authentication_method": "mab", +"backend_auth_method": "radius", +"auth_status": "authorized" +} +}, +{ +"31-March-2021-13:45:58": { +"client_mac_addr": "00:00:00:11:22:33", +"authentication_method": "802.1X", +"backend_auth_method": "radius", +"auth_status": "un-authorized" +} +} +] +} + + +key = PAC_CLIENT_HISTORY_TABLE : port ; Physical Port Clientmac; Client MAC address ;field = value -enabled_method_list = "dot1x"/"mab" ; List of methods to be used for authentication -enabled_priority_list = "dot1x"/"mab" ; Relative priority of methods to be used for authentication -num_clients_authenticated = 1*2DIGIT ; Number of clients authenticated on the port. +authentication_method = "802.1x"/'mab" ; Method used to authenticate the client +backend_auth_method = "radius" ; Backend authentication method used to authorize the client. +auth_status = "authorized"/"unauthorized" ; Authorization status of the client + +``` + +*hostapd* ``` +"HOSTAPD_OPER_PORT_TABLE": [{ +"ethernet1": { +"protocol_version": 2, +"quiet_period": 30, +"tx_period": 30, +"server_timeout": 45, +"max_reqs": 2, +"max_req_ids": 3 +} +}] + + + +key = HOSTAPD_OPER_PORT_TABLE : port ; Physical Port +;field = value +protocol_version = 1DIGIT ; Dot1x protocol version +quiet_period = 1*5DIGIT ; The initial value of the timer that defines the period during which the Authenticator will not attempt to authenticate the Supplicant. Range is 0-65535 seconds. +tx_period = 1*5DIGIT ; Time time interval between each EAP Request Ids sent to the supplicant. + +server_timeout = 1*5DIGIT ; RADIUS server timeout + +max_reqs = 1*5DIGIT ; Maximum number of EAP requests (except Req-Ids) to be sent to the supplicant before timing out. + +max_req_id = 1*5DIGIT ; Maximum number of EAP Req-Ids to be sent to the supplicant before timing out. +``` + +``` +"HOSTAPD_CLIENT_OPER_TABLE": { +"ethernet1": [{ +"00:00:00:11:22:33": { +"user_name": "sonic_user" +} +}, +{ +"00:00:00:11:22:55": { +"user_name": "sonic_user1" +} +} +] +} +key = HOSTAPD_OPER_PORT_TABLE : port ; Physical Port: client mac; Client MAC +;field = value +user_name = 1*255VCHARS ; Client user name +``` + + ## 3.3 Switch State Service Design @@ -855,7 +1040,14 @@ Configured actions and counters should continue to work across warm reboot. *fpinfra* -fpinfra being a shared library that provides C APIs is unit tested via a C/C++ based test utility that exercises those APIs. The unit test is build up on the google test (gtest) infrastructure. The test infra relies on the automake "make check" and gets executed during the compliation of sonic-secutity docker. +fpinfra is a shared library that provides C APIs. Its unit tested using a C/C++ based test utility that exercises these APIs in sequence. The unit test is build up on the google test (gtest) infrastructure. The test infra relies on the automake "make check" and gets executed during the compliation of sonic-secutity docker. The test code is spread into the following file/modules. +1. Semaphore API tests. +2. Task API tests +3. Linked list API tests. +4. Buffer managment API tests. +5. Tree API tests. +6. OS API tests. +7. NIM task and API tests. # 12 Appendix: Sample configuration From 7a509ec44f3febd1910bb9b4206623d0afa24742 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 5 Apr 2021 15:13:54 +0530 Subject: [PATCH 14/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 39f613741fdf..c83c0bba77ad 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1059,7 +1059,7 @@ fpinfra is a shared library that provides C APIs. Its unit tested using a C/C++ Internal BRCM information to be removed before sharing with the community. -Feature shall be supported on below mentioned platforms. +Feature shall be supported on below mentioned platforms. *AS4630* - 4 Core CPU - 8 GB RAM From 3fbb00a04859aced02dec06f6288382bfbc7e3d9 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Thu, 22 Apr 2021 10:05:02 +0530 Subject: [PATCH 15/47] changed from Netlink to Unix domain sockets --- L2/PAC/PortAccessControl.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index c83c0bba77ad..3c4263c0e0da 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -86,7 +86,7 @@ High level design document version 0.2 | Rev | Date | Author | Change Description | | ---- | ---------- | ---------| ------------------ | | 0.1 | 02/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Initial version | -| 0.2 | 04/05/2021 | Prabhu Sreenivasan | DB schema update and Review comments | +| 0.2 | 04/05/2021 | Prabhu Sreenivasan, Amitabha Sen | DB schema update and Review comments | # About this Manual This document provides general information about the Port Access Control feature in SONiC. @@ -296,14 +296,14 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ### 3.1.1 Configuration flow -![pac-config-flow](https://user-images.githubusercontent.com/45380242/112821782-bd4e6580-90a4-11eb-93bb-b453b97da456.PNG) +![pac-config-flow](https://user-images.githubusercontent.com/45380242/115655812-a91f2080-a351-11eb-9207-26dafc103d8e.PNG) **Figure 1: PAC service daemon and configuration flow** 1. Mgmt interfaces like CLI and REST writes the user provided configuration to CONFIG_DB. 2. The pacd, mabd and hostApdMgr gets notified about their respective configuration. 3. hostApd being a standard Linux application gets its configuration from hostapd.conf file. hostApdMgr makes use of Jinja2 templates to generates the hostapd.conf file based on the relevant CONFIG_DB tables. -4. Pacd gets to know about the list of ports that needs to be authenticated from PAC_PORT_CONFIG_TABLE on CONFIG_DB. The same table provides info on which ports supporrts DOT1X and which supports MAB and priority amoung the authentication methods. Based on the priority and authentication failure status, pacd decides on the list of ports to be authenticated via DOT1X and the list of ports that needs to be authenticated via MAB. It communicates the respective list of interfaces to hostApd and mabd via netlink messages. +4. Pacd gets to know about the list of ports that needs to be authenticated from PAC_PORT_CONFIG_TABLE on CONFIG_DB. The same table provides info on which ports supporrts DOT1X and which supports MAB and priority amoung the authentication methods. Based on the priority and authentication failure status, pacd decides on the list of ports to be authenticated via DOT1X and the list of ports that needs to be authenticated via MAB. It communicates the respective list of interfaces to hostApd and mabd via Unix domain socket messages. 5. hostApd listens to EAPOL PDUs on the provided interface list and proceeds to authenticate the client when it receives a PDU. mabd listens to DHCP and EAPOL PDUs on the provided interface list and proceeds to authenticate the client when it receives a PDU. @@ -311,13 +311,14 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ### 3.1.2 EAPOL receive flow -![EAPOL-receive-flow](https://user-images.githubusercontent.com/45380242/112822933-369a8800-90a6-11eb-9dfa-c8eaecbb681e.PNG) +![EAPOL-receive-flow](https://user-images.githubusercontent.com/45380242/115655906-ceac2a00-a351-11eb-9095-9d53ae549ad7.PNG) + **Figure 2: EAPOL receive flow** 1. EAPOL packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to hostApd socket listening on EtherType 0x888E on kernel interface associated with the given front panel interface. 2. In a multi-step process, hostApd runs the Dot1x state machine to Authenticate the client via RADIUS. -3. On successful authentication of a client, hostApd sends an Client Authenticated netlink message to pacd with all the authorization parameters like VLAN and DACL. +3. On successful authentication of a client, hostApd sends an Client Authenticated Unix domain socket message to pacd with all the authorization parameters like VLAN and DACL. 4. pacd proceeds to authorize the client by writing PAC_AUTHORIZE_TABLE on APPL_DB. RADIUS authorization parameters like dynamic VLAN, dynamic ACL are created by writing on their tables on STATE_DB. 5. Orchagent in SWSS docker gets notified about changes in APPL_DB and responds by translating the APPL_DB changes to respective sairedis calls. 6. Sairedis APIs write into ASIC_DB. @@ -328,14 +329,15 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ### 3.1.3 MAB PDU receive flow -![mab-pdu-receive-flow](https://user-images.githubusercontent.com/45380242/112823181-94c76b00-90a6-11eb-8a5e-19ccb525dcef.PNG) +![mab-pdu-receive-flow](https://user-images.githubusercontent.com/45380242/115655929-da97ec00-a351-11eb-90d3-a602ee2b0e3e.PNG) + **Figure 3: MAB PDU receive flow** 1. DHCP packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to pacd socket listening on the kernel interface associated with the given front panel interface. -2. Pacd sends an Client Authenticate netlink message along with the received PDU MAC. +2. Pacd sends an Client Authenticate Unix domain socket message along with the received PDU MAC. 3. mabd interacts with RADIUS server to authenticate the given client based on the MAC. -4. On successful authentication of a client, mabd sends an Client Authenticated netlink message to pacd with all the authorization parameters like VLAN and DACL. +4. On successful authentication of a client, mabd sends an Client Authenticated Unix domain socket message to pacd with all the authorization parameters like VLAN and DACL. 5. pacd proceeds to authorize the client by writing PAC_AUTHORIZE_TABLE on APPL_DB. RADIUS authorization parameters like dynamic VLAN, dynamic ACL are created by writing on their tables on STATE_DB. 6. Orchagent in SWSS docker gets notified about changes in APPL_DB and responds by translating the APPL_DB changes to respective sairedis calls. 7. Sairedis APIs write into ASIC_DB. From 4386428124a3d541411af7d1364c50a8add8b939 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Tue, 27 Apr 2021 17:31:22 +0530 Subject: [PATCH 16/47] corrected config commands --- L2/PAC/PortAccessControl.md | 399 +++++++++++++++++++++++++----------- 1 file changed, 282 insertions(+), 117 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 3c4263c0e0da..5f6ce3d464c3 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -46,19 +46,26 @@ High level design document version 0.2 - [3.6 Manageability](#36-manageability) - [3.6.1 Data Models](#361-data-models) - [3.6.2 Configuration Commands](#362-configuration-commands) - - [3.6.2.1 Config dot1x adminmode](#3621-config-dot1x-adminmode) - - [3.6.2.2 Config dot1x port initialize](#3622-config-dot1x-port-initialize) - - [3.6.2.3 Config dot1x port reauthenticate](#3623-config-dot1x-port-reauthenticate) - - [3.6.2.4 Config dot1x port controldir](#3624-config-dot1x-port-controldir) - - [3.6.2.5 Config dot1x port controlmode](#3625-config-dot1x-port-controlmode) - - [3.6.2.6 Config dot1x port quietperiod](#3626-config-dot1x-port-quietperiod) - - [3.6.2.7 Config dot1x port transmitperiod](#3627-config-dot1x-port-transmitperiod) - - [3.6.2.8 Config dot1x port supptimeout](#3628-config-dot1x-port-supptimeout) - - [3.6.2.9 Config dot1x port servertimeout](#3629-config-dot1x-port-servertimeout) - - [3.6.2.10 Config dot1x port maxrequests](#36210-config-dot1x-port-maxrequests) - - [3.6.2.11 Config dot1x port reauthperiod](#36211-config-dot1x-port-reauthperiod) - - [3.6.2.12 Config dot1x port reauthenabled](#36212-config-dot1x-port-reauthenabled) - - [3.6.2.13 Config dot1x port keytxenabled](#36213-config-dot1x-port-keytxenabled) + - [3.6.2.1 authentication enable](#3621-authentication-enable) + - [3.6.2.2 authentication critical recovery max-reauth](#3622-authentication-critical-recovery-max-reauth ) + - [3.6.2.3 authentication monitor](#3623-authentication-monitor) + - [3.6.2.4 aaa authentication pac](#3624-aaa-authentication-pac) + - [3.6.2.5 mab request format attribute 1](#3625-mab-request-format-attribute-1) + - [3.6.2.6 dot1x system-auth-control](#3626-dot1x-system-auth-control) + - [3.6.2.7 authentication event no-response action authorize vlan](#3627-authentication-event-no-response-action-authorize-vlan) + - [3.6.2.8 authentication event fail action authorize vlan](#3628-authentication-event-fail-action-authorize-vlan) + - [3.6.2.9 authentication event fail retry](#3629-authentication-event-fail-retry) + - [3.6.2.10 authentication max-users](#36210-authentication-max-users) + - [3.6.2.11 authentication periodic](#36211-authentication-periodic) + - [3.6.2.12 authentication port-control](#36212-authentication-port-control) + - [3.6.2.13 authentication host-mode](#36213-authentication-host-mode) + - [3.6.2.14 authentication timer reauthentiate](#36214-authentication-timer-reauthentiate) + - [3.6.2.15 authentication event server dead action](#36215-authentication-event-server-dead-action) + - [3.6.2.16 authentication event server dead action authorize voice](#36216-authentication-event-server-dead-action-authorize-voice) + - [3.6.2.17 authentication event server alive action reinitialize](#36217-authentication-event-server-alive-action-reinitialize) + - [3.6.2.18 authentication open](#36218-authentication-open) + - [3.6.2.19 mab](#36219-mab) + - [3.6.2.20 dot1x timeout](#36220-dot1x-timeout) - [3.6.3 Show Commands](#363-show-commands) - [3.6.3.1 Show dot1x summary](#3631-show-dot1x-summary) - [3.6.3.2 Show dot1x port summary](#3632-show-dot1x-port-summary) @@ -792,190 +799,344 @@ Since Openconfig models are not available, Openconfig dot1x and mab are propriet The following commands are used to configure PAC. +#### 3.6.2.1 authentication enable -#### 3.6.2.1 Config dot1x adminmode -This command enables or disables authentication support on the switch. The default value is disable. While disabled, the dot1x configuration is retained and can be changed, but it is not activated. -| Mode | Config | +#### 3.6.2.2 authentication critical recovery max-reauth +This command configures the number of supplicants that are re-authenticated per second. This configuration is for the entire system across all the supplicants on all ports. This is used to control the system and network load when the number of supplicants to be re-authenticated is large. These re-authentications can be triggered due to ‘reinitialize’ dead or alive server actions. + +| Mode | Global Config | | ---- | ------ | -| Syntax | config dot1x adminmode | -|Default | disable | +| Syntax | authentication critical recovery max-reauth | +| Default | 10 | | Change history | SONiC 4.0 - Introduced | - -#### 3.6.2.2 Config dot1x port initialize -This command begins the initialization sequence on the specified port. This command is only valid if the control mode for the specified port is ‘auto’. If the control mode is not ‘auto’, an error will be returned. -| Mode | Config | +#### 3.6.2.3 authentication monitor + +This command enables the Authentication monitor mode on the switch. The purpose of Monitor mode is to help troubleshoot port-based authentication configuration issues without disrupting network access for hosts connected to the switch. In Monitor mode, a host is granted network access to an authentication enforced port even if it fails the authentication process. The results of the process are logged for diagnostic purposes. + +| Mode | Global Config | | ---- | ------ | -| Syntax | config dot1x port initialize | +| Syntax | authentication monitor | +| Default | disable | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.3 Config dot1x port reauthenticate -This command begins the reauthentication sequence on the specified port. This command is only valid if the control mode for the specified port is ‘auto’. If the control mode is not ‘auto’, an error will be returned. +#### 3.6.2.4 aaa authentication pac +This command configures the authentication method for port-based access to the switch. The additional methods of authentication are used only if the previous method returns an error, not if there is an authentication failure. The possible methods are as follows: +ias. Uses the internal authentication server users database for authentication. This method can be used in conjunction with any one of the existing methods like local, radius, etc. +local. Uses the local username database for authentication. +none. Uses no authentication. +radius. Uses the list of all RADIUS servers for authentication -| Mode | Config | +| Mode | Global Config | | ---- | ------ | -| Syntax | config dot1x port reauthenticate | +| Syntax | aaa authentication pac { radius | local | none } | +| Default | radius | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.4 Config dot1x port controldir -This command configures the control direction for the specified port or ports. The control direction dictates the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). +#### 3.6.2.5 mab request format attribute 1 +This command sets configuration parameters that are used to format attribute1 for MAB requests to the RADIUS server. RADIUS attribute 1 is the username, which is often the client MAC address -| Mode | Config | +| Mode | Global Config | | ---- | ------ | -| Syntax | config dot1x port controldir | -| Default | both | +| Syntax | mab request format attribute 1 groupsize {1 | 2 | 4 | 12} separator {- | : | .} [lowercase | uppercase] | +| Default | group size=2 | +| Default | separator is : | +| Default | uppercase | | Change history | SONiC 4.0 - Introduced | - -#### 3.6.2.5 Config dot1x port controlmode -This command sets the authentication mode to be used on the specified port or ports. The control mode may be one of the following: -forceunauthorized: The authenticator PAE unconditionally sets the controlled port to unauthorized. -forceauthorized: The authenticator PAE unconditionally sets the controlled port to authorized. -auto: The authenticator PAE sets the controlled port mode to reflect the outcome of the authentication exchanges between the supplicant, authenticator, and the authentication server. +#### 3.6.2.6 dot1x system-auth-control +This command enables the dot1x authentication support on the switch. While disabled, the dot1x configuration is retained and can be changed, but is not activated. +| Mode | Global Config | +| ---- | ------ | +| Syntax | dot1x system-auth-control | +| Default | disable | +| Change history | SONiC 4.0 - Introduced | + + +#### 3.6.2.7 authentication event no-response action authorize vlan +This command configures VLAN as guest vlan on an interface or a range of interfaces. The range is 1 to the maximum VLAN ID supported by the platformor alive server actions. By default, the guest VLAN is 0, i.e. invalid and is not operational. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port controlmode | -| Default | auto | +| Syntax | authentication event no-response action authorize vlan | +| Default | 0 | | Change history | SONiC 4.0 - Introduced | - -#### 3.6.2.6 Config dot1x port quietperiod -This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. The quiet period must be a value in the range of 0 and 65535. +#### 3.6.2.8 authentication event fail action authorize vlan +This command configures the unauthenticated VLAN associated with the specified interface or range of interfaces. This VLAN is used when the AAA server fails to recognize the client credentials and rejects the authentication attempt. The unauthenticated VLAN ID can be a valid VLAN ID from 1-Maximum supported VLAN ID (4093 for FASTPATH). By default, the unauthenticated VLAN is 0, i.e. invalid and not operational. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port quietperiod <0-65535> | -| Default | 60 | +| Syntax | authentication event fail action authorize vlan | +| Default | 0 | | Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.9 authentication event fail retry +This command configures the number of times authentication may be reattempted by the client before a port moves to the authentication fail VLAN. The reattemps range is 1 to 5. +| Mode | Interface Config | +| ---- | ------ | +| Syntax | authentication event fail retry | +| Default | 3 | +| Change history | SONiC 4.0 - Introduced | -#### 3.6.2.7 Config dot1x port transmitperiod -This command sets the value, in seconds, of the timer used by the authenticator state machine on the specified port to determine when to send an EAPOL EAP Request/Identity frame to the supplicant. The transmit period must be a value in the range of 1 and 65535. +#### 3.6.2.10 authentication max-users +This command sets the maximum number of clients supported on an interface or range of interfaces when multi-authentication host mode is enabled on the port. The maximum users supported per port is dependent on the product. The count value is in the range 1 - 48. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port transmitperiod <1-65535> | -| Default | 30 | +| Syntax | authentication max-users | +| Default | 48 | | Change history | SONiC 4.0 - Introduced | - -#### 3.6.2.8 Config dot1x port supptimeout -This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to timeout the supplicant. The supplicant timeout must be a value in the range of 1 and 65535. +#### 3.6.2.11 authentication periodic +This command enables periodic reauthentication of the supplicant for the specified interface or range of interfaces. + +| Mode | Interface Config | +| ---- | ------ | +| Syntax | authentication periodic | +| Default | Disabled | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.12 authentication port-control +This command sets the authentication mode to use on the specified interface or range of interfaces. The configuration on the interface mode takes precedence over the global configuration of this parameter. + +| Mode | Interface Config | +| ---- | ------ | +| Syntax | authentication host-mode authentication port-control { auto | force-authorized | force-unauthorized } | +| Default | auto | +| Change history | SONiC 4.0 - Introduced + +#### 3.6.2.13 authentication host-mode +This command configures the host mode of a port. The configuration on the interface mode takes precedence over the global configuration of this parameter. + +| Mode | Interface Config | +| ---- | ------ | +| Syntax | authentication host-mode { multi-auth | multi-domain | multi-host | single-host | multi-domain-multi-host } | +| Default | multi-host | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.14 authentication timer reauthentiate +This command is used to configure the period of time after which the Authenticator attempts to reauthenticate a supplicant on the port. This command also provides an option to specify re-authentication time out value from the server (ex. Radius). When ‘server’ option is selected, the server supplied Session time out and Session Termination-action are used by Authenticator to reauthenticate a supplicant on the port . By default server option is enabled. The reauthenticate seconds value range is 1 to 65535. + +For reauthentication to happen after the configured or server provided timeout, the command “authentication periodic” should have enabled periodic reauthentication. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port supptimeout <1-65535>| -| Default | 30 | +| Syntax | authentication timer reauthenticate { | server} | +| Default | server | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.9 Config dot1x port servertimeout -This command sets the value, in seconds, of the timer used by the authenticator on this port to timeout the authentication server. The server timeout must be a value in the range of 1 and 65535. +#### 3.6.2.15 authentication event server dead action +This command configures the actions to take when all the authentication servers are dead. The command also configures the critical VLAN ID. If the VLAN ID is not specified, the port PVID is used as the critical VLAN ID. + +| Mode | Interface Config | +| ---- | ------ | +| Syntax | authentication event server dead action [{reinitialize | authorize}][vlan vlan-id]] | +| Default | Action: None | +| Default | VLAN: Port PVID | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.16 authentication event server dead action authorize voice +This command enables authorization of voice devices on the critical voice VLAN when all the authentication servers are dead. The configured voice VLAN of the port, on which the voice device is connected, is used as the critical voice VLAN ID. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port servertimeout <1-65535> | -| Default | 30 | +| Syntax | authentication event server dead action authorize voice | +| Default | Action: None | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.10 Config dot1x port maxrequests -This command sets the maximum number of times the authenticator state machine on this port will retransmit an EAPOL EAP Request/Identity before timing out the supplicant. The max requests value must be in the range of 1 and 10. +#### 3.6.2.17 authentication event server alive action reinitialize +This command configures the actions to take when one authentication server comes back alive after all were dead. The reinitialize action triggers the re-authentication of supplicants authenticated on the critical VLAN. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port maxrequests <1-10> | -| Default | 2 | +| Syntax | authentication event server alive action reinitialize | +| Default | Action: None | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.11 Config dot1x port reauthperiod -This command sets the value, in seconds, of the timer used by the authenticator state machine on this port to determine when reauthentication of the supplicant takes place. The reauthperiod must be a value in the range of 1 and 65535. +#### 3.6.2.18 authentication open +This command configures Open Authentication mode on the port. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port reauthperiod <1-65535> | -| Default | 3600 | +| Syntax | authentication open | +| Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.12 Config dot1x port reauthenabled -This command enables or disables reauthentication of the supplicant for the specified port. The reauthenabled value must be ‘true’ or ‘false’. If the value is ‘true’ reauthentication will occur. Otherwise, reauthentication will not be allowed. +#### 3.6.2.19 mab +This command is used to enable MAC Authentication Bypass (MAB) on an interface. MAB is a supplemental authentication mechanism that allows 802.1X unaware clients – such as printers, fax machines, and some IP phones — to authenticate to the network using the client MAC address as an identifier. However MAB can also be used to authenticate 802.1x aware clients. This command also provides options to specify the type of authentication to be used, which can be either EAP-MD5 ,PAP,CHAP. If enabled, EAP-MD5 is used by default. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port reauthenabled | -| Default | false | +| Syntax | mab [auth-type {pap | eap-md5}|chap] | +| Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.13 Config dot1x port keytxenabled -This command enables or disables key transmission to the supplicant. The keytransmissionenabled value must be ‘true’ or ‘false’. If the value is ‘true’, keys will be transmitted to the supplicant. +#### 3.6.2.20 dot1x timeout +This command sets the value, in seconds, of the timers used by the authenticator or supplicant state machines on an interface or range of interfaces. Depending on the token used and the value (in seconds) passed, various timeout configurable parameters are set. + +- quiet-period: The value, in seconds, of the timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. This is the period for which the authenticator state machine stays in the HELD state. +- tx-period: The value, in seconds, of the timer used by the authenticator state machine on this port to determine when to send an EAPOL EAP Request/Identity frame to the supplicant. +- server-timeout: The value, in seconds, of the timer used by the authenticator state machine on this port to timeout the authentication server. +- supp-timeout: The value, in seconds, of the timer used by the authenticator state machine on this port to timeout the supplicant. +- auth-period: The value, in seconds, of the timer used by the supplicant state machine on this port to timeout an authenticator when waiting for a response to packets other than EAPOL-Start. +- start-period: The value, in seconds, of the timer used by the supplicant state machine on this port to determine the interval between two successive EAPOL-Start frames when they are being retransmitted. +- held-period: The value, in seconds, of the timer used by the supplicant state machine on this port to determine the length of time it will wait before trying to send the authentication credentials again after a failed attempt. This is the period for which the supplicant state machine stays in the HELD state. -| Mode | Config | +| Mode | Interface Config | | ---- | ------ | -| Syntax | config dot1x port keytxenabled | -| Default | false | +| Syntax | dot1x timeout { quiet-period | tx-period | server-timeout | supp-timeout | auth-period | start-period | held-period } | +| Default | quiet-period: 60 seconds | +| Default | tx-period: 30 seconds | +| Default | supp-timeout: 30 seconds | +| Default | server-timeout: 30 seconds | +| Default | auth-period: 30 seconds | +| Default | start-period: 30 seconds | +| Default | held-period: 60 seconds | | Change history | SONiC 4.0 - Introduced | + ### 3.6.3 Show Commands -#### 3.6.3.1 Show dot1x summary -This command displays a summary of the global dot1x configuration. +#### 3.6.3.1 show authentication interface +This command displays the authentication manager information for the interface | Mode | Exec | | ------ | ------------------- | -| Syntax | SONiC# show dot1x summary | +| Syntax | show authentication interface {all | {interface }} | | Change history | SONiC 4.0 - Introduced | | Field | Description | | ------ | ------------------- | -| Administrative mode | Indicates if authentication control is enabled on the switch. Possible values are “Enabled” and “Disabled”. | +| Authentication Manager Status | The admin status of Authentication on the switch. This is a global configuration. | +| Interface | The interface for which authentication configuration information is being displayed. | +| Port Control Mode | The configured control mode for this port. Possible values are force-unauthorized | auto | unauthorized. | +| Host Mode | The authentication host mode configured on the interface. | +| Authentication Restart timer | The time, in seconds, after which reauthentication starts. | +| Configured method order | The order of authentication methods used on the interface. | +| Enabled method order | The order of authentication methods used on the interface. | +| Configured method priority | The priority for the authentication methods used on the interface. | +| Enabled method priority | The priority for the authentication methods used on the interface. | +| Reauthentication Period | The period after which all clients on the interface will be reauthenticated. | +| Reauthentication Enabled | Indicates whether reauthentication is enabled on the interface. | +| Maximum Users | The maximum number of clients that can be authenticated on the interface if the interface is configured as multi-auth host mode. | +| Guest VLAN ID | The VLAN id to be used to authorize clients that time out or fail authentication due to invalid credentials. This is applicable only for 802.1x unaware clients. | +| Unauthenticated VLAN ID | The VLAN id to be used to authorize clients that that time out or fail authentication due to invalid credentials. This is applicable only for 802.1x clients. | +| Critical Vlan Id | The VLAN id to be used to authorize clients that that time out due to unreachable RADIUS servers. | +| Authentication Violation Mode | The action to be taken when a security violation occurs on a port. | +| Authentication Server Dead action | The action to be undertaken for data clients when all RADIUS servers are found dead. | +| Authentication Server Dead action for Voice | The action to be undertaken for voice clients when all RADIUS servers are found dead. | +| Authentication Server Alive action | The action to be undertaken for data clients when a RADIUS server comes back alive after all were found dead. | +| Allowed protocols on unauthorized port | The action to drop or forward the particular protocol packet from and to unauthorized clients on the port | +| Open Authentication | Indicates if Open Authentication is enabled on the interface. | + +Example: +``` +show authentication interface 1/0/1 + +Authentication Manager Status.................. Enabled + +Interface...................................... 1/0/1 +Authentication Restart timer................... 300 +Configured method order........................ mab undefined undefined +Enabled method order........................... mab undefined undefined +Configured method priority..................... dot1x mab captive-portal +Enabled method priority........................ dot1x mab undefined +Reauthentication Period (secs)................. 3600 +Reauthentication Enabled....................... False +Maximum Users.................................. 48 +Guest VLAN ID..... ............................ 0 +Unauthenticated VLAN ID........................ 0 +Critical Vlan Id............................... 0 +Authentication Violation Mode.................. Restrict +Authentication Server Dead action.............. None +Authentication Server Dead action for Voice.... None +Authentication Server Alive action............. None +Allowed protocols on unauthorized port......... dhcp +Open Authentication............................ Disabled -#### 3.6.3.2 Show dot1x port summary -This command displays a summary of the dot1x configuration for a specified port or for all ports. +``` +#### 3.6.3.2 show authentication +This command displays the authentication manager information for the interface | Mode | Exec | | ------ | ------------------- | -| Syntax | show dot1x port summary | +| Syntax | show authentication | | Change history | SONiC 4.0 - Introduced | | Field | Description | | ------ | ------------------- | -| Port | The interface whose configuration is displayed in this row. | -| Control Mode | The configured control mode for this port. Possible values are “ForceUnauthorized”, “ForceAuthorized”, or “Auto”. | -| Operating Control Mode | The control mode under which this port is operating. Possible values are “Authorized” or “Unauthorized”. | -| Reauthentication Enabled | Indicates if reauthentication is enabled on this port. Possible values are “True” or “False”. | -| Key Transmission Enabled | Indicates if the key is transmitted to the supplicant for the specified port. Possible values are “True” or “False”. | +| Authentication Manager Status | The admin status of Authentication on the switch. This is a global configuration. | +| Dynamic VLAN Creation Mode | Indicates whether the switch can dynamically create a RADIUS-assigned VLAN if it does not currently exist on the switch. | +| VLAN Assignment Mode | Indicates if RADIUS assigned VLAN can be used for the Authentication Manager client or not. | +| Authentication Monitor Mode | The admin status of Monitor mode on the switch. This is a global configuration. | +| Critical Recovery Max ReAuth | Indicates the number of supplicants that are re-authenticated per second. | +| Number of Authenticated clients | The total number of clients authenticated on the switch except the ones in Monitor Mode | +| Number of clients in Monitor Mode | The number clients authorized by Monitor mode on the switch.| + +Example: +``` + #show authentication +Authentication Manager Status.................. Disabled +Dynamic Vlan Creation Mode..................... Disabled +VLAN Assignment Mode........................... Disabled +Authentication Monitor Mode.................... Disabled +Critical Recovery Max ReAuth................... 10 -#### 3.6.3.3 Show dot1x port detailed +Number of Authenticated clients................ 2 +Number of clients in Monitor mode.............. 0 + +``` + +#### 3.6.3.3 show authentication clients This command displays the details of the dot1x configuration for a specified port. | Mode | Exec | | ------ | ------------------- | -| Syntax | show dot1x port detailed | +| Syntax | show authentication clients {all | {interface }} | | Change history | SONiC 4.0 - Introduced | -| Field | Description | -| ------ | ------------------- | -| Port | The interface whose configuration is displayed | -| Protocol Version | The protocol version associated with this port. The only possible value is 1, corresponding to the first version of the dot1x specification. | -| PAE Capabilities | The PAE functionality of this port. Possible values are “Authenticator” or “Supplicant”. | -| Authenticator PAE State | Current state of the authenticator PAE state machine. Possible values are “Initialize”, “Disconnected”, “Connecting”, “Authenticating”, “Authenticated”, “Aborting”, “Held”, “ForceAuthorized”, and “ForceUnauthorized”. | -| Backend Authentication State | Current state of the backend authentication state machine. Possible values are “Request”, “Response”, “Success”, “Fail”, “Timeout”, “Idle”, and “Initialize”. | -| Quiet Period | The timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. The value is expressed in seconds and will be in the range 0 and 65535. | -| Transmit Period | The timer used by the authenticator state machine on the specified port to determine when to send an EAPOL EAP Request/Identity frame to the supplicant. The value is expressed in seconds and will be in the range of 1 and 65535. | -| Supplicant Timeout | The timer used by the authenticator state machine on this port to timeout the supplicant. . The value is expressed in seconds and will be in the range of 1 and 65535. -| Server Timeout | The timer used by the authenticator on this port to timeout the authentication server. The value is expressed in seconds and will be in the range of 1 and 65535. | -| Maximum Requests | The maximum number of times the authenticator state machine on this port will retransmit an EAPOL EAP Request/Identity before timing out the supplicant. The value will be in the range of 1 and 10. | -| Reauthentication Period | The timer used by the authenticator state machine on this port to determine when reauthentication of the supplicant takes place. The value is expressed in seconds and will be in the range of 1 and 65535. | -| Reauthentication Enabled | Indicates if reauthentication is enabled on this port. Possible values are “True” or “False”. | -| Key Transmission Enabled | Indicates if the key is transmitted to the supplicant for the specified port. Possible values are “True” or “False”. | - - - -#### 3.6.3.4 Show dot1x port stats +Example: +``` +(dhcp-10-130-86-200) #show authentication clients all + + +(dhcp-10-130-86-142) (Interface 0/10)#show authentication clients all + +Interface MAC-Address Method Host Mode Control Mode VLAN Assigned Reason +--------- ----------------- ------- ------------ ------------ -------------------------- +0/16 10:8D:B6:C6:00:00 802.1X multi-host auto RADIUS Assigned VLAN (10) + +(dhcp-10-130-86-200) #show authentication clients interface 1/0/2 + +Mac Address.................................... 58:05:94:1C:00:00 +User Name...................................... testixia +VLAN Assigned Reason........................... Voice VLAN (100) +Host Mode ..................................... multi-auth +Method......................................... 802.1X +Control Mode................................... auto +Session time ... .............................. 10 +Session timeout ............................... 100 +Time left for Session Termination Action....... 90 +Session Termination Action..................... Default +Filter-Id ..................................... None +ACS ACL Name................................... xACSACLx-IP-FP_ACL-5ee227a2 +DACL........................................... None +Redirect ACL................................... IP-REDIRECT-IN-00000001#d +Redirect URL................................... http://rtpjira.rtp.broadcom.com:8080 +Session Termination Action..................... Default +Acct SessionId:................................ testixia:200000003 + +``` + + +#### 3.6.3.4 show authentication authentication-history This command displays the dot1x statistics for a specified port. | Mode | Exec | @@ -998,10 +1159,12 @@ This command displays the dot1x statistics for a specified port. | Invalid EAPOL Frames Received | The number of EAPOL frames that have been received by this authenticator in which the frame type is not recognized. | | EAP Length Error Frames Received | The number of EAPOL frames that have been received by this authenticator in which the frame type is not recognized. | +#### 3.6.3.5 show mab +#### 3.6.3.6 show dot1x ### 3.6.4 Clear Commands -#### 3.6.4.1 Clear dot1x port stats +#### 3.6.4.1 clear authentication sessions This command resets the dot1x statistics for the specified port or for all ports. | Mode | Exec | @@ -1009,6 +1172,8 @@ This command resets the dot1x statistics for the specified port or for all ports | Syntax | clear dot1x port stats | | Change history | SONiC 4.0 - Introduced | +#### 3.6.4.2 clear dot1x statistics + # 4 Flow Diagrams # 5 Error Handling From b71e5f80030580c2948f3df955a91372f8fe9ed3 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Tue, 27 Apr 2021 18:08:53 +0530 Subject: [PATCH 17/47] update show commands --- L2/PAC/PortAccessControl.md | 126 ++++++++++++++++++++++++++++++------ 1 file changed, 105 insertions(+), 21 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 5f6ce3d464c3..19f8ce15726d 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -67,10 +67,12 @@ High level design document version 0.2 - [3.6.2.19 mab](#36219-mab) - [3.6.2.20 dot1x timeout](#36220-dot1x-timeout) - [3.6.3 Show Commands](#363-show-commands) - - [3.6.3.1 Show dot1x summary](#3631-show-dot1x-summary) - - [3.6.3.2 Show dot1x port summary](#3632-show-dot1x-port-summary) - - [3.6.3.3 Show dot1x port detailed](#3633-show-dot1x-port-detailed) - - [3.6.3.4 Show dot1x port stats](#3634-show-dot1x-port-stats) + - [3.6.3.1 show authentication interface](#3631-show-authentication-interface) + - [3.6.3.2 show authentication](#3632-show-authentication) + - [3.6.3.3 show authentication clients](#3633-show-authentication-clients) + - [3.6.3.4 show authentication authentication-history](#3634-show-authentication-authentication-history) + - [3.6.3.5 show mab](#3635-show-mab) + - [3.6.3.6 show dot1x](#3636-show-dot1x) - [3.6.4 Clear Commands](#364-clear-commands) - [3.6.4.1 Clear dot1x port stats](#364-clear-dot1x-port-stats) - **[4 Flow Diagrams](#4-flow-diagrams)** @@ -1062,7 +1064,7 @@ Open Authentication............................ Disabled ``` #### 3.6.3.2 show authentication -This command displays the authentication manager information for the interface +This command displays the authentication manager global information and the number of authenticated clients. | Mode | Exec | | ------ | ------------------- | @@ -1102,6 +1104,40 @@ This command displays the details of the dot1x configuration for a specified por | Syntax | show authentication clients {all | {interface }} | | Change history | SONiC 4.0 - Introduced | + +| Field | Description | +| ------ | ------------------- | +| Interface | The interface for which authentication configuration information is being displayed. | +| Mac Address | The MAC address of the client. | +| User Name | The user name associated with the client. | +| VLAN Assigned Reason | This can take one of the following values | +| Host Mode | The authentication host mode configured on the interface. The possible values are multi-auth, multi-domain, multi-host, single-host and multi-domain-multi-host. | +| Method | The method used to authenticate the client on the interface. The possible values are 802.1x. MAB, Captive Portal and None. | +| Control Mode | The configured control mode for this port. Possible values are force-unauthorized, auto and unauthorized. | +| Session Time | The amount of time the client session has been active. | +| Session Timeout | This value indicates the time for which the given session is valid. The time period in seconds is returned by the RADIUS server on authentication of the port. | +| Time left for Session Termination Action | This value indicates the time left for the session termination action to occur. This field is valid only when the “authentication periodic” is configured. | +| Session Termination Action | This value indicates the action to be taken once the session timeout expires. Possible values are Default and Radius-Request. If the value is Default, the session is terminated and client details are cleared. If the value is Radius-Request, then a reauthentication of the client is performed. | +| Filter ID | Identifies the Filter ID returned by the RADIUS server when the client was authenticated. This is a configured DiffServ policy name on the switch. | +| ACS ACL Name | Identifies the Downloadable ACL returned by the RADIUS server when the client was authenticated. The Downloadable ACL is the same as returned using CiscoSecure-Defined-ACL AVP.| +| DACL | Identifies the Downloadable Dynamic ACL returned by the RADIUS server when the client was authenticated. | +| Redirect-ACL | The Redirect ACL is a static ACL sent in the RADIUS attribute redirect-acl. It is used to redirect matching packets to the CPU for further action. | +| Redirect URL | The Redirect URL is a URL sent in the RADIUS attribute redirect-url. It is used by the Redirect component logic to redirect matching packets the redirect URL by using HTTP 302 response code. | +| Acct Session Id | The Accounting Session Id associated with the client session. | + + +VLAN Assigned Reason can take one of the following values: +| VLAN Assigned Reason | Description | +| ------ | ------------------- | +| Default VLAN | The client has been authenticated on the port default VLAN and the authentication server is not RADIUS. | +| RADIUS | RADIUS is used for authenticating the client. | +| Voice VLAN | The client is identified as a Voice device. | +| Critical VLAN | The client has been authenticated on the Critical VLAN | +| Unauthenticated VLAN | The client has been authenticated on the Unauthenticated VLAN. | +| Guest VLAN | The client has been authenticated on the Guest VLAN. | +| Monitor Mode | The client has been authenticated by Monitor mode. | + + Example: ``` (dhcp-10-130-86-200) #show authentication clients all @@ -1136,31 +1172,79 @@ Acct SessionId:................................ testixia:200000003 ``` + + + #### 3.6.3.4 show authentication authentication-history -This command displays the dot1x statistics for a specified port. +This command displays the authentication manager authentication history log for an interface | Mode | Exec | | ------ | ------------------- | -| Syntax | show dot1x port stats | +| Syntax | show authentication authentication-history {interface } | | Change history | SONiC 4.0 - Introduced | -| Field | Description | -| ------ | ------------------- | -| Port | The interface whose statistics are displayed. | -| EAPOL Frames Transmitted | The number of EAPOL frames of any type that have been transmitted by this authenticator. | -| EAPOL Start Frames Received | The number of EAPOL start frames that have been received by this authenticator. | -| EAPOL Logoff Frames Received | The number of EAPOL logoff frames that have been received by this authenticator. | -| Last EAPOL Frame Version | The protocol version number carried in the most recently received EAPOL frame. | -| Last EAPOL Frame Source | The source MAC address carried in the most recently received EAPOL frame. | -| EAP Response/Id Frames Received | The number of EAP response/identity frames that have been received by this authenticator. | -| EAP Response Frames Received | The number of valid EAP response frames (other than resp/id frames) that have been received by this authenticator. | -| EAP Request/Id Frames Transmitted | The number of EAP request/identity frames that have been transmitted by this authenticator. | -| EAP Request Frames Transmitted | The number of EAP request frames (other than request/identity frames) that have been transmitted by this authenticator.| -| Invalid EAPOL Frames Received | The number of EAPOL frames that have been received by this authenticator in which the frame type is not recognized. | -| EAP Length Error Frames Received | The number of EAPOL frames that have been received by this authenticator in which the frame type is not recognized. | +Example: +``` +show authentication authentication-history 1/0/2 + + +Timestamp Interface MAC-Address Auth Status Method +-------------------- --------- ----------------- ------------ ------ +May 07 2020 13:02:41 1/0/2 58:05:94:1C:00:00 Unauthorized 802.1X +May 07 2020 13:01:33 1/0/2 58:05:94:1C:00:00 Unauthorized 802.1X + +``` #### 3.6.3.5 show mab +This command is used to show a summary of the global mab configuration and summary information of the mab configuration for all ports. This command also provides the detailed mab sessions for a specified port. + +| Mode | Exec | +| ------ | ------------------- | +| Syntax | show mab { | {interface }} | +| Change history | SONiC 4.0 - Introduced | + +Example: +``` +dhcp-10-130-86-142) #show mab + +MAB Request Fmt Attr1 Groupsize... 2 +MAB Request Fmt Attr1 Separator... legacy(:) +MAB Request Fmt Attr1 Case........ uppercase + +Interface Admin Mode Auth-type --------- ----------- --------- --------------------- ------- ------------- +0/1 Disabled N/A 0/2 Disabled N/A +0/3 Disabled N/A + + +(dhcp-10-130-86-142) #show mab interface 0/10 +Interface Admin Mode Auth-type +0/10 Enabled eap-md5 + +``` + #### 3.6.3.6 show dot1x +This command is used to show a summary of the global dot1x configuration, summary information of the dot1x configuration for a specified port or all ports, the detailed dot1x configuration for a specified port and the dot1x statistics for a specified port - depending on the tokens used. + +| Mode | Exec | +| ------ | ------------------- | +| Syntax | show dot1x | +| Change history | SONiC 4.0 - Introduced | + +| Field | Description | +| ------ | ------------------- | +| Administrative Mode | Indicates whether 802.1x is enabled or disabled. | +| EAPOL Flood Mode | Indicates whether the EAPOL flood support is enabled on the switch. | +| Dot1x Software Version | The version of Dot1x implementation running on the switch. | + +Example: +``` +#show dot1x + +Administrative Mode............... Enabled +EAPOL Flood Mode.................. Disabled +Software Version.................. 1 + +``` ### 3.6.4 Clear Commands From 1d781e6c79c036612aeecc1fae341fad3354dc17 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Tue, 27 Apr 2021 18:52:13 +0530 Subject: [PATCH 18/47] updated clear command and revision history --- L2/PAC/PortAccessControl.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 19f8ce15726d..5c33584d75aa 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.2 +High level design document version 0.3 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -74,7 +74,8 @@ High level design document version 0.2 - [3.6.3.5 show mab](#3635-show-mab) - [3.6.3.6 show dot1x](#3636-show-dot1x) - [3.6.4 Clear Commands](#364-clear-commands) - - [3.6.4.1 Clear dot1x port stats](#364-clear-dot1x-port-stats) + - [3.6.4.1 clear authentication sessions](#3641-clear-authentication-sessions) + - [3.6.4.2 clear dot1x statistics](#3642-clear-dot1x-statistics) - **[4 Flow Diagrams](#4-flow-diagrams)** - **[5 Error Handling](#5-error-handling)** - **[6 Serviceability and Debug](#6-serviceability-and-debug)** @@ -96,6 +97,7 @@ High level design document version 0.2 | ---- | ---------- | ---------| ------------------ | | 0.1 | 02/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Initial version | | 0.2 | 04/05/2021 | Prabhu Sreenivasan, Amitabha Sen | DB schema update and Review comments | +| 0.3 | 04/27/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated CLI commands | # About this Manual This document provides general information about the Port Access Control feature in SONiC. @@ -1249,14 +1251,20 @@ Software Version.................. 1 ### 3.6.4 Clear Commands #### 3.6.4.1 clear authentication sessions -This command resets the dot1x statistics for the specified port or for all ports. +This command clears information for all Auth Manager sessions. All the authenticated clients are re-intialized and forced to authenticate again. | Mode | Exec | | ------ | ------------------- | -| Syntax | clear dot1x port stats | +| Syntax | clear authentication session | | Change history | SONiC 4.0 - Introduced | #### 3.6.4.2 clear dot1x statistics +This command resets the 802.1X statistics for the specified port or for all ports. + +| Mode | Exec | +| ------ | ------------------- | +| Syntax | clear dot1x statistics | +| Change history | SONiC 4.0 - Introduced | # 4 Flow Diagrams From 3e25b5455b5c5fe45300b8d1f12b35e7293da4cf Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 3 May 2021 15:22:29 +0530 Subject: [PATCH 19/47] corrected formatting issues --- L2/PAC/PortAccessControl.md | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 5c33584d75aa..a4ea947eaacc 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -116,6 +116,7 @@ This document provides general information about the Port Access Control feature | EAPOL | Extensible Authentication Protocol over LAN | | MAB | MAC Authentication Bypass| | PAC | Port Access Control | +| PAE | Port Access Entity | | RADIUS | Remote Authentication Dial In User service | | SONiC-CLI | Klish CLI used by management framework | @@ -262,7 +263,7 @@ When RADIUS authentication is used, the Authenticator basically becomes a passth The controlled directions dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control direction are of two type: 1. Both: Control is exerted over both incoming and outgoing frames. 2. In: Control is only exerted over incoming traffic. -SONiC supports on the unidirection(In) control. Please see "Limitations and Restrictions" section. +SONiC allows only unidirection(In) control. Please see "Limitations and Restrictions" section. ### 2.2.3 Downloadable ACL @@ -752,7 +753,7 @@ Upon successful authentication, the authentication methods inform Authentication Authentication Manager receives the client authorization parameters from the authentication method after successful authentication of a client. The following parameters are acted upon: -- *VLAN Id*: This is the VLAN ID sent by a RADIUS server. Authentication Manager configures the port membership accordingly so that the client traffic is associated with the VLAN. Refer [3] for further details. +- *VLAN Id*: This is the VLAN ID sent by a RADIUS server. Authentication Manager configures the port membership accordingly so that the client traffic is associated with the VLAN. - *Session Timeout*: This is the timeout attribute of the authenticated client session. - *Session Termination Action*: Upon session timeout, the Session Termination Action determines the action on the client session. The following actions are defined: - *Default*: The client session is torn down and authentication needs to be restarted for the client. @@ -835,7 +836,7 @@ radius. Uses the list of all RADIUS servers for authentication | Mode | Global Config | | ---- | ------ | -| Syntax | aaa authentication pac { radius | local | none } | +| Syntax | aaa authentication pac \{ radius \| local \| none \} | | Default | radius | | Change history | SONiC 4.0 - Introduced | @@ -844,7 +845,7 @@ This command sets configuration parameters that are used to format attribute1 fo | Mode | Global Config | | ---- | ------ | -| Syntax | mab request format attribute 1 groupsize {1 | 2 | 4 | 12} separator {- | : | .} [lowercase | uppercase] | +| Syntax | mab request format attribute 1 groupsize \{ 1 \| 2 \| 4 \| 12 \} separator \{ \- \| \: \| \. } \[ lowercase \| uppercase \] | | Default | group size=2 | | Default | separator is : | | Default | uppercase | @@ -864,7 +865,7 @@ This command configures VLAN as guest vlan on an interface or a range of interfa | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication event no-response action authorize vlan | +| Syntax | authentication event no-response action authorize vlan \ | | Default | 0 | | Change history | SONiC 4.0 - Introduced | @@ -873,7 +874,7 @@ This command configures the unauthenticated VLAN associated with the specified i | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication event fail action authorize vlan | +| Syntax | authentication event fail action authorize vlan \ | | Default | 0 | | Change history | SONiC 4.0 - Introduced | @@ -882,7 +883,7 @@ This command configures the number of times authentication may be reattempted b | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication event fail retry | +| Syntax | authentication event fail retry \ | | Default | 3 | | Change history | SONiC 4.0 - Introduced | @@ -891,7 +892,7 @@ This command sets the maximum number of clients supported on an interface or ran | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication max-users | +| Syntax | authentication max-users \ | | Default | 48 | | Change history | SONiC 4.0 - Introduced | @@ -909,7 +910,7 @@ This command sets the authentication mode to use on the specified interface or r | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication host-mode authentication port-control { auto | force-authorized | force-unauthorized } | +| Syntax | authentication host-mode authentication port-control \{ auto \| force-authorized \| force-unauthorized \} | | Default | auto | | Change history | SONiC 4.0 - Introduced @@ -918,7 +919,7 @@ This command configures the host mode of a port. The configuration on the interf | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication host-mode { multi-auth | multi-domain | multi-host | single-host | multi-domain-multi-host } | +| Syntax | authentication host-mode \{ multi-auth \| multi-domain \| multi-host \| single-host \| multi-domain-multi-host \} | | Default | multi-host | | Change history | SONiC 4.0 - Introduced | @@ -929,7 +930,7 @@ For reauthentication to happen after the configured or server provided timeout, | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication timer reauthenticate { | server} | +| Syntax | authentication timer reauthenticate \{ \ \| server \} | | Default | server | | Change history | SONiC 4.0 - Introduced | @@ -939,7 +940,7 @@ This command configures the actions to take when all the authentication servers | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication event server dead action [{reinitialize | authorize}][vlan vlan-id]] | +| Syntax | authentication event server dead action \[ \{ reinitialize \| authorize \} \] \[ vlan vlan-id \] \] | | Default | Action: None | | Default | VLAN: Port PVID | | Change history | SONiC 4.0 - Introduced | @@ -976,7 +977,7 @@ This command is used to enable MAC Authentication Bypass (MAB) on an interface. | Mode | Interface Config | | ---- | ------ | -| Syntax | mab [auth-type {pap | eap-md5}|chap] | +| Syntax | mab \[ auth-type \{ pap \| eap-md5 \} \| chap \] | | Default | Disabled | | Change history | SONiC 4.0 - Introduced | @@ -993,7 +994,7 @@ This command sets the value, in seconds, of the timers used by the authenticator | Mode | Interface Config | | ---- | ------ | -| Syntax | dot1x timeout { quiet-period | tx-period | server-timeout | supp-timeout | auth-period | start-period | held-period } | +| Syntax | dot1x timeout \{ quiet-period \| tx-period \| server-timeout \| supp-timeout \| auth-period \| start-period \| held-period \} | | Default | quiet-period: 60 seconds | | Default | tx-period: 30 seconds | | Default | supp-timeout: 30 seconds | @@ -1012,7 +1013,7 @@ This command displays the authentication manager information for the interface | Mode | Exec | | ------ | ------------------- | -| Syntax | show authentication interface {all | {interface }} | +| Syntax | show authentication interface \{ all \| \{ interface \ \} \} | | Change history | SONiC 4.0 - Introduced | | Field | Description | @@ -1103,7 +1104,7 @@ This command displays the details of the dot1x configuration for a specified por | Mode | Exec | | ------ | ------------------- | -| Syntax | show authentication clients {all | {interface }} | +| Syntax | show authentication clients \{ all \| \{ interface \ \} \} | | Change history | SONiC 4.0 - Introduced | @@ -1182,7 +1183,7 @@ This command displays the authentication manager authentication history log for | Mode | Exec | | ------ | ------------------- | -| Syntax | show authentication authentication-history {interface } | +| Syntax | show authentication authentication-history \{ interface \ \} | | Change history | SONiC 4.0 - Introduced | Example: @@ -1202,7 +1203,7 @@ This command is used to show a summary of the global mab configuration and summa | Mode | Exec | | ------ | ------------------- | -| Syntax | show mab { | {interface }} | +| Syntax | show mab \{ \ \| \{ interface \ \} \} | | Change history | SONiC 4.0 - Introduced | Example: From 32bb121cd576e9817e0acf502830a2b31934876a Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 3 May 2021 16:20:04 +0530 Subject: [PATCH 20/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index a4ea947eaacc..eb4f859fdbc6 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -13,7 +13,7 @@ High level design document version 0.3 - **[1 Feature Overview](#1-feature-overview)** - [1.1 Port Access Control](#11-port-access-control) - [1.1.1 Dot1x](#111-dot1x) - - [1.1.2 MAC Authentication Bypass](#112-mac-autentication-bypass) + - [1.1.2 MAC Authentication Bypass](#112-mac-authentication-bypass) - [1.3 Requirements](#13-requirements) - [1.3.1 Functional Requirements](#131-functional-requirements) - [1.3.2 Configuration and Management Requirements](#132-configuration-and-management-requirements) @@ -31,9 +31,9 @@ High level design document version 0.3 - [3.2 DB Changes](#32-db-changes) - [3.2.1 Config DB](#321-config-db) - [3.2.2 App DB](#322-app-db) - - [3.2.3 State DB](#323-state-db) - - [3.2.4 ASIC DB](#324-asic-db) - - [3.2.5 Counter DB](#325-counter-db) + - [3.2.3 ASIC DB](#324-asic-db) + - [3.2.4 Counter DB](#325-counter-db) + - [3.2.5 State DB](#323-state-db) - [3.3 Switch State Service Design](#33-switch-state-service-design) - [3.3.1 Orchestration Agent](#331-orchestration-agent) - [3.3.2 PAC daemons](#332-pac-daemons) @@ -217,7 +217,7 @@ Port Access Control feature should work seamlessly across warmboot. Statistics m ### 1.4.2 Container A new container sonic-security is introduced to hold all the port security applications. Apart from sonic-security container, code changes are made to SWSS, mgmt-frameowrk containers. -### 1.4.3 SAI Overview +### 1.4.3 SAI Support No changes to SAI spec for supporting PAC. # 2 Functionality @@ -436,11 +436,11 @@ dot1x_system_auth_control "true"/"false" ; Indicates whether dot1x is enabled in ### 3.2.2 App DB -### 3.2.4 ASIC DB +### 3.2.3 ASIC DB None -### 3.2.5 Counter DB +### 3.2.4 Counter DB ``` "HOST_APD_STATS_TABLE": [{ @@ -491,7 +491,7 @@ dot1xAuthLastEapolFrameVersion = 1*10DIGIT ; The protocol version number carrie ``` -### 3.2.6 State DB +### 3.2.5 State DB *PAC* ``` @@ -1273,6 +1273,9 @@ This command resets the 802.1X statistics for the specified port or for all port # 6 Serviceability and Debug +show commands will help to see if the PAC is active on a port. +All processing errors will be captured in syslog. +Debug command output will be captured as part of tech support for offline analysis. # 7 Warm Boot Support Configured actions and counters should continue to work across warm reboot. @@ -1280,6 +1283,15 @@ Configured actions and counters should continue to work across warm reboot. # 8 Scalability ## 8.1 Software scalability +The following is the support scale for Port Access Control. The following numbers are recommended numbers and are not enforced by the software. Its expected that the user will not configure beyond the recommended scale. + +| Configuration / Resource | Scale | +| ------ | ------------------- | +| ports supported by dot1x | 300 | +| ports supported by MAB | 300 | +| Clients per port | 48 | +| DACLs supported | system-limit | + # 9 Limitation From e588dfe171d18bd46265c840434dd90fd79de7c0 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Tue, 4 May 2021 14:54:16 +0530 Subject: [PATCH 21/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index eb4f859fdbc6..06f463b05848 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1325,7 +1325,23 @@ fpinfra is a shared library that provides C APIs. Its unit tested using a C/C++ **Using Sonic-CLI** - +``` +configure +authentication enable +aaa authentication dot1x default radius + +interface 1/0/1 +authentication order dot1x mab +authentication priority dot1x mab +authentication host-mode multi-auth +authentication event fail action authorize vlan 30 +authentication event no-response action authorize vlan 30 +mab +exit + +dot1x system-auth-control +exit +``` # 13 Internal Design Information From ca5ccc58d9d8ddf0b2d968e0b2bb9c748d542785 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 5 May 2021 09:53:57 +0530 Subject: [PATCH 22/47] updated "about this manual" and scope sections. --- L2/PAC/PortAccessControl.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 06f463b05848..94712be43dc8 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -100,10 +100,10 @@ High level design document version 0.3 | 0.3 | 04/27/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated CLI commands | # About this Manual -This document provides general information about the Port Access Control feature in SONiC. +This document describes the design details of the Port Access Control feature in SONiC. Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. # Scope -This document provides general information about the Port Access Control feature implementation in SONiC. +This document describes the high level design details about Port Access Control feature implementation in SONiC. # Definition / Abbreviation From c6fd14d33c73c0b48a07de8714e6bfc8d43e1b2f Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 5 May 2021 12:03:04 +0530 Subject: [PATCH 23/47] added authentication enable, order and priority commands --- L2/PAC/PortAccessControl.md | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 94712be43dc8..10c9cc667290 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -64,8 +64,10 @@ High level design document version 0.3 - [3.6.2.16 authentication event server dead action authorize voice](#36216-authentication-event-server-dead-action-authorize-voice) - [3.6.2.17 authentication event server alive action reinitialize](#36217-authentication-event-server-alive-action-reinitialize) - [3.6.2.18 authentication open](#36218-authentication-open) - - [3.6.2.19 mab](#36219-mab) - - [3.6.2.20 dot1x timeout](#36220-dot1x-timeout) + - [3.6.2.19 authentication order](#36219-authentication-order) + - [3.6.2.20 authentication priority](#36220-authentication-priority) + - [3.6.2.21 mab](#36221-mab) + - [3.6.2.22 dot1x timeout](#36222-dot1x-timeout) - [3.6.3 Show Commands](#363-show-commands) - [3.6.3.1 show authentication interface](#3631-show-authentication-interface) - [3.6.3.2 show authentication](#3632-show-authentication) @@ -805,7 +807,13 @@ Since Openconfig models are not available, Openconfig dot1x and mab are propriet The following commands are used to configure PAC. #### 3.6.2.1 authentication enable +This command enables PAC feature globally. By default the value is disabled. If enabled only, the configuration on the interface would take effect. +| Mode | Global Config | +| ---- | ------ | +| Syntax | authentication enable | +| Default | disable | +| Change history | SONiC 4.0 - Introduced | #### 3.6.2.2 authentication critical recovery max-reauth This command configures the number of supplicants that are re-authenticated per second. This configuration is for the entire system across all the supplicants on all ports. This is used to control the system and network load when the number of supplicants to be re-authenticated is large. These re-authentications can be triggered due to ‘reinitialize’ dead or alive server actions. @@ -972,7 +980,25 @@ This command configures Open Authentication mode on the port. | Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.19 mab +#### 3.6.2.19 authentication order +This command is used to set the order of authentication methods used on a port. The allowed methods to configure for SONiC are Dot1x and MAB. Ordering sets the order of methods that the switch attempts when trying to authenticate a new device connected to a port. If one method in the list is unsuccessful or timed out, the next method is atempted. Each method can only be entered once. + +| Mode | Interface Config | +| ---- | ------ | +| Syntax | authentication order \{ dot1x \[ mab \] \| mab \[ dot1x \] \} | +| Default | None | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.20 authentication priority +This command is used to set the priority for the authentication methods used on a port. The allowed methods to configure for SONiC are Dot1x and MAB. Authentication priority decides if the client, who is already authenticated, to re-authenticate with the higher-priority method when the same is received. + +| Mode | Interface Config | +| ---- | ------ | +| Syntax | authentication priority \{ dot1x \[ mab \] \| mab \[ dot1x \] \} | +| Default | None | +| Change history | SONiC 4.0 - Introduced | + +#### 3.6.2.21 mab This command is used to enable MAC Authentication Bypass (MAB) on an interface. MAB is a supplemental authentication mechanism that allows 802.1X unaware clients – such as printers, fax machines, and some IP phones — to authenticate to the network using the client MAC address as an identifier. However MAB can also be used to authenticate 802.1x aware clients. This command also provides options to specify the type of authentication to be used, which can be either EAP-MD5 ,PAP,CHAP. If enabled, EAP-MD5 is used by default. | Mode | Interface Config | @@ -981,7 +1007,7 @@ This command is used to enable MAC Authentication Bypass (MAB) on an interface. | Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.20 dot1x timeout +#### 3.6.2.22 dot1x timeout This command sets the value, in seconds, of the timers used by the authenticator or supplicant state machines on an interface or range of interfaces. Depending on the token used and the value (in seconds) passed, various timeout configurable parameters are set. - quiet-period: The value, in seconds, of the timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. This is the period for which the authenticator state machine stays in the HELD state. From f57e0fcbe12ee30b6941c9652a83a029f63fe281 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 5 May 2021 13:42:48 +0530 Subject: [PATCH 24/47] Added more details to design section. --- L2/PAC/PortAccessControl.md | 180 +++++++++++++++++++++++++++++++++++- 1 file changed, 175 insertions(+), 5 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 10c9cc667290..870198eb3673 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -41,6 +41,7 @@ High level design document version 0.3 - [3.3.2.2 Authentication Manager](#3322-authentication-manager) - [3.3.2.3 mabd](#3323-mabd) - [3.3.3 Other Process](#333-other-process) + - [3.3.4 Interaction between pacd hostapd and mabd](#334-interaction-between-pacd-hostapd-and-mabd) - [3.4 SyncD](#34-syncd) - [3.5 SAI](#35-sai) - [3.6 Manageability](#36-manageability) @@ -116,7 +117,7 @@ This document describes the high level design details about Port Access Control | CoPP | Control Plane Policing | | Dot1x | IEEE 802.1 standard | | EAPOL | Extensible Authentication Protocol over LAN | -| MAB | MAC Authentication Bypass| +| MAB | Mac-based Authentication Bypass | | PAC | Port Access Control | | PAE | Port Access Entity | | RADIUS | Remote Authentication Dial In User service | @@ -694,7 +695,7 @@ user_name = 1*255VCHARS ; Client user name #### 3.3.2.1 PAC Manager #### 3.3.2.2 Authentication Manager -Authentication Manager primarily manages the order of authentication methods during a failover scenario. Majority of authentication functionalities are managed by 802.1X. These include interaction with a AAA server, applying client authorization parameters to allow authenticated client traffic, etc. These are strictly speaking not specific to 802.1X and are applicable to any authenticated methods like MAB. +Authentication Manager in major component of pacd process. Authentication Manager primarily manages the order of authentication methods during a failover scenario. Majority of authentication functionalities are managed by hostapd(802.1X). These include interaction with a AAA server, applying client authorization parameters to allow authenticated client traffic, etc. These are strictly speaking not specific to 802.1X and are applicable to any authenticated methods like MAB. Authentication Manager allows enforcing authentication on a port. Authentication Manager needs to be enabled for the same. This is the first step to enabling port based access control. Once authentication is enabled, the port is marked Unauthorized and traffic is blocked through it. @@ -765,8 +766,160 @@ Authentication Manager receives the client authorization parameters from the aut - *Redirect ACL*: This is used to apply an ACL that traps matching packets to the CPU for redirection. It is typically used to match on HTTP packets from a client. - *Redirect URL*: This is used to specify a redirect URL and works in conjunction with the Redirect ACL. + +**Dynamic ACL attributes** + +ACL attributes from the RADIUS server can be sent using below methods: + +*Individual Cisco AVPair attributes*: +This attribute sends single or multiple Cisco AV-Pairs in the format “ip:inacl” or “ipv6:inacl” containing attribute value as IP ACL rules in Extended ACL format. It can also specify the ACL name which must be pre-configured on the switch. Only one ipv4 and one ipv6 ACL is allowed per client. + +Predefined ACL example: +``` +ip:inacl=99 +ip:inacl=Named_ACL +ipv6:inacl=Named_IPv6_ACL +Dynamic ACL example: +ip:inacl[#number]={extended-access-control-list} +ipv6:inacl[#number]={ extended-access-control-list} +``` + +*Filter-Id Attribute (locally configured ACL)*: +ACL’s sent using Filter-Id need to be pre-configured on the switch. On receiving Access-Accept packet with Filter-Id containing ACL name with direction, the specified ACL is applied on the port. This ACL can be of any type; ipv4, ipv6 or MAC. Any existing static ACLs on the port are removed and the new ACL is applied prior to authorizing the port to 802.1X. When the 802.1X session terminates, the pre-existing ACLs is restored to the port. If both a Filter-ID and a Cisco AV-Pair (26) containing a DACL are present in the Access Accept, the Access Accept is treated as an Access-Reject. + +*CiscoSecure-Defined-ACL attribute-value pair*: +This attribute uses Named ACL’s configured on the RADIUS Server. CiscoSecure-Defined-ACL attribute-value pair can be set with the RADIUS Cisco-AV-Pair vendor-specific attributes (VSAs). This pair specifies the name of the Downloadable ACL on the RADIUS server with the “ACL-Name” attribute. On receiving CiscoSecure-Defined-ACL attribute, a new Access-Request, with UserName as “ACL-Name” is sent to RADIUS server, to which RADIUS responds with Access-Accept containing Rules in the ACL Set of CiscoSecure-Defined-ACL as individual Cisco AV Pair attributes. If there is no response to the 2nd Access-Request or if an Access-Reject is received, the client is Rejected. +Individual Cisco AVPs containing individual ACL rules can be sent in Access-Accept along with CiscoSecure-Defined-ACL AVP. All the rules/ACLs are applied on the port. +Also, the rules downloaded as part of the second Access-Request are stored (cached) in a DB on the DUT till there is at least one client (on any port) using (configured with) that ACL. The “ACL-Name” has to be compliant with ACL naming convention as defined by SONiC. + +For each client session, one ACL of each type (IPv4, IPv6) is supported. Prior to applying ACL sent from RADIUS server, if any ACL’s were configured, they are removed and DACL’s are applied to the port. In case of the last session termination on a port, the removed static ACL’s are restored to the port after deleting the DACL’s. + +**ACL naming convention** + +When an ACL is installed by Authentication Manager, the following the naming convention is used. + + +| ACL type | Source | ACL name | +| -------- | ------ | -------- | +| IPv4 | Filter Id / Cisco AV Pair StaticACL | IP-STATIC-IN-\ | +| IPv6 | Filter Id / Cisco AV Pair StaticACL | IPV6-STATIC-IN-\ | +| IPv4 | Cisco AV Pair DACL | IP-DACL-IN-\ | +| IPv6 | Cisco AV Pair DACL | IPV6-DACL-IN-\ | +| IPv4 | Redirect ACL | IP-REDIRECT-IN-\ | +| IPv6 | Redirect ACL | IPV6- REDIRECT-IN-\ | +| MAC | Filter Id / Cisco AV Pair StaticACL | MAC-STATIC-IN-\ | + + +The switch UI shall prevent the operator from creating a static ACL where the name matches any of the regular expressions that can be part of the above naming conventions. + +**Authentication Manager special VLANs** + +Authentication Manager keeps trying the next configured authentication method in case authentication method fails or times out. However if the last authentication fails, Authentication Manager authorizes the client to special VLANs like Unauthenticated VLAN, Guest VLAN, or Critical VLAN. If a client is authenticated in any of these VLANs and the VLAN is reconfigured or deleted from the system, all these clients are unauthorized. + +*Unauthenticated VLAN* +This is a special VLAN which is used to authorize clients which fail authentication due to invalid credentials. This is used for 802.1X aware clients only. + +*Guest VLAN* +This is a special VLAN used to authorize 802.1X unaware clients. Refer [4] for details. + +*Critical VLAN* +Critical VLAN allows supplicants to authenticate on a Critical VLAN when all RADIUS servers are dead. The criteria to mark a server dead is documented in [8]. The dead-server (all RADIUS servers marked dead) actions are configured per port. + +*Critical Voice VLAN* +Critical Voice VLAN support allows a phone to continue port access on the Voice VLAN when all the RADIUS servers go dead. If the feature is not enabled, the phone will be disconnected. + + +**Critical VLAN processing** + +When all the configured RADIUS servers are marked Dead, the existing clients are kept intact. This is true for dead action Reinitialize/Authorize/None. Critical VLAN processing begins when either a new client tries to authenticate or re-authentication kicks in for an authorized client. + +*Critical VLAN dead action “Reinitialize”* +Pre-condition: All the configured RADIUS servers are marked Dead + +When a new client attempts to authenticate or an existing client undergoes re-authentication, the new client or the client under re-authentication is authorized into Critical Data VLAN. All the other authorized clients are terminated, with the exception of clients in Unauthenticated VLAN, Guest VLAN, Voice VLAN, Critical Data VLAN, Critical Voice VLAN, clients authorized in Monitor mode and Open mode. Terminated clients are expected to re-initiate the authentication process and they would be authorized into Critical Data VLAN once they do so. + +*Critical VLAN dead action “Authorize”* +Pre-condition: All the configured RADIUS servers are marked Dead + +When a new client attempts to authenticate or an existing client undergoes re-authentication, the new client or the client under re-authentication is authorized into Critical Data VLAN. All the other authorized clients are kept undisturbed. + +*Critical VLAN dead action “None”* +Pre-condition: All the configured RADIUS servers are marked Dead. + +When a new client attempts to authenticate or an existing client undergoes re-authentication, the new client or the client under re-authentication is not authorized and is terminated. All the other authorized clients are kept undisturbed. + +*Critical VLAN alive-server action “Reinitialize”* +When the alive-server action (one server alive after all were dead) is configured to “reinitialize”, Authentication Manager triggers the re-authentication of supplicants authorized on the Critical VLAN. + +The number of supplicants that are re-authenticated per second is configurable. This configuration is for the entire system across all the supplicants on all ports. This is used to control the system and network load when the number of supplicants to be re-authenticated is large. These re-authentications are triggered due to alive server actions. + + +**RADIUS assigned Trunk mode** + +In an 802.1X Access-Accept message, the Cisco VSA device-traffic-class=switch indicates that the connected device is capable of forwarding traffic from multiple stations using tagged and untagged traffic. + +When an Access-Accept message is received that contains the VSA device-traffic-class=switch, the switch shall: + +- if present in the Access-Accept, utilize the RADIUS assigned VLAN to set the trunk port native VLAN. If not present, the port PVID is used to set the operational trunk port native VLAN. +- Spanning-tree portfast is operationally disabled on the port. +- The port is operationally set to trunk mode using the current trunk mode configuration. + +Parsing of this VSA attribute is subject to the setting of the “radius-server vsa send authentication” command. + +It is expected that the first device to be authenticated on an interface will have the trunk mode configuration in the Access-Accept and other authentications will not have trunk mode assignment. However, subsequent authentications with trunk mode assignment shall be allowed, however, only the first trunk mode assignment is processed (including the native VLAN assignment). Additional trunk mode assignments are allowed and processed with a debug level log message "Redundant trunk mode assignment for <> ignored" + +Only the first Trunk mode native VLAN assignment received along with the first trunk mode assignment Access-Accept is processed. Typically, this will be contained in the first Access-Accept received for the port along with the trunk mode assignment, however, it need not be. Subsequent VLAN assignments - if the same as the operational PVID - are logged as a DEBUG level message "Redundant native VLAN assignment of Gi1/0/1 to VLAN P ignored" and are ignored as if the assignment was not present in the message. +Subsequent clients authenticating with a VLAN that does not match the Native VLAN/access PVID are denied access with the message (RADIUS supplied VLAN P does not match operational native VLAN Q on \. Access denied". + +The RADIUS supplied native VLAN must be configured on the switch. Dynamic VLAN creation is not supported for RADIUS supplied native VLANs for trunk mode. + +If non-switch clients are already authenticated on a port when a Trunk mode assignment is received, the existing clients are terminated. These clients are assumed to have been behind the switch whose authentication attempt resulted in a Trunk mode assignment. + +If a port is in RADIUS assigned Trunk mode, when the last 802.1X session on the port is terminated or the interface is shut down or error-disabled, the port is restored to the configuration state as it was prior to establishment of any 802.1X session. This is regardless of whether the 802.1X sessions are trunk or non-trunk. + + +**Monitor Mode** +If Monitor mode is enabled, Authentication Manager places the client in Monitor mode as applicable. + + +**Authentication History** +Authentication Manager maintains a database of authentication events. Events like “Authorized” or “Unauthorized” are recorded along with the timestamp, port number, client MAC address, and the authentication method used. + + +**Open Authentication** +The Open Authentication capability allows Authentication Manager to allow client traffic event before it authenticates. This is typically used to allow certain devices to allow access to network resources prior to authenticating to obtain IP address and download configuration or firmware upgrades. Once the information is downloaded, the device will authenticate to the network. + +Open Authentication is configured per interface. The open authentication settings are ignored for force-authorized and force-unauthorized ports. + +Open Authentication is supported for all switchport modes (access, general and trunk). It is also supported in all Authentication Manager Host modes. The number of clients that get Open access before authentication is limited by the configured host mode on the port. + +When a packet is received from a client, it is allowed access in Open mode before the authentication sequence initiates. The exception to this is when the client sends an EAP packet. In this scenario the client is not placed in Open mode immediately. We should look for the first authentication method. If it is configured as 802.1x, authentication is attempted instead. + +A client authorized in Open mode is considered a Data client and is authorized on the data VLAN of the port. A client given access in Open mode has its VLAN assigned reason as Default VLAN. Periodic re-authentication is not supported for these clients. + +A client authentication will eventually trigger based on the available and configured authentication methods on the port and on the reception of packets from the client. + +If a client fails authentication, the authentication failure actions will continue to applicable (Critical VLAN, Unauthenticated VLAN, Guest VLAN, Monitor mode etc.). If however we do not have the required configuration to authorize the client in any of these mentioned methods, the client will have access in Open mode. + +If the client succeeds authentication, the authorization parameters from RADIUS will be applied as usual. However if a DACL or Filter-Id is received, the admin configured static ACLs on the port will not be removed. These will be applied on the port prior to the statically configured ACL. This is required for subsequent clients on the port that are authorized in Open mode. The static ACL would continue to apply on the traffic as intended. + +**Inactivity Timer** +The feature is used to clean up idle data clients who have not sent any traffic for 300 seconds. The Authentication Manager Inactivity timer is a per client timer and is run when Re-authentication is not enabled for the client. +The inactivity timer has a value of 300 seconds and is not configurable. Once the inactivity timer expires, the timer handler: +- Checks the SrcHit bit for the client MAC in the hardware L2 table +- If the bit is set, it resets the bit to 0 and the timer is reloaded. +- If the bit is not set, the client entry is cleared from the Authentication Manager database and also the hardware (idle client is cleaned up) + +The above implies that although the Inactivity timer fires every 300 seconds, an idle client can get cleaned up after 300 seconds and up to 600 seconds of its inactivity. + +The feature is: +- Only applicable for clients only +- Not applicable for clients authorized in Open mode +- Applicable for clients in single-host, multi-auth and multi-domain modes + + #### 3.3.2.3 mabd -MAB is intended to provide 802.1x unaware clients controlled access to the network using the devices’ MAC address as an identifier. This requires that the known and allowable MAC address and corresponding access rights be pre-populated in the authentication server. +mabd provides the Mac-based Authentication Bypass(MAB) functionality. MAB is intended to provide 802.1x unaware clients controlled access to the network using the devices’ MAC address as an identifier. This requires that the known and allowable MAC address and corresponding access rights be pre-populated in the authentication server. Today, 802.1x has become the recommended port-based authentication method at the access layer in enterprise networks. However, there may be 802.1x unaware devices such as printers, fax-machines etc that would require access to the network without 802.1x authentication. MAB is a supplemental authentication mechanism to allow 802.1x unaware clients to authenticate to the network. SONiC supported authentication methods are as below: - CHAP @@ -791,6 +944,23 @@ The authentication server checks its pre-populated database for the authorized M No change to other process. +### 3.3.4 Interaction between pacd hostapd and mabd + +*hostapd(802.1X)* + +hostapd(802.1x) comes to know of an 802.1x client attempting authentication via an EAP exchange. It informs pacd(Authentication Manager) of this client by conveying the client MAC. If the authentication method selected by pacd(Authentication Manager) is 802.1X, pacd(Authentication Manager) sends an event to hostapd(802.1X) for authenticating the user. + +hostapd(802.1X) informs pacd(Authentication Manager) about the result of the authentication. hostapd(802.1X) also passes all the authorization parameters it receives from an AAA Server to the pacd(Authentication Manager). These are used for configuring the NAS to allow authenticated client traffic. + +*mabd(MAB)* + +When user or client tries to authenticate and the method selected is MAB, the pacd(Authentication Manager) sends an event to mabd(MAB) for authenticating the user. The client’s MAC address is sent to mabd(MAB) for the same. + +pacd(Authentication Manager) learns client’s MAC address through an hardware rule to copy-to-CPU the packets from unknown source MAC addresses. + +mabd(MAB) informs pacd(Authentication Manager) about the result of the authentication. mabd(MAB) also passes all the authorization parameters it receives from an AAA Server to the pacd(Authentication Manager). These are used for configuring the NAS to allow authenticated client traffic. + + ## 3.4 SyncD No changes to SyncD. @@ -927,7 +1097,7 @@ This command configures the host mode of a port. The configuration on the interf | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication host-mode \{ multi-auth \| multi-domain \| multi-host \| single-host \| multi-domain-multi-host \} | +| Syntax | authentication host-mode \{ multi-auth \| multi-domain \| multi-host \| single-host \} | | Default | multi-host | | Change history | SONiC 4.0 - Introduced | @@ -1140,7 +1310,7 @@ This command displays the details of the dot1x configuration for a specified por | Mac Address | The MAC address of the client. | | User Name | The user name associated with the client. | | VLAN Assigned Reason | This can take one of the following values | -| Host Mode | The authentication host mode configured on the interface. The possible values are multi-auth, multi-domain, multi-host, single-host and multi-domain-multi-host. | +| Host Mode | The authentication host mode configured on the interface. The possible values are multi-auth, multi-domain, multi-host and single-host. | | Method | The method used to authenticate the client on the interface. The possible values are 802.1x. MAB, Captive Portal and None. | | Control Mode | The configured control mode for this port. Possible values are force-unauthorized, auto and unauthorized. | | Session Time | The amount of time the client session has been active. | From e7b4e7e832f5d4f0f164187ac7809409b5b88626 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 5 May 2021 14:47:03 +0530 Subject: [PATCH 25/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 870198eb3673..d54f924268e2 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -695,7 +695,7 @@ user_name = 1*255VCHARS ; Client user name #### 3.3.2.1 PAC Manager #### 3.3.2.2 Authentication Manager -Authentication Manager in major component of pacd process. Authentication Manager primarily manages the order of authentication methods during a failover scenario. Majority of authentication functionalities are managed by hostapd(802.1X). These include interaction with a AAA server, applying client authorization parameters to allow authenticated client traffic, etc. These are strictly speaking not specific to 802.1X and are applicable to any authenticated methods like MAB. +Authentication Manager is the major component of pacd process. Authentication Manager primarily manages the order of authentication methods during a failover scenario. Majority of authentication functionalities are managed by hostapd(802.1X). These include interaction with a AAA server, applying client authorization parameters to allow authenticated client traffic, etc. These are strictly speaking not specific to 802.1X and are applicable to any authenticated methods like MAB. Authentication Manager allows enforcing authentication on a port. Authentication Manager needs to be enabled for the same. This is the first step to enabling port based access control. Once authentication is enabled, the port is marked Unauthorized and traffic is blocked through it. From ec11e4cf22c991d6d781a7ee226a8332080aa705 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 5 May 2021 16:07:15 +0530 Subject: [PATCH 26/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index d54f924268e2..88ebe1c503bd 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1485,8 +1485,9 @@ The following is the support scale for Port Access Control. The following number | ------ | ------------------- | | ports supported by dot1x | 300 | | ports supported by MAB | 300 | -| Clients per port | 48 | -| DACLs supported | system-limit | +| authentication history entries | 1024 | +| authentication history entries per interface | 20 | +| clients that can be authorized on a port configured in Multi-Auth host mode | 48 | # 9 Limitation From f696114864ce12b181a1cb59dd5c38de087411dd Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Thu, 6 May 2021 17:29:28 +0530 Subject: [PATCH 27/47] diagrams for deployment and pacd process internals. --- L2/PAC/PortAccessControl.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 88ebe1c503bd..e7757d721c95 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -229,8 +229,9 @@ No changes to SAI spec for supporting PAC. When a client authenticates itself initially on the network, the Switch acts as the authenticator to the clients on the network and forwards the authentication request to the Radius server in the network. If the authentication succeeds then the client is placed in authorized state and the client is able to forward or receive traffic through the port. -If the vlan assignment is enabled in the Radius server, then as part of the response message, Radius server sends the vlan id the client is supposed to be in the 802.1x tunnel attributes. This implies that the client can connect from any port and can get assigned to the appropriate vlan that it is supposed to be in; this is configured in the radius server. This gives flexibility for the clients to move around the network with out much configuration need to be done by the administrator. - +If the vlan assignment is enabled in the Radius server, then as part of the response message, Radius server sends the vlan id the client is supposed to be in the 802.1x tunnel attributes. This implies that the client can connect from any port and can get assigned to the appropriate vlan that it is supposed to be in; this is configured in the radius server. This gives flexibility for the clients to move around the network without much configuration need to be done by the administrator. +![pac-deployment](https://user-images.githubusercontent.com/45380242/117288373-0efac480-ae89-11eb-9f00-985c431a8b7f.PNG) +**Figure : PAC target deployment use cases** ## 2.2 Functional Description @@ -695,6 +696,11 @@ user_name = 1*255VCHARS ; Client user name #### 3.3.2.1 PAC Manager #### 3.3.2.2 Authentication Manager +pacd process links with FASTPATH components libfpinfra.so and libauthmgr.so for the infrastructure and authentication manager functionality respectvely. Below picture depicts the interal details of the pacd process. + +![pacd](https://user-images.githubusercontent.com/45380242/117293455-05745b00-ae8f-11eb-9c36-f7986b0179cf.PNG) +**Figure 4: pacd process internals** + Authentication Manager is the major component of pacd process. Authentication Manager primarily manages the order of authentication methods during a failover scenario. Majority of authentication functionalities are managed by hostapd(802.1X). These include interaction with a AAA server, applying client authorization parameters to allow authenticated client traffic, etc. These are strictly speaking not specific to 802.1X and are applicable to any authenticated methods like MAB. Authentication Manager allows enforcing authentication on a port. Authentication Manager needs to be enabled for the same. This is the first step to enabling port based access control. Once authentication is enabled, the port is marked Unauthorized and traffic is blocked through it. From 907376256b46741c28643fe2302b72a153da7394 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Thu, 6 May 2021 17:39:31 +0530 Subject: [PATCH 28/47] corrected figure numbers --- L2/PAC/PortAccessControl.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index e7757d721c95..b9cf0a12adad 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -31,9 +31,9 @@ High level design document version 0.3 - [3.2 DB Changes](#32-db-changes) - [3.2.1 Config DB](#321-config-db) - [3.2.2 App DB](#322-app-db) - - [3.2.3 ASIC DB](#324-asic-db) - - [3.2.4 Counter DB](#325-counter-db) - - [3.2.5 State DB](#323-state-db) + - [3.2.3 ASIC DB](#323-asic-db) + - [3.2.4 Counter DB](#324-counter-db) + - [3.2.5 State DB](#325-state-db) - [3.3 Switch State Service Design](#33-switch-state-service-design) - [3.3.1 Orchestration Agent](#331-orchestration-agent) - [3.3.2 PAC daemons](#332-pac-daemons) @@ -229,9 +229,12 @@ No changes to SAI spec for supporting PAC. When a client authenticates itself initially on the network, the Switch acts as the authenticator to the clients on the network and forwards the authentication request to the Radius server in the network. If the authentication succeeds then the client is placed in authorized state and the client is able to forward or receive traffic through the port. -If the vlan assignment is enabled in the Radius server, then as part of the response message, Radius server sends the vlan id the client is supposed to be in the 802.1x tunnel attributes. This implies that the client can connect from any port and can get assigned to the appropriate vlan that it is supposed to be in; this is configured in the radius server. This gives flexibility for the clients to move around the network without much configuration need to be done by the administrator. -![pac-deployment](https://user-images.githubusercontent.com/45380242/117288373-0efac480-ae89-11eb-9f00-985c431a8b7f.PNG) -**Figure : PAC target deployment use cases** +If the vlan assignment is enabled in the Radius server, then as part of the response message, Radius server sends the vlan id the client is supposed to be in the 802.1x tunnel attributes. This implies that the client can connect from any port and can get assigned to the appropriate vlan that it is supposed to be in; this is configured in the radius server. This gives flexibility for the clients to move around the network without much configuration need to be done by the administrator. + +![pac-deployment](https://user-images.githubusercontent.com/45380242/117295415-7157c300-ae91-11eb-99fb-6415ce79fe44.PNG) + + +**Figure 1 : PAC target deployment use cases** ## 2.2 Functional Description @@ -308,13 +311,13 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ## 3.1 Overview -[Figure 1](#pac-config-flow) shows the high level design overview of PAC services in SONiC. PAC Services Daemon is composed of multiple sub-modules. The main module i.e. PAC daemon handles the authentication related commands and makes use of hostApd and mabd daemons to authenticate a client via dot1x and mab respectively. hostApd being a standard Linux application takes hostapd.conf as its config file. hostApdMgr takes care of listening to dot1x specific configuration and translating them to respective hostapd.conf file config entries. pacd daemon being the main module decides which authentication protocol needs to be used for a given port and also calls APIs to program the polices in hardware. +[Figure 2](#pac-config-flow) shows the high level design overview of PAC services in SONiC. PAC Services Daemon is composed of multiple sub-modules. The main module i.e. PAC daemon handles the authentication related commands and makes use of hostApd and mabd daemons to authenticate a client via dot1x and mab respectively. hostApd being a standard Linux application takes hostapd.conf as its config file. hostApdMgr takes care of listening to dot1x specific configuration and translating them to respective hostapd.conf file config entries. pacd daemon being the main module decides which authentication protocol needs to be used for a given port and also calls APIs to program the polices in hardware. ### 3.1.1 Configuration flow ![pac-config-flow](https://user-images.githubusercontent.com/45380242/115655812-a91f2080-a351-11eb-9207-26dafc103d8e.PNG) -**Figure 1: PAC service daemon and configuration flow** +**Figure 2: PAC service daemon and configuration flow** 1. Mgmt interfaces like CLI and REST writes the user provided configuration to CONFIG_DB. 2. The pacd, mabd and hostApdMgr gets notified about their respective configuration. @@ -330,7 +333,7 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ![EAPOL-receive-flow](https://user-images.githubusercontent.com/45380242/115655906-ceac2a00-a351-11eb-9095-9d53ae549ad7.PNG) -**Figure 2: EAPOL receive flow** +**Figure 3: EAPOL receive flow** 1. EAPOL packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to hostApd socket listening on EtherType 0x888E on kernel interface associated with the given front panel interface. 2. In a multi-step process, hostApd runs the Dot1x state machine to Authenticate the client via RADIUS. @@ -348,7 +351,7 @@ traffic for the client must still get dropped. To achieve the same, PAC installs ![mab-pdu-receive-flow](https://user-images.githubusercontent.com/45380242/115655929-da97ec00-a351-11eb-90d3-a602ee2b0e3e.PNG) -**Figure 3: MAB PDU receive flow** +**Figure 4: MAB PDU receive flow** 1. DHCP packet is received by hardware on a front panel interface and trapped to CPU. The packet gets thru the KNET driver and Linux Network Stack and eventually gets delivered to pacd socket listening on the kernel interface associated with the given front panel interface. 2. Pacd sends an Client Authenticate Unix domain socket message along with the received PDU MAC. @@ -699,7 +702,7 @@ user_name = 1*255VCHARS ; Client user name pacd process links with FASTPATH components libfpinfra.so and libauthmgr.so for the infrastructure and authentication manager functionality respectvely. Below picture depicts the interal details of the pacd process. ![pacd](https://user-images.githubusercontent.com/45380242/117293455-05745b00-ae8f-11eb-9c36-f7986b0179cf.PNG) -**Figure 4: pacd process internals** +**Figure 5: pacd process internals** Authentication Manager is the major component of pacd process. Authentication Manager primarily manages the order of authentication methods during a failover scenario. Majority of authentication functionalities are managed by hostapd(802.1X). These include interaction with a AAA server, applying client authorization parameters to allow authenticated client traffic, etc. These are strictly speaking not specific to 802.1X and are applicable to any authenticated methods like MAB. From 3bbcb0131a990959104bc80a077e0a5f7e82a62f Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Thu, 6 May 2021 22:31:47 +0530 Subject: [PATCH 29/47] updated flow diagram and Error handling section --- L2/PAC/PortAccessControl.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index b9cf0a12adad..3059d9a2f715 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1473,14 +1473,15 @@ This command resets the 802.1X statistics for the specified port or for all port | Change history | SONiC 4.0 - Introduced | # 4 Flow Diagrams +The flow diagrams Figure 2: PAC service daemon and configuration flow, Figure 3: EAPOL receive flow, Figure 4: MAB PDU receive flow; indicates the sequence of events involved in processing of PAC configuration and EAPOL/MAB packets. # 5 Error Handling - +N/A # 6 Serviceability and Debug -show commands will help to see if the PAC is active on a port. -All processing errors will be captured in syslog. -Debug command output will be captured as part of tech support for offline analysis. +show commands will help to see if the PAC is active on a port. +All processing errors will be captured in syslog. +Debug command output will be captured as part of tech support for offline analysis. # 7 Warm Boot Support Configured actions and counters should continue to work across warm reboot. From 1772e7dda9de7a0b4ae765770c02237c63e82e4b Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Fri, 7 May 2021 10:44:11 +0530 Subject: [PATCH 30/47] rearranged swss design section. --- L2/PAC/PortAccessControl.md | 69 ++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 27 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 3059d9a2f715..8f1975481c26 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -36,12 +36,25 @@ High level design document version 0.3 - [3.2.5 State DB](#325-state-db) - [3.3 Switch State Service Design](#33-switch-state-service-design) - [3.3.1 Orchestration Agent](#331-orchestration-agent) - - [3.3.2 PAC daemons](#332-pac-daemons) - - [3.3.2.1 PAC Manager](#3321-pac-manager) - - [3.3.2.2 Authentication Manager](#3322-authentication-manager) - - [3.3.2.3 mabd](#3323-mabd) - - [3.3.3 Other Process](#333-other-process) - - [3.3.4 Interaction between pacd hostapd and mabd](#334-interaction-between-pacd-hostapd-and-mabd) + - [3.3.2 pacd](#332-pacd) + - [3.3.2.1 Authentication Manager port modes](#3321-authentication-manager-port-modes) + - [3.3.2.2 Authentication Manager port host modes](#3322-authentication-manager-port-host-modes) + - [3.3.2.3 Authentication Manager Authentication method fallback and priorities](#3323-authentication-manager-authentication-method-fallback-and-priorities) + - [3.3.2.4 Authorization parameters](#3324-authorization-parameters) + - [3.3.2.5 Dynamic ACL attributes](#3325-dynamic-acl-attributes) + - [3.3.2.6 ACL naming convention](#3326-acl-naming-convention) + - [3.3.2.7 Authentication Manager special VLANs](#3327-authentication-manager-special-vlans) + - [3.3.2.8 Critical VLAN processing](#3328-critical-vlan-processing) + - [3.3.2.9 RADIUS assigned Trunk mode](#3329-radius-assigned-trunk-mode) + - [3.3.2.10 Monitor Mode](#33210-monitor-mode) + - [3.3.2.11 Authentication History](#33211-authentication-history) + - [3.3.2.12 Open Authentication](#33212-open-authentication) + - [3.3.2.13 Inactivity Timer](#33213-inactivity-timer) + - [3.3.3 mabd](#333-mabd) + - [3.3.4 hostapd](#334-hostapd) + - [3.3.5 pacmgr](#335-pacmgr) + - [3.3.6 Other Process](#336-other-process) + - [3.3.7 Interaction between pacd hostapd and mabd](#337-interaction-between-pacd-hostapd-and-mabd) - [3.4 SyncD](#34-syncd) - [3.5 SAI](#35-sai) - [3.6 Manageability](#36-manageability) @@ -694,16 +707,13 @@ user_name = 1*255VCHARS ; Client user name #### 3.3.1.1 PAC Orchestration agent -### 3.3.2 PAC daemons - -#### 3.3.2.1 PAC Manager - -#### 3.3.2.2 Authentication Manager +### 3.3.2 pacd pacd process links with FASTPATH components libfpinfra.so and libauthmgr.so for the infrastructure and authentication manager functionality respectvely. Below picture depicts the interal details of the pacd process. ![pacd](https://user-images.githubusercontent.com/45380242/117293455-05745b00-ae8f-11eb-9c36-f7986b0179cf.PNG) **Figure 5: pacd process internals** +**Authentication Manager** Authentication Manager is the major component of pacd process. Authentication Manager primarily manages the order of authentication methods during a failover scenario. Majority of authentication functionalities are managed by hostapd(802.1X). These include interaction with a AAA server, applying client authorization parameters to allow authenticated client traffic, etc. These are strictly speaking not specific to 802.1X and are applicable to any authenticated methods like MAB. Authentication Manager allows enforcing authentication on a port. Authentication Manager needs to be enabled for the same. This is the first step to enabling port based access control. Once authentication is enabled, the port is marked Unauthorized and traffic is blocked through it. @@ -720,7 +730,7 @@ Authentication Manager allows configuring priority for each authentication metho After successful authentication, the authentication method returns the Authorization parameters for the client. Authentication Manager uses these parameters for configuring the switch for allowing traffic for authenticated clients. -**Authentication Manager port modes** +#### 3.3.2.1 Authentication Manager port modes *Auto* This mode is used to enforce authentication on a port. The port is unauthorized and blocked for traffic unless a client is authenticated. @@ -732,7 +742,7 @@ This mode is used to disable authentication on a port. All client traffic is all This mode is used to un-authorize a port and block any client traffic -**Authentication Manager port host modes** +#### 3.3.2.2 Authentication Manager port host modes *Single-Host mode* In this mode only one data client can be authenticated on a port and the client is granted access to the port. Access is allowed only for this client and no one else. Only when this client logs off, can another client get authenticated and authorized on the port and granted port access. @@ -746,7 +756,7 @@ In this mode one data client and one voice client can be authenticated on a port *Multiple Authentication mode* In this mode one voice client and multiple data clients can be authenticated on a port and these clients are then granted access. Typical use case is a network of laptops and an IP phone connected to the NAS port via a hub. -**Authentication Manager Authentication method fallback and priorities** +#### 3.3.2.3 Authentication Manager Authentication method fallback and priorities Authentication manager controls the order in which the authentication methods are executed. Authentication manager does not make any required configuration for the respective methods to authenticate successfully. User or Administrator needs to ensure that the correct and appropriate configuration is present in the system. Using the Authentication manager, user can configure an authentication method fallback list, which is configured per port. If authentication using any of the method fails, then authentication of the client on the port is tried using the next or subsequent methods. @@ -759,7 +769,7 @@ Authentication manager allows user to modify the default method priorities using If administrator changes the priority of the methods, then all the users who are authenticated using a lower priority method will be forced to re-authenticate. If an authentication session is in progress and administrator changes the order of the authentication methods then the configuration will take effect for the next session onwards. -**Authorization parameters** +#### 3.3.2.4 Authorization parameters Upon successful authentication, the authentication methods inform Authentication Manager about the result. Authentication Manager then authorizes the port and configures it for allowing traffic from the client. @@ -776,7 +786,7 @@ Authentication Manager receives the client authorization parameters from the aut - *Redirect URL*: This is used to specify a redirect URL and works in conjunction with the Redirect ACL. -**Dynamic ACL attributes** +#### 3.3.2.5 Dynamic ACL attributes ACL attributes from the RADIUS server can be sent using below methods: @@ -803,7 +813,7 @@ Also, the rules downloaded as part of the second Access-Request are stored (cach For each client session, one ACL of each type (IPv4, IPv6) is supported. Prior to applying ACL sent from RADIUS server, if any ACL’s were configured, they are removed and DACL’s are applied to the port. In case of the last session termination on a port, the removed static ACL’s are restored to the port after deleting the DACL’s. -**ACL naming convention** +#### 3.3.2.6 ACL naming convention When an ACL is installed by Authentication Manager, the following the naming convention is used. @@ -821,7 +831,7 @@ When an ACL is installed by Authentication Manager, the following the naming con The switch UI shall prevent the operator from creating a static ACL where the name matches any of the regular expressions that can be part of the above naming conventions. -**Authentication Manager special VLANs** +#### 3.3.2.7 Authentication Manager special VLANs Authentication Manager keeps trying the next configured authentication method in case authentication method fails or times out. However if the last authentication fails, Authentication Manager authorizes the client to special VLANs like Unauthenticated VLAN, Guest VLAN, or Critical VLAN. If a client is authenticated in any of these VLANs and the VLAN is reconfigured or deleted from the system, all these clients are unauthorized. @@ -838,7 +848,7 @@ Critical VLAN allows supplicants to authenticate on a Critical VLAN when all RAD Critical Voice VLAN support allows a phone to continue port access on the Voice VLAN when all the RADIUS servers go dead. If the feature is not enabled, the phone will be disconnected. -**Critical VLAN processing** +#### 3.3.2.8 Critical VLAN processing When all the configured RADIUS servers are marked Dead, the existing clients are kept intact. This is true for dead action Reinitialize/Authorize/None. Critical VLAN processing begins when either a new client tries to authenticate or re-authentication kicks in for an authorized client. @@ -863,7 +873,7 @@ When the alive-server action (one server alive after all were dead) is configure The number of supplicants that are re-authenticated per second is configurable. This configuration is for the entire system across all the supplicants on all ports. This is used to control the system and network load when the number of supplicants to be re-authenticated is large. These re-authentications are triggered due to alive server actions. -**RADIUS assigned Trunk mode** +#### 3.3.2.9 RADIUS assigned Trunk mode In an 802.1X Access-Accept message, the Cisco VSA device-traffic-class=switch indicates that the connected device is capable of forwarding traffic from multiple stations using tagged and untagged traffic. @@ -887,15 +897,15 @@ If non-switch clients are already authenticated on a port when a Trunk mode assi If a port is in RADIUS assigned Trunk mode, when the last 802.1X session on the port is terminated or the interface is shut down or error-disabled, the port is restored to the configuration state as it was prior to establishment of any 802.1X session. This is regardless of whether the 802.1X sessions are trunk or non-trunk. -**Monitor Mode** +#### 3.3.2.10 Monitor Mode If Monitor mode is enabled, Authentication Manager places the client in Monitor mode as applicable. -**Authentication History** +#### 3.3.2.11 Authentication History Authentication Manager maintains a database of authentication events. Events like “Authorized” or “Unauthorized” are recorded along with the timestamp, port number, client MAC address, and the authentication method used. -**Open Authentication** +#### 3.3.2.12 Open Authentication The Open Authentication capability allows Authentication Manager to allow client traffic event before it authenticates. This is typically used to allow certain devices to allow access to network resources prior to authenticating to obtain IP address and download configuration or firmware upgrades. Once the information is downloaded, the device will authenticate to the network. Open Authentication is configured per interface. The open authentication settings are ignored for force-authorized and force-unauthorized ports. @@ -912,7 +922,7 @@ If a client fails authentication, the authentication failure actions will contin If the client succeeds authentication, the authorization parameters from RADIUS will be applied as usual. However if a DACL or Filter-Id is received, the admin configured static ACLs on the port will not be removed. These will be applied on the port prior to the statically configured ACL. This is required for subsequent clients on the port that are authorized in Open mode. The static ACL would continue to apply on the traffic as intended. -**Inactivity Timer** +#### 3.3.2.13 Inactivity Timer The feature is used to clean up idle data clients who have not sent any traffic for 300 seconds. The Authentication Manager Inactivity timer is a per client timer and is run when Re-authentication is not enabled for the client. The inactivity timer has a value of 300 seconds and is not configurable. Once the inactivity timer expires, the timer handler: - Checks the SrcHit bit for the client MAC in the hardware L2 table @@ -927,7 +937,7 @@ The feature is: - Applicable for clients in single-host, multi-auth and multi-domain modes -#### 3.3.2.3 mabd +#### 3.3.3 mabd mabd provides the Mac-based Authentication Bypass(MAB) functionality. MAB is intended to provide 802.1x unaware clients controlled access to the network using the devices’ MAC address as an identifier. This requires that the known and allowable MAC address and corresponding access rights be pre-populated in the authentication server. Today, 802.1x has become the recommended port-based authentication method at the access layer in enterprise networks. However, there may be 802.1x unaware devices such as printers, fax-machines etc that would require access to the network without 802.1x authentication. MAB is a supplemental authentication mechanism to allow 802.1x unaware clients to authenticate to the network. SONiC supported authentication methods are as below: @@ -948,12 +958,17 @@ If authentication type is configured as CHAP, a randomly generated 16-octet chal The authentication server checks its pre-populated database for the authorized Mac addresses and returns an ‘Access-Accept’ or an ‘Access-Reject’ depending on if the Mac address has been found in the database. This also makes it possible for the client to be placed in a RADIUS assigned VLAN or apply a specific Filter ID to the client traffic. +### 3.3.4 hostapd +Hostapd application supplied with wpa_supplicant is an open source implementation of 802.1x standard. The wired driver module of hostapd is adapted to write information to SONiC DB instead of directly controlling the interfaces. This driver also takes care of interacting with pacd via socket interface. hostapd gets its configuration from the hostapd.conf file generated by SONiC system. + +### 3.3.5 pacmgr +pacmgr aids standard Linux application hostapd to read its relevant configuration from SONiC DBs, populate the hostapd.conf and restart hostapd. -### 3.3.3 Other Process +### 3.3.6 Other Process No change to other process. -### 3.3.4 Interaction between pacd hostapd and mabd +### 3.3.7 Interaction between pacd hostapd and mabd *hostapd(802.1X)* From ba95a8458b0fa3fa63ba8ff2812deb40a9ef62bf Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Fri, 7 May 2021 12:24:55 +0530 Subject: [PATCH 31/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 89 +++++++++---------------------------- 1 file changed, 20 insertions(+), 69 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 8f1975481c26..89b085dfcf72 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -45,14 +45,12 @@ High level design document version 0.3 - [3.3.2.6 ACL naming convention](#3326-acl-naming-convention) - [3.3.2.7 Authentication Manager special VLANs](#3327-authentication-manager-special-vlans) - [3.3.2.8 Critical VLAN processing](#3328-critical-vlan-processing) - - [3.3.2.9 RADIUS assigned Trunk mode](#3329-radius-assigned-trunk-mode) - - [3.3.2.10 Monitor Mode](#33210-monitor-mode) - - [3.3.2.11 Authentication History](#33211-authentication-history) - - [3.3.2.12 Open Authentication](#33212-open-authentication) - - [3.3.2.13 Inactivity Timer](#33213-inactivity-timer) + - [3.3.2.9 Monitor Mode](#3329-monitor-mode) + - [3.3.2.10 Authentication History](#33210-authentication-history) + - [3.3.2.11 Open Authentication](#33211-open-authentication) - [3.3.3 mabd](#333-mabd) - [3.3.4 hostapd](#334-hostapd) - - [3.3.5 pacmgr](#335-pacmgr) + - [3.3.5 hostapd](#335-hostapdmgr) - [3.3.6 Other Process](#336-other-process) - [3.3.7 Interaction between pacd hostapd and mabd](#337-interaction-between-pacd-hostapd-and-mabd) - [3.4 SyncD](#34-syncd) @@ -114,6 +112,7 @@ High level design document version 0.3 | 0.1 | 02/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Initial version | | 0.2 | 04/05/2021 | Prabhu Sreenivasan, Amitabha Sen | DB schema update and Review comments | | 0.3 | 04/27/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated CLI commands | +| 0.4 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated desgin section | # About this Manual This document describes the design details of the Port Access Control feature in SONiC. Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. @@ -782,8 +781,6 @@ Authentication Manager receives the client authorization parameters from the aut - *RADIUS*: Re-authentication is initiated for the client. - *Filter-Id*: Specifies an ACL of Diffserv policy name. This is used to apply a Static ACL or DiffServ policy on the port for the client. IPv4 and IPv6 ACLs in the “IN” direction is supported. If the Differv policy or ACL is not present in the system, or if a Diffserv policy is already configured on the port, authentication for the client is rejected. These are subject to Monitor Mode configuration. Filter-Id is supported on all Authentication Manager host modes. - *Downloadable ACL*: DACLs are supported on all host modes. -- *Redirect ACL*: This is used to apply an ACL that traps matching packets to the CPU for redirection. It is typically used to match on HTTP packets from a client. -- *Redirect URL*: This is used to specify a redirect URL and works in conjunction with the Redirect ACL. #### 3.3.2.5 Dynamic ACL attributes @@ -824,9 +821,6 @@ When an ACL is installed by Authentication Manager, the following the naming con | IPv6 | Filter Id / Cisco AV Pair StaticACL | IPV6-STATIC-IN-\ | | IPv4 | Cisco AV Pair DACL | IP-DACL-IN-\ | | IPv6 | Cisco AV Pair DACL | IPV6-DACL-IN-\ | -| IPv4 | Redirect ACL | IP-REDIRECT-IN-\ | -| IPv6 | Redirect ACL | IPV6- REDIRECT-IN-\ | -| MAC | Filter Id / Cisco AV Pair StaticACL | MAC-STATIC-IN-\ | The switch UI shall prevent the operator from creating a static ACL where the name matches any of the regular expressions that can be part of the above naming conventions. @@ -872,40 +866,15 @@ When the alive-server action (one server alive after all were dead) is configure The number of supplicants that are re-authenticated per second is configurable. This configuration is for the entire system across all the supplicants on all ports. This is used to control the system and network load when the number of supplicants to be re-authenticated is large. These re-authentications are triggered due to alive server actions. - -#### 3.3.2.9 RADIUS assigned Trunk mode - -In an 802.1X Access-Accept message, the Cisco VSA device-traffic-class=switch indicates that the connected device is capable of forwarding traffic from multiple stations using tagged and untagged traffic. - -When an Access-Accept message is received that contains the VSA device-traffic-class=switch, the switch shall: - -- if present in the Access-Accept, utilize the RADIUS assigned VLAN to set the trunk port native VLAN. If not present, the port PVID is used to set the operational trunk port native VLAN. -- Spanning-tree portfast is operationally disabled on the port. -- The port is operationally set to trunk mode using the current trunk mode configuration. - -Parsing of this VSA attribute is subject to the setting of the “radius-server vsa send authentication” command. - -It is expected that the first device to be authenticated on an interface will have the trunk mode configuration in the Access-Accept and other authentications will not have trunk mode assignment. However, subsequent authentications with trunk mode assignment shall be allowed, however, only the first trunk mode assignment is processed (including the native VLAN assignment). Additional trunk mode assignments are allowed and processed with a debug level log message "Redundant trunk mode assignment for <> ignored" - -Only the first Trunk mode native VLAN assignment received along with the first trunk mode assignment Access-Accept is processed. Typically, this will be contained in the first Access-Accept received for the port along with the trunk mode assignment, however, it need not be. Subsequent VLAN assignments - if the same as the operational PVID - are logged as a DEBUG level message "Redundant native VLAN assignment of Gi1/0/1 to VLAN P ignored" and are ignored as if the assignment was not present in the message. -Subsequent clients authenticating with a VLAN that does not match the Native VLAN/access PVID are denied access with the message (RADIUS supplied VLAN P does not match operational native VLAN Q on \. Access denied". - -The RADIUS supplied native VLAN must be configured on the switch. Dynamic VLAN creation is not supported for RADIUS supplied native VLANs for trunk mode. - -If non-switch clients are already authenticated on a port when a Trunk mode assignment is received, the existing clients are terminated. These clients are assumed to have been behind the switch whose authentication attempt resulted in a Trunk mode assignment. - -If a port is in RADIUS assigned Trunk mode, when the last 802.1X session on the port is terminated or the interface is shut down or error-disabled, the port is restored to the configuration state as it was prior to establishment of any 802.1X session. This is regardless of whether the 802.1X sessions are trunk or non-trunk. - - -#### 3.3.2.10 Monitor Mode +#### 3.3.2.9 Monitor Mode If Monitor mode is enabled, Authentication Manager places the client in Monitor mode as applicable. -#### 3.3.2.11 Authentication History +#### 3.3.2.10 Authentication History Authentication Manager maintains a database of authentication events. Events like “Authorized” or “Unauthorized” are recorded along with the timestamp, port number, client MAC address, and the authentication method used. -#### 3.3.2.12 Open Authentication +#### 3.3.2.11 Open Authentication The Open Authentication capability allows Authentication Manager to allow client traffic event before it authenticates. This is typically used to allow certain devices to allow access to network resources prior to authenticating to obtain IP address and download configuration or firmware upgrades. Once the information is downloaded, the device will authenticate to the network. Open Authentication is configured per interface. The open authentication settings are ignored for force-authorized and force-unauthorized ports. @@ -922,20 +891,6 @@ If a client fails authentication, the authentication failure actions will contin If the client succeeds authentication, the authorization parameters from RADIUS will be applied as usual. However if a DACL or Filter-Id is received, the admin configured static ACLs on the port will not be removed. These will be applied on the port prior to the statically configured ACL. This is required for subsequent clients on the port that are authorized in Open mode. The static ACL would continue to apply on the traffic as intended. -#### 3.3.2.13 Inactivity Timer -The feature is used to clean up idle data clients who have not sent any traffic for 300 seconds. The Authentication Manager Inactivity timer is a per client timer and is run when Re-authentication is not enabled for the client. -The inactivity timer has a value of 300 seconds and is not configurable. Once the inactivity timer expires, the timer handler: -- Checks the SrcHit bit for the client MAC in the hardware L2 table -- If the bit is set, it resets the bit to 0 and the timer is reloaded. -- If the bit is not set, the client entry is cleared from the Authentication Manager database and also the hardware (idle client is cleaned up) - -The above implies that although the Inactivity timer fires every 300 seconds, an idle client can get cleaned up after 300 seconds and up to 600 seconds of its inactivity. - -The feature is: -- Only applicable for clients only -- Not applicable for clients authorized in Open mode -- Applicable for clients in single-host, multi-auth and multi-domain modes - #### 3.3.3 mabd mabd provides the Mac-based Authentication Bypass(MAB) functionality. MAB is intended to provide 802.1x unaware clients controlled access to the network using the devices’ MAC address as an identifier. This requires that the known and allowable MAC address and corresponding access rights be pre-populated in the authentication server. @@ -972,17 +927,17 @@ No change to other process. *hostapd(802.1X)* -hostapd(802.1x) comes to know of an 802.1x client attempting authentication via an EAP exchange. It informs pacd(Authentication Manager) of this client by conveying the client MAC. If the authentication method selected by pacd(Authentication Manager) is 802.1X, pacd(Authentication Manager) sends an event to hostapd(802.1X) for authenticating the user. +hostapd comes to know of an 802.1x client attempting authentication via an EAP exchange. It informs pacd of this client by conveying the client MAC. If the authentication method selected by pacd is 802.1X, pacd sends an event to hostapd for authenticating the user. -hostapd(802.1X) informs pacd(Authentication Manager) about the result of the authentication. hostapd(802.1X) also passes all the authorization parameters it receives from an AAA Server to the pacd(Authentication Manager). These are used for configuring the NAS to allow authenticated client traffic. +hostapd informs pacd about the result of the authentication. hostapd also passes all the authorization parameters it receives from an AAA Server to the pacd. These are used for configuring the NAS to allow authenticated client traffic. *mabd(MAB)* -When user or client tries to authenticate and the method selected is MAB, the pacd(Authentication Manager) sends an event to mabd(MAB) for authenticating the user. The client’s MAC address is sent to mabd(MAB) for the same. +When user or client tries to authenticate and the method selected is MAB, the pacd sends an event to mabd for authenticating the user. The client’s MAC address is sent to mabd for the same. -pacd(Authentication Manager) learns client’s MAC address through an hardware rule to copy-to-CPU the packets from unknown source MAC addresses. +pacd learns client’s MAC address through an hardware rule to copy-to-CPU the packets from unknown source MAC addresses. -mabd(MAB) informs pacd(Authentication Manager) about the result of the authentication. mabd(MAB) also passes all the authorization parameters it receives from an AAA Server to the pacd(Authentication Manager). These are used for configuring the NAS to allow authenticated client traffic. +mabd informs pacd about the result of the authentication. mabd also passes all the authorization parameters it receives from an AAA Server to the pacd. These are used for configuring the NAS to allow authenticated client traffic. ## 3.4 SyncD @@ -1233,7 +1188,7 @@ This command displays the authentication manager information for the interface | Mode | Exec | | ------ | ------------------- | -| Syntax | show authentication interface \{ all \| \{ interface \ \} \} | +| Syntax | show authentication interface \{ all \| \{ interface \ \} \} | | Change history | SONiC 4.0 - Introduced | | Field | Description | @@ -1266,7 +1221,7 @@ show authentication interface 1/0/1 Authentication Manager Status.................. Enabled -Interface...................................... 1/0/1 +Interface...................................... 1/1 Authentication Restart timer................... 300 Configured method order........................ mab undefined undefined Enabled method order........................... mab undefined undefined @@ -1324,7 +1279,7 @@ This command displays the details of the dot1x configuration for a specified por | Mode | Exec | | ------ | ------------------- | -| Syntax | show authentication clients \{ all \| \{ interface \ \} \} | +| Syntax | show authentication clients \{ all \| \{ interface \ \} \} | | Change history | SONiC 4.0 - Introduced | @@ -1344,8 +1299,6 @@ This command displays the details of the dot1x configuration for a specified por | Filter ID | Identifies the Filter ID returned by the RADIUS server when the client was authenticated. This is a configured DiffServ policy name on the switch. | | ACS ACL Name | Identifies the Downloadable ACL returned by the RADIUS server when the client was authenticated. The Downloadable ACL is the same as returned using CiscoSecure-Defined-ACL AVP.| | DACL | Identifies the Downloadable Dynamic ACL returned by the RADIUS server when the client was authenticated. | -| Redirect-ACL | The Redirect ACL is a static ACL sent in the RADIUS attribute redirect-acl. It is used to redirect matching packets to the CPU for further action. | -| Redirect URL | The Redirect URL is a URL sent in the RADIUS attribute redirect-url. It is used by the Redirect component logic to redirect matching packets the redirect URL by using HTTP 302 response code. | | Acct Session Id | The Accounting Session Id associated with the client session. | @@ -1372,7 +1325,7 @@ Interface MAC-Address Method Host Mode Control Mode VLAN Assigned --------- ----------------- ------- ------------ ------------ -------------------------- 0/16 10:8D:B6:C6:00:00 802.1X multi-host auto RADIUS Assigned VLAN (10) -(dhcp-10-130-86-200) #show authentication clients interface 1/0/2 +(dhcp-10-130-86-200) #show authentication clients interface 1/2 Mac Address.................................... 58:05:94:1C:00:00 User Name...................................... testixia @@ -1387,8 +1340,6 @@ Session Termination Action..................... Default Filter-Id ..................................... None ACS ACL Name................................... xACSACLx-IP-FP_ACL-5ee227a2 DACL........................................... None -Redirect ACL................................... IP-REDIRECT-IN-00000001#d -Redirect URL................................... http://rtpjira.rtp.broadcom.com:8080 Session Termination Action..................... Default Acct SessionId:................................ testixia:200000003 @@ -1403,7 +1354,7 @@ This command displays the authentication manager authentication history log for | Mode | Exec | | ------ | ------------------- | -| Syntax | show authentication authentication-history \{ interface \ \} | +| Syntax | show authentication authentication-history \{ interface \ \} | | Change history | SONiC 4.0 - Introduced | Example: @@ -1423,7 +1374,7 @@ This command is used to show a summary of the global mab configuration and summa | Mode | Exec | | ------ | ------------------- | -| Syntax | show mab \{ \ \| \{ interface \ \} \} | +| Syntax | show mab \{ \ \| \{ interface \ \} \} | | Change history | SONiC 4.0 - Introduced | Example: @@ -1439,7 +1390,7 @@ Interface Admin Mode Auth-type --------- ----------- --------- 0/3 Disabled N/A -(dhcp-10-130-86-142) #show mab interface 0/10 +(dhcp-10-130-86-142) #show mab interface 1/10 Interface Admin Mode Auth-type 0/10 Enabled eap-md5 From 7bfd078998f61fedf7053e5b27f9e66c6fe61c19 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Fri, 7 May 2021 12:39:02 +0530 Subject: [PATCH 32/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 89b085dfcf72..6d4909ebc388 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.3 +High level design document version 0.4 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -704,8 +704,6 @@ user_name = 1*255VCHARS ; Client user name ### 3.3.1 Orchestration Agent -#### 3.3.1.1 PAC Orchestration agent - ### 3.3.2 pacd pacd process links with FASTPATH components libfpinfra.so and libauthmgr.so for the infrastructure and authentication manager functionality respectvely. Below picture depicts the interal details of the pacd process. @@ -914,10 +912,10 @@ If authentication type is configured as CHAP, a randomly generated 16-octet chal The authentication server checks its pre-populated database for the authorized Mac addresses and returns an ‘Access-Accept’ or an ‘Access-Reject’ depending on if the Mac address has been found in the database. This also makes it possible for the client to be placed in a RADIUS assigned VLAN or apply a specific Filter ID to the client traffic. ### 3.3.4 hostapd -Hostapd application supplied with wpa_supplicant is an open source implementation of 802.1x standard. The wired driver module of hostapd is adapted to write information to SONiC DB instead of directly controlling the interfaces. This driver also takes care of interacting with pacd via socket interface. hostapd gets its configuration from the hostapd.conf file generated by SONiC system. +Hostapd is an open source implementation of 802.1x standard and the Linux application is supplied with wpa_suplicant package. The wired driver module of hostapd is adapted to communicate with pacd via socket interface instead of directly controlling the interfaces. hostapd gets its configuration from the hostapd.conf file generated via jinja2 tempaltes by SONiC system. -### 3.3.5 pacmgr -pacmgr aids standard Linux application hostapd to read its relevant configuration from SONiC DBs, populate the hostapd.conf and restart hostapd. +### 3.3.5 hostapdmgr +hostapdmgr reads hostapd specific configuration from SONiC DBs and populates the hostapd.conf. It further notifies the hostapd to re-read the configuration file. ### 3.3.6 Other Process From 043c75cec5599750bb6495d124c1dca50de0e964 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 12 May 2021 12:26:54 +0530 Subject: [PATCH 33/47] Updated requirements and functional description --- L2/PAC/PortAccessControl.md | 67 ++++++++++--------------------------- 1 file changed, 17 insertions(+), 50 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 6d4909ebc388..68fab9042602 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.4 +High level design document version 0.5 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -113,6 +113,8 @@ High level design document version 0.4 | 0.2 | 04/05/2021 | Prabhu Sreenivasan, Amitabha Sen | DB schema update and Review comments | | 0.3 | 04/27/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated CLI commands | | 0.4 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated desgin section | +| 0.5 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated requirements and functional description section | + # About this Manual This document describes the design details of the Port Access Control feature in SONiC. Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. @@ -168,12 +170,7 @@ The following are the requirements for Port Access Control feature: - Filter Id 7. SONiC supports Single-Host mode where only one data client can be authenticated on a port and is granted access to the port at a given time. 8. SONiC supports Multiple Hosts mode where only one data client can be authenticated on a port and after that access is granted to all clients connected to the port -9. SONiC supports Multi Domain Authentication (MDA), where 802.1X is extended to allow authorization of multiple devices (a data and a voice device) on a single port and assign different VLANs to the devices based on authorization. - - MDA is enabled by default; however, you need to assign a tagged VLAN for voice devices (see Configure 802.1X Interfaces for a VLAN-aware Bridge). - - A maximum of four authorized devices (MAB + EAPOL) per port are supported. - - The 802.1X-enabled port must be a trunk port to allow tagged voice traffic from a phone; you cannot enable 802.1X on an access port. - - Only one untagged VLAN and one tagged VLAN is supported on the 802.1X enabled ports. - - Multiple MAB (non voice) devices on a port are supported for VLAN-aware bridges only. Authorization of multiple MAB devices for different VLANs is not supported. +9. SONiC supports Multiple Domain Authentication mode where only one data and one voice client can be authenticated on a port. 10. SONiC supports Multiple Authentication mode where one voice client and multiple data clients can be authenticated on a port and these clients are then granted access. 11. SONiC supports the following specical VLANs: - Unauthenticated VLAN @@ -191,30 +188,10 @@ The following are the requirements for Port Access Control feature: 1. SONiC shall make use of opensource 802.1x implementation **hostapd** suppied with **wpa_supplicant** package. *MAB* -The following are the requirements for MAB feature: 1. MAB can be used to authenticate clients that do not support EAP. -2. A port can be configured to be either doing port-based authentication or doing Mac-based authentication. But only one mode at a given instance. -3. A port when enabled for Dot1x authentication needs to explicitly mention whether it is being enabled for port-based authentication mode or Mac-based authentication mode. -4. When a port is configured for Mac-based Dot1x Authentication, then if at least one client has actively authentication itself then port is placed in authorized state for other components. -5. When a port is configured for Mac-based Dot1x Authentication, then port is placed in un-authorized state if the last active authorized client ceases to exist. -6. When a port is operational in Mac-based Dot1x Authentication, then only the data traffic arriving on the port from authorized clients need to be forwarded. -7. When a port is operational in Mac-based Dot1x Authentication, accept EAPOL packets from all the clients (both authorized and unauthorized as well). -8. When a port is enabled for Guest vlan, then Mac-based dot1x authentication can not be enabled on that port. -9. When a port is enabled for vlan assignment, then Mac-based dot1x authentication could also be enabled on that port. As the vlan assignment is based on the user details of the client. -10. To enable Mac-based dot1x authentication on port it needs to be an Edge port. (Dot1s Configuration). -11. If Mac-based dot1x authentication is enabled on a port and if Mac-based VLANs or Subnet VLANs or Protocol VLANs are also enabled, then Mac-based dot1x authentication is disabled. -12. If Port-Mac Locking is enabled on the port and if Mac-based dot1x authentication is also enabled on the port. Then Port-Mac Locking needs to be disabled. -13. If a client already authentication on one port has roamed to another port on the switch, then the state (status, vlan etc) of the client on the prior port needs to be cleaned. -14. Timeout mechanism needs to be maintained per client so that inactive client's status can be removed on the switch. -15. Multicast/Broadcast traffic arriving on the port that is enabled for Mac-based authentication would be forwarded accordingly. If the source Mac-address of the packet is from a authenticated user. -16. Even when the port is authorized, dot1x would still continue to send EAPOL for authentication as more users could join on the port. -17. Unauthenticated Vlan is per port configuration. By default unauthenticated vlan is zero (invalid and not operational). -18. In port-based dot1x, if the client fails authentication then port is placed in the unauthenticated vlan (if configured) -19. In mac-based dot1x, if the client fails authentication then client-mac is associated to the unauthenticated vlan (if configured). -20. Unauthenticated vlan deprecates the Guest vlan feature of supplicant mode, as it would be redundant. *RADIUS* -1. User can configure up to three RADIUS servers (in case of failover). However, do not use a SONiC switch as the RADIUS server. +1. User can configure RADIUS servers. However, do not use a SONiC switch as the RADIUS server. 2. RADIUS authentication is supported with FreeRADIUS and Cisco ISE. @@ -265,24 +242,15 @@ Additionally, there exists a third role: All three roles are required in order to complete an authentication exchange. SONiC supports the Authenticator role only, in which the PAE is responsible for communicating with the Supplicant. The Authenticator PAE is also responsible for submitting the information received from the Supplicant to the Authentication Server in order for the credentials to be checked, which will determine the authorization state of the Port. The Authenticator PAE controls the authorized/unauthorized state of the controlled Port depending on the outcome of the authentication process. -### 2.2.1 Local vs. RADIUS Authentication -There are two methods that can be used for authenticating a user for a particular port on a switch. These methods are described in the following sections. - -*Local Authentication* -Local authentication consists of matching a user ID/password combination from the Supplicant to a locally-stored user database. The user ID that is returned in response to an EAP-Request/Identity is matched against the database. If a match is found, an EAP-Request/MD5 challenge request is sent to the Supplicant. The Supplicant then takes the challenge, its password and the EAP ID and derives an MD5 response. The MD5 response is then send to the Authenticator which uses the locally stored password to derive the answer and compare it to the Supplicants response. A match results in a successful authentication of the port. - -Note that the SONiC Authenticator supports only the EAP-MD5 authentication type for local authentication. - - -*RADIUS Authentication* - +### 2.2.1 RADIUS Authentication When RADIUS authentication is used, the Authenticator basically becomes a passthrough. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section labelled "RADIUS Authorization Attributes" in this document. ### 2.2.2 Unidirectional and bidirectional control -The controlled directions dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control direction are of two type: +The controlled directions dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control directions are of two types: 1. Both: Control is exerted over both incoming and outgoing frames. 2. In: Control is only exerted over incoming traffic. -SONiC allows only unidirection(In) control. Please see "Limitations and Restrictions" section. + +**SONiC allows only unidirection(In) control. Please see "Limitations and Restrictions" section.** ### 2.2.3 Downloadable ACL @@ -290,7 +258,7 @@ PAC (Port access control) feature brings in DACL (downloadable ACL) support into The switch does not display RADIUS specified DACL’s in the running configuration. The ACL however shows up in the user interface show commands. Essentially, the DACL configuration is temporary (applied for the duration of the authenticated client session) and not persistent. The downloadable ACLs sent by RADIUS are in extended ACL syntax style and are validated just like user created ACLs. The ACLs created by the applications are owned by the internal application and hence cannot be deleted by a user. -Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. Amoung DACLs IPv6 ACL have higher prority over IPv4. In situations where the client IP address changes, the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. +Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. In situations where the client IP address changes, the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. ### 2.2.4 Named ACLs @@ -313,8 +281,7 @@ PAC interacts with FDB to modify the learning mode of a port and add static FDB 1. Once PAC is enabled on a port, all incoming traffic on the port are blocked/dropped except certain protocol traffic. 2. PAC turns off learning on the port essentially dropping all unknown source MAC packets. This achieves the requirement of blocking ingress traffic. 3. Egress traffic on the port is not blocked. - 4. Once a client starts the authentication process, the client is no longer unknown (unknown source MAC). However, since authentication is yet to be completed, -traffic for the client must still get dropped. To achieve the same, PAC installs a static FDB entry with discard bits set, is installed to mark the client "known" so that the incoming traffic does not flood the CPU. + 4. Once a client starts the authentication process, the client is no longer unknown (unknown source MAC). PAC installs a static FDB entry with discard bits set to mark the client "known" so that the incoming traffic does not flood the CPU. - For MAB, unknown source MAC packets are trapped to the CPU. - Station movement is also handled i.e if a packet is received from another port on a MAC, VLAN pair for which PAC installed a static FDB entry, such packets also get trapped to the CPU. @@ -983,15 +950,13 @@ This command enables the Authentication monitor mode on the switch. The purpose | Change history | SONiC 4.0 - Introduced | #### 3.6.2.4 aaa authentication pac -This command configures the authentication method for port-based access to the switch. The additional methods of authentication are used only if the previous method returns an error, not if there is an authentication failure. The possible methods are as follows: -ias. Uses the internal authentication server users database for authentication. This method can be used in conjunction with any one of the existing methods like local, radius, etc. -local. Uses the local username database for authentication. -none. Uses no authentication. -radius. Uses the list of all RADIUS servers for authentication +This command configures the authentication method for port-based access to the switch. The additional methods of authentication are used only if the previous method returns an error, not if there is an authentication failure. The possible methods are as follows: +- none: Uses no authentication. +- radius: Uses the list of all RADIUS servers for authentication | Mode | Global Config | | ---- | ------ | -| Syntax | aaa authentication pac \{ radius \| local \| none \} | +| Syntax | aaa authentication pac \{ radius \| none \} | | Default | radius | | Change history | SONiC 4.0 - Introduced | @@ -1466,6 +1431,8 @@ The following is the support scale for Port Access Control. The following number # 9 Limitation +- SONiC PAC allows only unidirectional (In) control where the incoming traffic is blocked while the port is not authenticated. PAC does not have any control on traffic egressing out of the port. + - Authentication Manager does not make any required configuration for the respective methods to authenticate successfully. The administrator needs to ensure that the correct and appropriate configuration is present in the system. For example, if the authentication order method includes the 802.1x port authentication method, 802.1X should be enabled for the authentication to succeed. Authentication manager will not enable/disable and make the configurations related to 802.1X. Administrator should make the necessary configurations. - In the default configuration, all traffic that is not EAP over LAN (EAPoL) traffic (including DHCP) is dropped until 802.1X and MAB times out. Therefore, the value of the timeout can significantly affect the DHCP client on the end host. Longer 802.1X timeouts may prevent DHCP from functioning correctly after the 802.1X timeout expires. From d2b200f875968139b52413d6a8d187866a2ee145 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 12 May 2021 18:56:36 +0530 Subject: [PATCH 34/47] updated docker to macsec and updated scalability and warmboot requirement --- L2/PAC/PortAccessControl.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 68fab9042602..b9adcf346138 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.5 +High level design document version 0.6 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -114,6 +114,7 @@ High level design document version 0.5 | 0.3 | 04/27/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated CLI commands | | 0.4 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated desgin section | | 0.5 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated requirements and functional description section | +| 0.6 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated docker to macsec, added configuration, scalability and warmboot requirements | # About this Manual @@ -146,7 +147,7 @@ Local Area Networks (LANs) are often deployed in environments that permit unauth ### 1.1.1 Dot1x -IEEE 802.1X is an IEEE Standard for Port Access Control (PAC) that provides an authentication mechanism to devices wishing to attach to a LAN. The standard defines Extensible Authentication Protocol Over LAN (EAPOL). The 802.1X standard describes an architectural framework within with authentication and consequent actions take place. It also establishes the requirements for a protocol between the authenticator and the supplicant, as well as between the authenticator and the authentication server. +IEEE 802.1X is an IEEE Standard for Port Access Control (PAC) that provides an authentication mechanism to devices wishing to attach to a LAN. The standard defines Extensible Authentication Protocol Over LAN (EAPOL). The 802.1X standard describes an architectural framework within which authentication and consequent actions take place. It also establishes the requirements for a protocol between the authenticator and the supplicant, as well as between the authenticator and the authentication server. ### 1.1.2 MAC Authentication Bypass Simple devices like camera or printers which do not support 802.1x authentication can make use of MAB feature where the device gets authenticated based on the device MAC address. @@ -168,6 +169,7 @@ The following are the requirements for Port Access Control feature: - Named ACLs - Dynamic ACLs - Filter Id + - Downloadable ACLs 7. SONiC supports Single-Host mode where only one data client can be authenticated on a port and is granted access to the port at a given time. 8. SONiC supports Multiple Hosts mode where only one data client can be authenticated on a port and after that access is granted to all clients connected to the port 9. SONiC supports Multiple Domain Authentication mode where only one data and one voice client can be authenticated on a port. @@ -192,22 +194,31 @@ The following are the requirements for Port Access Control feature: *RADIUS* 1. User can configure RADIUS servers. However, do not use a SONiC switch as the RADIUS server. -2. RADIUS authentication is supported with FreeRADIUS and Cisco ISE. +2. RADIUS authentication is supported with FreeRADIUS, ClearPass and Cisco ISE. ### 1.3.2 Configuration and Management Requirements +This feature supports CLI and REST based configurations. +1. Support CLI configurations as mentioned in section 3.6.2 +2. Support show commands as mentioned in section 3.6.3 +3. Support debug commands as mentioned in section 3.6.4 +4. Support REST APIs for config and operational data ### 1.3.3 Scalability Requirements +1. 48 clients per port, with a maxmimum of 512 clients per box/unit/system +2. 30 ACL rules per client/host ### 1.3.4 Warm Boot Requirements -Port Access Control feature should work seamlessly across warmboot. Statistics must be preserved across warmboot. +Port Access Control feature should work seamlessly across warmboot. +Statistics must be preserved across warmboot. +HW and SW entries for authenticated clients are preserved across warmboot. ## 1.4 Design Overview ### 1.4.1 Basic Approach ### 1.4.2 Container -A new container sonic-security is introduced to hold all the port security applications. Apart from sonic-security container, code changes are made to SWSS, mgmt-frameowrk containers. +Existing container macsec holds all the port security applications. Apart from macsec container, code changes are made to SWSS, mgmt-frameowrk containers. ### 1.4.3 SAI Support No changes to SAI spec for supporting PAC. @@ -240,17 +251,17 @@ A PAE is able to adopt one of two distinct roles within an access control intera Additionally, there exists a third role: 3. authentication server: Performs the authentication function necessary to check the credentials of the Supplicant on behalf of the Authenticator. -All three roles are required in order to complete an authentication exchange. SONiC supports the Authenticator role only, in which the PAE is responsible for communicating with the Supplicant. The Authenticator PAE is also responsible for submitting the information received from the Supplicant to the Authentication Server in order for the credentials to be checked, which will determine the authorization state of the Port. The Authenticator PAE controls the authorized/unauthorized state of the controlled Port depending on the outcome of the authentication process. +All three roles are required in order to complete an authentication exchange. **SONiC supports the Authenticator role only, in which the PAE is responsible for communicating with the Supplicant.** The Authenticator PAE is also responsible for submitting the information received from the Supplicant to the Authentication Server in order for the credentials to be checked, which will determine the authorization state of the Port. The Authenticator PAE controls the authorized/unauthorized state of the controlled Port depending on the outcome of the authentication process. ### 2.2.1 RADIUS Authentication -When RADIUS authentication is used, the Authenticator basically becomes a passthrough. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section labelled "RADIUS Authorization Attributes" in this document. +The Authenticator is essentially a passthrough for the EAP method. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section [Authorization parameters](#3324-authorization-parameters). ### 2.2.2 Unidirectional and bidirectional control The controlled directions dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control directions are of two types: 1. Both: Control is exerted over both incoming and outgoing frames. 2. In: Control is only exerted over incoming traffic. -**SONiC allows only unidirection(In) control. Please see "Limitations and Restrictions" section.** +**SONiC allows only unidirection(In) control. Please see [Limitation](#9-limitation) section.** ### 2.2.3 Downloadable ACL @@ -1262,7 +1273,6 @@ This command displays the details of the dot1x configuration for a specified por | Filter ID | Identifies the Filter ID returned by the RADIUS server when the client was authenticated. This is a configured DiffServ policy name on the switch. | | ACS ACL Name | Identifies the Downloadable ACL returned by the RADIUS server when the client was authenticated. The Downloadable ACL is the same as returned using CiscoSecure-Defined-ACL AVP.| | DACL | Identifies the Downloadable Dynamic ACL returned by the RADIUS server when the client was authenticated. | -| Acct Session Id | The Accounting Session Id associated with the client session. | VLAN Assigned Reason can take one of the following values: From e5465fcb29149672a2ddfe4c1ed3e528094bba0e Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 26 May 2021 15:55:31 +0530 Subject: [PATCH 35/47] addressed suggestions by Santosh and Chandra --- L2/PAC/PortAccessControl.md | 126 +++++++++++++++++++----------------- 1 file changed, 68 insertions(+), 58 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index b9adcf346138..c37b04421c0c 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.6 +High level design document version 0.7 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -115,7 +115,7 @@ High level design document version 0.6 | 0.4 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated desgin section | | 0.5 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated requirements and functional description section | | 0.6 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated docker to macsec, added configuration, scalability and warmboot requirements | - +| 0.7 | 05/26/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | # About this Manual This document describes the design details of the Port Access Control feature in SONiC. Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. @@ -129,6 +129,7 @@ This document describes the high level design details about Port Access Control ## Table 1 Abbreviations | **Term** | **Meaning** | | -------- | -------------------- | +| Authenticator | An entity that enforces authentication before allowing access to services available via that Port | | CoPP | Control Plane Policing | | Dot1x | IEEE 802.1 standard | | EAPOL | Extensible Authentication Protocol over LAN | @@ -137,20 +138,23 @@ This document describes the high level design details about Port Access Control | PAE | Port Access Entity | | RADIUS | Remote Authentication Dial In User service | | SONiC-CLI | Klish CLI used by management framework | +| Supplicant | An entity that attempts to access services offered by the Authenticator | # 1 Feature Overview ## 1.1 Port Access Control -Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. +Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. + +Local Area Networks (LANs) are often deployed in environments that permit unauthorized devices to be physically attached to the LAN infrastructure, or permit unauthorized users to attempt to access the LAN through equipment already attached. In such environments, it may be desirable to restrict access to the services offered by the LAN to those users and devices (clients) that are permitted to use those services. PAC provides means for authenticating and authorizing devices attached to a LAN port that has point-to-point connection characteristics and of preventing access to that port in cases in which the authentication and authorization process fails. -Local Area Networks (LANs) are often deployed in environments that permit unauthorized devices to be physically attached to the LAN infrastructure, or permit unauthorized users to attempt to access the LAN through equipment already attached. In such environments, it may be desirable to restrict access to the services offered by the LAN to those users and devices that are permitted to use those services. Port access control makes use of the physical characteristics of LAN infrastructures in order to provide a means of authenticating and authorizing devices attached to a LAN port that has point-to-point connection characteristics and of preventing access to that port in cases in which the authentication and authorization process fails. In this context, a port is a single point of attachment to the LAN, such as Ports of MAC bridges and associations between stations or access points in IEEE 802.11 Wireless LANs. +PAC uses authentication methods like 802.1x and MAB for client authentication. These methods in turn use RADIUS for client credential verification and receive the authorization attributes like VLANs, ACLs etc.. for the authenticated clients. ### 1.1.1 Dot1x -IEEE 802.1X is an IEEE Standard for Port Access Control (PAC) that provides an authentication mechanism to devices wishing to attach to a LAN. The standard defines Extensible Authentication Protocol Over LAN (EAPOL). The 802.1X standard describes an architectural framework within which authentication and consequent actions take place. It also establishes the requirements for a protocol between the authenticator and the supplicant, as well as between the authenticator and the authentication server. +IEEE 802.1X-2004 is an IEEE Standard for Port Access Control (PAC) that provides an authentication mechanism to devices wishing to attach to a LAN. The standard defines Extensible Authentication Protocol Over LAN (EAPOL). The 802.1X standard describes an architectural framework within which authentication and consequent actions take place. It also establishes the requirements for a protocol between the authenticator and the supplicant, as well as between the authenticator and the authentication server. ### 1.1.2 MAC Authentication Bypass -Simple devices like camera or printers which do not support 802.1x authentication can make use of MAB feature where the device gets authenticated based on the device MAC address. +An authenticator can make use of MAC Authentication Bypass (MAB) feature to authenticate simple devices like camera or printers which do not support 802.1x. MAB feature makes use of the device MAC address to authenticate the client. ## 1.3 Requirements @@ -158,43 +162,47 @@ Simple devices like camera or printers which do not support 802.1x authenticatio *PAC* The following are the requirements for Port Access Control feature: -1. PAC is supported on physical interfaces only. -2. The interfaces cannot be part of a port-channel / LAG. -3. PAC is not supported on service port. -4. User can configure PAC interfaces for switches using the following features: +1. PAC should be supported on physical interfaces only. +2. The interfaces should not be part of a port-channel / LAG. +3. PAC shall not be supported on Out-of-band port. +4. PAC enforces access control for clients on switch ports using the following authentication mechanisms: - 802.1x - MAB (MAC-based authentication bypass). -5. MAB, and dot1x need support for access port. -6. PAC supports the following Dynamic ACLs: - - Named ACLs - - Dynamic ACLs - - Filter Id - - Downloadable ACLs -7. SONiC supports Single-Host mode where only one data client can be authenticated on a port and is granted access to the port at a given time. -8. SONiC supports Multiple Hosts mode where only one data client can be authenticated on a port and after that access is granted to all clients connected to the port -9. SONiC supports Multiple Domain Authentication mode where only one data and one voice client can be authenticated on a port. -10. SONiC supports Multiple Authentication mode where one voice client and multiple data clients can be authenticated on a port and these clients are then granted access. -11. SONiC supports the following specical VLANs: +5. Both 802.1x and MAB can be enabled on a port together. Their relative order and priority shall be configurable. +6. PAC shall be supported on ports configured as switch port mode access. Its not supported on trunk ports. +7. PAC supports the following Dynamic ACLs: + - Named ACLs : ACLs that are statically configured on the switch and are used to control authenticated client traffic. + - Dynamic ACLs : Rules of these ACLs are defined in RADIUS profiles. These rules (excluding ACL name) are sent in the RADIUS Access Accept and then the ACL is applied to the authenticated client. + - Filter Id : This is a standard RADIUS attribute that is sent in the RADIUS Access Accept message and is used to indicate a statically configured ACL to be used for the authenticated client. + - Downloadable ACLs : These ACLs, along with name and their rules, are defined in a RADIUS server. They are downloaded using RADIUS messages and are applied to the authenticated clients. They are also called CISCO-secure-ACLs. +8. SONiC supports Single-Host mode where only one data client can be authenticated on a port and is granted access to the port at a given time. +9. SONiC supports Multiple Hosts mode where only one data client can be authenticated on a port and after that access is granted to all clients connected to the port +10. SONiC supports Multiple Domain Authentication mode where only one data and one voice client can be authenticated on a port. +11. SONiC supports Multiple Authentication mode where one voice client and multiple data clients can be authenticated on a port and these clients are then granted access. +12. SONiC shall suport the following VLANs to authorize clients which fail authentication: - Unauthenticated VLAN - Guest VLAN - Monitor VLAN - Open VLAN - Critical VLAN - - Voice VLAN -12. The following PAC port modes are supported on SONiC: - - Auto - - Force Authorized - - Force Unauthorized +13. SONiC shall suport Voice VLAN to authorize Voice clients. +14. The following PAC port modes are supported on SONiC: + - Auto : Authentication is enforced on the port. Traffic is only allowed for authenticated clients + - Force Authorized : Authentication is not enforced on the port and all traffic is allowed. + - Force Unauthorized : Authentication is not enforced on the port and all traffic is blocked. *802.1x* -1. SONiC shall make use of opensource 802.1x implementation **hostapd** suppied with **wpa_supplicant** package. +1. SONiC shall support 802.1x authenticator functionality. *MAB* -1. MAB can be used to authenticate clients that do not support EAP. +1. MAB shall be used to authenticate clients that do not support 802.1x *RADIUS* -1. User can configure RADIUS servers. However, do not use a SONiC switch as the RADIUS server. -2. RADIUS authentication is supported with FreeRADIUS, ClearPass and Cisco ISE. +1. PAC shall have a RADIUS clinet functionality where user shall configure RADIUS server details. +2. RADIUS authentication shall be tested/qualified with the following Radius Servers: + - FreeRADIUS + - ClearPass + - Cisco ISE. ### 1.3.2 Configuration and Management Requirements @@ -205,13 +213,15 @@ This feature supports CLI and REST based configurations. 4. Support REST APIs for config and operational data ### 1.3.3 Scalability Requirements -1. 48 clients per port, with a maxmimum of 512 clients per box/unit/system +1. 48 clients per port, with a maxmimum of 512 clients per switch 2. 30 ACL rules per client/host ### 1.3.4 Warm Boot Requirements -Port Access Control feature should work seamlessly across warmboot. -Statistics must be preserved across warmboot. -HW and SW entries for authenticated clients are preserved across warmboot. +Port Access Control feature should work seamlessly across warmboot: +- Statistics must be preserved across warmboot. +- HW and SW entries for authenticated clients are preserved across warmboot. +- Authenticated client traffic is not disrupted. +- Clients in the process of authentication will need to re-initiate their authentication process. ## 1.4 Design Overview @@ -227,9 +237,7 @@ No changes to SAI spec for supporting PAC. ## 2.1 Target Deployment Use Cases -When a client authenticates itself initially on the network, the Switch acts as the authenticator to the clients on the network and forwards the authentication request to the Radius server in the network. If the authentication succeeds then the client is placed in authorized state and the client is able to forward or receive traffic through the port. - -If the vlan assignment is enabled in the Radius server, then as part of the response message, Radius server sends the vlan id the client is supposed to be in the 802.1x tunnel attributes. This implies that the client can connect from any port and can get assigned to the appropriate vlan that it is supposed to be in; this is configured in the radius server. This gives flexibility for the clients to move around the network without much configuration need to be done by the administrator. +When a client authenticates itself initially on the network, the Switch acts as the authenticator to the clients on the network and forwards the authentication request to the Radius server in the network. If the authentication succeeds then the client is placed in authorized state and the client is able to forward or receive traffic through the port. RADIUS servers sends a list of Authorization attributes like VLAN, ACLs etc.. to be applied to the client traffic. This allows the flexibility of differential treatment to clients. ![pac-deployment](https://user-images.githubusercontent.com/45380242/117295415-7157c300-ae91-11eb-99fb-6415ce79fe44.PNG) @@ -269,7 +277,7 @@ PAC (Port access control) feature brings in DACL (downloadable ACL) support into The switch does not display RADIUS specified DACL’s in the running configuration. The ACL however shows up in the user interface show commands. Essentially, the DACL configuration is temporary (applied for the duration of the authenticated client session) and not persistent. The downloadable ACLs sent by RADIUS are in extended ACL syntax style and are validated just like user created ACLs. The ACLs created by the applications are owned by the internal application and hence cannot be deleted by a user. -Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. In situations where the client IP address changes, the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. +Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. In situations where the client IP address changes, PAC gets to know about it via dhcp-snooping binding tables and the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. ### 2.2.4 Named ACLs @@ -293,6 +301,7 @@ PAC interacts with FDB to modify the learning mode of a port and add static FDB 2. PAC turns off learning on the port essentially dropping all unknown source MAC packets. This achieves the requirement of blocking ingress traffic. 3. Egress traffic on the port is not blocked. 4. Once a client starts the authentication process, the client is no longer unknown (unknown source MAC). PAC installs a static FDB entry with discard bits set to mark the client "known" so that the incoming traffic does not flood the CPU. + 5. After a client is authenticated, this discard FDB entry is removed. Learning on the port is enabled(multi-host-mode) or retained disabled (rest of the host modes) for that port. - For MAB, unknown source MAC packets are trapped to the CPU. - Station movement is also handled i.e if a packet is received from another port on a MAC, VLAN pair for which PAC installed a static FDB entry, such packets also get trapped to the CPU. @@ -683,7 +692,7 @@ user_name = 1*255VCHARS ; Client user name ### 3.3.1 Orchestration Agent ### 3.3.2 pacd -pacd process links with FASTPATH components libfpinfra.so and libauthmgr.so for the infrastructure and authentication manager functionality respectvely. Below picture depicts the interal details of the pacd process. +pacd process links with libfpinfra.so and libauthmgr.so for the infrastructure and authentication manager functionality respectvely. Below picture depicts the interal details of the pacd process. ![pacd](https://user-images.githubusercontent.com/45380242/117293455-05745b00-ae8f-11eb-9c36-f7986b0179cf.PNG) **Figure 5: pacd process internals** @@ -1001,7 +1010,7 @@ This command configures VLAN as guest vlan on an interface or a range of interfa | Change history | SONiC 4.0 - Introduced | #### 3.6.2.8 authentication event fail action authorize vlan -This command configures the unauthenticated VLAN associated with the specified interface or range of interfaces. This VLAN is used when the AAA server fails to recognize the client credentials and rejects the authentication attempt. The unauthenticated VLAN ID can be a valid VLAN ID from 1-Maximum supported VLAN ID (4093 for FASTPATH). By default, the unauthenticated VLAN is 0, i.e. invalid and not operational. +This command configures the unauthenticated VLAN associated with the specified interface or range of interfaces. This VLAN is used when the AAA server fails to recognize the client credentials and rejects the authentication attempt. The unauthenticated VLAN ID can be a valid VLAN ID from 1-Maximum supported VLAN ID (4093). By default, the unauthenticated VLAN is 0, i.e. invalid and not operational. | Mode | Interface Config | | ---- | ------ | @@ -1041,7 +1050,7 @@ This command sets the authentication mode to use on the specified interface or r | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication host-mode authentication port-control \{ auto \| force-authorized \| force-unauthorized \} | +| Syntax | authentication port-control \{ auto \| force-authorized \| force-unauthorized \} | | Default | auto | | Change history | SONiC 4.0 - Introduced @@ -1109,7 +1118,7 @@ This command is used to set the order of authentication methods used on a port. | Mode | Interface Config | | ---- | ------ | | Syntax | authentication order \{ dot1x \[ mab \] \| mab \[ dot1x \] \} | -| Default | None | +| Default order | dot1x, mab | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.20 authentication priority @@ -1118,7 +1127,7 @@ This command is used to set the priority for the authentication methods used on | Mode | Interface Config | | ---- | ------ | | Syntax | authentication priority \{ dot1x \[ mab \] \| mab \[ dot1x \] \} | -| Default | None | +| Default order | dot1x, mab | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.21 mab @@ -1171,7 +1180,7 @@ This command displays the authentication manager information for the interface | Interface | The interface for which authentication configuration information is being displayed. | | Port Control Mode | The configured control mode for this port. Possible values are force-unauthorized | auto | unauthorized. | | Host Mode | The authentication host mode configured on the interface. | -| Authentication Restart timer | The time, in seconds, after which reauthentication starts. | +| Authentication Restart timer | The is the quite period timer. The quite period is time in seconds before re-attempting authentication for a failed client. | | Configured method order | The order of authentication methods used on the interface. | | Enabled method order | The order of authentication methods used on the interface. | | Configured method priority | The priority for the authentication methods used on the interface. | @@ -1182,7 +1191,6 @@ This command displays the authentication manager information for the interface | Guest VLAN ID | The VLAN id to be used to authorize clients that time out or fail authentication due to invalid credentials. This is applicable only for 802.1x unaware clients. | | Unauthenticated VLAN ID | The VLAN id to be used to authorize clients that that time out or fail authentication due to invalid credentials. This is applicable only for 802.1x clients. | | Critical Vlan Id | The VLAN id to be used to authorize clients that that time out due to unreachable RADIUS servers. | -| Authentication Violation Mode | The action to be taken when a security violation occurs on a port. | | Authentication Server Dead action | The action to be undertaken for data clients when all RADIUS servers are found dead. | | Authentication Server Dead action for Voice | The action to be undertaken for voice clients when all RADIUS servers are found dead. | | Authentication Server Alive action | The action to be undertaken for data clients when a RADIUS server comes back alive after all were found dead. | @@ -1191,7 +1199,7 @@ This command displays the authentication manager information for the interface Example: ``` -show authentication interface 1/0/1 +show authentication interface 1/1 Authentication Manager Status.................. Enabled @@ -1207,7 +1215,6 @@ Maximum Users.................................. 48 Guest VLAN ID..... ............................ 0 Unauthenticated VLAN ID........................ 0 Critical Vlan Id............................... 0 -Authentication Violation Mode.................. Restrict Authentication Server Dead action.............. None Authentication Server Dead action for Voice.... None Authentication Server Alive action............. None @@ -1303,9 +1310,9 @@ Interface MAC-Address Method Host Mode Control Mode VLAN Assigned Mac Address.................................... 58:05:94:1C:00:00 User Name...................................... testixia VLAN Assigned Reason........................... Voice VLAN (100) -Host Mode ..................................... multi-auth +Host Mode ..................................... Multi-auth Method......................................... 802.1X -Control Mode................................... auto +Control Mode................................... Auto Session time ... .............................. 10 Session timeout ............................... 100 Time left for Session Termination Action....... 90 @@ -1327,18 +1334,18 @@ This command displays the authentication manager authentication history log for | Mode | Exec | | ------ | ------------------- | -| Syntax | show authentication authentication-history \{ interface \ \} | +| Syntax | show authentication authentication-history \{ interface \ \} | | Change history | SONiC 4.0 - Introduced | Example: ``` -show authentication authentication-history 1/0/2 +show authentication authentication-history interface 1/2 Timestamp Interface MAC-Address Auth Status Method -------------------- --------- ----------------- ------------ ------ -May 07 2020 13:02:41 1/0/2 58:05:94:1C:00:00 Unauthorized 802.1X -May 07 2020 13:01:33 1/0/2 58:05:94:1C:00:00 Unauthorized 802.1X +May 07 2020 13:02:41 1/2 58:05:94:1C:00:00 Unauthorized 802.1X +May 07 2020 13:01:33 1/2 58:05:94:1C:00:00 Unauthorized 802.1X ``` @@ -1358,14 +1365,17 @@ MAB Request Fmt Attr1 Groupsize... 2 MAB Request Fmt Attr1 Separator... legacy(:) MAB Request Fmt Attr1 Case........ uppercase -Interface Admin Mode Auth-type --------- ----------- --------- --------------------- ------- ------------- -0/1 Disabled N/A 0/2 Disabled N/A -0/3 Disabled N/A +Interface Admin Mode Auth-type +--------- ----------- --------- +1/1 Disabled N/A +1/2 Disabled N/A +1/3 Disabled N/A (dhcp-10-130-86-142) #show mab interface 1/10 Interface Admin Mode Auth-type -0/10 Enabled eap-md5 +--------- ----------- --------- +1/10 Enabled eap-md5 ``` @@ -1495,7 +1505,7 @@ exit Internal BRCM information to be removed before sharing with the community. -Feature shall be supported on below mentioned platforms. +Feature shall be qualified on the below mentioned platforms. *AS4630* - 4 Core CPU - 8 GB RAM From 265bac72ecf372bce1ce34c3b8ac8df6bfd79a47 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Thu, 3 Jun 2021 17:28:32 +0530 Subject: [PATCH 36/47] review comments from Vissu --- L2/PAC/PortAccessControl.md | 386 ++++++++++++++++++++---------------- 1 file changed, 214 insertions(+), 172 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index c37b04421c0c..52713704a7e1 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.7 +High level design document version 0.8 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -116,6 +116,7 @@ High level design document version 0.7 | 0.5 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated requirements and functional description section | | 0.6 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated docker to macsec, added configuration, scalability and warmboot requirements | | 0.7 | 05/26/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | +| 0.8 | 06/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | # About this Manual This document describes the design details of the Port Access Control feature in SONiC. Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. @@ -129,7 +130,7 @@ This document describes the high level design details about Port Access Control ## Table 1 Abbreviations | **Term** | **Meaning** | | -------- | -------------------- | -| Authenticator | An entity that enforces authentication before allowing access to services available via that Port | +| Authenticator | An entity that enforces authentication on a port before allowing access to services available on that port | | CoPP | Control Plane Policing | | Dot1x | IEEE 802.1 standard | | EAPOL | Extensible Authentication Protocol over LAN | @@ -138,7 +139,7 @@ This document describes the high level design details about Port Access Control | PAE | Port Access Entity | | RADIUS | Remote Authentication Dial In User service | | SONiC-CLI | Klish CLI used by management framework | -| Supplicant | An entity that attempts to access services offered by the Authenticator | +| Supplicant | A client that attempts to access services offered by the Authenticator | # 1 Feature Overview @@ -253,8 +254,8 @@ Port Access Control provides a means of preventing unauthorized access by Suppli Access control is achieved by enforcing authentication of Supplicants that are attached to an Authenticator's controlled Ports. The result of the authentication process determines whether the Supplicant is authorized to access services on that controlled Port. A PAE is able to adopt one of two distinct roles within an access control interaction: -1. authenticator: A Port that enforces authentication before allowing access to services available via that Port. -2. supplicant: A Port that attempts to access services offered by the Authenticator. +1. authenticator: An entity that enforces authentication on a port before allowing access to services available on that port. +2. supplicant: A client that attempts to access services offered by the Authenticator. Additionally, there exists a third role: 3. authentication server: Performs the authentication function necessary to check the credentials of the Supplicant on behalf of the Authenticator. @@ -265,7 +266,7 @@ All three roles are required in order to complete an authentication exchange. ** The Authenticator is essentially a passthrough for the EAP method. The Supplicant and the RADIUS server exchange EAP messages which are encapsulated in either EAPOL or RADIUS frames (depending on the direction of the frame) by the Authenticator switch. The Authenticator determines the authorization status of the port based on RADIUS Access-Accept or Access-Reject frames. The Authenticator switch also needs to send and process all appropriate RADIUS attributes. For more information on these attributes, see the section [Authorization parameters](#3324-authorization-parameters). ### 2.2.2 Unidirectional and bidirectional control -The controlled directions dictate the degree to which protocol exchanges take place between Supplicant and Authenticator. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control directions are of two types: +The controlled directions (from the authenticator perspective) dictate the degree to which data traffic flow is controlled for an unauthenticated client. This affects whether the unauthorized controlled Port exerts control over communication in both directions (disabling both incoming and outgoing frames) or just in the incoming direction (disabling only the reception of incoming frames). The control directions are of two types: 1. Both: Control is exerted over both incoming and outgoing frames. 2. In: Control is only exerted over incoming traffic. @@ -273,11 +274,11 @@ The controlled directions dictate the degree to which protocol exchanges take pl ### 2.2.3 Downloadable ACL -PAC (Port access control) feature brings in DACL (downloadable ACL) support into SONiC. As a part of PAC, once a client on an access controlled port is authenticated, the external RADIUS server can send ACL attributes based on user profile configuration on the RADIUS server. These are called Downloadable ACL’s. IPv6 and IPv4 ACLs are supported for DACL. The downloadable ACL rules per client are sent in extended ACL syntax style. The switch applies the client specific DACL for the duration of the authenticated session. +Once a client on an access controlled port is authenticated, the external RADIUS server can send ACL attributes based on user profile configuration on the RADIUS server. These are called Downloadable ACL’s. IPv6 and IPv4 ACLs are supported for DACL. The downloadable ACL rules per client are sent in extended ACL syntax style. The switch applies the client specific DACL for the duration of the authenticated session. -The switch does not display RADIUS specified DACL’s in the running configuration. The ACL however shows up in the user interface show commands. Essentially, the DACL configuration is temporary (applied for the duration of the authenticated client session) and not persistent. The downloadable ACLs sent by RADIUS are in extended ACL syntax style and are validated just like user created ACLs. The ACLs created by the applications are owned by the internal application and hence cannot be deleted by a user. +The switch does not display RADIUS specified DACL’s in the running configuration. The ACL however shows up in the user interface show commands. The DACL configuration is only applied on the client-connected-port for the duration of the authenticated client session and is not persistent. The downloadable ACLs sent by RADIUS are in extended ACL syntax style and are validated just like user created ACLs. The DACLs on the switch are managed by the PAC application and hence cannot be deleted by the user. -Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However in certain situations, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. In situations where the client IP address changes, PAC gets to know about it via dhcp-snooping binding tables and the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. +Generally, any static ACLs (created by user) applied on the port are removed prior to applying the dynamic ACL on the port. Once the application created dynamic ACL is removed/deleted, the static ACLs is re-applied on the port. Essentially, static ACLs and dynamic ACLs are mutually exclusive. However if Open Authentication is configured on the port, the static ACLs and dynamic ACLs co-exist on the port. In such situations, the static ACLs have lower priority than the dynamic ACLs attached on the port. In situations where the client IP address changes, PAC gets to know about it via dhcp-snooping binding tables and the application created ACLs are automatically updated to accommodate the operational change like a changed client IP address. ### 2.2.4 Named ACLs @@ -296,7 +297,7 @@ PAC interacts with FDB to modify the learning mode of a port and add static FDB - Note that FDB entries thus added are not persistent and are operational config only (entries added as a result of the client getting authenticated). - The entries get removed once the client logs off. - FDB entries added operationally follows a similar config sequence like user created FDB entries. -- The learning mode of a port (or bridge port) was configured and controlled completely at the orchestration layer. With PAC, the application layer (pacd) also manages the learning mode to +- Prior to the introduction of PAC, the learning mode of a port (or bridge port) was configured and controlled completely at the orchestration layer. With PAC, the application layer (pacd) also manages the learning mode to 1. Once PAC is enabled on a port, all incoming traffic on the port are blocked/dropped except certain protocol traffic. 2. PAC turns off learning on the port essentially dropping all unknown source MAC packets. This achieves the requirement of blocking ingress traffic. 3. Egress traffic on the port is not blocked. @@ -371,69 +372,103 @@ PAC interacts with FDB to modify the learning mode of a port and add static FDB *PAC* ``` - "PAC_PORT_CONFIG_TABLE": { -"ethernet1": { -"method_list": [ -"802.1x", -"mab" -], -"priority_list": [ -"802.1x", -"mab" -], -"port_control_mode": "auto", -"host_control_mode": "multi_auth", -"quiet_period": 10, -"reauth_period": 60, -"reauth_enable": "true", -"max_users_per_port": 48, -"max_reauth_attempts": 1, -"guest_vlan": 10, -"auth_fail_vlan": 100 -} +"PAC_PORT_CONFIG_TABLE": { + "ethernet1": { + "method_list": [ + "802.1x", + "mab" + ], + "priority_list": [ + "802.1x", + "mab" + ], + "port_control_mode": "auto", + "host_control_mode": "multi_auth", + "quiet_period": 10, + "reauth_period": 60, + "reauth_enable": "true", + "max_users_per_port": 48, + "max_reauth_attempts": 1, + "guest_vlan": 10, + "auth_fail_vlan": 100, + "open_authentication_mode": "disabled", + "dead_server_action": "reinitialize", + "dead_server_alive_action": "reinitialize", + "dead_server_critical_vlan": 200, + "dead_server_action_voice": "authorize" + } } -key = PAC_PORT_CONFIG_TABLE:port ; Physical port -;field = value -method_list = "dot1x"/"mab" ; List of methods to be used for authentication -priority_list = "dot1x"/"mab"; Relative priority of methods to be used for authentication -port_control_mode = "auto"/"force_authorized"/"force_unauthorized"; Port control mode - ; 'auto": authentication enforced on port - ; 'force_authorized": authentication not enforced on port - ; 'force_unauthorized": authentication not enforced on port but port is blocked for all traffic - -host_control_mode = "multi-host"/"multi-domain"/"multi-auth"/"single-auth" ; Host control mode - ; "multi-host": One data client can be authenticated on the port. Rest of the clients tailgate once the first client is authenticated. - ; "multi-domain": One data client and one voice client can be authenticated on the port. - ; "multi-auth": Multiple data client and one voice client can be authenticated on the port. - ; "single-auth": One data client or one voice client can be authenticated on the port. - -quiet_period = 1*5DIGIT ; The initial value of the timer that defines the period during which the Authenticator will not attempt to authenticate the Supplicant. Range is 0-65535 seconds. -reauth_period = 1*10DIGIT;The initial value of the timer that defines the period after which the Authenticator will reauthenticate the Supplicant. Range is 3600 - 4294967296 seconds. -reauth_enable = "true"/"false";Indicates whether Reauthentication is enabled on the port. -max_users_per_port=1*2DIGIT; Maximum number of clients that can be authenticated on the port. This is applicable only for "multi-auth" host mode.Range is 1 - 64 clients. -guest_vlan_id= 1*4DIGIT;The Guest VLAN Id for the port. Range is 1 - 4093 -auth_fail_vlan_id=1*4DIGIT;The Authentication Fail VLAN Id for the port. Range is 1 - 4093 -max_auth_attempts=1DIGIT;The maximum number of authentication retries in the event of authentication failure.Range is 1 - 5 -``` +key = PAC_PORT_CONFIG_TABLE:port ;Physical port + +;field = value + +method_list = "dot1x"/"mab" ;List of methods to be used for authentication + +priority_list = "dot1x"/"mab" ;Relative priority of methods to be used for authentication + +port_control_mode = "auto"/"force_authorized"/ 'auto": authentication enforced on port + "force_unauthorized" ; 'force_authorized": authentication not enforced on port + 'force_unauthorized": authentication not enforced on port but port is blocked for all traffic + +host_control_mode = "multi-host"/"multi-domain"/ ;"multi-host": One data client can be authenticated on the port. Rest of the + "multi-auth"/"single-auth" clients tailgate once the first client is authenticated. + "multi-domain": One data client and one voice client can be authenticated on the port. + "multi-auth": Multiple data client and one voice client can be authenticated on the port. + "single-auth": One data client or one voice client can be authenticated on the port. + +quiet_period = 1*5DIGIT ;The initial value of the timer that defines the period during which the + Authenticator will not attempt to authenticate the Supplicant. + Range is 0-65535 seconds. + +reauth_period = 1*10DIGIT ;The initial value of the timer that defines the period after which the will + reauthenticate the Supplicant. Range is 3600 - 4294967296 seconds. -``` -"PAC_GLOBAL_CONFIG_TABLE": { -"authentication_enable": "true", -"monitor_mode_enable": "false" -} - -;field=value -authentication_enable = "true"/"false";Indicates whether PAC is enabled in the system. -monitor_mode_enable = "true"/"false";Indicates whether monitor mode is enabled in the system. +reauth_enable = "true"/"false" ;Indicates whether Reauthentication is enabled on the port. + +max_users_per_port = 1*2DIGIT ;Maximum number of clients that can be authenticated on the port. This is applicable + only for "multi-auth" host mode. Range is 1 - 64 clients. + +guest_vlan_id = 1*4DIGIT ;The Guest VLAN Id for the port.Range is 1 - 4093 + +auth_fail_vlan_id = 1*4DIGIT ;The Authentication Fail VLAN Id for the port.Range is 1 - 4093 + + +max_auth_attempts = 1DIGIT ;The maximum number of authentication retries in the event of authentication + failure. Range is 1 - 5 + +open_authentication_mode = "enable"/"disable" ;Indicates whether Open Authentication mode is enabled on the port. + + +dead_server_action = "none"/"reinitialize"/"authorize" ;Indicates action to be taken for data clients when all configured RADIUS + servers are marked Dead. + +dead_server_alive_action =“none”/"reinitialize" ;Indicates action to be taken for date clients when one of the configured RADIUS + servers is marked Alive after all were marked Dead. + +dead_server_critical_vlan = 1*4DIGIT ;The Critical (data) VLAN Id for the port.Range is 1 - 4093 + +dead_server_action_voice = “none”/”authorize" ;Indicates action to be taken for voice clients when all configured RADIUS servers are marked Dead. + + + + +"PAC_GLOBAL_CONFIG_TABLE": {"authentication_enable": "true","monitor_mode_enable": "false"} + + +;field = value + +authentication_enable = "true"/"false" ;Indicates whether PAC is enabled in the system. + +monitor_mode_enable = "true"/"false" ;Indicates whether monitor mode is enabled in the system. ``` *hostapd* ``` -" HOSTAPD_GLOBAL_CONFIG_TABLE ": { -"dot1x_system_auth_control": "enable" +"HOSTAPD_GLOBAL_CONFIG_TABLE ": { + "dot1x_system_auth_control": "enable" } ;field = value @@ -449,36 +484,37 @@ None ### 3.2.4 Counter DB ``` -"HOST_APD_STATS_TABLE": [{ -"00:00:00:11:22:33": { -"dot1xAuthEapolFramesRx": 311, -"dot1xAuthEapolFramesTx": 380, -"dot1xAuthEapolStartFramesRx": 71, -"dot1xAuthEapolLogoffFramesRx": 15, -"dot1xAuthEapolRespIdFramesRx": 67, -"dot1xAuthEapolRespFramesRx": 212, -"dot1xAuthEapolReqIdFramesTx": 250, -"dot1xAuthEapolReqFramesTx": 250, -"dot1xAuthInvalidEapolFramesRx": 250, -"dot1xAuthEapLengthErrorFramesRx": 250, -"dot1xAuthLastEapolFrameVersion": 2 -} -}, -{ -"00:00:00:22:22:34": { -"dot1xAuthEapolFramesRx": 311, -"dot1xAuthEapolFramesTx": 380, -"dot1xAuthEapolStartFramesRx": 71, -"dot1xAuthEapolLogoffFramesRx": 15, -"dot1xAuthEapolRespIdFramesRx": 67, -"dot1xAuthEapolRespFramesRx": 212, -"dot1xAuthEapolReqIdFramesTx": 250, -"dot1xAuthEapolReqFramesTx": 250, -"dot1xAuthInvalidEapolFramesRx": 250, -"dot1xAuthEapLengthErrorFramesRx": 250, -"dot1xAuthLastEapolFrameVersion": 2 -} -} +"HOST_APD_STATS_TABLE": [ + { + "00:00:00:11:22:33": { + "dot1xAuthEapolFramesRx": 311, + "dot1xAuthEapolFramesTx": 380, + "dot1xAuthEapolStartFramesRx": 71, + "dot1xAuthEapolLogoffFramesRx": 15, + "dot1xAuthEapolRespIdFramesRx": 67, + "dot1xAuthEapolRespFramesRx": 212, + "dot1xAuthEapolReqIdFramesTx": 250, + "dot1xAuthEapolReqFramesTx": 250, + "dot1xAuthInvalidEapolFramesRx": 250, + "dot1xAuthEapLengthErrorFramesRx": 250, + "dot1xAuthLastEapolFrameVersion": 2 + } + }, + { + "00:00:00:22:22:34": { + "dot1xAuthEapolFramesRx": 311, + "dot1xAuthEapolFramesTx": 380, + "dot1xAuthEapolStartFramesRx": 71, + "dot1xAuthEapolLogoffFramesRx": 15, + "dot1xAuthEapolRespIdFramesRx": 67, + "dot1xAuthEapolRespFramesRx": 212, + "dot1xAuthEapolReqIdFramesTx": 250, + "dot1xAuthEapolReqFramesTx": 250, + "dot1xAuthInvalidEapolFramesRx": 250, + "dot1xAuthEapLengthErrorFramesRx": 250, + "dot1xAuthLastEapolFrameVersion": 2 + } + } ] key = HOST_APD_STATS_TABLE : client mac; Client MAC @@ -502,81 +538,91 @@ dot1xAuthLastEapolFrameVersion = 1*10DIGIT ; The protocol version number carrie *PAC* ``` " PAC_PORT_OPER_TABLE ": { -"ethernet1": { -"enabled_method_list": [ -"802.1x", -"mab" -], -"enabled_priority_list": [ -"802.1x", -"mab" -], -"num_clients_authenticated": 10 -} + "ethernet1": { + "enabled_method_list": [ + "802.1x", + "mab" + ], + "enabled_priority_list": [ + "802.1x", + "mab" + ], + "num_clients_authenticated": 10, + "open_authentication_mode": "enabled", + "dead_server_action": "reinitialize", + "dead_server_alive_action": "reinitialize", + "dead_server_critical_vlan": 200, + "dead_server_action_voice": "authorize" + } } -key = PAC_PORT_OPER_TABLE : port ; Physical port -;field = value -enabled_method_list = "dot1x"/"mab" ; List of methods to be used for authentication -enabled_priority_list = "dot1x"/"mab" ; Relative priority of methods to be used for authentication -num_clients_authenticated = 1*2DIGIT ; Number of clients authenticated on the port. +key = PAC_PORT_OPER_TABLE:port ;Physical port + +;field = value + +enabled_method_list = "dot1x"/"mab" ;List of methods to be used for authentication +enabled_priority_list = "dot1x"/"mab" ;Relative priority of methods to be used for authentication +num_clients_authenticated = 1*2DIGIT ;Number of clients authenticated on the port. + +open_authentication_mode = "enabled"/"disabled" ;Indicates if open authentication mode is enabled on the port. + +dead_server_action = "none"/"reinitialize"/"authorize" ;Indicates action to be taken for data clients when all configured + RADIUS servers are marked Dead. + +dead_server_alive_action = “none”/"reinitialize" ;Indicates action to be taken for date clients when one of the + configured RADIUS servers is marked Alive after all were marked Dead. + +dead_server_critical_vlan = 1*4DIGIT ;The Critical (data) VLAN Id for the port.Range is 1 - 4093 + +dead_server_action_voice = “none”/”authorize" ;Indicates action to be taken for voice clients when all configured + RADIUS servers are marked Dead. ``` ``` -" PAC_AUTHENTICATED_CLIENT_OPER_TABLE ": { -"ethernet1": [{ -"00:00:00:11:02:33": { -"current_id": 21, -"auth_status": "authorized", -"authenticated_method": "802.1X", -"server_state": "36 34 43 50 4d 53 65 73 73 69 6f 6e 49 44 3d 30 61 38 32 62 39 37 36 4c 49 -50 5a 44 45 4d 32 74 64 35 55 39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d -6e 4a 33 31 42 6a 5a 34 51 49 3b 33 34 53 65 73 73 69 6f 6e 49 44 3d 43 69 73 63 6f 49 53 45 -2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35 3b", -"server_state_len": 106, -"server_class": "43 41 43 53 3a 30 61 38 32 62 39 37 36 4c 49 50 5a 44 45 4d 32 74 64 35 55 -39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d 6e 4a 33 31 42 6a 5a 34 51 49 -3a 43 69 73 63 6f 49 53 45 2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35", -"server_class_len": 83, -"session_timeout": 60, -"user_name": "sonic_user", -"user_name_len": 9, -"termination_action": 0, -"vlan_id": 194, -"vlan_type": "radius", -"backend_auth_method": "radius", -"session_time": 511 -} -}, -{ -"00:00:00:21:00:30": { -"current_id": 28, -"auth_status": "authorized", -"authenticated_method": "802.1X", -"server_state": "36 34 43 50 4d 53 65 73 73 69 6f 6e 49 44 3d 30 61 38 32 62 39 37 36 4c 49 -50 5a 44 45 4d 32 74 64 35 55 39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d -6e 4a 33 31 42 6a 5a 34 51 49 3b 33 34 53 65 73 73 69 6f 6e 49 44 3d 43 69 73 63 6f 49 53 45 -2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35 3b", -"server_state_len": 106, -"server_class": "43 41 43 53 3a 30 61 38 32 62 39 37 36 4c 49 50 5a 44 45 4d 32 74 64 35 55 -39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d 6e 4a 33 31 42 6a 5a 34 51 49 -3a 43 69 73 63 6f 49 53 45 2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35", -"server_class_len": 83, -"session_timeout": 60, -"user_name": "sonic_user1", -"user_name_len": 9, -"termination_action": 0, -"vlan_id": 194, -"vlan_type": "radius", -"backend_auth_method": "radius", -"session_time": 51 -} +"PAC_AUTHENTICATED_CLIENT_OPER_TABLE": { + "ethernet1": [ + { + "00:00:00:11:02:33": { + "current_id": 21, + "auth_status": "authorized", + "authenticated_method": "802.1X", + "server_state": "36 34 43 50 4d 53 65 73 73 69 6f 6e 49 44 3d 30 61 38 32 62 39 37 36 4c 49 50 5a 44 45 4d 32 74 64 35 55 39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d 6e 4a 33 31 42 6a 5a 34 51 49 3b 33 34 53 65 73 73 69 6f 6e 49 44 3d 43 69 73 63 6f 49 53 45 2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35 3b", + "server_state_len": 106, + "server_class": "43 41 43 53 3a 30 61 38 32 62 39 37 36 4c 49 50 5a 44 45 4d 32 74 64 35 55 39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d 6e 4a 33 31 42 6a 5a 34 51 49 3a 43 69 73 63 6f 49 53 45 2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35", + "server_class_len": 83, + "session_timeout": 60, + "user_name": "sonic_user", + "user_name_len": 9, + "termination_action": 0, + "vlan_id": 194, + "vlan_type": "radius", + "backend_auth_method": "radius", + "session_time": 511 + } + }, + { + "00:00:00:21:00:30": { + "current_id": 28, + "auth_status": "authorized", + "authenticated_method": "802.1X", + "server_state": "36 34 43 50 4d 53 65 73 73 69 6f 6e 49 44 3d 30 61 38 32 62 39 37 36 4c 49 50 5a 44 45 4d 32 74 64 35 55 39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d 6e 4a 33 31 42 6a 5a 34 51 49 3b 33 34 53 65 73 73 69 6f 6e 49 44 3d 43 69 73 63 6f 49 53 45 2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35 3b", + "server_state_len": 106, + "server_class": "43 41 43 53 3a 30 61 38 32 62 39 37 36 4c 49 50 5a 44 45 4d 32 74 64 35 55 39 44 31 4c 37 43 56 44 37 5a 48 56 44 4f 70 74 4a 47 6b 7a 4d 6e 4a 33 31 42 6a 5a 34 51 49 3a 43 69 73 63 6f 49 53 45 2f 33 33 32 35 38 39 38 35 33 2f 38 36 36 33 35", + "server_class_len": 83, + "session_timeout": 60, + "user_name": "sonic_user1", + "user_name_len": 9, + "termination_action": 0, + "vlan_id": 194, + "vlan_type": "radius", + "backend_auth_method": "radius", + "session_time": 51 + } + } + ] } -] -} - key = PAC_AUTHENTICATED_CLIENTS_OPER_TABLE: mac ; Client MAC address ;field = value ; @@ -880,7 +926,7 @@ If the client succeeds authentication, the authorization parameters from RADIUS #### 3.3.3 mabd mabd provides the Mac-based Authentication Bypass(MAB) functionality. MAB is intended to provide 802.1x unaware clients controlled access to the network using the devices’ MAC address as an identifier. This requires that the known and allowable MAC address and corresponding access rights be pre-populated in the authentication server. -Today, 802.1x has become the recommended port-based authentication method at the access layer in enterprise networks. However, there may be 802.1x unaware devices such as printers, fax-machines etc that would require access to the network without 802.1x authentication. MAB is a supplemental authentication mechanism to allow 802.1x unaware clients to authenticate to the network. SONiC supported authentication methods are as below: +MAB is a supplemental authentication mechanism to allow 802.1x unaware clients to authenticate to the network. SONiC supported authentication methods for mab are as given below: - CHAP - EAP-MD5 - PAP @@ -941,7 +987,7 @@ Since Openconfig models are not available, Openconfig dot1x and mab are propriet The following commands are used to configure PAC. #### 3.6.2.1 authentication enable -This command enables PAC feature globally. By default the value is disabled. If enabled only, the configuration on the interface would take effect. +This command enables PAC feature globally. By default the feature is disabled. Any interface PAC configuration is effective only when PAC is enabled globally. | Mode | Global Config | | ---- | ------ | @@ -1433,7 +1479,9 @@ All processing errors will be captured in syslog. Debug command output will be captured as part of tech support for offline analysis. # 7 Warm Boot Support -Configured actions and counters should continue to work across warm reboot. +- Configured actions and counters continue to work across warm reboot. +- Already authenticated sessions continues to work. +- Authentication is restarted for the Clients being authenticated at the time of warmboot. # 8 Scalability @@ -1453,13 +1501,7 @@ The following is the support scale for Port Access Control. The following number - SONiC PAC allows only unidirectional (In) control where the incoming traffic is blocked while the port is not authenticated. PAC does not have any control on traffic egressing out of the port. -- Authentication Manager does not make any required configuration for the respective methods to authenticate successfully. The administrator needs to ensure that the correct and appropriate configuration is present in the system. For example, if the authentication order method includes the 802.1x port authentication method, 802.1X should be enabled for the authentication to succeed. Authentication manager will not enable/disable and make the configurations related to 802.1X. Administrator should make the necessary configurations. - -- In the default configuration, all traffic that is not EAP over LAN (EAPoL) traffic (including DHCP) is dropped until 802.1X and MAB times out. Therefore, the value of the timeout can significantly affect the DHCP client on the end host. Longer 802.1X timeouts may prevent DHCP from functioning correctly after the 802.1X timeout expires. - -- To prevent DHCP clients from timing out, SONiC recommends testing the DHCP clients in respective network to discover how long they take to time out and setting the 802.1X timers accordingly. - -- After configuration Save and reload, if the session Id in the PDU, that is sent by the client doesn’t match with the session Id expected by the 802.1X, then the received PDU is ignored and SONiC will re-try for 802.1X authentication. If the PDU is processed and the authentication fails or times out, then only the authentication moves to the next method. +- Authentication Manager does not automatically apply any additional configuration for the respective authentication methods to authenticate successfully. The administrator needs to ensure that the correct and appropriate configuration is present in the system. For example, if the authentication order method includes the 802.1x port authentication method, 802.1X should be enabled for the authentication to succeed. Authentication manager will not enable/disable and make the configurations related to 802.1X. Administrator should make the necessary configurations. - Authentication Manager cannot be enabled on LAG interfaces. Enabling Authentication Manager on ports which are member of LAGs or including an Unauthorized port into a LAG will result in unpredictable results. @@ -1488,7 +1530,7 @@ configure authentication enable aaa authentication dot1x default radius -interface 1/0/1 +interface 1/1 authentication order dot1x mab authentication priority dot1x mab authentication host-mode multi-auth From ffa61b1567953a154caf5ef9f8f825bfa5a3b730 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Thu, 3 Jun 2021 17:43:55 +0530 Subject: [PATCH 37/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 51 +++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 19 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 52713704a7e1..1da0ce295238 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -370,7 +370,7 @@ PAC interacts with FDB to modify the learning mode of a port and add static FDB ### 3.2.1 Config DB -*PAC* +**PAC_PORT_CONFIG_TABLE** ``` "PAC_PORT_CONFIG_TABLE": { "ethernet1": { @@ -451,9 +451,10 @@ dead_server_critical_vlan = 1*4DIGIT ;The Critical (d dead_server_action_voice = “none”/”authorize" ;Indicates action to be taken for voice clients when all configured RADIUS servers are marked Dead. +``` - - +**PAC_GLOBAL_CONFIG_TABLE** +``` "PAC_GLOBAL_CONFIG_TABLE": {"authentication_enable": "true","monitor_mode_enable": "false"} @@ -463,14 +464,15 @@ authentication_enable = "true"/"false" ;Indicates whether PAC i monitor_mode_enable = "true"/"false" ;Indicates whether monitor mode is enabled in the system. -``` - -*hostapd* +``` + +**HOSTAPD_GLOBAL_CONFIG_TABLE** ``` -"HOSTAPD_GLOBAL_CONFIG_TABLE ": { +"HOSTAPD_GLOBAL_CONFIG_TABLE": { "dot1x_system_auth_control": "enable" } + ;field = value dot1x_system_auth_control "true"/"false" ; Indicates whether dot1x is enabled in the system. ``` @@ -483,6 +485,7 @@ None ### 3.2.4 Counter DB +**HOST_APD_STATS_TABLE** ``` "HOST_APD_STATS_TABLE": [ { @@ -517,6 +520,7 @@ None } ] + key = HOST_APD_STATS_TABLE : client mac; Client MAC ;field = value dot1xAuthEapolFramesRx = 1*10DIGIT ; The number of valid EAPOL frames of any type that have been received by this Authenticator. @@ -535,9 +539,9 @@ dot1xAuthLastEapolFrameVersion = 1*10DIGIT ; The protocol version number carrie ### 3.2.5 State DB -*PAC* +**PAC_PORT_OPER_TABLE** ``` -" PAC_PORT_OPER_TABLE ": { +"PAC_PORT_OPER_TABLE": { "ethernet1": { "enabled_method_list": [ "802.1x", @@ -556,6 +560,7 @@ dot1xAuthLastEapolFrameVersion = 1*10DIGIT ; The protocol version number carrie } } + key = PAC_PORT_OPER_TABLE:port ;Physical port ;field = value @@ -578,8 +583,10 @@ dead_server_action_voice = “none”/”authorize" ;Indic RADIUS servers are marked Dead. -``` +``` + +**PAC_AUTHENTICATED_CLIENT_OPER_TABLE** ``` "PAC_AUTHENTICATED_CLIENT_OPER_TABLE": { "ethernet1": [ @@ -624,6 +631,7 @@ dead_server_action_voice = “none”/”authorize" ;Indic ] } + key = PAC_AUTHENTICATED_CLIENTS_OPER_TABLE: mac ; Client MAC address ;field = value ; current_id = 1*3DIGIT ; EAP Packet Id @@ -653,9 +661,9 @@ session_time = 1*10DIGIT ; Client session time. ``` - +**PAC_CLIENT_HISTORY_TABLE** ``` -" PAC_CLIENT_HISTORY_TABLE ": { +"PAC_CLIENT_HISTORY_TABLE": { "ethernet1": [{ "31-March-2021-13:46:02": { "client_mac_addr": "00:00:00:11:22:33", @@ -676,15 +684,16 @@ session_time = 1*10DIGIT ; Client session time. } -key = PAC_CLIENT_HISTORY_TABLE : port ; Physical Port Clientmac; Client MAC address +key = PAC_CLIENT_HISTORY_TABLE : port : date ; Physical Port Clientmac; Client MAC address ; Date ;field = value +client_mac_addr = ; Client MAC address authentication_method = "802.1x"/'mab" ; Method used to authenticate the client -backend_auth_method = "radius" ; Backend authentication method used to authorize the client. -auth_status = "authorized"/"unauthorized" ; Authorization status of the client +backend_auth_method = "radius" ; Backend authentication method used to authorize the client. +auth_status = "authorized"/"unauthorized" ; Authorization status of the client -``` +``` -*hostapd* +**HOSTAPD_OPER_PORT_TABLE** ``` "HOSTAPD_OPER_PORT_TABLE": [{ "ethernet1": { @@ -698,7 +707,6 @@ auth_status = "authorized"/"unauthorized" ; Authorization status of the client }] - key = HOSTAPD_OPER_PORT_TABLE : port ; Physical Port ;field = value protocol_version = 1DIGIT ; Dot1x protocol version @@ -710,7 +718,10 @@ server_timeout = 1*5DIGIT ; RADIUS server timeout max_reqs = 1*5DIGIT ; Maximum number of EAP requests (except Req-Ids) to be sent to the supplicant before timing out. max_req_id = 1*5DIGIT ; Maximum number of EAP Req-Ids to be sent to the supplicant before timing out. -``` +``` + + +**HOSTAPD_CLIENT_OPER_TABLE** ``` "HOSTAPD_CLIENT_OPER_TABLE": { @@ -726,6 +737,8 @@ max_req_id = 1*5DIGIT ; Maximum number of EAP Req-Ids to be sent to the s } ] } + + key = HOSTAPD_OPER_PORT_TABLE : port ; Physical Port: client mac; Client MAC ;field = value user_name = 1*255VCHARS ; Client user name From 83330ff8cce8a802065d664885450b70dc116e01 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Thu, 3 Jun 2021 18:21:06 +0530 Subject: [PATCH 38/47] added no command syntax --- L2/PAC/PortAccessControl.md | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 1da0ce295238..6ae0ea80d351 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1004,7 +1004,7 @@ This command enables PAC feature globally. By default the feature is disabled. A | Mode | Global Config | | ---- | ------ | -| Syntax | authentication enable | +| Syntax | [no] authentication enable | | Default | disable | | Change history | SONiC 4.0 - Introduced | @@ -1013,7 +1013,7 @@ This command configures the number of supplicants that are re-authenticated per | Mode | Global Config | | ---- | ------ | -| Syntax | authentication critical recovery max-reauth | +| Syntax | [no] authentication critical recovery max-reauth | | Default | 10 | | Change history | SONiC 4.0 - Introduced | @@ -1024,7 +1024,7 @@ This command enables the Authentication monitor mode on the switch. The purpose | Mode | Global Config | | ---- | ------ | -| Syntax | authentication monitor | +| Syntax | [no] authentication monitor | | Default | disable | | Change history | SONiC 4.0 - Introduced | @@ -1037,6 +1037,7 @@ This command configures the authentication method for port-based access to the s | ---- | ------ | | Syntax | aaa authentication pac \{ radius \| none \} | | Default | radius | +| Syntax | no aaa authentication pac | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.5 mab request format attribute 1 @@ -1048,13 +1049,14 @@ This command sets configuration parameters that are used to format attribute1 fo | Default | group size=2 | | Default | separator is : | | Default | uppercase | +| Syntax | no mab request format attribute 1 | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.6 dot1x system-auth-control This command enables the dot1x authentication support on the switch. While disabled, the dot1x configuration is retained and can be changed, but is not activated. | Mode | Global Config | | ---- | ------ | -| Syntax | dot1x system-auth-control | +| Syntax | [no] dot1x system-auth-control | | Default | disable | | Change history | SONiC 4.0 - Introduced | @@ -1066,6 +1068,7 @@ This command configures VLAN as guest vlan on an interface or a range of interfa | ---- | ------ | | Syntax | authentication event no-response action authorize vlan \ | | Default | 0 | +| Syntax | no authentication event no-response | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.8 authentication event fail action authorize vlan @@ -1075,6 +1078,7 @@ This command configures the unauthenticated VLAN associated with the specified i | ---- | ------ | | Syntax | authentication event fail action authorize vlan \ | | Default | 0 | +| Syntax | no authentication event fail action authorize vlan | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.9 authentication event fail retry @@ -1084,6 +1088,7 @@ This command configures the number of times authentication may be reattempted b | ---- | ------ | | Syntax | authentication event fail retry \ | | Default | 3 | +| Syntax | no authentication event fail retry | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.10 authentication max-users @@ -1093,6 +1098,7 @@ This command sets the maximum number of clients supported on an interface or ran | ---- | ------ | | Syntax | authentication max-users \ | | Default | 48 | +| Syntax | no authentication max-users | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.11 authentication periodic @@ -1100,7 +1106,7 @@ This command enables periodic reauthentication of the supplicant for the specifi | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication periodic | +| Syntax | [no] authentication periodic | | Default | Disabled | | Change history | SONiC 4.0 - Introduced | @@ -1111,6 +1117,7 @@ This command sets the authentication mode to use on the specified interface or r | ---- | ------ | | Syntax | authentication port-control \{ auto \| force-authorized \| force-unauthorized \} | | Default | auto | +| Syntax | no authentication port-control | | Change history | SONiC 4.0 - Introduced #### 3.6.2.13 authentication host-mode @@ -1120,6 +1127,7 @@ This command configures the host mode of a port. The configuration on the interf | ---- | ------ | | Syntax | authentication host-mode \{ multi-auth \| multi-domain \| multi-host \| single-host \} | | Default | multi-host | +| Syntax | no authentication host-mode | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.14 authentication timer reauthentiate @@ -1131,6 +1139,7 @@ For reauthentication to happen after the configured or server provided timeout, | ---- | ------ | | Syntax | authentication timer reauthenticate \{ \ \| server \} | | Default | server | +| Syntax | no authentication timer reauthenticate | | Change history | SONiC 4.0 - Introduced | @@ -1142,6 +1151,7 @@ This command configures the actions to take when all the authentication servers | Syntax | authentication event server dead action \[ \{ reinitialize \| authorize \} \] \[ vlan vlan-id \] \] | | Default | Action: None | | Default | VLAN: Port PVID | +| Syntax | no authentication event server dead action | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.16 authentication event server dead action authorize voice @@ -1151,6 +1161,7 @@ This command enables authorization of voice devices on the critical voice VLAN w | ---- | ------ | | Syntax | authentication event server dead action authorize voice | | Default | Action: None | +| Syntax | no authentication event server dead action authorize | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.17 authentication event server alive action reinitialize @@ -1160,6 +1171,7 @@ This command configures the actions to take when one authentication server comes | ---- | ------ | | Syntax | authentication event server alive action reinitialize | | Default | Action: None | +| Syntax | no authentication event server alive action | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.18 authentication open @@ -1167,7 +1179,7 @@ This command configures Open Authentication mode on the port. | Mode | Interface Config | | ---- | ------ | -| Syntax | authentication open | +| Syntax | [no] authentication open | | Default | Disabled | | Change history | SONiC 4.0 - Introduced | @@ -1178,6 +1190,7 @@ This command is used to set the order of authentication methods used on a port. | ---- | ------ | | Syntax | authentication order \{ dot1x \[ mab \] \| mab \[ dot1x \] \} | | Default order | dot1x, mab | +| Syntax | no authentication order | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.20 authentication priority @@ -1187,6 +1200,7 @@ This command is used to set the priority for the authentication methods used on | ---- | ------ | | Syntax | authentication priority \{ dot1x \[ mab \] \| mab \[ dot1x \] \} | | Default order | dot1x, mab | +| Syntax | no authentication priority | | Change history | SONiC 4.0 - Introduced | #### 3.6.2.21 mab @@ -1194,7 +1208,7 @@ This command is used to enable MAC Authentication Bypass (MAB) on an interface. | Mode | Interface Config | | ---- | ------ | -| Syntax | mab \[ auth-type \{ pap \| eap-md5 \} \| chap \] | +| Syntax | [no] mab \[ auth-type \{ pap \| eap-md5 \} \| chap \] | | Default | Disabled | | Change history | SONiC 4.0 - Introduced | @@ -1211,7 +1225,7 @@ This command sets the value, in seconds, of the timers used by the authenticator | Mode | Interface Config | | ---- | ------ | -| Syntax | dot1x timeout \{ quiet-period \| tx-period \| server-timeout \| supp-timeout \| auth-period \| start-period \| held-period \} | +| Syntax | [no] dot1x timeout \{ quiet-period \| tx-period \| server-timeout \| supp-timeout \| auth-period \| start-period \| held-period \} | | Default | quiet-period: 60 seconds | | Default | tx-period: 30 seconds | | Default | supp-timeout: 30 seconds | From 4202db7f4903a4db9eae572b72c6d91822a8a548 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Thu, 3 Jun 2021 18:23:40 +0530 Subject: [PATCH 39/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 6ae0ea80d351..f90f8389c216 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1372,12 +1372,14 @@ Example: (dhcp-10-130-86-200) #show authentication clients all -(dhcp-10-130-86-142) (Interface 0/10)#show authentication clients all +(dhcp-10-130-86-142) (Interface 1/16)#show authentication clients all Interface MAC-Address Method Host Mode Control Mode VLAN Assigned Reason --------- ----------------- ------- ------------ ------------ -------------------------- -0/16 10:8D:B6:C6:00:00 802.1X multi-host auto RADIUS Assigned VLAN (10) +1/16 10:8D:B6:C6:00:00 802.1X multi-host auto RADIUS Assigned VLAN (10) + + (dhcp-10-130-86-200) #show authentication clients interface 1/2 Mac Address.................................... 58:05:94:1C:00:00 From 97d61a25359a0eb6eec2a4f14fd10b2ff2b1faf2 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Fri, 4 Jun 2021 13:59:14 +0530 Subject: [PATCH 40/47] added section 3.3.6 fpinfra Library --- L2/PAC/PortAccessControl.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index f90f8389c216..ec8e9c384a6d 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -51,8 +51,9 @@ High level design document version 0.8 - [3.3.3 mabd](#333-mabd) - [3.3.4 hostapd](#334-hostapd) - [3.3.5 hostapd](#335-hostapdmgr) - - [3.3.6 Other Process](#336-other-process) - - [3.3.7 Interaction between pacd hostapd and mabd](#337-interaction-between-pacd-hostapd-and-mabd) + - [3.3.6 fpinfra Library](#336-fpinfra-library) + - [3.3.7 Other Process](#337-other-process) + - [3.3.8 Interaction between pacd hostapd and mabd](#338-interaction-between-pacd-hostapd-and-mabd) - [3.4 SyncD](#34-syncd) - [3.5 SAI](#35-sai) - [3.6 Manageability](#36-manageability) @@ -963,11 +964,31 @@ Hostapd is an open source implementation of 802.1x standard and the Linux applic ### 3.3.5 hostapdmgr hostapdmgr reads hostapd specific configuration from SONiC DBs and populates the hostapd.conf. It further notifies the hostapd to re-read the configuration file. -### 3.3.6 Other Process +### 3.3.6 fpinfra Library +fpInfra provides OS layer and Network layer abstractions for authentication manager and mab modules. It is implemented as a shared library *libfpinfra.so* and can be included in C or C++ applications. Only one instance of the library can run in a program (Linux process).  The library needs to be initialized via the ``` int fpinfraInit(void) ``` API before making any fpinfra API calls. During fpinfra library initialization, it starts multiple threads (fpinfraTask, nimHpcTask, osapiTimerHandler) to achieve the functionality. The major modules of fpinfra are as given below: + + - Network Interface Manager (NIM) + - osapi Layer (memory, string, network) + - sysapi Layer + - Semaphore + - Message Queue + - SLL + - Timer + - AVL + - Buffer Pool + - Task creation / deletion + - osapiTimer + - Configurator + - resource constants + +The fpinfra(nim) listens to netlink notifications from the kernel, translates them to respective NIM events and delivers them to the registered applications via callbacks. + +### 3.3.7 Other Process + No change to other process. -### 3.3.7 Interaction between pacd hostapd and mabd +### 3.3.8 Interaction between pacd hostapd and mabd *hostapd(802.1X)* From 6ef50fbd229799ff512e67add8ff875daee4cfb6 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Fri, 4 Jun 2021 23:03:32 +0530 Subject: [PATCH 41/47] update configuration requirement. --- L2/PAC/PortAccessControl.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index ec8e9c384a6d..d112f170b36c 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -208,11 +208,30 @@ The following are the requirements for Port Access Control feature: ### 1.3.2 Configuration and Management Requirements -This feature supports CLI and REST based configurations. -1. Support CLI configurations as mentioned in section 3.6.2 -2. Support show commands as mentioned in section 3.6.3 -3. Support debug commands as mentioned in section 3.6.4 -4. Support REST APIs for config and operational data +This feature shall support CLI and REST based configurations. + +List of configuration shall include the following: +- enable PAC feature globally. +- configure the number of supplicants that are re-authenticated per second. +- enable the Authentication monitor mode on the switch. +- configure the authentication method for port-based access to the switch. +- configuration parameters that needed to format attribute1 for MAB requests to the RADIUS server. +- enable the dot1x authentication support on the switch. +- configure VLAN as guest vlan on an interface or a range of interfaces. +- configure the unauthenticated VLAN associated with the specified interface or range of interfaces. +- configure the number of times authentication may be reattempted by the client before a port moves to the authentication fail VLAN. +- set the maximum number of clients supported on an interface or range of interfaces when multi-authentication host mode is enabled on the port. +- enable periodic reauthentication of the supplicant for the specified interface or range of interfaces. +- set the authentication mode to use on the specified interface or range of interfaces. +- configure the host mode of a port. +- configure the period of time after which the Authenticator attempts to reauthenticate a supplicant on the port. +- configure the actions to take when all the authentication servers are dead. +- enable authorization of voice devices on the critical voice VLAN when all the authentication servers are dead. +- configure the actions to take when one authentication server comes back alive after all were dead. +- configure Open Authentication mode on the port. +- set the order of authentication methods used on a port. +- set the priority for the authentication methods used on a port. +- enable MAC Authentication Bypass (MAB) on an interface. ### 1.3.3 Scalability Requirements 1. 48 clients per port, with a maxmimum of 512 clients per switch From 6ab3012799f738f9ab0d671b410e2e18045f229d Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Fri, 9 Jul 2021 13:11:37 +0530 Subject: [PATCH 42/47] review comments --- L2/PAC/PortAccessControl.md | 121 +++++++++++++++++------------------- 1 file changed, 57 insertions(+), 64 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index d112f170b36c..06a288e39395 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -59,28 +59,27 @@ High level design document version 0.8 - [3.6 Manageability](#36-manageability) - [3.6.1 Data Models](#361-data-models) - [3.6.2 Configuration Commands](#362-configuration-commands) - - [3.6.2.1 authentication enable](#3621-authentication-enable) - - [3.6.2.2 authentication critical recovery max-reauth](#3622-authentication-critical-recovery-max-reauth ) - - [3.6.2.3 authentication monitor](#3623-authentication-monitor) - - [3.6.2.4 aaa authentication pac](#3624-aaa-authentication-pac) - - [3.6.2.5 mab request format attribute 1](#3625-mab-request-format-attribute-1) - - [3.6.2.6 dot1x system-auth-control](#3626-dot1x-system-auth-control) - - [3.6.2.7 authentication event no-response action authorize vlan](#3627-authentication-event-no-response-action-authorize-vlan) - - [3.6.2.8 authentication event fail action authorize vlan](#3628-authentication-event-fail-action-authorize-vlan) - - [3.6.2.9 authentication event fail retry](#3629-authentication-event-fail-retry) - - [3.6.2.10 authentication max-users](#36210-authentication-max-users) - - [3.6.2.11 authentication periodic](#36211-authentication-periodic) - - [3.6.2.12 authentication port-control](#36212-authentication-port-control) - - [3.6.2.13 authentication host-mode](#36213-authentication-host-mode) - - [3.6.2.14 authentication timer reauthentiate](#36214-authentication-timer-reauthentiate) - - [3.6.2.15 authentication event server dead action](#36215-authentication-event-server-dead-action) - - [3.6.2.16 authentication event server dead action authorize voice](#36216-authentication-event-server-dead-action-authorize-voice) - - [3.6.2.17 authentication event server alive action reinitialize](#36217-authentication-event-server-alive-action-reinitialize) - - [3.6.2.18 authentication open](#36218-authentication-open) - - [3.6.2.19 authentication order](#36219-authentication-order) - - [3.6.2.20 authentication priority](#36220-authentication-priority) - - [3.6.2.21 mab](#36221-mab) - - [3.6.2.22 dot1x timeout](#36222-dot1x-timeout) + - [3.6.2.1 authentication critical recovery max-reauth](#3621-authentication-critical-recovery-max-reauth ) + - [3.6.2.2 authentication monitor](#3622-authentication-monitor) + - [3.6.2.3 aaa authentication pac](#3623-aaa-authentication-pac) + - [3.6.2.4 mab request format attribute 1](#3624-mab-request-format-attribute-1) + - [3.6.2.5 dot1x system-auth-control](#3625-dot1x-system-auth-control) + - [3.6.2.6 authentication event no-response action authorize vlan](#3626-authentication-event-no-response-action-authorize-vlan) + - [3.6.2.7 authentication event fail action authorize vlan](#3627-authentication-event-fail-action-authorize-vlan) + - [3.6.2.8 authentication event fail retry](#3628-authentication-event-fail-retry) + - [3.6.2.9 authentication max-users](#3629-authentication-max-users) + - [3.6.2.10 authentication periodic](#36210-authentication-periodic) + - [3.6.2.11 authentication port-control](#36211-authentication-port-control) + - [3.6.2.12 authentication host-mode](#36212-authentication-host-mode) + - [3.6.2.13 authentication timer reauthentiate](#36213-authentication-timer-reauthentiate) + - [3.6.2.14 authentication event server dead action](#36214-authentication-event-server-dead-action) + - [3.6.2.15 authentication event server dead action authorize voice](#36215-authentication-event-server-dead-action-authorize-voice) + - [3.6.2.16 authentication event server alive action reinitialize](#36216-authentication-event-server-alive-action-reinitialize) + - [3.6.2.17 authentication open](#36217-authentication-open) + - [3.6.2.18 authentication order](#36218-authentication-order) + - [3.6.2.19 authentication priority](#36219-authentication-priority) + - [3.6.2.20 mab](#36220-mab) + - [3.6.2.21 dot1x timeout](#36221-dot1x-timeout) - [3.6.3 Show Commands](#363-show-commands) - [3.6.3.1 show authentication interface](#3631-show-authentication-interface) - [3.6.3.2 show authentication](#3632-show-authentication) @@ -217,12 +216,12 @@ List of configuration shall include the following: - configure the authentication method for port-based access to the switch. - configuration parameters that needed to format attribute1 for MAB requests to the RADIUS server. - enable the dot1x authentication support on the switch. -- configure VLAN as guest vlan on an interface or a range of interfaces. -- configure the unauthenticated VLAN associated with the specified interface or range of interfaces. +- configure VLAN as guest vlan on an interface. +- configure the unauthenticated VLAN associated with the specified interface. - configure the number of times authentication may be reattempted by the client before a port moves to the authentication fail VLAN. -- set the maximum number of clients supported on an interface or range of interfaces when multi-authentication host mode is enabled on the port. -- enable periodic reauthentication of the supplicant for the specified interface or range of interfaces. -- set the authentication mode to use on the specified interface or range of interfaces. +- set the maximum number of clients supported on an interface when multi-authentication host mode is enabled on the port. +- enable periodic reauthentication of the supplicant for the specified interface. +- set the authentication mode to use on the specified interface. - configure the host mode of a port. - configure the period of time after which the Authenticator attempts to reauthenticate a supplicant on the port. - configure the actions to take when all the authentication servers are dead. @@ -1039,16 +1038,7 @@ Since Openconfig models are not available, Openconfig dot1x and mab are propriet The following commands are used to configure PAC. -#### 3.6.2.1 authentication enable -This command enables PAC feature globally. By default the feature is disabled. Any interface PAC configuration is effective only when PAC is enabled globally. - -| Mode | Global Config | -| ---- | ------ | -| Syntax | [no] authentication enable | -| Default | disable | -| Change history | SONiC 4.0 - Introduced | - -#### 3.6.2.2 authentication critical recovery max-reauth +#### 3.6.2.1 authentication critical recovery max-reauth This command configures the number of supplicants that are re-authenticated per second. This configuration is for the entire system across all the supplicants on all ports. This is used to control the system and network load when the number of supplicants to be re-authenticated is large. These re-authentications can be triggered due to ‘reinitialize’ dead or alive server actions. | Mode | Global Config | @@ -1058,7 +1048,7 @@ This command configures the number of supplicants that are re-authenticated per | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.3 authentication monitor +#### 3.6.2.2 authentication monitor This command enables the Authentication monitor mode on the switch. The purpose of Monitor mode is to help troubleshoot port-based authentication configuration issues without disrupting network access for hosts connected to the switch. In Monitor mode, a host is granted network access to an authentication enforced port even if it fails the authentication process. The results of the process are logged for diagnostic purposes. @@ -1068,7 +1058,7 @@ This command enables the Authentication monitor mode on the switch. The purpose | Default | disable | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.4 aaa authentication pac +#### 3.6.2.3 aaa authentication pac This command configures the authentication method for port-based access to the switch. The additional methods of authentication are used only if the previous method returns an error, not if there is an authentication failure. The possible methods are as follows: - none: Uses no authentication. - radius: Uses the list of all RADIUS servers for authentication @@ -1080,7 +1070,7 @@ This command configures the authentication method for port-based access to the s | Syntax | no aaa authentication pac | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.5 mab request format attribute 1 +#### 3.6.2.4 mab request format attribute 1 This command sets configuration parameters that are used to format attribute1 for MAB requests to the RADIUS server. RADIUS attribute 1 is the username, which is often the client MAC address | Mode | Global Config | @@ -1092,7 +1082,7 @@ This command sets configuration parameters that are used to format attribute1 fo | Syntax | no mab request format attribute 1 | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.6 dot1x system-auth-control +#### 3.6.2.5 dot1x system-auth-control This command enables the dot1x authentication support on the switch. While disabled, the dot1x configuration is retained and can be changed, but is not activated. | Mode | Global Config | | ---- | ------ | @@ -1101,8 +1091,8 @@ This command enables the dot1x authentication support on the switch. While disab | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.7 authentication event no-response action authorize vlan -This command configures VLAN as guest vlan on an interface or a range of interfaces. The range is 1 to the maximum VLAN ID supported by the platformor alive server actions. By default, the guest VLAN is 0, i.e. invalid and is not operational. +#### 3.6.2.6 authentication event no-response action authorize vlan +This command configures VLAN as guest vlan on an interface. The range is 1 to the maximum VLAN ID supported by the platformor alive server actions. By default, the guest VLAN is 0, i.e. invalid and is not operational. | Mode | Interface Config | | ---- | ------ | @@ -1111,8 +1101,8 @@ This command configures VLAN as guest vlan on an interface or a range of interfa | Syntax | no authentication event no-response | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.8 authentication event fail action authorize vlan -This command configures the unauthenticated VLAN associated with the specified interface or range of interfaces. This VLAN is used when the AAA server fails to recognize the client credentials and rejects the authentication attempt. The unauthenticated VLAN ID can be a valid VLAN ID from 1-Maximum supported VLAN ID (4093). By default, the unauthenticated VLAN is 0, i.e. invalid and not operational. +#### 3.6.2.7 authentication event fail action authorize vlan +This command configures the unauthenticated VLAN associated with the specified interface. This VLAN is used when the AAA server fails to recognize the client credentials and rejects the authentication attempt. The unauthenticated VLAN ID can be a valid VLAN ID from 1-Maximum supported VLAN ID (4093). By default, the unauthenticated VLAN is 0, i.e. invalid and not operational. | Mode | Interface Config | | ---- | ------ | @@ -1121,7 +1111,7 @@ This command configures the unauthenticated VLAN associated with the specified i | Syntax | no authentication event fail action authorize vlan | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.9 authentication event fail retry +#### 3.6.2.8 authentication event fail retry This command configures the number of times authentication may be reattempted by the client before a port moves to the authentication fail VLAN. The reattemps range is 1 to 5. | Mode | Interface Config | @@ -1131,8 +1121,8 @@ This command configures the number of times authentication may be reattempted b | Syntax | no authentication event fail retry | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.10 authentication max-users -This command sets the maximum number of clients supported on an interface or range of interfaces when multi-authentication host mode is enabled on the port. The maximum users supported per port is dependent on the product. The count value is in the range 1 - 48. +#### 3.6.2.9 authentication max-users +This command sets the maximum number of clients supported on an interface when multi-authentication host mode is enabled on the port. The maximum users supported per port is dependent on the product. The count value is in the range 1 - 48. | Mode | Interface Config | | ---- | ------ | @@ -1141,8 +1131,8 @@ This command sets the maximum number of clients supported on an interface or ran | Syntax | no authentication max-users | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.11 authentication periodic -This command enables periodic reauthentication of the supplicant for the specified interface or range of interfaces. +#### 3.6.2.10 authentication periodic +This command enables periodic reauthentication of the supplicant for the specified interface. | Mode | Interface Config | | ---- | ------ | @@ -1150,8 +1140,8 @@ This command enables periodic reauthentication of the supplicant for the specifi | Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.12 authentication port-control -This command sets the authentication mode to use on the specified interface or range of interfaces. The configuration on the interface mode takes precedence over the global configuration of this parameter. +#### 3.6.2.11 authentication port-control +This command sets the authentication mode to use on the specified interface. | Mode | Interface Config | | ---- | ------ | @@ -1160,7 +1150,7 @@ This command sets the authentication mode to use on the specified interface or r | Syntax | no authentication port-control | | Change history | SONiC 4.0 - Introduced -#### 3.6.2.13 authentication host-mode +#### 3.6.2.12 authentication host-mode This command configures the host mode of a port. The configuration on the interface mode takes precedence over the global configuration of this parameter. | Mode | Interface Config | @@ -1170,7 +1160,7 @@ This command configures the host mode of a port. The configuration on the interf | Syntax | no authentication host-mode | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.14 authentication timer reauthentiate +#### 3.6.2.13 authentication timer reauthentiate This command is used to configure the period of time after which the Authenticator attempts to reauthenticate a supplicant on the port. This command also provides an option to specify re-authentication time out value from the server (ex. Radius). When ‘server’ option is selected, the server supplied Session time out and Session Termination-action are used by Authenticator to reauthenticate a supplicant on the port . By default server option is enabled. The reauthenticate seconds value range is 1 to 65535. For reauthentication to happen after the configured or server provided timeout, the command “authentication periodic” should have enabled periodic reauthentication. @@ -1183,7 +1173,7 @@ For reauthentication to happen after the configured or server provided timeout, | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.15 authentication event server dead action +#### 3.6.2.14 authentication event server dead action This command configures the actions to take when all the authentication servers are dead. The command also configures the critical VLAN ID. If the VLAN ID is not specified, the port PVID is used as the critical VLAN ID. | Mode | Interface Config | @@ -1194,7 +1184,7 @@ This command configures the actions to take when all the authentication servers | Syntax | no authentication event server dead action | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.16 authentication event server dead action authorize voice +#### 3.6.2.15 authentication event server dead action authorize voice This command enables authorization of voice devices on the critical voice VLAN when all the authentication servers are dead. The configured voice VLAN of the port, on which the voice device is connected, is used as the critical voice VLAN ID. | Mode | Interface Config | @@ -1204,7 +1194,7 @@ This command enables authorization of voice devices on the critical voice VLAN w | Syntax | no authentication event server dead action authorize | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.17 authentication event server alive action reinitialize +#### 3.6.2.16 authentication event server alive action reinitialize This command configures the actions to take when one authentication server comes back alive after all were dead. The reinitialize action triggers the re-authentication of supplicants authenticated on the critical VLAN. | Mode | Interface Config | @@ -1214,7 +1204,7 @@ This command configures the actions to take when one authentication server comes | Syntax | no authentication event server alive action | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.18 authentication open +#### 3.6.2.17 authentication open This command configures Open Authentication mode on the port. | Mode | Interface Config | @@ -1223,7 +1213,7 @@ This command configures Open Authentication mode on the port. | Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.19 authentication order +#### 3.6.2.18 authentication order This command is used to set the order of authentication methods used on a port. The allowed methods to configure for SONiC are Dot1x and MAB. Ordering sets the order of methods that the switch attempts when trying to authenticate a new device connected to a port. If one method in the list is unsuccessful or timed out, the next method is atempted. Each method can only be entered once. | Mode | Interface Config | @@ -1233,7 +1223,7 @@ This command is used to set the order of authentication methods used on a port. | Syntax | no authentication order | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.20 authentication priority +#### 3.6.2.19 authentication priority This command is used to set the priority for the authentication methods used on a port. The allowed methods to configure for SONiC are Dot1x and MAB. Authentication priority decides if the client, who is already authenticated, to re-authenticate with the higher-priority method when the same is received. | Mode | Interface Config | @@ -1243,7 +1233,7 @@ This command is used to set the priority for the authentication methods used on | Syntax | no authentication priority | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.21 mab +#### 3.6.2.20 mab This command is used to enable MAC Authentication Bypass (MAB) on an interface. MAB is a supplemental authentication mechanism that allows 802.1X unaware clients – such as printers, fax machines, and some IP phones — to authenticate to the network using the client MAC address as an identifier. However MAB can also be used to authenticate 802.1x aware clients. This command also provides options to specify the type of authentication to be used, which can be either EAP-MD5 ,PAP,CHAP. If enabled, EAP-MD5 is used by default. | Mode | Interface Config | @@ -1252,8 +1242,8 @@ This command is used to enable MAC Authentication Bypass (MAB) on an interface. | Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.22 dot1x timeout -This command sets the value, in seconds, of the timers used by the authenticator or supplicant state machines on an interface or range of interfaces. Depending on the token used and the value (in seconds) passed, various timeout configurable parameters are set. +#### 3.6.2.21 dot1x timeout +This command sets the value, in seconds, of the timers used by the authenticator or supplicant state machines on an interface. Depending on the token used and the value (in seconds) passed, various timeout configurable parameters are set. - quiet-period: The value, in seconds, of the timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. This is the period for which the authenticator state machine stays in the HELD state. - tx-period: The value, in seconds, of the timer used by the authenticator state machine on this port to determine when to send an EAPOL EAP Request/Identity frame to the supplicant. @@ -1551,6 +1541,10 @@ Debug command output will be captured as part of tech support for offline analys - Configured actions and counters continue to work across warm reboot. - Already authenticated sessions continues to work. - Authentication is restarted for the Clients being authenticated at the time of warmboot. +- Statistics are preserved across warmboot. +- HW and SW entries for authenticated clients are preserved across warmboot. +- Authenticated client traffic is not disrupted. +- Clients in the process of authentication will need to re-initiate their authentication process. # 8 Scalability @@ -1596,7 +1590,6 @@ fpinfra is a shared library that provides C APIs. Its unit tested using a C/C++ **Using Sonic-CLI** ``` configure -authentication enable aaa authentication dot1x default radius interface 1/1 From 1388d171727c86f2724a5fbc9f651712da37b39b Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Fri, 9 Jul 2021 14:55:18 +0530 Subject: [PATCH 43/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 06a288e39395..8abaa1cef458 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1044,6 +1044,7 @@ This command configures the number of supplicants that are re-authenticated per | Mode | Global Config | | ---- | ------ | | Syntax | [no] authentication critical recovery max-reauth | +| range | 1-50 | | Default | 10 | | Change history | SONiC 4.0 - Introduced | @@ -1117,6 +1118,7 @@ This command configures the number of times authentication may be reattempted b | Mode | Interface Config | | ---- | ------ | | Syntax | authentication event fail retry \ | +| range | 1-5 | | Default | 3 | | Syntax | no authentication event fail retry | | Change history | SONiC 4.0 - Introduced | @@ -1127,6 +1129,7 @@ This command sets the maximum number of clients supported on an interface when m | Mode | Interface Config | | ---- | ------ | | Syntax | authentication max-users \ | +| range | 1-48 | | Default | 48 | | Syntax | no authentication max-users | | Change history | SONiC 4.0 - Introduced | @@ -1170,6 +1173,7 @@ For reauthentication to happen after the configured or server provided timeout, | Syntax | authentication timer reauthenticate \{ \ \| server \} | | Default | server | | Syntax | no authentication timer reauthenticate | +| range | 1-65535 | | Change history | SONiC 4.0 - Introduced | @@ -1306,7 +1310,7 @@ show authentication interface 1/1 Authentication Manager Status.................. Enabled -Interface...................................... 1/1 +Interface...................................... Eth1/1 Authentication Restart timer................... 300 Configured method order........................ mab undefined undefined Enabled method order........................... mab undefined undefined @@ -1406,7 +1410,7 @@ Example: Interface MAC-Address Method Host Mode Control Mode VLAN Assigned Reason --------- ----------------- ------- ------------ ------------ -------------------------- -1/16 10:8D:B6:C6:00:00 802.1X multi-host auto RADIUS Assigned VLAN (10) +Eth1/16 10:8D:B6:C6:00:00 802.1X multi-host auto RADIUS Assigned VLAN (10) @@ -1449,8 +1453,8 @@ show authentication authentication-history interface 1/2 Timestamp Interface MAC-Address Auth Status Method -------------------- --------- ----------------- ------------ ------ -May 07 2020 13:02:41 1/2 58:05:94:1C:00:00 Unauthorized 802.1X -May 07 2020 13:01:33 1/2 58:05:94:1C:00:00 Unauthorized 802.1X +May 07 2020 13:02:41 Eth1/2 58:05:94:1C:00:00 Unauthorized 802.1X +May 07 2020 13:01:33 Eth1/2 58:05:94:1C:00:00 Unauthorized 802.1X ``` @@ -1472,15 +1476,15 @@ MAB Request Fmt Attr1 Case........ uppercase Interface Admin Mode Auth-type --------- ----------- --------- -1/1 Disabled N/A -1/2 Disabled N/A -1/3 Disabled N/A +Eth1/1 Disabled N/A +Eth1/2 Disabled N/A +Eth1/3 Disabled N/A (dhcp-10-130-86-142) #show mab interface 1/10 Interface Admin Mode Auth-type --------- ----------- --------- -1/10 Enabled eap-md5 +Eth1/10 Enabled eap-md5 ``` From 7f2e2334a7a37788217f11795d17b94d874ef8c9 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 12 Jul 2021 11:15:47 +0530 Subject: [PATCH 44/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 8abaa1cef458..2279ca15b3c4 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1562,6 +1562,7 @@ The following is the support scale for Port Access Control. The following number | authentication history entries | 1024 | | authentication history entries per interface | 20 | | clients that can be authorized on a port configured in Multi-Auth host mode | 48 | +| Number of clients supported by the switch | 512 | # 9 Limitation @@ -1575,6 +1576,8 @@ The following is the support scale for Port Access Control. The following number # 10 Upgrade / Downgrade considerations +Compatibility across software versions are not guaranteed. Upgrade/downgrade across non-compatible versions needs to be treated as a service affecting upgrade. Upgrade downgrade to a compatible software version can be done in conjunction with a warm boot to avoid disruption to already authenticated client sessions. Software compatibility related information can be found in the release notes. + # 11 Unit Test *fpinfra* From 59e52b19f454fae4251837f94aa511b612f1793c Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Mon, 12 Jul 2021 16:22:45 +0530 Subject: [PATCH 45/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 45 ++++--------------------------------- 1 file changed, 4 insertions(+), 41 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 2279ca15b3c4..459303ac3226 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.8 +High level design document version 0.9 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -79,7 +79,6 @@ High level design document version 0.8 - [3.6.2.18 authentication order](#36218-authentication-order) - [3.6.2.19 authentication priority](#36219-authentication-priority) - [3.6.2.20 mab](#36220-mab) - - [3.6.2.21 dot1x timeout](#36221-dot1x-timeout) - [3.6.3 Show Commands](#363-show-commands) - [3.6.3.1 show authentication interface](#3631-show-authentication-interface) - [3.6.3.2 show authentication](#3632-show-authentication) @@ -89,7 +88,6 @@ High level design document version 0.8 - [3.6.3.6 show dot1x](#3636-show-dot1x) - [3.6.4 Clear Commands](#364-clear-commands) - [3.6.4.1 clear authentication sessions](#3641-clear-authentication-sessions) - - [3.6.4.2 clear dot1x statistics](#3642-clear-dot1x-statistics) - **[4 Flow Diagrams](#4-flow-diagrams)** - **[5 Error Handling](#5-error-handling)** - **[6 Serviceability and Debug](#6-serviceability-and-debug)** @@ -117,6 +115,7 @@ High level design document version 0.8 | 0.6 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated docker to macsec, added configuration, scalability and warmboot requirements | | 0.7 | 05/26/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | | 0.8 | 06/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | +| 0.9 | 07/12/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments, removed dot1x timeout and clear dot1x statistics commands, removed scale limit for max ports supporting mab, dot1x. modified show dot1x output. | # About this Manual This document describes the design details of the Port Access Control feature in SONiC. Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. @@ -1246,30 +1245,6 @@ This command is used to enable MAC Authentication Bypass (MAB) on an interface. | Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.21 dot1x timeout -This command sets the value, in seconds, of the timers used by the authenticator or supplicant state machines on an interface. Depending on the token used and the value (in seconds) passed, various timeout configurable parameters are set. - -- quiet-period: The value, in seconds, of the timer used by the authenticator state machine on this port to define periods of time in which it will not attempt to acquire a supplicant. This is the period for which the authenticator state machine stays in the HELD state. -- tx-period: The value, in seconds, of the timer used by the authenticator state machine on this port to determine when to send an EAPOL EAP Request/Identity frame to the supplicant. -- server-timeout: The value, in seconds, of the timer used by the authenticator state machine on this port to timeout the authentication server. -- supp-timeout: The value, in seconds, of the timer used by the authenticator state machine on this port to timeout the supplicant. -- auth-period: The value, in seconds, of the timer used by the supplicant state machine on this port to timeout an authenticator when waiting for a response to packets other than EAPOL-Start. -- start-period: The value, in seconds, of the timer used by the supplicant state machine on this port to determine the interval between two successive EAPOL-Start frames when they are being retransmitted. -- held-period: The value, in seconds, of the timer used by the supplicant state machine on this port to determine the length of time it will wait before trying to send the authentication credentials again after a failed attempt. This is the period for which the supplicant state machine stays in the HELD state. - -| Mode | Interface Config | -| ---- | ------ | -| Syntax | [no] dot1x timeout \{ quiet-period \| tx-period \| server-timeout \| supp-timeout \| auth-period \| start-period \| held-period \} | -| Default | quiet-period: 60 seconds | -| Default | tx-period: 30 seconds | -| Default | supp-timeout: 30 seconds | -| Default | server-timeout: 30 seconds | -| Default | auth-period: 30 seconds | -| Default | start-period: 30 seconds | -| Default | held-period: 60 seconds | -| Change history | SONiC 4.0 - Introduced | - - ### 3.6.3 Show Commands @@ -1489,7 +1464,7 @@ Eth1/10 Enabled eap-md5 ``` #### 3.6.3.6 show dot1x -This command is used to show a summary of the global dot1x configuration, summary information of the dot1x configuration for a specified port or all ports, the detailed dot1x configuration for a specified port and the dot1x statistics for a specified port - depending on the tokens used. +This command is used to show a summary of the global dot1x configuration. | Mode | Exec | | ------ | ------------------- | @@ -1499,16 +1474,13 @@ This command is used to show a summary of the global dot1x configuration, summar | Field | Description | | ------ | ------------------- | | Administrative Mode | Indicates whether 802.1x is enabled or disabled. | -| EAPOL Flood Mode | Indicates whether the EAPOL flood support is enabled on the switch. | -| Dot1x Software Version | The version of Dot1x implementation running on the switch. | + Example: ``` #show dot1x Administrative Mode............... Enabled -EAPOL Flood Mode.................. Disabled -Software Version.................. 1 ``` @@ -1522,13 +1494,6 @@ This command clears information for all Auth Manager sessions. All the authenti | Syntax | clear authentication session | | Change history | SONiC 4.0 - Introduced | -#### 3.6.4.2 clear dot1x statistics -This command resets the 802.1X statistics for the specified port or for all ports. - -| Mode | Exec | -| ------ | ------------------- | -| Syntax | clear dot1x statistics | -| Change history | SONiC 4.0 - Introduced | # 4 Flow Diagrams The flow diagrams Figure 2: PAC service daemon and configuration flow, Figure 3: EAPOL receive flow, Figure 4: MAB PDU receive flow; indicates the sequence of events involved in processing of PAC configuration and EAPOL/MAB packets. @@ -1557,8 +1522,6 @@ The following is the support scale for Port Access Control. The following number | Configuration / Resource | Scale | | ------ | ------------------- | -| ports supported by dot1x | 300 | -| ports supported by MAB | 300 | | authentication history entries | 1024 | | authentication history entries per interface | 20 | | clients that can be authorized on a port configured in Multi-Auth host mode | 48 | From e307acde7ea5cd1989ab1db424b8b80409dec132 Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 14 Jul 2021 14:22:07 +0530 Subject: [PATCH 46/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 150 +++++++++++++++++++++++++++--------- 1 file changed, 115 insertions(+), 35 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 459303ac3226..3168339742e2 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -1,7 +1,7 @@ # Port Access Control in SONiC -High level design document version 0.9 +High level design document version 0.10 # Table of Contents - **[List of Tables](#list-of-tables)** @@ -64,21 +64,22 @@ High level design document version 0.9 - [3.6.2.3 aaa authentication pac](#3623-aaa-authentication-pac) - [3.6.2.4 mab request format attribute 1](#3624-mab-request-format-attribute-1) - [3.6.2.5 dot1x system-auth-control](#3625-dot1x-system-auth-control) - - [3.6.2.6 authentication event no-response action authorize vlan](#3626-authentication-event-no-response-action-authorize-vlan) - - [3.6.2.7 authentication event fail action authorize vlan](#3627-authentication-event-fail-action-authorize-vlan) - - [3.6.2.8 authentication event fail retry](#3628-authentication-event-fail-retry) - - [3.6.2.9 authentication max-users](#3629-authentication-max-users) - - [3.6.2.10 authentication periodic](#36210-authentication-periodic) - - [3.6.2.11 authentication port-control](#36211-authentication-port-control) - - [3.6.2.12 authentication host-mode](#36212-authentication-host-mode) - - [3.6.2.13 authentication timer reauthentiate](#36213-authentication-timer-reauthentiate) - - [3.6.2.14 authentication event server dead action](#36214-authentication-event-server-dead-action) - - [3.6.2.15 authentication event server dead action authorize voice](#36215-authentication-event-server-dead-action-authorize-voice) - - [3.6.2.16 authentication event server alive action reinitialize](#36216-authentication-event-server-alive-action-reinitialize) - - [3.6.2.17 authentication open](#36217-authentication-open) - - [3.6.2.18 authentication order](#36218-authentication-order) - - [3.6.2.19 authentication priority](#36219-authentication-priority) - - [3.6.2.20 mab](#36220-mab) + - [3.6.2.6 dot1x pae](#3626-dot1x-pae) + - [3.6.2.7 authentication event no-response action authorize vlan](#3627-authentication-event-no-response-action-authorize-vlan) + - [3.6.2.8 authentication event fail action authorize vlan](#3628-authentication-event-fail-action-authorize-vlan) + - [3.6.2.9 authentication event fail retry](#3629-authentication-event-fail-retry) + - [3.6.2.10 authentication max-users](#36210-authentication-max-users) + - [3.6.2.11 authentication periodic](#36211-authentication-periodic) + - [3.6.2.12 authentication port-control](#36212-authentication-port-control) + - [3.6.2.13 authentication host-mode](#36213-authentication-host-mode) + - [3.6.2.14 authentication timer reauthentiate](#36214-authentication-timer-reauthentiate) + - [3.6.2.15 authentication event server dead action](#36215-authentication-event-server-dead-action) + - [3.6.2.16 authentication event server dead action authorize voice](#36216-authentication-event-server-dead-action-authorize-voice) + - [3.6.2.17 authentication event server alive action reinitialize](#36217-authentication-event-server-alive-action-reinitialize) + - [3.6.2.18 authentication open](#36218-authentication-open) + - [3.6.2.19 authentication order](#36219-authentication-order) + - [3.6.2.20 authentication priority](#36220-authentication-priority) + - [3.6.2.21 mab](#36221-mab) - [3.6.3 Show Commands](#363-show-commands) - [3.6.3.1 show authentication interface](#3631-show-authentication-interface) - [3.6.3.2 show authentication](#3632-show-authentication) @@ -115,7 +116,8 @@ High level design document version 0.9 | 0.6 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated docker to macsec, added configuration, scalability and warmboot requirements | | 0.7 | 05/26/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | | 0.8 | 06/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | -| 0.9 | 07/12/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments, removed dot1x timeout and clear dot1x statistics commands, removed scale limit for max ports supporting mab, dot1x. modified show dot1x output. | +| 0.9 | 07/12/2021 | Prabhu Sreenivasan, Amitabha Sen | removed dot1x timeout and clear dot1x statistics commands, removed scale limit for max ports supporting mab, dot1x. modified show dot1x output. | +| 0.10 | 07/14/2021 | Prabhu Sreenivasan, Amitabha Sen | Added "dot1x pae" command and updated "show authentication interface" for the same. Updated section 6 Serviceability and Debug with syslog messages | # About this Manual This document describes the design details of the Port Access Control feature in SONiC. Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. @@ -767,6 +769,7 @@ user_name = 1*255VCHARS ; Client user name ## 3.3 Switch State Service Design ### 3.3.1 Orchestration Agent +There no new orchestration agent for PAC. ### 3.3.2 pacd pacd process links with libfpinfra.so and libauthmgr.so for the infrastructure and authentication manager functionality respectvely. Below picture depicts the interal details of the pacd process. @@ -1026,7 +1029,70 @@ mabd informs pacd about the result of the authentication. mabd also passes all t No changes to SyncD. ## 3.5 SAI -No change to SAI. + +### 3.5.1 Host interface traps +Added support for **SAI_HOSTIF_TRAP_TYPE_EAPOL** to trap EAP packets (Ethertype - 0x888E) to the CPU. +Added support for **SAI_HOSTIF_TRAP_TYPE_STATIC_FDB_MOVE** to identify station movement on static FDB entries. + +### 3.5.2 Bridge port learning modes +PAC uses the following bridge port learning modes to drop/trap all unknown source MAC packets. + - SAI_BRIDGE_PORT_FDB_LEARNING_MODE_DROP + - SAI_BRIDGE_PORT_FDB_LEARNING_MODE_HW + - SAI_BRIDGE_PORT_FDB_LEARNING_MODE_CPU_TRAP + +SAI config sequence: +``` +attr.id = SAI_BRIDGE_PORT_ATTR_FDB_LEARNING_MODE; +attr.value.u32 = SAI_BRIDGE_PORT_FDB_LEARNING_MODE_DROP; +sai_bridge_apis->set_bridge_port_attribute(port1_bid ,&attr)); + attr.value.u32 = SAI_BRIDGE_PORT_FDB_LEARNING_MODE_HW; +sai_bridge_apis->set_bridge_port_attribute(port1_bid ,&attr)); +attr.value.u32 = SAI_BRIDGE_PORT_FDB_LEARNING_MODE_CPU_TRAP; +rv = sai_bridge_apis->set_bridge_port_attribute(port1_bid ,&attr)); +``` + +### 3.5.3 FDB +PAC will use **SAI_FDB_ENTRY_ATTR_PACKET_ACTION** with **SAI_PACKET_ACTION_DROP** to put the static FDB entry in discard state. +**SAI_PACKET_ACTION_FORWARD** is used to put the static FDB entry into forwarding state post successful client authentication. + +SAI config sequence: +``` +sai_attribute_t attr_list1[] = + { + { SAI_FDB_ENTRY_ATTR_TYPE, .value.s32 = SAI_FDB_ENTRY_TYPE_STATIC }, + { SAI_FDB_ENTRY_ATTR_BRIDGE_PORT_ID, .value.oid = bid }, + { SAI_FDB_ENTRY_ATTR_PACKET_ACTION, .value.u32 = SAI_PACKET_ACTION_DROP} + }; +sai_fdb_apis->create_fdb_entry(&fdb_entry1, COUNTOF(attr_list1), attr_list1)); + +Move FDB entry to forwarding state: +attr.type = SAI_FDB_ENTRY_ATTR_PACKET_ACTION; +attr.value.s32 = SAI_PACKET_ACTION_FORWARD; +sai_fdb_apis->set_fdb_entry_attribute(&fdb_entry1, &attr); +``` +### 3.5.3 VLAN +**SAI_ACL_STAGE_LOOKUP** will be used to configure a LOOKUP stage ACL that achieves the MAC-VLAN translation. +**SAI_ACL_ENTRY_ATTR_FIELD_SRC_MAC** is used as the qualifier to qualify the packet based upon the source MAC of the client. +**SAI_ACL_ENTRY_ATTR_FIELD_PACKET_VLAN** and **SAI_ACL_ENTRY_ATTR_FIELD_HAS_VLAN_TAG** qualifiers are used to identify if the packet is tagged or not. +**SAI_ACL_ENTRY_ATTR_ACTION_ADD_VLAN_ID**, **SAI_ACL_ENTRY_ATTR_ACTION_SET_OUTER_VLAN_ID** and **SAI_ACL_ENTRY_ATTR_ACTION_SET_INNER_VLAN_ID** actions to achieve PAC functionality. + +### 3.5.3 VFP +VFP rules match on the packet fields like source MAC (bcmFieldQualifySrcMac) and VLAN format (bcmFieldQualifyVlanFormat) to qualify packets for VLAN translation and add VLAN tags accordingly (bcmFieldActionOuterVlanAdd, bcmFieldActionOuterVlanNew). + +Config sequence: +``` +bcm_field_entry_create(unit, group, &entry); +bcm_field_qualify_SrcMac(unit, entry, mac, mac_mask); + +Qualify on untagged packets and add VLAN tag: +bcm_field_qualify_VlanFormat(unit, entry, 0x40, 0xff ); +bcm_field_action_add(unit, entry, bcmFieldActionOuterVlanAdd, vlan, 0, 0); + +Qualify on tagged packets and change VLAN tag: +bcm_field_qualify_VlanFormat(unit, entry, 0x01, 0xff ); +bcm_field_action_add(unit, entry, bcmFieldActionOuterVlanNew, vlan, 0, 0); +``` + ## 3.6 Manageability @@ -1090,8 +1156,15 @@ This command enables the dot1x authentication support on the switch. While disab | Default | disable | | Change history | SONiC 4.0 - Introduced | +#### 3.6.2.6 dot1x pae +This command sets the PAC role on the port. +| Mode | Interface Config | +| ---- | ------ | +| Syntax | [no] dot1x pae \{ authenticator \| none \} | +| Default | none | +| Change history | SONiC 4.0 - Introduced | -#### 3.6.2.6 authentication event no-response action authorize vlan +#### 3.6.2.7 authentication event no-response action authorize vlan This command configures VLAN as guest vlan on an interface. The range is 1 to the maximum VLAN ID supported by the platformor alive server actions. By default, the guest VLAN is 0, i.e. invalid and is not operational. | Mode | Interface Config | @@ -1101,7 +1174,7 @@ This command configures VLAN as guest vlan on an interface. The range is 1 to th | Syntax | no authentication event no-response | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.7 authentication event fail action authorize vlan +#### 3.6.2.8 authentication event fail action authorize vlan This command configures the unauthenticated VLAN associated with the specified interface. This VLAN is used when the AAA server fails to recognize the client credentials and rejects the authentication attempt. The unauthenticated VLAN ID can be a valid VLAN ID from 1-Maximum supported VLAN ID (4093). By default, the unauthenticated VLAN is 0, i.e. invalid and not operational. | Mode | Interface Config | @@ -1111,7 +1184,7 @@ This command configures the unauthenticated VLAN associated with the specified i | Syntax | no authentication event fail action authorize vlan | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.8 authentication event fail retry +#### 3.6.2.9 authentication event fail retry This command configures the number of times authentication may be reattempted by the client before a port moves to the authentication fail VLAN. The reattemps range is 1 to 5. | Mode | Interface Config | @@ -1122,7 +1195,7 @@ This command configures the number of times authentication may be reattempted b | Syntax | no authentication event fail retry | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.9 authentication max-users +#### 3.6.2.10 authentication max-users This command sets the maximum number of clients supported on an interface when multi-authentication host mode is enabled on the port. The maximum users supported per port is dependent on the product. The count value is in the range 1 - 48. | Mode | Interface Config | @@ -1133,7 +1206,7 @@ This command sets the maximum number of clients supported on an interface when m | Syntax | no authentication max-users | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.10 authentication periodic +#### 3.6.2.11 authentication periodic This command enables periodic reauthentication of the supplicant for the specified interface. | Mode | Interface Config | @@ -1142,7 +1215,7 @@ This command enables periodic reauthentication of the supplicant for the specifi | Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.11 authentication port-control +#### 3.6.2.12 authentication port-control This command sets the authentication mode to use on the specified interface. | Mode | Interface Config | @@ -1152,7 +1225,7 @@ This command sets the authentication mode to use on the specified interface. | Syntax | no authentication port-control | | Change history | SONiC 4.0 - Introduced -#### 3.6.2.12 authentication host-mode +#### 3.6.2.13 authentication host-mode This command configures the host mode of a port. The configuration on the interface mode takes precedence over the global configuration of this parameter. | Mode | Interface Config | @@ -1162,7 +1235,7 @@ This command configures the host mode of a port. The configuration on the interf | Syntax | no authentication host-mode | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.13 authentication timer reauthentiate +#### 3.6.2.14 authentication timer reauthentiate This command is used to configure the period of time after which the Authenticator attempts to reauthenticate a supplicant on the port. This command also provides an option to specify re-authentication time out value from the server (ex. Radius). When ‘server’ option is selected, the server supplied Session time out and Session Termination-action are used by Authenticator to reauthenticate a supplicant on the port . By default server option is enabled. The reauthenticate seconds value range is 1 to 65535. For reauthentication to happen after the configured or server provided timeout, the command “authentication periodic” should have enabled periodic reauthentication. @@ -1176,7 +1249,7 @@ For reauthentication to happen after the configured or server provided timeout, | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.14 authentication event server dead action +#### 3.6.2.15 authentication event server dead action This command configures the actions to take when all the authentication servers are dead. The command also configures the critical VLAN ID. If the VLAN ID is not specified, the port PVID is used as the critical VLAN ID. | Mode | Interface Config | @@ -1187,7 +1260,7 @@ This command configures the actions to take when all the authentication servers | Syntax | no authentication event server dead action | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.15 authentication event server dead action authorize voice +#### 3.6.2.16 authentication event server dead action authorize voice This command enables authorization of voice devices on the critical voice VLAN when all the authentication servers are dead. The configured voice VLAN of the port, on which the voice device is connected, is used as the critical voice VLAN ID. | Mode | Interface Config | @@ -1197,7 +1270,7 @@ This command enables authorization of voice devices on the critical voice VLAN w | Syntax | no authentication event server dead action authorize | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.16 authentication event server alive action reinitialize +#### 3.6.2.17 authentication event server alive action reinitialize This command configures the actions to take when one authentication server comes back alive after all were dead. The reinitialize action triggers the re-authentication of supplicants authenticated on the critical VLAN. | Mode | Interface Config | @@ -1207,7 +1280,7 @@ This command configures the actions to take when one authentication server comes | Syntax | no authentication event server alive action | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.17 authentication open +#### 3.6.2.18 authentication open This command configures Open Authentication mode on the port. | Mode | Interface Config | @@ -1216,7 +1289,7 @@ This command configures Open Authentication mode on the port. | Default | Disabled | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.18 authentication order +#### 3.6.2.19 authentication order This command is used to set the order of authentication methods used on a port. The allowed methods to configure for SONiC are Dot1x and MAB. Ordering sets the order of methods that the switch attempts when trying to authenticate a new device connected to a port. If one method in the list is unsuccessful or timed out, the next method is atempted. Each method can only be entered once. | Mode | Interface Config | @@ -1226,7 +1299,7 @@ This command is used to set the order of authentication methods used on a port. | Syntax | no authentication order | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.19 authentication priority +#### 3.6.2.20 authentication priority This command is used to set the priority for the authentication methods used on a port. The allowed methods to configure for SONiC are Dot1x and MAB. Authentication priority decides if the client, who is already authenticated, to re-authenticate with the higher-priority method when the same is received. | Mode | Interface Config | @@ -1236,7 +1309,7 @@ This command is used to set the priority for the authentication methods used on | Syntax | no authentication priority | | Change history | SONiC 4.0 - Introduced | -#### 3.6.2.20 mab +#### 3.6.2.21 mab This command is used to enable MAC Authentication Bypass (MAB) on an interface. MAB is a supplemental authentication mechanism that allows 802.1X unaware clients – such as printers, fax machines, and some IP phones — to authenticate to the network using the client MAC address as an identifier. However MAB can also be used to authenticate 802.1x aware clients. This command also provides options to specify the type of authentication to be used, which can be either EAP-MD5 ,PAP,CHAP. If enabled, EAP-MD5 is used by default. | Mode | Interface Config | @@ -1278,6 +1351,7 @@ This command displays the authentication manager information for the interface | Authentication Server Alive action | The action to be undertaken for data clients when a RADIUS server comes back alive after all were found dead. | | Allowed protocols on unauthorized port | The action to drop or forward the particular protocol packet from and to unauthorized clients on the port | | Open Authentication | Indicates if Open Authentication is enabled on the interface. | +| PAE role | Indicates the configured PAE role as authenticator or none. | Example: ``` @@ -1302,6 +1376,7 @@ Authentication Server Dead action for Voice.... None Authentication Server Alive action............. None Allowed protocols on unauthorized port......... dhcp Open Authentication............................ Disabled +PAE role....................................... authenticator ``` #### 3.6.3.2 show authentication @@ -1502,9 +1577,13 @@ The flow diagrams Figure 2: PAC service daemon and configuration flow, Figure 3: N/A # 6 Serviceability and Debug -show commands will help to see if the PAC is active on a port. -All processing errors will be captured in syslog. +show commands will help to see if the PAC is active on a port. Debug command output will be captured as part of tech support for offline analysis. +All processing errors will be captured in syslog. +Below syslog messages indicates the authorization state of a client: +``` Client Authorized. MAC: aa:bb:cc:dd:ee:ff, Port: Ethernet0, VLAN: 10 ``` + +``` Client Unauthorized. MAC: aa:bb:cc:dd:ee:ff, Port: Ethernet0, VLAN: 10 ``` # 7 Warm Boot Support - Configured actions and counters continue to work across warm reboot. @@ -1563,6 +1642,7 @@ configure aaa authentication dot1x default radius interface 1/1 +dot1x pae authenticator authentication order dot1x mab authentication priority dot1x mab authentication host-mode multi-auth From e733ece0f4dcb43590cc6907c0f2385764e7bb0d Mon Sep 17 00:00:00 2001 From: Prabhu Sreenivasan <45380242+PrabhuSreenivasan@users.noreply.github.com> Date: Wed, 14 Jul 2021 16:41:00 +0530 Subject: [PATCH 47/47] Update PortAccessControl.md --- L2/PAC/PortAccessControl.md | 29 ++++++----------------------- 1 file changed, 6 insertions(+), 23 deletions(-) diff --git a/L2/PAC/PortAccessControl.md b/L2/PAC/PortAccessControl.md index 3168339742e2..50d2c86d657d 100644 --- a/L2/PAC/PortAccessControl.md +++ b/L2/PAC/PortAccessControl.md @@ -116,8 +116,8 @@ High level design document version 0.10 | 0.6 | 05/07/2021 | Prabhu Sreenivasan, Amitabha Sen | Updated docker to macsec, added configuration, scalability and warmboot requirements | | 0.7 | 05/26/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | | 0.8 | 06/03/2021 | Prabhu Sreenivasan, Amitabha Sen | Review comments | -| 0.9 | 07/12/2021 | Prabhu Sreenivasan, Amitabha Sen | removed dot1x timeout and clear dot1x statistics commands, removed scale limit for max ports supporting mab, dot1x. modified show dot1x output. | -| 0.10 | 07/14/2021 | Prabhu Sreenivasan, Amitabha Sen | Added "dot1x pae" command and updated "show authentication interface" for the same. Updated section 6 Serviceability and Debug with syslog messages | +| 0.9 | 07/12/2021 | Prabhu Sreenivasan, Amitabha Sen | Removed "dot1x timeout" and "clear dot1x statistics" commands, Removed scale limit for max ports supporting mab, dot1x. modified show dot1x output. | +| 0.10 | 07/14/2021 | Prabhu Sreenivasan, Amitabha Sen | Added "dot1x pae" command and updated "show authentication interface" for the same. Updated section 6 Serviceability and Debug with syslog messages. Updated secion 3.5 SAI with details. | # About this Manual This document describes the design details of the Port Access Control feature in SONiC. Port Access Control (PAC) feature provides validation of client and user credentials to prevent unauthorized access to a specific switch port. @@ -1035,10 +1035,10 @@ Added support for **SAI_HOSTIF_TRAP_TYPE_EAPOL** to trap EAP packets (Ethertype Added support for **SAI_HOSTIF_TRAP_TYPE_STATIC_FDB_MOVE** to identify station movement on static FDB entries. ### 3.5.2 Bridge port learning modes -PAC uses the following bridge port learning modes to drop/trap all unknown source MAC packets. - - SAI_BRIDGE_PORT_FDB_LEARNING_MODE_DROP - - SAI_BRIDGE_PORT_FDB_LEARNING_MODE_HW - - SAI_BRIDGE_PORT_FDB_LEARNING_MODE_CPU_TRAP +PAC uses the following bridge port learning modes to drop/trap all unknown source MAC packets. +- SAI_BRIDGE_PORT_FDB_LEARNING_MODE_DROP +- SAI_BRIDGE_PORT_FDB_LEARNING_MODE_HW +- SAI_BRIDGE_PORT_FDB_LEARNING_MODE_CPU_TRAP SAI config sequence: ``` @@ -1075,23 +1075,6 @@ sai_fdb_apis->set_fdb_entry_attribute(&fdb_entry1, &attr); **SAI_ACL_ENTRY_ATTR_FIELD_SRC_MAC** is used as the qualifier to qualify the packet based upon the source MAC of the client. **SAI_ACL_ENTRY_ATTR_FIELD_PACKET_VLAN** and **SAI_ACL_ENTRY_ATTR_FIELD_HAS_VLAN_TAG** qualifiers are used to identify if the packet is tagged or not. **SAI_ACL_ENTRY_ATTR_ACTION_ADD_VLAN_ID**, **SAI_ACL_ENTRY_ATTR_ACTION_SET_OUTER_VLAN_ID** and **SAI_ACL_ENTRY_ATTR_ACTION_SET_INNER_VLAN_ID** actions to achieve PAC functionality. - -### 3.5.3 VFP -VFP rules match on the packet fields like source MAC (bcmFieldQualifySrcMac) and VLAN format (bcmFieldQualifyVlanFormat) to qualify packets for VLAN translation and add VLAN tags accordingly (bcmFieldActionOuterVlanAdd, bcmFieldActionOuterVlanNew). - -Config sequence: -``` -bcm_field_entry_create(unit, group, &entry); -bcm_field_qualify_SrcMac(unit, entry, mac, mac_mask); - -Qualify on untagged packets and add VLAN tag: -bcm_field_qualify_VlanFormat(unit, entry, 0x40, 0xff ); -bcm_field_action_add(unit, entry, bcmFieldActionOuterVlanAdd, vlan, 0, 0); - -Qualify on tagged packets and change VLAN tag: -bcm_field_qualify_VlanFormat(unit, entry, 0x01, 0xff ); -bcm_field_action_add(unit, entry, bcmFieldActionOuterVlanNew, vlan, 0, 0); -``` ## 3.6 Manageability