idnits 2.17.1 draft-ietf-netmod-acl-model-13.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 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 656: '...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 246 has weird spacing: '...er-port ine...' == Line 250 has weird spacing: '...er-port ine...' == Line 268 has weird spacing: '...er-port ine...' == Line 272 has weird spacing: '...er-port ine...' == Line 299 has weird spacing: '...er-port ine...' == (7 more instances...) -- The document date (September 12, 2017) is 2411 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-01 -- Obsolete informational reference (is this intentional?): RFC 5101 (Obsoleted by RFC 7011) Summary: 2 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 Cisco Systems, Inc 4 Intended status: Standards Track L. Huang 5 Expires: March 16, 2018 General Electric 6 S. Agarwal 7 Cisco Systems, Inc. 8 D. Blair 9 Cisco Systems, INc 10 September 12, 2017 12 Network Access Control List (ACL) YANG Data Model 13 draft-ietf-netmod-acl-model-13 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 http://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 March 16, 2018. 55 Copyright Notice 57 Copyright (c) 2017 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 (http://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 . . . . . . . . . . . . . . . . 18 80 4.3. An ACL Example . . . . . . . . . . . . . . . . . . . . . 31 81 4.4. Port Range Usage Example . . . . . . . . . . . . . . . . 32 82 5. Security Considerations . . . . . . . . . . . . . . . . . . . 33 83 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 84 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 34 85 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 35 86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 87 9.1. Normative References . . . . . . . . . . . . . . . . . . 35 88 9.2. Informative References . . . . . . . . . . . . . . . . . 36 89 Appendix A. Extending ACL model examples . . . . . . . . . . . . 36 90 A.1. Example of extending existing model for route filtering . 36 91 A.2. A company proprietary module example . . . . . . . . . . 38 92 A.3. Linux nftables . . . . . . . . . . . . . . . . . . . . . 44 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 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 set of rules that is used to filter traffic on a 102 networking device. Each rule is represented by an Access Control 103 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, vendors would have to augment 135 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 easily 160 used 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 list entries - ACEs. 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. 198 The use of feature statements in the document allows vendors to 199 advertise match rules they support. 201 3.1. ACL Modules 203 There are two YANG modules in the model. The first module, "ietf- 204 access-control-list", defines generic ACL aspects which are common to 205 all ACLs regardless of their type or vendor. In effect, the module 206 can be viewed as providing a generic ACL "superclass". It imports 207 the second module, "ietf-packet-fields". The match container in 208 "ietf-access-control-list" uses groupings in "ietf-packet-fields". 209 The combination of if-feature checks and must statements allow for 210 the selection of relevant match fields that a user can define rules 211 for. 213 If there is a need to define new "matches" choice, such as IPFIX 214 [RFC5101], the container "matches" can be augmented. 216 For a reference to the annotations used in the diagram below, see 217 YANG Tree Diagrams [I-D.ietf-netmod-yang-tree-diagrams]. 219 module: ietf-access-control-list 220 +--rw access-lists 221 +--rw acl* [acl-type acl-name] 222 +--rw acl-name string 223 +--rw acl-type acl-type 224 +--ro acl-oper-data 225 +--rw aces 226 +--rw ace* [rule-name] 227 +--rw rule-name string 228 +--rw matches 229 | +--rw l2-acl {l2-acl}? 230 | | +--rw destination-mac-address? yang:mac-ad 231 dress 232 | | +--rw destination-mac-address-mask? yang:mac-ad 233 dress 234 | | +--rw source-mac-address? yang:mac-ad 235 dress 236 | | +--rw source-mac-address-mask? yang:mac-ad 237 dress 238 | | +--rw ether-type? string 239 | +--rw ipv4-acl {ipv4-acl}? 240 | | +--rw dscp? inet:dscp 241 | | +--rw ecn? uint8 242 | | +--rw length? uint16 243 | | +--rw ttl? uint8 244 | | +--rw protocol? uint8 245 | | +--rw source-port-range! 246 | | | +--rw lower-port inet:port-number 247 | | | +--rw upper-port? inet:port-number 248 | | | +--rw operation? operator 249 | | +--rw destination-port-range! 250 | | | +--rw lower-port inet:port-number 251 | | | +--rw upper-port? inet:port-number 252 | | | +--rw operations? operator 253 | | +--rw ihl? uint8 254 | | +--rw flags? bits 255 | | +--rw offset? uint16 256 | | +--rw identification? uint16 257 | | +--rw destination-ipv4-network? inet:ipv4-prefi 258 x 259 | | +--rw source-ipv4-network? inet:ipv4-prefi 260 x 261 | +--rw ipv6-acl {ipv6-acl}? 262 | | +--rw dscp? inet:dscp 263 | | +--rw ecn? uint8 264 | | +--rw length? uint16 265 | | +--rw ttl? uint8 266 | | +--rw protocol? uint8 267 | | +--rw source-port-range! 268 | | | +--rw lower-port inet:port-number 269 | | | +--rw upper-port? inet:port-number 270 | | | +--rw operation? operator 271 | | +--rw destination-port-range! 272 | | | +--rw lower-port inet:port-number 273 | | | +--rw upper-port? inet:port-number 274 | | | +--rw operations? operator 275 | | +--rw next-header? uint8 276 | | +--rw destination-ipv6-network? inet:ipv6-prefi 277 x 278 | | +--rw source-ipv6-network? inet:ipv6-prefi 279 x 280 | | +--rw flow-label? inet:ipv6-flow- 281 label 282 | +--rw l2-l3-ipv4-acl {mixed-ipv4-acl}? 283 | | +--rw destination-mac-address? yang:mac-ad 284 dress 285 | | +--rw destination-mac-address-mask? yang:mac-ad 287 dress 288 | | +--rw source-mac-address? yang:mac-ad 289 dress 290 | | +--rw source-mac-address-mask? yang:mac-ad 291 dress 292 | | +--rw ether-type? string 293 | | +--rw dscp? inet:dscp 294 | | +--rw ecn? uint8 295 | | +--rw length? uint16 296 | | +--rw ttl? uint8 297 | | +--rw protocol? uint8 298 | | +--rw source-port-range! 299 | | | +--rw lower-port inet:port-number 300 | | | +--rw upper-port? inet:port-number 301 | | | +--rw operation? operator 302 | | +--rw destination-port-range! 303 | | | +--rw lower-port inet:port-number 304 | | | +--rw upper-port? inet:port-number 305 | | | +--rw operations? operator 306 | | +--rw ihl? uint8 307 | | +--rw flags? bits 308 | | +--rw offset? uint16 309 | | +--rw identification? uint16 310 | | +--rw destination-ipv4-network? inet:ipv4-p 311 refix 312 | | +--rw source-ipv4-network? inet:ipv4-p 313 refix 314 | +--rw l2-l3-ipv6-acl {mixed-ipv6-acl}? 315 | | +--rw destination-mac-address? yang:mac-ad 316 dress 317 | | +--rw destination-mac-address-mask? yang:mac-ad 318 dress 319 | | +--rw source-mac-address? yang:mac-ad 320 dress 321 | | +--rw source-mac-address-mask? yang:mac-ad 322 dress 323 | | +--rw ether-type? string 324 | | +--rw dscp? inet:dscp 325 | | +--rw ecn? uint8 326 | | +--rw length? uint16 327 | | +--rw ttl? uint8 328 | | +--rw protocol? uint8 329 | | +--rw source-port-range! 330 | | | +--rw lower-port inet:port-number 331 | | | +--rw upper-port? inet:port-number 332 | | | +--rw operation? operator 333 | | +--rw destination-port-range! 334 | | | +--rw lower-port inet:port-number 335 | | | +--rw upper-port? inet:port-number 336 | | | +--rw operations? operator 337 | | +--rw next-header? uint8 338 | | +--rw destination-ipv6-network? inet:ipv6-p 339 refix 340 | | +--rw source-ipv6-network? inet:ipv6-p 341 refix 342 | | +--rw flow-label? 343 | | inet:ipv6-flow-label 344 | +--rw l2-l3-ipv4-ipv6-acl {l2-l3-ipv4-ipv6-acl}? 345 | | +--rw destination-mac-address? yang:mac-ad 346 dress 347 | | +--rw destination-mac-address-mask? yang:mac-ad 348 dress 349 | | +--rw source-mac-address? yang:mac-ad 350 dress 351 | | +--rw source-mac-address-mask? yang:mac-ad 352 dress 353 | | +--rw ether-type? string 354 | | +--rw dscp? inet:dscp 355 | | +--rw ecn? uint8 356 | | +--rw length? uint16 357 | | +--rw ttl? uint8 358 | | +--rw protocol? uint8 359 | | +--rw source-port-range! 360 | | | +--rw lower-port inet:port-number 361 | | | +--rw upper-port? inet:port-number 362 | | | +--rw operation? operator 363 | | +--rw destination-port-range! 364 | | | +--rw lower-port inet:port-number 365 | | | +--rw upper-port? inet:port-number 366 | | | +--rw operations? operator 367 | | +--rw ihl? uint8 368 | | +--rw flags? bits 369 | | +--rw offset? uint16 370 | | +--rw identification? uint16 371 | | +--rw destination-ipv4-network? inet:ipv4-p 372 refix 373 | | +--rw source-ipv4-network? inet:ipv4-p 374 refix 375 | | +--rw next-header? uint8 376 | | +--rw destination-ipv6-network? inet:ipv6-p 377 refix 378 | | +--rw source-ipv6-network? inet:ipv6-p 379 refix 380 | | +--rw flow-label? 381 | | inet:ipv6-flow-label 382 | +--rw tcp-acl {tcp-acl}? 383 | | +--rw sequence-number? uint32 384 | | +--rw acknowledgement-number? uint32 385 | | +--rw data-offset? uint8 386 | | +--rw reserved? uint8 387 | | +--rw flags? bits 388 | | +--rw window-size? uint16 389 | | +--rw urgent-pointer? uint16 390 | | +--rw options? uint32 391 | +--rw udp-acl {udp-acl}? 392 | | +--rw length? uint16 393 | +--rw icmp-acl {icmp-acl}? 394 | | +--rw type? uint8 395 | | +--rw code? uint8 396 | | +--rw rest-of-header? uint32 397 | +--rw any-acl! {any-acl}? 398 | +--rw interface? if:interface-ref 399 +--rw actions 400 | +--rw (packet-handling)? 401 | | +--:(deny) 402 | | | +--rw deny? empty 403 | | +--:(permit) 404 | | +--rw permit? empty 405 | +--rw logging? boolean 406 +--ro ace-oper-data 407 +--ro match-counter? yang:counter64 409 4. ACL YANG Models 411 4.1. IETF Access Control List module 413 "ietf-access-control-list" is the standard top level module for 414 access lists. The "access-lists" container stores a list of "acl". 415 Each "acl" has information identifying the access list by a 416 name("acl-name") and a list("access-list-entries") of rules 417 associated with the "acl-name". Each of the entries in the 418 list("access-list-entries"), indexed by the string "rule-name", has 419 containers defining "matches" and "actions". 421 The "matches" define criteria used to identify patterns in "ietf- 422 packet-fields". The "actions" define behavior to undertake once a 423 "match" has been identified. In addition to permit and deny for 424 actions, a logging option allows for a match to be logged that can be 425 used to determine which rule was matched upon. 427 file "ietf-access-control-list@2017-09-12.yang" 429 module ietf-access-control-list { 430 namespace "urn:ietf:params:xml:ns:yang:ietf-access-control-list"; 431 prefix acl; 433 import ietf-yang-types { 434 prefix yang; 435 } 437 import ietf-packet-fields { 438 prefix packet-fields; 439 } 441 import ietf-interfaces { 442 prefix if; 443 } 445 organization 446 "IETF NETMOD (NETCONF Data Modeling Language) 447 Working Group"; 449 contact 450 "WG Web: http://tools.ietf.org/wg/netmod/ 451 WG List: netmod@ietf.org 453 Editor: Mahesh Jethanandani 454 mjethanandani@gmail.com 455 Editor: Lisa Huang 456 lyihuang16@gmail.com 457 Editor: Sonal Agarwal 458 agarwaso@cisco.com 459 Editor: Dana Blair 460 dblair@cisco.com"; 462 description 463 "This YANG module defines a component that describe the 464 configuration of Access Control Lists (ACLs). 466 Copyright (c) 2017 IETF Trust and the persons identified as 467 the document authors. All rights reserved. 468 Redistribution and use in source and binary forms, with or 469 without modification, is permitted pursuant to, and subject 470 to the license terms contained in, the Simplified BSD 471 License set forth in Section 4.c of the IETF Trust's Legal 472 Provisions Relating to IETF Documents 473 (http://trustee.ietf.org/license-info). 475 This version of this YANG module is part of RFC XXXX; see 476 the RFC itself for full legal notices."; 478 revision 2017-09-12 { 479 description 480 "Added feature and identity statements for different types 481 of rule matches. Split the matching rules based on the 482 feature statement and added a must statement within 483 each container."; 484 reference 485 "RFC XXX: Network Access Control List (ACL) YANG Data Model."; 486 } 488 /* 489 * Identities 490 */ 491 identity acl-base { 492 description 493 "Base Access Control List type for all Access Control List type 494 identifiers."; 495 } 497 identity ipv4-acl { 498 base acl:acl-base; 499 description 500 "ACL that primarily matches on fields from the IPv4 header 501 (e.g. IPv4 destination address) and layer 4 headers (e.g. TCP 502 destination port). An acl of type ipv4-acl does not contain 503 matches on fields in the ethernet header or the IPv6 header."; 504 } 506 identity ipv6-acl { 507 base acl:acl-base; 508 description 509 "ACL that primarily matches on fields from the IPv6 header 510 (e.g. IPv6 destination address) and layer 4 headers (e.g. TCP 511 destination port). An acl of type ipv6-acl does not contain 512 matches on fields in the ethernet header or the IPv4 header."; 513 } 515 identity eth-acl { 516 base acl:acl-base; 517 description 518 "ACL that primarily matches on fields in the ethernet header, 519 like 10/100/1000baseT or WiFi Access Control List. An acl of 520 type eth-acl does not contain matches on fields in the IPv4 521 header, IPv6 header or layer 4 headers."; 522 } 524 identity mixed-l2-l3-ipv4-acl { 525 base "acl:acl-base"; 526 description 527 "ACL that contains a mix of entries that 528 primarily match on fields in ethernet headers, 529 entries that primarily match on IPv4 headers. 530 Matching on layer 4 header fields may also exist in the 531 list."; 532 } 534 identity mixed-l2-l3-ipv6-acl { 535 base "acl:acl-base"; 537 description 538 "ACL that contains a mix of entries that 539 primarily match on fields in ethernet headers, entries 540 that primarily match on fields in IPv6 headers. Matching on 541 layer 4 header fields may also exist in the list."; 542 } 544 identity mixed-l2-l3-ipv4-ipv6-acl { 545 base "acl:acl-base"; 547 description 548 "ACL that contains a mix of entries that 549 primarily match on fields in ethernet headers, entries 550 that primarily match on fields in IPv4 headers, and entries 551 that primarily match on fields in IPv6 headers. Matching on 552 layer 4 header fields may also exist in the list."; 553 } 555 identity any-acl { 556 base "acl:acl-base"; 558 description 559 "ACL that can contain any pattern to match upon"; 560 } 562 /* 563 * Features 564 */ 565 feature l2-acl { 566 description 567 "Layer 2 ACL supported"; 568 } 570 feature ipv4-acl { 571 description 572 "Layer 3 IPv4 ACL supported"; 573 } 574 feature ipv6-acl { 575 description 576 "Layer 3 IPv6 ACL supported"; 577 } 579 feature mixed-ipv4-acl { 580 description 581 "Layer 2 and Layer 3 IPv4 ACL supported"; 582 } 584 feature mixed-ipv6-acl { 585 description 586 "Layer 2 and Layer 3 IPv6 ACL supported"; 587 } 589 feature l2-l3-ipv4-ipv6-acl { 590 description 591 "Layer 2 and any Layer 3 ACL supported."; 592 } 594 feature tcp-acl { 595 description 596 "TCP header ACL supported."; 597 } 599 feature udp-acl { 600 description 601 "UDP header ACL supported."; 602 } 604 feature icmp-acl { 605 description 606 "ICMP header ACL supported."; 607 } 609 feature any-acl { 610 description 611 "ACL for any pattern."; 612 } 614 /* 615 * Typedefs 616 */ 617 typedef acl-type { 618 type identityref { 619 base acl-base; 620 } 621 description 622 "This type is used to refer to an Access Control List 623 (ACL) type"; 624 } 626 typedef acl-ref { 627 type leafref { 628 path "/access-lists/acl/acl-name"; 629 } 630 description 631 "This type is used by data models that need to reference an 632 Access Control List"; 633 } 635 /* 636 * Configuration data nodes 637 */ 638 container access-lists { 639 description 640 "This is a top level container for Access Control Lists. 641 It can have one or more Access Control Lists."; 642 list acl { 643 key "acl-type acl-name"; 644 description 645 "An Access Control List(ACL) is an ordered list of 646 Access List Entries (ACE). Each Access Control Entry has a 647 list of match criteria and a list of actions. 648 Since there are several kinds of Access Control Lists 649 implemented with different attributes for 650 different vendors, this 651 model accommodates customizing Access Control Lists for 652 each kind and for each vendor."; 653 leaf acl-name { 654 type string; 655 description 656 "The name of access-list. A device MAY restrict the length 657 and value of this name, possibly space and special 658 characters are not allowed."; 659 } 660 leaf acl-type { 661 type acl-type; 662 description 663 "Type of access control list. Indicates the primary intended 664 type of match criteria (e.g. ethernet, IPv4, IPv6, mixed, 665 etc) used in the list instance."; 666 } 667 container acl-oper-data { 668 config false; 669 description 670 "Overall Access Control List operational data"; 671 } 672 container aces { 673 description 674 "The access-list-entries container contains 675 a list of access-list-entries(ACE)."; 676 list ace { 677 key "rule-name"; 678 ordered-by user; 679 description 680 "List of access list entries(ACE)"; 681 leaf rule-name { 682 type string; 683 description 684 "A unique name identifying this Access List 685 Entry(ACE)."; 686 } 688 container matches { 689 description 690 "The rules in this set determine what fields will be 691 matched upon before any action is taken on them. 692 The rules are selected based on the feature set 693 defined by the server and the acl-type defined."; 695 container l2-acl { 696 if-feature l2-acl; 697 must "../../../../acl-type = 'eth-acl'"; 698 uses packet-fields:acl-eth-header-fields; 699 description 700 "Rule set for L2 ACL."; 701 } 703 container ipv4-acl { 704 if-feature ipv4-acl; 705 must "../../../../acl-type = 'ipv4-acl'"; 706 uses packet-fields:acl-ip-header-fields; 707 uses packet-fields:acl-ipv4-header-fields; 708 description 709 "Rule set that supports IPv4 headers."; 710 } 712 container ipv6-acl { 713 if-feature ipv6-acl; 714 must "../../../../acl-type = 'ipv6-acl'"; 715 uses packet-fields:acl-ip-header-fields; 716 uses packet-fields:acl-ipv6-header-fields; 717 description 718 "Rule set that supports IPv6 headers."; 719 } 721 container l2-l3-ipv4-acl { 722 if-feature mixed-ipv4-acl; 723 must "../../../../acl-type = 'mixed-l2-l3-ipv4-acl'"; 724 uses packet-fields:acl-eth-header-fields; 725 uses packet-fields:acl-ip-header-fields; 726 uses packet-fields:acl-ipv4-header-fields; 727 description 728 "Rule set that is a logical AND (&&) of l2 729 and ipv4 headers."; 730 } 732 container l2-l3-ipv6-acl { 733 if-feature mixed-ipv6-acl; 734 must "../../../../acl-type = 'mixed-l2-l3-ipv6-acl'"; 735 uses packet-fields:acl-eth-header-fields; 736 uses packet-fields:acl-ip-header-fields; 737 uses packet-fields:acl-ipv6-header-fields; 738 description 739 "Rule set that is a logical AND (&&) of L2 740 && IPv6 headers."; 741 } 743 container l2-l3-ipv4-ipv6-acl { 744 if-feature l2-l3-ipv4-ipv6-acl; 745 must "../../../../acl-type = 'mixed-l2-l3-ipv4-ipv6-acl'"; 746 uses packet-fields:acl-eth-header-fields; 747 uses packet-fields:acl-ip-header-fields; 748 uses packet-fields:acl-ipv4-header-fields; 749 uses packet-fields:acl-ipv6-header-fields; 750 description 751 "Rule set that is a logical AND (&&) of L2 752 && IPv4 && IPv6 headers."; 753 } 755 container tcp-acl { 756 if-feature tcp-acl; 757 uses packet-fields:acl-tcp-header-fields; 758 description 759 "Rule set that defines TCP headers."; 760 } 762 container udp-acl { 763 if-feature udp-acl; 764 uses packet-fields:acl-udp-header-fields; 765 description 766 "Rule set that defines UDP headers."; 767 } 769 container icmp-acl { 770 if-feature icmp-acl; 771 uses packet-fields:acl-icmp-header-fields; 772 description 773 "Rule set that defines ICMP headers."; 774 } 776 container any-acl { 777 if-feature any-acl; 778 must "../../../../acl-type = 'any-acl'"; 779 presence "Matches any"; 780 description 781 "Rule set that allows for a any ACL."; 782 } 784 leaf interface { 785 type if:interface-ref; 786 description 787 "Interface name that is specified to 788 match upon."; 789 } 790 } 792 container actions { 793 description 794 "Definitions of action criteria for this Access List 795 Entry."; 796 choice packet-handling { 797 default "deny"; 798 description 799 "Packet handling action."; 800 case deny { 801 leaf deny { 802 type empty; 803 description 804 "Deny action."; 805 } 806 } 807 case permit { 808 leaf permit { 809 type empty; 810 description 811 "Permit action."; 812 } 813 } 815 } 816 leaf logging { 817 type boolean; 818 default "false"; 819 description 820 "Log the rule on which the match occurred. 821 Setting the value to true enables logging, 822 whereas setting the value to false disables it."; 823 } 824 } 825 /* 826 * Operational state data nodes 827 */ 828 container ace-oper-data { 829 config false; 830 description 831 "Operational data for this Access List Entry."; 832 leaf match-counter { 833 type yang:counter64; 834 description 835 "Number of matches for this Access List Entry"; 836 } 837 } 838 } 839 } 840 } 841 } 842 } 844 846 4.2. IETF Packet Fields module 848 The packet fields module defines the necessary groups for matching on 849 fields in the packet including ethernet, ipv4, ipv6, and transport 850 layer fields. The 'acl-type' node determines which of these fields 851 get included for any given ACL with the exception of TCP, UDP and 852 ICMP header fields. Those fields can be used in conjunction with any 853 of the above layer 2 or layer 3 fields. 855 Since the number of match criteria is very large, the base draft does 856 not include these directly but references them by "uses" to keep the 857 base module simple. In case more match conditions are needed, those 858 can be added by augmenting choices within container "matches" in 859 ietf-access-control-list.yang model. 861 file "ietf-packet-fields@2017-09-12.yang" 862 module ietf-packet-fields { 863 namespace "urn:ietf:params:xml:ns:yang:ietf-packet-fields"; 864 prefix packet-fields; 866 import ietf-inet-types { 867 prefix inet; 868 } 870 import ietf-yang-types { 871 prefix yang; 872 } 874 organization 875 "IETF NETMOD (NETCONF Data Modeling Language) Working 876 Group"; 878 contact 879 "WG Web: http://tools.ietf.org/wg/netmod/ 880 WG List: netmod@ietf.org 882 Editor: Mahesh Jethanandani 883 mjethanandani@gmail.com 884 Editor: Lisa Huang 885 lyihuang16@gmail.com 886 Editor: Sonal Agarwal 887 agarwaso@cisco.com 888 Editor: Dana Blair 889 dblair@cisco.com"; 891 description 892 "This YANG module defines groupings that are used by 893 ietf-access-control-list YANG module. Their usage is not 894 limited to ietf-access-control-list and can be 895 used anywhere as applicable. 896 Copyright (c) 2017 IETF Trust and the persons identified as 897 the document authors. All rights reserved. 898 Redistribution and use in source and binary forms, with or 899 without modification, is permitted pursuant to, and subject 901 to the license terms contained in, the Simplified BSD 902 License set forth in Section 4.c of the IETF Trust's Legal 903 Provisions Relating to IETF Documents 904 (http://trustee.ietf.org/license-info). 905 This version of this YANG module is part of RFC XXXX; see 906 the RFC itself for full legal notices."; 908 revision 2017-09-12 { 909 description 910 "Added header fields for TCP, UDP, and ICMP."; 911 reference 912 "RFC XXX: Network Access Control List (ACL) YANG Data Model."; 913 } 915 /* 916 * Typedefs 917 */ 918 typedef operator { 919 type enumeration { 920 enum lt { 921 description 922 "Less than."; 923 } 924 enum gt { 925 description 926 "Greater than."; 927 } 928 enum eq { 929 description 930 "Equal to."; 931 } 932 enum neq { 933 description 934 "Not equal to."; 935 } 936 } 937 description 938 "The source and destination port range definitions 939 can be further qualified using an operator. An 940 operator is needed only if lower-port is specified 941 and upper-port is not specified. The operator 942 therefore further qualifies lower-port only."; 943 } 945 grouping acl-transport-header-fields { 946 description 947 "Transport header fields"; 948 container source-port-range { 949 presence "Enables setting source port range"; 950 description 951 "Inclusive range representing source ports to be used. 952 When only lower-port is present, it represents a single 953 port and eq operator is assumed to be default. 955 When both lower-port and upper-port are specified, 956 it implies a range inclusive of both values. 958 If no port is specified, 'any' (wildcard) is assumed."; 960 leaf lower-port { 961 type inet:port-number; 962 mandatory true; 963 description 964 "Lower boundary for port."; 965 } 966 leaf upper-port { 967 type inet:port-number; 968 must ". >= ../lower-port" { 969 error-message 970 "The upper-port must be greater than or equal 971 to lower-port"; 972 } 973 description 974 "Upper boundary for port. If it exists, the upper port 975 must be greater or equal to lower-port."; 976 } 977 leaf operation { 978 type operator; 979 must "(../lower-port and not(../upper-port))" { 980 error-message 981 "If lower-port is specified, and an operator is also 982 specified, then upper-port should not be specified."; 983 description 984 "If lower-port is specified, and an operator is also 985 specified, then upper-port should not be specified."; 986 } 987 default eq; 988 description 989 "Operator to be applied on the lower-port."; 990 } 991 } 993 container destination-port-range { 994 presence "Enables setting destination port range"; 995 description 996 "Inclusive range representing destination ports to be used. 997 When only lower-port is present, it represents a single 998 port and eq operator is assumed to be default. 1000 When both lower-port and upper-port are specified, 1001 it implies a range inclusive of both values. 1003 If no port is specified, 'any' (wildcard) is assumed. "; 1005 leaf lower-port { 1006 type inet:port-number; 1007 mandatory true; 1008 description 1009 "Lower boundary for port."; 1010 } 1011 leaf upper-port { 1012 type inet:port-number; 1013 must ". >= ../lower-port" { 1014 error-message 1015 "The upper-port must be greater than or equal 1016 to lower-port"; 1017 } 1018 description 1019 "Upper boundary for port. If existing, the upper port must 1020 be greater or equal to lower-port"; 1021 } 1022 leaf operations { 1023 type operator; 1024 must "(../lower-port and not(../upper-port))" { 1025 error-message 1026 "If lower-port is specified, and an operator is also 1027 specified, then upper-port should not be specified."; 1028 description 1029 "If lower-port is specified, and an operator is also 1030 specified, then upper-port should not be specified."; 1031 } 1032 default eq; 1033 description 1034 "Operator to be applied on the lower-port."; 1035 } 1036 } 1037 } 1039 grouping acl-ip-header-fields { 1040 description 1041 "IP header fields common to ipv4 and ipv6"; 1042 reference 1043 "RFC 791."; 1045 leaf dscp { 1046 type inet:dscp; 1047 description 1048 "Differentiated Services Code Point."; 1049 reference 1050 "RFC 2474: Definition of Differentiated services field 1051 (DS field) in the IPv4 and IPv6 headers."; 1052 } 1053 leaf ecn { 1054 type uint8 { 1055 range 0..3; 1056 } 1057 description 1058 "Explicit Congestion Notification."; 1059 reference 1060 "RFC 3168."; 1061 } 1063 leaf length { 1064 type uint16; 1065 description 1066 "In IPv4 header field, this field is known as the Total Length. 1067 Total Length is the length of the datagram, measured in octets, 1068 including internet header and data. 1070 In IPv6 header field, this field is known as the Payload 1071 Length, the length of the IPv6 payload, i.e. the rest of 1072 the packet following the IPv6 header, in octets."; 1073 reference 1074 "RFC 719, RFC 2460"; 1075 } 1077 leaf ttl { 1078 type uint8; 1079 description 1080 "This field indicates the maximum time the datagram is allowed 1081 to remain in the internet system. If this field contains the 1082 value zero, then the datagram must be destroyed. 1084 In IPv6, this field is known as the Hop Limit."; 1085 reference "RFC 719, RFC 2460"; 1086 } 1088 leaf protocol { 1089 type uint8; 1090 description 1091 "Internet Protocol number."; 1092 } 1093 uses acl-transport-header-fields; 1094 } 1096 grouping acl-ipv4-header-fields { 1097 description 1098 "Fields in IPv4 header."; 1100 leaf ihl { 1101 type uint8 { 1102 range "5..60"; 1103 } 1104 description 1105 "An IPv4 header field, the Internet Header Length (IHL) is 1106 the length of the internet header in 32 bit words, and 1107 thus points to the beginning of the data. Note that the 1108 minimum value for a correct header is 5."; 1109 } 1111 leaf flags { 1112 type bits { 1113 bit reserved { 1114 position 0; 1115 description 1116 "Reserved. Must be zero."; 1117 } 1118 bit fragment { 1119 position 1; 1120 description 1121 "Setting value to 0 indicates may fragment, while setting 1122 the value to 1 indicates do not fragment."; 1123 } 1124 bit more { 1125 position 2; 1126 description 1127 "Setting the value to 0 indicates this is the last fragment, 1128 and setting the value to 1 indicates more fragments are 1129 coming."; 1130 } 1131 } 1132 description 1133 "Bit definitions for the flags field in IPv4 header."; 1134 } 1136 leaf offset { 1137 type uint16 { 1138 range "20..65535"; 1139 } 1140 description 1141 "The fragment offset is measured in units of 8 octets (64 bits). 1142 The first fragment has offset zero. The length is 13 bits"; 1143 } 1145 leaf identification { 1146 type uint16; 1147 description 1148 "An identifying value assigned by the sender to aid in 1149 assembling the fragments of a datagram."; 1150 } 1152 leaf destination-ipv4-network { 1153 type inet:ipv4-prefix; 1154 description 1155 "Destination IPv4 address prefix."; 1156 } 1157 leaf source-ipv4-network { 1158 type inet:ipv4-prefix; 1159 description 1160 "Source IPv4 address prefix."; 1161 } 1162 } 1164 grouping acl-ipv6-header-fields { 1165 description 1166 "Fields in IPv6 header"; 1168 leaf next-header { 1169 type uint8; 1170 description 1171 "Identifies the type of header immediately following the 1172 IPv6 header. Uses the same values as the IPv4 Protocol 1173 field."; 1174 reference 1175 "RFC 2460"; 1176 } 1178 leaf destination-ipv6-network { 1179 type inet:ipv6-prefix; 1180 description 1181 "Destination IPv6 address prefix."; 1182 } 1184 leaf source-ipv6-network { 1185 type inet:ipv6-prefix; 1186 description 1187 "Source IPv6 address prefix."; 1188 } 1190 leaf flow-label { 1191 type inet:ipv6-flow-label; 1192 description 1193 "IPv6 Flow label."; 1194 } 1195 reference 1196 "RFC 4291: IP Version 6 Addressing Architecture 1197 RFC 4007: IPv6 Scoped Address Architecture 1198 RFC 5952: A Recommendation for IPv6 Address Text 1199 Representation"; 1200 } 1202 grouping acl-eth-header-fields { 1203 description 1204 "Fields in Ethernet header."; 1206 leaf destination-mac-address { 1207 type yang:mac-address; 1208 description 1209 "Destination IEEE 802 MAC address."; 1210 } 1211 leaf destination-mac-address-mask { 1212 type yang:mac-address; 1213 description 1214 "Destination IEEE 802 MAC address mask."; 1215 } 1216 leaf source-mac-address { 1217 type yang:mac-address; 1218 description 1219 "Source IEEE 802 MAC address."; 1220 } 1221 leaf source-mac-address-mask { 1222 type yang:mac-address; 1223 description 1224 "Source IEEE 802 MAC address mask."; 1225 } 1226 leaf ether-type { 1227 type string { 1228 pattern '[0-9a-fA-F]{4}'; 1229 } 1230 description 1231 "The Ethernet Type (or Length) value represented 1232 in the canonical order defined by IEEE 802. 1233 The canonical representation uses lowercase 1234 characters. 1236 Note: This is not the most ideal way to define 1237 ether-types. Ether-types are well known types 1238 and are registered with RAC in IEEE. So they 1239 should well defined types with values. For now 1240 this model is defining it as a string. 1241 There is a note out to IEEE that needs to be 1242 turned into a liaison statement asking them to 1243 define all ether-types for the industry to use."; 1244 reference 1245 "IEEE 802-2014 Clause 9.2"; 1246 } 1247 reference 1248 "IEEE 802: IEEE Standard for Local and Metropolitan 1249 Area Networks: Overview and Architecture."; 1250 } 1252 grouping acl-tcp-header-fields { 1253 description 1254 "Collection of TCP header fields that can be used to 1255 setup a match filter."; 1257 leaf sequence-number { 1258 type uint32; 1259 description 1260 "Sequence number that appears in the packet."; 1261 } 1263 leaf acknowledgement-number { 1264 type uint32; 1265 description 1266 "The acknowledgement number that appears in the 1267 packet."; 1268 } 1270 leaf data-offset { 1271 type uint8 { 1272 range "5..15"; 1273 } 1274 description 1275 "Specifies the size of the TCP header in 32-bit 1276 words. The minimum size header is 5 words and 1277 the maximum is 15 words thus giving the minimum 1278 size of 20 bytes and maximum of 60 bytes, 1279 allowing for up to 40 bytes of options in the 1280 header."; 1281 } 1283 leaf reserved { 1284 type uint8; 1285 description 1286 "Reserved for future use."; 1287 } 1289 leaf flags { 1290 type bits { 1291 bit ns { 1292 position 0; 1293 description 1294 "ECN-nonce concealment protection"; 1295 reference "RFC 3540)."; 1296 } 1297 bit cwr { 1298 position 1; 1299 description 1300 "Congestion Window Reduced (CWR) flag is set by 1301 the sending host to indicate that it received 1302 a TCP segment with the ECE flag set and had 1303 responded in congestion control mechanism."; 1304 reference "RFC 3168"; 1305 } 1306 bit ece { 1307 position 2; 1308 description 1309 "ECN-Echo has a dual role, depending on the value 1310 of the SYN flag. It indicates: 1311 If the SYN flag is set (1), that the TCP peer is ECN 1312 capable. If the SYN flag is clear (0), that a packet 1313 with Congestion Experienced flag set (ECN=11) in IP 1314 header was received during normal transmission 1315 (added to header by RFC 3168). This serves as an 1316 indication of network congestion (or impending 1317 congestion) to the TCP sender."; 1318 } 1319 bit urg { 1320 position 3; 1321 description 1322 "Indicates that the Urgent pointer field is significant."; 1323 } 1324 bit ack { 1325 position 4; 1326 description 1327 "Indicates that the Acknowledgment field is significant. 1328 All packets after the initial SYN packet sent by the 1329 client should have this flag set."; 1330 } 1331 bit psh { 1332 position 5; 1333 description 1334 "Push function. Asks to push the buffered data to the 1335 receiving application."; 1336 } 1337 bit rst { 1338 position 6; 1339 description 1340 "Reset the connection."; 1342 } 1343 bit syn { 1344 position 7; 1345 description 1346 "Synchronize sequence numbers. Only the first packet 1347 sent from each end should have this flag set. Some 1348 other flags and fields change meaning based on this 1349 flag, and some are only valid for when it is set, 1350 and others when it is clear."; 1351 } 1352 bit fin { 1353 position 8; 1354 description 1355 "Last package from sender."; 1356 } 1357 } 1358 description 1359 "Also known as Control Bits. Contains 9 1-bit flags."; 1360 } 1362 leaf window-size { 1363 type uint16; 1364 description 1365 "The size of the receive window, which specifies 1366 the number of window size units (by default, 1367 bytes) (beyond the segment identified by the 1368 sequence number in the acknowledgment field) 1369 that the sender of this segment is currently 1370 willing to receive."; 1371 } 1373 leaf urgent-pointer { 1374 type uint16; 1375 description 1376 "This field is an offset from the sequence number 1377 indicating the last urgent data byte."; 1378 } 1380 leaf options { 1381 type uint32; 1382 description 1383 "The length of this field is determined by the 1384 data offset field. Options have up to three 1385 fields: Option-Kind (1 byte), Option-Length 1386 (1 byte), Option-Data (variable). The Option-Kind 1387 field indicates the type of option, and is the 1388 only field that is not optional. Depending on 1389 what kind of option we are dealing with, 1390 the next two fields may be set: the Option-Length 1391 field indicates the total length of the option, 1392 and the Option-Data field contains the value of 1393 the option, if applicable."; 1394 } 1395 } 1397 grouping acl-udp-header-fields { 1398 description 1399 "Collection of UDP header fields that can be used 1400 to setup a match filter."; 1402 leaf length { 1403 type uint16; 1404 description 1405 "A field that specifies the length in bytes of 1406 the UDP header and UDP data. The minimum 1407 length is 8 bytes because that is the length of 1408 the header. The field size sets a theoretical 1409 limit of 65,535 bytes (8 byte header + 65,527 1410 bytes of data) for a UDP datagram. However the 1411 actual limit for the data length, which is 1412 imposed by the underlying IPv4 protocol, is 1413 65,507 bytes (65,535 minus 8 byte UDP header 1414 minus 20 byte IP header). 1416 In IPv6 jumbograms it is possible to have 1417 UDP packets of size greater than 65,535 bytes. 1418 RFC 2675 specifies that the length field is set 1419 to zero if the length of the UDP header plus 1420 UDP data is greater than 65,535."; 1421 } 1422 } 1424 grouping acl-icmp-header-fields { 1425 description 1426 "Collection of ICMP header fields that can be 1427 used to setup a match filter."; 1429 leaf type { 1430 type uint8; 1431 description 1432 "Also known as Control messages."; 1433 reference "RFC 792"; 1434 } 1436 leaf code { 1437 type uint8; 1438 description 1439 "ICMP subtype. Also known as Control messages."; 1440 } 1442 leaf rest-of-header { 1443 type uint32; 1444 description 1445 "Four-bytes field, contents vary based on the 1446 ICMP type and code."; 1447 } 1448 } 1449 } 1451 1453 4.3. An ACL Example 1455 Requirement: Deny tcp traffic from 10.10.10.1/24, destined to 1456 11.11.11.1/24. 1458 Here is the acl configuration xml for this Access Control List: 1460 1461 1462 1464 1465 sample-ipv4-acl 1466 ipv4-acl 1467 1468 1469 rule1 1470 1471 1472 tcp 1473 1474 11.11.11.1/24 1475 1476 1477 10.10.10.1/24 1478 1479 1480 1481 1482 deny 1483 1484 1485 1486 1487 1488 1490 The acl and aces can be described in CLI as the following: 1492 access-list ipv4 sample-ipv4-acl 1493 deny tcp 10.10.10.1/24 11.11.11.1/24 1495 4.4. Port Range Usage Example 1497 When a lower-port and an upper-port are both present, it represents a 1498 range between lower-port and upper-port with both the lower-port and 1499 upper-port are included. When only a lower-port presents, it 1500 represents a single port. 1502 With the follow XML snippet: 1504 1505 16384 1506 16387 1507 1509 This represents source ports 16384,16385, 16386, and 16387. 1511 With the follow XML snippet: 1513 1514 16384 1515 65535 1516 1518 This represents source ports greater than/equal to 16384 and less 1519 than equal to 65535. 1521 With the follow XML snippet: 1523 1524 21 1525 1527 This represents port 21. 1529 With the following XML snippet, the configuration is specifying all 1530 ports that are not equal to 21. 1532 1533 21 1534 neq 1535 1537 5. Security Considerations 1539 The YANG module defined in this memo is designed to be accessed via 1540 the NETCONF [RFC6241]. The lowest NETCONF layer is the secure 1541 transport layer and the mandatory-to-implement secure transport is 1542 SSH [RFC6242]. The NETCONF Access Control Model ( NACM [RFC6536]) 1543 provides the means to restrict access for particular NETCONF users to 1544 a pre-configured subset of all available NETCONF protocol operations 1545 and content. 1547 There are a number of data nodes defined in the YANG module which are 1548 writable/creatable/deletable (i.e., config true, which is the 1549 default). These data nodes may be considered sensitive or vulnerable 1550 in some network environments. Write operations (e.g., ) 1551 to these data nodes without proper protection can have a negative 1552 effect on network operations. 1554 These are the subtrees and data nodes and their sensitivity/ 1555 vulnerability: 1557 /access-lists/acl/access-list-entries: This list specifies all the 1558 configured access list entries on the device. Unauthorized write 1559 access to this list can allow intruders to access and control the 1560 system. Unauthorized read access to this list can allow intruders to 1561 spoof packets with authorized addresses thereby compromising the 1562 system. 1564 6. IANA Considerations 1566 This document registers a URI in the IETF XML registry [RFC3688]. 1567 Following the format in RFC 3688, the following registration is 1568 requested to be made: 1570 URI: urn:ietf:params:xml:ns:yang:ietf-access-control-list 1572 URI: urn:ietf:params:xml:ns:yang:ietf-packet-fields 1574 Registrant Contact: The IESG. 1576 XML: N/A, the requested URI is an XML namespace. 1578 This document registers a YANG module in the YANG Module Names 1579 registry [RFC6020]. 1581 name: ietf-access-control-list namespace: 1582 urn:ietf:params:xml:ns:yang:ietf-access-control-list prefix: ietf-acl 1583 reference: RFC XXXX 1585 name: ietf-packet-fields namespace: urn:ietf:params:xml:ns:yang:ietf- 1586 packet-fields prefix: ietf-packet-fields reference: RFC XXXX 1588 7. Acknowledgements 1590 Alex Clemm, Andy Bierman and Lisa Huang started it by sketching out 1591 an initial IETF draft in several past IETF meetings. That draft 1592 included an ACL YANG model structure and a rich set of match filters, 1593 and acknowledged contributions by Louis Fourie, Dana Blair, Tula 1594 Kraiser, Patrick Gili, George Serpa, Martin Bjorklund, Kent Watsen, 1595 and Phil Shafer. Many people have reviewed the various earlier 1596 drafts that made the draft went into IETF charter. 1598 Dean Bogdanovic, Kiran Agrahara Sreenivasa, Lisa Huang, and Dana 1599 Blair each evaluated the YANG model in previous drafts separately, 1600 and then worked together to created a ACL draft that was supported by 1601 different vendors. That draft removed vendor specific features, and 1602 gave examples to allow vendors to extend in their own proprietary 1603 ACL. The earlier draft was superseded with this updated draft and 1604 received more participation from many vendors. 1606 Authors would like to thank Jason Sterne, Lada Lhotka, Juergen 1607 Schoenwalder, and David Bannister for their review of and suggestions 1608 to the draft. 1610 8. Open Issues 1612 o The current model does not support the concept of "containers" 1613 used to contain multiple addresses per rule entry. 1615 o The model defines 'ether-type' node as a string. Ideally, this 1616 should be a well defined list of all Ethernet Types assigned by 1617 IEEE. 1619 9. References 1621 9.1. Normative References 1623 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1624 DOI 10.17487/RFC3688, January 2004, . 1627 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1628 the Network Configuration Protocol (NETCONF)", RFC 6020, 1629 DOI 10.17487/RFC6020, October 2010, . 1632 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1633 and A. Bierman, Ed., "Network Configuration Protocol 1634 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1635 . 1637 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1638 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1639 . 1641 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1642 Protocol (NETCONF) Access Control Model", RFC 6536, 1643 DOI 10.17487/RFC6536, March 2012, . 1646 9.2. Informative References 1648 [I-D.ietf-netmod-yang-tree-diagrams] 1649 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 1650 ietf-netmod-yang-tree-diagrams-01 (work in progress), June 1651 2017. 1653 [RFC5101] Claise, B., Ed., "Specification of the IP Flow Information 1654 Export (IPFIX) Protocol for the Exchange of IP Traffic 1655 Flow Information", RFC 5101, DOI 10.17487/RFC5101, January 1656 2008, . 1658 Appendix A. Extending ACL model examples 1660 A.1. Example of extending existing model for route filtering 1662 With proposed modular design, it is easy to extend the model with 1663 other features. Those features can be standard features, like route 1664 filters. Route filters match on specific IP addresses or ranges of 1665 prefixes. Much like ACLs, they include some match criteria and 1666 corresponding match action(s). For that reason, it is very simple to 1667 extend existing ACL model with route filtering. The combination of a 1668 route prefix and prefix length along with the type of match 1669 determines how route filters are evaluated against incoming routes. 1670 Different vendors have different match types and in this model we are 1671 using only ones that are common across all vendors participating in 1672 this draft. As in this example, the base ACL model can be extended 1673 with company proprietary extensions, described in the next section. 1675 module: example-ext-route-filter 1676 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ac 1677 e/ietf-acl:matches: 1678 +--rw (route-prefix)? 1679 +--:(range) 1680 +--rw (ipv4-range)? 1681 | +--:(v4-lower-bound) 1682 | | +--rw v4-lower-bound? inet:ipv4-prefix 1683 | +--:(v4-upper-bound) 1684 | +--rw v4-upper-bound? inet:ipv4-prefix 1685 +--rw (ipv6-range)? 1686 +--:(v6-lower-bound) 1687 | +--rw v6-lower-bound? inet:ipv6-prefix 1688 +--:(v6-upper-bound) 1689 +--rw v6-upper-bound? inet:ipv6-prefix 1691 file "example-ext-route-filter@2017-09-12.yang" 1692 module example-ext-route-filter { 1693 namespace "urn:ietf:params:xml:ns:yang:example-ext-route-filter"; 1694 prefix example-ext-route-filter; 1696 import ietf-inet-types { 1697 prefix "inet"; 1698 } 1699 import ietf-access-control-list { 1700 prefix "ietf-acl"; 1701 } 1703 organization 1704 "Route model group."; 1706 contact 1707 "abc@abc.com"; 1709 description " 1710 This module describes route filter as a collection of 1711 match prefixes. When specifying a match prefix, you 1712 can specify an exact match with a particular route or 1713 a less precise match. You can configure either a 1714 common action that applies to the entire list or an 1715 action associated with each prefix. 1716 "; 1717 revision 2017-09-12 { 1718 description 1719 "Creating Route-Filter extension model based on 1720 ietf-access-control-list model"; 1721 reference "Example route filter"; 1722 } 1724 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1725 "ietf-acl:aces/ietf-acl:ace/ietf-acl:matches" { 1726 description " 1727 This module augments the matches container in the ietf-acl 1728 module with route filter specific actions"; 1730 choice route-prefix{ 1731 description "Define route filter match criteria"; 1732 case range { 1733 description 1734 "Route falls between the lower prefix/prefix-length 1735 and the upperprefix/prefix-length."; 1736 choice ipv4-range { 1737 description "Defines the IPv4 prefix range"; 1738 leaf v4-lower-bound { 1739 type inet:ipv4-prefix; 1740 description 1741 "Defines the lower IPv4 prefix/prefix length"; 1743 } 1744 leaf v4-upper-bound { 1745 type inet:ipv4-prefix; 1746 description 1747 "Defines the upper IPv4 prefix/prefix length"; 1748 } 1749 } 1750 choice ipv6-range { 1751 description "Defines the IPv6 prefix/prefix range"; 1752 leaf v6-lower-bound { 1753 type inet:ipv6-prefix; 1754 description 1755 "Defines the lower IPv6 prefix/prefix length"; 1756 } 1757 leaf v6-upper-bound { 1758 type inet:ipv6-prefix; 1759 description 1760 "Defines the upper IPv6 prefix/prefix length"; 1761 } 1762 } 1763 } 1764 } 1765 } 1766 } 1768 A.2. A company proprietary module example 1770 Access control list typically does not exist in isolation. Instead, 1771 they are associated with a certain scope in which they are applied, 1772 for example, an interface of a set of interfaces. How to attach an 1773 access control list to an interface (or other system artifact) is 1774 outside the scope of this model, as it depends on the specifics of 1775 the system model that is being applied. However, in general, the 1776 general design pattern will involved adding a data node with a 1777 reference, or set of references, to ACLs that are to be applied to 1778 the interface. For this purpose, the type definition "access- 1779 control-list-ref" can be used. 1781 Module "example-newco-acl" is an example of company proprietary model 1782 that augments "ietf-acl" module. It shows how to use 'augment' with 1783 an XPath expression to add additional match criteria, action 1784 criteria, and default actions when no ACE matches found, as well how 1785 to attach an Access Control List to an interface. All these are 1786 company proprietary extensions or system feature extensions. 1787 "example-newco-acl" is just an example and it is expected from 1788 vendors to create their own proprietary models. 1790 The following figure is the tree structure of example-newco-acl. In 1791 this example, /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf- 1792 acl:ace/ietf-acl:matches are augmented with two new choices, 1793 protocol-payload-choice and metadata. The protocol-payload-choice 1794 uses a grouping with an enumeration of all supported protocol values. 1795 Metadata matches apply to fields associated with the packet but not 1796 in the packet header such as input interface or overall packet 1797 length. In other example, /ietf-acl:access-lists/ietf-acl:acl/ietf- 1798 acl:aces/ietf-acl:ace/ietf-acl:actions are augmented with new choice 1799 of actions. 1801 module: example-newco-acl 1802 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ac 1803 e/ietf-acl:matches: 1804 +--rw (protocol-payload-choice)? 1805 | +--:(protocol-payload) 1806 | +--rw protocol-payload* [value-keyword] 1807 | +--rw value-keyword enumeration 1808 +--rw (metadata)? 1809 +--:(interface-name) 1810 +--rw interface-name* [input-interface] 1811 +--rw input-interface ietf-if:interface-ref 1812 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ac 1813 e/ietf-acl:actions: 1814 +--rw (action)? 1815 +--:(count) 1816 | +--rw count? string 1817 +--:(policer) 1818 | +--rw policer? string 1819 +--:(hiearchical-policer) 1820 +--rw hierarchitacl-policer? string 1821 augment /ietf-acl:access-lists/ietf-acl:acl: 1822 +--rw default-actions 1823 +--rw deny? empty 1824 augment /ietf-if:interfaces/ietf-if:interface: 1825 +--rw acl 1826 +--rw acl-name? ietf-acl:acl-ref 1827 +--ro match-counter? yang:counter64 1828 +--rw (direction)? 1829 +--:(in) 1830 | +--rw in? empty 1831 +--:(out) 1832 +--rw out? empty 1833 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ac 1834 e/ietf-acl:ace-oper-data: 1835 +--ro targets 1836 +--ro (interface)? 1837 +--:(interface-name) 1838 +--ro interface-name* ietf-if:interface-ref 1840 module example-newco-acl { 1842 yang-version 1.1; 1844 namespace "urn:newco:params:xml:ns:yang:example-newco-acl"; 1846 prefix example-newco-acl; 1848 import ietf-access-control-list { 1849 prefix "ietf-acl"; 1850 } 1852 import ietf-interfaces { 1853 prefix "ietf-if"; 1854 } 1856 import ietf-yang-types { 1857 prefix yang; 1858 } 1860 organization 1861 "Newco model group."; 1863 contact 1864 "abc@newco.com"; 1865 description 1866 "This YANG module augments IETF ACL Yang."; 1868 revision 2017-09-12 { 1869 description 1870 "Creating NewCo proprietary extensions to ietf-acl model"; 1872 reference 1873 "RFC XXXX: Network Access Control List (ACL) 1874 YANG Data Model"; 1875 } 1877 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1878 "ietf-acl:aces/ietf-acl:ace/" + 1879 "ietf-acl:matches" { 1880 description "Newco proprietary simple filter matches"; 1881 choice protocol-payload-choice { 1882 description "Newo proprietary payload match condition"; 1883 list protocol-payload { 1884 key value-keyword; 1885 ordered-by user; 1886 description "Match protocol payload"; 1887 uses match-simple-payload-protocol-value; 1888 } 1889 } 1891 choice metadata { 1892 description "Newco proprietary interface match condition"; 1893 list interface-name { 1894 key input-interface; 1895 ordered-by user; 1896 description "Match interface name"; 1897 uses metadata; 1898 } 1899 } 1900 } 1902 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1903 "ietf-acl:aces/ietf-acl:ace/" + 1904 "ietf-acl:actions" { 1905 description "Newco proprietary simple filter actions"; 1906 choice action { 1907 description ""; 1908 case count { 1909 description "Count the packet in the named counter"; 1910 leaf count { 1911 type string; 1912 description ""; 1913 } 1914 } 1915 case policer { 1916 description "Name of policer to use to rate-limit traffic"; 1917 leaf policer { 1918 type string; 1919 description ""; 1920 } 1921 } 1922 case hiearchical-policer { 1923 description "Name of hierarchical policer to use to 1924 rate-limit traffic"; 1925 leaf hierarchitacl-policer { 1926 type string; 1927 description ""; 1928 } 1929 } 1930 } 1931 } 1933 augment "/ietf-acl:access-lists/ietf-acl:acl" { 1934 description "Newco proprietary default action"; 1935 container default-actions { 1936 description 1937 "Actions that occur if no access-list entry is matched."; 1938 leaf deny { 1939 type empty; 1940 description ""; 1941 } 1942 } 1943 } 1944 grouping metadata { 1945 description 1946 "Fields associated with a packet which are not in 1947 the header."; 1948 leaf input-interface { 1949 type ietf-if:interface-ref { 1950 require-instance false; 1951 } 1952 description 1953 "Packet was received on this interface"; 1954 } 1955 } 1957 grouping match-simple-payload-protocol-value { 1958 description "Newco proprietary payload"; 1959 leaf value-keyword { 1960 type enumeration { 1961 enum icmp { 1962 description "Internet Control Message Protocol"; 1963 } 1964 enum icmp6 { 1965 description "Internet Control Message Protocol Version 6"; 1966 } 1967 enum range { 1968 description "Range of values"; 1969 } 1970 } 1971 description "(null)"; 1972 } 1973 } 1975 augment "/ietf-if:interfaces/ietf-if:interface" { 1976 description "Apply ACL to interfaces"; 1977 container acl { 1978 description "ACL related properties."; 1979 leaf acl-name { 1980 type ietf-acl:acl-ref; 1981 description "Access Control List name."; 1982 } 1983 leaf match-counter { 1984 type yang:counter64; 1985 config false; 1987 description 1988 "Total match count for Access Control 1989 List on this interface"; 1990 } 1991 choice direction { 1992 description "Applying ACL in which traffic direction"; 1993 leaf in { 1994 type empty; 1995 description "Inbound traffic"; 1996 } 1997 leaf out { 1998 type empty; 1999 description "Outbound traffic"; 2000 } 2001 } 2002 } 2003 } 2005 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 2006 "ietf-acl:aces/ietf-acl:ace/" + 2007 "ietf-acl:ace-oper-data" { 2008 description 2009 "This is an example on how to apply acl to a target to collect 2010 operational data"; 2011 container targets { 2012 description "To which object is the ACL attached to"; 2013 choice interface { 2014 description 2015 "Access Control List was attached to this interface"; 2016 leaf-list interface-name{ 2017 type ietf-if:interface-ref { 2018 require-instance true; 2019 } 2020 description "Attached to this interface name"; 2021 } 2022 } 2023 } 2024 } 2025 } 2027 Draft authors expect that different vendors will provide their own 2028 yang models as in the example above, which is the augmentation of the 2029 base model 2031 A.3. Linux nftables 2033 As Linux platform is becoming more popular as networking platform, 2034 the Linux data model is changing. Previously ACLs in Linux were 2035 highly protocol specific and different utilities were used (iptables, 2036 ip6tables, arptables, ebtables), so each one had separate data model. 2037 Recently, this has changed and a single utility, nftables, has been 2038 developed. With a single application, it has a single data model for 2039 filewall filters and it follows very similarly to the ietf-access- 2040 control list module proposed in this draft. The nftables support 2041 input and output ACEs and each ACE can be defined with match and 2042 action. 2044 The example in Section 4.3 can be configured using nftable tool as 2045 below. 2047 nft add table ip filter 2048 nft add chain filter input 2049 nft add rule ip filter input ip protocol tcp ip saddr \ 2050 10.10.10.1/24 drop 2052 The configuration entries added in nftable would be. 2054 table ip filter { 2055 chain input { 2056 ip protocol tcp ip saddr 10.10.10.1/24 drop 2057 } 2058 } 2060 We can see that there are many similarities between Linux nftables 2061 and IETF ACL YANG data models and its extension models. It should be 2062 fairly easy to do translation between ACL YANG model described in 2063 this draft and Linux nftables. 2065 Authors' Addresses 2067 Mahesh Jethanandani 2068 Cisco Systems, Inc 2070 Email: mjethanandani@gmail.com 2072 Lisa Huang 2073 General Electric 2075 Email: lyihuang16@gmail.com 2077 Sonal Agarwal 2078 Cisco Systems, Inc. 2080 Email: agarwaso@cisco.com 2081 Dana Blair 2082 Cisco Systems, INc 2084 Email: dblair@cisco.com