RFC 9899

Extensions to the YANG Data Model for Access Control Lists (ACLs)

📅 published December 2025, from ietf

Abstract ✨

RFC 9899 is Extensions to the YANG Data Model for Access Control Lists (ACLs) 🎀 It was published by the Internet Engineering Task Force (IETF) in December 2025, and it's a Standards Track document, so it's real protocol spec, not just an idea. The ISSN is 2070-1721. The authors are O. Gonzalez de Dios (Telefonica), S. Barguil (Nokia), M. Boucadair (Orange), and Q. Wu (Huawei). Its header doesn't list anything it obsoletes or updates.

RFC 8519 defines a YANG data model for Access Control Lists (ACLs). This document specifies a set of extensions that fix many of the limitations of the ACL model as RFC 8519 first defined it. Specifically, it adds augmentations to the ACL base model to make it more functional and useful in more places. 💅

This document also creates initial versions of IANA-maintained modules for ICMP types and IPv6 extension headers. 🦋

Status of This Memo 📜

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9899.

Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.

Table of Contents 🗺️

   1.  Introduction
   2.  Terminology
   3.  Overall Structure of the Enhanced ACL Module
     3.1.  Tree Structure
     3.2.  Defined Sets
     3.3.  IPv6 Extension Headers
     3.4.  TCP Flags Handling
     3.5.  Fragments Handling
     3.6.  Payload-Based Filtering
     3.7.  Match on MPLS Headers
     3.8.  VLAN Filtering
     3.9.  Instance Service Identifier (I-SID) Filtering
     3.10. Additional Actions
   4.  Enhanced ACL YANG Module
   5.  Security Considerations
   6.  IANA Considerations
     6.1.  URI Registrations
     6.2.  YANG Module Name Registrations
     6.3.  Considerations for IANA-Maintained Modules
       6.3.1.  ICMPv4 Types IANA Module
       6.3.2.  ICMPv6 Types IANA Module
       6.3.3.  IPv6 Extension Header Types IANA Module
   7.  References
     7.1.  Normative References
     7.2.  Informative References
   Appendix A.  Problem Statement and Gap Analysis
     A.1.  Suboptimal Configuration: Lack of Support for Lists of
           Prefixes
     A.2.  Manageability: Impossibility of Using Aliases or Defined
           Sets
     A.3.  Bind ACLs to Devices, Not Only Interfaces
     A.4.  Partial or Lack of IPv4/IPv6 Fragment Handling
     A.5.  Suboptimal TCP Flags Handling
     A.6.  Rate-Limit Action
     A.7.  Payload-Based Filtering
     A.8.  Reuse the Content of ACLs Across Several Devices
     A.9.  Match MPLS Headers
   Appendix B.  Examples
     B.1.  TCP Flags Handling
     B.2.  Fragments Handling
     B.3.  Pattern-Based Filtering
     B.4.  VLAN Filtering
     B.5.  I-SID Filtering
     B.6.  Rate-Limit
   Acknowledgments
   Authors' Addresses

1. Introduction ✨

[RFC8519] defines Access Control Lists (ACLs) as a user-ordered set of filtering rules. It's the model for configuring how a device filters traffic. The problem is that the model structure, as [RFC8519] defines it, has a bunch of limitations 😭 This document calls those out and specifies an enhanced ACL structure, which adds augmentations to the ACL base model (Section 4). Appendix A explains the motivation for all of this in detail.

When managing ACLs, network operators usually group match elements into predefined sets. Grouping matches cuts down on the number of rules, which matters a lot in large-scale networks. For example, if you need to match against 100 IP addresses (or prefixes), one rule will do the job instead of a separate Access Control Entry (ACE) for each IP address (or prefix). Doing it this way lets implementations optimize the performance of matching lists versus matching multiple rules. Main character energy 🎀

The enhanced ACL structure (see "ietf-acl-enh" in Section 4) is also meant to make life easier for network operators. Instead of typing in IP address or port number literals, you use user-named lists, and that decouples creating the rule from managing the sets. So you can remove or add entries to a list without redefining the parent ACL rule. Iconic. 💖

The notion of ACL and defined sets also gets generalized, so it isn't tied to one device the way it is in [RFC8519]. ACLs and defined sets can be defined at the network or administrative domain level and then associated with devices. That makes them reusable across many network elements. For example, managing IP prefix sets from the network level makes them easier for security groups to maintain. 🧚

Network operators maintain sets of IP prefixes that relate to each other, like deny-lists or accept-lists tied to what a VPN customer provides. Security expert teams at the network operators are the ones who maintain and manipulate these lists. 🔥

Just a heads up: ACLs are used locally on devices, but other tools trigger them, like DDoS mitigation [RFC9132] or BGP Flow Spec [RFC8955] [RFC8956]. So from a network operations point of view, it's really valuable to be able to map easily to the filtering rules carried in messages those tools send. 🌈

The enhanced ACL module (Section 4) conforms to the Network Management Datastore Architecture (NMDA) defined in [RFC8342].

There's a set of examples showing how to use the enhanced ACL module in Appendix B. 🍓

This document also creates initial versions of IANA-maintained modules for ICMP types and IPv6 extension headers. The design of these modules follows the recommendations in Section 4.30.2 of [YANG-GUIDELINES]. You can grab the latest version of these IANA-maintained modules from the "YANG Parameters" registry group [IANA-YANG-PARAMETERS]. 🦋

2. Terminology 📖

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 💜

The terminology for describing YANG modules is defined in [RFC7950]. The meaning of the symbols in the tree diagrams is defined in [RFC8340].

In addition to the terms defined in [RFC8519], this document makes use of the following term:

Defined set: Elements in a defined set typically share a logical purpose or function, such as IP addresses, IP prefixes, port numbers, or ICMP types. 🎀

3. Overall Structure of the Enhanced ACL Module ✨

3.1. Tree Structure ✨

okay so bestie, here's the full tree of the enhanced ACL module (Section 4) 🌳💅

module: ietf-acl-enh

  augment /acl:acls:
    +--rw defined-sets
       +---u defined-sets
  augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches:
    +--rw (payload)?
    |  +--:(pattern)
    |     +--rw pattern {match-on-payload}?
    |        +---u payload-match
    +--rw (alias)?
    |  +--:(alias-name)
    |     +--rw alias-name*       alias-ref
    +--rw (mpls)?
       +--:(mpls-values)
          +--rw mpls-values {match-on-mpls}?
             +---u mpls-match-parameters-config
  augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches/acl:l2:
    +--rw vlan-filter {match-on-vlan-filter}?
    |  +--rw frame-type?         string
    |  +--rw (vlan-type)?
    |     +--:(range)
    |     |  +--rw lower-vlan    uint16
    |     |  +--rw upper-vlan    uint16
    |     +--:(operator)
    |        +--rw operator?     packet-fields:operator
    |        +--rw vlan*         uint16
    +--rw isid-filter {match-on-isid-filter}?
       +--rw (isid-type)?
          +--:(range)
          |  +--rw lower-isid    uint16
          |  +--rw upper-isid    uint16
          +--:(operator)
             +--rw operator?     packet-fields:operator
             +--rw isid*         uint16
  augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches/acl:l3
            /acl:ipv4/acl:ipv4:
    +--rw ipv4-fragment
    |  +---u fragment-fields
    +--rw source-ipv4-prefix-list?        ipv4-prefix-set-ref
    +--rw destination-ipv4-prefix-list?   ipv4-prefix-set-ref
    +--rw protocol-set?                   protocol-set-ref
  augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches/acl:l3
            /acl:ipv6/acl:ipv6:
    +--rw ipv6-fragment
    |  +---u fragment-fields
    +--rw source-ipv6-prefix-list?        ipv6-prefix-set-ref
    +--rw destination-ipv6-prefix-list?   ipv6-prefix-set-ref
    +--rw protocol-set?                   protocol-set-ref
    +--rw extension-header?
            iana-ipv6-ext-types:ipv6-extension-header-type
  augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches/acl:l4
            /acl:tcp/acl:tcp:
    +--rw flags-bitmask
    |  +---u tcp-flags
    +--rw source-tcp-port-set?        port-set-ref
    +--rw destination-tcp-port-set?   port-set-ref
  augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches/acl:l4
            /acl:udp/acl:udp:
    +--rw source-udp-port-set?        port-set-ref
    +--rw destination-udp-port-set?   port-set-ref
  augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches/acl:l4
            /acl:icmp/acl:icmp:
    +--rw icmpv4-set?   icmpv4-type-set-ref
    +--rw icmpv6-set?   icmpv6-type-set-ref
  augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:actions:
    +---u acl-complementary-actions
    +--rw rate-limit?                  decimal64

