idnits 2.17.1 draft-ietf-netmod-acl-model-11.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 644: '...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 247 has weird spacing: '...er-port ine...' == Line 250 has weird spacing: '...er-port ine...' == Line 266 has weird spacing: '...er-port ine...' == Line 269 has weird spacing: '...er-port ine...' == Line 293 has weird spacing: '...er-port ine...' == (7 more instances...) -- The document date (June 15, 2017) is 2506 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-00 -- 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 D. Bogdanovic 3 Internet-Draft Volta Networks 4 Intended status: Standards Track M. Jethanandani 5 Expires: December 17, 2017 Cisco Systems, Inc 6 L. Huang 7 General Electric 8 S. Agarwal 9 Cisco Systems, Inc. 10 D. Blair 11 Cisco Systems, INc 12 June 15, 2017 14 Network Access Control List (ACL) YANG Data Model 15 draft-ietf-netmod-acl-model-11 17 Abstract 19 This document describes a data model of Access Control List (ACL) 20 basic building blocks. 22 Editorial Note (To be removed by RFC Editor) 24 This draft contains many placeholder values that need to be replaced 25 with finalized values at the time of publication. This note 26 summarizes all of the substitutions that are needed. Please note 27 that no other RFC Editor instructions are specified anywhere else in 28 this document. 30 Artwork in this document contains shorthand references to drafts in 31 progress. Please apply the following replacements 33 o "XXXX" --> the assigned RFC value for this draft. 35 o Revision date in model (Oct 12, 2016) needs to get updated with 36 the date the draft gets approved. The date also needs to get 37 reflected on the line with . 39 Status of This Memo 41 This Internet-Draft is submitted in full conformance with the 42 provisions of BCP 78 and BCP 79. 44 Internet-Drafts are working documents of the Internet Engineering 45 Task Force (IETF). Note that other groups may also distribute 46 working documents as Internet-Drafts. The list of current Internet- 47 Drafts is at http://datatracker.ietf.org/drafts/current/. 49 Internet-Drafts are draft documents valid for a maximum of six months 50 and may be updated, replaced, or obsoleted by other documents at any 51 time. It is inappropriate to use Internet-Drafts as reference 52 material or to cite them other than as "work in progress." 54 This Internet-Draft will expire on December 17, 2017. 56 Copyright Notice 58 Copyright (c) 2017 IETF Trust and the persons identified as the 59 document authors. All rights reserved. 61 This document is subject to BCP 78 and the IETF Trust's Legal 62 Provisions Relating to IETF Documents 63 (http://trustee.ietf.org/license-info) in effect on the date of 64 publication of this document. Please review these documents 65 carefully, as they describe your rights and restrictions with respect 66 to this document. Code Components extracted from this document must 67 include Simplified BSD License text as described in Section 4.e of 68 the Trust Legal Provisions and are provided without warranty as 69 described in the Simplified BSD License. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 74 1.1. Definitions and Acronyms . . . . . . . . . . . . . . . . 3 75 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 4 76 3. Understanding ACL's Filters and Actions . . . . . . . . . . . 4 77 3.1. ACL Modules . . . . . . . . . . . . . . . . . . . . . . . 5 78 4. ACL YANG Models . . . . . . . . . . . . . . . . . . . . . . . 9 79 4.1. IETF Access Control List module . . . . . . . . . . . . . 9 80 4.2. IETF Packet Fields module . . . . . . . . . . . . . . . . 18 81 4.3. An ACL Example . . . . . . . . . . . . . . . . . . . . . 28 82 4.4. Port Range Usage Example . . . . . . . . . . . . . . . . 28 83 5. Security Considerations . . . . . . . . . . . . . . . . . . . 29 84 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 85 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 86 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 31 87 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 88 9.1. Normative References . . . . . . . . . . . . . . . . . . 31 89 9.2. Informative References . . . . . . . . . . . . . . . . . 32 90 Appendix A. Extending ACL model examples . . . . . . . . . . . . 32 91 A.1. Example of extending existing model for route filtering . 32 92 A.2. A company proprietary module example . . . . . . . . . . 34 93 A.3. Example to augment model with mixed ACL type . . . . . . 42 94 A.4. Linux nftables . . . . . . . . . . . . . . . . . . . . . 43 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 97 1. Introduction 99 Access Control List (ACL) is one of the basic elements to configure 100 device forwarding behavior. It is used in many networking concepts 101 such as Policy Based Routing, Firewalls etc. 103 An ACL is an ordered set of rules that is used to filter traffic on a 104 networking device. Each rule is represented by an Access Control 105 Entry (ACE). 107 Each ACE has a group of match criteria and a group of action 108 criteria. 110 The match criteria consist of a tuple of packet header match criteria 111 and can have metadata match criteria as well. 113 o Packet header matches apply to fields visible in the packet such 114 as address or class of service or port numbers. 116 o In case vendor supports it, metadata matches apply to fields 117 associated with the packet but not in the packet header such as 118 input interface or overall packet length 120 The actions specify what to do with the packet when the matching 121 criteria is met. These actions are any operations that would apply 122 to the packet, such as counting, policing, or simply forwarding.The 123 list of potential actions is endless depending on the innovations of 124 the networked devices. 126 Access Control List is also widely knowns as ACL (pronounce as [ak-uh 127 l]) or Access List. In this document, Access Control List, ACL and 128 Access List are used interchangeably. 130 The matching of filters and actions in an ACE/ACL are triggered only 131 after application/attachment of the ACL to an interface, VRF, vty/tty 132 session, QoS policy, routing protocols amongst various other config 133 attachment points. Once attached, it is used for filtering traffic 134 using the match criteria in the ACE's and taking appropriate 135 action(s) that have been configured against that ACE. In order to 136 apply an ACL to any attachment point, vendors would have to augment 137 the ACL YANG model. 139 1.1. Definitions and Acronyms 141 ACE: Access Control Entry 143 ACL: Access Control List 144 DSCP: Differentiated Services Code Point 146 ICMP: Internet Control Message Protocol 148 IP: Internet Protocol 150 IPv4: Internet Protocol version 4 152 IPv6: Internet Protocol version 6 154 MAC: Media Access Control 156 TCP: Transmission Control Protocol 158 2. Problem Statement 160 This document defines a YANG [RFC6020] data model for the 161 configuration of ACLs. It is very important that model can be easily 162 used by applications/attachments. 164 ACL implementations in every device may vary greatly in terms of the 165 filter constructs and actions that they support. Therefore this 166 draft proposes a model that can be augmented by standard extensions 167 and vendor proprietary models. 169 3. Understanding ACL's Filters and Actions 171 Although different vendors have different ACL data models, there is a 172 common understanding of what access control list (ACL) is. A network 173 system usually have a list of ACLs, and each ACL contains an ordered 174 list of rules, also known as access list entries - ACEs. Each ACE 175 has a group of match criteria and a group of action criteria. The 176 match criteria consist of packet header matching. It as also 177 possible for ACE to match on metadata, if supported by the vendor. 178 Packet header matching applies to fields visible in the packet such 179 as address or class of service or port numbers. Metadata matching 180 applies to fields associated with the packet, but not in the packet 181 header such as input interface, packet length, or source or 182 destination prefix length. The actions can be any sort of operation 183 from logging to rate limiting or dropping to simply forwarding. 184 Actions on the first matching ACE are applied with no processing of 185 subsequent ACEs. 187 The model also includes a container to hold overall operational state 188 for each ACL and operational state for each ACE. One ACL can be 189 applied to multiple targets within the device, such as interfaces of 190 a networked device, applications or features running in the device, 191 etc. When applied to interfaces of a networked device, the ACL is 192 applied in a direction which indicates if it should be applied to 193 packet entering (input) or leaving the device (output). An example 194 in the appendix shows how to express it in YANG model. 196 This draft tries to address the commonalities between all vendors and 197 create a common model, which can be augmented with proprietary 198 models. The base model is simple and with this design we hope to 199 achieve enough flexibility for each vendor to extend the base model. 200 The use of feature statements in the document allows vendors to 201 advertise match rules they support. 203 3.1. ACL Modules 205 There are two YANG modules in the model. The first module, "ietf- 206 access-control-list", defines generic ACL aspects which are common to 207 all ACLs regardless of their type or vendor. In effect, the module 208 can be viewed as providing a generic ACL "superclass". It imports 209 the second module, "ietf-packet-fields". The match container in 210 "ietf-access-control-list" uses groupings in "ietf-packet-fields". 211 The combination of if-feature checks and must statements allow for 212 the selection of relevant match fields that a user can define rules 213 for. 215 If there is a need to define new "matches" choice, such as IPFIX 216 [RFC5101], the container "matches" can be augmented. 218 For a reference to the annotations used in the diagram below, see 219 YANG Tree Diagrams [I-D.ietf-netmod-yang-tree-diagrams]. 221 module: ietf-access-control-list 222 +--rw access-lists 223 +--rw acl* [acl-type acl-name] 224 +--rw acl-name string 225 +--rw acl-type acl-type 226 +--ro acl-oper-data 227 +--rw access-list-entries 228 +--rw ace* [rule-name] 229 +--rw rule-name string 230 +--rw matches 231 | +--rw l2-acl {l2-acl}? 232 | | +--rw destination-mac-address? yang:mac-ad 233 dress 234 | | +--rw destination-mac-address-mask? yang:mac-ad 235 dress 236 | | +--rw source-mac-address? yang:mac-ad 237 dress 238 | | +--rw source-mac-address-mask? yang:mac-ad 239 dress 240 | | +--rw ether-type? string 241 | +--rw ipv4-acl {ipv4-acl}? 242 | | +--rw tos? uint8 243 | | +--rw length? uint16 244 | | +--rw ttl? uint8 245 | | +--rw protocol? uint8 246 | | +--rw source-port-range! 247 | | | +--rw lower-port inet:port-number 248 | | | +--rw upper-port? inet:port-number 249 | | +--rw destination-port-range! 250 | | | +--rw lower-port inet:port-number 251 | | | +--rw upper-port? inet:port-number 252 | | +--rw ihl? uint8 253 | | +--rw flags? bits 254 | | +--rw offset? uint16 255 | | +--rw identification? uint16 256 | | +--rw destination-ipv4-network? inet:ipv4-prefi 257 x 258 | | +--rw source-ipv4-network? inet:ipv4-prefi 259 x 260 | +--rw ipv6-acl {ipv6-acl}? 261 | | +--rw tos? uint8 262 | | +--rw length? uint16 263 | | +--rw ttl? uint8 264 | | +--rw protocol? uint8 265 | | +--rw source-port-range! 266 | | | +--rw lower-port inet:port-number 267 | | | +--rw upper-port? inet:port-number 268 | | +--rw destination-port-range! 269 | | | +--rw lower-port inet:port-number 270 | | | +--rw upper-port? inet:port-number 271 | | +--rw next-header? uint8 272 | | +--rw destination-ipv6-network? inet:ipv6-prefi 273 x 274 | | +--rw source-ipv6-network? inet:ipv6-prefi 275 x 276 | | +--rw flow-label? inet:ipv6-flow- 277 label 278 | +--rw l2-l3-ipv4-acl {mixed-ipv4-acl}? 279 | | +--rw destination-mac-address? yang:mac-ad 280 dress 281 | | +--rw destination-mac-address-mask? yang:mac-ad 282 dress 283 | | +--rw source-mac-address? yang:mac-ad 284 dress 285 | | +--rw source-mac-address-mask? yang:mac-ad 286 dress 287 | | +--rw ether-type? string 288 | | +--rw tos? uint8 289 | | +--rw length? uint16 290 | | +--rw ttl? uint8 291 | | +--rw protocol? uint8 292 | | +--rw source-port-range! 293 | | | +--rw lower-port inet:port-number 294 | | | +--rw upper-port? inet:port-number 295 | | +--rw destination-port-range! 296 | | | +--rw lower-port inet:port-number 297 | | | +--rw upper-port? inet:port-number 298 | | +--rw ihl? uint8 299 | | +--rw flags? bits 300 | | +--rw offset? uint16 301 | | +--rw identification? uint16 302 | | +--rw destination-ipv4-network? inet:ipv4-p 303 refix 304 | | +--rw source-ipv4-network? inet:ipv4-p 305 refix 306 | +--rw l2-l3-ipv6-acl {mixed-ipv6-acl}? 307 | | +--rw destination-mac-address? yang:mac-ad 308 dress 309 | | +--rw destination-mac-address-mask? yang:mac-ad 310 dress 311 | | +--rw source-mac-address? yang:mac-ad 312 dress 313 | | +--rw source-mac-address-mask? yang:mac-ad 314 dress 315 | | +--rw ether-type? string 316 | | +--rw tos? uint8 317 | | +--rw length? uint16 318 | | +--rw ttl? uint8 319 | | +--rw protocol? uint8 320 | | +--rw source-port-range! 321 | | | +--rw lower-port inet:port-number 322 | | | +--rw upper-port? inet:port-number 323 | | +--rw destination-port-range! 324 | | | +--rw lower-port inet:port-number 325 | | | +--rw upper-port? inet:port-number 326 | | +--rw next-header? uint8 327 | | +--rw destination-ipv6-network? inet:ipv6-p 328 refix 329 | | +--rw source-ipv6-network? inet:ipv6-p 330 refix 331 | | +--rw flow-label? inet:ipv6-f 332 low-label 333 | +--rw l2-l3-ipv4-ipv6-acl {l2-l3-ipv4-ipv6-acl}? 334 | | +--rw destination-mac-address? yang:mac-ad 335 dress 336 | | +--rw destination-mac-address-mask? yang:mac-ad 337 dress 338 | | +--rw source-mac-address? yang:mac-ad 339 dress 340 | | +--rw source-mac-address-mask? yang:mac-ad 341 dress 342 | | +--rw ether-type? string 343 | | +--rw tos? uint8 344 | | +--rw length? uint16 345 | | +--rw ttl? uint8 346 | | +--rw protocol? uint8 347 | | +--rw source-port-range! 348 | | | +--rw lower-port inet:port-number 349 | | | +--rw upper-port? inet:port-number 350 | | +--rw destination-port-range! 351 | | | +--rw lower-port inet:port-number 352 | | | +--rw upper-port? inet:port-number 353 | | +--rw ihl? uint8 354 | | +--rw flags? bits 355 | | +--rw offset? uint16 356 | | +--rw identification? uint16 357 | | +--rw destination-ipv4-network? inet:ipv4-p 358 refix 359 | | +--rw source-ipv4-network? inet:ipv4-p 360 refix 361 | | +--rw next-header? uint8 362 | | +--rw destination-ipv6-network? inet:ipv6-p 363 refix 364 | | +--rw source-ipv6-network? inet:ipv6-p 365 refix 366 | | +--rw flow-label? inet:ipv6-f 367 low-label 368 | +--rw tcp-acl {tcp-acl}? 369 | | +--rw sequence-number? uint32 370 | | +--rw acknowledgement-number? uint32 371 | | +--rw data-offset? uint8 372 | | +--rw reserved? uint8 373 | | +--rw flags? uint16 374 | | +--rw window-size? uint16 375 | | +--rw urgent-pointer? uint16 376 | | +--rw options? uint32 377 | +--rw udp-acl {udp-acl}? 378 | | +--rw length? uint16 379 | +--rw icmp-acl {icmp-acl}? 380 | | +--rw type? uint8 381 | | +--rw code? uint8 382 | | +--rw rest-of-header? uint32 383 | +--rw any-acl! {any-acl}? 384 +--rw actions 385 | +--rw (packet-handling)? 386 | | +--:(deny) 387 | | | +--rw deny? empty 388 | | +--:(permit) 389 | | +--rw permit? empty 390 | +--rw logging? boolean 391 +--ro ace-oper-data 392 +--ro match-counter? yang:counter64 394 4. ACL YANG Models 396 4.1. IETF Access Control List module 398 "ietf-access-control-list" is the standard top level module for 399 access lists. The "access-lists" container stores a list of "acl". 400 Each "acl" has information identifying the access list by a 401 name("acl-name") and a list("access-list-entries") of rules 402 associated with the "acl-name". Each of the entries in the 403 list("access-list-entries"), indexed by the string "rule-name", has 404 containers defining "matches" and "actions". 406 The "matches" define criteria used to identify patterns in "ietf- 407 packet-fields". The "actions" define behavior to undertake once a 408 "match" has been identified. In addition to permit and deny for 409 actions, a logging option allows for a match to be logged that can be 410 used to determine which rule was matched upon. 412 file "ietf-access-control-list@2017-06-16.yang" 414 module ietf-access-control-list { 415 namespace "urn:ietf:params:xml:ns:yang:ietf-access-control-list"; 416 prefix acl; 417 import ietf-yang-types { 418 prefix yang; 419 } 420 import ietf-packet-fields { 421 prefix packet-fields; 422 } 423 organization 424 "IETF NETMOD (NETCONF Data Modeling Language) 425 Working Group"; 427 contact 428 "WG Web: http://tools.ietf.org/wg/netmod/ 429 WG List: netmod@ietf.org 430 Editor: Dean Bogdanovic 431 ivandean@gmail.com 432 Editor: Mahesh Jethanandani 433 mjethanandani@gmail.com 434 Editor: Lisa Huang 435 lyihuang16@gmail.com 436 Editor: Sonal Agarwal 437 agarwaso@cisco.com 438 Editor: Dana Blair 439 dblair@cisco.com"; 441 description 442 "This YANG module defines a component that describing the 443 configuration of Access Control Lists (ACLs). 444 Copyright (c) 2016 IETF Trust and the persons identified as 445 the document authors. All rights reserved. 446 Redistribution and use in source and binary forms, with or 447 without modification, is permitted pursuant to, and subject 448 to the license terms contained in, the Simplified BSD 449 License set forth in Section 4.c of the IETF Trust's Legal 450 Provisions Relating to IETF Documents 451 (http://trustee.ietf.org/license-info). 452 This version of this YANG module is part of RFC XXXX; see 453 the RFC itself for full legal notices."; 455 revision 2017-06-16 { 456 description 457 "Added feature and identity statements for different types 458 of rule matches. Split the matching rules based on the 459 feature statement and added a must statement within 460 each container."; 461 reference 462 "RFC XXX: Network Access Control List (ACL) YANG Data Model."; 463 } 465 revision 2016-10-12 { 466 description 467 "Base model for Network Access Control List (ACL)."; 468 reference 469 "RFC XXXX: Network Access Control List (ACL) 470 YANG Data Model"; 471 } 473 /* 474 * Identities 475 */ 476 identity acl-base { 477 description 478 "Base Access Control List type for all Access Control List type 479 identifiers."; 481 } 483 identity ipv4-acl { 484 base acl:acl-base; 485 description 486 "ACL that primarily matches on fields from the IPv4 header 487 (e.g. IPv4 destination address) and layer 4 headers (e.g. TCP 488 destination port). An acl of type ipv4-acl does not contain 489 matches on fields in the ethernet header or the IPv6 header."; 490 } 492 identity ipv6-acl { 493 base acl:acl-base; 494 description 495 "ACL that primarily matches on fields from the IPv6 header 496 (e.g. IPv6 destination address) and layer 4 headers (e.g. TCP 497 destination port). An acl of type ipv6-acl does not contain 498 matches on fields in the ethernet header or the IPv4 header."; 499 } 501 identity eth-acl { 502 base acl:acl-base; 503 description 504 "ACL that primarily matches on fields in the ethernet header, 505 like 10/100/1000baseT or WiFi Access Control List. An acl of 506 type eth-acl does not contain matches on fields in the IPv4 507 header, IPv6 header or layer 4 headers."; 508 } 510 identity mixed-l2-l3-ipv4-acl { 511 base "acl:acl-base"; 513 description 514 "ACL that contains a mix of entries that 515 primarily match on fields in ethernet headers, 516 entries that primarily match on IPv4 headers. 517 Matching on layer 4 header fields may also exist in the 518 list."; 519 } 521 identity mixed-l2-l3-ipv6-acl { 522 base "acl:acl-base"; 524 description 525 "ACL that contains a mix of entries that 526 primarily match on fields in ethernet headers, entries 527 that primarily match on fields in IPv6 headers. Matching on 528 layer 4 header fields may also exist in the list."; 530 } 532 identity mixed-l2-l3-ipv4-ipv6-acl { 533 base "acl:acl-base"; 535 description 536 "ACL that contains a mix of entries that 537 primarily match on fields in ethernet headers, entries 538 that primarily match on fields in IPv4 headers, and entries 539 that primarily match on fields in IPv6 headers. Matching on 540 layer 4 header fields may also exist in the list."; 541 } 543 identity any-acl { 544 base "acl:acl-base"; 546 description 547 "ACL that can contain any pattern to match upon"; 548 } 550 /* 551 * Features 552 */ 553 feature l2-acl { 554 description 555 "Layer 2 ACL supported"; 556 } 558 feature ipv4-acl { 559 description 560 "Layer 3 IPv4 ACL supported"; 561 } 563 feature ipv6-acl { 564 description 565 "Layer 3 IPv6 ACL supported"; 566 } 568 feature mixed-ipv4-acl { 569 description 570 "Layer 2 and Layer 3 IPv4 ACL supported"; 571 } 573 feature mixed-ipv6-acl { 574 description 575 "Layer 2 and Layer 3 IPv6 ACL supported"; 576 } 577 feature l2-l3-ipv4-ipv6-acl { 578 description 579 "Layer 2 and any Layer 3 ACL supported."; 580 } 582 feature tcp-acl { 583 description 584 "TCP header ACL supported."; 585 } 587 feature udp-acl { 588 description 589 "UDP header ACL supported."; 590 } 592 feature icmp-acl { 593 description 594 "ICMP header ACL supported."; 595 } 597 feature any-acl { 598 description 599 "ACL for any pattern."; 600 } 602 /* 603 * Typedefs 604 */ 605 typedef acl-type { 606 type identityref { 607 base acl-base; 608 } 609 description 610 "This type is used to refer to an Access Control List 611 (ACL) type"; 612 } 614 typedef access-control-list-ref { 615 type leafref { 616 path "/access-lists/acl/acl-name"; 617 } 618 description 619 "This type is used by data models that need to reference an 620 Access Control List"; 621 } 623 /* 624 * Configuration data nodes 625 */ 626 container access-lists { 627 description 628 "This is a top level container for Access Control Lists. 629 It can have one or more Access Control Lists."; 630 list acl { 631 key "acl-type acl-name"; 632 description 633 "An Access Control List(ACL) is an ordered list of 634 Access List Entries (ACE). Each Access Control Entry has a 635 list of match criteria and a list of actions. 636 Since there are several kinds of Access Control Lists 637 implemented with different attributes for 638 different vendors, this 639 model accommodates customizing Access Control Lists for 640 each kind and for each vendor."; 641 leaf acl-name { 642 type string; 643 description 644 "The name of access-list. A device MAY restrict the length 645 and value of this name, possibly space and special 646 characters are not allowed."; 647 } 648 leaf acl-type { 649 type acl-type; 650 description 651 "Type of access control list. Indicates the primary intended 652 type of match criteria (e.g. ethernet, IPv4, IPv6, mixed, 653 etc) used in the list instance."; 654 } 655 container acl-oper-data { 656 config false; 657 description 658 "Overall Access Control List operational data"; 659 } 660 container access-list-entries { 661 description 662 "The access-list-entries container contains 663 a list of access-list-entries(ACE)."; 664 list ace { 665 key "rule-name"; 666 ordered-by user; 667 description 668 "List of access list entries(ACE)"; 669 leaf rule-name { 670 type string; 671 description 672 "A unique name identifying this Access List 673 Entry(ACE)."; 674 } 676 container matches { 677 description 678 "The rules in this set determine what fields will be 679 matched upon before any action is taken on them. 680 The rules are selected based on the feature set 681 defined by the server and the acl-type defined."; 683 container l2-acl { 684 if-feature l2-acl; 685 must "../../../../acl-type = 'eth-acl'"; 686 uses packet-fields:acl-eth-header-fields; 687 description 688 "Rule set for L2 ACL."; 689 } 691 container ipv4-acl { 692 if-feature ipv4-acl; 693 must "../../../../acl-type = 'ipv4-acl'"; 694 uses packet-fields:acl-ip-header-fields; 695 uses packet-fields:acl-ipv4-header-fields; 696 description 697 "Rule set that supports IPv4 headers."; 698 } 700 container ipv6-acl { 701 if-feature ipv6-acl; 702 must "../../../../acl-type = 'ipv6-acl'"; 703 uses packet-fields:acl-ip-header-fields; 704 uses packet-fields:acl-ipv6-header-fields; 705 description 706 "Rule set that supports IPv6 headers."; 707 } 709 container l2-l3-ipv4-acl { 710 if-feature mixed-ipv4-acl; 711 must "../../../../acl-type = 'mixed-l2-l3-ipv4-acl'"; 712 uses packet-fields:acl-eth-header-fields; 713 uses packet-fields:acl-ip-header-fields; 714 uses packet-fields:acl-ipv4-header-fields; 715 description 716 "Rule set that is a logical AND (&&) of l2 717 and ipv4 headers."; 718 } 720 container l2-l3-ipv6-acl { 721 if-feature mixed-ipv6-acl; 722 must "../../../../acl-type = 'mixed-l2-l3-ipv6-acl'"; 723 uses packet-fields:acl-eth-header-fields; 724 uses packet-fields:acl-ip-header-fields; 725 uses packet-fields:acl-ipv6-header-fields; 726 description 727 "Rule set that is a logical AND (&&) of L2 728 && IPv6 headers."; 729 } 731 container l2-l3-ipv4-ipv6-acl { 732 if-feature l2-l3-ipv4-ipv6-acl; 733 must "../../../../acl-type = 'mixed-l2-l3-ipv4-ipv6-acl'"; 734 uses packet-fields:acl-eth-header-fields; 735 uses packet-fields:acl-ip-header-fields; 736 uses packet-fields:acl-ipv4-header-fields; 737 uses packet-fields:acl-ipv6-header-fields; 738 description 739 "Rule set that is a logical AND (&&) of L2 740 && IPv4 && IPv6 headers."; 741 } 743 container tcp-acl { 744 if-feature tcp-acl; 745 uses packet-fields:acl-tcp-header-fields; 746 description 747 "Rule set that defines TCP headers."; 748 } 750 container udp-acl { 751 if-feature udp-acl; 752 uses packet-fields:acl-udp-header-fields; 753 description 754 "Rule set that defines UDP headers."; 755 } 757 container icmp-acl { 758 if-feature icmp-acl; 759 uses packet-fields:acl-icmp-header-fields; 760 description 761 "Rule set that defines ICMP headers."; 762 } 764 container any-acl { 765 if-feature any-acl; 766 must "../../../../acl-type = 'any-acl'"; 767 presence "Matches any"; 768 description 769 "Rule set that allows for a any ACL."; 770 } 771 } 773 container actions { 774 description 775 "Definitions of action criteria for this Access List 776 Entry."; 777 choice packet-handling { 778 default "deny"; 779 description 780 "Packet handling action."; 781 case deny { 782 leaf deny { 783 type empty; 784 description 785 "Deny action."; 786 } 787 } 788 case permit { 789 leaf permit { 790 type empty; 791 description 792 "Permit action."; 793 } 794 } 795 } 796 leaf logging { 797 type boolean; 798 description 799 "Log the rule on which the match occurred. 800 Setting the value to true enables logging, 801 whereas setting the value to false disables it."; 802 } 803 } 804 /* 805 * Operational state data nodes 806 */ 807 container ace-oper-data { 808 config false; 809 description 810 "Operational data for this Access List Entry."; 811 leaf match-counter { 812 type yang:counter64; 813 description 814 "Number of matches for this Access List Entry"; 815 } 816 } 818 } 819 } 820 } 821 } 822 } 824 826 4.2. IETF Packet Fields module 828 The packet fields module defines the necessary groups for matching on 829 fields in the packet including ethernet, ipv4, ipv6, and transport 830 layer fields. The 'acl-type' node determines which of these fields 831 get included for any given ACL with the exception of TCP, UDP and 832 ICMP header fields. Those fields can be used in conjunction with any 833 of the above layer 2 or layer 3 fields. 835 Since the number of match criteria is very large, the base draft does 836 not include these directly but references them by "uses" to keep the 837 base module simple. In case more match conditions are needed, those 838 can be added by augmenting choices within container "matches" in 839 ietf-access-control-list.yang model. 841 file "ietf-packet-fields@2017-06-16.yang" 843 module ietf-packet-fields { 844 namespace "urn:ietf:params:xml:ns:yang:ietf-packet-fields"; 845 prefix packet-fields; 847 import ietf-inet-types { 848 prefix inet; 849 } 851 import ietf-yang-types { 852 prefix yang; 853 } 855 organization 856 "IETF NETMOD (NETCONF Data Modeling Language) Working 857 Group"; 859 contact 860 "WG Web: http://tools.ietf.org/wg/netmod/ 861 WG List: netmod@ietf.org 863 Editor: Dean Bogdanovic 864 ivandean@gmail.com 865 Editor: Mahesh Jethanandani 866 mahesh@cisco.com 867 Editor: Lisa Huang 868 lyihuang16@gmail.com 869 Editor: Sonal Agarwal 870 agarwaso@cisco.com 871 Editor: Dana Blair 872 dblair@cisco.com"; 874 description 875 "This YANG module defines groupings that are used by 876 ietf-access-control-list YANG module. Their usage is not 877 limited to ietf-access-control-list and can be 878 used anywhere as applicable. 879 Copyright (c) 2016 IETF Trust and the persons identified as 880 the document authors. All rights reserved. 881 Redistribution and use in source and binary forms, with or 882 without modification, is permitted pursuant to, and subject 884 to the license terms contained in, the Simplified BSD 885 License set forth in Section 4.c of the IETF Trust's Legal 886 Provisions Relating to IETF Documents 887 (http://trustee.ietf.org/license-info). 888 This version of this YANG module is part of RFC XXXX; see 889 the RFC itself for full legal notices."; 891 revision 2017-06-16 { 892 description 893 "Added header fields for TCP, UDP, and ICMP."; 894 reference 895 "RFC XXX: Network Access Control List (ACL) YANG Data Model."; 896 } 898 revision 2016-10-12 { 899 description 900 "Initial version of packet fields used by 901 ietf-access-control-list"; 902 reference 903 "RFC XXXX: Network Access Control List (ACL) 904 YANG Data Model"; 905 } 907 grouping acl-transport-header-fields { 908 description 909 "Transport header fields"; 910 container source-port-range { 911 presence "Enables setting source port range"; 912 description 913 "Inclusive range representing source ports to be used. 915 When only lower-port is present, it represents a single port."; 916 leaf lower-port { 917 type inet:port-number; 918 mandatory true; 919 description 920 "Lower boundary for port."; 921 } 922 leaf upper-port { 923 type inet:port-number; 924 must ". >= ../lower-port" { 925 error-message 926 "The upper-port must be greater than or equal 927 to lower-port"; 928 } 929 description 930 "Upper boundary for port . If existing, the upper port 931 must be greater or equal to lower-port."; 932 } 933 } 935 container destination-port-range { 936 presence "Enables setting destination port range"; 937 description 938 "Inclusive range representing destination ports to be used. 939 When only lower-port is present, it represents a single 940 port."; 942 leaf lower-port { 943 type inet:port-number; 944 mandatory true; 945 description 947 "Lower boundary for port."; 948 } 949 leaf upper-port { 950 type inet:port-number; 951 must ". >= ../lower-port" { 952 error-message 953 "The upper-port must be greater than or equal 954 to lower-port"; 955 } 957 description 958 "Upper boundary for port. If existing, the upper port must 959 be greater or equal to lower-port"; 960 } 961 } 962 } 963 grouping acl-ip-header-fields { 964 description 965 "IP header fields common to ipv4 and ipv6"; 966 reference 967 "RFC 791."; 969 leaf tos { 970 type uint8; 971 description 972 "Also known as Traffic Class in IPv6. The Type of Service (TOS) 973 provides an indication of the abstract parameters of the 974 quality of service desired."; 975 reference 976 "RFC 719, RFC 2460"; 977 } 979 leaf length { 980 type uint16; 981 description 982 "In IPv4 header field, this field is known as the Total Length. 983 Total Length is the length of the datagram, measured in octets, 984 including internet header and data. 986 In IPv6 header field, this field is known as the Payload 987 Length, the length of the IPv6 payload, i.e. the rest of 988 the packet following the IPv6 header, in octets."; 989 reference 990 "RFC 719, RFC 2460"; 991 } 993 leaf ttl { 994 type uint8; 995 description 996 "This field indicates the maximum time the datagram is allowed 997 to remain in the internet system. If this field contains the 998 value zero, then the datagram must be destroyed. 1000 In IPv6, this field is known as the Hop Limit."; 1001 reference "RFC 719, RFC 2460"; 1002 } 1004 leaf protocol { 1005 type uint8; 1006 description 1007 "Internet Protocol number."; 1008 } 1009 uses acl-transport-header-fields; 1010 } 1011 grouping acl-ipv4-header-fields { 1012 description 1013 "Fields in IPv4 header."; 1015 leaf ihl { 1016 type uint8 { 1017 range "5..60"; 1018 } 1019 description 1020 "An IPv4 header field, the Internet Header Length (IHL) is 1021 the length of the internet header in 32 bit words, and 1022 thus points to the beginning of the data. Note that the 1023 minimum value for a correct header is 5."; 1024 } 1026 leaf flags { 1027 type bits { 1028 bit reserved { 1029 position 0; 1030 description 1031 "Reserved. Must be zero."; 1032 } 1033 bit fragment { 1034 position 1; 1035 description 1036 "Setting value to 0 indicates may fragment, while setting 1037 the value to 1 indicates do not fragment."; 1038 } 1039 bit more { 1040 position 2; 1041 description 1042 "Setting the value to 0 indicates this is the last fragment, 1043 and setting the value to 1 indicates more fragments are 1044 coming."; 1045 } 1046 } 1047 description 1048 "Bit definitions for the flags field in IPv4 header."; 1049 } 1051 leaf offset { 1052 type uint16 { 1053 range "20..65535"; 1054 } 1055 description 1056 "The fragment offset is measured in units of 8 octets (64 bits). 1057 The first fragment has offset zero. The length is 13 bits"; 1058 } 1059 leaf identification { 1060 type uint16; 1061 description 1062 "An identifying value assigned by the sender to aid in 1063 assembling the fragments of a datagram."; 1064 } 1066 leaf destination-ipv4-network { 1067 type inet:ipv4-prefix; 1068 description 1069 "Destination IPv4 address prefix."; 1070 } 1071 leaf source-ipv4-network { 1072 type inet:ipv4-prefix; 1073 description 1074 "Source IPv4 address prefix."; 1075 } 1076 } 1078 grouping acl-ipv6-header-fields { 1079 description 1080 "Fields in IPv6 header"; 1082 leaf next-header { 1083 type uint8; 1084 description 1085 "Identifies the type of header immediately following the 1086 IPv6 header. Uses the same values as the IPv4 Protocol 1087 field."; 1088 reference 1089 "RFC 2460"; 1090 } 1092 leaf destination-ipv6-network { 1093 type inet:ipv6-prefix; 1094 description 1095 "Destination IPv6 address prefix."; 1096 } 1098 leaf source-ipv6-network { 1099 type inet:ipv6-prefix; 1100 description 1101 "Source IPv6 address prefix."; 1102 } 1104 leaf flow-label { 1105 type inet:ipv6-flow-label; 1106 description 1107 "IPv6 Flow label."; 1108 } 1109 reference 1110 "RFC 4291: IP Version 6 Addressing Architecture 1111 RFC 4007: IPv6 Scoped Address Architecture 1112 RFC 5952: A Recommendation for IPv6 Address Text 1113 Representation"; 1114 } 1116 grouping acl-eth-header-fields { 1117 description 1118 "Fields in Ethernet header."; 1120 leaf destination-mac-address { 1121 type yang:mac-address; 1122 description 1123 "Destination IEEE 802 MAC address."; 1124 } 1125 leaf destination-mac-address-mask { 1126 type yang:mac-address; 1127 description 1128 "Destination IEEE 802 MAC address mask."; 1129 } 1130 leaf source-mac-address { 1131 type yang:mac-address; 1132 description 1133 "Source IEEE 802 MAC address."; 1134 } 1135 leaf source-mac-address-mask { 1136 type yang:mac-address; 1137 description 1138 "Source IEEE 802 MAC address mask."; 1139 } 1140 leaf ether-type { 1141 type string { 1142 pattern '[0-9a-fA-F]{4}'; 1143 } 1144 description 1145 "The Ethernet Type (or Length) value represented 1146 in the canonical order defined by IEEE 802. 1147 The canonical representation uses lowercase 1148 characters. 1150 Note: This is not the most ideal way to define 1151 ether-types. Ether-types are well known types 1152 and are registered with RAC in IEEE. So they 1153 should well defined types with values. For now 1154 this model is defining it as a string. 1156 There is a note out to IEEE that needs to be 1157 turned into a liaison statement asking them to 1158 define all ether-types for the industry to use."; 1159 reference 1160 "IEEE 802-2014 Clause 9.2"; 1161 } 1162 reference 1163 "IEEE 802: IEEE Standard for Local and Metropolitan 1164 Area Networks: Overview and Architecture."; 1165 } 1167 grouping acl-tcp-header-fields { 1168 description 1169 "Collection of TCP header fields that can be used to 1170 setup a match filter."; 1172 leaf sequence-number { 1173 type uint32; 1174 description 1175 "Sequence number that appears in the packet."; 1176 } 1178 leaf acknowledgement-number { 1179 type uint32; 1180 description 1181 "The acknowledgement number that appears in the 1182 packet."; 1183 } 1185 leaf data-offset { 1186 type uint8 { 1187 range "5..15"; 1188 } 1189 description 1190 "Specifies the size of the TCP header in 32-bit 1191 words. The minimum size header is 5 words and 1192 the maximum is 15 words thus giving the minimum 1193 size of 20 bytes and maximum of 60 bytes, 1194 allowing for up to 40 bytes of options in the 1195 header."; 1196 } 1198 leaf reserved { 1199 type uint8; 1200 description 1201 "Reserved for future use."; 1202 } 1203 leaf flags { 1204 type uint16; 1205 description 1206 "Also known as Control Bits. Contains 9 1-bit flags."; 1207 } 1209 leaf window-size { 1210 type uint16; 1211 description 1212 "The size of the receive window, which specifies 1213 the number of window size units (by default, 1214 bytes) (beyond the segment identified by the 1215 sequence number in the acknowledgment field) 1216 that the sender of this segment is currently 1217 willing to receive."; 1218 } 1220 leaf urgent-pointer { 1221 type uint16; 1222 description 1223 "This field s an offset from the sequence number 1224 indicating the last urgent data byte."; 1225 } 1227 leaf options { 1228 type uint32; 1229 description 1230 "The length of this field is determined by the 1231 data offset field. Options have up to three 1232 fields: Option-Kind (1 byte), Option-Length 1233 (1 byte), Option-Data (variable). The Option-Kind 1234 field indicates the type of option, and is the 1235 only field that is not optional. Depending on 1236 what kind of option we are dealing with, 1237 the next two fields may be set: the Option-Length 1238 field indicates the total length of the option, 1239 and the Option-Data field contains the value of 1240 the option, if applicable."; 1241 } 1242 } 1244 grouping acl-udp-header-fields { 1245 description 1246 "Collection of UDP header fields that can be used 1247 to setup a match filter."; 1249 leaf length { 1250 type uint16; 1251 description 1252 "A field that specifies the length in bytes of 1253 the UDP header and UDP data. The minimum 1254 length is 8 bytes because that is the length of 1255 the header. The field size sets a theoretical 1256 limit of 65,535 bytes (8 byte header + 65,527 1257 bytes of data) for a UDP datagram. However the 1258 actual limit for the data length, which is 1259 imposed by the underlying IPv4 protocol, is 1260 65,507 bytes (65,535 minus 8 byte UDP header 1261 minus 20 byte IP header). 1263 In IPv6 jumbograms it is possible to have 1264 UDP packets of size greater than 65,535 bytes. 1265 RFC 2675 specifies that the length field is set 1266 to zero if the length of the UDP header plus 1267 UDP data is greater than 65,535."; 1268 } 1269 } 1271 grouping acl-icmp-header-fields { 1272 description 1273 "Collection of ICMP header fields that can be 1274 used to setup a match filter."; 1276 leaf type { 1277 type uint8; 1278 description 1279 "Also known as Control messages."; 1280 reference "RFC 792"; 1281 } 1283 leaf code { 1284 type uint8; 1285 description 1286 "ICMP subtype. Also known as Control messages."; 1287 } 1289 leaf rest-of-header { 1290 type uint32; 1291 description 1292 "Four-bytes field, contents vary based on the 1293 ICMP type and code."; 1294 } 1295 } 1296 } 1298 1299 4.3. An ACL Example 1301 Requirement: Deny tcp traffic from 10.10.10.1/24, destined to 1302 11.11.11.1/24. 1304 Here is the acl configuration xml for this Access Control List: 1306 1307 1308 1310 1311 sample-ipv4-acl 1312 ipv4 1313 1314 1315 rule1 1316 1317 1318 10.10.10.1/24 1319 1320 1321 11.11.11.1/24 1322 1323 1324 1325 1326 1327 1328 tcp 1329 1330 1331 1332 1333 1334 1336 The acl and aces can be described in CLI as the following: 1338 access-list ipv4 sample-ipv4-acl 1339 deny tcp 10.10.10.1/24 11.11.11.1/24 1341 4.4. Port Range Usage Example 1343 When a lower-port and an upper-port are both present, it represents a 1344 range between lower-port and upper-port with both the lower-port and 1345 upper-port are included. When only a lower-port presents, it 1346 represents a single port. 1348 With the follow XML snippet: 1350 1351 16384 1352 16387 1353 1355 This represents source ports 16384,16385, 16386, and 16387. 1357 With the follow XML snippet: 1359 1360 16384 1361 65535 1362 1364 This represents source ports greater than/equal to 16384 and less 1365 than equal to 65535. 1367 With the follow XML snippet: 1369 1370 21 1371 1373 This represents port 21. 1375 5. Security Considerations 1377 The YANG module defined in this memo is designed to be accessed via 1378 the NETCONF [RFC6241]. The lowest NETCONF layer is the secure 1379 transport layer and the mandatory-to-implement secure transport is 1380 SSH [RFC6242]. The NETCONF Access Control Model ( NACM [RFC6536]) 1381 provides the means to restrict access for particular NETCONF users to 1382 a pre-configured subset of all available NETCONF protocol operations 1383 and content. 1385 There are a number of data nodes defined in the YANG module which are 1386 writable/creatable/deletable (i.e., config true, which is the 1387 default). These data nodes may be considered sensitive or vulnerable 1388 in some network environments. Write operations (e.g., ) 1389 to these data nodes without proper protection can have a negative 1390 effect on network operations. 1392 These are the subtrees and data nodes and their sensitivity/ 1393 vulnerability: 1395 /access-lists/acl/access-list-entries: This list specifies all the 1396 configured access list entries on the device. Unauthorized write 1397 access to this list can allow intruders to access and control the 1398 system. Unauthorized read access to this list can allow intruders to 1399 spoof packets with authorized addresses thereby compromising the 1400 system. 1402 6. IANA Considerations 1404 This document registers a URI in the IETF XML registry [RFC3688]. 1405 Following the format in RFC 3688, the following registration is 1406 requested to be made: 1408 URI: urn:ietf:params:xml:ns:yang:ietf-access-control-list 1410 URI: urn:ietf:params:xml:ns:yang:ietf-packet-fields 1412 Registrant Contact: The IESG. 1414 XML: N/A, the requested URI is an XML namespace. 1416 This document registers a YANG module in the YANG Module Names 1417 registry [RFC6020]. 1419 name: ietf-access-control-list namespace: 1420 urn:ietf:params:xml:ns:yang:ietf-access-control-list prefix: ietf-acl 1421 reference: RFC XXXX 1423 name: ietf-packet-fields namespace: urn:ietf:params:xml:ns:yang:ietf- 1424 packet-fields prefix: ietf-packet-fields reference: RFC XXXX 1426 7. Acknowledgements 1428 Alex Clemm, Andy Bierman and Lisa Huang started it by sketching out 1429 an initial IETF draft in several past IETF meetings. That draft 1430 included an ACL YANG model structure and a rich set of match filters, 1431 and acknowledged contributions by Louis Fourie, Dana Blair, Tula 1432 Kraiser, Patrick Gili, George Serpa, Martin Bjorklund, Kent Watsen, 1433 and Phil Shafer. Many people have reviewed the various earlier 1434 drafts that made the draft went into IETF charter. 1436 Dean Bogdanovic, Kiran Agrahara Sreenivasa, Lisa Huang, and Dana 1437 Blair each evaluated the YANG model in previous draft separately and 1438 then work together, to created a new ACL draft that can be supported 1439 by different vendors. The new draft removes vendor specific 1440 features, and gives examples to allow vendors to extend in their own 1441 proprietary ACL. The earlier draft was superseded with the new one 1442 that received more participation from many vendors. 1444 Authors would like to thank Jason Sterne, Lada Lhotka, Juergen 1445 Schoenwalder, and David Bannister for their review of and suggestions 1446 to the draft. 1448 8. Open Issues 1450 o The current model does not support the concept of "containers" 1451 used to contain multiple addresses per rule entry. 1453 o The current model defines 'any' rule as a presence container, 1454 allowing a user to define any 'any' rule. 1456 o The model defines 'ether-type' node as a string. Ideally, this 1457 should be a well defined list of all Ethernet Types assigned by 1458 IEEE. 1460 o Should this draft include route-policy definition as defined in 1461 draft-ietf-rtgwg-policy-model? 1463 9. References 1465 9.1. Normative References 1467 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1468 DOI 10.17487/RFC3688, January 2004, 1469 . 1471 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1472 the Network Configuration Protocol (NETCONF)", RFC 6020, 1473 DOI 10.17487/RFC6020, October 2010, 1474 . 1476 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1477 and A. Bierman, Ed., "Network Configuration Protocol 1478 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1479 . 1481 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1482 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1483 . 1485 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1486 Protocol (NETCONF) Access Control Model", RFC 6536, 1487 DOI 10.17487/RFC6536, March 2012, 1488 . 1490 9.2. Informative References 1492 [I-D.ietf-netmod-yang-tree-diagrams] 1493 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 1494 ietf-netmod-yang-tree-diagrams-00 (work in progress), June 1495 2017. 1497 [RFC5101] Claise, B., Ed., "Specification of the IP Flow Information 1498 Export (IPFIX) Protocol for the Exchange of IP Traffic 1499 Flow Information", RFC 5101, DOI 10.17487/RFC5101, January 1500 2008, . 1502 Appendix A. Extending ACL model examples 1504 A.1. Example of extending existing model for route filtering 1506 With proposed modular design, it is easy to extend the model with 1507 other features. Those features can be standard features, like route 1508 filters. Route filters match on specific IP addresses or ranges of 1509 prefixes. Much like ACLs, they include some match criteria and 1510 corresponding match action(s). For that reason, it is very simple to 1511 extend existing ACL model with route filtering. The combination of a 1512 route prefix and prefix length along with the type of match 1513 determines how route filters are evaluated against incoming routes. 1514 Different vendors have different match types and in this model we are 1515 using only ones that are common across all vendors participating in 1516 this draft. As in this example, the base ACL model can be extended 1517 with company proprietary extensions, described in the next section. 1519 module: example-ext-route-filter 1520 augment /ietf-acl:access-lists/ietf-acl:acl/ 1521 ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches: 1522 +--rw (route-prefix)? 1523 +--:(range) 1524 +--rw (ipv4-range)? 1525 | +--:(v4-lower-bound) 1526 | | +--rw v4-lower-bound? inet:ipv4-prefix 1527 | +--:(v4-upper-bound) 1528 | +--rw v4-upper-bound? inet:ipv4-prefix 1529 +--rw (ipv6-range)? 1530 +--:(v6-lower-bound) 1531 | +--rw v6-lower-bound? inet:ipv6-prefix 1532 +--:(v6-upper-bound) 1533 +--rw v6-upper-bound? inet:ipv6-prefix 1535 file "example-ext-route-filter@2016-10-12.yang" 1536 module example-ext-route-filter { 1537 namespace "urn:ietf:params:xml:ns:yang:example-ext-route-filter"; 1538 prefix example-ext-route-filter; 1539 import ietf-inet-types { 1540 prefix "inet"; 1541 } 1542 import ietf-access-control-list { 1543 prefix "ietf-acl"; 1544 } 1546 organization 1547 "Route model group."; 1549 contact 1550 "abc@abc.com"; 1552 description " 1553 This module describes route filter as a collection of 1554 match prefixes. When specifying a match prefix, you 1555 can specify an exact match with a particular route or 1556 a less precise match. You can configure either a 1557 common action that applies to the entire list or an 1558 action associated with each prefix. 1559 "; 1560 revision 2016-10-12 { 1561 description 1562 "Creating Route-Filter extension model based on 1563 ietf-access-control-list model"; 1564 reference " "; 1565 } 1566 augment "/ietf-acl:access-lists/ietf-acl:acl/" 1567 + "ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches"{ 1568 description " 1569 This module augments the matches container in the ietf-acl 1570 module with route filter specific actions 1571 "; 1572 choice route-prefix{ 1573 description "Define route filter match criteria"; 1574 case range { 1575 description 1576 "Route falls between the lower prefix/prefix-length 1577 and the upperprefix/prefix-length."; 1578 choice ipv4-range { 1579 description "Defines the IPv4 prefix range"; 1580 leaf v4-lower-bound { 1581 type inet:ipv4-prefix; 1582 description 1583 "Defines the lower IPv4 prefix/prefix length"; 1584 } 1585 leaf v4-upper-bound { 1586 type inet:ipv4-prefix; 1587 description 1588 "Defines the upper IPv4 prefix/prefix length"; 1589 } 1590 } 1591 choice ipv6-range { 1592 description "Defines the IPv6 prefix/prefix range"; 1593 leaf v6-lower-bound { 1594 type inet:ipv6-prefix; 1595 description 1596 "Defines the lower IPv6 prefix/prefix length"; 1597 } 1598 leaf v6-upper-bound { 1599 type inet:ipv6-prefix; 1600 description 1601 "Defines the upper IPv6 prefix/prefix length"; 1602 } 1603 } 1604 } 1605 } 1606 } 1607 } 1609 A.2. A company proprietary module example 1611 Access control list typically does not exist in isolation. Instead, 1612 they are associated with a certain scope in which they are applied, 1613 for example, an interface of a set of interfaces. How to attach an 1614 access control list to an interface (or other system artifact) is 1615 outside the scope of this model, as it depends on the specifics of 1616 the system model that is being applied. However, in general, the 1617 general design pattern will involved adding a data node with a 1618 reference, or set of references, to ACLs that are to be applied to 1619 the interface. For this purpose, the type definition "access- 1620 control-list-ref" can be used. 1622 Module "example-newco-acl" is an example of company proprietary model 1623 that augments "ietf-acl" module. It shows how to use 'augment' with 1624 an XPath expression to add additional match criteria, action 1625 criteria, and default actions when no ACE matches found, as well how 1626 to attach an Access Control List to an interface. All these are 1627 company proprietary extensions or system feature extensions. 1628 "example-newco-acl" is just an example and it is expected from 1629 vendors to create their own proprietary models. 1631 The following figure is the tree structure of example-newco-acl. In 1632 this example, /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access- 1633 list-entries/ ietf-acl:ace/ietf-acl:matches are augmented with two 1634 new choices, protocol-payload-choice and metadata. The protocol- 1635 payload-choice uses a grouping with an enumeration of all supported 1636 protocol values. Metadata matches apply to fields associated with 1637 the packet but not in the packet header such as input interface or 1638 overall packet length. In other example, /ietf-acl:access-lists/ 1639 ietf-acl:acl/ietf-acl:access-list-entries/ ietf-acl:ace/ietf- 1640 acl:actions are augmented with new choice of actions. 1642 module: example-newco-acl 1643 augment /ietf-acl:access-lists/ietf-acl:acl/ 1644 ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches: 1645 +--rw vlan-tagged? uint16 1646 +--rw mpls-unicast? uint16 1647 +--rw mpls-multicast? uint16 1648 +--rw ipv4? uint16 1649 +--rw ipv6? uint16 1650 augment /ietf-acl:access-lists/ietf-acl:acl/ 1651 ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches: 1652 +--rw ipv4-ttl? uint8 1653 +--rw ipv4-len? uint16 1654 +--rw ipv4-ihl? uint8 1655 +--rw ipv4-id? uint16 1656 +--rw ipv4-flags? ipv4-flags-type 1657 +--rw ipv4-offset? uint16 1658 augment /ietf-acl:access-lists/ietf-acl:acl/ 1659 ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches: 1660 +--rw (protocol-payload-choice)? 1661 | +--:(protocol-payload) 1662 | +--rw protocol-payload* [value-keyword] 1663 | +--rw value-keyword enumeration 1664 +--rw (metadata)? 1665 +--:(interface-name) 1666 +--rw interface-name* [input-interface] 1667 +--rw input-interface ietf-if:interface-ref 1668 augment /ietf-acl:access-lists/ietf-acl:acl/ 1669 ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:actions: 1670 +--rw (action)? 1671 +--:(count) 1672 | +--rw count? string 1673 +--:(policer) 1674 | +--rw policer? string 1675 +--:(hiearchical-policer) 1676 +--rw hierarchitacl-policer? string 1677 augment /ietf-acl:access-lists/ietf-acl:acl: 1678 +--rw default-actions 1679 +--rw deny? empty 1680 augment /ietf-if:interfaces/ietf-if:interface: 1682 +--rw acl 1683 +--rw acl-name? ietf-acl:access-control-list-ref 1684 +--ro match-counter? yang:counter64 1685 +--rw (direction)? 1686 +--:(in) 1687 | +--rw in? empty 1688 +--:(out) 1689 +--rw out? empty 1690 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:acl-oper-data: 1691 +--ro targets 1692 +--ro (interface)? 1693 +--:(interface-name) 1694 +--ro interface-name* ietf-if:interface-ref 1696 module example-newco-acl { 1698 yang-version 1.1; 1700 namespace "urn:newco:params:xml:ns:yang:example-newco-acl"; 1702 prefix example-newco-acl; 1704 import ietf-access-control-list { 1705 prefix "ietf-acl"; 1706 } 1708 import ietf-interfaces { 1709 prefix "ietf-if"; 1710 } 1712 import ietf-yang-types { 1713 prefix yang; 1714 } 1716 organization 1717 "Newco model group."; 1719 contact 1720 "abc@newco.com"; 1721 description 1722 "This YANG module augment IETF ACL Yang."; 1724 revision 2016-10-12{ 1725 description 1726 "Creating NewCo proprietary extensions to ietf-acl model"; 1727 reference 1728 "RFC XXXX: Network Access Control List (ACL) 1729 YANG Data Model"; 1731 } 1733 typedef known-ether-type { 1734 type enumeration { 1735 enum "ipv4" { 1736 value 2048; // 0x0800 1737 description "Internet Protocol version 4 (IPv4)"; 1738 } 1739 enum "vlan-tagged" { 1740 value 33024; // 0x8100 1741 description 1742 "VLAN-tagged frame (IEEE 802.1Q) & Shortest Path 1743 Bridging IEEE 802.1aq[4]"; 1744 } 1745 enum "ipv6" { 1746 value 34525; // 0x86DD 1747 description "Internet Protocol Version 6 (IPv6)"; 1748 } 1749 enum "mpls-unicast" { 1750 value 34887; // 0x8847 1751 description "MPLS unicast"; 1752 } 1753 enum "mpls-multicast" { 1754 value 34888; // 0x8848 1755 description "MPLS multicast"; 1756 } 1757 } 1758 description "Listing supported Ethertypes"; 1759 } 1761 typedef ipv4-flags-type { 1762 type bits { 1763 bit ipv4-reserved { 1764 position 0; 1765 description "reserved bit"; 1766 } 1767 bit ipv4-DF { 1768 position 1; 1769 description "DF bit"; 1770 } 1771 bit ipv4-MF { 1772 position 2; 1773 description "MF bit"; 1774 } 1775 } 1776 description "IPv4 flag types"; 1777 } 1778 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1779 "ietf-acl:access-list-entries/ietf-acl:ace/" + 1780 "ietf-acl:matches" { 1781 when "ietf-acl:access-lists/ietf-acl:acl/" + 1782 "ietf-acl:acl-type = 'ace-eth'"; 1784 description "additional MAC header matching"; 1786 leaf vlan-tagged { 1787 type uint16; 1788 description "Ethernet frame with VLAN tag"; 1789 } 1791 leaf mpls-unicast { 1792 type uint16; 1793 description "Ethernet frame with MPLS unicast payload"; 1794 } 1796 leaf mpls-multicast { 1797 type uint16; 1798 description "Ethernet frame with MPLS multicast payload"; 1799 } 1801 leaf ipv4 { 1802 type uint16; 1803 description "Ethernet frame with IPv4 unicast payload"; 1804 } 1806 leaf ipv6 { 1807 type uint16; 1808 description "Ethernet frame with IPv4 unicast payload"; 1809 } 1810 } 1811 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1812 "ietf-acl:access-list-entries/ietf-acl:ace/" + 1813 "ietf-acl:matches" { 1814 when "ietf-acl:access-lists/ietf-acl:acl/" + 1815 "ietf-acl:acl-type = 'ipv4-acl'"; 1817 description "additional IP header information"; 1819 leaf ipv4-ttl { 1820 type uint8; 1821 description "time to live of a given packet as 1822 defined in RFC791"; 1823 } 1825 leaf ipv4-len { 1826 type uint16; 1827 description "total packet length as defined in RFC791"; 1828 } 1830 leaf ipv4-ihl { 1831 type uint8 { 1832 range 0..15; 1833 } 1834 description "Internet Header Length in 32 bit words 1835 (see RFC791). Note that while the minimum 1836 value for this field in a packet is 5, 1837 we leave open the possibility here that 1838 the packet has been corrupted."; 1839 } 1841 leaf ipv4-id { 1842 type uint16; 1843 description "Identification as decribed in RFC791"; 1844 } 1846 leaf ipv4-flags { 1847 type ipv4-flags-type; 1848 description "IPv4 flags as defined in RFC791"; 1849 } 1851 leaf ipv4-offset { 1852 type uint16 { 1853 range 0..8191; 1854 } 1855 description "Matches on the packet fragment offset"; 1856 } 1857 } 1859 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1860 "ietf-acl:access-list-entries/ietf-acl:ace/" + 1861 "ietf-acl:matches" { 1862 description "Newco proprietary simple filter matches"; 1863 choice protocol-payload-choice { 1864 description "Newo proprietary payload match condition"; 1865 list protocol-payload { 1866 key value-keyword; 1867 ordered-by user; 1868 description "Match protocol payload"; 1869 uses match-simple-payload-protocol-value; 1870 } 1871 } 1873 choice metadata { 1874 description "Newco proprietary interface match condition"; 1875 list interface-name { 1876 key input-interface; 1877 ordered-by user; 1878 description "Match interface name"; 1879 uses metadata; 1880 } 1881 } 1882 } 1884 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1885 "ietf-acl:access-list-entries/ietf-acl:ace/" + 1886 "ietf-acl:actions" { 1887 description "Newco proprietary simple filter actions"; 1888 choice action { 1889 description ""; 1890 case count { 1891 description "Count the packet in the named counter"; 1892 leaf count { 1893 type string; 1894 description ""; 1895 } 1896 } 1897 case policer { 1898 description "Name of policer to use to rate-limit traffic"; 1899 leaf policer { 1900 type string; 1901 description ""; 1902 } 1903 } 1904 case hiearchical-policer { 1905 description "Name of hierarchical policer to use to 1906 rate-limit traffic"; 1907 leaf hierarchitacl-policer{ 1908 type string; 1909 description ""; 1910 } 1911 } 1912 } 1913 } 1915 augment "/ietf-acl:access-lists/ietf-acl:acl" { 1916 description "Newco proprietary default action"; 1917 container default-actions { 1918 description 1919 "Actions that occur if no access-list entry is matched."; 1920 leaf deny { 1921 type empty; 1922 description ""; 1923 } 1924 } 1925 } 1927 grouping metadata { 1928 description 1929 "Fields associated with a packet which are not in 1930 the header."; 1931 leaf input-interface { 1932 type ietf-if:interface-ref { 1933 require-instance false; 1934 } 1935 description 1936 "Packet was received on this interface"; 1937 } 1938 } 1940 grouping match-simple-payload-protocol-value { 1941 description "Newco proprietary payload"; 1942 leaf value-keyword { 1943 type enumeration { 1944 enum icmp { 1945 description "Internet Control Message Protocol"; 1946 } 1947 enum icmp6 { 1948 description "Internet Control Message Protocol Version 6"; 1949 } 1950 enum range { 1951 description "Range of values"; 1952 } 1953 } 1955 description "(null)"; 1956 } 1957 } 1959 augment "/ietf-if:interfaces/ietf-if:interface" { 1960 description "Apply ACL to interfaces"; 1961 container acl{ 1962 description "ACL related properties."; 1963 leaf acl-name { 1964 type ietf-acl:access-control-list-ref; 1965 description "Access Control List name."; 1966 } 1967 leaf match-counter { 1968 type yang:counter64; 1969 config false; 1970 description 1971 "Total match count for Access Control 1972 List on this interface"; 1973 } 1974 choice direction { 1975 description "Applying ACL in which traffic direction"; 1976 leaf in { 1977 type empty; 1978 description "Inbound traffic"; 1979 } 1980 leaf out { 1981 type empty; 1982 description "Outbound traffic"; 1983 } 1984 } 1985 } 1986 } 1988 augment "/ietf-acl:access-lists/ietf-acl:acl/" + 1989 "ietf-acl:acl-oper-data" { 1990 description 1991 "This is an example on how to apply acl to a target to collect 1992 operational data"; 1993 container targets { 1994 description "To which object is the ACL attached to"; 1995 choice interface { 1996 description 1997 "Access Control List was attached to this interface"; 1998 leaf-list interface-name{ 1999 type ietf-if:interface-ref { 2000 require-instance true; 2001 } 2002 description "Attached to this interface name"; 2003 } 2004 } 2005 } 2006 } 2008 Draft authors expect that different vendors will provide their own 2009 yang models as in the example above, which is the augmentation of the 2010 base model 2012 A.3. Example to augment model with mixed ACL type 2014 As vendors (or IETF) add more features to ACL, the model is easily 2015 augmented. One of such augmentations can be to add support for mixed 2016 type of ACLs, where acl-type-base can be augmented like in example 2017 below: 2019 identity mixed-l3-acl { 2020 base "access-control-list:acl-type-base"; 2021 description "ACL that contains a mix of entries that 2022 primarily match on fields in IPv4 headers and entries 2023 that primarily match on fields in IPv6 headers. 2024 Matching on layer 4 header fields may also exist in the 2025 list. An acl of type mixed-l3-acl does not contain 2026 matches on fields in the ethernet header."; 2027 } 2029 identity mixed-l2-l3-acl { 2030 base "access-control-list:acl-type-base"; 2031 description "ACL that contains a mix of entries that 2032 primarily match on fields in ethernet headers, entries 2033 that primarily match on fields in IPv4 headers, 2034 and entries that primarily match on fields in IPv6 2035 headers. Matching on layer 4 header fields may also 2036 exist in the list."; 2037 } 2039 A.4. Linux nftables 2041 As Linux platform is becoming more popular as networking platform, 2042 the Linux data model is changing. Previously ACLs in Linux were 2043 highly protocol specific and different utilities were used (iptables, 2044 ip6tables, arptables, ebtables), so each one had separate data model. 2045 Recently, this has changed and a single utility, nftables, has been 2046 developed. With a single application, it has a single data model for 2047 filewall filters and it follows very similarly to the ietf-access- 2048 control list module proposed in this draft. The nftables support 2049 input and output ACEs and each ACE can be defined with match and 2050 action. 2052 The example in Section 4.3 can be configured using nftable tool as 2053 below. 2055 nft add table ip filter 2056 nft add chain filter input 2057 nft add rule ip filter input ip protocol tcp ip saddr \ 2058 10.10.10.1/24 drop 2060 The configuration entries added in nftable would be. 2062 table ip filter { 2063 chain input { 2064 ip protocol tcp ip saddr 10.10.10.1/24 drop 2065 } 2066 } 2068 We can see that there are many similarities between Linux nftables 2069 and IETF ACL YANG data models and its extension models. It should be 2070 fairly easy to do translation between ACL YANG model described in 2071 this draft and Linux nftables. 2073 Authors' Addresses 2075 Dean Bogdanovic 2076 Volta Networks 2078 Email: ivandean@gmail.com 2080 Mahesh Jethanandani 2081 Cisco Systems, Inc 2083 Email: mjethanandani@gmail.com 2085 Lisa Huang 2086 General Electric 2088 Email: lyihuang16@gmail.com 2090 Sonal Agarwal 2091 Cisco Systems, Inc. 2093 Email: agarwaso@cisco.com 2095 Dana 2096 Cisco Systems, INc 2098 Email: dblair@cisco.com