idnits 2.17.1 draft-ietf-netmod-acl-model-10.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 31 instances of too long lines in the document, the longest one being 37 characters in excess of 72. == There are 7 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 391: '...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 231 has weird spacing: '...er-port ine...' == Line 234 has weird spacing: '...er-port ine...' == Line 1025 has weird spacing: '...keyword enu...' == Line 1029 has weird spacing: '...terface iet...' -- The document date (March 13, 2017) is 2594 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) -- Obsolete informational reference (is this intentional?): RFC 5101 (Obsoleted by RFC 7011) Summary: 3 errors (**), 0 flaws (~~), 6 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 K. Sreenivasa 5 Expires: September 14, 2017 Cisco Systems 6 L. Huang 7 General Electric 8 D. Blair 9 Cisco Systems 10 March 13, 2017 12 Network Access Control List (ACL) YANG Data Model 13 draft-ietf-netmod-acl-model-10 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. 33 o Revision date in model (Oct 12, 2016) needs to get updated with 34 the date the draft gets approved. The date also needs to get 35 reflected on the line with . 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at http://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on September 14, 2017. 54 Copyright Notice 56 Copyright (c) 2017 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (http://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 1.1. Definitions and Acronyms . . . . . . . . . . . . . . . . 3 73 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 4 74 3. Understanding ACL's Filters and Actions . . . . . . . . . . . 4 75 3.1. ACL Modules . . . . . . . . . . . . . . . . . . . . . . . 5 76 4. ACL YANG Models . . . . . . . . . . . . . . . . . . . . . . . 7 77 4.1. IETF Access Control List module . . . . . . . . . . . . . 7 78 4.2. IETF Packet Fields module . . . . . . . . . . . . . . . . 12 79 4.3. An ACL Example . . . . . . . . . . . . . . . . . . . . . 16 80 4.4. Port Range Usage Example . . . . . . . . . . . . . . . . 16 81 5. Security Considerations . . . . . . . . . . . . . . . . . . . 17 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 83 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 84 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 85 8.1. Normative References . . . . . . . . . . . . . . . . . . 19 86 8.2. Informative References . . . . . . . . . . . . . . . . . 19 87 Appendix A. Extending ACL model examples . . . . . . . . . . . . 20 88 A.1. Example of extending existing model for route filtering . 20 89 A.2. A company proprietary module example . . . . . . . . . . 22 90 A.3. Example to augment model with mixed ACL type . . . . . . 30 91 A.4. Linux nftables . . . . . . . . . . . . . . . . . . . . . 30 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 94 1. Introduction 96 Access Control List (ACL) is one of the basic elements to configure 97 device forwarding behavior. It is used in many networking concepts 98 such as Policy Based Routing, Firewalls etc. 100 An ACL is an ordered set of rules that is used to filter traffic on a 101 networking device. Each rule is represented by an Access Control 102 Entry (ACE). 104 Each ACE has a group of match criteria and a group of action 105 criteria. 107 The match criteria consist of a tuple of packet header match criteria 108 and can have metadata match criteria as well. 110 o Packet header matches apply to fields visible in the packet such 111 as address or class of service or port numbers. 113 o In case vendor suppors it, metadata matches apply to fields 114 associated with the packet but not in the packet header such as 115 input interface or overall packet length 117 The actions specify what to do with the packet when the matching 118 criteria is met. These actions are any operations that would apply 119 to the packet, such as counting, policing, or simply forwarding.The 120 list of potential actions is endless depending on the innovations of 121 the networked devices. 123 Access Control List is also widely knowns as ACL (pronounce as [ak-uh 124 l]) or Access List. In this document, Access Control List, ACL and 125 Access List are interchangeable. 127 The matching of filters and actions in an ACE/ACL are triggered only 128 after application/attachment of the ACL to an interface, VRF, vty/tty 129 session, QoS policy, routing protocols amongst various other config 130 attachment points. Once attached, it is used for filtering traffic 131 using the match cirteria in the ACE's and taking appropriate 132 action(s) that have been configured against that ACE. In order to 133 apply an ACL to any attachment point, vendors would have to augment 134 the ACL YANG model. 136 1.1. Definitions and Acronyms 138 ACE: Access Control Entry 140 ACL: Access Control List 141 DSCP: Differentiated Services Code Point 143 ICMP: Internet Control Message Protocol 145 IP: Internet Protocol 147 IPv4: Internet Protocol version 4 149 IPv6: Internet Protocol version 6 151 MAC: Media Access Control 153 TCP: Transmission Control Protocol 155 2. Problem Statement 157 This document defines a YANG [RFC6020] data model for the 158 configuration of ACLs. It is very important that model can be easily 159 used by applications/attachments. 161 ACL implementations in every device may vary greatly in terms of the 162 filter constructs and actions that they support. Therefore this 163 draft proposes a model that can be augmented by standard extensions 164 and vendor proprietary models. 166 3. Understanding ACL's Filters and Actions 168 Although different vendors have different ACL data models, there is a 169 common understanding of what access control list (ACL) is. A network 170 system usually have a list of ACLs, and each ACL contains an ordered 171 list of rules, also known as access list entries - ACEs. Each ACE 172 has a group of match criteria and a group of action criteria. The 173 match criteria consist of packet header matching. It as also 174 possible for ACE to match on metadata, if supported by the vendor. 175 Packet header matching applies to fields visible in the packet such 176 as address or class of service or port numbers. Metadata matching 177 applies to fields associated with the packet, but not in the packet 178 header such as input interface, packet length, or source or 179 destination prefix length. The actions can be any sort of operation 180 from logging to rate limiting or dropping to simply forwarding. 181 Actions on the first matching ACE are applied with no processing of 182 subsequent ACEs. The model also includes a container to hold overall 183 operational state for each ACL and operational state for each ACE. 184 One ACL can be applied to multiple targets within the device, such as 185 interfaces of a networked device, applications or features running in 186 the device, etc. When applied to interfaces of a networked device, 187 the ACL is applied in a direction which indicates if it should be 188 applied to packet entering (input) or leaving the device (output). 189 An example in the appendix shows how to express it in YANG model. 191 This draft tries to address the commonalities between all vendors and 192 create a common model, which can be augmented with proprietary 193 models. The base model is very simple and with this design we hope 194 to achieve needed flexibility for each vendor to extend the base 195 model. 197 3.1. ACL Modules 199 There are two YANG modules in the model. The first module, "ietf- 200 access-control-list", defines generic ACL aspects which are common to 201 all ACLs regardless of their type or vendor. In effect, the module 202 can be viewed as providing a generic ACL "superclass". It imports 203 the second module, "ietf-packet-fields". The match container in 204 "ietf-access-control-list" uses groupings in "ietf-packet-fields". 205 If there is a need to define new "matches" choice, such as IPFIX 206 [RFC5101], the container "matches" can be augmented. 208 module: ietf-access-control-list 209 +--rw access-lists 210 +--rw acl* [acl-type acl-name] 211 +--rw acl-name string 212 +--rw acl-type acl-type 213 +--ro acl-oper-data 214 +--rw access-list-entries 215 +--rw ace* [rule-name] 216 +--rw rule-name string 217 +--rw matches 218 | +--rw (ace-type)? 219 | +--:(ace-ip) 220 | | +--rw (ace-ip-version)? 221 | | | +--:(ace-ipv4) 222 | | | | +--rw destination-ipv4-network? inet:ipv4-prefix 223 | | | | +--rw source-ipv4-network? inet:ipv4-prefix 224 | | | +--:(ace-ipv6) 225 | | | +--rw destination-ipv6-network? inet:ipv6-prefix 226 | | | +--rw source-ipv6-network? inet:ipv6-prefix 227 | | | +--rw flow-label? inet:ipv6-flow-label 228 | | +--rw dscp? inet:dscp 229 | | +--rw protocol? uint8 230 | | +--rw source-port-range! 231 | | | +--rw lower-port inet:port-number 232 | | | +--rw upper-port? inet:port-number 233 | | +--rw destination-port-range! 234 | | +--rw lower-port inet:port-number 235 | | +--rw upper-port? inet:port-number 236 | +--:(ace-eth) 237 | +--rw destination-mac-address? yang:mac-address 238 | +--rw destination-mac-address-mask? yang:mac-address 239 | +--rw source-mac-address? yang:mac-address 240 | +--rw source-mac-address-mask? yang:mac-address 241 +--rw actions 242 | +--rw (packet-handling)? 243 | +--:(deny) 244 | | +--rw deny? empty 245 | +--:(permit) 246 | +--rw permit? empty 247 +--ro ace-oper-data 248 +--ro match-counter? yang:counter64 250 Figure 1 252 4. ACL YANG Models 254 4.1. IETF Access Control List module 256 "ietf-access-control-list" is the standard top level module for 257 access lists. The "access-lists" container stores a list of "acl". 258 Each "acl" has information identifying the access list by a 259 name("acl-name") and a list("access-list-entries") of rules 260 associated with the "acl-name". Each of the entries in the 261 list("access-list-entries"), indexed by the string "rule-name", has 262 containers defining "matches" and "actions". The "matches" define 263 criteria used to identify patterns in "ietf-packet-fields". The 264 "actions" define behavior to undertake once a "match" has been 265 identified. 267 file "ietf-access-control-list@2016-10-12.yang" 268 module ietf-access-control-list { 269 namespace "urn:ietf:params:xml:ns:yang:ietf-access-control-list"; 270 prefix acl; 271 import ietf-yang-types { 272 prefix yang; 273 } 274 import ietf-packet-fields { 275 prefix packet-fields; 276 } 277 organization "IETF NETMOD (NETCONF Data Modeling Language) 278 Working Group"; 279 contact 280 "WG Web: http://tools.ietf.org/wg/netmod/ 281 WG List: netmod@ietf.org 283 Editor: Dean Bogdanovic 284 ivandean@gmail.com 285 Editor: Kiran Agrahara Sreenivasa 286 kkoushik@cisco.com 287 Editor: Lisa Huang 288 lyihuang16@gmail.com 289 Editor: Dana Blair 290 dblair@cisco.com"; 292 description 293 "This YANG module defines a component that describing the 294 configuration of Access Control Lists (ACLs). 295 Copyright (c) 2016 IETF Trust and the persons identified as 296 the document authors. All rights reserved. 297 Redistribution and use in source and binary forms, with or 298 without modification, is permitted pursuant to, and subject 299 to the license terms contained in, the Simplified BSD 300 License set forth in Section 4.c of the IETF Trust's Legal 301 Provisions Relating to IETF Documents 302 (http://trustee.ietf.org/license-info). 303 This version of this YANG module is part of RFC XXXX; see 304 the RFC itself for full legal notices."; 305 revision 2016-10-12 { 306 description 307 "Base model for Network Access Control List (ACL)."; 308 reference 309 "RFC XXXX: Network Access Control List (ACL) 310 YANG Data Model"; 311 } 313 /* 314 * Identities 315 */ 317 identity acl-base { 318 description 319 "Base Access Control List type for all Access Control List type 320 identifiers."; 321 } 323 identity ipv4-acl { 324 base acl:acl-base; 325 description 326 "ACL that primarily matches on fields from the IPv4 header 327 (e.g. IPv4 destination address) and layer 4 headers (e.g. TCP 328 destination port). An acl of type ipv4-acl does not contain 329 matches on fields in the ethernet header or the IPv6 header."; 330 } 331 identity ipv6-acl { 332 base acl:acl-base; 333 description 334 "ACL that primarily matches on fields from the IPv6 header 335 (e.g. IPv6 destination address) and layer 4 headers (e.g. TCP 336 destination port). An acl of type ipv6-acl does not contain 337 matches on fields in the ethernet header or the IPv4 header."; 338 } 339 identity eth-acl { 340 base acl:acl-base; 341 description 342 "ACL that primarily matches on fields in the ethernet header, 343 like 10/100/1000baseT or WiFi Access Control List. An acl of 344 type eth-acl does not contain matches on fields in the IPv4 345 header, IPv6 header or layer 4 headers."; 346 } 347 /* 348 * Typedefs 349 */ 351 typedef acl-type { 352 type identityref { 353 base acl-base; 354 } 355 description 356 "This type is used to refer to an Access Control List 357 (ACL) type"; 358 } 360 typedef access-control-list-ref { 361 type leafref { 362 path "/access-lists/acl/acl-name"; 363 } 364 description 365 "This type is used by data models that need to reference an 366 Access Control List"; 367 } 369 /* 370 * Configuration data nodes 371 */ 373 container access-lists { 374 description 375 "This is a top level container for Access Control Lists. 376 It can have one or more Access Control Lists."; 377 list acl { 378 key "acl-type acl-name"; 379 description 380 "An Access Control List(ACL) is an ordered list of 381 Access List Entries (ACE). Each Access Control Entry has a 382 list of match criteria and a list of actions. 383 Since there are several kinds of Access Control Lists 384 implemented with different attributes for 385 different vendors, this 386 model accommodates customizing Access Control Lists for 387 each kind and for each vendor."; 388 leaf acl-name { 389 type string; 390 description 391 "The name of access-list. A device MAY restrict the length 392 and value of this name, possibly space and special 393 characters are not allowed."; 394 } 395 leaf acl-type { 396 type acl-type; 397 description 398 "Type of access control list. Indicates the primary intended 399 type of match criteria (e.g. ethernet, IPv4, IPv6, mixed, etc) 400 used in the list instance."; 401 } 402 container acl-oper-data { 403 config false; 404 description 405 "Overall Access Control List operational data"; 406 } 407 container access-list-entries { 408 description 409 "The access-list-entries container contains 410 a list of access-list-entries(ACE)."; 411 list ace { 412 key "rule-name"; 413 ordered-by user; 414 description 415 "List of access list entries(ACE)"; 416 leaf rule-name { 417 type string; 418 description 419 "A unique name identifying this Access List 420 Entry(ACE)."; 421 } 422 container matches { 423 description 424 "Definitions for match criteria for this Access List 425 Entry."; 426 choice ace-type { 427 description 428 "Type of access list entry."; 429 case ace-ip { 430 description "IP Access List Entry."; 431 choice ace-ip-version { 432 description 433 "IP version used in this Acess List Entry."; 434 case ace-ipv4 { 435 uses packet-fields:acl-ipv4-header-fields; 436 } 437 case ace-ipv6 { 438 uses packet-fields:acl-ipv6-header-fields; 439 } 440 } 441 uses packet-fields:acl-ip-header-fields; 442 } 443 case ace-eth { 444 description 445 "Ethernet Access List entry."; 446 uses packet-fields:acl-eth-header-fields; 447 } 448 } 449 } 450 container actions { 451 description 452 "Definitions of action criteria for this Access List 453 Entry."; 454 choice packet-handling { 455 default "deny"; 456 description 457 "Packet handling action."; 458 case deny { 459 leaf deny { 460 type empty; 461 description 462 "Deny action."; 463 } 464 } 465 case permit { 466 leaf permit { 467 type empty; 468 description 469 "Permit action."; 470 } 471 } 472 } 473 } 475 /* 476 * Operational state data nodes 477 */ 478 container ace-oper-data { 479 config false; 480 description 481 "Operational data for this Access List Entry."; 482 leaf match-counter { 483 type yang:counter64; 484 description 485 "Number of matches for this Access List Entry"; 486 } 487 } 488 } 489 } 490 } 492 } 493 } 494 496 4.2. IETF Packet Fields module 498 The packet fields module defines the necessary groups for matching on 499 fields in the packet including ethernet, ipv4, ipv6, and transport 500 layer fields. Since the number of match criteria is very large, the 501 base draft does not include these directly but references them by 502 "uses" to keep the base module simple. In case more match conditions 503 are needed, those can be added by augmenting choices within container 504 "matches" in ietf-access-control-list.yang model. 506 file "ietf-packet-fields@2016-10-12.yang" 507 module ietf-packet-fields { 508 namespace "urn:ietf:params:xml:ns:yang:ietf-packet-fields"; 509 prefix packet-fields; 510 import ietf-inet-types { 511 prefix inet; 512 } 513 import ietf-yang-types { 514 prefix yang; 515 } 516 organization "IETF NETMOD (NETCONF Data Modeling Language) Working 517 Group"; 518 contact 519 "WG Web: http://tools.ietf.org/wg/netmod/ 520 WG List: netmod@ietf.org 522 Editor: Dean Bogdanovic 523 ivandean@gmail.com 524 Editor: Kiran Agrahara Sreenivasa 525 kkoushik@cisco.com 526 Editor: Lisa Huang 527 lyihuang16@gmail.com 528 Editor: Dana Blair 529 dblair@cisco.com"; 531 description 532 "This YANG module defines groupings that are used by 533 ietf-access-control-list YANG module. Their usage is not 534 limited to ietf-access-control-list and can be 535 used anywhere as applicable. 536 Copyright (c) 2016 IETF Trust and the persons identified as 537 the document authors. All rights reserved. 538 Redistribution and use in source and binary forms, with or 539 without modification, is permitted pursuant to, and subject 540 to the license terms contained in, the Simplified BSD 541 License set forth in Section 4.c of the IETF Trust's Legal 542 Provisions Relating to IETF Documents 543 (http://trustee.ietf.org/license-info). 544 This version of this YANG module is part of RFC XXXX; see 545 the RFC itself for full legal notices."; 546 revision 2016-10-12 { 547 description 548 "Initial version of packet fields used by 549 ietf-access-control-list"; 550 reference 551 "RFC XXXX: Network Access Control List (ACL) 552 YANG Data Model"; 553 } 554 grouping acl-transport-header-fields { 555 description 556 "Transport header fields"; 557 container source-port-range { 558 presence "Enables setting source port range"; 559 description 560 "Inclusive range representing source ports to be used. 561 When only lower-port is present, it represents a single port."; 562 leaf lower-port { 563 type inet:port-number; 564 mandatory true; 565 description 566 "Lower boundary for port."; 567 } 568 leaf upper-port { 569 type inet:port-number; 570 must ". >= ../lower-port" { 571 error-message 572 "The upper-port must be greater than or equal to lower-port"; 573 } 574 description 575 "Upper boundary for port . If existing, the upper port 576 must be greater or equal to lower-port."; 577 } 578 } 579 container destination-port-range { 580 presence "Enables setting destination port range"; 581 description 582 "Inclusive range representing destination ports to be used. When 583 only lower-port is present, it represents a single port."; 584 leaf lower-port { 585 type inet:port-number; 586 mandatory true; 587 description 588 "Lower boundary for port."; 589 } 590 leaf upper-port { 591 type inet:port-number; 592 must ". >= ../lower-port" { 593 error-message 594 "The upper-port must be greater than or equal to lower-port"; 595 } 597 description 598 "Upper boundary for port. If existing, the upper port must 599 be greater or equal to lower-port"; 600 } 601 } 602 } 603 grouping acl-ip-header-fields { 604 description 605 "IP header fields common to ipv4 and ipv6"; 606 leaf dscp { 607 type inet:dscp; 608 description 609 "Value of dscp."; 610 } 611 leaf protocol { 612 type uint8; 613 description 614 "Internet Protocol number."; 615 } 616 uses acl-transport-header-fields; 617 } 618 grouping acl-ipv4-header-fields { 619 description 620 "Fields in IPv4 header."; 621 leaf destination-ipv4-network { 622 type inet:ipv4-prefix; 623 description 624 "Destination IPv4 address prefix."; 625 } 626 leaf source-ipv4-network { 627 type inet:ipv4-prefix; 628 description 629 "Source IPv4 address prefix."; 630 } 631 } 632 grouping acl-ipv6-header-fields { 633 description 634 "Fields in IPv6 header"; 635 leaf destination-ipv6-network { 636 type inet:ipv6-prefix; 637 description 638 "Destination IPv6 address prefix."; 639 } 640 leaf source-ipv6-network { 641 type inet:ipv6-prefix; 642 description 643 "Source IPv6 address prefix."; 644 } 645 leaf flow-label { 646 type inet:ipv6-flow-label; 647 description 648 "IPv6 Flow label."; 649 } 650 reference 651 "RFC 4291: IP Version 6 Addressing Architecture 652 RFC 4007: IPv6 Scoped Address Architecture 653 RFC 5952: A Recommendation for IPv6 Address Text Representation"; 654 } 655 grouping acl-eth-header-fields { 656 description 657 "Fields in Ethernet header."; 658 leaf destination-mac-address { 659 type yang:mac-address; 660 description 661 "Destination IEEE 802 MAC address."; 662 } 663 leaf destination-mac-address-mask { 664 type yang:mac-address; 665 description 666 "Destination IEEE 802 MAC address mask."; 667 } 668 leaf source-mac-address { 669 type yang:mac-address; 670 description 671 "Source IEEE 802 MAC address."; 672 } 673 leaf source-mac-address-mask { 674 type yang:mac-address; 675 description 676 "Source IEEE 802 MAC address mask."; 677 } 678 reference 679 "IEEE 802: IEEE Standard for Local and Metropolitan Area 680 Networks: Overview and Architecture."; 681 } 683 } 684 686 4.3. An ACL Example 688 Requirement: Deny tcp traffic from 10.10.10.1/24, destined to 689 11.11.11.1/24. 691 Here is the acl configuration xml for this Access Control List: 693 694 695 696 697 sample-ipv4-acl 698 ipv4 699 700 701 rule1 702 703 704 10.10.10.1/24 705 706 707 11.11.11.1/24 708 709 710 711 712 713 714 tcp 715 716 717 718 719 720 722 The acl and aces can be described in CLI as the following: 724 access-list ipv4 sample-ipv4-acl 725 deny tcp 10.10.10.1/24 11.11.11.1/24 727 4.4. Port Range Usage Example 729 When a lower-port and an upper-port are both present, it represents a 730 range between lower-port and upper-port with both the lower-port and 731 upper-port are included. When only a lower-port presents, it 732 represents a single port. 734 With the follow XML snippet: 736 737 16384 738 16387 739 741 This represents source ports 16384,16385, 16386, and 16387. 743 With the follow XML snippet: 745 746 16384 747 65535 748 750 This represents source ports greater than/equal to 16384 and less 751 than equal to 65535. 753 With the follow XML snippet: 755 756 21 757 759 This represents port 21. 761 5. Security Considerations 763 The YANG module defined in this memo is designed to be accessed via 764 the NETCONF [RFC6241]. The lowest NETCONF layer is the secure 765 transport layer and the mandatory-to-implement secure transport is 766 SSH [RFC6242]. The NETCONF Access Control Model ( NACM [RFC6536]) 767 provides the means to restrict access for particular NETCONF users to 768 a pre-configured subset of all available NETCONF protocol operations 769 and content. 771 There are a number of data nodes defined in the YANG module which are 772 writable/creatable/deletable (i.e., config true, which is the 773 default). These data nodes may be considered sensitive or vulnerable 774 in some network environments. Write operations (e.g., ) 775 to these data nodes without proper protection can have a negative 776 effect on network operations. 778 These are the subtrees and data nodes and their sensitivity/ 779 vulnerability: 781 /access-lists/acl/access-list-entries: This list specifies all the 782 configured access list entries on the device. Unauthorized write 783 access to this list can allow intruders to access and control the 784 system. Unauthorized read access to this list can allow intruders to 785 spoof packets with authorized addresses thereby compromising the 786 system. 788 6. IANA Considerations 790 This document registers a URI in the IETF XML registry [RFC3688]. 791 Following the format in RFC 3688, the following registration is 792 requested to be made: 794 URI: urn:ietf:params:xml:ns:yang:ietf-access-control-list 796 URI: urn:ietf:params:xml:ns:yang:ietf-packet-fields 798 Registrant Contact: The IESG. 800 XML: N/A, the requested URI is an XML namespace. 802 This document registers a YANG module in the YANG Module Names 803 registry [RFC6020]. 805 name: ietf-access-control-list namespace: 806 urn:ietf:params:xml:ns:yang:ietf-access-control-list prefix: ietf-acl 807 reference: RFC XXXX 809 name: ietf-packet-fields namespace: urn:ietf:params:xml:ns:yang:ietf- 810 packet-fields prefix: ietf-packet-fields reference: RFC XXXX 812 7. Acknowledgements 814 Alex Clemm, Andy Bierman and Lisa Huang started it by sketching out 815 an initial IETF draft in several past IETF meetings. That draft 816 included an ACL YANG model structure and a rich set of match filters, 817 and acknowledged contributions by Louis Fourie, Dana Blair, Tula 818 Kraiser, Patrick Gili, George Serpa, Martin Bjorklund, Kent Watsen, 819 and Phil Shafer. Many people have reviewed the various earlier 820 drafts that made the draft went into IETF charter. 822 Dean Bogdanovic, Kiran Agrahara Sreenivasa, Lisa Huang, and Dana 823 Blair each evaluated the YANG model in previous draft separately and 824 then work together, to created a new ACL draft that can be supported 825 by different vendors. The new draft removes vendor specific 826 features, and gives examples to allow vendors to extend in their own 827 proprietary ACL. The earlier draft was superseded with the new one 828 that received more participation from many vendors. 830 Authors would like to thank Sonal Agarwal, Jason Sterne, Lada Lhotka, 831 Juergen Schoenwalder for their review of and suggestions to the 832 draft. 834 8. References 836 8.1. Normative References 838 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 839 DOI 10.17487/RFC3688, January 2004, 840 . 842 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 843 the Network Configuration Protocol (NETCONF)", RFC 6020, 844 DOI 10.17487/RFC6020, October 2010, 845 . 847 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 848 and A. Bierman, Ed., "Network Configuration Protocol 849 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 850 . 852 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 853 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 854 . 856 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 857 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 858 10.17487/RFC6536, March 2012, 859 . 861 8.2. Informative References 863 [RFC5101] Claise, B., Ed., "Specification of the IP Flow Information 864 Export (IPFIX) Protocol for the Exchange of IP Traffic 865 Flow Information", RFC 5101, DOI 10.17487/RFC5101, January 866 2008, . 868 Appendix A. Extending ACL model examples 870 A.1. Example of extending existing model for route filtering 872 With proposed modular design, it is easy to extend the model with 873 other features. Those features can be standard features, like route 874 filters. Route filters match on specific IP addresses or ranges of 875 prefixes. Much like ACLs, they include some match criteria and 876 corresponding match action(s). For that reason, it is very simple to 877 extend existing ACL model with route filtering. The combination of a 878 route prefix and prefix length along with the type of match 879 determines how route filters are evaluated against incoming routes. 880 Different vendors have different match types and in this model we are 881 using only ones that are common across all vendors participating in 882 this draft. As in this example, the base ACL model can be extended 883 with company proprietary extensions, described in the next section. 885 module: example-ext-route-filter 886 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches: 887 +--rw (route-prefix)? 888 +--:(range) 889 +--rw (ipv4-range)? 890 | +--:(v4-lower-bound) 891 | | +--rw v4-lower-bound? inet:ipv4-prefix 892 | +--:(v4-upper-bound) 893 | +--rw v4-upper-bound? inet:ipv4-prefix 894 +--rw (ipv6-range)? 895 +--:(v6-lower-bound) 896 | +--rw v6-lower-bound? inet:ipv6-prefix 897 +--:(v6-upper-bound) 898 +--rw v6-upper-bound? inet:ipv6-prefix 900 file "example-ext-route-filter@2016-10-12.yang" 901 module example-ext-route-filter { 902 namespace "urn:ietf:params:xml:ns:yang:example-ext-route-filter"; 903 prefix example-ext-route-filter; 904 import ietf-inet-types { 905 prefix "inet"; 906 } 907 import ietf-access-control-list { 908 prefix "ietf-acl"; 909 } 911 organization 912 "Route model group."; 914 contact 915 "abc@abc.com"; 917 description " 918 This module describes route filter as a collection of 919 match prefixes. When specifying a match prefix, you 920 can specify an exact match with a particular route or 921 a less precise match. You can configure either a 922 common action that applies to the entire list or an 923 action associated with each prefix. 924 "; 925 revision 2016-10-12 { 926 description 927 "Creating Route-Filter extension model based on 928 ietf-access-control-list model"; 929 reference " "; 930 } 931 augment "/ietf-acl:access-lists/ietf-acl:acl/" 932 + "ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches"{ 933 description " 934 This module augments the matches container in the ietf-acl 935 module with route filter specific actions 936 "; 937 choice route-prefix{ 938 description "Define route filter match criteria"; 939 case range { 940 description 941 "Route falls between the lower prefix/prefix-length 942 and the upperprefix/prefix-length."; 943 choice ipv4-range { 944 description "Defines the IPv4 prefix range"; 945 leaf v4-lower-bound { 946 type inet:ipv4-prefix; 947 description 948 "Defines the lower IPv4 prefix/prefix length"; 949 } 950 leaf v4-upper-bound { 951 type inet:ipv4-prefix; 952 description 953 "Defines the upper IPv4 prefix/prefix length"; 954 } 955 } 956 choice ipv6-range { 957 description "Defines the IPv6 prefix/prefix range"; 958 leaf v6-lower-bound { 959 type inet:ipv6-prefix; 960 description 961 "Defines the lower IPv6 prefix/prefix length"; 962 } 963 leaf v6-upper-bound { 964 type inet:ipv6-prefix; 965 description 966 "Defines the upper IPv6 prefix/prefix length"; 967 } 968 } 969 } 970 } 971 } 972 } 974 A.2. A company proprietary module example 976 Access control list typically does not exist in isolation. Instead, 977 they are associated with a certain scope in which they are applied, 978 for example, an interface of a set of interfaces. How to attach an 979 access control list to an interface (or other system artifact) is 980 outside the scope of this model, as it depends on the specifics of 981 the system model that is being applied. However, in general, the 982 general design pattern will involved adding a data node with a 983 reference, or set of references, to ACLs that are to be applied to 984 the interface. For this purpose, the type definition "access- 985 control-list-ref" can be used. 987 Module "example-newco-acl" is an example of company proprietary model 988 that augments "ietf-acl" module. It shows how to use 'augment' with 989 an XPath expression to add additional match criteria, action 990 criteria, and default actions when no ACE matches found, as well how 991 to attach an Access Control List to an interface. All these are 992 company proprietary extensions or system feature extensions. 993 "example-newco-acl" is just an example and it is expected from 994 vendors to create their own proprietary models. 996 The following figure is the tree structure of example-newco-acl. In 997 this example, /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access- 998 list-entries/ ietf-acl:ace/ietf-acl:matches are augmented with two 999 new choices, protocol-payload-choice and metadata. The protocol- 1000 payload-choice uses a grouping with an enumeration of all supported 1001 protocol values. Metadata matches apply to fields associated with 1002 the packet but not in the packet header such as input interface or 1003 overall packet length. In other example, /ietf-acl:access-lists/ 1004 ietf-acl:acl/ietf-acl:access-list-entries/ ietf-acl:ace/ietf- 1005 acl:actions are augmented with new choice of actions. 1007 module: example-newco-acl 1008 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches: 1009 +--rw vlan-tagged? uint16 1010 +--rw mpls-unicast? uint16 1011 +--rw mpls-multicast? uint16 1012 +--rw ipv4? uint16 1013 +--rw ipv6? uint16 1014 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches: 1015 +--rw ipv4-ttl? uint8 1016 +--rw ipv4-len? uint16 1017 +--rw ipv4-ihl? uint8 1018 +--rw ipv4-id? uint16 1019 +--rw ipv4-flags? ipv4-flags-type 1020 +--rw ipv4-offset? uint16 1021 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches: 1022 +--rw (protocol-payload-choice)? 1023 | +--:(protocol-payload) 1024 | +--rw protocol-payload* [value-keyword] 1025 | +--rw value-keyword enumeration 1026 +--rw (metadata)? 1027 +--:(interface-name) 1028 +--rw interface-name* [input-interface] 1029 +--rw input-interface ietf-if:interface-ref 1030 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:actions: 1031 +--rw (action)? 1032 +--:(count) 1033 | +--rw count? string 1034 +--:(policer) 1035 | +--rw policer? string 1036 +--:(hiearchical-policer) 1037 +--rw hierarchitacl-policer? string 1038 augment /ietf-acl:access-lists/ietf-acl:acl: 1039 +--rw default-actions 1040 +--rw deny? empty 1041 augment /ietf-if:interfaces/ietf-if:interface: 1042 +--rw acl 1043 +--rw acl-name? ietf-acl:access-control-list-ref 1044 +--ro match-counter? yang:counter64 1045 +--rw (direction)? 1046 +--:(in) 1047 | +--rw in? empty 1048 +--:(out) 1049 +--rw out? empty 1050 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:acl-oper-data: 1051 +--ro targets 1052 +--ro (interface)? 1053 +--:(interface-name) 1054 +--ro interface-name* ietf-if:interface-ref 1056 module example-newco-acl { 1058 yang-version 1.1; 1060 namespace "urn:newco:params:xml:ns:yang:example-newco-acl"; 1062 prefix example-newco-acl; 1064 import ietf-access-control-list { 1065 prefix "ietf-acl"; 1066 } 1068 import ietf-interfaces { 1069 prefix "ietf-if"; 1070 } 1072 import ietf-yang-types { 1073 prefix yang; 1074 } 1076 organization 1077 "Newco model group."; 1079 contact 1080 "abc@newco.com"; 1081 description 1082 "This YANG module augment IETF ACL Yang."; 1084 revision 2016-10-12{ 1085 description 1086 "Creating NewCo proprietary extensions to ietf-acl model"; 1087 reference 1088 "RFC XXXX: Network Access Control List (ACL) 1089 YANG Data Model"; 1090 } 1092 typedef known-ether-type { 1093 type enumeration { 1094 enum "ipv4" { 1095 value 2048; // 0x0800 1096 description "Internet Protocol version 4 (IPv4)"; 1097 } 1098 enum "vlan-tagged" { 1099 value 33024; // 0x8100 1100 description "VLAN-tagged frame (IEEE 802.1Q) & Shortest Path Bridging IEEE 802.1aq[4]"; 1101 } 1102 enum "ipv6" { 1103 value 34525; // 0x86DD 1104 description "Internet Protocol Version 6 (IPv6)"; 1105 } 1106 enum "mpls-unicast" { 1107 value 34887; // 0x8847 1108 description "MPLS unicast"; 1109 } 1110 enum "mpls-multicast" { 1111 value 34888; // 0x8848 1112 description "MPLS multicast"; 1113 } 1114 } 1115 description "Listing supported Ethertypes"; 1116 } 1118 typedef ipv4-flags-type { 1119 type bits { 1120 bit ipv4-reserved { 1121 position 0; 1122 description "reserved bit"; 1123 } 1124 bit ipv4-DF { 1125 position 1; 1126 description "DF bit"; 1127 } 1128 bit ipv4-MF { 1129 position 2; 1130 description "MF bit"; 1131 } 1132 } 1133 description "IPv4 flag types"; 1134 } 1136 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches" { 1137 when "ietf-acl:access-lists/ietf-acl:acl/ietf-acl:acl-type = 'ace-eth'"; 1139 description "additional MAC header matching"; 1141 leaf vlan-tagged { 1142 type uint16; 1143 description "Ethernet frame with VLAN tag"; 1144 } 1146 leaf mpls-unicast { 1147 type uint16; 1148 description "Ethernet frame with MPLS unicast payload"; 1149 } 1150 leaf mpls-multicast { 1151 type uint16; 1152 description "Ethernet frame with MPLS multicast payload"; 1153 } 1155 leaf ipv4 { 1156 type uint16; 1157 description "Ethernet frame with IPv4 unicast payload"; 1158 } 1160 leaf ipv6 { 1161 type uint16; 1162 description "Ethernet frame with IPv4 unicast payload"; 1163 } 1164 } 1165 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches" { 1166 when "ietf-acl:access-lists/ietf-acl:acl/ietf-acl:acl-type = 'ipv4-acl'"; 1168 description "additional IP header information"; 1170 leaf ipv4-ttl { 1171 type uint8; 1172 description "time to live of a given packet as defined in RFC791"; 1173 } 1175 leaf ipv4-len { 1176 type uint16; 1177 description "total packet length as defined in RFC791"; 1178 } 1180 leaf ipv4-ihl { 1181 type uint8 { 1182 range 0..15; 1183 } 1184 description "Internet Header Length in 32 bit words (see RFC791). Note 1185 that while the minimum value for this field in a packet is 1186 5, we leave open the possibility here that the packet has 1187 been corrupted."; 1188 } 1190 leaf ipv4-id { 1191 type uint16; 1192 description "Identification as decribed in RFC791"; 1193 } 1195 leaf ipv4-flags { 1196 type ipv4-flags-type; 1197 description "IPv4 flags as defined in RFC791"; 1199 } 1201 leaf ipv4-offset { 1202 type uint16 { 1203 range 0..8191; 1204 } 1205 description "Matches on the packet fragment offset"; 1206 } 1207 } 1209 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:matches" { 1210 description "Newco proprietary simple filter matches"; 1211 choice protocol-payload-choice { 1212 description "Newo proprietary payload match condition"; 1213 list protocol-payload { 1214 key value-keyword; 1215 ordered-by user; 1216 description "Match protocol payload"; 1217 uses match-simple-payload-protocol-value; 1218 } 1219 } 1221 choice metadata { 1222 description "Newco proprietary interface match condition"; 1223 list interface-name { 1224 key input-interface; 1225 ordered-by user; 1226 description "Match interface name"; 1227 uses metadata; 1228 } 1229 } 1230 } 1232 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:actions" { 1233 description "Newco proprietary simple filter actions"; 1234 choice action { 1235 description ""; 1236 case count { 1237 description "Count the packet in the named counter"; 1238 leaf count { 1239 type string; 1240 description ""; 1241 } 1242 } 1243 case policer { 1244 description "Name of policer to use to rate-limit traffic"; 1245 leaf policer { 1246 type string; 1247 description ""; 1248 } 1249 } 1250 case hiearchical-policer { 1251 description "Name of hierarchical policer to use to 1252 rate-limit traffic"; 1253 leaf hierarchitacl-policer{ 1254 type string; 1255 description ""; 1256 } 1257 } 1258 } 1259 } 1261 augment "/ietf-acl:access-lists/ietf-acl:acl" { 1262 description "Newco proprietary default action"; 1263 container default-actions { 1264 description 1265 "Actions that occur if no access-list entry is matched."; 1266 leaf deny { 1267 type empty; 1268 description ""; 1269 } 1270 } 1271 } 1273 grouping metadata { 1274 description 1275 "Fields associated with a packet which are not in 1276 the header."; 1277 leaf input-interface { 1278 type ietf-if:interface-ref { 1279 require-instance false; 1280 } 1281 description 1282 "Packet was received on this interface"; 1283 } 1284 } 1286 grouping match-simple-payload-protocol-value { 1287 description "Newco proprietary payload"; 1288 leaf value-keyword { 1289 type enumeration { 1290 enum icmp { 1291 description "Internet Control Message Protocol"; 1292 } 1293 enum icmp6 { 1294 description "Internet Control Message Protocol Version 6"; 1296 } 1297 enum range { 1298 description "Range of values"; 1299 } 1300 } 1302 description "(null)"; 1303 } 1304 } 1306 augment "/ietf-if:interfaces/ietf-if:interface" { 1307 description "Apply ACL to interfaces"; 1308 container acl{ 1309 description "ACL related properties."; 1310 leaf acl-name { 1311 type ietf-acl:access-control-list-ref; 1312 description "Access Control List name."; 1313 } 1314 leaf match-counter { 1315 type yang:counter64; 1316 config false; 1317 description 1318 "Total match count for Access Control 1319 List on this interface"; 1320 } 1321 choice direction { 1322 description "Applying ACL in which traffic direction"; 1323 leaf in { 1324 type empty; 1325 description "Inbound traffic"; 1326 } 1327 leaf out { 1328 type empty; 1329 description "Outbound traffic"; 1330 } 1331 } 1332 } 1333 } 1335 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:acl-oper-data" { 1336 description 1337 "This is an example on how to apply acl to a target to collect 1338 operational data"; 1339 container targets{ 1340 description "To which object is the ACL attached to"; 1341 choice interface{ 1342 description "Access Control List was attached to this interface"; 1343 leaf-list interface-name{ 1344 type ietf-if:interface-ref { 1345 require-instance true; 1346 } 1347 description "Attached to this interface name"; 1348 } 1349 } 1350 } 1351 } 1352 } 1354 Draft authors expect that different vendors will provide their own 1355 yang models as in the example above, which is the augmentation of the 1356 base model 1358 A.3. Example to augment model with mixed ACL type 1360 As vendors (or IETF) add more features to ACL, the model is easily 1361 augmented. One of such augmentations can be to add support for mixed 1362 type of ACLs, where acl-type-base can be augmented like in example 1363 below: 1365 identity mixed-l3-acl { 1366 base "access-control-list:acl-type-base"; 1367 description "ACL that contains a mix of entries that 1368 primarily match on fields in IPv4 headers and entries 1369 that primarily match on fields in IPv6 headers. 1370 Matching on layer 4 header fields may also exist in the 1371 list. An acl of type mixed-l3-acl does not contain 1372 matches on fields in the ethernet header."; 1373 } 1375 identity mixed-l2-l3-acl { 1376 base "access-control-list:acl-type-base"; 1377 description "ACL that contains a mix of entries that 1378 primarily match on fields in ethernet headers, entries 1379 that primarily match on fields in IPv4 headers, and entries 1380 that primarily match on fields in IPv6 headers. Matching on 1381 layer 4 header fields may also exist in the list."; 1382 } 1384 A.4. Linux nftables 1386 As Linux platform is becoming more popular as networking platform, 1387 the Linux data model is changing. Previously ACLs in Linux were 1388 highly protocol specific and different utilities were used (iptables, 1389 ip6tables, arptables, ebtables), so each one had separate data model. 1390 Recently, this has changed and a single utility, nftables, has been 1391 developed. With a single application, it has a single data model for 1392 filewall filters and it follows very similarly to the ietf-access- 1393 control list module proposed in this draft. The nftables support 1394 input and output ACEs and each ACE can be defined with match and 1395 action. 1397 The example in Section 4.3 can be configured using nftable tool as 1398 below. 1400 nft add table ip filter 1401 nft add chain filter input 1402 nft add rule ip filter input ip protocol tcp ip saddr 10.10.10.1/24 drop 1404 The configuration entries added in nftable would be. 1406 table ip filter { 1407 chain input { 1408 ip protocol tcp ip saddr 10.10.10.1/24 drop 1409 } 1410 } 1412 We can see that there are many similarities between Linux nftables 1413 and IETF ACL YANG data models and its extension models. It should be 1414 fairly easy to do translation between ACL YANG model described in 1415 this draft and Linux nftables. 1417 Authors' Addresses 1419 Dean Bogdanovic 1420 Volta Networks 1422 Email: ivandean@gmail.com 1424 Kiran Agrahara Sreenivasa 1425 Cisco Systems 1427 Email: kkoushik@cisco.com 1429 Lisa Huang 1430 General Electric 1432 Email: lyihuang16@gmail.com 1433 Dana Blair 1434 Cisco Systems 1436 Email: dblair@cisco.com