Figure 1: Enhanced ACL Tree Structure

Figure 2 shows the reusable groupings that are defined in the enhanced ACL module 🧩✨

  grouping tcp-flags:
    +--rw operator?                  operator
    +-- (mode)?
       +--:(explicit)
       |  +-- explicit-tcp-flag*   identityref
       +--:(builtin)
          +-- bitmask?             uint16
  grouping fragment-fields:
    +-- operator?   operator
    +-- type?       fragment-type
  grouping mpls-match-parameters-config:
    +-- traffic-class?       uint8
    +-- label-position?      identityref
    +-- upper-label-range?   rt-types:mpls-label
    +-- lower-label-range?   rt-types:mpls-label
    +-- label-block-name?    string
    +-- ttl-value?           uint8
  grouping payload-match:
    +-- offset?       identityref
    +-- length?   uint16
    +-- operator?     operator
    +-- pattern?       binary
  grouping alias:
    +-- vlan*         uint16
    +-- prefix*       inet:ip-prefix
    +-- port-range* [lower-port]
    |  +-- lower-port    inet:port-number
    |  +-- upper-port?   inet:port-number
    +-- protocol*     uint8
    +-- fqdn*         inet:domain-name
    +-- uri*          inet:uri
  grouping icmpv4-header-fields:
    +-- type?             iana-icmpv4-types:icmpv4-type
    +-- code?             uint8
    +-- rest-of-header?   binary
  grouping icmpv6-header-fields:
    +-- type?             iana-icmpv6-types:icmpv6-type
    +-- code?             uint8
    +-- rest-of-header?   binary
  grouping acl-complementary-actions:
    +-- log-action
    |  +-- log-type?   identityref
    |  +-- log-id?     string
    +-- counter-action
       +-- counter-type?   identityref
       +-- counter-name*   string
  grouping ipv4-prefix-sets:
    +-- prefix-set* [name]
       +-- name           string
       +-- description?   string
       +-- prefix*        inet:ipv4-prefix
  grouping ipv6-prefix-sets:
    +-- prefix-set* [name]
       +-- name           string
       +-- description?   string
       +-- prefix*        inet:ipv6-prefix
  grouping port-sets:
    +-- port-set* [name]
       +-- name    string
       +-- port* [id]
          +-- id                              string
          +-- (port)?
             +--:(port-range-or-operator)
                +-- port-range-or-operator
                   +---u packet-fields:port-range-or-operator
  grouping protocol-sets:
    +-- protocol-set* [name]
       +-- name        string
       +-- protocol*   union
  grouping icmpv4-type-sets:
    +-- set* [name]
       +-- name           string
       +-- icmpv4-type* [type]
          +---u icmpv4-header-fields
  grouping icmpv6-type-sets:
    +-- set* [name]
       +-- name           string
       +-- icmpv6-type* [type]
          +---u icmpv6-header-fields
  grouping aliases:
    +-- alias* [name]
       +-- name     string
       +---u alias
  grouping defined-sets:
    +-- ipv4-prefix-sets
    |  +---u ipv4-prefix-sets
    +-- ipv6-prefix-sets
    |  +---u ipv6-prefix-sets
    +-- port-sets
    |  +---u port-sets
    +-- protocol-sets
    |  +---u protocol-sets
    +-- icmpv4-type-sets
    |  +---u icmpv4-type-sets
    +-- icmpv6-type-sets
    |  +---u icmpv6-type-sets
    +-- aliases
       +---u aliases

Figure 2: Enhanced ACL Groupings

3.2. Defined Sets 🎀

okay the augmented ACL structure has a bunch of containers for reusable sets of stuff you can match in an ACL entry 🧺 each set gets a name and can be called from the relevant entry. these are the sets (you can spot them in Figure 1) 👀

  • IPv4 prefix sets: an IPv4 prefix set holds a list of IPv4 prefixes. it's a match if the IP address (source or destination, depending on the ACL entry) is inside any of the prefixes in the set 🌸
  • IPv6 prefix sets: an IPv6 prefix set holds a list of IPv6 prefixes. same vibe: it's a match if the IP address (source or destination, depending on the ACL entry) is inside any of the prefixes in the set 💜
  • Port sets: a port set holds a list of port numbers for transport protocol entries (like TCP and UDP) 🔌
    • a port number can be a port range, or a single port number with an operator (equal to, greater than or equal to, etc.) 🧮
  • Protocol sets: a protocol set holds a list of protocol values. a protocol can be identified by a number (like 17) or a name (like UDP) 🦋
  • ICMP sets: an ICMP set holds a list of ICMPv4 [RFC0792] or ICMPv6 [RFC4443] types. each type is identified by a type value, and can optionally be identified by the code and the rest of the header 🧊
    • IANA-maintained modules for ICMP types are created in this document 🏛️
  • Aliases: an alias is defined by a combination of different parameters (like IP prefix, protocol, port number, or VLAN [IEEE802.1Qcp]). when you're only handling sets of one parameter (like protocol), the relevant parameter sets should be used (like protocol set) instead of an alias 🙅‍♀️
    • for example, an alias can be made to apply ACL policies bound to a set of HTTPS servers 🔐 that alias will typically include those HTTPS server addresses (like "prefix": ["2001:db8:6401::1/128","2001:db8:6401::2/128"]) and the TCP port number 443 (i.e., "protocol": [6] and "lower-port": 443) ✨
    • sets of aliases can be defined and referred to in ACL match criteria 🫶
  • Payload-based filtering: a filtering technique that looks at the data payload of packets, not just the header info, to identify, allow, or block traffic based on specific content or patterns inside the payload 👀 an offset type (like Layer 2 or Layer 3) is used to show where the data sits in the packet to use for the match 📍

3.3. IPv6 Extension Headers 🌈

the enhanced ACL module can manage ACLs that need to match against IPv6 extension headers [RFC8200] 🧚 to make that happen, a brand new IANA-maintained module for IPv6 extension header types, "iana-ipv6-ext-types", is created in this document 💖

3.4. TCP Flags Handling 🚩

the augmented ACL module has a new container 'flags-bitmask' to handle TCP flags better (Section 3.1 of [RFC9293]) 🎯 assigned TCP flags are kept in the "TCP Header Flags" registry under the "Transmission Control Protocol (TCP) Parameters" registry group [IANA-TCP-FLAGS] 📜

clients that support both 'flags-bitmask' and 'flags' [RFC8519] matching fields MUST NOT set these fields in the same request 🙅‍♀️💀

3.5. Fragments Handling 🧩

the augmented ACL module has new leafs 'ipv4-fragment' and 'ipv6-fragment' so fragments get handled more nicely 🥹

clients that support both 'ipv4-fragment' and 'flags' [RFC8519] matching fields MUST NOT set these fields in the same request 🚫 this is giving "don't mix these two in one request" energy, bestie 💅

3.6. Payload-Based Filtering 🍓

some transport protocols use existing protocols (like TCP or UDP) as a substrate 🫧 the match criteria for these can rely on the 'protocol' under 'l3', TCP/UDP match criteria, part of the TCP/UDP payload, or a mix of those 🌀

a new feature called 'match-on-payload' is defined in this document ✨ it can be used, for example, for QUIC [RFC9000] or for tunneling protocols 🚇 this feature needs you to configure a data offset, a length, and a binary pattern to match the data against, using a specified operator 🔍 the data offset shows the position to look at in a packet (for example, it can start at the beginning of the IP header or the transport header) 📦

3.7. Match on MPLS Headers 🏷️

the enhanced ACL module (Section 4) can be used to make rules that match against the MPLS fields of a packet 🎀 the MPLS header defined in [RFC3032] and [RFC5462] has these fields:

  • Traffic Class: the 3-bit "Exp" field [RFC3032], which gets renamed to "Traffic Class field" ("TC field") [RFC5462] 🌷
  • Label Value: a 20-bit field that carries the actual value of the MPLS label 💜
  • TTL: an 8-bit field used to encode the Time-to-Live (TTL) value ⏳

the augmented ACL module can be used by an operator to configure ACLs that match based on these data nodes 🧁

  • 'traffic-class'
  • 'label-position' (e.g., top or bottom)
  • 'upper-label-range'
  • 'lower-label-range'
  • 'label-block-name'
  • 'ttl-value'

3.8. VLAN Filtering 🎀

Okay so filtering every packet bridged inside a VLAN, or routed into or out of a bridge domain, is part of the VPN control requirements for Ethernet VPN (EVPN) [RFC7209]. Literally essential 💅

All packets that are bridged within a VLAN, or that are routed into or out of a VLAN, can be captured, forwarded, translated, or discarded based on the network policy. Your policy decides the fate of every single packet 👑

3.9. Instance Service Identifier (I-SID) Filtering 🦋

