idnits 2.17.1 draft-ietf-netmod-acl-model-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 5 characters in excess of 72. == There are 7 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 782: '...s-list. A device MAY restrict the leng...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 230 has weird spacing: '...rw name str...' == Line 265 has weird spacing: '...er-port ine...' == Line 267 has weird spacing: '...er-port ine...' == Line 276 has weird spacing: '...er-port ine...' == Line 278 has weird spacing: '...er-port ine...' == (7 more instances...) -- The document date (January 16, 2018) is 2264 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-04 -- Obsolete informational reference (is this intentional?): RFC 5101 (Obsoleted by RFC 7011) Summary: 3 errors (**), 0 flaws (~~), 9 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD WG M. Jethanandani 3 Internet-Draft 4 Intended status: Standards Track L. Huang 5 Expires: July 20, 2018 General Electric 6 S. Agarwal 7 Cisco Systems, Inc. 8 D. Blair 9 Cisco Systems, INc 10 January 16, 2018 12 Network Access Control List (ACL) YANG Data Model 13 draft-ietf-netmod-acl-model-15 15 Abstract 17 This document describes a data model of Access Control List (ACL) 18 basic building blocks. 20 Editorial Note (To be removed by RFC Editor) 22 This draft contains many placeholder values that need to be replaced 23 with finalized values at the time of publication. This note 24 summarizes all of the substitutions that are needed. Please note 25 that no other RFC Editor instructions are specified anywhere else in 26 this document. 28 Artwork in this document contains shorthand references to drafts in 29 progress. Please apply the following replacements 31 o "XXXX" --> the assigned RFC value for this draft both in this 32 draft and in the YANG models under the revision statement. 34 o Revision date in model needs to get updated with the date the 35 draft gets approved. The date also needs to get reflected on the 36 line with . 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at https://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on July 20, 2018. 55 Copyright Notice 57 Copyright (c) 2018 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (https://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 73 1.1. Definitions and Acronyms . . . . . . . . . . . . . . . . 3 74 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 4 75 3. Understanding ACL's Filters and Actions . . . . . . . . . . . 4 76 3.1. ACL Modules . . . . . . . . . . . . . . . . . . . . . . . 5 77 4. ACL YANG Models . . . . . . . . . . . . . . . . . . . . . . . 9 78 4.1. IETF Access Control List module . . . . . . . . . . . . . 9 79 4.2. IETF Packet Fields module . . . . . . . . . . . . . . . . 22 80 4.3. An ACL Example . . . . . . . . . . . . . . . . . . . . . 33 81 4.4. Port Range Usage Example . . . . . . . . . . . . . . . . 34 82 5. Security Considerations . . . . . . . . . . . . . . . . . . . 36 83 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 84 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 85 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 37 86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 87 9.1. Normative References . . . . . . . . . . . . . . . . . . 37 88 9.2. Informative References . . . . . . . . . . . . . . . . . 38 89 Appendix A. Extending ACL model examples . . . . . . . . . . . . 38 90 A.1. A company proprietary module example . . . . . . . . . . 38 91 A.2. Linux nftables . . . . . . . . . . . . . . . . . . . . . 42 92 A.3. Ethertypes . . . . . . . . . . . . . . . . . . . . . . . 42 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 95 1. Introduction 97 Access Control List (ACL) is one of the basic elements used to 98 configure device forwarding behavior. It is used in many networking 99 technologies such as Policy Based Routing, Firewalls etc. 101 An ACL is an ordered-by-user set of rules that is used to filter 102 traffic on a networking device. Each rule is represented by an 103 Access Control Entry (ACE). 105 Each ACE has a group of match criteria and a group of action 106 criteria. 108 The match criteria consist of a tuple of packet header match criteria 109 and can have metadata match criteria as well. 111 o Packet header matches apply to fields visible in the packet such 112 as address or class of service or port numbers. 114 o In case vendor supports it, metadata matches apply to fields 115 associated with the packet but not in the packet header such as 116 input interface or overall packet length 118 The actions specify what to do with the packet when the matching 119 criteria is met. These actions are any operations that would apply 120 to the packet, such as counting, policing, or simply forwarding.The 121 list of potential actions is endless depending on the capabilities of 122 the networked devices. 124 Access Control List is also widely knowns as ACL (pronounce as [ak-uh 125 l]) or Access List. In this document, Access Control List, ACL and 126 Access List are used interchangeably. 128 The matching of filters and actions in an ACE/ACL are triggered only 129 after application/attachment of the ACL to an interface, VRF, vty/tty 130 session, QoS policy, routing protocols amongst various other config 131 attachment points. Once attached, it is used for filtering traffic 132 using the match criteria in the ACE's and taking appropriate 133 action(s) that have been configured against that ACE. In order to 134 apply an ACL to any attachment point other than an interface, vendors 135 would have to augment the ACL YANG model. 137 1.1. Definitions and Acronyms 139 ACE: Access Control Entry 141 ACL: Access Control List 142 DSCP: Differentiated Services Code Point 144 ICMP: Internet Control Message Protocol 146 IP: Internet Protocol 148 IPv4: Internet Protocol version 4 150 IPv6: Internet Protocol version 6 152 MAC: Media Access Control 154 TCP: Transmission Control Protocol 156 2. Problem Statement 158 This document defines a YANG [RFC6020] data model for the 159 configuration of ACLs. It is very important that model can be used 160 easily by applications/attachments. 162 ACL implementations in every device may vary greatly in terms of the 163 filter constructs and actions that they support. Therefore this 164 draft proposes a model that can be augmented by standard extensions 165 and vendor proprietary models. 167 3. Understanding ACL's Filters and Actions 169 Although different vendors have different ACL data models, there is a 170 common understanding of what Access Control List (ACL) is. A network 171 system usually have a list of ACLs, and each ACL contains an ordered 172 list of rules, also known as Access Control Entries (ACE). Each ACE 173 has a group of match criteria and a group of action criteria. The 174 match criteria consist of packet header matching. It as also 175 possible for ACE to match on metadata, if supported by the vendor. 176 Packet header matching applies to fields visible in the packet such 177 as address or class of service or port numbers. Metadata matching 178 applies to fields associated with the packet, but not in the packet 179 header such as input interface, packet length, or source or 180 destination prefix length. The actions can be any sort of operation 181 from logging to rate limiting or dropping to simply forwarding. 182 Actions on the first matching ACE are applied with no processing of 183 subsequent ACEs. 185 The model also includes a container to hold overall operational state 186 for each ACL and operational state for each ACE. One ACL can be 187 applied to multiple targets within the device, such as interfaces of 188 a networked device, applications or features running in the device, 189 etc. When applied to interfaces of a networked device, the ACL is 190 applied in a direction which indicates if it should be applied to 191 packet entering (input) or leaving the device (output). An example 192 in the appendix shows how to express it in YANG model. 194 This draft tries to address the commonalities between all vendors and 195 create a common model, which can be augmented with proprietary 196 models. The base model is simple and with this design we hope to 197 achieve enough flexibility for each vendor to extend the base model. 199 The use of feature statements in the model allows vendors to 200 advertise match rules they are capable and willing support. There 201 are two sets of feature statements a device needs to advertise. The 202 first set of feature statements specify the capability of the device. 203 These include features such as "Device can support ethernet headers" 204 or "Device can support of IPv4 headers". The second set of feature 205 statements specify the combinations of headers the device is willing 206 to support. These include features such as "Plain IPv6 ACL 207 supported" or "Ethernet, IPv4 and IPv6 ACL combinations supported". 209 3.1. ACL Modules 211 There are two YANG modules in the model. The first module, "ietf- 212 access-control-list", defines generic ACL aspects which are common to 213 all ACLs regardless of their type or vendor. In effect, the module 214 can be viewed as providing a generic ACL "superclass". It imports 215 the second module, "ietf-packet-fields". The match container in 216 "ietf-access-control-list" uses groupings in "ietf-packet-fields" to 217 specify match fields such as port numbers or protocol. The 218 combination of if-feature checks and must statements allow for the 219 selection of relevant match fields that a user can define rules for. 221 If there is a need to define new "matches" choice, such as IPFIX 222 [RFC5101], the container "matches" can be augmented. 224 For a reference to the annotations used in the diagram below, see 225 YANG Tree Diagrams [I-D.ietf-netmod-yang-tree-diagrams]. 227 module: ietf-access-control-list 228 +--rw access-lists 229 +--rw acl* [name] 230 | +--rw name string 231 | +--rw type? acl-type 232 | +--rw aces 233 | +--rw ace* [name] 234 | +--rw name string 235 | +--rw matches 236 | | +--rw (l2)? 237 | | | +--:(eth) 238 | | | +--rw eth {match-on-eth}? 239 | | | +--rw destination-mac-address? 240 | | | | yang:mac-address 241 | | | +--rw destination-mac-address-mask? 242 | | | | yang:mac-address 243 | | | +--rw source-mac-address? 244 | | | | yang:mac-address 245 | | | +--rw source-mac-address-mask? 246 | | | | yang:mac-address 247 | | | +--rw ethertype? 248 | | | eth:ethertype 249 | | +--rw (l3)? 250 | | | +--:(ipv4) 251 | | | | +--rw ipv4 {match-on-ipv4}? 252 | | | | +--rw dscp? 253 | | | | | inet:dscp 254 | | | | +--rw ecn? 255 | | | | | uint8 256 | | | | +--rw length? 257 | | | | | uint16 258 | | | | +--rw ttl? 259 | | | | | uint8 260 | | | | +--rw protocol? 261 | | | | | uint8 262 | | | | +--rw source-port-range-or-operator 263 | | | | | +--rw (port-range-or-operator)? 264 | | | | | +--:(range) 265 | | | | | | +--rw lower-port inet:port-numb 266 er 267 | | | | | | +--rw upper-port inet:port-numb 268 er 269 | | | | | +--:(operator) 270 | | | | | +--rw operator? operator 271 | | | | | +--rw port inet:port-numb 272 er 273 | | | | +--rw destination-port-range-or-operator 274 | | | | | +--rw (port-range-or-operator)? 275 | | | | | +--:(range) 276 | | | | | | +--rw lower-port inet:port-numb 277 er 278 | | | | | | +--rw upper-port inet:port-numb 279 er 280 | | | | | +--:(operator) 281 | | | | | +--rw operator? operator 282 | | | | | +--rw port inet:port-numb 283 er 284 | | | | +--rw ihl? 285 | | | | | uint8 286 | | | | +--rw flags? 287 | | | | | bits 288 | | | | +--rw offset? 289 | | | | | uint16 290 | | | | +--rw identification? 291 | | | | | uint16 292 | | | | +--rw destination-ipv4-network? 293 | | | | | inet:ipv4-prefix 294 | | | | +--rw source-ipv4-network? 295 | | | | inet:ipv4-prefix 296 | | | +--:(ipv6) 297 | | | +--rw ipv6 {match-on-ipv6}? 298 | | | +--rw dscp? 299 | | | | inet:dscp 300 | | | +--rw ecn? 301 | | | | uint8 302 | | | +--rw length? 303 | | | | uint16 304 | | | +--rw ttl? 305 | | | | uint8 306 | | | +--rw protocol? 307 | | | | uint8 308 | | | +--rw source-port-range-or-operator 309 | | | | +--rw (port-range-or-operator)? 310 | | | | +--:(range) 311 | | | | | +--rw lower-port inet:port-numb 312 er 313 | | | | | +--rw upper-port inet:port-numb 314 er 315 | | | | +--:(operator) 316 | | | | +--rw operator? operator 317 | | | | +--rw port inet:port-numb 318 er 319 | | | +--rw destination-port-range-or-operator 320 | | | | +--rw (port-range-or-operator)? 321 | | | | +--:(range) 322 | | | | | +--rw lower-port inet:port-numb 323 er 324 | | | | | +--rw upper-port inet:port-numb 325 er 326 | | | | +--:(operator) 327 | | | | +--rw operator? operator 328 | | | | +--rw port inet:port-numb 329 er 330 | | | +--rw destination-ipv6-network? 331 | | | | inet:ipv6-prefix 332 | | | +--rw source-ipv6-network? 333 | | | | inet:ipv6-prefix 334 | | | +--rw flow-label? 335 | | | inet:ipv6-flow-label 336 | | +--rw (l4)? 337 | | | +--:(tcp) 338 | | | | +--rw tcp {match-on-tcp}? 339 | | | | +--rw sequence-number? uint32 340 | | | | +--rw acknowledgement-number? uint32 341 | | | | +--rw data-offset? uint8 342 | | | | +--rw reserved? uint8 343 | | | | +--rw flags? bits 344 | | | | +--rw window-size? uint16 345 | | | | +--rw urgent-pointer? uint16 346 | | | | +--rw options? uint32 347 | | | +--:(udp) 348 | | | | +--rw udp {match-on-udp}? 349 | | | | +--rw length? uint16 350 | | | +--:(icmp) 351 | | | +--rw icmp {match-on-icmp}? 352 | | | +--rw type? uint8 353 | | | +--rw code? uint8 354 | | | +--rw rest-of-header? uint32 355 | | +--rw egress-interface? if:interface-ref 356 | | +--rw ingress-interface? if:interface-ref 357 | +--rw actions 358 | | +--rw forwarding identityref 359 | | +--rw logging? identityref 360 | +--ro statistics {acl-aggregate-stats}? 361 | +--ro matched-packets? yang:counter64 362 | +--ro matched-octets? yang:counter64 363 +--rw attachment-points 364 +--rw interface* [interface-id] {interface-attachment}? 365 +--rw interface-id if:interface-ref 366 +--rw ingress 367 | +--rw acl-sets 368 | +--rw acl-set* [name] 369 | +--rw name 370 | | -> ../../../../../../acl/name 371 | +--ro ace-statistics* [name] {interface-stats}? 372 | +--ro name leafref 373 | +--ro matched-packets? yang:counter64 374 | +--ro matched-octets? yang:counter64 375 +--rw egress 376 +--rw acl-sets 377 +--rw acl-set* [name] 378 +--rw name 379 | -> ../../../../../../acl/name 380 +--ro ace-statistics* [name] {interface-stats}? 381 +--ro name leafref 382 +--ro matched-packets? yang:counter64 383 +--ro matched-octets? yang:counter64 385 4. ACL YANG Models 387 4.1. IETF Access Control List module 389 "ietf-access-control-list" is the standard top level module for 390 access lists. The "access-lists" container stores a list of "acl". 391 Each "acl" has information identifying the access list by a name 392 ("name") and a list ("aces") of rules associated with the "name". 393 Each of the entries in the list ("aces"), indexed by the string 394 "name", has containers defining "matches" and "actions". 396 The model defines several ACL types and actions in the form of 397 identities and features. Features are used by implementors to select 398 the ACL types the system can support and identities are used to 399 validate the types that have been selected. These types are 400 implicitly inherited by the "ace", thus safeguarding against 401 misconfiguration of "ace" types in an "acl". 403 The "matches" define criteria used to identify patterns in "ietf- 404 packet-fields". The choice statements within the match container 405 allow for selection of one header within each of "l2", "l3", or "l4" 406 headers. The "actions" define behavior to undertake once a "match" 407 has been identified. In addition to permit and deny for actions, a 408 logging option allows for a match to be logged that can be used to 409 determine which rule was matched upon. The model also defines the 410 ability for ACL's to be attached to a particular interface. 412 Statistics in the ACL can be collected for an "ace" or for an 413 "interface". The feature statements defined for statistics can be 414 used to determine whether statistics are being collected per "ace", 415 or per "interface". 417 file "ietf-access-control-list@2018-01-16.yang" 419 module ietf-access-control-list { 420 yang-version 1.1; 421 namespace "urn:ietf:params:xml:ns:yang:ietf-access-control-list"; 422 prefix acl; 424 import ietf-yang-types { 425 prefix yang; 426 } 428 import ietf-packet-fields { 429 prefix packet-fields; 431 } 433 import ietf-interfaces { 434 prefix if; 435 } 437 organization 438 "IETF NETMOD (NETCONF Data Modeling Language) 439 Working Group"; 441 contact 442 "WG Web: http://tools.ietf.org/wg/netmod/ 443 WG List: netmod@ietf.org 445 Editor: Mahesh Jethanandani 446 mjethanandani@gmail.com 447 Editor: Lisa Huang 448 lyihuang16@gmail.com 449 Editor: Sonal Agarwal 450 sagarwal12@gmail.com 451 Editor: Dana Blair 452 dblair@cisco.com"; 454 description 455 "This YANG module defines a component that describe the 456 configuration of Access Control Lists (ACLs). 458 Copyright (c) 2018 IETF Trust and the persons identified as 459 the document authors. All rights reserved. 460 Redistribution and use in source and binary forms, with or 461 without modification, is permitted pursuant to, and subject 462 to the license terms contained in, the Simplified BSD 463 License set forth in Section 4.c of the IETF Trust's Legal 464 Provisions Relating to IETF Documents 465 (http://trustee.ietf.org/license-info). 467 This version of this YANG module is part of RFC XXXX; see 468 the RFC itself for full legal notices."; 470 revision 2018-01-16 { 471 description 472 "Initial version."; 473 reference 474 "RFC XXX: Network Access Control List (ACL) YANG Data Model."; 475 } 477 /* 478 * Identities 479 */ 481 /* 482 * Forwarding actions for a packet 483 */ 484 identity forwarding-action { 485 description 486 "Base identity for actions in the forwarding category"; 487 } 489 identity accept { 490 base forwarding-action; 491 description 492 "Accept the packet"; 493 } 495 identity drop { 496 base forwarding-action; 497 description 498 "Drop packet without sending any ICMP error message"; 499 } 501 identity reject { 502 base forwarding-action; 503 description 504 "Drop the packet and send an ICMP error message to the source"; 505 } 507 /* 508 * Logging actions for a packet 509 */ 510 identity log-action { 511 description 512 "Base identity for defining the destination for logging actions"; 513 } 515 identity log-syslog { 516 base log-action; 517 description 518 "System log (syslog) the information for the packet"; 519 } 521 identity log-none { 522 base log-action; 523 description 524 "No logging for the packet"; 525 } 526 /* 527 * ACL type identities 528 */ 529 identity acl-base { 530 description 531 "Base Access Control List type for all Access Control List type 532 identifiers."; 533 } 535 identity ipv4-acl-type { 536 base acl:acl-base; 537 if-feature "ipv4"; 538 description 539 "ACL that primarily matches on fields from the IPv4 header 540 (e.g. IPv4 destination address) and layer 4 headers (e.g. TCP 541 destination port). An acl of type ipv4 does not contain 542 matches on fields in the ethernet header or the IPv6 header."; 543 } 545 identity ipv6-acl-type { 546 base acl:acl-base; 547 if-feature "ipv6"; 548 description 549 "ACL that primarily matches on fields from the IPv6 header 550 (e.g. IPv6 destination address) and layer 4 headers (e.g. TCP 551 destination port). An acl of type ipv6 does not contain 552 matches on fields in the ethernet header or the IPv4 header."; 553 } 555 identity eth-acl-type { 556 base acl:acl-base; 557 if-feature "eth"; 558 description 559 "ACL that primarily matches on fields in the ethernet header, 560 like 10/100/1000baseT or WiFi Access Control List. An acl of 561 type ethernet does not contain matches on fields in the IPv4 562 header, IPv6 header or layer 4 headers."; 563 } 565 identity mixed-eth-ipv4-acl-type { 566 base "acl:eth-acl-type"; 567 base "acl:ipv4-acl-type"; 568 if-feature "mixed-eth-ipv4"; 569 description 570 "ACL that contains a mix of entries that 571 primarily match on fields in ethernet headers, 572 entries that primarily match on IPv4 headers. 573 Matching on layer 4 header fields may also exist in the 574 list."; 575 } 577 identity mixed-eth-ipv6-acl-type { 578 base "acl:eth-acl-type"; 579 base "acl:ipv6-acl-type"; 580 if-feature "mixed-eth-ipv6"; 581 description 582 "ACL that contains a mix of entries that 583 primarily match on fields in ethernet headers, entries 584 that primarily match on fields in IPv6 headers. Matching on 585 layer 4 header fields may also exist in the list."; 586 } 588 identity mixed-eth-ipv4-ipv6-acl-type { 589 base "acl:eth-acl-type"; 590 base "acl:ipv4-acl-type"; 591 base "acl:ipv6-acl-type"; 592 if-feature "mixed-eth-ipv4-ipv6"; 593 description 594 "ACL that contains a mix of entries that 595 primarily match on fields in ethernet headers, entries 596 that primarily match on fields in IPv4 headers, and entries 597 that primarily match on fields in IPv6 headers. Matching on 598 layer 4 header fields may also exist in the list."; 599 } 601 /* 602 * Features 603 */ 605 /* 606 * Features supported by device 607 */ 608 feature match-on-eth { 609 description 610 "Device can support matching on ethernet headers."; 611 } 613 feature match-on-ipv4 { 614 description 615 "Device can support matching on IPv4 headers."; 616 } 618 feature match-on-ipv6 { 619 description 620 "Device can support matching on IPv6 headers."; 621 } 622 feature match-on-tcp { 623 description 624 "Device can support TCP headers."; 625 } 627 feature match-on-udp { 628 description 629 "Device can support UDP header."; 630 } 632 feature match-on-icmp { 633 description 634 "Device can support ICMP header."; 635 } 637 /* 638 * Header classifications combinations supported by 639 * device 640 */ 641 feature eth { 642 if-feature "match-on-eth"; 643 description 644 "Plain Ethernet ACL supported"; 645 } 647 feature ipv4 { 648 if-feature "match-on-ipv4"; 649 description 650 "Plain IPv4 ACL supported"; 651 } 653 feature ipv6 { 654 if-feature "match-on-ipv6"; 655 description 656 "Plain IPv6 ACL supported"; 657 } 659 feature mixed-eth-ipv4 { 660 if-feature "match-on-eth and match-on-ipv4"; 661 description 662 "Ethernet and IPv4 ACL combinations supported"; 663 } 665 feature mixed-eth-ipv6 { 666 if-feature "match-on-eth and match-on-ipv6"; 667 description 668 "Ethernet and IPv6 ACL combinations supported"; 669 } 670 feature mixed-eth-ipv4-ipv6 { 671 if-feature "match-on-eth and match-on-ipv4 672 and match-on-ipv6"; 673 description 674 "Ethernet, IPv4 and IPv6 ACL combinations supported."; 675 } 677 /* 678 * Stats Features 679 */ 680 feature interface-stats { 681 description 682 "ACL counters are available and reported only per interface"; 683 } 685 feature acl-aggregate-stats { 686 description 687 "ACL counters are aggregated over all interfaces, and reported 688 only per ACL entry"; 689 } 691 /* 692 * Attachment point features 693 */ 694 feature interface-attachment { 695 description 696 "ACLs are set on interfaces."; 697 } 699 /* 700 * Typedefs 701 */ 702 typedef acl-type { 703 type identityref { 704 base acl-base; 705 } 706 description 707 "This type is used to refer to an Access Control List 708 (ACL) type"; 709 } 711 /* 712 * Groupings 713 */ 714 grouping acl-counters { 715 description 716 "Common grouping for ACL counters"; 718 leaf matched-packets { 719 type yang:counter64; 720 config false; 721 description 722 "Count of the number of packets matching the current ACL 723 entry. 725 An implementation should provide this counter on a 726 per-interface per-ACL-entry if possible. 728 If an implementation only supports ACL counters per entry 729 (i.e., not broken out per interface), then the value 730 should be equal to the aggregate count across all interfaces. 732 An implementation that provides counters per entry per 733 interface is not required to also provide an aggregate count, 734 e.g., per entry -- the user is expected to be able implement 735 the required aggregation if such a count is needed."; 736 } 738 leaf matched-octets { 739 type yang:counter64; 740 config false; 741 description 742 "Count of the number of octets (bytes) matching the current 743 ACL entry. 745 An implementation should provide this counter on a 746 per-interface per-ACL-entry if possible. 748 If an implementation only supports ACL counters per entry 749 (i.e., not broken out per interface), then the value 750 should be equal to the aggregate count across all interfaces. 752 An implementation that provides counters per entry per 753 interface is not required to also provide an aggregate count, 754 e.g., per entry -- the user is expected to be able implement 755 the required aggregation if such a count is needed."; 756 } 757 } 759 /* 760 * Configuration data nodes 761 */ 762 container access-lists { 763 description 764 "This is a top level container for Access Control Lists. 765 It can have one or more Access Control Lists."; 767 list acl { 768 key "name"; 769 description 770 "An Access Control List(ACL) is an ordered list of 771 Access List Entries (ACE). Each Access Control Entry has a 772 list of match criteria and a list of actions. 773 Since there are several kinds of Access Control Lists 774 implemented with different attributes for 775 different vendors, this model accommodates customizing 776 Access Control Lists for each kind and for each vendor."; 777 leaf name { 778 type string { 779 length "1..64"; 780 } 781 description 782 "The name of access-list. A device MAY restrict the length 783 and value of this name, possibly space and special 784 characters are not allowed."; 785 } 786 leaf type { 787 type acl-type; 788 description 789 "Type of access control list. Indicates the primary intended 790 type of match criteria (e.g. ethernet, IPv4, IPv6, mixed, 791 etc) used in the list instance."; 792 } 793 container aces { 794 description 795 "The access-list-entries container contains 796 a list of access-list-entries(ACE)."; 797 list ace { 798 key "name"; 799 ordered-by user; 800 description 801 "List of access list entries(ACE)"; 802 leaf name { 803 type string { 804 length "1..64"; 805 } 806 description 807 "A unique name identifying this Access List 808 Entry(ACE)."; 809 } 811 container matches { 812 description 813 "The rules in this set determine what fields will be 814 matched upon before any action is taken on them. 816 The rules are selected based on the feature set 817 defined by the server and the acl-type defined. 818 If no matches are defined in a particular container, 819 then any packet will match that container. If no 820 matches are specified at all in an ACE, then any 821 packet will match the ACE."; 823 choice l2 { 824 container eth { 825 when "derived-from(../../../../type, " + 826 "'acl:eth-acl-type')"; 827 if-feature match-on-eth; 828 uses packet-fields:acl-eth-header-fields; 829 description 830 "Rule set that matches ethernet headers."; 831 } 832 description 833 "Match layer 2 headers, for example ethernet 834 header fields."; 835 } 837 choice l3 { 838 container ipv4 { 839 when "derived-from(../../../../type, " + 840 "'acl:ipv4-acl-type')"; 841 if-feature match-on-ipv4; 842 uses packet-fields:acl-ip-header-fields; 843 uses packet-fields:acl-ipv4-header-fields; 844 description 845 "Rule set that matches IPv4 headers."; 846 } 848 container ipv6 { 849 when "derived-from(../../../../type, " + 850 "'acl:ipv6-acl-type')"; 851 if-feature match-on-ipv6; 852 uses packet-fields:acl-ip-header-fields; 853 uses packet-fields:acl-ipv6-header-fields; 854 description 855 "Rule set that matches IPv6 headers."; 856 } 857 description 858 "Choice of either ipv4 or ipv6 headers"; 859 } 861 choice l4 { 862 container tcp { 863 if-feature match-on-tcp; 864 uses packet-fields:acl-tcp-header-fields; 865 description 866 "Rule set that matches TCP headers."; 867 } 869 container udp { 870 if-feature match-on-udp; 871 uses packet-fields:acl-udp-header-fields; 872 description 873 "Rule set that matches UDP headers."; 874 } 876 container icmp { 877 if-feature match-on-icmp; 878 uses packet-fields:acl-icmp-header-fields; 879 description 880 "Rule set that matches ICMP headers."; 881 } 882 description 883 "Choice of TCP, UDP or ICMP headers."; 884 } 886 leaf egress-interface { 887 type if:interface-ref; 888 description 889 "Egress interface. This should not be used if this ACL 890 is attached as an egress ACL (or the value should equal 891 the interface to which the ACL is attached)."; 892 } 894 leaf ingress-interface { 895 type if:interface-ref; 896 description 897 "Ingress interface. This should not be used if this ACL 898 is attached as an ingress ACL (or the value should 899 equal the interface to which the ACL is attached)"; 900 } 901 } 903 container actions { 904 description 905 "Definitions of action for this ace entry"; 906 leaf forwarding { 907 type identityref { 908 base forwarding-action; 909 } 910 mandatory true; 911 description 912 "Specifies the forwarding action per ace entry"; 913 } 915 leaf logging { 916 type identityref { 917 base log-action; 918 } 919 default log-none; 920 description 921 "Specifies the log action and destination for 922 matched packets. Default value is not to log the 923 packet."; 924 } 925 } 926 container statistics { 927 if-feature "acl-aggregate-stats"; 928 config false; 929 description 930 "Statistics gathered across all attachment points for the 931 given ACL."; 932 uses acl-counters; 933 } 934 } 935 } 936 } 937 container attachment-points { 938 description 939 "Enclosing container for the list of 940 attachment-points on which ACLs are set"; 942 /* 943 * Groupings 944 */ 945 grouping interface-acl { 946 description 947 "Grouping for per-interface ingress ACL data"; 949 container acl-sets { 950 description 951 "Enclosing container the list of ingress ACLs on the 952 interface"; 954 list acl-set { 955 key "name"; 956 ordered-by user; 957 description 958 "List of ingress ACLs on the interface"; 960 leaf name { 961 type leafref { 962 path "../../../../../../acl/name"; 963 } 964 description 965 "Reference to the ACL name applied on ingress"; 966 } 968 list ace-statistics { 969 if-feature "interface-stats"; 970 key "name"; 971 config false; 972 description 973 "List of access list entries(ACE)"; 974 leaf name { 975 type leafref { 976 path "../../../../../../../acl/aces/ace/name"; 977 } 978 description 979 "The ace name"; 980 } 981 uses acl-counters; 982 } 983 } 984 } 985 } 987 list interface { 988 if-feature interface-attachment; 989 key "interface-id"; 990 description 991 "List of interfaces on which ACLs are set"; 993 leaf interface-id { 994 type if:interface-ref; 995 description 996 "Reference to the interface id list key"; 997 } 999 container ingress { 1000 uses interface-acl; 1001 description 1002 "The ACL's applied to ingress interface"; 1003 } 1004 container egress { 1005 uses interface-acl; 1006 description 1007 "The ACL's applied to egress interface"; 1009 } 1010 } 1011 } 1012 } 1013 } 1015 1017 4.2. IETF Packet Fields module 1019 The packet fields module defines the necessary groups for matching on 1020 fields in the packet including ethernet, ipv4, ipv6, and transport 1021 layer fields. The "type" node determines which of these fields get 1022 included for any given ACL with the exception of TCP, UDP and ICMP 1023 header fields. Those fields can be used in conjunction with any of 1024 the above layer 2 or layer 3 fields. 1026 Since the number of match criteria is very large, the base draft does 1027 not include these directly but references them by "uses" to keep the 1028 base module simple. In case more match conditions are needed, those 1029 can be added by augmenting choices within container "matches" in 1030 ietf-access-control-list.yang model. 1032 file "ietf-packet-fields@2018-01-16.yang" 1034 module ietf-packet-fields { 1035 namespace "urn:ietf:params:xml:ns:yang:ietf-packet-fields"; 1036 prefix packet-fields; 1038 import ietf-inet-types { 1039 prefix inet; 1040 } 1042 import ietf-yang-types { 1043 prefix yang; 1044 } 1046 import ietf-ethertypes { 1047 prefix eth; 1048 } 1050 organization 1051 "IETF NETMOD (NETCONF Data Modeling Language) Working 1052 Group"; 1054 contact 1055 "WG Web: http://tools.ietf.org/wg/netmod/ 1056 WG List: netmod@ietf.org 1057 Editor: Mahesh Jethanandani 1058 mjethanandani@gmail.com 1059 Editor: Lisa Huang 1060 lyihuang16@gmail.com 1061 Editor: Sonal Agarwal 1062 sagarwal12@gmail.com 1063 Editor: Dana Blair 1064 dblair@cisco.com"; 1066 description 1067 "This YANG module defines groupings that are used by 1068 ietf-access-control-list YANG module. Their usage is not 1069 limited to ietf-access-control-list and can be 1070 used anywhere as applicable. 1072 Copyright (c) 2018 IETF Trust and the persons identified as 1073 the document authors. All rights reserved. 1074 Redistribution and use in source and binary forms, with or 1075 without modification, is permitted pursuant to, and subject 1076 to the license terms contained in, the Simplified BSD 1077 License set forth in Section 4.c of the IETF Trust's Legal 1078 Provisions Relating to IETF Documents 1079 (http://trustee.ietf.org/license-info). 1081 This version of this YANG module is part of RFC XXXX; see 1082 the RFC itself for full legal notices."; 1084 revision 2018-01-16 { 1085 description 1086 "Initial version."; 1087 reference 1088 "RFC XXX: Network Access Control List (ACL) YANG Data Model."; 1089 } 1091 /* 1092 * Typedefs 1093 */ 1094 typedef operator { 1095 type enumeration { 1096 enum lte { 1097 description 1098 "Less than or equal."; 1099 } 1100 enum gte { 1101 description 1102 "Greater than or equal."; 1103 } 1104 enum eq { 1105 description 1106 "Equal to."; 1107 } 1108 enum neq { 1109 description 1110 "Not equal to."; 1111 } 1112 } 1113 description 1114 "The source and destination port range definitions 1115 can be further qualified using an operator. An 1116 operator is needed only if lower-port is specified 1117 and upper-port is not specified. The operator 1118 therefore further qualifies lower-port only."; 1119 } 1121 /* 1122 * Groupings 1123 */ 1124 grouping port-range-or-operator { 1125 choice port-range-or-operator { 1126 case range { 1127 leaf lower-port { 1128 type inet:port-number; 1129 must ". <= ../upper-port" { 1130 error-message 1131 "The lower-port must be less than or equal to 1132 upper-port."; 1133 } 1134 mandatory true; 1135 description 1136 "Lower boundry for a port."; 1137 } 1138 leaf upper-port { 1139 type inet:port-number; 1140 mandatory true; 1141 description 1142 "Upper boundry for port."; 1143 } 1144 } 1145 case operator { 1146 leaf operator { 1147 type operator; 1148 default eq; 1149 description 1150 "Operator to be applied on the port below."; 1151 } 1152 leaf port { 1153 type inet:port-number; 1154 mandatory true; 1155 description 1156 "Port number along with operator on which to 1157 match."; 1158 } 1159 } 1160 description 1161 "Choice of specifying a port range or a single 1162 port along with an operator."; 1163 } 1164 description 1165 "Grouping for port definitions in the form of a 1166 choice statement."; 1167 } 1169 grouping acl-ip-header-fields { 1170 description 1171 "IP header fields common to ipv4 and ipv6"; 1172 reference 1173 "RFC 791."; 1175 leaf dscp { 1176 type inet:dscp; 1177 description 1178 "Differentiated Services Code Point."; 1179 reference 1180 "RFC 2474: Definition of Differentiated services field 1181 (DS field) in the IPv4 and IPv6 headers."; 1182 } 1184 leaf ecn { 1185 type uint8 { 1186 range 0..3; 1187 } 1188 description 1189 "Explicit Congestion Notification."; 1190 reference 1191 "RFC 3168."; 1192 } 1194 leaf length { 1195 type uint16; 1196 description 1197 "In IPv4 header field, this field is known as the Total Length. 1198 Total Length is the length of the datagram, measured in octets, 1199 including internet header and data. 1201 In IPv6 header field, this field is known as the Payload 1202 Length, the length of the IPv6 payload, i.e. the rest of 1203 the packet following the IPv6 header, in octets."; 1204 reference 1205 "RFC 719, RFC 2460"; 1206 } 1208 leaf ttl { 1209 type uint8; 1210 description 1211 "This field indicates the maximum time the datagram is allowed 1212 to remain in the internet system. If this field contains the 1213 value zero, then the datagram must be destroyed. 1215 In IPv6, this field is known as the Hop Limit."; 1216 reference "RFC 719, RFC 2460"; 1217 } 1219 leaf protocol { 1220 type uint8; 1221 description 1222 "Internet Protocol number. Refers to the protocol of the 1223 payload. In IPv6, this field is known as 'next-header."; 1224 reference "RFC 719, RFC 2460."; 1225 } 1226 container source-port-range-or-operator { 1227 uses port-range-or-operator; 1228 description 1229 "Source port definition."; 1230 } 1231 container destination-port-range-or-operator { 1232 uses port-range-or-operator; 1233 description 1234 "Destination port definition."; 1235 } 1236 } 1238 grouping acl-ipv4-header-fields { 1239 description 1240 "Fields in IPv4 header."; 1242 leaf ihl { 1243 type uint8 { 1244 range "5..60"; 1245 } 1246 description 1247 "An IPv4 header field, the Internet Header Length (IHL) is 1248 the length of the internet header in 32 bit words, and 1249 thus points to the beginning of the data. Note that the 1250 minimum value for a correct header is 5."; 1251 } 1253 leaf flags { 1254 type bits { 1255 bit reserved { 1256 position 0; 1257 description 1258 "Reserved. Must be zero."; 1259 } 1260 bit fragment { 1261 position 1; 1262 description 1263 "Setting value to 0 indicates may fragment, while setting 1264 the value to 1 indicates do not fragment."; 1265 } 1266 bit more { 1267 position 2; 1268 description 1269 "Setting the value to 0 indicates this is the last fragment, 1270 and setting the value to 1 indicates more fragments are 1271 coming."; 1272 } 1273 } 1274 description 1275 "Bit definitions for the flags field in IPv4 header."; 1276 } 1278 leaf offset { 1279 type uint16 { 1280 range "20..65535"; 1281 } 1282 description 1283 "The fragment offset is measured in units of 8 octets (64 bits). 1284 The first fragment has offset zero. The length is 13 bits"; 1285 } 1287 leaf identification { 1288 type uint16; 1289 description 1290 "An identifying value assigned by the sender to aid in 1291 assembling the fragments of a datagram."; 1292 } 1294 leaf destination-ipv4-network { 1295 type inet:ipv4-prefix; 1296 description 1297 "Destination IPv4 address prefix."; 1298 } 1299 leaf source-ipv4-network { 1300 type inet:ipv4-prefix; 1301 description 1302 "Source IPv4 address prefix."; 1303 } 1304 } 1306 grouping acl-ipv6-header-fields { 1307 description 1308 "Fields in IPv6 header"; 1310 leaf destination-ipv6-network { 1311 type inet:ipv6-prefix; 1312 description 1313 "Destination IPv6 address prefix."; 1314 } 1316 leaf source-ipv6-network { 1317 type inet:ipv6-prefix; 1318 description 1319 "Source IPv6 address prefix."; 1320 } 1322 leaf flow-label { 1323 type inet:ipv6-flow-label; 1324 description 1325 "IPv6 Flow label."; 1326 } 1327 reference 1328 "RFC 4291: IP Version 6 Addressing Architecture 1329 RFC 4007: IPv6 Scoped Address Architecture 1330 RFC 5952: A Recommendation for IPv6 Address Text 1331 Representation"; 1332 } 1334 grouping acl-eth-header-fields { 1335 description 1336 "Fields in Ethernet header."; 1338 leaf destination-mac-address { 1339 type yang:mac-address; 1340 description 1341 "Destination IEEE 802 MAC address."; 1342 } 1343 leaf destination-mac-address-mask { 1344 type yang:mac-address; 1345 description 1346 "Destination IEEE 802 MAC address mask."; 1347 } 1348 leaf source-mac-address { 1349 type yang:mac-address; 1350 description 1351 "Source IEEE 802 MAC address."; 1352 } 1353 leaf source-mac-address-mask { 1354 type yang:mac-address; 1355 description 1356 "Source IEEE 802 MAC address mask."; 1357 } 1358 leaf ethertype { 1359 type eth:ethertype; 1360 description 1361 "The Ethernet Type (or Length) value represented 1362 in the canonical order defined by IEEE 802. 1363 The canonical representation uses lowercase 1364 characters."; 1365 reference 1366 "IEEE 802-2014 Clause 9.2"; 1367 } 1368 reference 1369 "IEEE 802: IEEE Standard for Local and Metropolitan 1370 Area Networks: Overview and Architecture."; 1371 } 1373 grouping acl-tcp-header-fields { 1374 description 1375 "Collection of TCP header fields that can be used to 1376 setup a match filter."; 1378 leaf sequence-number { 1379 type uint32; 1380 description 1381 "Sequence number that appears in the packet."; 1382 } 1384 leaf acknowledgement-number { 1385 type uint32; 1386 description 1387 "The acknowledgement number that appears in the 1388 packet."; 1389 } 1391 leaf data-offset { 1392 type uint8 { 1393 range "5..15"; 1394 } 1395 description 1396 "Specifies the size of the TCP header in 32-bit 1397 words. The minimum size header is 5 words and 1398 the maximum is 15 words thus giving the minimum 1399 size of 20 bytes and maximum of 60 bytes, 1400 allowing for up to 40 bytes of options in the 1401 header."; 1402 } 1404 leaf reserved { 1405 type uint8; 1406 description 1407 "Reserved for future use."; 1408 } 1410 leaf flags { 1411 type bits { 1412 bit ns { 1413 position 0; 1414 description 1415 "ECN-nonce concealment protection"; 1416 reference "RFC 3540)."; 1417 } 1418 bit cwr { 1419 position 1; 1420 description 1421 "Congestion Window Reduced (CWR) flag is set by 1422 the sending host to indicate that it received 1423 a TCP segment with the ECE flag set and had 1424 responded in congestion control mechanism."; 1425 reference "RFC 3168"; 1426 } 1427 bit ece { 1428 position 2; 1429 description 1430 "ECN-Echo has a dual role, depending on the value 1431 of the SYN flag. It indicates: 1432 If the SYN flag is set (1), that the TCP peer is ECN 1433 capable. If the SYN flag is clear (0), that a packet 1434 with Congestion Experienced flag set (ECN=11) in IP 1435 header was received during normal transmission 1436 (added to header by RFC 3168). This serves as an 1437 indication of network congestion (or impending 1438 congestion) to the TCP sender."; 1439 } 1440 bit urg { 1441 position 3; 1442 description 1443 "Indicates that the Urgent pointer field is significant."; 1444 } 1445 bit ack { 1446 position 4; 1447 description 1448 "Indicates that the Acknowledgment field is significant. 1449 All packets after the initial SYN packet sent by the 1450 client should have this flag set."; 1451 } 1452 bit psh { 1453 position 5; 1454 description 1455 "Push function. Asks to push the buffered data to the 1456 receiving application."; 1457 } 1458 bit rst { 1459 position 6; 1460 description 1461 "Reset the connection."; 1462 } 1463 bit syn { 1464 position 7; 1465 description 1466 "Synchronize sequence numbers. Only the first packet 1467 sent from each end should have this flag set. Some 1468 other flags and fields change meaning based on this 1469 flag, and some are only valid for when it is set, 1470 and others when it is clear."; 1471 } 1472 bit fin { 1473 position 8; 1474 description 1475 "Last package from sender."; 1476 } 1477 } 1478 description 1479 "Also known as Control Bits. Contains 9 1-bit flags."; 1480 } 1482 leaf window-size { 1483 type uint16; 1484 description 1485 "The size of the receive window, which specifies 1486 the number of window size units (by default, 1487 bytes) (beyond the segment identified by the 1488 sequence number in the acknowledgment field) 1489 that the sender of this segment is currently 1490 willing to receive."; 1491 } 1493 leaf urgent-pointer { 1494 type uint16; 1495 description 1496 "This field is an offset from the sequence number 1497 indicating the last urgent data byte."; 1498 } 1500 leaf options { 1501 type uint32; 1502 description 1503 "The length of this field is determined by the 1504 data offset field. Options have up to three 1505 fields: Option-Kind (1 byte), Option-Length 1506 (1 byte), Option-Data (variable). The Option-Kind 1507 field indicates the type of option, and is the 1508 only field that is not optional. Depending on 1509 what kind of option we are dealing with, 1510 the next two fields may be set: the Option-Length 1511 field indicates the total length of the option, 1512 and the Option-Data field contains the value of 1513 the option, if applicable."; 1514 } 1515 } 1517 grouping acl-udp-header-fields { 1518 description 1519 "Collection of UDP header fields that can be used 1520 to setup a match filter."; 1522 leaf length { 1523 type uint16; 1524 description 1525 "A field that specifies the length in bytes of 1526 the UDP header and UDP data. The minimum 1527 length is 8 bytes because that is the length of 1528 the header. The field size sets a theoretical 1529 limit of 65,535 bytes (8 byte header + 65,527 1530 bytes of data) for a UDP datagram. However the 1531 actual limit for the data length, which is 1532 imposed by the underlying IPv4 protocol, is 1533 65,507 bytes (65,535 minus 8 byte UDP header 1534 minus 20 byte IP header). 1536 In IPv6 jumbograms it is possible to have 1537 UDP packets of size greater than 65,535 bytes. 1538 RFC 2675 specifies that the length field is set 1539 to zero if the length of the UDP header plus 1540 UDP data is greater than 65,535."; 1541 } 1542 } 1544 grouping acl-icmp-header-fields { 1545 description 1546 "Collection of ICMP header fields that can be 1547 used to setup a match filter."; 1549 leaf type { 1550 type uint8; 1551 description 1552 "Also known as Control messages."; 1553 reference "RFC 792"; 1554 } 1556 leaf code { 1557 type uint8; 1558 description 1559 "ICMP subtype. Also known as Control messages."; 1560 } 1562 leaf rest-of-header { 1563 type uint32; 1564 description 1565 "Four-bytes field, contents vary based on the 1566 ICMP type and code."; 1567 } 1568 } 1569 } 1571 1573 4.3. An ACL Example 1575 Requirement: Deny tcp traffic from 10.10.10.1/24, destined to 1576 11.11.11.1/24. 1578 Here is the acl configuration xml for this Access Control List: 1580 1581 1582 1583 1584 sample-ipv4-acl 1585 ipv4-acl-type 1586 1587 1588 rule1 1589 1590 1591 1592 tcp 1593 1594 11.11.11.1/24 1595 1596 1597 10.10.10.1/24 1598 1599 1600 1601 1602 1603 drop 1604 1605 1606 1607 1608 1609 1611 The acl and aces can be described in CLI as the following: 1613 access-list ipv4 sample-ipv4-acl 1614 deny tcp 10.10.10.1/24 11.11.11.1/24 1616 4.4. Port Range Usage Example 1618 When a lower-port and an upper-port are both present, it represents a 1619 range between lower-port and upper-port with both the lower-port and 1620 upper-port are included. When only a lower-port presents, it 1621 represents a single port. 1623 With the follow XML snippet: 1625 1626 1627 1628 16384 1629 16387 1630 1631 1632 1634 This represents source ports 16384, 16385, 16386, and 16387. 1636 With the follow XML snippet: 1638 1639 1640 1641 16384 1642 65535 1643 1644 1645 1647 This represents source ports greater than or equal to 16384 and less 1648 than equal to 65535. 1650 With the follow XML snippet: 1652 1653 1654 1655 eq 1656 21 1657 1658 1659 1661 This represents port 21. 1663 With the following XML snippet, the configuration is specifying all 1664 ports that are not equal to 21. 1666 1667 1668 1669 neq 1670 21 1671 1672 1673 1675 5. Security Considerations 1677 The YANG module defined in this memo is designed to be accessed via 1678 the NETCONF [RFC6241]. The lowest NETCONF layer is the secure 1679 transport layer and the mandatory-to-implement secure transport is 1680 SSH [RFC6242]. The NETCONF Access Control Model ( NACM [RFC6536]) 1681 provides the means to restrict access for particular NETCONF users to 1682 a pre-configured subset of all available NETCONF protocol operations 1683 and content. 1685 There are a number of data nodes defined in the YANG module which are 1686 writable/creatable/deletable (i.e., config true, which is the 1687 default). These data nodes may be considered sensitive or vulnerable 1688 in some network environments. Write operations (e.g., ) 1689 to these data nodes without proper protection can have a negative 1690 effect on network operations. 1692 These are the subtrees and data nodes and their sensitivity/ 1693 vulnerability: 1695 /access-lists/acl/aces: This list specifies all the configured access 1696 control entries on the device. Unauthorized write access to this 1697 list can allow intruders to access and control the system. 1698 Unauthorized read access to this list can allow intruders to spoof 1699 packets with authorized addresses thereby compromising the system. 1701 6. IANA Considerations 1703 This document registers a URI in the IETF XML registry [RFC3688]. 1704 Following the format in RFC 3688, the following registration is 1705 requested to be made: 1707 URI: urn:ietf:params:xml:ns:yang:ietf-access-control-list 1709 URI: urn:ietf:params:xml:ns:yang:ietf-packet-fields 1711 Registrant Contact: The IESG. 1713 XML: N/A, the requested URI is an XML namespace. 1715 This document registers a YANG module in the YANG Module Names 1716 registry [RFC6020]. 1718 name: ietf-access-control-list namespace: 1719 urn:ietf:params:xml:ns:yang:ietf-access-control-list prefix: ietf-acl 1720 reference: RFC XXXX 1722 name: ietf-packet-fields namespace: urn:ietf:params:xml:ns:yang:ietf- 1723 packet-fields prefix: ietf-packet-fields reference: RFC XXXX 1725 7. Acknowledgements 1727 Alex Clemm, Andy Bierman and Lisa Huang started it by sketching out 1728 an initial IETF draft in several past IETF meetings. That draft 1729 included an ACL YANG model structure and a rich set of match filters, 1730 and acknowledged contributions by Louis Fourie, Dana Blair, Tula 1731 Kraiser, Patrick Gili, George Serpa, Martin Bjorklund, Kent Watsen, 1732 and Phil Shafer. Many people have reviewed the various earlier 1733 drafts that made the draft went into IETF charter. 1735 Dean Bogdanovic, Kiran Agrahara Sreenivasa, Lisa Huang, and Dana 1736 Blair each evaluated the YANG model in previous drafts separately, 1737 and then worked together to created a ACL draft that was supported by 1738 different vendors. That draft removed vendor specific features, and 1739 gave examples to allow vendors to extend in their own proprietary 1740 ACL. The earlier draft was superseded with this updated draft and 1741 received more participation from many vendors. 1743 Authors would like to thank Jason Sterne, Lada Lhotka, Juergen 1744 Schoenwalder, David Bannister, Jeff Haas, Kristian Larsson and Einar 1745 Nilsen-Nygaard for their review of and suggestions to the draft. 1747 8. Open Issues 1749 o The current model does not support the concept of "containers" 1750 used to contain multiple addresses per rule entry. 1752 9. References 1754 9.1. Normative References 1756 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1757 DOI 10.17487/RFC3688, January 2004, 1758 . 1760 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1761 the Network Configuration Protocol (NETCONF)", RFC 6020, 1762 DOI 10.17487/RFC6020, October 2010, 1763 . 1765 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1766 and A. Bierman, Ed., "Network Configuration Protocol 1767 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1768 . 1770 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1771 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1772 . 1774 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1775 Protocol (NETCONF) Access Control Model", RFC 6536, 1776 DOI 10.17487/RFC6536, March 2012, 1777 . 1779 9.2. Informative References 1781 [I-D.ietf-netmod-yang-tree-diagrams] 1782 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 1783 ietf-netmod-yang-tree-diagrams-04 (work in progress), 1784 December 2017. 1786 [RFC5101] Claise, B., Ed., "Specification of the IP Flow Information 1787 Export (IPFIX) Protocol for the Exchange of IP Traffic 1788 Flow Information", RFC 5101, DOI 10.17487/RFC5101, January 1789 2008, . 1791 Appendix A. Extending ACL model examples 1793 A.1. A company proprietary module example 1795 Module "example-newco-acl" is an example of company proprietary model 1796 that augments "ietf-acl" module. It shows how to use 'augment' with 1797 an XPath expression to add additional match criteria, action 1798 criteria, and default actions when no ACE matches found. All these 1799 are company proprietary extensions or system feature extensions. 1800 "example-newco-acl" is just an example and it is expected from 1801 vendors to create their own proprietary models. 1803 The following figure is the tree structure of example-newco-acl. In 1804 this example, /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf- 1805 acl:ace/ietf-acl:matches are augmented with two new choices, 1806 protocol-payload-choice and metadata. The protocol-payload-choice 1807 uses a grouping with an enumeration of all supported protocol values. 1809 Metadata matches apply to fields associated with the packet but not 1810 in the packet header such as overall packet length. In other 1811 example, /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf- 1812 acl:ace/ietf-acl:actions are augmented with new choice of actions. 1814 module: example-newco-acl 1815 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ac 1816 e/ietf-acl:matches: 1817 +--rw (protocol-payload-choice)? 1818 | +--:(protocol-payload) 1819 | +--rw protocol-payload* [value-keyword] 1820 | +--rw value-keyword enumeration 1821 +--rw (metadata)? 1822 +--:(packet-length) 1823 +--rw packet-length? uint16 1824 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ac 1825 e/ietf-acl:actions: 1826 +--rw (action)? 1827 +--:(count) 1828 | +--rw count? uint32 1829 +--:(policer) 1830 | +--rw policer? string 1831 +--:(hiearchical-policer) 1832 +--rw hierarchitacl-policer? string 1833 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ac 1834 e/ietf-acl:actions: 1835 +--rw default-action? identityref 1837 module example-newco-acl { 1839 yang-version 1.1; 1841 namespace "urn:newco:params:xml:ns:yang:example-newco-acl"; 1843 prefix example-newco-acl; 1845 import ietf-access-control-list { 1846 prefix "ietf-acl"; 1847 } 1849 organization 1850 "Newco model group."; 1852 contact 1853 "abc@newco.com"; 1854 description 1855 "This YANG module augments IETF ACL Yang."; 1857 revision 2018-01-16 { 1858 description 1859 "Creating NewCo proprietary extensions to ietf-acl model"; 1861 reference 1862 "RFC XXXX: Network Access Control List (ACL) 1863 YANG Data Model"; 1864 } 1866 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1867 "ietf-acl:aces/ietf-acl:ace/" + 1868 "ietf-acl:matches" { 1869 description "Newco proprietary simple filter matches"; 1870 choice protocol-payload-choice { 1871 description "Newco proprietary payload match condition"; 1872 list protocol-payload { 1873 key value-keyword; 1874 ordered-by user; 1875 description "Match protocol payload"; 1876 uses match-simple-payload-protocol-value; 1877 } 1878 } 1880 choice metadata { 1881 description "Newco proprietary interface match condition"; 1882 leaf packet-length { 1883 type uint16; 1884 description "Match on packet length"; 1885 } 1886 } 1887 } 1889 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1890 "ietf-acl:aces/ietf-acl:ace/" + 1891 "ietf-acl:actions" { 1892 description "Newco proprietary simple filter actions"; 1893 choice action { 1894 description ""; 1895 case count { 1896 description "Count the packet in the named counter"; 1897 leaf count { 1898 type uint32; 1899 description "Count"; 1900 } 1901 } 1902 case policer { 1903 description "Name of policer to use to rate-limit traffic"; 1904 leaf policer { 1905 type string; 1906 description "Name of the policer"; 1907 } 1908 } 1909 case hiearchical-policer { 1910 description "Name of hierarchical policer to use to 1911 rate-limit traffic"; 1912 leaf hierarchitacl-policer { 1913 type string; 1914 description "Name of the hierarchical policer."; 1915 } 1916 } 1917 } 1918 } 1920 augment "/ietf-acl:access-lists/ietf-acl:acl" + 1921 "/ietf-acl:aces/ietf-acl:ace/" + 1922 "ietf-acl:actions" { 1923 description "Newco proprietary default action"; 1924 leaf default-action { 1925 description 1926 "Actions that occur if no ace is matched."; 1927 type identityref { 1928 base ietf-acl:forwarding-action; 1929 } 1930 default ietf-acl:drop; 1931 } 1932 } 1934 grouping match-simple-payload-protocol-value { 1935 description "Newco proprietary payload"; 1936 leaf value-keyword { 1937 type enumeration { 1938 enum icmp { 1939 description "Internet Control Message Protocol"; 1940 } 1941 enum icmp6 { 1942 description "Internet Control Message Protocol Version 6"; 1943 } 1944 enum range { 1945 description "Range of values"; 1946 } 1947 } 1948 description "(null)"; 1949 } 1950 } 1951 } 1952 Draft authors expect that different vendors will provide their own 1953 yang models as in the example above, which is the augmentation of the 1954 base model 1956 A.2. Linux nftables 1958 As Linux platform is becoming more popular as networking platform, 1959 the Linux data model is changing. Previously ACLs in Linux were 1960 highly protocol specific and different utilities were used (iptables, 1961 ip6tables, arptables, ebtables), so each one had separate data model. 1962 Recently, this has changed and a single utility, nftables, has been 1963 developed. With a single application, it has a single data model for 1964 filewall filters and it follows very similarly to the ietf-access- 1965 control list module proposed in this draft. The nftables support 1966 input and output ACEs and each ACE can be defined with match and 1967 action. 1969 The example in Section 4.3 can be configured using nftable tool as 1970 below. 1972 nft add table ip filter 1973 nft add chain filter input 1974 nft add rule ip filter input ip protocol tcp ip saddr \ 1975 10.10.10.1/24 drop 1977 The configuration entries added in nftable would be. 1979 table ip filter { 1980 chain input { 1981 ip protocol tcp ip saddr 10.10.10.1/24 drop 1982 } 1983 } 1985 We can see that there are many similarities between Linux nftables 1986 and IETF ACL YANG data models and its extension models. It should be 1987 fairly easy to do translation between ACL YANG model described in 1988 this draft and Linux nftables. 1990 A.3. Ethertypes 1992 The ACL module is dependent on the definition of ethertypes. IEEE 1993 owns the allocation of those ethertypes. This model is being 1994 included here to enable definition of those types till such time that 1995 IEEE takes up the task of publication of the model that defines those 1996 ethertypes. At that time, this model can be deprecated. 1998 file "ietf-ethertypes@2018-01-16.yang" 1999 module ietf-ethertypes { 2000 namespace "urn:ietf:params:xml:ns:yang:ietf-ethertypes"; 2001 prefix ie; 2003 organization 2004 "IETF NETMOD (NETCONF Data Modeling Language)"; 2006 contact 2007 "WG Web: 2008 WG List: 2010 Editor: Mahesh Jethanandani 2011 "; 2013 description 2014 "This module contains the common definitions for the 2015 Ethertype used by different modules. It is a 2016 placeholder module, till such time that IEEE 2017 starts a project to define these Ethertypes 2018 and publishes a standard. 2020 At that time this module can be deprecated."; 2022 revision 2018-01-16 { 2023 description 2024 "Initial revision."; 2025 reference 2026 "RFC XXXX: IETF Ethertype YANG Data Module."; 2027 } 2029 typedef ethertype { 2030 type union { 2031 type uint16; 2032 type enumeration { 2033 enum ipv4 { 2034 value 2048; 2035 description 2036 "Internet Protocol version 4 (IPv4) with a 2037 hex value of 0x0800."; 2038 reference 2039 "RFC 791, Internet Protocol."; 2040 } 2041 enum arp { 2042 value 2054; 2043 description 2044 "Address Resolution Protocol (ARP) with a 2045 hex value of 0x0806."; 2046 reference 2047 "RFC 826 An Ethernet Address Resolution Protocol."; 2048 } 2049 enum wlan { 2050 value 2114; 2051 description 2052 "Wake-on-LAN. Hex value of 0x0842."; 2053 } 2054 enum trill { 2055 value 8947; 2056 description 2057 "Transparent Interconnection of Lots of Links. 2058 Hex value of 0x22F3."; 2059 reference 2060 "RFC 6325 Routing Bridges (RBridges): Base Protocol 2061 Specification."; 2062 } 2063 enum srp { 2064 value 8938; 2065 description 2066 "Stream Reservation Protocol. Hex value of 2067 0x22EA."; 2068 reference 2069 "IEEE 801.1Q-2011."; 2070 } 2071 enum decnet { 2072 value 24579; 2073 description 2074 "DECnet Phase IV. Hex value of 0x6003."; 2075 } 2076 enum rarp { 2077 value 32821; 2078 description 2079 "Reverse Address Resolution Protocol. 2080 Hex value 0x8035."; 2081 reference 2082 "RFC 903. A Reverse Address Resolution Protocol."; 2083 } 2084 enum appletalk { 2085 value 32923; 2086 description 2087 "Appletalk (Ethertalk). Hex value 0x809B."; 2088 } 2089 enum aarp { 2090 value 33011; 2091 description 2092 "Appletalk Address Resolution Protocol. Hex value 2093 of 0x80F3."; 2094 } 2095 enum vlan { 2096 value 33024; 2097 description 2098 "VLAN-tagged frame (802.1Q) and Shortest Path 2099 Bridging IEEE 802.1aq with NNI compatibility. 2100 Hex value 0x8100."; 2101 reference 2102 "802.1Q."; 2104 } 2105 enum ipx { 2106 value 33079; 2107 description 2108 "Internetwork Packet Exchange (IPX). Hex value 2109 of 0x8137."; 2110 } 2111 enum qnx { 2112 value 33284; 2113 description 2114 "QNX Qnet. Hex value of 0x8204."; 2115 } 2116 enum ipv6 { 2117 value 34525; 2118 description 2119 "Internet Protocol Version 6 (IPv6). Hex value 2120 of 0x86DD."; 2121 reference 2122 "RFC 8200, 8201."; 2123 } 2124 enum efc { 2125 value 34824; 2126 description 2127 "Ethernet flow control using pause frames. 2128 Hex value of 0x8808"; 2129 reference 2130 "IEEE Std. 802.1Qbb."; 2131 } 2132 enum esp { 2133 value 34825; 2134 description 2135 "Ethernet Slow Protocol. Hex value of 0x8809."; 2136 reference 2137 "IEEE Std. 802.3-2015"; 2138 } 2139 enum cobranet { 2140 value 34841; 2141 description 2142 "CobraNet. Hex value of 0x"; 2144 } 2145 enum mpls-unicast { 2146 value 34887; 2147 description 2148 "MultiProtocol Label Switch (MPLS) unicast traffic. 2149 Hex value of 0x8847."; 2150 reference 2151 "RFC 3031."; 2152 } 2153 enum mpls-multicast { 2154 value 34888; 2155 description 2156 "MultiProtocol Label Switch (MPLS) multicast traffic. 2157 Hex value of 0x8848."; 2158 reference 2159 "RFC 3031."; 2160 } 2161 enum pppoe-discovery { 2162 value 34915; 2163 description 2164 "Point-to-Point Protocol over Ethernet. Used during 2165 the discovery process. Hex value of 0x8863."; 2166 reference 2167 "RFC 2516."; 2168 } 2169 enum pppoe-session { 2170 value 34916; 2171 description 2172 "Point-to-Point Protocol over Ethernet. Used during 2173 session stage. Hex value of 0x8864."; 2174 reference 2175 "RFC 2516."; 2176 } 2177 enum intel-ans { 2178 value 34925; 2179 description 2180 "Intel Advanced Networking Services. Hex value of 2181 0x886D."; 2182 } 2183 enum jumbo-frames { 2184 value 34928; 2185 description 2186 "Jumbo frames or Ethernet frames with more than 2187 1500 bytes of payload, upto 9000 bytes."; 2188 } 2189 enum homeplug { 2190 value 34939; 2191 description 2192 "Family name for the various power line 2193 communications. Hex value of 0x887B."; 2194 } 2195 enum eap { 2196 value 34958; 2197 description 2198 "Ethernet Access Protocol (EAP) over LAN. Hex value 2199 of 0x888E."; 2200 reference 2201 "IEEE 802.1X"; 2202 } 2203 enum profinet { 2204 value 34962; 2205 description 2206 "PROcess FIeld Net (PROFINET). Hex value of 0x8892."; 2207 } 2208 enum hyperscsi { 2209 value 34970; 2210 description 2211 "SCSI over Ethernet. Hex value of 0x889A"; 2212 } 2213 enum aoe { 2214 value 34978; 2215 description 2216 "Advanced Technology Advancement (ATA) over Ethernet. 2217 Hex value of 0x88A2."; 2218 } 2219 enum ethercat { 2220 value 34980; 2221 description 2222 "Ethernet for Control Automation Technology (EtherCAT). 2223 Hex value of 0x88A4."; 2224 } 2225 enum provider-bridging { 2226 value 34984; 2227 description 2228 "Provider Bridging (802.1ad) and Shortest Path Bridging 2229 (801.1aq). Hex value of 0x88A8."; 2230 reference 2231 "IEEE 802.1ad, IEEE 802.1aq)."; 2232 } 2233 enum ethernet-powerlink { 2234 value 34987; 2235 description 2236 "Ethernet Powerlink. Hex value of 0x88AB."; 2237 } 2238 enum goose { 2239 value 35000; 2240 description 2241 "Generic Object Oriented Substation Event (GOOSE). 2242 Hex value of 0x88B8."; 2243 reference 2244 "IEC/ISO 8802-2 and 8802-3."; 2245 } 2246 enum gse { 2247 value 35001; 2248 description 2249 "Generic Substation Events. Hex value of 88B9."; 2250 reference 2251 "IEC 61850."; 2252 } 2253 enum sv { 2254 value 35002; 2255 description 2256 "Sampled Value Transmission. Hex value of 0x88BA."; 2257 reference 2258 "IEC 61850."; 2259 } 2260 enum lldp { 2261 value 35020; 2262 description 2263 "Link Layer Discovery Protocol (LLDP). Hex value of 2264 0x88CC."; 2265 reference 2266 "IEEE 802.1AB."; 2267 } 2268 enum sercos { 2269 value 35021; 2270 description 2271 "Sercos Interface. Hex value of 0x88CD."; 2272 } 2273 enum wsmp { 2274 value 35036; 2275 description 2276 "WAVE Short Message Protocl (WSMP). Hex value of 2277 0x88DC."; 2278 } 2279 enum homeplug-av-mme { 2280 value 35041; 2281 description 2282 "HomePlug AV MME. Hex value of 88E1."; 2283 } 2284 enum mrp { 2285 value 35043; 2286 description 2287 "Media Redundancy Protocol (MRP). Hex value of 2288 0x88E3."; 2289 reference 2290 "IEC62439-2."; 2291 } 2292 enum macsec { 2293 value 35045; 2294 description 2295 "MAC Security. Hex value of 0x88E5."; 2296 reference 2297 "IEEE 802.1AE."; 2298 } 2299 enum pbb { 2300 value 35047; 2301 description 2302 "Provider Backbone Bridges (PBB). Hex value of 2303 0x88E7."; 2304 reference 2305 "IEEE 802.1ah."; 2306 } 2307 enum cfm { 2308 value 35074; 2309 description 2310 "Connectivity Fault Management (CFM). Hex value of 2311 0x8902."; 2312 reference 2313 "IEEE 802.1ag."; 2314 } 2315 enum fcoe { 2316 value 35078; 2317 description 2318 "Fiber Channel over Ethernet (FCoE). Hex value of 2319 0x8906."; 2320 reference 2321 "T11 FC-BB-5."; 2322 } 2323 enum fcoe-ip { 2324 value 35092; 2325 description 2326 "FCoE Initialization Protocol. Hex value of 0x8914."; 2327 } 2328 enum roce { 2329 value 35093; 2330 description 2331 "RDMA over Converged Ethernet (RoCE). Hex value of 2332 0x8915."; 2333 } 2334 enum tte { 2335 value 35101; 2336 description 2337 "TTEthernet Protocol Control Frame (TTE). Hex value 2338 of 0x891D."; 2339 reference 2340 "SAE AS6802."; 2341 } 2342 enum hsr { 2343 value 35119; 2344 description 2345 "High-availability Seamless Redundancy (HSR). Hex 2346 value of 0x892F."; 2347 reference 2348 "IEC 62439-3:2016."; 2349 } 2350 } 2351 } 2352 description 2353 "The uint16 type placeholder type is defined to enable 2354 users to manage their own ethertypes not 2355 covered by the module. Otherwise the module contains 2356 enum definitions for the more commonly used ethertypes."; 2357 } 2358 } 2360 2362 Authors' Addresses 2364 Mahesh Jethanandani 2366 Email: mjethanandani@gmail.com 2368 Lisa Huang 2369 General Electric 2371 Email: lyihuang16@gmail.com 2373 Sonal Agarwal 2374 Cisco Systems, Inc. 2376 Email: sagarwal12@gmail.com 2377 Dana Blair 2378 Cisco Systems, INc 2380 Email: dblair@cisco.com