idnits 2.17.1 draft-ietf-netconf-rfc6536bis-01.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 (March 10, 2017) is 2575 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 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 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: September 11, 2017 March 10, 2017 8 Network Configuration Protocol (NETCONF) Access Control Model 9 draft-ietf-netconf-rfc6536bis-01 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 September 11, 2017. 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 6535 . . . . . . . . . . . . . . . . . 5 61 2. Access Control Design Objectives . . . . . . . . . . . . . . 6 62 2.1. Access Control Points . . . . . . . . . . . . . . . . . . 6 63 2.2. Simplicity . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.3. Procedural Interface . . . . . . . . . . . . . . . . . . 7 65 2.4. Datastore Access . . . . . . . . . . . . . . . . . . . . 7 66 2.5. Users and Groups . . . . . . . . . . . . . . . . . . . . 7 67 2.6. Maintenance . . . . . . . . . . . . . . . . . . . . . . . 8 68 2.7. Configuration Capabilities . . . . . . . . . . . . . . . 8 69 2.8. Identifying Security-Sensitive Content . . . . . . . . . 8 70 3. NETCONF Access Control Model (NACM) . . . . . . . . . . . . . 9 71 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 9 72 3.1.1. Features . . . . . . . . . . . . . . . . . . . . . . 9 73 3.1.2. External Dependencies . . . . . . . . . . . . . . . . 10 74 3.1.3. Message Processing Model . . . . . . . . . . . . . . 10 75 3.2. Datastore Access . . . . . . . . . . . . . . . . . . . . 13 76 3.2.1. Access Rights . . . . . . . . . . . . . . . . . . . . 13 77 3.2.2. RESTCONF Methods . . . . . . . . . . . . . . . . . . 13 78 3.2.3. and Operations . . . . . . . . . . 14 79 3.2.4. Operation . . . . . . . . . . . . . . . 15 80 3.2.5. Operation . . . . . . . . . . . . . . . 16 81 3.2.6. Operation . . . . . . . . . . . . . . 16 82 3.2.7. Operation . . . . . . . . . . . . . . . . . 17 83 3.2.8. Operation . . . . . . . . . . . . . 17 84 3.2.9. Operation . . . . . . . . . . . . . . 17 85 3.3. Model Components . . . . . . . . . . . . . . . . . . . . 17 86 3.3.1. Users . . . . . . . . . . . . . . . . . . . . . . . . 17 87 3.3.2. Groups . . . . . . . . . . . . . . . . . . . . . . . 17 88 3.3.3. Emergency Recovery Session . . . . . . . . . . . . . 18 89 3.3.4. Global Enforcement Controls . . . . . . . . . . . . . 18 90 3.3.4.1. enable-nacm Switch . . . . . . . . . . . . . . . 18 91 3.3.4.2. read-default Switch . . . . . . . . . . . . . . . 18 92 3.3.4.3. write-default Switch . . . . . . . . . . . . . . 19 93 3.3.4.4. exec-default Switch . . . . . . . . . . . . . . . 19 94 3.3.4.5. enable-external-groups Switch . . . . . . . . . . 19 95 3.3.5. Access Control Rules . . . . . . . . . . . . . . . . 19 96 3.4. Access Control Enforcement Procedures . . . . . . . . . . 20 97 3.4.1. Initial Operation . . . . . . . . . . . . . . . . . . 20 98 3.4.2. Session Establishment . . . . . . . . . . . . . . . . 20 99 3.4.3. "access-denied" Error Handling . . . . . . . . . . . 21 100 3.4.4. Incoming RPC Message Validation . . . . . . . . . . . 21 101 3.4.5. Data Node Access Validation . . . . . . . . . . . . . 23 102 3.4.6. Outgoing Authorization . . . . . . . . 25 103 3.5. Data Model Definitions . . . . . . . . . . . . . . . . . 28 104 3.5.1. Data Organization . . . . . . . . . . . . . . . . . . 28 105 3.5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . 28 106 3.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 38 107 3.7. Security Considerations . . . . . . . . . . . . . . . . . 38 108 3.7.1. NACM Configuration and Monitoring Considerations . . 39 109 3.7.2. General Configuration Issues . . . . . . . . . . . . 40 110 3.7.3. Data Model Design Considerations . . . . . . . . . . 42 111 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 112 4.1. Normative References . . . . . . . . . . . . . . . . . . 42 113 4.2. Informative References . . . . . . . . . . . . . . . . . 43 114 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 44 115 A.1. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 44 116 A.2. v00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 117 Appendix B. Usage Examples . . . . . . . . . . . . . . . . . . . 44 118 B.1. Example . . . . . . . . . . . . . . . . . . . . 44 119 B.2. Module Rule Example . . . . . . . . . . . . . . . . . . . 45 120 B.3. Protocol Operation Rule Example . . . . . . . . . . . . . 47 121 B.4. Data Node Rule Example . . . . . . . . . . . . . . . . . 49 122 B.5. Notification Rule Example . . . . . . . . . . . . . . . . 51 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 125 1. Introduction 127 The NETCONF and RESTCONF protocols do not provide any standard 128 mechanisms to restrict the protocol operations and content that each 129 user is authorized to access. 131 There is a need for interoperable management of the controlled access 132 to administrator-selected portions of the available NETCONF or 133 RESTCONF content within a particular server. 135 This document addresses access control mechanisms for the Operations 136 and Content layers of NETCONF, as defined in [RFC6241], and RESTCONF, 137 as defined in [RFC8040]. It contains three main sections: 139 1. Access Control Design Objectives 141 2. NETCONF Access Control Model (NACM) 143 3. YANG Data Model (ietf-netconf-acm.yang) 144 YANG version 1.1 [RFC7950] adds two new constructs that need special 145 access control handling. The "action" statement is similar to the 146 "rpc" statement, except it is located within a data node. The 147 "notification" statement can also be located within a data node. 149 1.1. Terminology 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 153 document are to be interpreted as described in [RFC2119]. 155 The following terms are defined in [RFC6241] and are not redefined 156 here: 158 o client 160 o datastore 162 o protocol operation 164 o server 166 o session 168 o user 170 The following terms are defined in [RFC7950] and are not redefined 171 here: 173 o action 175 o data node 177 o data definition statement 179 The following terms are defined in [RFC8040] and are not redefined 180 here: 182 o data resource 184 o datastore resource 186 o operation resource 188 o target resource 190 The following term is defined in [RFC7230] and is not redefined here: 192 o request URI 194 The following terms are used throughout this document: 196 access control: A security feature provided by the NETCONF server 197 that allows an administrator to restrict access to a subset of all 198 NETCONF protocol operations and data, based on various criteria. 200 access control model (ACM): A conceptual model used to configure and 201 monitor the access control procedures desired by the administrator 202 to enforce a particular access control policy. 204 access control rule: The criterion used to determine if a particular 205 NETCONF protocol operation will be permitted or denied. 207 access operation: How a request attempts to access a conceptual 208 object. One of "none", "read", "create", "delete", "update", or 209 "execute". 211 data node hierarchy: The hierarchy of data nodes that identifies the 212 specific "action" or "notification" node in the datastore. 214 recovery session: A special administrative session that is given 215 unlimited NETCONF access and is exempt from all access control 216 enforcement. The mechanism(s) used by a server to control and 217 identify whether or not a session is a recovery session are 218 implementation specific and outside the scope of this document. 220 write access: A shorthand for the "create", "delete", and "update" 221 access operations. 223 1.2. Changes Since RFC 6535 225 The NACM procedures and data model have been updated to support new 226 data modeling capabilities in the version 1.1. of the YANG data 227 modeling language. The "action" and "notification" statements can be 228 used within data nodes to define data-model specific operations and 229 notifications. 231 An important use-case for these new YANG statements is the increased 232 access control granularity that can be achieved over top-level "rpc" 233 and "notification" statements. The new "action" and "notification" 234 statements are used within data nodes, and access to the action or 235 notification can be restricted to specific instances of these data 236 nodes. 238 Support for the RESTCONF protocol has been added. The RESTCONF 239 operations are similar to the NETCONF operations, so a simple mapping 240 to the existing NACM procedures and data model is possible. 242 2. Access Control Design Objectives 244 This section documents the design objectives for the NETCONF Access 245 Control Model presented in Section 3. 247 2.1. Access Control Points 249 NETCONF allows new protocol operations to be added at any time, and 250 the YANG Data Modeling Language supports this feature. It is not 251 possible to design an ACM for NETCONF that only focuses on a static 252 set of protocol operations, like some other protocols. Since few 253 assumptions can be made about an arbitrary protocol operation, the 254 NETCONF architectural server components need to be protected at three 255 conceptual control points. 257 These access control points, described in Figure 1, are as follows: 259 protocol operation: Permission to invoke specific protocol 260 operations. 262 datastore: Permission to read and/or alter specific data nodes 263 within any datastore. 265 notification: Permission to receive specific notification event 266 types. 268 +-------------+ +-------------+ 269 client | protocol | | data node | 270 request --> | operation | -------------> | access | 271 | allowed? | datastore | allowed? | 272 +-------------+ or state +-------------+ 273 data access 275 +----------------+ 276 | notification | 277 event --> | allowed? | 278 +----------------+ 280 Figure 1 282 2.2. Simplicity 284 There is concern that a complicated ACM will not be widely deployed 285 because it is too hard to use. It needs to be easy to do simple 286 things and possible to do complex things, instead of hard to do 287 everything. 289 Configuration of the access control system needs to be as simple as 290 possible. Simple and common tasks need to be easy to configure and 291 require little expertise or domain-specific knowledge. Complex tasks 292 are possible using additional mechanisms, which may require 293 additional expertise. 295 A single set of access control rules ought to be able to control all 296 types of NETCONF protocol operation invocation, all datastore access, 297 and all notification events. 299 Access control ought to be defined with a small and familiar set of 300 permissions, while still allowing full control of NETCONF datastore 301 access. 303 2.3. Procedural Interface 305 The NETCONF protocol uses a remote procedure call model and an 306 extensible set of protocol operations. Access control for any 307 possible protocol operation is necessary. 309 2.4. Datastore Access 311 It is necessary to control access to specific nodes and subtrees 312 within the NETCONF datastore, regardless of which protocol operation, 313 standard or proprietary, was used to access the datastore. 315 2.5. Users and Groups 317 It is necessary that access control rules for a single user or a 318 configurable group of users can be configured. 320 The ACM needs to support the concept of administrative groups, to 321 support the well-established distinction between a root account and 322 other types of less-privileged conceptual user accounts. These 323 groups need to be configurable by the administrator. 325 It is necessary that the user-to-group mapping can be delegated to a 326 central server, such as a RADIUS server [RFC2865][RFC5607]. Since 327 authentication is performed by the NETCONF transport layer and RADIUS 328 performs authentication and service authorization at the same time, 329 the underlying NETCONF transport needs to be able to report a set of 330 group names associated with the user to the server. It is necessary 331 that the administrator can disable the usage of these group names 332 within the ACM. 334 2.6. Maintenance 336 It ought to be possible to disable part or all of the access control 337 model enforcement procedures without deleting any access control 338 rules. 340 2.7. Configuration Capabilities 342 Suitable configuration and monitoring mechanisms are needed to allow 343 an administrator to easily manage all aspects of the ACM's behavior. 344 A standard data model, suitable for use with the 345 protocol operation, needs to be available for this purpose. 347 Access control rules to restrict access operations on specific 348 subtrees within the configuration datastore need to be supported. 350 2.8. Identifying Security-Sensitive Content 352 One of the most important aspects of the data model documentation, 353 and biggest concerns during deployment, is the identification of 354 security-sensitive content. This applies to protocol operations in 355 NETCONF, not just data and notifications. 357 It is mandatory for security-sensitive objects to be documented in 358 the Security Considerations section of an RFC. This is nice, but it 359 is not good enough, for the following reasons: 361 o This documentation-only approach forces administrators to study 362 the RFC and determine if there are any potential security risks 363 introduced by a new data model. 365 o If any security risks are identified, then the administrator must 366 study some more RFC text and determine how to mitigate the 367 security risk(s). 369 o The ACM on each server must be configured to mitigate the security 370 risks, e.g., require privileged access to read or write the 371 specific data identified in the Security Considerations section. 373 o If the ACM is not pre-configured, then there will be a time window 374 of vulnerability after the new data model is loaded and before the 375 new access control rules for that data model are configured, 376 enabled, and debugged. 378 Often, the administrator just wants to disable default access to the 379 secure content, so no inadvertent or malicious changes can be made to 380 the server. This allows the default rules to be more lenient, 381 without significantly increasing the security risk. 383 A data model designer needs to be able to use machine-readable 384 statements to identify NETCONF content, which needs to be protected 385 by default. This will allow client and server tools to automatically 386 identify data-model-specific security risks, by denying access to 387 sensitive data unless the user is explicitly authorized to perform 388 the requested access operation. 390 3. NETCONF Access Control Model (NACM) 392 3.1. Introduction 394 This section provides a high-level overview of the access control 395 model structure. It describes the NETCONF protocol message 396 processing model and the conceptual access control requirements 397 within that model. 399 3.1.1. Features 401 The NACM data model provides the following features: 403 o Independent control of remote procedure call (RPC), action, data, 404 and notification access. 406 o Simple access control rules configuration data model that is easy 407 to use. 409 o The concept of an emergency recovery session is supported, but 410 configuration of the server for this purpose is beyond the scope 411 of this document. An emergency recovery session will bypass all 412 access control enforcement, in order to allow it to initialize or 413 repair the NACM configuration. 415 o A simple and familiar set of datastore permissions is used. 417 o Support for YANG security tagging (e.g., "nacm:default-deny-write" 418 statement) allows default security modes to automatically exclude 419 sensitive data. 421 o Separate default access modes for read, write, and execute 422 permissions. 424 o Access control rules are applied to configurable groups of users. 426 o The access control enforcement procedures can be disabled during 427 operation, without deleting any access control rules, in order to 428 debug operational problems. 430 o Access control rules are simple to configure. 432 o The number of denied protocol operation requests and denied 433 datastore write requests can be monitored by the client. 435 o Simple unconstrained YANG instance identifiers are used to 436 configure access control rules for specific data nodes. 438 3.1.2. External Dependencies 440 The NETCONF protocol [RFC6241] is used for network management 441 purposes within this document. 443 The RESTCONF protocol [RFC8040] is used for network management 444 purposes within this document. 446 The YANG Data Modeling Language [RFC7950] is used to define the data 447 models for use with the NETCONF or RESTCONF protocols. YANG is also 448 used to define the data model in this document. 450 3.1.3. Message Processing Model 452 The following diagram shows the conceptual message flow model, 453 including the points at which access control is applied during 454 NETCONF message processing. 456 RESTCONF operations are mapped to the access control model based on 457 the HTTP method and resource class used in the operation. For 458 example, a POST method on a data resource is considered "write data 459 node" access, but a POST method on an operation resource is 460 considered "operation" access. 462 +-------------------------+ 463 | session | 464 | (username) | 465 +-------------------------+ 466 | ^ 467 V | 468 +--------------+ +---------------+ 469 | message | | message | 470 | dispatcher | | generator | 471 +--------------+ +---------------+ 472 | | ^ ^ 473 | V | | 474 | +=============+ | | 475 | | pre-read | | | 476 | | data node | | | 477 | | acc. ctl | | | 478 | +=============+ | | 479 | | | | 480 V V | | 481 +===========+ +-------------+ +----------------+ 482 | operation |---> | reply | | | 483 | acc. ctl | | generator | | generator | 484 +===========+ +-------------+ +----------------+ 485 | ^ ^ ^ 486 V +------+ | | 487 +-----------+ | +=============+ +================+ 488 | operation | | | read | | | 489 | processor |-+ | data node | | access ctl | 490 | | | acc. ctl | | | 491 +-----------+ +=============+ +================+ 492 | | ^ ^ ^ 493 V +----------------+ | | | 494 +===========+ | | | +============+ 495 | write | | | | | pre-read | 496 | data node | | | | | data node | 497 | acc. ctl | -----------+ | | | | acc. ctl | 498 +===========+ | | | | +============+ 499 | | | | | ^ 500 V V V | | | 501 +---------------+ +-------------------+ 502 | configuration | ---> | server | 503 | datastore | | instrumentation | 504 | | <--- | | 505 +---------------+ +-------------------+ 507 Figure 2 509 The following high-level sequence of conceptual processing steps is 510 executed for each received message, if access control 511 enforcement is enabled: 513 o For each active session, access control is applied individually to 514 all messages (except ) received by the 515 server, unless the session is identified as a recovery session. 517 o If the operation defined in [RFC7950] is invoked, then 518 read access is required for all instances in the hierarchy of data 519 nodes that identifies the specific action in the datastore, and 520 execute access is required for the action node. If the user is 521 not authorized to read all the specified data nodes and execute 522 the action, then the request is rejected with an "access-denied" 523 error. 525 o Otherwise, if the user is not authorized to execute the specified 526 protocol operation, then the request is rejected with an "access- 527 denied" error. 529 o If the configuration datastore or conceptual state data is 530 accessed by the protocol operation, then the server checks if the 531 client is authorized to access the nodes in the datastore. If the 532 user is not authorized to perform the requested access operation 533 on the requested data, then the request is rejected with an 534 "access-denied" error. 536 The following sequence of conceptual processing steps is executed for 537 each generated notification event, if access control enforcement is 538 enabled: 540 o Server instrumentation generates a notification for a particular 541 subscription. 543 o If the notification statement is specified within a data subtree, 544 as specified in [RFC7950], then read access is required for all 545 instances in the hierarchy of data nodes that identifies the 546 specific notification in the datastore, and read access is 547 required for the notification node. If the user is not authorized 548 to read all the specified data nodes and the notification node, 549 then the notification is dropped for that subscription. 551 o If the notification statement is a top-level statement, the 552 notification access control enforcer checks the notification event 553 type, and if it is one that the user is not authorized to read, 554 then the notification is dropped for that subscription. 556 3.2. Datastore Access 558 The same access control rules apply to all datastores, for example, 559 the candidate configuration datastore or the running configuration 560 datastore. 562 Only the standard NETCONF datastores (candidate, running, and 563 startup) are controlled by NACM. Local or remote files or datastores 564 accessed via the parameter are not controlled by NACM. A 565 standalone RESTCONF server (i.e., not co-located with a NETCONF 566 server) applies NACM rules to a conceptual datastore, since 567 datastores are not supported in RESTCONF. 569 3.2.1. Access Rights 571 A small set of hard-wired datastore access rights is needed to 572 control access to all possible NETCONF protocol operations, including 573 vendor extensions to the standard protocol operation set. 575 The "CRUDX" model can support all NETCONF protocol operations: 577 o Create: allows the client to add a new data node instance to a 578 datastore. 580 o Read: allows the client to read a data node instance from a 581 datastore or receive the notification event type. 583 o Update: allows the client to update an existing data node instance 584 in a datastore. 586 o Delete: allows the client to delete a data node instance from a 587 datastore. 589 o eXec: allows the client to execute the operation. 591 3.2.2. RESTCONF Methods 593 The RESTCONF protocol utilizes HTTP methods to perform datastore 594 operations, similar to the NETCONF protocol. The NACM procedures 595 were originally written for NETCONF protocol operations so the 596 RESTCONF methods are mapped to NETCONF operations for the purpose of 597 access control processing. The enforcement procedures described 598 within this document apply to both protocols unless explicitly stated 599 otherwise. 601 The request URI needs to be considered when processing RESTCONF 602 requests on data resources: 604 o For HEAD and GET requests, any data nodes which are ancestor nodes 605 of the target resource are considered to be part of the retrieval 606 request for access control purposes. 608 o For PUT, PATCH, and DELETE requests, any data nodes which are 609 ancestor nodes of the target resource are not considered to be 610 part of the edit request for access control purposes. The edit 611 operation for these nodes is considered to be 'none'. The edit 612 begins at the target resource. 614 o For POST requests on data resources, any data nodes which are 615 specified in the request URI, including the target resource, are 616 not considered to be part of the edit request for access control 617 purposes. The edit operation for these nodes is considered to be 618 'none'. The edit begins at a child node of the target resource, 619 specified in the message body. 621 Not all RESTCONF methods are subject to access control. The 622 following table specifies how each method is mapped to NETCONF 623 protocol operations. The value 'none' indicates that NACM is not 624 applied at all to the specific RESTCONF method. 626 +---------+-----------------+---------------------+-----------------+ 627 | method | resource class | NETCONF operation | Edit operation | 628 +---------+-----------------+---------------------+-----------------+ 629 | OPTIONS | all | none | N/A | 630 | HEAD | all | | N/A | 631 | GET | all | | N/A | 632 | POST | datastore, data | | create | 633 | POST | operation | specified operation | N/A | 634 | PUT | data | | create, replace | 635 | PUT | datastore | | replace | 636 | PATCH | data, datastore | | merge | 637 | DELETE | data | | delete | 638 +---------+-----------------+---------------------+-----------------+ 640 Table 1: Mapping RESTCONF Methods to NETCONF 642 3.2.3. and Operations 644 Data nodes to which the client does not have read access are silently 645 omitted from the message. This is done to allow NETCONF 646 filters for and to function properly, instead of 647 causing an "access-denied" error because the filter criteria would 648 otherwise include unauthorized read access to some data nodes. For 649 NETCONF filtering purposes, the selection criteria is applied to the 650 subset of nodes that the user is authorized to read, not the entire 651 datastore. 653 3.2.4. Operation 655 The NACM access rights are not directly coupled to the 656 "operation" attribute, although they are similar. Instead, a NACM 657 access right applies to all protocol operations that would result in 658 a particular access operation to the target datastore. This section 659 describes how these access rights apply to the specific access 660 operations supported by the protocol operation. 662 If the effective access operation is "none" (i.e., default- 663 operation="none") for a particular data node, then no access control 664 is applied to that data node. This is required to allow access to a 665 subtree within a larger data structure. For example, a user may be 666 authorized to create a new "/interfaces/interface" list entry but not 667 be authorized to create or delete its parent container 668 ("/interfaces"). If the "/interfaces" container already exists in 669 the target datastore, then the effective operation will be "none" for 670 the "/interfaces" node if an "/interfaces/interface" list entry is 671 edited. 673 If the protocol operation would result in the creation of a datastore 674 node and the user does not have "create" access permission for that 675 node, the protocol operation is rejected with an "access-denied" 676 error. 678 If the protocol operation would result in the deletion of a datastore 679 node and the user does not have "delete" access permission for that 680 node, the protocol operation is rejected with an "access-denied" 681 error. 683 If the protocol operation would result in the modification of a 684 datastore node and the user does not have "update" access permission 685 for that node, the protocol operation is rejected with an "access- 686 denied" error. 688 A "merge" or "replace" operation may include data nodes 689 that do not alter portions of the existing datastore. For example, a 690 container or list node may be present for naming purposes but does 691 not actually alter the corresponding datastore node. These unaltered 692 data nodes are ignored by the server and do not require any access 693 rights by the client. 695 A "merge" operation may include data nodes but not 696 include particular child data nodes that are present in the 697 datastore. These missing data nodes within the scope of a "merge" 698 operation are ignored by the server and do not require 699 any access rights by the client. 701 The contents of specific restricted datastore nodes MUST NOT be 702 exposed in any elements within the reply. 704 3.2.5. Operation 706 Access control for the protocol operation requires 707 special consideration because the administrator may be replacing the 708 entire target datastore. 710 If the source of the protocol operation is the running 711 configuration datastore and the target is the startup configuration 712 datastore, the client is only required to have permission to execute 713 the protocol operation. 715 Otherwise: 717 o If the source of the operation is a datastore, then 718 data nodes to which the client does not have read access are 719 silently omitted. 721 o If the target of the operation is a datastore, the 722 client needs access to the modified nodes, specifically: 724 * If the protocol operation would result in the creation of a 725 datastore node and the user does not have "create" access 726 permission for that node, the protocol operation is rejected 727 with an "access-denied" error. 729 * If the protocol operation would result in the deletion of a 730 datastore node and the user does not have "delete" access 731 permission for that node, the protocol operation is rejected 732 with an "access-denied" error. 734 * If the protocol operation would result in the modification of a 735 datastore node and the user does not have "update" access 736 permission for that node, the protocol operation is rejected 737 with an "access-denied" error. 739 3.2.6. Operation 741 Access to the protocol operation is denied by 742 default. The "exec-default" leaf does not apply to this protocol 743 operation. Access control rules must be explicitly configured to 744 allow invocation by a non-recovery session. 746 3.2.7. Operation 748 The server MUST determine the exact nodes in the running 749 configuration datastore that are actually different and only check 750 "create", "update", and "delete" access permissions for this set of 751 nodes, which could be empty. 753 For example, if a session can read the entire datastore but only 754 change one leaf, that session needs to be able to edit and commit 755 that one leaf. 757 3.2.8. Operation 759 The client is only required to have permission to execute the 760 protocol operation. No datastore permissions are 761 needed. 763 3.2.9. Operation 765 The operation does not directly alter a datastore. 766 However, it allows one session to disrupt another session that is 767 editing a datastore. 769 Access to the protocol operation is denied by default. 770 The "exec-default" leaf does not apply to this protocol operation. 771 Access control rules must be explicitly configured to allow 772 invocation by a non-recovery session. 774 3.3. Model Components 776 This section defines the conceptual components related to the access 777 control model. 779 3.3.1. Users 781 A "user" is the conceptual entity that is associated with the access 782 permissions granted to a particular session. A user is identified by 783 a string that is unique within the server. 785 As described in [RFC6241], the username string is derived from the 786 transport layer during session establishment. If the transport layer 787 cannot authenticate the user, the session is terminated. 789 3.3.2. Groups 791 Access to a specific NETCONF protocol operation is granted to a 792 session, associated with a group, not a user. 794 A group is identified by its name. All group names are unique within 795 the server. 797 A group member is identified by a username string. 799 The same user can be a member of multiple groups. 801 3.3.3. Emergency Recovery Session 803 The server MAY support a recovery session mechanism, which will 804 bypass all access control enforcement. This is useful for 805 restricting initial access and repairing a broken access control 806 configuration. 808 3.3.4. Global Enforcement Controls 810 There are five global controls that are used to help control how 811 access control is enforced. 813 3.3.4.1. enable-nacm Switch 815 A global "enable-nacm" on/off switch is provided to enable or disable 816 all access control enforcement. When this global switch is set to 817 "true", then all requests are checked against the access control 818 rules and only permitted if configured to allow the specific access 819 request. When this global switch is set to "false", then all access 820 requested are permitted. 822 3.3.4.2. read-default Switch 824 An on/off "read-default" switch is provided to enable or disable 825 default access to receive data in replies and notifications. When 826 the "enable-nacm" global switch is set to "true", then this global 827 switch is relevant if no matching access control rule is found to 828 explicitly permit or deny read access to the requested NETCONF 829 datastore data or notification event type. 831 When this global switch is set to "permit" and no matching access 832 control rule is found for the NETCONF datastore read or notification 833 event requested, then access is permitted. 835 When this global switch is set to "deny" and no matching access 836 control rule is found for the NETCONF datastore read or notification 837 event requested, then access is denied. 839 3.3.4.3. write-default Switch 841 An on/off "write-default" switch is provided to enable or disable 842 default access to alter configuration data. When the "enable-nacm" 843 global switch is set to "true", then this global switch is relevant 844 if no matching access control rule is found to explicitly permit or 845 deny write access to the requested NETCONF datastore data. 847 When this global switch is set to "permit" and no matching access 848 control rule is found for the NETCONF datastore write requested, then 849 access is permitted. 851 When this global switch is set to "deny" and no matching access 852 control rule is found for the NETCONF datastore write requested, then 853 access is denied. 855 3.3.4.4. exec-default Switch 857 An on/off "exec-default" switch is provided to enable or disable 858 default access to execute protocol operations. When the "enable- 859 nacm" global switch is set to "true", then this global switch is 860 relevant if no matching access control rule is found to explicitly 861 permit or deny access to the requested NETCONF protocol operation. 863 When this global switch is set to "permit" and no matching access 864 control rule is found for the NETCONF protocol operation requested, 865 then access is permitted. 867 When this global switch is set to "deny" and no matching access 868 control rule is found for the NETCONF protocol operation requested, 869 then access is denied. 871 3.3.4.5. enable-external-groups Switch 873 When this global switch is set to "true", the group names reported by 874 the NETCONF transport layer for a session are used together with the 875 locally configured group names to determine the access control rules 876 for the session. 878 When this switch is set to "false", the group names reported by the 879 NETCONF transport layer are ignored by NACM. 881 3.3.5. Access Control Rules 883 There are four types of rules available in NACM: 885 module rule: controls access for definitions in a specific YANG 886 module, identified by its name. 888 protocol operation rule: controls access for a specific protocol 889 operation, identified by its YANG module and name. 891 data node rule: controls access for a specific data node, identified 892 by its path location within the conceptual XML document for the 893 data node. 895 notification rule: controls access for a specific notification event 896 type, identified by its YANG module and name. 898 3.4. Access Control Enforcement Procedures 900 There are seven separate phases that need to be addressed, four of 901 which are related to the NETCONF message processing model 902 (Section 3.1.3). In addition, the initial startup mode for a NETCONF 903 server, session establishment, and "access-denied" error-handling 904 procedures also need to be considered. 906 The server MUST use the access control rules in effect at the time it 907 starts processing the message. The same access control rules MUST 908 stay in effect for the processing of the entire message. 910 3.4.1. Initial Operation 912 Upon the very first startup of the NETCONF server, the access control 913 configuration will probably not be present. If it isn't, a server 914 MUST NOT allow any write access to any session role except a recovery 915 session. 917 Access rules are enforced any time a request is initiated from a user 918 session. Access control is not enforced for server-initiated access 919 requests, such as the initial load of the running datastore, during 920 bootup. 922 3.4.2. Session Establishment 924 The access control model applies specifically to the well-formed XML 925 content transferred between a client and a server after session 926 establishment has been completed and after the exchange has 927 been successfully completed. 929 Once session establishment is completed and a user has been 930 authenticated, the NETCONF transport layer reports the username and a 931 possibly empty set of group names associated with the user to the 932 NETCONF server. The NETCONF server will enforce the access control 933 rules, based on the supplied username, group names, and the 934 configuration data stored on the server. 936 3.4.3. "access-denied" Error Handling 938 The "access-denied" error-tag is generated when the access control 939 system denies access to either a request to invoke a protocol 940 operation or a request to perform a particular access operation on 941 the configuration datastore. 943 A server MUST NOT include any information the client is not allowed 944 to read in any elements within the response. 946 3.4.4. Incoming RPC Message Validation 948 The diagram below shows the basic conceptual structure of the access 949 control processing model for incoming NETCONF messages within a 950 server. 952 NETCONF server 953 +------------+ 954 | XML | 955 | message | 956 | dispatcher | 957 +------------+ 958 | 959 | 960 V 961 +------------+ 962 | NC-base NS | 963 | | 964 +------------+ 965 | | | 966 | | +-------------------------+ 967 | +------------+ | 968 V V V 969 +-----------+ +---------------+ +------------+ 970 | Vendor NS | | NC-base NS | | NC-base NS | 971 | | | | | | 972 +-----------+ +---------------+ +------------+ 973 | | 974 | | 975 V V 976 +----------------------+ 977 | | 978 | configuration | 979 | datastore | 980 +----------------------+ 982 Figure 3 984 Access control begins with the message dispatcher. 986 After the server validates the element and determines the 987 namespace URI and the element name of the protocol operation being 988 requested, the server verifies that the user is authorized to invoke 989 the protocol operation. 991 The server MUST separately authorize every protocol operation by 992 following these steps: 994 1. If the "enable-nacm" leaf is set to "false", then the protocol 995 operation is permitted. 997 2. If the requesting session is identified as a recovery session, 998 then the protocol operation is permitted. 1000 3. If the requested operation is the NETCONF 1001 protocol operation, then the protocol operation is permitted. 1003 4. Check all the "group" entries for ones that contain a "user- 1004 name" entry that equals the username for the session making the 1005 request. If the "enable-external-groups" leaf is "true", add to 1006 these groups the set of groups provided by the transport layer. 1008 5. If no groups are found, continue with step 10. 1010 6. Process all rule-list entries, in the order they appear in the 1011 configuration. If a rule-list's "group" leaf-list does not 1012 match any of the user's groups, proceed to the next rule-list 1013 entry. 1015 7. For each rule-list entry found, process all rules, in order, 1016 until a rule that matches the requested access operation is 1017 found. A rule matches if all of the following criteria are met: 1019 * The rule's "module-name" leaf is "*" or equals the name of 1020 the YANG module where the protocol operation is defined. 1022 * The rule does not have a "rule-type" defined or the "rule- 1023 type" is "protocol-operation" and the "rpc-name" is "*" or 1024 equals the name of the requested protocol operation. 1026 * The rule's "access-operations" leaf has the "exec" bit set or 1027 has the special value "*". 1029 8. If a matching rule is found, then the "action" leaf is checked. 1030 If it is equal to "permit", then the protocol operation is 1031 permitted; otherwise, it is denied. 1033 9. At this point, no matching rule was found in any rule-list 1034 entry. 1036 10. If the requested protocol operation is defined in a YANG module 1037 advertised in the server capabilities and the "rpc" statement 1038 contains a "nacm:default-deny-all" statement, then the protocol 1039 operation is denied. 1041 11. If the requested protocol operation is the NETCONF or , then the protocol operation is 1043 denied. 1045 12. If the "exec-default" leaf is set to "permit", then permit the 1046 protocol operation; otherwise, deny the request. 1048 If the user is not authorized to invoke the protocol operation, then 1049 an is generated with the following information: 1051 error-tag: access-denied 1053 error-path: Identifies the requested protocol operation. The 1054 following example represents the protocol operation 1055 in the NETCONF base namespace: 1057 1059 /nc:rpc/nc:edit-config 1060 1062 If a datastore is accessed, either directly or as a side effect of 1063 the protocol operation, then the server MUST intercept the access 1064 operation and make sure the user is authorized to perform the 1065 requested access operation on the specified data, as defined in 1066 Section 3.4.5. 1068 3.4.5. Data Node Access Validation 1070 If a data node within a datastore is accessed, or an action or 1071 notification tied to a data node, then the server MUST ensure that 1072 the user is authorized to perform the requested "read", "create", 1073 "update", "delete", or "execute" access operation on the specified 1074 data node. 1076 If an action is requested to be executed, the server MUST ensure that 1077 the user is authorized to perform the "execute" access operation on 1078 the requested action. 1080 If a notification tied to a data node is generated, the server MUST 1081 ensure that the user is authorized to perform the "read" access 1082 operation on the requested notification. 1084 The data node access request is authorized by following these steps: 1086 1. If the "enable-nacm" leaf is set to "false", then the access 1087 operation is permitted. 1089 2. If the requesting session is identified as a recovery session, 1090 then the access operation is permitted. 1092 3. Check all the "group" entries for ones that contain a "user- 1093 name" entry that equals the username for the session making the 1094 request. If the "enable-external-groups" leaf is "true", add to 1095 these groups the set of groups provided by the transport layer. 1097 4. If no groups are found, continue with step 9. 1099 5. Process all rule-list entries, in the order they appear in the 1100 configuration. If a rule-list's "group" leaf-list does not 1101 match any of the user's groups, proceed to the next rule-list 1102 entry. 1104 6. For each rule-list entry found, process all rules, in order, 1105 until a rule that matches the requested access operation is 1106 found. A rule matches if all of the following criteria are met: 1108 * The rule's "module-name" leaf is "*" or equals the name of 1109 the YANG module where the requested data node is defined. 1111 * The rule does not have a "rule-type" defined or the "rule- 1112 type" is "data-node" and the "path" matches the requested 1113 data node, action node, or notification node. 1115 * For a "read" access operation, the rule's "access-operations" 1116 leaf has the "read" bit set or has the special value "*". 1118 * For a "create" access operation, the rule's "access- 1119 operations" leaf has the "create" bit set or has the special 1120 value "*". 1122 * For a "delete" access operation, the rule's "access- 1123 operations" leaf has the "delete" bit set or has the special 1124 value "*". 1126 * For an "update" access operation, the rule's "access- 1127 operations" leaf has the "update" bit set or has the special 1128 value "*". 1130 * For an "execute" access operation, the rule's "access- 1131 operations" leaf has the "exec" bit set or has the special 1132 value "*". 1134 7. If a matching rule is found, then the "action" leaf is checked. 1135 If it is equal to "permit", then the data node access is 1136 permitted; otherwise, it is denied. For a "read" access 1137 operation, "denied" means that the requested data is not 1138 returned in the reply. 1140 8. At this point, no matching rule was found in any rule-list 1141 entry. 1143 9. For a "read" access operation, if the requested data node is 1144 defined in a YANG module advertised in the server capabilities 1145 and the data definition statement contains a "nacm:default-deny- 1146 all" statement, then the requested data node is not included in 1147 the reply. 1149 10. For a "write" access operation, if the requested data node is 1150 defined in a YANG module advertised in the server capabilities 1151 and the data definition statement contains a "nacm:default-deny- 1152 write" or a "nacm:default-deny-all" statement, then the data 1153 node access request is denied. 1155 11. For a "read" access operation, if the "read-default" leaf is set 1156 to "permit", then include the requested data node in the reply; 1157 otherwise, do not include the requested data node in the reply. 1159 12. For a "write" access operation, if the "write-default" leaf is 1160 set to "permit", then permit the data node access request; 1161 otherwise, deny the request. 1163 13. For an "execute" access operation, if the "exec-default" leaf is 1164 set to "permit", then permit the request; otherwise, deny the 1165 request. 1167 3.4.6. Outgoing Authorization 1169 Configuration of access control rules specifically for descendant 1170 nodes of the notification event type element are outside the scope of 1171 this document. If the user is authorized to receive the notification 1172 event type, then it is also authorized to receive any data it 1173 contains. 1175 If the notification is specified within a data subtree, as specified 1176 in [RFC7950], then read access to the notification is required. 1177 Processing continues as described in Section 3.4.5. 1179 The following figure shows the conceptual message processing model 1180 for outgoing messages. 1182 NETCONF server 1183 +------------+ 1184 | XML | 1185 | message | 1186 | generator | 1187 +------------+ 1188 ^ 1189 | 1190 +----------------+ 1191 | | 1192 | generator | 1193 +----------------+ 1194 ^ 1195 | 1196 +=================+ 1197 | | 1198 | access control | 1199 | | 1200 +=================+ 1201 ^ 1202 | 1203 +------------------------+ 1204 | server instrumentation | 1205 +------------------------+ 1206 | ^ 1207 V | 1208 +----------------------+ 1209 | configuration | 1210 | datastore | 1211 +----------------------+ 1213 Figure 4 1215 The generation of a notification for a specific subscription 1216 [RFC5277] is authorized by following these steps: 1218 1. If the "enable-nacm" leaf is set to "false", then the 1219 notification is permitted. 1221 2. If the session is identified as a recovery session, then the 1222 notification is permitted. 1224 3. If the notification is the NETCONF or 1225 event type [RFC5277], then the 1226 notification is permitted. 1228 4. Check all the "group" entries for ones that contain a "user- 1229 name" entry that equals the username for the session making the 1230 request. If the "enable-external-groups" leaf is "true", add to 1231 these groups the set of groups provided by the transport layer. 1233 5. If no groups are found, continue with step 10. 1235 6. Process all rule-list entries, in the order they appear in the 1236 configuration. If a rule-list's "group" leaf-list does not 1237 match any of the user's groups, proceed to the next rule-list 1238 entry. 1240 7. For each rule-list entry found, process all rules, in order, 1241 until a rule that matches the requested access operation is 1242 found. A rule matches if all of the following criteria are met: 1244 * The rule's "module-name" leaf is "*" or equals the name of 1245 the YANG module where the notification is defined. 1247 * The rule does not have a "rule-type" defined or the "rule- 1248 type" is "notification" and the "notification-name" is "*" or 1249 equals the name of the notification. 1251 * The rule's "access-operations" leaf has the "read" bit set or 1252 has the special value "*". 1254 8. If a matching rule is found, then the "action" leaf is checked. 1255 If it is equal to "permit", then permit the notification; 1256 otherwise, drop the notification for the associated 1257 subscription. 1259 9. Otherwise, no matching rule was found in any rule-list entry. 1261 10. If the requested notification is defined in a YANG module 1262 advertised in the server capabilities and the "notification" 1263 statement contains a "nacm:default-deny-all" statement, then the 1264 notification is dropped for the associated subscription. 1266 11. If the "read-default" leaf is set to "permit", then permit the 1267 notification; otherwise, drop the notification for the 1268 associated subscription. 1270 3.5. Data Model Definitions 1272 3.5.1. Data Organization 1274 The following diagram highlights the contents and structure of the 1275 NACM YANG module. 1277 module: ietf-netconf-acm 1278 +--rw nacm 1279 +--rw enable-nacm? boolean 1280 +--rw read-default? action-type 1281 +--rw write-default? action-type 1282 +--rw exec-default? action-type 1283 +--rw enable-external-groups? boolean 1284 +--ro denied-operations yang:zero-based-counter32 1285 +--ro denied-data-writes yang:zero-based-counter32 1286 +--ro denied-notifications yang:zero-based-counter32 1287 +--rw groups 1288 | +--rw group* [name] 1289 | +--rw name group-name-type 1290 | +--rw user-name* user-name-type 1291 +--rw rule-list* [name] 1292 +--rw name string 1293 +--rw group* union 1294 +--rw rule* [name] 1295 +--rw name string 1296 +--rw module-name? union 1297 +--rw (rule-type)? 1298 | +--:(protocol-operation) 1299 | | +--rw rpc-name? union 1300 | +--:(notification) 1301 | | +--rw notification-name? union 1302 | +--:(data-node) 1303 | +--rw path node-instance-identifier 1304 +--rw access-operations? union 1305 +--rw action action-type 1306 +--rw comment? string 1308 3.5.2. YANG Module 1310 The following YANG module specifies the normative NETCONF content 1311 that MUST by supported by the server. 1313 The "ietf-netconf-acm" YANG module imports typedefs from [RFC6991]. 1315 file "ietf-netconf-acm@2017-01-05.yang" 1316 module ietf-netconf-acm { 1317 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-acm"; 1319 prefix "nacm"; 1321 import ietf-yang-types { 1322 prefix yang; 1323 } 1325 organization 1326 "IETF NETCONF (Network Configuration) Working Group"; 1328 contact 1329 "WG Web: 1330 WG List: 1332 Author: Andy Bierman 1333 1335 Author: Martin Bjorklund 1336 "; 1338 description 1339 "NETCONF Access Control Model. 1341 Copyright (c) 2012, 2017 IETF Trust and the persons 1342 identified as authors of the code. All rights reserved. 1344 Redistribution and use in source and binary forms, with or 1345 without modification, is permitted pursuant to, and subject 1346 to the license terms contained in, the Simplified BSD 1347 License set forth in Section 4.c of the IETF Trust's 1348 Legal Provisions Relating to IETF Documents 1349 (http://trustee.ietf.org/license-info). 1351 This version of this YANG module is part of RFC XXXX; see 1352 the RFC itself for full legal notices."; 1354 revision "2017-01-05" { 1355 description 1356 "Second version"; 1357 reference 1358 "RFC XXXX: Network Configuration Protocol (NETCONF) 1359 Access Control Model"; 1360 } 1362 revision "2012-02-22" { 1363 description 1364 "Initial version"; 1365 reference 1366 "RFC 6536: Network Configuration Protocol (NETCONF) 1367 Access Control Model"; 1368 } 1370 /* 1371 * Extension statements 1372 */ 1374 extension default-deny-write { 1375 description 1376 "Used to indicate that the data model node 1377 represents a sensitive security system parameter. 1379 If present, and the NACM module is enabled (i.e., 1380 /nacm/enable-nacm object equals 'true'), the NETCONF server 1381 will only allow the designated 'recovery session' to have 1382 write access to the node. An explicit access control rule is 1383 required for all other users. 1385 The 'default-deny-write' extension MAY appear within a data 1386 definition statement. It is ignored otherwise."; 1387 } 1389 extension default-deny-all { 1390 description 1391 "Used to indicate that the data model node 1392 controls a very sensitive security system parameter. 1394 If present, and the NACM module is enabled (i.e., 1395 /nacm/enable-nacm object equals 'true'), the NETCONF server 1396 will only allow the designated 'recovery session' to have 1397 read, write, or execute access to the node. An explicit 1398 access control rule is required for all other users. 1400 The 'default-deny-all' extension MAY appear within a data 1401 definition statement, 'rpc' statement, or 'notification' 1402 statement. It is ignored otherwise."; 1403 } 1405 /* 1406 * Derived types 1407 */ 1409 typedef user-name-type { 1410 type string { 1411 length "1..max"; 1413 } 1414 description 1415 "General Purpose Username string."; 1416 } 1418 typedef matchall-string-type { 1419 type string { 1420 pattern '\*'; 1421 } 1422 description 1423 "The string containing a single asterisk '*' is used 1424 to conceptually represent all possible values 1425 for the particular leaf using this data type."; 1426 } 1428 typedef access-operations-type { 1429 type bits { 1430 bit create { 1431 description 1432 "Any protocol operation that creates a 1433 new data node."; 1434 } 1435 bit read { 1436 description 1437 "Any protocol operation or notification that 1438 returns the value of a data node."; 1439 } 1440 bit update { 1441 description 1442 "Any protocol operation that alters an existing 1443 data node."; 1444 } 1445 bit delete { 1446 description 1447 "Any protocol operation that removes a data node."; 1448 } 1449 bit exec { 1450 description 1451 "Execution access to the specified protocol operation."; 1452 } 1453 } 1454 description 1455 "NETCONF Access Operation."; 1456 } 1458 typedef group-name-type { 1459 type string { 1460 length "1..max"; 1461 pattern '[^\*].*'; 1462 } 1463 description 1464 "Name of administrative group to which 1465 users can be assigned."; 1466 } 1468 typedef action-type { 1469 type enumeration { 1470 enum permit { 1471 description 1472 "Requested action is permitted."; 1473 } 1474 enum deny { 1475 description 1476 "Requested action is denied."; 1477 } 1478 } 1479 description 1480 "Action taken by the server when a particular 1481 rule matches."; 1482 } 1484 typedef node-instance-identifier { 1485 type yang:xpath1.0; 1486 description 1487 "Path expression used to represent a special 1488 data node, action, or notification instance identifier 1489 string. 1491 A node-instance-identifier value is an 1492 unrestricted YANG instance-identifier expression. 1493 All the same rules as an instance-identifier apply 1494 except predicates for keys are optional. If a key 1495 predicate is missing, then the node-instance-identifier 1496 represents all possible server instances for that key. 1498 This XPath expression is evaluated in the following context: 1500 o The set of namespace declarations are those in scope on 1501 the leaf element where this type is used. 1503 o The set of variable bindings contains one variable, 1504 'USER', which contains the name of the user of the current 1505 session. 1507 o The function library is the core function library, but 1508 note that due to the syntax restrictions of an 1509 instance-identifier, no functions are allowed. 1511 o The context node is the root node in the data tree. 1513 The accessible tree includes actions and notifications tied to 1514 data nodes."; 1515 } 1517 /* 1518 * Data definition statements 1519 */ 1521 container nacm { 1522 nacm:default-deny-all; 1524 description 1525 "Parameters for NETCONF Access Control Model."; 1527 leaf enable-nacm { 1528 type boolean; 1529 default true; 1530 description 1531 "Enables or disables all NETCONF access control 1532 enforcement. If 'true', then enforcement 1533 is enabled. If 'false', then enforcement 1534 is disabled."; 1535 } 1537 leaf read-default { 1538 type action-type; 1539 default "permit"; 1540 description 1541 "Controls whether read access is granted if 1542 no appropriate rule is found for a 1543 particular read request."; 1544 } 1546 leaf write-default { 1547 type action-type; 1548 default "deny"; 1549 description 1550 "Controls whether create, update, or delete access 1551 is granted if no appropriate rule is found for a 1552 particular write request."; 1553 } 1555 leaf exec-default { 1556 type action-type; 1557 default "permit"; 1558 description 1559 "Controls whether exec access is granted if no appropriate 1560 rule is found for a particular protocol operation request."; 1561 } 1563 leaf enable-external-groups { 1564 type boolean; 1565 default true; 1566 description 1567 "Controls whether the server uses the groups reported by the 1568 NETCONF transport layer when it assigns the user to a set of 1569 NACM groups. If this leaf has the value 'false', any group 1570 names reported by the transport layer are ignored by the 1571 server."; 1572 } 1574 leaf denied-operations { 1575 type yang:zero-based-counter32; 1576 config false; 1577 mandatory true; 1578 description 1579 "Number of times since the server last restarted that a 1580 protocol operation request was denied."; 1581 } 1583 leaf denied-data-writes { 1584 type yang:zero-based-counter32; 1585 config false; 1586 mandatory true; 1587 description 1588 "Number of times since the server last restarted that a 1589 protocol operation request to alter 1590 a configuration datastore was denied."; 1591 } 1593 leaf denied-notifications { 1594 type yang:zero-based-counter32; 1595 config false; 1596 mandatory true; 1597 description 1598 "Number of times since the server last restarted that 1599 a notification was dropped for a subscription because 1600 access to the event type was denied."; 1601 } 1603 container groups { 1604 description 1605 "NETCONF Access Control Groups."; 1607 list group { 1608 key name; 1610 description 1611 "One NACM Group Entry. This list will only contain 1612 configured entries, not any entries learned from 1613 any transport protocols."; 1615 leaf name { 1616 type group-name-type; 1617 description 1618 "Group name associated with this entry."; 1619 } 1621 leaf-list user-name { 1622 type user-name-type; 1623 description 1624 "Each entry identifies the username of 1625 a member of the group associated with 1626 this entry."; 1627 } 1628 } 1629 } 1631 list rule-list { 1632 key "name"; 1633 ordered-by user; 1634 description 1635 "An ordered collection of access control rules."; 1637 leaf name { 1638 type string { 1639 length "1..max"; 1640 } 1641 description 1642 "Arbitrary name assigned to the rule-list."; 1643 } 1644 leaf-list group { 1645 type union { 1646 type matchall-string-type; 1647 type group-name-type; 1648 } 1649 description 1650 "List of administrative groups that will be 1651 assigned the associated access rights 1652 defined by the 'rule' list. 1654 The string '*' indicates that all groups apply to the 1655 entry."; 1656 } 1658 list rule { 1659 key "name"; 1660 ordered-by user; 1661 description 1662 "One access control rule. 1664 Rules are processed in user-defined order until a match is 1665 found. A rule matches if 'module-name', 'rule-type', and 1666 'access-operations' match the request. If a rule 1667 matches, the 'action' leaf determines if access is granted 1668 or not."; 1670 leaf name { 1671 type string { 1672 length "1..max"; 1673 } 1674 description 1675 "Arbitrary name assigned to the rule."; 1676 } 1678 leaf module-name { 1679 type union { 1680 type matchall-string-type; 1681 type string; 1682 } 1683 default "*"; 1684 description 1685 "Name of the module associated with this rule. 1687 This leaf matches if it has the value '*' or if the 1688 object being accessed is defined in the module with the 1689 specified module name."; 1690 } 1691 choice rule-type { 1692 description 1693 "This choice matches if all leafs present in the rule 1694 match the request. If no leafs are present, the 1695 choice matches all requests."; 1696 case protocol-operation { 1697 leaf rpc-name { 1698 type union { 1699 type matchall-string-type; 1700 type string; 1701 } 1702 description 1703 "This leaf matches if it has the value '*' or if 1704 its value equals the requested protocol operation 1705 name."; 1706 } 1707 } 1708 case notification { 1709 leaf notification-name { 1710 type union { 1711 type matchall-string-type; 1712 type string; 1713 } 1714 description 1715 "This leaf matches if it has the value '*' or if its 1716 value equals the requested notification name."; 1717 } 1718 } 1719 case data-node { 1720 leaf path { 1721 type node-instance-identifier; 1722 mandatory true; 1723 description 1724 "Data Node Instance Identifier associated with the 1725 data node controlled by this rule. 1727 Configuration data or state data instance 1728 identifiers start with a top-level data node. A 1729 complete instance identifier is required for this 1730 type of path value. 1732 The special value '/' refers to all possible 1733 datastore contents."; 1734 } 1735 } 1736 } 1738 leaf access-operations { 1739 type union { 1740 type matchall-string-type; 1741 type access-operations-type; 1742 } 1743 default "*"; 1744 description 1745 "Access operations associated with this rule. 1747 This leaf matches if it has the value '*' or if the 1748 bit corresponding to the requested operation is set."; 1749 } 1750 leaf action { 1751 type action-type; 1752 mandatory true; 1753 description 1754 "The access control action associated with the 1755 rule. If a rule is determined to match a 1756 particular request, then this object is used 1757 to determine whether to permit or deny the 1758 request."; 1759 } 1761 leaf comment { 1762 type string; 1763 description 1764 "A textual description of the access rule."; 1765 } 1766 } 1767 } 1768 } 1769 } 1771 1773 Figure 5 1775 3.6. IANA Considerations 1777 This document reuses the URI for "ietf-netconf-acm" in "The IETF XML 1778 Registry". 1780 This document updates the module registration in the "YANG Module 1781 Names" registry to reference this RFC instead of RFC 6536. Following 1782 the format in [RFC6020], the following has been registered. 1784 Name: ietf-netconf-acm 1785 Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1786 Prefix: nacm 1787 reference: RFC XXXX 1789 3.7. Security Considerations 1791 This entire document discusses access control requirements and 1792 mechanisms for restricting NETCONF protocol behavior within a given 1793 session. 1795 This section highlights the issues for an administrator to consider 1796 when configuring a NETCONF server with NACM. 1798 3.7.1. NACM Configuration and Monitoring Considerations 1800 Configuration of the access control system is highly sensitive to 1801 system security. A server may choose not to allow any user 1802 configuration to some portions of it, such as the global security 1803 level or the groups that allowed access to system resources. 1805 By default, NACM enforcement is enabled. By default, "read" access 1806 to all datastore contents is enabled (unless "nacm:default-deny-all" 1807 is specified for the data definition), and "exec" access is enabled 1808 for safe protocol operations. An administrator needs to ensure that 1809 NACM is enabled and also decide if the default access parameters are 1810 set appropriately. Make sure the following data nodes are properly 1811 configured: 1813 o /nacm/enable-nacm (default "true") 1815 o /nacm/read-default (default "permit") 1817 o /nacm/write-default (default "deny") 1819 o /nacm/exec-default (default "permit") 1821 An administrator needs to restrict write access to all configurable 1822 objects within this data model. 1824 If write access is allowed for configuration of access control rules, 1825 then care needs to be taken not to disrupt the access control 1826 enforcement. For example, if the NACM access control rules are 1827 edited directly within the running configuration datastore (i.e., 1828 :writable-running capability is supported and used), then care needs 1829 to be taken not to allow unintended access while the edits are being 1830 done. 1832 An administrator needs to make sure that the translation from a 1833 transport- or implementation-dependent user identity to a NACM 1834 username is unique and correct. This requirement is specified in 1835 detail in Section 2.2 of [RFC6241]. 1837 An administrator needs to be aware that the YANG data structures 1838 representing access control rules (/nacm/rule-list and /nacm/rule- 1839 list/rule) are ordered by the client. The server will evaluate the 1840 access control rules according to their relative conceptual order 1841 within the running datastore configuration. 1843 Note that the /nacm/groups data structure contains the administrative 1844 group names used by the server. These group names may be configured 1845 locally and/or provided through an external protocol, such as RADIUS 1846 [RFC2865][RFC5607]. 1848 An administrator needs to be aware of the security properties of any 1849 external protocol used by the NETCONF transport layer to determine 1850 group names. For example, if this protocol does not protect against 1851 man-in-the-middle attacks, an attacker might be able to inject group 1852 names that are configured in NACM, so that a user gets more 1853 permissions than it should. In such cases, the administrator may 1854 wish to disable the usage of such group names, by setting /nacm/ 1855 enable-external-groups to "false". 1857 An administrator needs to restrict read access to the following 1858 objects within this data model, as they reveal access control 1859 configuration that could be considered sensitive. 1861 o /nacm/enable-nacm 1863 o /nacm/read-default 1865 o /nacm/write-default 1867 o /nacm/exec-default 1869 o /nacm/enable-external-groups 1871 o /nacm/groups 1873 o /nacm/rule-list 1875 3.7.2. General Configuration Issues 1877 There is a risk that invocation of non-standard protocol operations 1878 will have undocumented side effects. An administrator needs to 1879 construct access control rules such that the configuration datastore 1880 is protected from such side effects. 1882 It is possible for a session with some write access (e.g., allowed to 1883 invoke ), but without any access to a particular 1884 datastore subtree containing sensitive data, to determine the 1885 presence or non-presence of that data. This can be done by 1886 repeatedly issuing some sort of edit request (create, update, or 1887 delete) and possibly receiving "access-denied" errors in response. 1888 These "fishing" attacks can identify the presence or non-presence of 1889 specific sensitive data even without the "error-path" field being 1890 present within the response. 1892 It may be possible for the set of NETCONF capabilities on the server 1893 to change over time. If so, then there is a risk that new protocol 1894 operations, notifications, and/or datastore content have been added 1895 to the device. An administrator needs to be sure the access control 1896 rules are correct for the new content in this case. Mechanisms to 1897 detect NETCONF capability changes on a specific device are outside 1898 the scope of this document. 1900 It is possible that the data model definition itself (e.g., YANG 1901 when-stmt) will help an unauthorized session determine the presence 1902 or even value of sensitive data nodes by examining the presence and 1903 values of different data nodes. 1905 There is a risk that non-standard protocol operations, or even the 1906 standard protocol operation, may return data that "aliases" or 1907 "copies" sensitive data from a different data object. There may 1908 simply be multiple data model definitions that expose or even 1909 configure the same underlying system instrumentation. 1911 A data model may contain external keys (e.g., YANG leafref), which 1912 expose values from a different data structure. An administrator 1913 needs to be aware of sensitive data models that contain leafref 1914 nodes. This entails finding all the leafref objects that "point" at 1915 the sensitive data (i.e., "path-stmt" values) that implicitly or 1916 explicitly include the sensitive data node. 1918 It is beyond the scope of this document to define access control 1919 enforcement procedures for underlying device instrumentation that may 1920 exist to support the NETCONF server operation. An administrator can 1921 identify each protocol operation that the server provides and decide 1922 if it needs any access control applied to it. 1924 This document incorporates the optional use of a recovery session 1925 mechanism, which can be used to bypass access control enforcement in 1926 emergencies, such as NACM configuration errors that disable all 1927 access to the server. The configuration and identification of such a 1928 recovery session mechanism are implementation-specific and outside 1929 the scope of this document. An administrator needs to be aware of 1930 any recovery session mechanisms available on the device and make sure 1931 they are used appropriately. 1933 It is possible for a session to disrupt configuration management, 1934 even without any write access to the configuration, by locking the 1935 datastore. This may be done to ensure all or part of the 1936 configuration remains stable while it is being retrieved, or it may 1937 be done as a "denial-of-service" attack. There is no way for the 1938 server to know the difference. An administrator may wish to restrict 1939 "exec" access to the following protocol operations: 1941 o 1943 o 1945 o 1947 o 1949 3.7.3. Data Model Design Considerations 1951 Designers need to clearly identify any sensitive data, notifications, 1952 or protocol operations defined within a YANG module. For such 1953 definitions, a "nacm:default-deny-write" or "nacm:default-deny-all" 1954 statement ought to be present, in addition to a clear description of 1955 the security risks. 1957 Protocol operations need to be properly documented by the data model 1958 designer, so it is clear to administrators what data nodes (if any) 1959 are affected by the protocol operation and what information (if any) 1960 is returned in the message. 1962 Data models ought to be designed so that different access levels for 1963 input parameters to protocol operations are not required. Use of 1964 generic protocol operations should be avoided, and if different 1965 access levels are needed, separate protocol operations should be 1966 defined instead. 1968 4. References 1970 4.1. Normative References 1972 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1973 Requirement Levels", BCP 14, RFC 2119, 1974 DOI 10.17487/RFC2119, March 1997, 1975 . 1977 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1978 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1979 . 1981 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1982 the Network Configuration Protocol (NETCONF)", RFC 6020, 1983 DOI 10.17487/RFC6020, October 2010, 1984 . 1986 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1987 and A. Bierman, Ed., "Network Configuration Protocol 1988 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1989 . 1991 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1992 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1993 . 1995 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1996 Protocol (HTTP/1.1): Message Syntax and Routing", 1997 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1998 . 2000 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2001 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2002 . 2004 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2005 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2006 . 2008 4.2. Informative References 2010 [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, 2011 "Remote Authentication Dial In User Service (RADIUS)", 2012 RFC 2865, DOI 10.17487/RFC2865, June 2000, 2013 . 2015 [RFC5607] Nelson, D. and G. Weber, "Remote Authentication Dial-In 2016 User Service (RADIUS) Authorization for Network Access 2017 Server (NAS) Management", RFC 5607, DOI 10.17487/RFC5607, 2018 July 2009, . 2020 Appendix A. Change Log 2022 -- RFC Ed.: remove this section before publication. 2024 The NACM issue tracker can be found here: https://github.com/netconf- 2025 wg/rfc6536bis/issues 2027 A.1. v00 to v01 2029 o Updated RESTCONF reference 2031 A.2. v00 2033 o Renamed document from draft-bierman-netconf-rfc6536bis-01 to 2034 draft-ietf-netconf-rfc6536bis-00. 2036 Appendix B. Usage Examples 2038 The following XML snippets are provided as examples only, to 2039 demonstrate how NACM can be configured to perform some access control 2040 tasks. 2042 B.1. Example 2044 There needs to be at least one entry in order for any of the 2045 access control rules to be useful. 2047 The following XML shows arbitrary groups and is not intended to 2048 represent any particular use case. 2050 2051 2052 2053 admin 2054 admin 2055 andy 2056 2058 2059 limited 2060 wilma 2061 bam-bam 2062 2064 2065 guest 2066 guest 2067 guest@example.com 2068 2069 2070 2072 This example shows three groups: 2074 admin: The "admin" group contains two users named "admin" and 2075 "andy". 2077 limited: The "limited" group contains two users named "wilma" and 2078 "bam-bam". 2080 guest: The "guest" group contains two users named "guest" and 2081 "guest@example.com". 2083 B.2. Module Rule Example 2085 Module rules are used to control access to all the content defined in 2086 a specific module. A module rule has the leaf set, but 2087 no case in the "rule-type" choice. 2089 2090 2091 guest-acl 2092 guest 2094 2095 deny-ncm 2096 ietf-netconf-monitoring 2097 * 2098 deny 2099 2100 Do not allow guests any access to the NETCONF 2101 monitoring information. 2102 2103 2104 2106 2107 limited-acl 2108 limited 2110 2111 permit-ncm 2112 ietf-netconf-monitoring 2113 read 2114 permit 2115 2116 Allow read access to the NETCONF 2117 monitoring information. 2118 2119 2120 2121 permit-exec 2122 * 2123 exec 2124 permit 2125 2126 Allow invocation of the 2127 supported server operations. 2128 2129 2130 2132 2133 admin-acl 2134 admin 2136 2137 permit-all 2138 * 2139 * 2140 permit 2141 2142 Allow the admin group complete access to all 2143 operations and data. 2144 2145 2146 2147 2149 This example shows four module rules: 2151 deny-ncm: This rule prevents the "guest" group from reading any 2152 monitoring information in the "ietf-netconf-monitoring" YANG 2153 module. 2155 permit-ncm: This rule allows the "limited" group to read the "ietf- 2156 netconf-monitoring" YANG module. 2158 permit-exec: This rule allows the "limited" group to invoke any 2159 protocol operation supported by the server. 2161 permit-all: This rule allows the "admin" group complete access to 2162 all content in the server. No subsequent rule will match for the 2163 "admin" group because of this module rule. 2165 B.3. Protocol Operation Rule Example 2167 Protocol operation rules are used to control access to a specific 2168 protocol operation. 2170 2171 2172 guest-limited-acl 2173 limited 2174 guest 2176 2177 deny-kill-session 2178 ietf-netconf 2179 kill-session 2180 exec 2181 deny 2182 2183 Do not allow the limited or guest group 2184 to kill another session. 2185 2186 2187 2188 deny-delete-config 2189 ietf-netconf 2190 delete-config 2191 exec 2192 deny 2193 2194 Do not allow limited or guest group 2195 to delete any configurations. 2196 2197 2198 2200 2201 limited-acl 2202 limited 2204 2205 permit-edit-config 2206 ietf-netconf 2207 edit-config 2208 exec 2209 permit 2210 2211 Allow the limited group to edit the configuration. 2212 2213 2214 2216 2218 This example shows three protocol operation rules: 2220 deny-kill-session: This rule prevents the "limited" or "guest" 2221 groups from invoking the NETCONF protocol 2222 operation. 2224 deny-delete-config: This rule prevents the "limited" or "guest" 2225 groups from invoking the NETCONF protocol 2226 operation. 2228 permit-edit-config: This rule allows the "limited" group to invoke 2229 the NETCONF protocol operation. This rule will have 2230 no real effect unless the "exec-default" leaf is set to "deny". 2232 B.4. Data Node Rule Example 2234 Data node rules are used to control access to specific (config and 2235 non-config) data nodes within the NETCONF content provided by the 2236 server. 2238 2239 2240 guest-acl 2241 guest 2243 2244 deny-nacm 2245 2246 /n:nacm 2247 2248 * 2249 deny 2250 2251 Deny the guest group any access to the /nacm data. 2252 2253 2254 2256 2257 limited-acl 2258 limited 2260 2261 permit-acme-config 2262 2263 /acme:acme-netconf/acme:config-parameters 2264 2265 2266 read create update delete 2267 2268 permit 2269 2270 Allow the limited group complete access to the acme 2271 NETCONF configuration parameters. Showing long form 2272 of 'access-operations' instead of shorthand. 2273 2274 2275 2277 2278 guest-limited-acl 2279 guest 2280 limited 2282 2283 permit-dummy-interface 2284 2285 /acme:interfaces/acme:interface[acme:name='dummy'] 2286 2287 read update 2288 permit 2289 2290 Allow the limited and guest groups read 2291 and update access to the dummy interface. 2292 2293 2294 2296 2297 admin-acl 2298 admin 2299 2300 permit-interface 2301 2302 /acme:interfaces/acme:interface 2303 2304 * 2305 permit 2306 2307 Allow admin full access to all acme interfaces. 2308 2309 2310 2311 2313 This example shows four data node rules: 2315 deny-nacm: This rule denies the "guest" group any access to the 2316 subtree. Note that the default namespace is only 2317 applicable because this subtree is defined in the same namespace 2318 as the element. 2320 permit-acme-config: This rule gives the "limited" group read-write 2321 access to the acme . 2323 permit-dummy-interface: This rule gives the "limited" and "guest" 2324 groups read-update access to the acme entry named 2325 "dummy". This entry cannot be created or deleted by these groups, 2326 just altered. 2328 permit-interface: This rule gives the "admin" group read-write 2329 access to all acme entries. 2331 B.5. Notification Rule Example 2333 Notification rules are used to control access to a specific 2334 notification event type. 2336 2337 2338 sys-acl 2339 limited 2340 guest 2342 2343 deny-config-change 2344 acme-system 2345 sys-config-change 2346 read 2347 deny 2348 2349 Do not allow the guest or limited groups 2350 to receive config change events. 2351 2352 2353 2354 2356 This example shows one notification rule: 2358 deny-config-change: This rule prevents the "limited" or "guest" 2359 groups from receiving the acme event type. 2361 Authors' Addresses 2363 Andy Bierman 2364 YumaWorks 2365 685 Cochran St. 2366 Suite #160 2367 Simi Valley, CA 93065 2368 USA 2370 EMail: andy@yumaworks.com 2371 Martin Bjorklund 2372 Tail-f Systems 2374 EMail: mbj@tail-f.com