Okay, history moment! Provider Backbone Bridging (PBB) was originally defined as a Virtual Bridged Local Area Networks standard [IEEE-802-1ah]. Instead of multiplexing VLANs, PBB duplicates the Media Access Control (MAC) layer of the customer frame and separates it from the provider domain. It does this by encapsulating the frame in a 24-bit Instance Service Identifier (I-SID). The result is more transparency between the customer network and the provider network. So clean 🧚

The I-component is the customer- or access-facing interface or routing instance. It's the one in charge of mapping customer Ethernet traffic to the right I-SID. It is mandatory to configure the default service identifier in the network, so don't skip it 🫶

Being able to filter by I-component service identifier is a feature of the EVPN-PBB configuration. Iconic, honestly 🔥

3.10. Additional Actions ✨

Quick one: to support rate-limiting (see Appendix A.6), this document defines a new action called rate-limit. Main character energy 💖

The ietf-acl-enh module also adds new actions to complement the existing ones. There's log (log-action) and write a counter (counter-action). Heads up though: the version of the module defined in this document supports only local actions 🙈

4. Enhanced ACL YANG Module 💜

This YANG module imports types from [RFC6991], [RFC8519], and [RFC8294]. Here's the whole thing, no cap 💅

<CODE BEGINS> file "ietf-acl-enh@2025-12-22.yang"
module ietf-acl-enh {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-acl-enh";
  prefix acl-enh;

  import ietf-inet-types {
    prefix inet;
    reference
      "RFC 6991: Common YANG Data Types";
  }
  import ietf-netconf-acm {
    prefix nacm;
    reference
      "RFC 8341: Network Configuration Access Control Model";
  }
  import ietf-access-control-list {
    prefix acl;
    reference
      "RFC 8519: YANG Data Model for Network Access
                 Control Lists (ACLs), Section 4.1";
  }
  import ietf-packet-fields {
    prefix packet-fields;
    reference
      "RFC 8519: YANG Data Model for Network Access
                 Control Lists (ACLs), Section 4.2";
  }
  import ietf-routing-types {
    prefix rt-types;
    reference
      "RFC 8294: Common YANG Data Types for the Routing Area";
  }
  import iana-icmpv4-types {
    prefix iana-icmpv4-types;
    reference
      "RFC 9899: Extensions to the YANG Data Model for Access
                 Control Lists (ACLs)";
  }
  import iana-icmpv6-types {
    prefix iana-icmpv6-types;
    reference
      "RFC 9899: Extensions to the YANG Data Model for Access
                 Control Lists (ACLs)";
  }
  import iana-ipv6-ext-types {
    prefix iana-ipv6-ext-types;
    reference
      "RFC 9899: Extensions to the YANG Data Model for Access
                 Control Lists (ACLs)";
  }

  organization
    "IETF NETMOD Working Group";
  contact
    "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
     WG List:  <mailto:netmod@ietf.org>

     Author:   Mohamed Boucadair
               <mailto:mohamed.boucadair@orange.com>
     Author:   Samier Barguil
               <mailto:samier.barguil_giraldo@nokia.com>
     Author:   Oscar Gonzalez de Dios
               <mailto:oscar.gonzalezdedios@telefonica.com>";
  description

    "This module contains YANG definitions for enhanced ACLs.

     Copyright (c) 2025 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC 9899; see the
     RFC itself for full legal notices.";

  revision 2025-12-22 {
    description
      "Initial revision.";
    reference
      "RFC 9899: Extensions to the YANG Data Model for Access
                 Control Lists (ACLs)";
  }

  feature match-on-payload {
    description
      "Match based on a pattern is supported.";
  }

  feature match-on-vlan-filter {
    description
      "Match based on a VLAN range is supported.";
  }

  feature match-on-isid-filter {
    description
      "Match based on an I-SID range is supported.";
  }

  feature match-on-alias {
    description
      "Match based on aliases.";
  }

  feature match-on-mpls {
    description
      "Match based on MPLS headers.";
  }

  identity offset-type {
    description
      "Base identity for payload offset type.";
  }

  identity layer2 {
    base offset-type;
    description
      "The offset starts at the beginning of the Data Link Layer
       header.";
  }

  identity layer3 {
    base offset-type;
    description
      "The offset starts at the beginning of the IP header.";
  }

  identity layer4 {
    base offset-type;
    description
      "The offset starts right after the IP header (including
       any options or headers pertaining to that IP layer, e.g.,
       IPv6 Extension Headers and the Authentication Header (AH)).

