YANG Data Model for Network Access Control Lists (ACLs)
Extracted elements (26)
Feature statements serve two purposes: the first set advertises per-header-type device capabilities (e.g., 'match-on-eth'); the second set advertises which combinations of header types a device supports (e.g., 'mixed-eth-ipv4'). This two-tier model prevents misconfiguration of ACE types within an ACL.
The 'matches' container's choices for L2, L3, and L4 are expressed as separate YANG choice statements, allowing only one variant per layer per ACE. Additional match criteria (e.g., IPFIX) can be added by augmenting the 'matches' container rather than modifying the base module.
The model is split into two YANG modules: 'ietf-access-control-list' (generic ACL structure) and 'ietf-packet-fields' (header-field groupings). The separation keeps the base module simple and allows packet-field groupings to be reused independently in other models.
To apply an ACL to any attachment point other than an interface (e.g., VRF, vty/tty, QoS policy, routing protocol), vendors MUST augment the ACL YANG model. The base model only provides interface attachment natively, intentionally keeping the core simple.
Linux nftables follows a structure very similar to the ietf-access-control-list module: a single utility with input/output ACEs each having match and action. The RFC notes that translation between the ACL YANG model and Linux nftables should be straightforward.
Vendor-proprietary extensions should be implemented by augmenting the base model using YANG 'augment' with XPath expressions targeting the 'matches' or 'actions' containers. The 'example-newco-acl' appendix demonstrates adding payload matching, metadata matching, count/policer actions, and a default-action leaf.
In the port-range-or-operator grouping, when a range case is used, the lower-port MUST be less than or equal to the upper-port. This is enforced with a YANG 'must' statement that generates an error-message on violation.
The ACL name leaf MUST have a length between 1 and 64 characters. A device MAY further restrict the length; space and special characters are not allowed.
The 'forwarding' leaf inside the ACE 'actions' container is mandatory (mandatory true), meaning every ACE MUST declare an explicit forwarding action.
ACL type identities (ipv4-acl-type, ipv6-acl-type, eth-acl-type, mixed-eth-ipv4-acl-type, mixed-eth-ipv6-acl-type, mixed-eth-ipv4-ipv6-acl-type) all derive from acl-base and are guarded by corresponding feature statements. The 'type' leaf on an ACL drives YANG 'when' conditions that enforce which match containers are available for its ACEs.
Each ACE 'matches' container provides mutually exclusive choices at three header layers: L2 (eth), L3 (ipv4 or ipv6), and L4 (tcp, udp, or icmp). Additional metadata match leaves 'egress-interface' and 'ingress-interface' are available outside the layer choices. If no matches are specified, any packet matches the ACE.
Ethernet match fields ('acl-eth-header-fields') include destination-mac-address, destination-mac-address-mask, source-mac-address, source-mac-address-mask (all yang:mac-address), and ethertype (eth:ethertype in canonical IEEE 802 lowercase representation).
ICMP match fields ('acl-icmp-header-fields') include type (uint8), code (uint8), and rest-of-header (binary, unbounded). These fields apply to both ICMPv4 and ICMPv6.
IPv4-specific match fields ('acl-ipv4-header-fields') include ihl (uint8, range 5..60), flags (bits: reserved, fragment, more), offset (uint16, fragment offset), identification (uint16), destination-ipv4-network (inet:ipv4-prefix), and source-ipv4-network (inet:ipv4-prefix).
IPv6-specific match fields ('acl-ipv6-header-fields') include destination-ipv6-network (inet:ipv6-prefix), source-ipv6-network (inet:ipv6-prefix), and flow-label (inet:ipv6-flow-label). Source/destination are expressed as choices to allow future extension.
Port matching is expressed via the 'port-range-or-operator' grouping, which offers two cases: a 'range' case with mandatory lower-port and upper-port leaves (both inet:port-number, range inclusive), and an 'operator' case with an operator enum (lte, gte, eq, neq; default eq) and a mandatory port leaf.
Statistics are available at two granularities controlled by features: 'acl-aggregate-stats' exposes per-ACE matched-packets and matched-octets (yang:counter64, config false) aggregated across all interfaces; 'interface-stats' exposes per-ACE, per-interface counters under the attachment-points/interface tree.
TCP match fields ('acl-tcp-header-fields') include sequence-number (uint32), acknowledgement-number (uint32), data-offset (uint8, range 5..15), reserved (uint8), flags (bits: cwr, ece, urg, ack, psh, rst, syn, fin), window-size (uint16), urgent-pointer (uint16), and options (binary, length 1..40).
The 'acl-ip-header-fields' grouping defines common IPv4/IPv6 match fields: dscp (inet:dscp), ecn (uint8, range 0..3), length (uint16), ttl (uint8), and protocol (uint8). These fields are reused in both ipv4 and ipv6 match containers.
The 'actions' container within each ACE has a mandatory 'forwarding' leaf (identityref based on forwarding-action: accept, drop, or reject) and an optional 'logging' leaf (identityref based on log-action: log-syslog or log-none, defaulting to log-none).
The 'attachment-points' container (feature: interface-attachment) holds a list of interfaces, each with separate 'ingress' and 'egress' sub-containers. Each direction carries an ordered list of ACL references (leafrefs to /acls/acl/name) and optional per-ACE interface statistics.
The top-level data model is a 'acls' container holding a list of ACLs keyed by name. Each ACL contains an ordered list of ACEs (Access Control Entries), each with a 'matches' container and an 'actions' container. ACEs are ordered by user and processed first-match-wins.
This document registers three URIs in the IETF XML Registry (RFC 3688): urn:ietf:params:xml:ns:yang:ietf-access-control-list, urn:ietf:params:xml:ns:yang:ietf-packet-fields, and urn:ietf:params:xml:ns:yang:ietf-ethertypes.
This document registers three YANG modules in the 'YANG Module Names' registry (RFC 6020): 'ietf-access-control-list' (prefix acl, namespace urn:ietf:params:xml:ns:yang:ietf-access-control-list), 'ietf-packet-fields' (prefix packet-fields), and 'ietf-ethertypes' (prefix ethertypes).
Unauthorized write access to /acls/acl/aces/ace/actions/logging can enable logging on many ACEs, overwhelming the server. Unauthorized read access to logging configuration can reveal information useful for crafting attacks. NETCONF transport MUST use SSH; RESTCONF MUST use TLS (RFC 8446).
Unauthorized write access to /acls/acl/aces can allow intruders to modify ACEs to permit traffic that should be denied (potentially enabling compromise or DoS) or deny traffic that should be permitted (DoS). Read access exposes which rules are in effect, aiding attack crafting. NACM (RFC 8341) should be used to restrict access.