idnits 2.17.1 draft-ietf-netconf-rfc6536bis-08.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 26, 2017) is 2371 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) == Missing Reference: 'RFCXXXX' is mentioned on line 1863, but not defined == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-02 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Bierman 3 Internet-Draft YumaWorks 4 Obsoletes: 6536 (if approved) M. Bjorklund 5 Intended status: Standards Track Tail-f Systems 6 Expires: April 29, 2018 October 26, 2017 8 Network Configuration Access Control Module 9 draft-ietf-netconf-rfc6536bis-08 11 Abstract 13 The standardization of network configuration interfaces for use with 14 the Network Configuration Protocol (NETCONF) or RESTCONF protocol 15 requires a structured and secure operating environment that promotes 16 human usability and multi-vendor interoperability. There is a need 17 for standard mechanisms to restrict NETCONF or RESTCONF protocol 18 access for particular users to a pre-configured subset of all 19 available NETCONF or RESTCONF protocol operations and content. This 20 document defines such an access control model. 22 This document obsoletes RFC 6536. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 29, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.2. Changes Since RFC 6536 . . . . . . . . . . . . . . . . . 6 61 2. Access Control Design Objectives . . . . . . . . . . . . . . 6 62 2.1. Access Control Points . . . . . . . . . . . . . . . . . . 6 63 2.2. Simplicity . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.3. Procedural Interface . . . . . . . . . . . . . . . . . . 8 65 2.4. Datastore Access . . . . . . . . . . . . . . . . . . . . 8 66 2.5. Users and Groups . . . . . . . . . . . . . . . . . . . . 8 67 2.6. Maintenance . . . . . . . . . . . . . . . . . . . . . . . 8 68 2.7. Configuration Capabilities . . . . . . . . . . . . . . . 8 69 2.8. Identifying Security-Sensitive Content . . . . . . . . . 9 70 3. NETCONF Access Control Model (NACM) . . . . . . . . . . . . . 9 71 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 9 72 3.1.1. Features . . . . . . . . . . . . . . . . . . . . . . 10 73 3.1.2. External Dependencies . . . . . . . . . . . . . . . . 10 74 3.1.3. Message Processing Model . . . . . . . . . . . . . . 11 75 3.2. Datastore Access . . . . . . . . . . . . . . . . . . . . 14 76 3.2.1. Mapping New Datastores to NACM . . . . . . . . . . . 14 77 3.2.2. Access Rights . . . . . . . . . . . . . . . . . . . . 14 78 3.2.3. RESTCONF Methods . . . . . . . . . . . . . . . . . . 15 79 3.2.4. and Operations . . . . . . . . . . 16 80 3.2.5. Operation . . . . . . . . . . . . . . . 16 81 3.2.6. Operation . . . . . . . . . . . . . . . 17 82 3.2.7. Operation . . . . . . . . . . . . . . 18 83 3.2.8. Operation . . . . . . . . . . . . . . . . . 18 84 3.2.9. Operation . . . . . . . . . . . . . 18 85 3.2.10. Operation . . . . . . . . . . . . . . 19 86 3.3. Model Components . . . . . . . . . . . . . . . . . . . . 19 87 3.3.1. Users . . . . . . . . . . . . . . . . . . . . . . . . 19 88 3.3.2. Groups . . . . . . . . . . . . . . . . . . . . . . . 19 89 3.3.3. Emergency Recovery Session . . . . . . . . . . . . . 19 90 3.3.4. Global Enforcement Controls . . . . . . . . . . . . . 20 91 3.3.4.1. enable-nacm Switch . . . . . . . . . . . . . . . 20 92 3.3.4.2. read-default Switch . . . . . . . . . . . . . . . 20 93 3.3.4.3. write-default Switch . . . . . . . . . . . . . . 20 94 3.3.4.4. exec-default Switch . . . . . . . . . . . . . . . 21 95 3.3.4.5. enable-external-groups Switch . . . . . . . . . . 21 96 3.3.5. Access Control Rules . . . . . . . . . . . . . . . . 21 98 3.4. Access Control Enforcement Procedures . . . . . . . . . . 21 99 3.4.1. Initial Operation . . . . . . . . . . . . . . . . . . 22 100 3.4.2. Session Establishment . . . . . . . . . . . . . . . . 22 101 3.4.3. "access-denied" Error Handling . . . . . . . . . . . 22 102 3.4.4. Incoming RPC Message Validation . . . . . . . . . . . 22 103 3.4.5. Data Node Access Validation . . . . . . . . . . . . . 25 104 3.4.6. Outgoing Authorization . . . . . . . . 27 105 3.5. Data Model Definitions . . . . . . . . . . . . . . . . . 29 106 3.5.1. Data Organization . . . . . . . . . . . . . . . . . . 30 107 3.5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . 30 108 3.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 40 109 3.7. Security Considerations . . . . . . . . . . . . . . . . . 41 110 3.7.1. NACM Configuration and Monitoring Considerations . . 41 111 3.7.2. General Configuration Issues . . . . . . . . . . . . 43 112 3.7.3. Data Model Design Considerations . . . . . . . . . . 45 113 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 114 4.1. Normative References . . . . . . . . . . . . . . . . . . 45 115 4.2. Informative References . . . . . . . . . . . . . . . . . 46 116 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 47 117 A.1. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . 47 118 A.2. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 47 119 A.3. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 47 120 A.4. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 47 121 A.5. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 47 122 A.6. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 47 123 A.7. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 48 124 A.8. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 48 125 A.9. v00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 126 Appendix B. Usage Examples . . . . . . . . . . . . . . . . . . . 48 127 B.1. Example . . . . . . . . . . . . . . . . . . . . 48 128 B.2. Module Rule Example . . . . . . . . . . . . . . . . . . . 49 129 B.3. Protocol Operation Rule Example . . . . . . . . . . . . . 51 130 B.4. Data Node Rule Example . . . . . . . . . . . . . . . . . 53 131 B.5. Notification Rule Example . . . . . . . . . . . . . . . . 55 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 134 1. Introduction 136 The NETCONF and RESTCONF protocols do not provide any standard 137 mechanisms to restrict the protocol operations and content that each 138 user is authorized to access. 140 There is a need for interoperable management of the controlled access 141 to administrator-selected portions of the available NETCONF or 142 RESTCONF content within a particular server. 144 This document addresses access control mechanisms for the Operations 145 and Content layers of NETCONF, as defined in [RFC6241], and RESTCONF, 146 as defined in [RFC8040]. It contains three main sections: 148 1. Access Control Design Objectives 150 2. NETCONF Access Control Model (NACM) 152 3. YANG Data Model (ietf-netconf-acm.yang) 154 YANG version 1.1 [RFC7950] adds two new constructs that need special 155 access control handling. The "action" statement is similar to the 156 "rpc" statement, except it is located within a data node. The 157 "notification" statement can also be located within a data node. 159 1.1. Terminology 161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 162 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 163 "OPTIONAL" in this document are to be interpreted as described in BCP 164 14 [RFC2119] [RFC8174] when, and only when, they appear in all 165 capitals, as shown here. 167 The following terms are defined in 168 [I-D.ietf-netmod-revised-datastores] and are not redefined here: 170 o datastore 172 o configuration datastore 174 o conventional configuration datastore 176 o candidate configuration datastore 178 o running configuration datastore 180 o startup configuration datastore 182 o operational state datastore 184 o client 186 o server 188 The following terms are defined in [RFC6241] and are not redefined 189 here: 191 o protocol operation 192 o session 194 o user 196 The following terms are defined in [RFC7950] and are not redefined 197 here: 199 o action 201 o data node 203 o data definition statement 205 The following terms are defined in [RFC8040] and are not redefined 206 here: 208 o data resource 210 o datastore resource 212 o operation resource 214 o target resource 216 The following term is defined in [RFC7230] and is not redefined here: 218 o request URI 220 The following terms are used throughout this document: 222 access control: A security feature provided by the server that 223 allows an administrator to restrict access to a subset of all 224 protocol operations and data, based on various criteria. 226 access control model (ACM): A conceptual model used to configure and 227 monitor the access control procedures desired by the administrator 228 to enforce a particular access control policy. 230 access control rule: The criterion used to determine if a particular 231 access operation will be permitted or denied. 233 access operation: How a request attempts to access a conceptual 234 object. One of "none", "read", "create", "delete", "update", or 235 "execute". 237 data node hierarchy: The hierarchy of data nodes that identifies the 238 specific "action" or "notification" node in the datastore. 240 recovery session: A special administrative session that is given 241 unlimited NETCONF access and is exempt from all access control 242 enforcement. The mechanism(s) used by a server to control and 243 identify whether or not a session is a recovery session are 244 implementation specific and outside the scope of this document. 246 write access: A shorthand for the "create", "delete", and "update" 247 access operations. 249 1.2. Changes Since RFC 6536 251 The NACM procedures and data model have been updated to support new 252 data modeling capabilities in the version 1.1. of the YANG data 253 modeling language. The "action" and "notification" statements can be 254 used within data nodes to define data-model specific operations and 255 notifications. 257 An important use-case for these new YANG statements is the increased 258 access control granularity that can be achieved over top-level "rpc" 259 and "notification" statements. The new "action" and "notification" 260 statements are used within data nodes, and access to the action or 261 notification can be restricted to specific instances of these data 262 nodes. 264 Support for the RESTCONF protocol has been added. The RESTCONF 265 operations are similar to the NETCONF operations, so a simple mapping 266 to the existing NACM procedures and data model is possible. 268 The server message processing behavior for the edit operation "none", 269 used in the , has been changed. Now read access is 270 required for such data nodes, instead of no access required. 272 2. Access Control Design Objectives 274 This section documents the design objectives for the NETCONF Access 275 Control Model presented in Section 3. 277 2.1. Access Control Points 279 NETCONF allows server implementors to add new custom protocol 280 operations, and the YANG Data Modeling Language supports this 281 feature. These operations can be defined in standard or proprietary 282 YANG modules. 284 It is not possible to design an ACM for NETCONF that only focuses on 285 a static set of standard protocol operations defined by the NETCONF 286 protocol itself, like some other protocols. Since few assumptions 287 can be made about an arbitrary protocol operation, the NETCONF 288 architectural server components need to be protected at three 289 conceptual control points. 291 These access control points, described in Figure 1, are as follows: 293 protocol operation: Permission to invoke specific protocol 294 operations. 296 datastore: Permission to read and/or alter specific data nodes 297 within any datastore. 299 notification: Permission to receive specific notification event 300 types. 302 +-------------+ +-------------+ 303 client | protocol | | data node | 304 request --> | operation | -------------> | access | 305 | allowed? | datastore | allowed? | 306 +-------------+ or state +-------------+ 307 data access 309 +----------------+ 310 | notification | 311 event --> | allowed? | 312 +----------------+ 314 Figure 1 316 2.2. Simplicity 318 There is concern that a complicated ACM will not be widely deployed 319 because it is too hard to use. Configuration of the access control 320 system needs to be as simple as possible. Simple and common tasks 321 need to be easy to configure and require little expertise or domain- 322 specific knowledge. Complex tasks are possible using additional 323 mechanisms, which may require additional expertise. 325 A single set of access control rules ought to be able to control all 326 types of NETCONF protocol operation invocation, all datastore access, 327 and all notification events. 329 Access control ought to be defined with a small and familiar set of 330 permissions, while still allowing full control of datastore access. 332 2.3. Procedural Interface 334 The NETCONF protocol uses a remote procedure call model and an 335 extensible set of protocol operations. Access control for any 336 possible protocol operation is necessary. 338 2.4. Datastore Access 340 It is necessary to control access to specific nodes and subtrees 341 within the datastore, regardless of which protocol operation, 342 standard or proprietary, was used to access the datastore. 344 2.5. Users and Groups 346 It is necessary that access control rules for a single user or a 347 configurable group of users can be configured. 349 The ACM needs to support the concept of administrative groups, to 350 support the well-established distinction between a root account and 351 other types of less-privileged conceptual user accounts. These 352 groups need to be configurable by the administrator. 354 It is necessary that the user-to-group mapping can be delegated to a 355 central server, such as a RADIUS server [RFC2865][RFC5607]. Since 356 authentication is performed by the transport layer and RADIUS 357 performs authentication and service authorization at the same time, 358 the underlying transport protocol needs to be able to report a set of 359 group names associated with the user to the server. It is necessary 360 that the administrator can disable the usage of these group names 361 within the ACM. 363 2.6. Maintenance 365 It ought to be possible to disable part or all of the access control 366 model enforcement procedures without deleting any access control 367 rules. 369 2.7. Configuration Capabilities 371 Suitable configuration and monitoring mechanisms are needed to allow 372 an administrator to easily manage all aspects of the ACM's behavior. 373 A standard data model, suitable for use with the 374 protocol operation, needs to be available for this purpose. 376 Access control rules to restrict access operations on specific 377 subtrees within the configuration datastore need to be supported. 379 2.8. Identifying Security-Sensitive Content 381 One of the most important aspects of the data model documentation, 382 and biggest concerns during deployment, is the identification of 383 security-sensitive content. This applies to protocol operations in 384 NETCONF, not just data and notifications. 386 It is mandatory for security-sensitive objects to be documented in 387 the Security Considerations section of an RFC. This is nice, but it 388 is not good enough, for the following reasons: 390 o This documentation-only approach forces administrators to study 391 the RFC and determine if there are any potential security risks 392 introduced by a new data model. 394 o If any security risks are identified, then the administrator must 395 study some more RFC text and determine how to mitigate the 396 security risk(s). 398 o The ACM on each server must be configured to mitigate the security 399 risks, e.g., require privileged access to read or write the 400 specific data identified in the Security Considerations section. 402 o If the ACM is not pre-configured, then there will be a time window 403 of vulnerability after the new data model is loaded and before the 404 new access control rules for that data model are configured, 405 enabled, and debugged. 407 Often, the administrator just wants to disable default access to the 408 secure content, so no inadvertent or malicious changes can be made to 409 the server. This allows the default rules to be more lenient, 410 without significantly increasing the security risk. 412 A data model designer needs to be able to use machine-readable 413 statements to identify content that needs to be protected by default. 414 This will allow client and server tools to automatically identify 415 data-model-specific security risks, by denying access to sensitive 416 data unless the user is explicitly authorized to perform the 417 requested access operation. 419 3. NETCONF Access Control Model (NACM) 421 3.1. Introduction 423 This section provides a high-level overview of the access control 424 model structure. It describes the NETCONF protocol message 425 processing model and the conceptual access control requirements 426 within that model. 428 3.1.1. Features 430 The NACM data model provides the following features: 432 o Independent control of remote procedure call (RPC), action, data, 433 and notification access. 435 o Simple access control rules configuration data model that is easy 436 to use. 438 o The concept of an emergency recovery session is supported, but 439 configuration of the server for this purpose is beyond the scope 440 of this document. An emergency recovery session will bypass all 441 access control enforcement, in order to allow it to initialize or 442 repair the NACM configuration. 444 o A simple and familiar set of datastore permissions is used. 446 o Support for YANG security tagging (e.g., "nacm:default-deny-write" 447 statement) allows default security modes to automatically exclude 448 sensitive data. 450 o Separate default access modes for read, write, and execute 451 permissions. 453 o Access control rules are applied to configurable groups of users. 455 o The access control enforcement procedures can be disabled during 456 operation, without deleting any access control rules, in order to 457 debug operational problems. 459 o Access control rules are simple to configure. 461 o The number of denied protocol operation requests and denied 462 datastore write requests can be monitored by the client. 464 o Simple unconstrained YANG instance identifiers are used to 465 configure access control rules for specific data nodes. 467 3.1.2. External Dependencies 469 The NETCONF protocol [RFC6241] and RESTCONF protocol [RFC8040] are 470 used for network management purposes within this document. 472 The YANG Data Modeling Language [RFC7950] is used to define the data 473 models for use with the NETCONF or RESTCONF protocols. YANG is also 474 used to define the data model in this document. 476 3.1.3. Message Processing Model 478 The following diagram shows the conceptual message flow model, 479 including the points at which access control is applied during 480 NETCONF message processing. 482 RESTCONF operations are mapped to the access control model based on 483 the HTTP method and resource class used in the operation. For 484 example, a POST method on a data resource is considered "write data 485 node" access, but a POST method on an operation resource is 486 considered "operation" access. 488 The new "pre-read data acc. ctl" boxes in the diagram below refer to 489 group read access as it relates to data node ancestors of an action 490 or notification. As an example, if an action is defined as 491 /interfaces/interface/reset-interface, the group must be authorized 492 to read /interfaces and /interfaces/interface, and execute on 493 /interfaces/interface/reset-interface. 495 +-------------------------+ 496 | session | 497 | (username) | 498 +-------------------------+ 499 | ^ 500 V | 501 +--------------+ +---------------+ 502 | message | | message | 503 | dispatcher | | generator | 504 +--------------+ +---------------+ 505 | | ^ ^ 506 | V | | 507 | +=============+ | | 508 | | pre-read | | | 509 | | data node | | | 510 | | acc. ctl | | | 511 | +=============+ | | 512 | | | | 513 V V | | 514 +===========+ +-------------+ +----------------+ 515 | operation |---> | reply | | | 516 | acc. ctl | | generator | | generator | 517 +===========+ +-------------+ +----------------+ 518 | ^ ^ ^ 519 V +------+ | | 520 +-----------+ | +=============+ +================+ 521 | operation | | | read | | | 522 | processor |-+ | data node | | access ctl | 523 | | | acc. ctl | | | 524 +-----------+ +=============+ +================+ 525 | | ^ ^ ^ 526 V +----------------+ | | | 527 +===========+ | | | +============+ 528 | write | | | | | pre-read | 529 | data node | | | | | data node | 530 | acc. ctl | -----------+ | | | | acc. ctl | 531 +===========+ | | | | +============+ 532 | | | | | ^ 533 V V V | | | 534 +---------------+ +-------------------+ 535 | configuration | ---> | server | 536 | datastore | | instrumentation | 537 | | <--- | | 538 +---------------+ +-------------------+ 540 Figure 2 542 The following high-level sequence of conceptual processing steps is 543 executed for each received message, if access control 544 enforcement is enabled: 546 o For each active session, access control is applied individually to 547 all messages (except ) received by the 548 server, unless the session is identified as a recovery session. 550 o If the operation defined in [RFC7950] is invoked, then 551 read access is required for all instances in the hierarchy of data 552 nodes that identifies the specific action in the datastore, and 553 execute access is required for the action node. If the user is 554 not authorized to read all the specified data nodes and execute 555 the action, then the request is rejected with an "access-denied" 556 error. 558 o Otherwise, if the user is not authorized to execute the specified 559 protocol operation, then the request is rejected with an "access- 560 denied" error. 562 o If a datastore is accessed by the protocol operation, then the 563 server checks if the client is authorized to access the nodes in 564 the datastore. If the user is not authorized to perform the 565 requested access operation on the requested data, then the request 566 is rejected with an "access-denied" error. 568 The following sequence of conceptual processing steps is executed for 569 each generated notification event, if access control enforcement is 570 enabled: 572 o Server instrumentation generates a notification for a particular 573 subscription. 575 o If the notification statement is specified within a data subtree, 576 as specified in [RFC7950], then read access is required for all 577 instances in the hierarchy of data nodes that identifies the 578 specific notification in the datastore, and read access is 579 required for the notification node. If the user is not authorized 580 to read all the specified data nodes and the notification node, 581 then the notification is dropped for that subscription. 583 o If the notification statement is a top-level statement, the 584 notification access control enforcer checks the notification event 585 type, and if it is one that the user is not authorized to read, 586 then the notification is dropped for that subscription. 588 3.2. Datastore Access 590 The same access control rules apply to all datastores that support 591 NACM, for example, the candidate configuration datastore or the 592 running configuration datastore. 594 All conventional configuration datastores and the operational state 595 datastore are controlled by NACM. Local or remote files or 596 datastores accessed via the parameter are not controlled by 597 NACM. 599 3.2.1. Mapping New Datastores to NACM 601 It is possible that new datastores will be defined over time for use 602 with the NETCONF protocol. NACM MAY be applied to other datastores 603 that have similar access rights as defined in NACM. To apply NACM to 604 a new datastore, the new datastore specification needs to define how 605 it maps to the NACM CRUDX access rights. It is possible only a 606 subset of the NACM access rights would be applicable. For example, 607 only retrieval access control would be needed for a read-only 608 datastore. Operations and access rights not supported by the NACM 609 CRUDX model are outside the scope of this document. A datastore does 610 not need to use NACM, e.g., the datastore specification defines 611 something else, or does not use access control. 613 3.2.2. Access Rights 615 A small set of hard-wired datastore access rights is needed to 616 control access to all possible protocol operations, including vendor 617 extensions to the standard protocol operation set. 619 The "CRUDX" model can support all protocol operations: 621 o Create: allows the client to add a new data node instance to a 622 datastore. 624 o Read: allows the client to read a data node instance from a 625 datastore or receive the notification event type. 627 o Update: allows the client to update an existing data node instance 628 in a datastore. 630 o Delete: allows the client to delete a data node instance from a 631 datastore. 633 o eXec: allows the client to execute the operation. 635 3.2.3. RESTCONF Methods 637 The RESTCONF protocol utilizes HTTP methods to perform datastore 638 operations, similar to the NETCONF protocol. The NACM procedures 639 were originally written for NETCONF protocol operations so the 640 RESTCONF methods are mapped to NETCONF operations for the purpose of 641 access control processing. The enforcement procedures described 642 within this document apply to both protocols unless explicitly stated 643 otherwise. 645 The request URI needs to be considered when processing RESTCONF 646 requests on data resources: 648 o For HEAD and GET requests, any data nodes which are ancestor nodes 649 of the target resource are considered to be part of the retrieval 650 request for access control purposes. 652 o For PUT, PATCH, and DELETE requests, any data nodes which are 653 ancestor nodes of the target resource are not considered to be 654 part of the edit request for access control purposes. The access 655 operation for these nodes is considered to be "none". The edit 656 begins at the target resource. 658 o For POST requests on data resources, any data nodes which are 659 specified in the request URI, including the target resource, are 660 not considered to be part of the edit request for access control 661 purposes. The access operation for these nodes is considered to 662 be "none". The edit begins at a child node of the target 663 resource, specified in the message body. 665 Not all RESTCONF methods are subject to access control. The 666 following table specifies how each method is mapped to NETCONF 667 protocol operations. The value "none" indicates that NACM is not 668 applied at all to the specific RESTCONF method. 670 +---------+-----------------+---------------------+-----------------+ 671 | method | resource class | NETCONF operation | Access | 672 | | | | operation | 673 +---------+-----------------+---------------------+-----------------+ 674 | OPTIONS | all | none | none | 675 | HEAD | all | , | read | 676 | GET | all | , | read | 677 | POST | datastore, data | | create | 678 | POST | operation | specified operation | execute | 679 | PUT | data | | create, update | 680 | PUT | datastore | | update | 681 | PATCH | data, datastore | | update | 682 | DELETE | data | | delete | 683 +---------+-----------------+---------------------+-----------------+ 685 Table 1: Mapping RESTCONF Methods to NETCONF 687 3.2.4. and Operations 689 The NACM access rights are not directly coupled to the and 690 protocol operations, but apply to all operations 691 that would result in a "read" access operation to the target 692 datastore. This section describes how these access rights apply to 693 the specific access operations supported by the and protocol operations. 696 Data nodes to which the client does not have read access are silently 697 omitted from the message. This is done to allow NETCONF 698 filters for and to function properly, instead of 699 causing an "access-denied" error because the filter criteria would 700 otherwise include unauthorized read access to some data nodes. For 701 NETCONF filtering purposes, the selection criteria is applied to the 702 subset of nodes that the user is authorized to read, not the entire 703 datastore. 705 3.2.5. Operation 707 The NACM access rights are not directly coupled to the 708 "operation" attribute, although they are similar. Instead, a NACM 709 access right applies to all protocol operations that would result in 710 a particular access operation to the target datastore. This section 711 describes how these access rights apply to the specific access 712 operations supported by the protocol operation. 714 If the effective access operation is "none" (i.e., default- 715 operation="none") for a particular data node, then read permission is 716 required for that data node. This is required to allow access to a 717 subtree within a larger data structure. For example, a user may be 718 authorized to create a new "/interfaces/interface" list entry but not 719 be authorized to create or delete its parent container 720 ("/interfaces"). If the "/interfaces" container already exists in 721 the target datastore, then the effective operation will be "none" for 722 the "/interfaces" node if an "/interfaces/interface" list entry is 723 edited. 725 If the protocol operation would result in the creation of a datastore 726 node and the user does not have "create" access permission for that 727 node, the protocol operation is rejected with an "access-denied" 728 error. 730 If the protocol operation would result in the deletion of a datastore 731 node and the user does not have "delete" access permission for that 732 node, the protocol operation is rejected with an "access-denied" 733 error. 735 If the protocol operation would result in the modification of a 736 datastore node and the user does not have "update" access permission 737 for that node, the protocol operation is rejected with an "access- 738 denied" error. 740 A "merge" or "replace" operation may include data nodes 741 that do not alter portions of the existing datastore. For example, a 742 container or list node may be present for naming purposes but does 743 not actually alter the corresponding datastore node. These unaltered 744 data nodes are ignored by the server and do not require any access 745 rights by the client. 747 A "merge" operation may include data nodes but not 748 include particular child data nodes that are present in the 749 datastore. These missing data nodes within the scope of a "merge" 750 operation are ignored by the server and do not require 751 any access rights by the client. 753 The contents of specific restricted datastore nodes MUST NOT be 754 exposed in any elements within the reply. 756 3.2.6. Operation 758 Access control for the protocol operation requires 759 special consideration because the administrator may be replacing the 760 entire target datastore. 762 If the source of the protocol operation is the running 763 configuration datastore and the target is the startup configuration 764 datastore, the client is only required to have permission to execute 765 the protocol operation. 767 Otherwise: 769 o If the source of the operation is a datastore, then 770 data nodes to which the client does not have read access are 771 silently omitted. 773 o If the target of the operation is a datastore, the 774 client needs access to the modified nodes, specifically: 776 * If the protocol operation would result in the creation of a 777 datastore node and the user does not have "create" access 778 permission for that node, the protocol operation is rejected 779 with an "access-denied" error. 781 * If the protocol operation would result in the deletion of a 782 datastore node and the user does not have "delete" access 783 permission for that node, the protocol operation is rejected 784 with an "access-denied" error. 786 * If the protocol operation would result in the modification of a 787 datastore node and the user does not have "update" access 788 permission for that node, the protocol operation is rejected 789 with an "access-denied" error. 791 3.2.7. Operation 793 Access to the protocol operation is denied by 794 default. The "exec-default" leaf does not apply to this protocol 795 operation. Access control rules must be explicitly configured to 796 allow invocation by a non-recovery session. 798 3.2.8. Operation 800 The server MUST determine the exact nodes in the running 801 configuration datastore that are actually different and only check 802 "create", "update", and "delete" access permissions for this set of 803 nodes, which could be empty. 805 For example, if a session can read the entire datastore but only 806 change one leaf, that session needs to be able to edit and commit 807 that one leaf. 809 3.2.9. Operation 811 The client is only required to have permission to execute the 812 protocol operation. No datastore permissions are 813 needed. 815 3.2.10. Operation 817 The operation does not directly alter a datastore. 818 However, it allows one session to disrupt another session that is 819 editing a datastore. 821 Access to the protocol operation is denied by default. 822 The "exec-default" leaf does not apply to this protocol operation. 823 Access control rules must be explicitly configured to allow 824 invocation by a non-recovery session. 826 3.3. Model Components 828 This section defines the conceptual components related to the access 829 control model. 831 3.3.1. Users 833 A "user" is the conceptual entity that is associated with the access 834 permissions granted to a particular session. A user is identified by 835 a string that is unique within the server. 837 As described in [RFC6241], the username string is derived from the 838 transport layer during session establishment. If the transport layer 839 cannot authenticate the user, the session is terminated. 841 3.3.2. Groups 843 Access to a specific NETCONF protocol operation is granted to a 844 session, associated with a group, not a user. 846 A group is identified by its name. All group names are unique within 847 the server. 849 Access control is applied at the level of groups. A group contains 850 zero or more group members. 852 A group member is identified by a username string. 854 The same user can be a member of multiple groups. 856 3.3.3. Emergency Recovery Session 858 The server MAY support a recovery session mechanism, which will 859 bypass all access control enforcement. This is useful for 860 restricting initial access and repairing a broken access control 861 configuration. 863 3.3.4. Global Enforcement Controls 865 There are five global controls that are used to help control how 866 access control is enforced. 868 3.3.4.1. enable-nacm Switch 870 A global "enable-nacm" on/off switch is provided to enable or disable 871 all access control enforcement. When this global switch is set to 872 "true", then all requests are checked against the access control 873 rules and only permitted if configured to allow the specific access 874 request. When this global switch is set to "false", then all access 875 requested are permitted. 877 3.3.4.2. read-default Switch 879 An on/off "read-default" switch is provided to enable or disable 880 default access to receive data in replies and notifications. When 881 the "enable-nacm" global switch is set to "true", then this global 882 switch is relevant if no matching access control rule is found to 883 explicitly permit or deny read access to the requested datastore data 884 or notification event type. 886 When this global switch is set to "permit" and no matching access 887 control rule is found for the datastore read or notification event 888 requested, then access is permitted. 890 When this global switch is set to "deny" and no matching access 891 control rule is found for the datastore read or notification event 892 requested, then access is denied. 894 3.3.4.3. write-default Switch 896 An on/off "write-default" switch is provided to enable or disable 897 default access to alter configuration data. When the "enable-nacm" 898 global switch is set to "true", then this global switch is relevant 899 if no matching access control rule is found to explicitly permit or 900 deny write access to the requested datastore data. 902 When this global switch is set to "permit" and no matching access 903 control rule is found for the datastore write requested, then access 904 is permitted. 906 When this global switch is set to "deny" and no matching access 907 control rule is found for the datastore write requested, then access 908 is denied. 910 3.3.4.4. exec-default Switch 912 An on/off "exec-default" switch is provided to enable or disable 913 default access to execute protocol operations. When the "enable- 914 nacm" global switch is set to "true", then this global switch is 915 relevant if no matching access control rule is found to explicitly 916 permit or deny access to the requested NETCONF protocol operation. 918 When this global switch is set to "permit" and no matching access 919 control rule is found for the NETCONF protocol operation requested, 920 then access is permitted. 922 When this global switch is set to "deny" and no matching access 923 control rule is found for the NETCONF protocol operation requested, 924 then access is denied. 926 3.3.4.5. enable-external-groups Switch 928 When this global switch is set to "true", the group names reported by 929 the transport layer for a session are used together with the locally 930 configured group names to determine the access control rules for the 931 session. 933 When this switch is set to "false", the group names reported by the 934 transport layer are ignored by NACM. 936 3.3.5. Access Control Rules 938 There are four types of rules available in NACM: 940 module rule: controls access for definitions in a specific YANG 941 module, identified by its name. 943 protocol operation rule: controls access for a specific protocol 944 operation, identified by its YANG module and name. 946 data node rule: controls access for a specific data node, identified 947 by its path location within the conceptual XML document for the 948 data node. 950 notification rule: controls access for a specific notification event 951 type, identified by its YANG module and name. 953 3.4. Access Control Enforcement Procedures 955 There are seven separate phases that need to be addressed, four of 956 which are related to the NETCONF message processing model 957 (Section 3.1.3). In addition, the initial startup mode for a NETCONF 958 server, session establishment, and "access-denied" error-handling 959 procedures also need to be considered. 961 The server MUST use the access control rules in effect at the time it 962 starts processing the message. The same access control rules MUST 963 stay in effect for the processing of the entire message. 965 3.4.1. Initial Operation 967 Upon the very first startup of the NETCONF server, the access control 968 configuration will probably not be present. If it isn't, a server 969 MUST NOT allow any write access to any session role except a recovery 970 session. 972 Access rules are enforced any time a request is initiated from a user 973 session. Access control is not enforced for server-initiated access 974 requests, such as the initial load of the running configuration 975 datastore, during bootup. 977 3.4.2. Session Establishment 979 The access control model applies specifically to the well-formed XML 980 content transferred between a client and a server after session 981 establishment has been completed and after the exchange has 982 been successfully completed. 984 Once session establishment is completed and a user has been 985 authenticated, the transport layer reports the username and a 986 possibly empty set of group names associated with the user to the 987 NETCONF server. The NETCONF server will enforce the access control 988 rules, based on the supplied username, group names, and the 989 configuration data stored on the server. 991 3.4.3. "access-denied" Error Handling 993 The "access-denied" error-tag is generated when the access control 994 system denies access to either a request to invoke a protocol 995 operation or a request to perform a particular access operation on 996 the configuration datastore. 998 A server MUST NOT include any information the client is not allowed 999 to read in any elements within the response. 1001 3.4.4. Incoming RPC Message Validation 1003 The diagram below shows the basic conceptual structure of the access 1004 control processing model for incoming NETCONF messages within a 1005 server. 1007 NETCONF server 1008 +------------+ 1009 | XML | 1010 | message | 1011 | dispatcher | 1012 +------------+ 1013 | 1014 | 1015 V 1016 +------------+ 1017 | NC-base NS | 1018 | | 1019 +------------+ 1020 | | | 1021 | | +-------------------------+ 1022 | +------------+ | 1023 V V V 1024 +-----------+ +---------------+ +------------+ 1025 | Vendor NS | | NC-base NS | | NC-base NS | 1026 | | | | | | 1027 +-----------+ +---------------+ +------------+ 1028 | | 1029 | | 1030 V V 1031 +----------------------+ 1032 | | 1033 | configuration | 1034 | datastore | 1035 +----------------------+ 1037 Figure 3 1039 Access control begins with the message dispatcher. 1041 After the server validates the element and determines the 1042 namespace URI and the element name of the protocol operation being 1043 requested, the server verifies that the user is authorized to invoke 1044 the protocol operation. 1046 The server MUST separately authorize every protocol operation by 1047 following these steps: 1049 1. If the "enable-nacm" leaf is set to "false", then the protocol 1050 operation is permitted. 1052 2. If the requesting session is identified as a recovery session, 1053 then the protocol operation is permitted. 1055 3. If the requested operation is the NETCONF 1056 protocol operation, then the protocol operation is permitted. 1058 4. Check all the "group" entries for ones that contain a "user- 1059 name" entry that equals the username for the session making the 1060 request. If the "enable-external-groups" leaf is "true", add to 1061 these groups the set of groups provided by the transport layer. 1063 5. If no groups are found, continue with step 10. 1065 6. Process all rule-list entries, in the order they appear in the 1066 configuration. If a rule-list's "group" leaf-list does not 1067 match any of the user's groups, proceed to the next rule-list 1068 entry. 1070 7. For each rule-list entry found, process all rules, in order, 1071 until a rule that matches the requested access operation is 1072 found. A rule matches if all of the following criteria are met: 1074 * The rule's "module-name" leaf is "*" or equals the name of 1075 the YANG module where the protocol operation is defined. 1077 * The rule does not have a "rule-type" defined or the "rule- 1078 type" is "protocol-operation" and the "rpc-name" is "*" or 1079 equals the name of the requested protocol operation. 1081 * The rule's "access-operations" leaf has the "exec" bit set or 1082 has the special value "*". 1084 8. If a matching rule is found, then the "action" leaf is checked. 1085 If it is equal to "permit", then the protocol operation is 1086 permitted; otherwise, it is denied. 1088 9. At this point, no matching rule was found in any rule-list 1089 entry. 1091 10. If the requested protocol operation is defined in a YANG module 1092 advertised in the server capabilities and the "rpc" statement 1093 contains a "nacm:default-deny-all" statement, then the protocol 1094 operation is denied. 1096 11. If the requested protocol operation is the NETCONF or , then the protocol operation is 1098 denied. 1100 12. If the "exec-default" leaf is set to "permit", then permit the 1101 protocol operation; otherwise, deny the request. 1103 If the user is not authorized to invoke the protocol operation, then 1104 an is generated with the following information: 1106 error-tag: access-denied 1108 error-path: Identifies the requested protocol operation. The 1109 following example represents the protocol operation 1110 in the NETCONF base namespace: 1112 1114 /nc:rpc/nc:edit-config 1115 1117 If a datastore is accessed, either directly or as a side effect of 1118 the protocol operation, then the server MUST intercept the access 1119 operation and make sure the user is authorized to perform the 1120 requested access operation on the specified data, as defined in 1121 Section 3.4.5. 1123 3.4.5. Data Node Access Validation 1125 If a data node within a datastore is accessed, or an action or 1126 notification tied to a data node, then the server MUST ensure that 1127 the user is authorized to perform the requested "read", "create", 1128 "update", "delete", or "execute" access operation on the specified 1129 data node. 1131 If an action is requested to be executed, the server MUST ensure that 1132 the user is authorized to perform the "execute" access operation on 1133 the requested action. 1135 If a notification tied to a data node is generated, the server MUST 1136 ensure that the user is authorized to perform the "read" access 1137 operation on the requested notification. 1139 The data node access request is authorized by following these steps: 1141 1. If the "enable-nacm" leaf is set to "false", then the access 1142 operation is permitted. 1144 2. If the requesting session is identified as a recovery session, 1145 then the access operation is permitted. 1147 3. Check all the "group" entries for ones that contain a "user- 1148 name" entry that equals the username for the session making the 1149 request. If the "enable-external-groups" leaf is "true", add to 1150 these groups the set of groups provided by the transport layer. 1152 4. If no groups are found, continue with step 9. 1154 5. Process all rule-list entries, in the order they appear in the 1155 configuration. If a rule-list's "group" leaf-list does not 1156 match any of the user's groups, proceed to the next rule-list 1157 entry. 1159 6. For each rule-list entry found, process all rules, in order, 1160 until a rule that matches the requested access operation is 1161 found. A rule matches if all of the following criteria are met: 1163 * The rule's "module-name" leaf is "*" or equals the name of 1164 the YANG module where the requested data node is defined. 1166 * The rule does not have a "rule-type" defined or the "rule- 1167 type" is "data-node" and the "path" matches the requested 1168 data node, action node, or notification node. 1170 * For a "read" access operation, the rule's "access-operations" 1171 leaf has the "read" bit set or has the special value "*". 1173 * For a "create" access operation, the rule's "access- 1174 operations" leaf has the "create" bit set or has the special 1175 value "*". 1177 * For a "delete" access operation, the rule's "access- 1178 operations" leaf has the "delete" bit set or has the special 1179 value "*". 1181 * For an "update" access operation, the rule's "access- 1182 operations" leaf has the "update" bit set or has the special 1183 value "*". 1185 * For an "execute" access operation, the rule's "access- 1186 operations" leaf has the "exec" bit set or has the special 1187 value "*". 1189 7. If a matching rule is found, then the "action" leaf is checked. 1190 If it is equal to "permit", then the data node access is 1191 permitted; otherwise, it is denied. For a "read" access 1192 operation, "denied" means that the requested data is not 1193 returned in the reply. 1195 8. At this point, no matching rule was found in any rule-list 1196 entry. 1198 9. For a "read" access operation, if the requested data node is 1199 defined in a YANG module advertised in the server capabilities 1200 and the data definition statement contains a "nacm:default-deny- 1201 all" statement, then the requested data node is not included in 1202 the reply. 1204 10. For a "write" access operation, if the requested data node is 1205 defined in a YANG module advertised in the server capabilities 1206 and the data definition statement contains a "nacm:default-deny- 1207 write" or a "nacm:default-deny-all" statement, then the data 1208 node access request is denied. 1210 11. For a "read" access operation, if the "read-default" leaf is set 1211 to "permit", then include the requested data node in the reply; 1212 otherwise, do not include the requested data node in the reply. 1214 12. For a "write" access operation, if the "write-default" leaf is 1215 set to "permit", then permit the data node access request; 1216 otherwise, deny the request. 1218 13. For an "execute" access operation, if the "exec-default" leaf is 1219 set to "permit", then permit the request; otherwise, deny the 1220 request. 1222 3.4.6. Outgoing Authorization 1224 Configuration of access control rules specifically for descendant 1225 nodes of the notification event type element are outside the scope of 1226 this document. If the user is authorized to receive the notification 1227 event type, then it is also authorized to receive any data it 1228 contains. 1230 If the notification is specified within a data subtree, as specified 1231 in [RFC7950], then read access to the notification is required. 1232 Processing continues as described in Section 3.4.5. 1234 The following figure shows the conceptual message processing model 1235 for outgoing messages. 1237 NETCONF server 1238 +------------+ 1239 | XML | 1240 | message | 1241 | generator | 1242 +------------+ 1243 ^ 1244 | 1245 +----------------+ 1246 | | 1247 | generator | 1248 +----------------+ 1249 ^ 1250 | 1251 +=================+ 1252 | | 1253 | access control | 1254 | | 1255 +=================+ 1256 ^ 1257 | 1258 +------------------------+ 1259 | server instrumentation | 1260 +------------------------+ 1261 | ^ 1262 V | 1263 +----------------------+ 1264 | configuration | 1265 | datastore | 1266 +----------------------+ 1268 Figure 4 1270 The generation of a notification for a specific subscription 1271 [RFC5277] is authorized by following these steps: 1273 1. If the "enable-nacm" leaf is set to "false", then the 1274 notification is permitted. 1276 2. If the session is identified as a recovery session, then the 1277 notification is permitted. 1279 3. If the notification is the NETCONF or 1280 event type [RFC5277], then the 1281 notification is permitted. 1283 4. Check all the "group" entries for ones that contain a "user- 1284 name" entry that equals the username for the session making the 1285 request. If the "enable-external-groups" leaf is "true", add to 1286 these groups the set of groups provided by the transport layer. 1288 5. If no groups are found, continue with step 10. 1290 6. Process all rule-list entries, in the order they appear in the 1291 configuration. If a rule-list's "group" leaf-list does not 1292 match any of the user's groups, proceed to the next rule-list 1293 entry. 1295 7. For each rule-list entry found, process all rules, in order, 1296 until a rule that matches the requested access operation is 1297 found. A rule matches if all of the following criteria are met: 1299 * The rule's "module-name" leaf is "*" or equals the name of 1300 the YANG module where the notification is defined. 1302 * The rule does not have a "rule-type" defined or the "rule- 1303 type" is "notification" and the "notification-name" is "*" or 1304 equals the name of the notification. 1306 * The rule's "access-operations" leaf has the "read" bit set or 1307 has the special value "*". 1309 8. If a matching rule is found, then the "action" leaf is checked. 1310 If it is equal to "permit", then permit the notification; 1311 otherwise, drop the notification for the associated 1312 subscription. 1314 9. Otherwise, no matching rule was found in any rule-list entry. 1316 10. If the requested notification is defined in a YANG module 1317 advertised in the server capabilities and the "notification" 1318 statement contains a "nacm:default-deny-all" statement, then the 1319 notification is dropped for the associated subscription. 1321 11. If the "read-default" leaf is set to "permit", then permit the 1322 notification; otherwise, drop the notification for the 1323 associated subscription. 1325 3.5. Data Model Definitions 1326 3.5.1. Data Organization 1328 The following diagram highlights the contents and structure of the 1329 NACM YANG module. 1331 module: ietf-netconf-acm 1332 +--rw nacm 1333 +--rw enable-nacm? boolean 1334 +--rw read-default? action-type 1335 +--rw write-default? action-type 1336 +--rw exec-default? action-type 1337 +--rw enable-external-groups? boolean 1338 +--ro denied-operations yang:zero-based-counter32 1339 +--ro denied-data-writes yang:zero-based-counter32 1340 +--ro denied-notifications yang:zero-based-counter32 1341 +--rw groups 1342 | +--rw group* [name] 1343 | +--rw name group-name-type 1344 | +--rw user-name* user-name-type 1345 +--rw rule-list* [name] 1346 +--rw name string 1347 +--rw group* union 1348 +--rw rule* [name] 1349 +--rw name string 1350 +--rw module-name? union 1351 +--rw (rule-type)? 1352 | +--:(protocol-operation) 1353 | | +--rw rpc-name? union 1354 | +--:(notification) 1355 | | +--rw notification-name? union 1356 | +--:(data-node) 1357 | +--rw path node-instance-identifier 1358 +--rw access-operations? union 1359 +--rw action action-type 1360 +--rw comment? string 1362 3.5.2. YANG Module 1364 The following YANG module specifies the normative NETCONF content 1365 that MUST by supported by the server. 1367 The "ietf-netconf-acm" YANG module imports typedefs from [RFC6991]. 1369 file "ietf-netconf-acm@2017-10-26.yang" 1370 module ietf-netconf-acm { 1372 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-acm"; 1373 prefix "nacm"; 1375 import ietf-yang-types { 1376 prefix yang; 1377 } 1379 organization 1380 "IETF NETCONF (Network Configuration) Working Group"; 1382 contact 1383 "WG Web: 1384 WG List: 1386 Author: Andy Bierman 1387 1389 Author: Martin Bjorklund 1390 "; 1392 description 1393 "Network Configuration Access Control Model. 1395 Copyright (c) 2012, 2017 IETF Trust and the persons 1396 identified as authors of the code. All rights reserved. 1398 Redistribution and use in source and binary forms, with or 1399 without modification, is permitted pursuant to, and subject 1400 to the license terms contained in, the Simplified BSD 1401 License set forth in Section 4.c of the IETF Trust's 1402 Legal Provisions Relating to IETF Documents 1403 (http://trustee.ietf.org/license-info). 1405 This version of this YANG module is part of RFC XXXX; see 1406 the RFC itself for full legal notices."; 1408 revision "2017-10-26" { 1409 description 1410 "Added support for YANG 1.1 actions and notifications tied to 1411 data nodes. Clarify how NACM extensions can be used by other 1412 data models."; 1413 reference 1414 "RFC XXXX: Network Configuration Protocol (NETCONF) 1415 Access Control Model"; 1416 } 1418 revision "2012-02-22" { 1419 description 1420 "Initial version"; 1421 reference 1422 "RFC 6536: Network Configuration Protocol (NETCONF) 1423 Access Control Model"; 1424 } 1426 /* 1427 * Extension statements 1428 */ 1430 extension default-deny-write { 1431 description 1432 "Used to indicate that the data model node 1433 represents a sensitive security system parameter. 1435 If present, the NETCONF server will only allow the designated 1436 'recovery session' to have write access to the node. An 1437 explicit access control rule is required for all other users. 1439 If the NACM module is used, then it must be enabled (i.e., 1440 /nacm/enable-nacm object equals 'true'), or this extension 1441 is ignored. 1443 The 'default-deny-write' extension MAY appear within a data 1444 definition statement. It is ignored otherwise."; 1445 } 1447 extension default-deny-all { 1448 description 1449 "Used to indicate that the data model node 1450 controls a very sensitive security system parameter. 1452 If present, the NETCONF server will only allow the designated 1453 'recovery session' to have read, write, or execute access to the 1454 node. An explicit access control rule is required for all other 1455 users. 1457 If the NACM module is used, then it must be enabled (i.e., 1458 /nacm/enable-nacm object equals 'true'), or this extension 1459 is ignored. 1461 The 'default-deny-all' extension MAY appear within a data 1462 definition statement, 'rpc' statement, or 'notification' 1463 statement. It is ignored otherwise."; 1464 } 1466 /* 1467 * Derived types 1468 */ 1470 typedef user-name-type { 1471 type string { 1472 length "1..max"; 1473 } 1474 description 1475 "General Purpose Username string."; 1476 } 1478 typedef matchall-string-type { 1479 type string { 1480 pattern '\*'; 1481 } 1482 description 1483 "The string containing a single asterisk '*' is used 1484 to conceptually represent all possible values 1485 for the particular leaf using this data type."; 1486 } 1488 typedef access-operations-type { 1489 type bits { 1490 bit create { 1491 description 1492 "Any protocol operation that creates a 1493 new data node."; 1494 } 1495 bit read { 1496 description 1497 "Any protocol operation or notification that 1498 returns the value of a data node."; 1499 } 1500 bit update { 1501 description 1502 "Any protocol operation that alters an existing 1503 data node."; 1504 } 1505 bit delete { 1506 description 1507 "Any protocol operation that removes a data node."; 1508 } 1509 bit exec { 1510 description 1511 "Execution access to the specified protocol operation."; 1512 } 1513 } 1514 description 1515 "Access Operation."; 1517 } 1519 typedef group-name-type { 1520 type string { 1521 length "1..max"; 1522 pattern '[^\*].*'; 1523 } 1524 description 1525 "Name of administrative group to which 1526 users can be assigned."; 1527 } 1529 typedef action-type { 1530 type enumeration { 1531 enum permit { 1532 description 1533 "Requested action is permitted."; 1534 } 1535 enum deny { 1536 description 1537 "Requested action is denied."; 1538 } 1539 } 1540 description 1541 "Action taken by the server when a particular 1542 rule matches."; 1543 } 1545 typedef node-instance-identifier { 1546 type yang:xpath1.0; 1547 description 1548 "Path expression used to represent a special 1549 data node, action, or notification instance identifier 1550 string. 1552 A node-instance-identifier value is an 1553 unrestricted YANG instance-identifier expression. 1554 All the same rules as an instance-identifier apply 1555 except predicates for keys are optional. If a key 1556 predicate is missing, then the node-instance-identifier 1557 represents all possible server instances for that key. 1559 This XPath expression is evaluated in the following context: 1561 o The set of namespace declarations are those in scope on 1562 the leaf element where this type is used. 1564 o The set of variable bindings contains one variable, 1565 'USER', which contains the name of the user of the current 1566 session. 1568 o The function library is the core function library, but 1569 note that due to the syntax restrictions of an 1570 instance-identifier, no functions are allowed. 1572 o The context node is the root node in the data tree. 1574 The accessible tree includes actions and notifications tied 1575 to data nodes."; 1576 } 1578 /* 1579 * Data definition statements 1580 */ 1582 container nacm { 1583 nacm:default-deny-all; 1585 description 1586 "Parameters for NETCONF Access Control Model."; 1588 leaf enable-nacm { 1589 type boolean; 1590 default true; 1591 description 1592 "Enables or disables all NETCONF access control 1593 enforcement. If 'true', then enforcement 1594 is enabled. If 'false', then enforcement 1595 is disabled."; 1596 } 1598 leaf read-default { 1599 type action-type; 1600 default "permit"; 1601 description 1602 "Controls whether read access is granted if 1603 no appropriate rule is found for a 1604 particular read request."; 1605 } 1607 leaf write-default { 1608 type action-type; 1609 default "deny"; 1610 description 1611 "Controls whether create, update, or delete access 1612 is granted if no appropriate rule is found for a 1613 particular write request."; 1614 } 1616 leaf exec-default { 1617 type action-type; 1618 default "permit"; 1619 description 1620 "Controls whether exec access is granted if no appropriate 1621 rule is found for a particular protocol operation request."; 1622 } 1624 leaf enable-external-groups { 1625 type boolean; 1626 default true; 1627 description 1628 "Controls whether the server uses the groups reported by the 1629 NETCONF transport layer when it assigns the user to a set of 1630 NACM groups. If this leaf has the value 'false', any group 1631 names reported by the transport layer are ignored by the 1632 server."; 1633 } 1635 leaf denied-operations { 1636 type yang:zero-based-counter32; 1637 config false; 1638 mandatory true; 1639 description 1640 "Number of times since the server last restarted that a 1641 protocol operation request was denied."; 1642 } 1644 leaf denied-data-writes { 1645 type yang:zero-based-counter32; 1646 config false; 1647 mandatory true; 1648 description 1649 "Number of times since the server last restarted that a 1650 protocol operation request to alter 1651 a configuration datastore was denied."; 1652 } 1654 leaf denied-notifications { 1655 type yang:zero-based-counter32; 1656 config false; 1657 mandatory true; 1658 description 1659 "Number of times since the server last restarted that 1660 a notification was dropped for a subscription because 1661 access to the event type was denied."; 1662 } 1664 container groups { 1665 description 1666 "NETCONF Access Control Groups."; 1668 list group { 1669 key name; 1671 description 1672 "One NACM Group Entry. This list will only contain 1673 configured entries, not any entries learned from 1674 any transport protocols."; 1676 leaf name { 1677 type group-name-type; 1678 description 1679 "Group name associated with this entry."; 1680 } 1682 leaf-list user-name { 1683 type user-name-type; 1684 description 1685 "Each entry identifies the username of 1686 a member of the group associated with 1687 this entry."; 1688 } 1689 } 1690 } 1692 list rule-list { 1693 key "name"; 1694 ordered-by user; 1695 description 1696 "An ordered collection of access control rules."; 1698 leaf name { 1699 type string { 1700 length "1..max"; 1701 } 1702 description 1703 "Arbitrary name assigned to the rule-list."; 1704 } 1705 leaf-list group { 1706 type union { 1707 type matchall-string-type; 1708 type group-name-type; 1710 } 1711 description 1712 "List of administrative groups that will be 1713 assigned the associated access rights 1714 defined by the 'rule' list. 1716 The string '*' indicates that all groups apply to the 1717 entry."; 1718 } 1720 list rule { 1721 key "name"; 1722 ordered-by user; 1723 description 1724 "One access control rule. 1726 Rules are processed in user-defined order until a match is 1727 found. A rule matches if 'module-name', 'rule-type', and 1728 'access-operations' match the request. If a rule 1729 matches, the 'action' leaf determines if access is granted 1730 or not."; 1732 leaf name { 1733 type string { 1734 length "1..max"; 1735 } 1736 description 1737 "Arbitrary name assigned to the rule."; 1738 } 1740 leaf module-name { 1741 type union { 1742 type matchall-string-type; 1743 type string; 1744 } 1745 default "*"; 1746 description 1747 "Name of the module associated with this rule. 1749 This leaf matches if it has the value '*' or if the 1750 object being accessed is defined in the module with the 1751 specified module name."; 1752 } 1753 choice rule-type { 1754 description 1755 "This choice matches if all leafs present in the rule 1756 match the request. If no leafs are present, the 1757 choice matches all requests."; 1759 case protocol-operation { 1760 leaf rpc-name { 1761 type union { 1762 type matchall-string-type; 1763 type string; 1764 } 1765 description 1766 "This leaf matches if it has the value '*' or if 1767 its value equals the requested protocol operation 1768 name."; 1769 } 1770 } 1771 case notification { 1772 leaf notification-name { 1773 type union { 1774 type matchall-string-type; 1775 type string; 1776 } 1777 description 1778 "This leaf matches if it has the value '*' or if its 1779 value equals the requested notification name."; 1780 } 1781 } 1782 case data-node { 1783 leaf path { 1784 type node-instance-identifier; 1785 mandatory true; 1786 description 1787 "Data Node Instance Identifier associated with the 1788 data node, action, or notification controlled by 1789 this rule. 1791 Configuration data or state data instance 1792 identifiers start with a top-level data node. A 1793 complete instance identifier is required for this 1794 type of path value. 1796 The special value '/' refers to all possible 1797 datastore contents."; 1798 } 1799 } 1800 } 1802 leaf access-operations { 1803 type union { 1804 type matchall-string-type; 1805 type access-operations-type; 1806 } 1807 default "*"; 1808 description 1809 "Access operations associated with this rule. 1811 This leaf matches if it has the value '*' or if the 1812 bit corresponding to the requested operation is set."; 1813 } 1815 leaf action { 1816 type action-type; 1817 mandatory true; 1818 description 1819 "The access control action associated with the 1820 rule. If a rule is determined to match a 1821 particular request, then this object is used 1822 to determine whether to permit or deny the 1823 request."; 1824 } 1826 leaf comment { 1827 type string; 1828 description 1829 "A textual description of the access rule."; 1830 } 1831 } 1832 } 1833 } 1834 } 1836 1838 Figure 5 1840 3.6. IANA Considerations 1842 This document reuses the URI for "ietf-netconf-acm" in "The IETF XML 1843 Registry". 1845 This document updates the module registration in the "YANG Module 1846 Names" registry to reference this RFC instead of RFC 6536. Following 1847 the format in [RFC6020], the following has been registered. 1849 Name: ietf-netconf-acm 1850 Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1851 Prefix: nacm 1852 reference: RFC XXXX 1854 3.7. Security Considerations 1856 The YANG module defined in this document is designed to be accessed 1857 via network management protocols such as NETCONF [RFC6241] or 1858 RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport 1859 layer, and the mandatory-to-implement secure transport is Secure 1860 Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the 1861 mandatory-to-implement secure transport is TLS [RFC5246]. 1863 The NETCONF access control model [RFCXXXX] provides the means to 1864 restrict access for particular NETCONF or RESTCONF users to a 1865 preconfigured subset of all available NETCONF or RESTCONF protocol 1866 operations and content. 1868 There is a risk related to the lack of access control enforcement for 1869 the RESTCONF OPTIONS method. The risk here is that the response to 1870 OPTIONS may vary based on the presence or absence of a resource 1871 corresponding to the URL's path. If this is the case, then it can be 1872 used to trivially probe for the presence or absence of values within 1873 a tree. Therefore, a server MUST NOT vary their OPTIONS responses 1874 based on the existence of the underlying resource, which would 1875 indicate the presence or absence of resource instances. 1877 There are a number of data nodes defined in this YANG module that are 1878 writable/creatable/deletable (i.e., config true, which is the 1879 default). These data nodes may be considered sensitive or vulnerable 1880 in some network environments. Write operations (e.g., edit-config) 1881 to these data nodes without proper protection can have a negative 1882 effect on network operations. These are the subtrees and data nodes 1883 and their sensitivity/vulnerability: 1885 o /nacm : the entire /nacm subtree is related to security. Refer to 1886 the following sections for more details. 1888 This section highlights the issues for an administrator to consider 1889 when configuring a NETCONF server with NACM. 1891 3.7.1. NACM Configuration and Monitoring Considerations 1893 Configuration of the access control system is highly sensitive to 1894 system security. A server may choose not to allow any user 1895 configuration to some portions of it, such as the global security 1896 level or the groups that allowed access to system resources. 1898 By default, NACM enforcement is enabled. By default, "read" access 1899 to all datastore contents is enabled (unless "nacm:default-deny-all" 1900 is specified for the data definition), and "exec" access is enabled 1901 for safe protocol operations. An administrator needs to ensure that 1902 NACM is enabled and also decide if the default access parameters are 1903 set appropriately. Make sure the following data nodes are properly 1904 configured: 1906 o /nacm/enable-nacm (default "true") 1908 o /nacm/read-default (default "permit") 1910 o /nacm/write-default (default "deny") 1912 o /nacm/exec-default (default "permit") 1914 An administrator needs to restrict write access to all configurable 1915 objects within this data model. 1917 If write access is allowed for configuration of access control rules, 1918 then care needs to be taken not to disrupt the access control 1919 enforcement. For example, if the NACM access control rules are 1920 edited directly within the running configuration datastore (i.e., 1921 :writable-running capability is supported and used), then care needs 1922 to be taken not to allow unintended access while the edits are being 1923 done. 1925 An administrator needs to make sure that the translation from a 1926 transport- or implementation-dependent user identity to a NACM 1927 username is unique and correct. This requirement is specified in 1928 detail in Section 2.2 of [RFC6241]. 1930 An administrator needs to be aware that the YANG data structures 1931 representing access control rules (/nacm/rule-list and /nacm/rule- 1932 list/rule) are ordered by the client. The server will evaluate the 1933 access control rules according to their relative conceptual order 1934 within the running configuration datastore. 1936 Note that the /nacm/groups data structure contains the administrative 1937 group names used by the server. These group names may be configured 1938 locally and/or provided through an external protocol, such as RADIUS 1939 [RFC2865][RFC5607]. 1941 An administrator needs to be aware of the security properties of any 1942 external protocol used by the transport layer to determine group 1943 names. For example, if this protocol does not protect against man- 1944 in-the-middle attacks, an attacker might be able to inject group 1945 names that are configured in NACM, so that a user gets more 1946 permissions than it should. In such cases, the administrator may 1947 wish to disable the usage of such group names, by setting /nacm/ 1948 enable-external-groups to "false". 1950 An administrator needs to restrict read access to the following 1951 objects within this data model, as they reveal access control 1952 configuration that could be considered sensitive. 1954 o /nacm/enable-nacm 1956 o /nacm/read-default 1958 o /nacm/write-default 1960 o /nacm/exec-default 1962 o /nacm/enable-external-groups 1964 o /nacm/groups 1966 o /nacm/rule-list 1968 3.7.2. General Configuration Issues 1970 There is a risk that invocation of non-standard protocol operations 1971 will have undocumented side effects. An administrator needs to 1972 construct access control rules such that the configuration datastore 1973 is protected from such side effects. 1975 It is possible for a session with some write access (e.g., allowed to 1976 invoke ), but without any access to a particular 1977 datastore subtree containing sensitive data, to determine the 1978 presence or non-presence of that data. This can be done by 1979 repeatedly issuing some sort of edit request (create, update, or 1980 delete) and possibly receiving "access-denied" errors in response. 1981 These "fishing" attacks can identify the presence or non-presence of 1982 specific sensitive data even without the "error-path" field being 1983 present within the response. 1985 It may be possible for the set of NETCONF capabilities on the server 1986 to change over time. If so, then there is a risk that new protocol 1987 operations, notifications, and/or datastore content have been added 1988 to the device. An administrator needs to be sure the access control 1989 rules are correct for the new content in this case. Mechanisms to 1990 detect NETCONF capability changes on a specific device are outside 1991 the scope of this document. 1993 It is possible that the data model definition itself (e.g., YANG 1994 when-stmt) will help an unauthorized session determine the presence 1995 or even value of sensitive data nodes by examining the presence and 1996 values of different data nodes. 1998 There is a risk that non-standard protocol operations, or even the 1999 standard protocol operation, may return data that "aliases" or 2000 "copies" sensitive data from a different data object. There may 2001 simply be multiple data model definitions that expose or even 2002 configure the same underlying system instrumentation. 2004 A data model may contain external keys (e.g., YANG leafref), which 2005 expose values from a different data structure. An administrator 2006 needs to be aware of sensitive data models that contain leafref 2007 nodes. This entails finding all the leafref objects that "point" at 2008 the sensitive data (i.e., "path-stmt" values) that implicitly or 2009 explicitly include the sensitive data node. 2011 It is beyond the scope of this document to define access control 2012 enforcement procedures for underlying device instrumentation that may 2013 exist to support the NETCONF server operation. An administrator can 2014 identify each protocol operation that the server provides and decide 2015 if it needs any access control applied to it. 2017 This document incorporates the optional use of a recovery session 2018 mechanism, which can be used to bypass access control enforcement in 2019 emergencies, such as NACM configuration errors that disable all 2020 access to the server. The configuration and identification of such a 2021 recovery session mechanism are implementation-specific and outside 2022 the scope of this document. An administrator needs to be aware of 2023 any recovery session mechanisms available on the device and make sure 2024 they are used appropriately. 2026 It is possible for a session to disrupt configuration management, 2027 even without any write access to the configuration, by locking the 2028 datastore. This may be done to ensure all or part of the 2029 configuration remains stable while it is being retrieved, or it may 2030 be done as a "denial-of-service" attack. There is no way for the 2031 server to know the difference. An administrator may wish to restrict 2032 "exec" access to the following protocol operations: 2034 o 2036 o 2038 o 2040 o 2042 3.7.3. Data Model Design Considerations 2044 Designers need to clearly identify any sensitive data, notifications, 2045 or protocol operations defined within a YANG module. For such 2046 definitions, a "nacm:default-deny-write" or "nacm:default-deny-all" 2047 statement ought to be present, in addition to a clear description of 2048 the security risks. 2050 Protocol operations need to be properly documented by the data model 2051 designer, so it is clear to administrators what data nodes (if any) 2052 are affected by the protocol operation and what information (if any) 2053 is returned in the message. 2055 Data models ought to be designed so that different access levels for 2056 input parameters to protocol operations are not required. Use of 2057 generic protocol operations should be avoided, and if different 2058 access levels are needed, separate protocol operations should be 2059 defined instead. 2061 4. References 2063 4.1. Normative References 2065 [I-D.ietf-netmod-revised-datastores] 2066 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2067 and R. Wilton, "Network Management Datastore 2068 Architecture", draft-ietf-netmod-revised-datastores-02 2069 (work in progress), May 2017. 2071 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2072 Requirement Levels", BCP 14, RFC 2119, 2073 DOI 10.17487/RFC2119, March 1997, . 2076 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2077 (TLS) Protocol Version 1.2", RFC 5246, 2078 DOI 10.17487/RFC5246, August 2008, . 2081 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2082 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2083 . 2085 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2086 the Network Configuration Protocol (NETCONF)", RFC 6020, 2087 DOI 10.17487/RFC6020, October 2010, . 2090 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2091 and A. Bierman, Ed., "Network Configuration Protocol 2092 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2093 . 2095 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2096 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2097 . 2099 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2100 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2101 . 2103 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2104 Protocol (HTTP/1.1): Message Syntax and Routing", 2105 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2106 . 2108 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2109 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2110 . 2112 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2113 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2114 . 2116 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2117 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2118 May 2017, . 2120 4.2. Informative References 2122 [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, 2123 "Remote Authentication Dial In User Service (RADIUS)", 2124 RFC 2865, DOI 10.17487/RFC2865, June 2000, 2125 . 2127 [RFC5607] Nelson, D. and G. Weber, "Remote Authentication Dial-In 2128 User Service (RADIUS) Authorization for Network Access 2129 Server (NAS) Management", RFC 5607, DOI 10.17487/RFC5607, 2130 July 2009, . 2132 Appendix A. Change Log 2134 -- RFC Ed.: remove this section before publication. 2136 The NACM issue tracker can be found here: https://github.com/netconf- 2137 wg/rfc6536bis/issues 2139 A.1. v07 to v08 2141 o Address IESG review comments 2143 A.2. v06 to v07 2145 o Clarify CRUDX protocol operation mapping 2147 A.3. v05 to v06 2149 o Change title to remove the word NETCONF 2151 o Clarify data rule case in YANG module 2153 o Update security considerations section 2155 A.4. v04 to v05 2157 o Clarify NETCONF protocol operation vs added operation via 2158 additional YANG modules 2160 o Change term 'NETCONF transport layer' to 'transport layer' 2162 o Clarify that read access operations are not coupled to specific 2163 protocol operations 2165 o Update date of YANG module so it matches new revision date 2167 A.5. v03 to v04 2169 o Fix revision date mismatch for extracting YANG module 2171 A.6. v02 to v03 2173 o Clarify NACM YANG extensions for use outside NACM 2175 A.7. v01 to v02 2177 o Corrected section title for changes since RFC 6536. 2179 o Added section 'Mapping New Datastores to NACM'. 2181 o Changed term NETCONF datastore to datastore/ 2183 o Removed text about RESTCONF and a conceptual datastore. 2185 A.8. v00 to v01 2187 o Updated RESTCONF reference 2189 A.9. v00 2191 o Renamed document from draft-bierman-netconf-rfc6536bis-01 to 2192 draft-ietf-netconf-rfc6536bis-00. 2194 Appendix B. Usage Examples 2196 The following XML snippets are provided as examples only, to 2197 demonstrate how NACM can be configured to perform some access control 2198 tasks. 2200 B.1. Example 2202 There needs to be at least one entry in order for any of the 2203 access control rules to be useful. 2205 The following XML shows arbitrary groups and is not intended to 2206 represent any particular use case. 2208 2209 2210 2211 admin 2212 admin 2213 andy 2214 2216 2217 limited 2218 wilma 2219 bam-bam 2220 2222 2223 guest 2224 guest 2225 guest@example.com 2226 2227 2228 2230 This example shows three groups: 2232 admin: The "admin" group contains two users named "admin" and 2233 "andy". 2235 limited: The "limited" group contains two users named "wilma" and 2236 "bam-bam". 2238 guest: The "guest" group contains two users named "guest" and 2239 "guest@example.com". 2241 B.2. Module Rule Example 2243 Module rules are used to control access to all the content defined in 2244 a specific module. A module rule has the leaf set, but 2245 no case in the "rule-type" choice. 2247 2248 2249 guest-acl 2250 guest 2252 2253 deny-ncm 2254 ietf-netconf-monitoring 2255 * 2256 deny 2257 2258 Do not allow guests any access to the NETCONF 2259 monitoring information. 2260 2261 2262 2264 2265 limited-acl 2266 limited 2268 2269 permit-ncm 2270 ietf-netconf-monitoring 2271 read 2272 permit 2273 2274 Allow read access to the NETCONF 2275 monitoring information. 2276 2277 2278 2279 permit-exec 2280 * 2281 exec 2282 permit 2283 2284 Allow invocation of the 2285 supported server operations. 2286 2287 2288 2290 2291 admin-acl 2292 admin 2294 2295 permit-all 2296 * 2297 * 2298 permit 2299 2300 Allow the admin group complete access to all 2301 operations and data. 2302 2303 2304 2305 2307 This example shows four module rules: 2309 deny-ncm: This rule prevents the "guest" group from reading any 2310 monitoring information in the "ietf-netconf-monitoring" YANG 2311 module. 2313 permit-ncm: This rule allows the "limited" group to read the "ietf- 2314 netconf-monitoring" YANG module. 2316 permit-exec: This rule allows the "limited" group to invoke any 2317 protocol operation supported by the server. 2319 permit-all: This rule allows the "admin" group complete access to 2320 all content in the server. No subsequent rule will match for the 2321 "admin" group because of this module rule. 2323 B.3. Protocol Operation Rule Example 2325 Protocol operation rules are used to control access to a specific 2326 protocol operation. 2328 2329 2330 guest-limited-acl 2331 limited 2332 guest 2334 2335 deny-kill-session 2336 ietf-netconf 2337 kill-session 2338 exec 2339 deny 2340 2341 Do not allow the limited or guest group 2342 to kill another session. 2343 2344 2345 2346 deny-delete-config 2347 ietf-netconf 2348 delete-config 2349 exec 2350 deny 2351 2352 Do not allow limited or guest group 2353 to delete any configurations. 2354 2355 2356 2358 2359 limited-acl 2360 limited 2362 2363 permit-edit-config 2364 ietf-netconf 2365 edit-config 2366 exec 2367 permit 2368 2369 Allow the limited group to edit the configuration. 2370 2371 2372 2374 2376 This example shows three protocol operation rules: 2378 deny-kill-session: This rule prevents the "limited" or "guest" 2379 groups from invoking the NETCONF protocol 2380 operation. 2382 deny-delete-config: This rule prevents the "limited" or "guest" 2383 groups from invoking the NETCONF protocol 2384 operation. 2386 permit-edit-config: This rule allows the "limited" group to invoke 2387 the NETCONF protocol operation. This rule will have 2388 no real effect unless the "exec-default" leaf is set to "deny". 2390 B.4. Data Node Rule Example 2392 Data node rules are used to control access to specific (config and 2393 non-config) data nodes within the NETCONF content provided by the 2394 server. 2396 2397 2398 guest-acl 2399 guest 2401 2402 deny-nacm 2403 2404 /n:nacm 2405 2406 * 2407 deny 2408 2409 Deny the guest group any access to the /nacm data. 2410 2411 2412 2414 2415 limited-acl 2416 limited 2418 2419 permit-acme-config 2420 2421 /acme:acme-netconf/acme:config-parameters 2422 2423 2424 read create update delete 2425 2426 permit 2427 2428 Allow the limited group complete access to the acme 2429 NETCONF configuration parameters. Showing long form 2430 of 'access-operations' instead of shorthand. 2431 2432 2433 2435 2436 guest-limited-acl 2437 guest 2438 limited 2440 2441 permit-dummy-interface 2442 2443 /acme:interfaces/acme:interface[acme:name='dummy'] 2444 2445 read update 2446 permit 2447 2448 Allow the limited and guest groups read 2449 and update access to the dummy interface. 2450 2451 2452 2454 2455 admin-acl 2456 admin 2457 2458 permit-interface 2459 2460 /acme:interfaces/acme:interface 2461 2462 * 2463 permit 2464 2465 Allow admin full access to all acme interfaces. 2466 2467 2468 2469 2471 This example shows four data node rules: 2473 deny-nacm: This rule denies the "guest" group any access to the 2474 subtree. Note that the default namespace is only 2475 applicable because this subtree is defined in the same namespace 2476 as the element. 2478 permit-acme-config: This rule gives the "limited" group read-write 2479 access to the acme . 2481 permit-dummy-interface: This rule gives the "limited" and "guest" 2482 groups read-update access to the acme entry named 2483 "dummy". This entry cannot be created or deleted by these groups, 2484 just altered. 2486 permit-interface: This rule gives the "admin" group read-write 2487 access to all acme entries. 2489 B.5. Notification Rule Example 2491 Notification rules are used to control access to a specific 2492 notification event type. 2494 2495 2496 sys-acl 2497 limited 2498 guest 2500 2501 deny-config-change 2502 acme-system 2503 sys-config-change 2504 read 2505 deny 2506 2507 Do not allow the guest or limited groups 2508 to receive config change events. 2509 2510 2511 2512 2514 This example shows one notification rule: 2516 deny-config-change: This rule prevents the "limited" or "guest" 2517 groups from receiving the acme event type. 2519 Authors' Addresses 2521 Andy Bierman 2522 YumaWorks 2523 685 Cochran St. 2524 Suite #160 2525 Simi Valley, CA 93065 2526 USA 2528 EMail: andy@yumaworks.com 2529 Martin Bjorklund 2530 Tail-f Systems 2532 EMail: mbj@tail-f.com