       This can be typically the beginning of transport header
       (e.g., UDP, TCP, the Stream Control Transmission Protocol
       (SCTP), and the Datagram Congestion Control Protocol (DCCP))
       or any encapsulation scheme over IP such as IP-in-IP.";
  }

  identity payload {
    base offset-type;
    description
      "The offset starts right after the end of the transport
       header.  For example, this represents the beginning of the
       TCP data right after any TCP options or the beginning of
       the UDP payload right after the UDP header.

       This type may be used for matches against any data in
       the transport payload and/or any surplus area (if any,
       such as in UDP).";
  }

  identity tcp-flag {
    description
      "Base identity for the TCP Flags.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity ack {
    base tcp-flag;
    description
      "Acknowledgment TCP flag bit.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity syn {
    base tcp-flag;
    description
      "Synchronize sequence numbers.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity fin {
    base tcp-flag;
    description
      "No more data from the sender.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity urg {
    base tcp-flag;
    description
      "Urgent pointer TCP flag bit.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity psh {
    base tcp-flag;
    description
      "The Push function flag is similar to the URG flag and tells
       the receiver to process these packets as they are received
       instead of buffering them.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity rst {
    base tcp-flag;
    description
      "Reset TCP flag bit.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity ece {
    base tcp-flag;
    description
      "ECN-Echo TCP flag bit.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity cwr {
    base tcp-flag;
    description
      "Congestion Window Reduced flag bit.";
    reference
      "RFC 9293: Transmission Control Protocol (TCP), Section 3.1";
  }

  identity ae {
    base tcp-flag;
    description
      "Accurate Explicit Congestion Notification (ECN).

       Previously used as Nonce Sum (NS), which is now
       historic.";
  }

  identity mpls-acl-type {
    base acl:acl-base;
    description
      "An ACL that matches on fields from the MPLS header.";
  }

  identity label-position {
    description
      "Base identity for deriving MPLS label position.";
  }

  identity top {
    base label-position;
    description
      "Top of the label stack.";
  }

  identity bottom {
    base label-position;
    description
      "Bottom of the label stack.";
  }

  identity log-types {
    description
      "Base identity for deriving the log actions.";
  }

  identity local-log {
    base log-types;
    description
      "A local log is used to record the ACL results.";
  }

  identity counter-type {
    description
      "Base identity for deriving the counter actions.";
  }

  identity counter-name {
    base counter-type;
    description
      "Identity for counter name to be updated based on
        the ACL match actions.";
  }

  typedef operator {
    type bits {
      bit not {
        position 0;
        description
          "If set, the logical negation of operation.";
      }
      bit match {
        position 1;
        description
          "Match bit.  This is a bitwise match operation defined as
           '(data & value) == value'.";
      }
      bit any {
        position 2;
        description
          "Any bit.  This is a match on any of the bits in bitmask.
           It evaluates to 'true' if any of the bits in the
           value mask are set in the data, i.e.,
           '(data & value) != 0'.";
      }
    }
    description
      "Specifies how to apply the defined bitmask.  The
       'any' and 'match' bits must not be set simultaneously.";
  }

  typedef fragment-type {
    type bits {
      bit df {
        position 0;
        description
          "Don't fragment bit for IPv4.  Must be set to 0 when it
           appears in an IPv6 filter.";
      }
      bit isf {
        position 1;
        description
          "Is a fragment.";
      }
      bit ff {
        position 2;
        description
          "First fragment.";
      }
      bit lf {
        position 3;
        description
          "Last fragment.";
      }
    }
    description
      "Different fragment types to match against.";
  }

  typedef ipv4-prefix-set-ref {
    type leafref {
      path "/acl:acls/acl-enh:defined-sets/acl-enh:ipv4-prefix-sets"
         + "/acl-enh:prefix-set/acl-enh:name";
    }
    description
      "Defines a reference to an IPv4 prefix set.";
  }

  typedef ipv6-prefix-set-ref {
    type leafref {
      path "/acl:acls/acl-enh:defined-sets/acl-enh:ipv6-prefix-sets"
         + "/acl-enh:prefix-set/acl-enh:name";
    }
    description
      "Defines a reference to an IPv6 prefix set.";
  }

okay so the first batch is all typedefs, which are basically little named pointers 💖 each one says "go look over here in the tree" for a set. no cap, it's giving organization 🎀

typedef port-set-ref {
  type leafref {
    path "/acl:acls/acl-enh:defined-sets/acl-enh:port-sets"
       + "/acl-enh:port-set/acl-enh:name";
  }
  description
    "Defines a reference to a port set.";
}

typedef protocol-set-ref {
  type leafref {
    path "/acl:acls/acl-enh:defined-sets/acl-enh:protocol-sets"
       + "/acl-enh:protocol-set/acl-enh:name";
  }
  description
    "Defines a reference to a protocol set.";
}

typedef icmpv4-type-set-ref {
  type leafref {
    path "/acl:acls/acl-enh:defined-sets/acl-enh:icmpv4-type-sets"
       + "/acl-enh:set/acl-enh:name";
  }
  description
    "Defines a reference to an ICMPv4 type set.";
}

typedef icmpv6-type-set-ref {
  type leafref {
    path "/acl:acls/acl-enh:defined-sets/acl-enh:icmpv6-type-sets"
       + "/acl-enh:set/acl-enh:name";
  }
  description
    "Defines a reference to an ICMPv6 type set.";
}

typedef alias-ref {
  type leafref {
    path "/acl:acls/acl-enh:defined-sets/acl-enh:aliases"
       + "/acl-enh:alias/acl-enh:name";
  }
  description
    "Defines a reference to an alias.";
}

next up: the groupings 🦋 think of them as reusable outfits, you clip them onto whatever container needs them ✨ the TCP one is literally the main character of this batch 😭

grouping tcp-flags {
  description
    "Operations on TCP flags.";
  leaf operator {
    type operator;
    description
      "How to interpret the TCP flags.";
  }
  choice mode {
    description
      "Choice of how flags are indicated.";
    case explicit {
      leaf-list explicit-tcp-flag {
        type identityref {
          base acl-enh:tcp-flag;
        }
        description
          "An explicit list of the TCP flags that are to be
           matched.";
      }
    }
    case builtin {
      leaf bitmask {
        type uint16;
        description
          "The bitmask matches the last 4 bits of byte 13
           and byte 14 of the TCP header.
           For clarity, the 4 bits of byte 12
           corresponding to the TCP data offset field are not
           included in any matching.  Assigned TCP flags
           and their position are maintained in the IANA
           'Transmission Control Protocol (TCP) Parameters'
           registry group.";
        reference
          "RFC 9293: Transmission Control Protocol (TCP),
                     Section 3.1
           IANA: Transmission Control Protocol (TCP) Parameters,
           <https://www.iana.org/assignments/tcp-parameters>";
      }
    }
  }
}

grouping fragment-fields {
  description
    "Operations on fragment types.";
  leaf operator {
    type operator;
    default "match";
    description
      "How to interpret the fragment type.";
  }
  leaf type {
    type fragment-type;
    description
      "Specifies what fragment type to look for.";
  }
}

grouping mpls-match-parameters-config {
  description
    "Parameters for the configuration of MPLS match rules.";
  leaf traffic-class {
    type uint8 {
      range "0..7";
    }
    description
      "The value of the MPLS Traffic Class (TC) bits,
       formerly known as the EXP bits.";
  }
  leaf label-position {
    type identityref {
      base acl-enh:label-position;
    }
    description
      "Position of the label.";
  }
  leaf upper-label-range {
    type rt-types:mpls-label;
    description
      "Match MPLS label value on the MPLS header.
       The usage of this field indicates the upper
       range value in the top of the stack.  This
       label value does not include the encodings
       of TC and Time-to-Live (TTL).";
    reference
      "RFC 3032: MPLS Label Stack Encoding";
  }
  leaf lower-label-range {
    type rt-types:mpls-label;
    description
      "Match MPLS label value on the MPLS header.
       The usage of this field indicates the lower
       range value in the top of the stack.
       This label value does not include the
       encodings of TC and TTL.";
    reference
      "RFC 3032: MPLS Label Stack Encoding";
  }
  leaf label-block-name {
    type string;
    description
      "Reference to a label block predefined in the
       implementation.";
  }
  leaf ttl-value {
    type uint8;
    description
      "TTL MPLS packet value match.";
    reference
      "RFC 3032: MPLS Label Stack Encoding";
  }
}

okay the payload match and alias groupings are where it gets spicy 🌶️ the alias one holds the whole vibe: VLANs, prefixes, port ranges, protocols, FQDNs and URIs all in one place 🍓

grouping payload-match {
  description
    "Operations on payload match.";
  leaf offset {
    type identityref {
      base acl-enh:offset-type;
    }
    description
      "Indicates the payload offset.  This will indicate
       the position of the data in the packet to use for
       the match.";
  }
  leaf length {
    type uint16;
    units "bytes";
    description
      "Indicates the number of bytes to ignore, starting from
       the offset, to perform the pattern match.";
  }
  leaf operator {
    type operator;
    default "match";
    description
      "How to interpret the pattern match.";
  }
  leaf pattern {
    type binary;
    description
      "The binary pattern to match against starting.
       The match starts from the byte indicated by
       'offset' + length'.";
  }
}

grouping alias {
  description
    "Specifies an alias.";
  leaf-list vlan {
    type uint16;
    description
      "VLAN of the alias.";
    reference
      "IEEE Std 802.1Q: Bridges and Bridged Networks";
  }
  leaf-list prefix {
    type inet:ip-prefix;
    description
      "IPv4 or IPv6 prefix of the alias.";
  }
  list port-range {
    key "lower-port";
    description
      "Port range.  When only lower-port is
       present, it represents a single port number.";
    leaf lower-port {
      type inet:port-number;
      mandatory true;
      description
        "Lower port number of the port range.";
    }
    leaf upper-port {
      type inet:port-number;
      must '. >= ../lower-port' {
        error-message
          "The upper-port number must be greater than
           or equal to the lower-port number.";
      }
      description
        "Upper port number of the port range.";
    }
  }
  leaf-list protocol {
    type uint8;
    description
      "Identifies the target protocol number.
       For example, 6 for TCP or 17 for UDP.";
  }
  leaf-list fqdn {
    type inet:domain-name;
    description
      "Fully Qualified Domain Name (FQDN) identifying the target.";
  }
  leaf-list uri {
    type inet:uri;
    description
      "URI identifying the target.";
  }
}

last stretch 💜 the ICMP header groupings (v4 and v6, with their own RFC citations), the complementary actions for logging and counting, and the IPv4 prefix sets 🌈

grouping icmpv4-header-fields {
  description
    "Collection of ICMPv4 header fields that can be
     used to set up a match filter.";
  leaf type {
    type iana-icmpv4-types:icmpv4-type;
    description
      "Also known as control messages.";
    reference
      "RFC 792: Internet Control Message Protocol.";
  }
  leaf code {
    type uint8;
    description
      "ICMP subtype.";
    reference
      "RFC 792: Internet Control Message Protocol.";
  }
  leaf rest-of-header {
    type binary;
    description
      "Unbounded in length, the contents vary based on the
       ICMP type and code.";
    reference
      "RFC 792: Internet Control Message Protocol";
  }
}

grouping icmpv6-header-fields {
  description
    "Collection of ICMPv6 header fields that can be
     used to set up a match filter.";
  leaf type {
    type iana-icmpv6-types:icmpv6-type;
    description
      "Also known as control messages.";
    reference
      "RFC 4443: Internet Control Message Protocol (ICMPv6)
                 for Internet Protocol Version 6 (IPv6)
                 Specification.";
  }
  leaf code {
    type uint8;
    description
      "ICMP code.";
    reference
      "RFC 4443: Internet Control Message Protocol (ICMPv6)
                 for Internet Protocol Version 6 (IPv6)
                 Specification.";
  }
  leaf rest-of-header {
    type binary;
    description
      "Unbounded in length, the contents vary based on the
       ICMP type and code.  Also referred to as 'Message Body'
       in ICMPv6.";
    reference
      "RFC 4443: Internet Control Message Protocol (ICMPv6)
                 for Internet Protocol Version 6 (IPv6)
                 Specification.";
  }
}

grouping acl-complementary-actions {
  description
    "Collection of complementary ACL actions.";
  container log-action {
    description
      "Container for defining log actions.";
    leaf log-type {
      type identityref {
        base acl-enh:log-types;
      }
      description
        "The type of log action to be performed.";
    }
    leaf log-id {
      when "derived-from-or-self(../log-type, "
         + "'acl-enh:local-log')" {
        description
          "Name of the log file updated when type is 'local-log'.";
      }
      type string;
      description
        "The name of the counter action.";
    }
  }
  container counter-action {
    description
      "Container for defining counter actions.";
    leaf counter-type {
      type identityref {
        base acl-enh:counter-type;
      }
      description
        "The type of counter action to be performed.";
    }
    leaf-list counter-name {
      when "derived-from-or-self(../counter-type, "
         + "'acl-enh:counter-name')" {
        description
          "Name for the counter or variable to update when
           'counter-type' is 'counter-name'.";
      }
      type string;
      description
        "List of possible variables or counter names to
         update based on match criteria.";
    }
  }
}

grouping ipv4-prefix-sets {
  description
    "Data definitions for a list of IPv4 prefixes,
     which are matched as part of a policy.";
  list prefix-set {
    key "name";
    description
      "List of the defined prefix sets.";
    leaf name {
      type string;
      description
        "Name of the prefix set -- this is used as a label to
         reference the set in match conditions.";
    }
    leaf description {
      type string;
      description
        "Defined set description.";
    }
    leaf-list prefix {
      type inet:ipv4-prefix;
      description
        "List of IPv4 prefixes to be used in match
         conditions.";
    }
  }
}

that's the whole batch, bestie 🌈✨

grouping ipv6-prefix-sets { description "Data definitions for a list of IPv6 prefixes, which are matched as part of a policy."; list prefix-set { key "name"; description "List of the defined prefix sets."; leaf name { type string; description "Name of the prefix set -- this is used as a label to reference the set in match conditions."; } leaf description { type string; description "A textual description of the prefix list."; } leaf-list prefix { type inet:ipv6-prefix; description "List of IPv6 prefixes to be used in match conditions."; } } }

grouping port-sets { description "Data definitions for a list of ports, which can be matched in policies."; list port-set { key "name"; description "List of port set definitions."; leaf name { type string; description "Name of the port set -- this is used as a label to reference the set in match conditions."; } list port { key "id"; description "Port numbers along with the operator on which to match."; leaf id { type string; description "Identifier of the list of port numbers."; } choice port { description "Choice of specifying the port number or referring to a group of port numbers."; container port-range-or-operator { description "Indicates a set of ports."; uses packet-fields:port-range-or-operator; } } } } }

grouping protocol-sets { description "Data definitions for a list of protocols, which can be matched in policies."; list protocol-set { key "name"; description "List of protocol set definitions."; leaf name { type string; description "Name of the protocols set -- this is used as a label to reference the set in match conditions."; } leaf-list protocol { type union { type uint8; type string; } description "Value of the protocol set."; } } }

grouping icmpv4-type-sets { description "Data definitions for a list of ICMPv4 types, which can be matched in policies."; list set { key "name"; description "List of ICMPv4 type set definitions."; leaf name { type string; description "Name of the ICMPv4 type set -- this is used as a label to reference the set in match conditions."; } list icmpv4-type { key "type"; description "Includes a list of ICMPv4 types."; uses icmpv4-header-fields; } } }

grouping icmpv6-type-sets { description "Data definitions for a list of ICMPv6 types, which can be matched in policies."; list set { key "name"; description "List of ICMP type set definitions."; leaf name { type string; description "Name of the ICMPv6 type set -- this is used as a label to reference the set in match conditions."; } list icmpv6-type { key "type"; description "Includes a list of ICMPv6 types."; uses icmpv6-header-fields; } } }

grouping aliases { description "Grouping for a set of aliases."; list alias { key "name"; description "List of aliases."; leaf name { type string; description "The name of the alias."; } uses alias; } }

grouping defined-sets { description "Predefined sets of attributes used in policy match statements."; container ipv4-prefix-sets { description "Data definitions for a list of IPv4 or IPv6 prefixes, which are matched as part of a policy."; uses ipv4-prefix-sets; } container ipv6-prefix-sets { description "Data definitions for a list of IPv6 prefixes, which are matched as part of a policy."; uses ipv6-prefix-sets; } container port-sets { description "Data definitions for a list of ports, which can be matched in policies."; uses port-sets; } container protocol-sets { description "Data definitions for a list of protocols, which can be matched in policies."; uses protocol-sets; } container icmpv4-type-sets { description "Data definitions for a list of ICMPv4 types, which can be matched in policies."; uses icmpv4-type-sets; } container icmpv6-type-sets { description "Data definitions for a list of ICMPv6 types, which can be matched in policies."; uses icmpv6-type-sets; } container aliases { description "Top-level container for aliases."; uses aliases; } }

augment "/acl:acls" { description "predefined sets."; container defined-sets { description "Predefined sets of attributes used in policy match statements."; uses defined-sets; nacm:default-deny-write; } }

augment "/acl:acls/acl:acl/acl:aces/acl:ace"

  • "/acl:matches" { description "Adds a match type based on the payload."; choice payload { description "Matches based upon a prefix pattern."; container pattern { if-feature "match-on-payload"; description "Indicates the rule to perform the payload-based match."; uses payload-match; } } choice alias { description "Matches based upon aliases."; leaf-list alias-name { type alias-ref; description "Indicates one or more aliases."; } } choice mpls { description "Matches against MPLS headers, for example, label values."; container mpls-values { if-feature "match-on-mpls"; description "Provides the rule set that matches MPLS headers."; uses mpls-match-parameters-config; } } }

augment "/acl:acls/acl:acl/acl:aces"

  • "/acl:ace/acl:matches/acl:l2" { description "Adds a match type based on MAC VLAN and I-SID filters."; container vlan-filter { if-feature "match-on-vlan-filter"; description "Indicates how to handle MAC VLANs."; leaf frame-type { type string; description "Entering the frame type allows the filter to match a specific type of frame format."; } choice vlan-type { description "VLAN definition from range or operator."; case range { leaf lower-vlan { type uint16; must '. <= ../upper-vlan' { error-message "The lower-vlan must be less than or equal to the upper-vlan."; } mandatory true; description "Lower boundary for a VLAN."; } leaf upper-vlan { type uint16; mandatory true; description "Upper boundary for a VLAN."; } } case operator { leaf operator { type packet-fields:operator; default "eq"; description "Operator to be applied on the VLAN below."; } leaf-list vlan { type uint16; description "VLAN number along with the operator on which to match."; reference "IEEE Std 802.1Q: Bridges and Bridged Networks"; } } } } container isid-filter { if-feature "match-on-isid-filter"; description "Indicates how to handle I-SID filters. The I-component is responsible for mapping customer Ethernet traffic to the appropriate I-SID."; choice isid-type { description "I-SID definition from range or operator."; case range { leaf lower-isid { type uint16; must '. <= ../upper-isid' { error-message "The lower-isid must be less than or equal to the upper-isid."; } mandatory true; description "Lower boundary for an I-SID."; } leaf upper-isid { type uint16; mandatory true; description "Upper boundary for an I-SID."; } } case operator { leaf operator { type packet-fields:operator; default "eq"; description "Operator to be applied on the I-SID below."; } leaf-list isid { type uint16; description "I-SID number along with the operator on which to match."; reference "IEEE 802.1ah: Provider Backbone Bridges"; } } } } }

augment "/acl:acls/acl:acl/acl:aces"

  • "/acl:ace/acl:matches/acl:l3/acl:ipv4/acl:ipv4" { description "Handle non-initial and initial fragments for IPv4 packets."; container ipv4-fragment { must 'not(../acl:flags)' { error-message "Either flags or fragment should be provided, but not both."; } description "Indicates how to handle IPv4 fragments."; uses fragment-fields; } leaf source-ipv4-prefix-list { type ipv4-prefix-set-ref; description "A reference to an IPv4 prefix list to match the source address."; } leaf destination-ipv4-prefix-list { type ipv4-prefix-set-ref; description "A reference to a prefix list to match the destination address."; } leaf protocol-set { type protocol-set-ref; description "A reference to a protocol set to match the protocol field."; } }
     augment "/acl:acls/acl:acl/acl:aces"
           + "/acl:ace/acl:matches/acl:l3/acl:ipv6/acl:ipv6" {
       description
         "Handles non-initial and initial fragments for IPv6 packets.";
       container ipv6-fragment {
         description
           "Indicates how to handle IPv6 fragments.";
         uses fragment-fields;
       }
       leaf source-ipv6-prefix-list {
         type ipv6-prefix-set-ref;
         description
           "A reference to a prefix list to match the source address.";
       }
       leaf destination-ipv6-prefix-list {
         type ipv6-prefix-set-ref;
         description
           "A reference to a prefix list to match the destination
            address.";
       }
       leaf protocol-set {
         type protocol-set-ref;
         description
           "A reference to a protocol set to match the next-header
            field.";
       }
       leaf extension-header {
         type iana-ipv6-ext-types:ipv6-extension-header-type;
         description
           "IPv6 extension header value.";
       }
     }

     augment "/acl:acls/acl:acl/acl:aces"
           + "/acl:ace/acl:matches/acl:l4/acl:tcp/acl:tcp" {
       description
         "Handles TCP flags and port sets.";
       container flags-bitmask {
         must 'not(../acl:flags)' {
           error-message
             "Either flags or flags-bitmask should be provided, but not
              both.";
         }
         description
           "Indicates how to handle TCP flags.";
         uses tcp-flags;
       }
       leaf source-tcp-port-set {
         type port-set-ref;
         description
           "A reference to a port set to match the source port.";
       }
       leaf destination-tcp-port-set {
         type port-set-ref;
         description
           "A reference to a port set to match the destination port.";
       }
     }

     augment "/acl:acls/acl:acl/acl:aces"
           + "/acl:ace/acl:matches/acl:l4/acl:udp/acl:udp" {
       description
         "Handle UDP port sets.";
       leaf source-udp-port-set {
         type port-set-ref;
         description
           "A reference to a port set to match the source port.";
       }
       leaf destination-udp-port-set {
         type port-set-ref;
         description
           "A reference to a port set to match the destination port.";
       }
     }

     augment "/acl:acls/acl:acl/acl:aces"
           + "/acl:ace/acl:matches/acl:l4/acl:icmp/acl:icmp" {
       description
         "Handle ICMP type sets.";
       leaf icmpv4-set {
         type icmpv4-type-set-ref;
         description
           "A reference to an ICMPv4 type set to match the ICMPv4 type
            field.";
       }
       leaf icmpv6-set {
         type icmpv6-type-set-ref;
         description
           "A reference to an ICMPv6 type set to match the ICMPv6 type
            field.";
       }
     }

     augment "/acl:acls/acl:acl/acl:aces"
           + "/acl:ace/acl:actions" {
       description
         "Complementary actions including rate-limit action.";
       uses acl-complementary-actions;
       leaf rate-limit {
         when "../acl:forwarding = 'acl:accept'" {
           description
             "Rate-limit valid only when the accept action is used.";
         }
         type decimal64 {
           fraction-digits 2;
         }
         units "bytes per second";
         description
           "Indicates a rate-limit for the matched traffic.";
       }
     }
   }
   <CODE ENDS>

5. Security Considerations 🔒

okay bestie, this section is modeled after the template in Section 3.7.1 of [YANG-GUIDELINES], so it's giving consistency 🎀

The ietf-acl-enh YANG module is a data model built to be accessed through YANG-based management protocols, like NETCONF [RFC6241] and RESTCONF [RFC8040]. These YANG-based management protocols (1) have to use a secure transport layer (for example SSH [RFC4252], TLS [RFC8446], and QUIC [RFC9000]) and (2) have to use mutual authentication 🔐

The Network Configuration Access Control Model (NACM) [RFC8341] gives you the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. main character energy for access control 💅

There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., config true, which is the default). All writable data nodes are likely to be reasonably sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) and delete operations to these data nodes without proper protection or authentication can have a negative effect on network operations. The following subtrees and data nodes have particular sensitivities/vulnerabilities:

  • 'defined-sets': These lists specify a set of IP addresses, port numbers, protocols, ICMP types, and aliases. Similar to [RFC8519], unauthorized write access to these lists can allow intruders to modify the entries to permit traffic that should not be permitted or deny traffic that should be permitted. The former may result in a DoS attack or compromise a device. The latter may result in a DoS attack.

These sets are defined with "nacm:default-deny-write" tagging 🙈

Some of the readable data nodes in this YANG module may be considered sensitive or vulnerable in some network environments. It is thus important to control read access (e.g., via get, get-config, or notification) to these data nodes. Specifically, the following subtrees and data nodes have particular sensitivities/vulnerabilities:

  • 'defined-sets': Unauthorized read access of these lists will allow an attacker to identify the actual resources that are bound to ACLs. Likewise, access to this information will help an attacker to better scope its attacks to target resources that are specific to a given network instead of performing random scans. Also, disclosing some of this information (e.g., IP addresses of core routers) may nullify the effect of topology-hiding strategies in some networks.

There are no particularly sensitive RPC or action operations ✨

The document defines a match policy based on a pattern that can be observed in a packet. For example, such a policy can be combined with header-based matches in the context of DDoS mitigation. Filtering based on a pattern match is deterministic for packets with unencrypted data. However, the efficiency for encrypted packets depends on the presence of an unvarying pattern. Readers may also refer to Section 11 of [RFC8329] for security considerations related to Network Security Functions (NSFs) that apply packet content matching.

The YANG modules iana-icmpv4-types, iana-icmpv6-types, and iana-ipv6-ext-types define a set of types. These nodes are intended to be reused by other YANG modules. Each module by itself does not expose any data nodes that are writable, data nodes that contain read-only state, or RPCs. As such, there are no additional security issues related to these YANG modules that need to be considered 🫶

6. IANA Considerations 🏠

6.1. URI Registrations

IANA has registered the following URIs in the "ns" registry within the "IETF XML Registry" [RFC3688]:

URI:  urn:ietf:params:xml:ns:yang:ietf-acl-enh
Registrant Contact:  The IESG
XML:  N/A; the requested URI is an XML namespace.

URI:  urn:ietf:params:xml:ns:yang:iana-icmpv4-types
Registrant Contact:  The IESG
XML:  N/A; the requested URI is an XML namespace.

URI:  urn:ietf:params:xml:ns:yang:iana-icmpv6-types
Registrant Contact:  The IESG
XML:  N/A; the requested URI is an XML namespace.

URI:  urn:ietf:params:xml:ns:yang:iana-ipv6-ext-types
Registrant Contact:  The IESG
XML:  N/A; the requested URI is an XML namespace.

6.2. YANG Module Name Registrations

IANA has registered the following YANG modules in the "YANG Module Names" registry [RFC6020] [RFC9890] within the "YANG Parameters" registry group 📚

Name:  ietf-acl-enh
Maintained by IANA:  N
Namespace:  urn:ietf:params:xml:ns:yang:ietf-acl-enh
Prefix:  acl-enh
Reference:  RFC 9899

Name:  iana-icmpv4-types
Maintained by IANA:  Y
Namespace:  urn:ietf:params:xml:ns:yang:iana-icmpv4-types
Prefix:  iana-icmpv4-types
Reference:  RFC 9899

Name:  iana-icmpv6-types
Maintained by IANA:  Y
Namespace:  urn:ietf:params:xml:ns:yang:iana-icmpv6-types
Prefix:  iana-icmpv6-types
Reference:  RFC 9899

Name:  iana-ipv6-ext-types
Maintained by IANA:  Y
Namespace:  urn:ietf:params:xml:ns:yang:iana-ipv6-ext-types
Prefix:  iana-ipv6-ext-types
Reference:  RFC 9899

6.3. Considerations for IANA-Maintained Modules

6.3.1. ICMPv4 Types IANA Module

This document creates the initial version of the IANA-maintained "iana-icmpv4-types" YANG module. The most recent version of the YANG module is available in the "YANG Parameters" registry group [IANA-YANG-PARAMETERS] 🌸

IANA has added this note to the registry:

New values must not be directly added to the "iana-icmpv4-types" YANG module. They must instead be added to the "ICMP Type Numbers" registry [IANA-ICMPv4].

When a value is added to the "ICMP Type Numbers" registry, a new "enum" statement must be added to the "iana-icmpv4-types" YANG module. The "enum" statement, and substatements thereof, should be defined as follows:

  • "enum": Replicates the name from the registry with all illegal characters (e.g., spaces) stripped.
  • "value": Contains the decimal value of the IANA-assigned value.
  • "status": Included only if a registration has been deprecated or obsoleted. IANA "deprecated" maps to YANG status "deprecated", and IANA "obsolete" maps to YANG status "obsolete".
  • "description": Replicates the name from the registry.
  • "reference": Replicates the reference(s) from the registry with the title of the document(s) added.

Unassigned, reserved, or values styled like those in [RFC3692] are not present in the module 🙅‍♀️

When the "iana-icmpv4-types" YANG module is updated, a new "revision" statement with a unique revision date must be added in front of the existing revision statements.

IANA has added this note to "ICMP Type Numbers" registry [IANA-ICMPv4] and listed this document as an additional reference for the registry:

When this registry is modified, the YANG module "iana-icmpv4-types" [IANA-YANG-PARAMETERS] must be updated as defined in RFC 9899.

6.3.2. ICMPv6 Types IANA Module ✨

okay so this section creates the very first version of the IANA-maintained "iana-icmpv6-types" YANG module 🦋. the newest version always lives in the "YANG Parameters" registry group [IANA-YANG-PARAMETERS] 💖

IANA dropped a note on the registry, and it's giving rules 💅

|  New values must not be directly added to the "iana-icmpv6-types"
|  YANG module.  They must instead be added to the "ICMPv6 "type"
|  Numbers" registry [IANA-ICMPv6].

so when a value gets added to the "ICMPv6 "type" Numbers" registry, a new "enum" statement has to show up in the "iana-icmpv6-types" YANG module too 🎀 the "enum" statement, and its substatements, should be defined like this:

  • "enum": Replicates the name from the registry with all illegal characters (e.g., spaces) stripped. 🧚
  • "value": Contains the decimal value of the IANA-assigned value. 🔢
  • "status": Included only if a registration has been deprecated or obsoleted. IANA "deprecated" maps to YANG status "deprecated", and IANA "obsolete" maps to YANG status "obsolete". 🥀
  • "description": Replicates the name from the registry. 📝
  • "reference": Replicates the reference(s) from the registry with the title of the document(s) added. 📚

unassigned, reserved, or private experimentation values are not in the module at all, so don't even look for them 🙈

and when the "iana-icmpv6-types" YANG module gets updated, a new "revision" statement with a unique revision date goes in front of the existing revision statements 🌸

IANA also added a note to the "ICMPv6 "type" Numbers" registry [IANA-ICMPv6] and listed this document as an extra reference for it, and this is the part that's lowkey iconic:

|  When this registry is modified, the YANG module "iana-
|  icmpv6-types" [IANA-YANG-PARAMETERS] must be updated as defined in
|  RFC 9899.

6.3.3. IPv6 Extension Header Types IANA Module 🌈

okay bestie, this one does the same thing but for IPv6 extension headers 💜 it creates the initial version of the IANA-maintained "iana-ipv6-ext-types" YANG module, and the most recent version is in the "YANG Parameters" registry group [IANA-YANG-PARAMETERS] ⭐

IANA's note on the registry says:

|  New values must not be directly added to the "iana-ipv6-ext-types"
|  YANG module.  They must instead be added to the "IPv6 Extension
|  Header Types" registry [IANA-IPv6].

so when a value is added to the "IPv6 Extension Header Types" registry, a new "enum" statement must be added to the "iana-ipv6-ext-types" YANG module 🫶 the "enum" statement, and substatements thereof, should be defined as follows

  • "enum": Replicates the description from the registry with all spaces stripped. ✂️
  • "value": Contains the decimal value of the IANA-assigned value. 🔢
  • "status": Included only if a registration has been deprecated or obsoleted. IANA "deprecated" maps to YANG status "deprecated", and IANA "obsolete" maps to YANG status "obsolete". 🥀
  • "description": Replicates the description from the registry. 📝
  • "reference": Replicates the reference(s) from the registry with the title of the document(s) added. 📚

only unassigned or reserved values are left out of the module, so anything else that's registered needs to be there 🦋

when the "iana-ipv6-ext-types" YANG module is updated, a new "revision" statement with a unique revision date must be added in front of the existing revision statements 💖

IANA added a note to the "IPv6 Extension Header Types" registry [IANA-IPv6] and listed this document as an additional reference for the registry. the note is:

|  When this registry is modified, the YANG module "iana-ipv6-ext-
|  types" [IANA-YANG-PARAMETERS] must be updated as defined in RFC
|  9899.

7. References 📚

7.1. Normative References 🔥

okay the references are the receipts, so here's the whole list, every single one ✨

7.2. Informative References ✨

okay so these are the informative references, aka the "good to know" pile 📚 they're not required to implement the spec, but they give you the backstory, bestie 🫶

Appendix A. Problem Statement and Gap Analysis 🧚

A.1. Suboptimal Configuration: Lack of Support for Lists of Prefixes 💅

okay so the IP prefix data nodes (like destination-ipv4-network or destination-ipv6-network) can't take a whole list of IP prefixes 😭 which means you end up needing a huge pile of ACL entries in your config file. literally so many entries 💀

same problem shows up when you're trying to set up ACLs to fight DDoS attacks coming from a bunch of sources (see [RFC9132] for an example). and it gets even messier when you need a list of sources and destination prefixes in the same filter 🙈

Figure 3 shows what the ACL config looks like for filtering traffic from two prefixes. yes it's long, no it's not cute 😩

{
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "first-prefix",
        "type": "ipv6-acl-type",
        "aces": {
          "ace": [
            {
              "name": "my-test-ace",
              "matches": {
                "ipv6": {
                  "destination-ipv6-network":
                    "2001:db8:6401:1::/64",
                  "source-ipv6-network":
                    "2001:db8:1234::/96",
                  "protocol": 17,
                  "flow-label": 10000
                },
                "udp": {
                  "source-port": {
                    "operator": "lte",
                    "port": 80
                  },
                  "destination-port": {
                    "operator": "neq",
                    "port": 1010
                  }
                }
              },
              "actions": {
                "forwarding": "accept"
              }
            }
          ]
        }
      },
      {
        "name": "second-prefix",
        "type": "ipv6-acl-type",
        "aces": {
          "ace": [
            {
              "name": "my-test-ace",
              "matches": {
                "ipv6": {
                  "destination-ipv6-network":
                    "2001:db8:6401:c::/64",
                  "source-ipv6-network":
                    "2001:db8:1234::/96",
                  "protocol": 17,
                  "flow-label": 10000
                },
                "udp": {
                  "source-port": {
                    "operator": "lte",
                    "port": 80
                  },
                  "destination-port": {
                    "operator": "neq",
                    "port": 1010
                  }
                }
              },
              "actions": {
                "forwarding": "accept"
              }
            }
          ]
        }
      }
    ]
  }
}

      Figure 3: Example Illustrating Suboptimal Use of the ACL Model
                    with a Prefix List (Message Body)

this setup is suboptimal for both of these:

  • network controllers that have to handle big files, because all or part of this config needs to get passed down to the underlying network devices, and
  • devices that might receive this config and therefore have to keep it stored locally.

A.2. Manageability: Impossibility of Using Aliases or Defined Sets 🎀

same vibe as the IP prefix thing, but generalized 🦋 the idea is to introduce "aliases" or "defined sets" so you can reuse definitions across a bunch of ACLs. each category gets modeled in YANG as a list of parameters related to the class it represents. the sets that can be considered are:

  • Prefix sets: used to create lists of IPv4 or IPv6 prefixes.
  • Protocol sets: used to create a list of protocols.
  • Port number sets: used to create lists of TCP or UDP port values (or any other transport protocol that makes uses of port numbers). The identity of the protocols is identified by the protocol set, if present. Otherwise, a set applies to any protocol.
  • ICMP sets: used to create lists of ICMP-based filters. This applies only when the protocol is set to ICMP or ICMPv6.

aliases may also be considered to manage resources that are identified by a combination of various parameters (e.g., prefix, protocol, port number, FQDN, or VLAN IDs). note that some aliases can be provided by decomposing them into separate sets 🫶

A.3. Bind ACLs to Devices, Not Only Interfaces 🌸

in network management, an ACL might get enforced in lots of different network locations 🗺️ so the ACL module should let you bind an ACL to multiple devices, not just (abstract) interfaces.

so the ACL name has to be unique across the whole network, but the same name can be used on many devices when you're enforcing node-specific ACLs ✨

A.4. Partial or Lack of IPv4/IPv6 Fragment Handling 🧩

[RFC8519] doesn't do fragment handling for IPv6 🙅‍♀️ but it offers partial support for IPv4 through the use of 'flags'. the thing is, 'flags' is kinda problematic because it doesn't let you define a bitmask. for example, if a packet has other bits set that aren't covered by the 'flags' filtering clause, that packet will slip right through (because it won't match the ACE) 😬

so defining a new IPv4/IPv6 matching field called 'fragment' is thus required to efficiently handle fragment-related filtering rules 💜

A.5. Suboptimal TCP Flags Handling 🦋

[RFC8519] supports including flags in the TCP match fields, but that structure doesn't support the matching operations that BGP Flow Spec supports. defining this field as a flag bitmask together with a set of operations is meant to efficiently handle TCP flags filtering rules 🔥

A.6. Rate-Limit Action 🍓

[RFC8519] says forwarding actions can be 'accept' (i.e., accept matching traffic), 'drop' (i.e., drop matching traffic without sending any ICMP error message), or 'reject' (i.e., drop matching traffic and send an ICMP error message to the source). but there are situations where the matching traffic can be accepted, just with a rate-limit policy attached 🚦 and [RFC8519] doesn't support that capability yet 👀

A.7. Payload-Based Filtering 🌈

some transport protocols use existing protocols (e.g., TCP or UDP) as a substrate 🧁 the match criteria for those might rely on the 'protocol' under 'l3', TCP/UDP match criteria, part of the TCP/UDP payload, or a combo of all of that. [RFC8519] doesn't support matching based on the payload, though 💀

and likewise, the ACL model defined in [RFC8519] doesn't support filtering of encapsulated traffic ✨

A.8. Reuse the Content of ACLs Across Several Devices

okay so having a global view of ACLs is literally SO valuable for service providers 🌐✨ You can define an ACL at the network level, and then that same ACL can be used in (or referenced to) several devices, including termination points, inside that same network. main character planning 💅

this network/device split brings in a few new requirements, like:

  • An ACL name can be used at both network and device levels. 🎀
  • An ACL content updated at the network level should imply a transaction that updates the relevant content in all the nodes using this ACL. 🔄
  • ACLs defined at the device level have a local meaning for the specific node. 📍
  • A device can be associated with a router, a Virtual Routing and Forwarding (VRF), a logical system, or a virtual node. ACLs can be applied in physical and logical infrastructure. 🦋

A.9. Match MPLS Headers

ngl this one is short but important 🧚 ACLs can be used to create rules that match MPLS fields on a packet. [RFC8519] does not support such function. 🙈

Appendix B. Examples

this section has a few examples showing how to use the enhanced ACL module ("ietf-acl-enh") 💖 let's gooo

B.1. TCP Flags Handling

Figure 4 shows an example of the message body of a request to install a filter to discard incoming TCP messages having all flags unset. it's giving "no null attacks allowed" 🚫💀

{
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "tcp-flags-example",
        "aces": {
          "ace": [
            {
              "name": "null-attack",
              "matches": {
                "tcp": {
                  "ietf-acl-enh:flags-bitmask": {
                    "operator": "not any",
                    "bitmask": 4095
                  }
                }
              },
              "actions": {
                "forwarding": "drop"
              }
            }
          ]
        }
      }
    ]
  }
}
       Figure 4: Example of an ACL to Deny TCP Null Attack Messages
                              (Request Body)

B.2. Fragments Handling

Figure 5 shows the content of a POST request to allow the traffic destined to 198.51.100.0/24 and UDP port number 53, but to drop all fragmented packets 🧦 The following ACEs are defined (in this order):

  • "drop-all-fragments" ACE: discards all fragments. 🗑️
  • "allow-dns-packets" ACE: accepts DNS packets destined to 198.51.100.0/24. ✅
{
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "dns-fragments",
        "type": "ipv4-acl-type",
        "aces": {
          "ace": [
            {
              "name": "drop-all-fragments",
              "matches": {
                "ipv4": {
                  "ietf-acl-enh:ipv4-fragment": {
                    "operator": "match",
                    "type": "isf"
                  }
                }
              },
              "actions": {
                "forwarding": "drop"
              }
            },
            {
              "name": "allow-dns-packets",
              "matches": {
                "ipv4": {
                  "destination-ipv4-network": "198.51.100.0/24"
                },
                "udp": {
                  "destination-port": {
                    "operator": "eq",
                    "port": 53
                  }
                }
              },
              "actions": {
                "forwarding": "accept"
              }
            }
          ]
        }
      }
    ]
  }
}
      Figure 5: Example Illustrating Candidate Filtering of IPv4
                  Fragmented Packets (Message Body)

Figure 6 shows an example of the body of a POST request to allow the traffic destined to 2001:db8::/32 and UDP port number 53, but to drop all fragmented packets 🌸 The following ACEs are defined (in this order):

  • "drop-all-fragments" ACE: discards all fragments (including atomic fragments). That is, IPv6 packets that include a Fragment header (44) are dropped. 💅
  • "allow-dns-packets" ACE: accepts DNS packets destined to 2001:db8::/32. 🫶
{
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "dns-fragments",
        "type": "ipv6-acl-type",
        "aces": {
          "ace": [
            {
              "name": "drop-all-fragments",
              "matches": {
                "ipv6": {
                  "ietf-acl-enh:ipv6-fragment": {
                    "operator": "match",
                    "type": "isf"
                  }
                }
              },
              "actions": {
                "forwarding": "drop"
              }
            },
            {
              "name": "allow-dns-packets",
              "matches": {
                "ipv6": {
                  "destination-ipv6-network": "2001:db8::/32"
                },
                "udp": {
                  "destination-port": {
                    "operator": "eq",
                    "port": 53
                  }
                }
              },
              "actions": {
                "forwarding": "accept"
              }
            }
          ]
        }
      }
    ]
  }
}
    Figure 6: An Example Illustrating Filtering of IPv6 Fragmented
                        Packets (Message Body)

B.3. Pattern-Based Filtering

pattern-based filtering is useful for spotting specific patterns, signatures, or encapsulated packets 🔍 Figure 7 shows an example of the message body of a request to install a filter to discard IP-in-IP encapsulated messages with an inner destination IP address equal to "2001:db8::1". By using the offset at the end of Layer 3, the rule targets a specific portion of the payload that starts 20 bytes after the beginning of the data (that is, skipping the first 20 bytes of the inner IPv6 header). 🧠

for the reader's convenience, the textual representation of the pattern is used in the example instead of the binary form 📖

{
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "pattern-example",
        "aces": {
          "ace": [
            {
              "name": "pattern-1",
              "matches": {
                "ipv6": {
                  "protocol": 41
                },
                "ietf-acl-enh:pattern": {
                  "offset": "ietf-acl-enh:layer4",
                  "length": 20,
                  "operator": "match",
                  "pattern": "2001:db8::1"
                }
              },
              "actions": {
                "forwarding": "drop"
              }
            }
          ]
        }
      }
    ]
  }
}
   Figure 7: Example of an ACL to Deny Encapsulated Messages with a
          Specific Inner Destination Address (Request Body)

B.4. VLAN Filtering

Figure 8 shows an ACL example illustrating how to apply a VLAN range filter 🎀

{
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "VLAN_FILTER",
        "aces": {
          "ace": [
            {
              "name": "1",
              "matches": {
                "ietf-acl-enh:vlan-filter": {
                  "lower-vlan": 10,
                  "upper-vlan": 20
                }
              },
              "actions": {
                "forwarding": "ietf-access-control-list:accept"
              }
            }
          ]
        }
      }
    ]
  }
}
           Figure 8: Example of VLAN Filter (Message Body)

B.5. I-SID Filtering

Figure 9 shows an ACL example illustrating I-SID range filtering 🦄

{
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "test",
        "aces": {
          "ace": [
            {
              "name": "1",
              "matches": {
                "ietf-acl-enh:isid-filter": {
                  "lower-isid": 100,
                  "upper-isid": 200
                }
              },
              "actions": {
                "forwarding": "ietf-access-control-list:accept"
              }
            }
          ]
        }
      }
    ]
  }
}
           Figure 9: Example I-SID Filter (Message Body)

B.6. Rate-Limit

Figure 10 shows an ACL example to rate-limit incoming SYNs during a SYN flood attack 🚦⚡

{
  "ietf-access-control-list:acls": {
    "acl": [
      {
        "name": "tcp-flags-example-with-rate-limit",
        "aces": {
          "ace": [
            {
              "name": "rate-limit-syn",
              "matches": {
                "tcp": {
                  "ietf-acl-enh:flags-bitmask": {
                    "operator": "match",
                    "bitmask": 2
                  }
                }
              },
              "actions": {
                "forwarding": "accept",
                "ietf-acl-enh:rate-limit": "20.00"
              }
            }
          ]
        }
      }
    ]
  }
}
 Figure 10: An Example of Rate-Limiting Incoming TCP SYNs (Message
                               Body)

Acknowledgments ✨

huge thanks to Jon Shallow and Miguel Cros for their review and comments on this document 🙌

thanks to Qiufang Ma, Victor Lopez, Joe Clarke, and Mahesh Jethanandani for their comments and suggestions 💜

thanks to Lou Berger for shepherding this document 🧚

thanks to David Black for the tsvart review, Tim Wicinski for the intdir review, Per Andersson for the yangdoctors review, Russ Housley for the genart review, and Linda Dunbar and Sean Turner for the secdir reviews 🫶

thanks to Erik Kline, Mike Bishop, Éric Vyncke, Roman Danyliw, and Deb Cooley for the IESG review 👑

the IANA-maintained modules were generated using an XSLT stylesheet from the 'iana-yang' project [YANG-XSLT] 🛠️

this work is partially supported by the European Commission under Horizon 2020 Secured autonomic traffic management for a Tera of SDN flows (Teraflow) project (grant agreement number 101015857) 🌈

Authors' Addresses

Oscar Gonzalez de Dios Telefonica Email: oscar.gonzalezdedios@telefonica.com

Samier Barguil Nokia Email: samier.barguil_giraldo@nokia.com

Mohamed Boucadair Orange Email: mohamed.boucadair@orange.com

Qin Wu Huawei Email: bill.wu@huawei.com

📦 where this page comes from