idnits 2.17.1 draft-ietf-netconf-access-control-07.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 == Line 1130 has weird spacing: '...cations yan...' -- The document date (December 23, 2011) is 4501 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 6021 (Obsoleted by RFC 6991) Summary: 1 error (**), 0 flaws (~~), 2 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 Brocade 4 Intended status: Standards Track M. Bjorklund 5 Expires: June 25, 2012 Tail-f Systems 6 December 23, 2011 8 Network Configuration Protocol (NETCONF) Access Control Model 9 draft-ietf-netconf-access-control-07 11 Abstract 13 The standardization of network configuration interfaces for use with 14 the NETCONF protocol requires a structured and secure operating 15 environment that promotes human usability and multi-vendor 16 interoperability. There is a need for standard mechanisms to 17 restrict NETCONF protocol access for particular users to a pre- 18 configured subset of all available NETCONF protocol operations and 19 content. This document defines such an access control model. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on June 25, 2012. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Access Control Design Objectives . . . . . . . . . . . . . . . 6 58 2.1. Access Control Points . . . . . . . . . . . . . . . . . . 6 59 2.2. Simplicity . . . . . . . . . . . . . . . . . . . . . . . . 7 60 2.3. Procedural Interface . . . . . . . . . . . . . . . . . . . 7 61 2.4. Datastore Access . . . . . . . . . . . . . . . . . . . . . 7 62 2.5. Users and Groups . . . . . . . . . . . . . . . . . . . . . 7 63 2.6. Maintenance . . . . . . . . . . . . . . . . . . . . . . . 8 64 2.7. Configuration Capabilities . . . . . . . . . . . . . . . . 8 65 2.8. Identifying Security-Sensitive Content . . . . . . . . . . 8 66 3. NETCONF Access Control Model (NACM) . . . . . . . . . . . . . 10 67 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 10 68 3.1.1. Features . . . . . . . . . . . . . . . . . . . . . . . 10 69 3.1.2. External Dependencies . . . . . . . . . . . . . . . . 11 70 3.1.3. Message Processing Model . . . . . . . . . . . . . . . 11 71 3.2. Datastore Access . . . . . . . . . . . . . . . . . . . . . 13 72 3.2.1. Access Rights . . . . . . . . . . . . . . . . . . . . 13 73 3.2.2. and Operations . . . . . . . . . . 14 74 3.2.3. Operation . . . . . . . . . . . . . . . 14 75 3.2.4. Operation . . . . . . . . . . . . . . . 15 76 3.2.5. Operation . . . . . . . . . . . . . . 16 77 3.2.6. Operation . . . . . . . . . . . . . . . . . . 16 78 3.2.7. Operation . . . . . . . . . . . . . 16 79 3.2.8. Operation . . . . . . . . . . . . . . . 16 80 3.3. Model Components . . . . . . . . . . . . . . . . . . . . . 16 81 3.3.1. Users . . . . . . . . . . . . . . . . . . . . . . . . 17 82 3.3.2. Groups . . . . . . . . . . . . . . . . . . . . . . . . 17 83 3.3.3. Emergency Recovery Session . . . . . . . . . . . . . . 17 84 3.3.4. Global Enforcement Controls . . . . . . . . . . . . . 17 85 3.3.4.1. enable-nacm Switch . . . . . . . . . . . . . . . . 17 86 3.3.4.2. read-default Switch . . . . . . . . . . . . . . . 17 87 3.3.4.3. write-default Switch . . . . . . . . . . . . . . . 18 88 3.3.4.4. exec-default Switch . . . . . . . . . . . . . . . 18 89 3.3.4.5. enable-external-groups Switch . . . . . . . . . . 18 90 3.3.5. Access Control Rules . . . . . . . . . . . . . . . . . 19 91 3.4. Access Control Enforcement Procedures . . . . . . . . . . 19 92 3.4.1. Initial Operation . . . . . . . . . . . . . . . . . . 19 93 3.4.2. Session Establishment . . . . . . . . . . . . . . . . 20 94 3.4.3. "access-denied" Error Handling . . . . . . . . . . . . 20 95 3.4.4. Incoming RPC Message Validation . . . . . . . . . . . 20 96 3.4.5. Data Node Access Validation . . . . . . . . . . . . . 23 97 3.4.6. Outgoing Authorization . . . . . . . . 25 98 3.5. Data Model Definitions . . . . . . . . . . . . . . . . . . 27 99 3.5.1. Data Organization . . . . . . . . . . . . . . . . . . 27 100 3.5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . 28 101 3.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 38 102 3.7. Security Considerations . . . . . . . . . . . . . . . . . 39 103 3.7.1. NACM Configuration and Monitoring Considerations . . . 39 104 3.7.2. General Configuration Issues . . . . . . . . . . . . . 40 105 3.7.3. Data Model Design Considerations . . . . . . . . . . . 42 106 4. References . . . . . . . . . . . . . . . . . . . . . . . . . . 43 107 4.1. Normative References . . . . . . . . . . . . . . . . . . . 43 108 4.2. Informative References . . . . . . . . . . . . . . . . . . 43 109 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 44 110 A.1. Example . . . . . . . . . . . . . . . . . . . . . 44 111 A.2. Module Rule Example . . . . . . . . . . . . . . . . . . . 45 112 A.3. RPC Rule Example . . . . . . . . . . . . . . . . . . . . . 46 113 A.4. Data Rule Example . . . . . . . . . . . . . . . . . . . . 48 114 A.5. Notification Rule Example . . . . . . . . . . . . . . . . 50 115 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 52 116 B.1. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 52 117 B.2. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 52 118 B.3. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 52 119 B.4. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 52 120 B.5. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 53 121 B.6. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 53 122 B.7. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 53 123 B.8. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54 126 1. Introduction 128 The NETCONF protocol does not provide any standard mechanisms to 129 restrict the protocol operations and content that each user is 130 authorized to access. 132 There is a need for inter-operable management of the controlled 133 access to administrator selected portions of the available NETCONF 134 content within a particular server. 136 This document addresses access control mechanisms for the Operation 137 and Content layers of NETCONF, as defined in [RFC6241]. It contains 138 three main sections: 140 1. Access Control Design Objectives 142 2. NETCONF Access Control Model (NACM) 144 3. YANG Data Model (ietf-netconf-acm.yang) 146 1.1. Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. 152 The following terms are defined in [RFC6241] and are not redefined 153 here: 155 o client 157 o datastore 159 o protocol operation 161 o server 163 o session 165 o user 167 The following terms are defined in [RFC6020] and are not redefined 168 here: 170 o data node 172 o data definition statement 173 The following terms are used throughout this documentation: 175 access control: A security feature provided by the NETCONF server, 176 that allows an administrator to restrict access to a subset of all 177 NETCONF protocol operations and data, based on various criteria. 179 access control model (ACM): A conceptual model used to configure and 180 monitor the access control procedures desired by the administrator 181 to enforce a particular access control policy. 183 access control rule: The criteria used to determine if a particular 184 NETCONF protocol operation will be permitted or denied. 186 access operation: How a request attempts to access a conceptual 187 object. One of "none", "read", "create", "delete", "update", and 188 "execute". 190 recovery session: A special administrative session that is given 191 unlimited NETCONF access, and is exempt from all access control 192 enforcement. The mechanism(s) used by a server to control and 193 identify whether a session is a recovery session or not are 194 implementation-specific and outside the scope of this document. 196 write access: A shorthand for the "create", "delete", and "update" 197 access operations. 199 2. Access Control Design Objectives 201 This section documents the design objectives for the NETCONF Access 202 Control Model presented in Section 3. 204 2.1. Access Control Points 206 NETCONF allows new protocol operations to be added at any time, and 207 the YANG data modeling language supports this feature. It is not 208 possible to design an ACM for NETCONF that only focuses on a static 209 set of protocol operations, like some other protocols. Since few 210 assumptions can be made about an arbitrary protocol operation, the 211 NETCONF architectural server components need to be protected at three 212 conceptual control points. 214 +-------------+ +-------------+ 215 client | protocol | | data node | 216 request --> | operation | -------------> | access | 217 | allowed? | datastore | allowed? | 218 +-------------+ or state +-------------+ 219 data access 221 +----------------+ 222 | notification | 223 event --> | allowed? | 224 +----------------+ 226 Figure 1 228 The following access control points, described in Figure 1, are 229 identified: 231 protocol operation: Permission to invoke specific protocol 232 operations. 234 datastore: Permission to read and/or alter specific data nodes 235 within any datastore. 237 notification: Permission to receive specific notification event 238 types. 240 2.2. Simplicity 242 There is concern that a complicated ACM will not be widely deployed, 243 because it is too hard to use. It needs to be easy to do simple 244 things, and possible to do complex things, instead of hard to do 245 everything. 247 Configuration of the access control system needs to be as simple as 248 possible. Simple and common tasks need to be easy to configure, and 249 require little expertise or domain-specific knowledge. Complex tasks 250 are possible using additional mechanisms, which may require 251 additional expertise. 253 A single set of access control rules ought to be able to control all 254 types of NETCONF protocol operation invocation, all datastore access, 255 and all notification events. 257 Access control ought to be defined with a small and familiar set of 258 permissions, while still allowing full control of NETCONF datastore 259 access. 261 2.3. Procedural Interface 263 The NETCONF protocol uses a remote procedure call model, and an 264 extensible set of protocol operations. Access control for any 265 possible protocol operation is necessary. 267 2.4. Datastore Access 269 It is necessary to control access to specific nodes and subtrees 270 within the NETCONF datastore, regardless of which protocol operation, 271 standard or proprietary, was used to access the datastore. 273 2.5. Users and Groups 275 It is necessary that access control rules for a single user or a 276 configurable group of users can be configured. 278 The ACM needs to support the concept of administrative groups, to 279 support the well-established distinction between a root account and 280 other types of less-privileged conceptual user accounts. These 281 groups need to be configurable by the administrator. 283 It is necessary that the user-to-group mapping can be delegated to a 284 central server, such as a RADIUS server [RFC2865] [RFC5607]. Since 285 authentication is performed by the NETCONF transport layer, and 286 RADIUS performs authentication and service authorization at the same 287 time, the underlying NETCONF transport needs to be able to report a 288 set of group names associated with the user to the server. It is 289 necessary that the administrator can disable the usage of these group 290 names within the ACM. 292 2.6. Maintenance 294 It ought to be possible to disable part or all of the access control 295 model enforcement procedures without deleting any access control 296 rules. 298 2.7. Configuration Capabilities 300 Suitable configuration and monitoring mechanisms are needed to allow 301 an administrator to easily manage all aspects of the ACM behavior. A 302 standard data model, suitable for use with the protocol 303 operation needs to be available for this purpose. 305 Access control rules to restrict access operations on specific 306 subtrees within the configuration datastore need to be supported. 308 2.8. Identifying Security-Sensitive Content 310 One of the most important aspects of the data model documentation, 311 and biggest concerns during deployment, is the identification of 312 security-sensitive content. This applies to protocol operations in 313 NETCONF, not just data and notifications. 315 It is mandatory for security-sensitive objects to be documented in 316 the Security Considerations section of an RFC. This is nice, but it 317 is not good enough, for the following reasons: 319 o This documentation-only approach forces administrators to study 320 the RFC and determine if there are any potential security risks 321 introduced by a new data model. 323 o If any security risks are identified, then the administrator can 324 study some more RFC text, and determine how to mitigate the 325 security risk(s). 327 o The ACM on each server can be configured to mitigate the security 328 risks, e.g., require privileged access to read or write the 329 specific data identified in the Security Considerations section. 331 o If the ACM is not pre-configured, then there will be a time window 332 of vulnerability, after the new data model is loaded, and before 333 the new access control rules for that data model are configured, 334 enabled, and debugged. 336 Often, the administrator just wants to disable default access to the 337 secure content, so no inadvertent or malicious changes can be made to 338 the server. This allows the default rules to be more lenient, 339 without significantly increasing the security risk. 341 A data model designer needs to be able to use machine-readable 342 statements to identify NETCONF content which needs to be protected by 343 default. This will allow client and server tools to automatically 344 identify data-model specific security risks, by denying access to 345 sensitive data unless the user is explicitly authorized to perform 346 the requested access operation. 348 3. NETCONF Access Control Model (NACM) 350 3.1. Introduction 352 This section provides a high-level overview of the access control 353 model structure. It describes the NETCONF protocol message 354 processing model, and the conceptual access control requirements 355 within that model. 357 3.1.1. Features 359 The NACM data model provides the following features: 361 o Independent control of RPC, data, and notification access. 363 o Simple access control rules configuration data model that is easy 364 to use. 366 o The concept of an emergency recovery session is supported, but 367 configuration of the server for this purpose is beyond the scope 368 of this document. An emergency recovery session will bypass all 369 access control enforcement, in order to allow it to initialize or 370 repair the NACM configuration. 372 o A simple and familiar set of datastore permissions is used. 374 o Support for YANG security tagging (e.g., "nacm:default-deny-write" 375 statement) allows default security modes to automatically exclude 376 sensitive data. 378 o Separate default access modes for read, write, and execute 379 permissions. 381 o Access control rules are applied to configurable groups of users. 383 o The access control enforcement procedures can be disabled during 384 operation, without deleting any access control rules, in order to 385 debug operational problems. 387 o Access control rules are simple to configure. 389 o The number of denied protocol operation requests and denied 390 datastore write requests can be monitored by the client. 392 o Simple unconstrained YANG instance identifiers are used to 393 configure access control rules for specific data nodes. 395 3.1.2. External Dependencies 397 The NETCONF [RFC6241] protocol is used for all management purposes 398 within this document. 400 The YANG Data Modeling Language [RFC6020] is used to define the 401 NETCONF data models specified in this document. 403 3.1.3. Message Processing Model 405 The following diagram shows the conceptual message flow model, 406 including the points at which access control is applied, during 407 NETCONF message processing. 409 +-------------------------+ 410 | session | 411 | (username) | 412 +-------------------------+ 413 | ^ 414 V | 415 +--------------+ +---------------+ 416 | message | | message | 417 | dispatcher | | generator | 418 +--------------+ +---------------+ 419 | ^ ^ 420 V | | 421 +===========+ +-------------+ +----------------+ 422 | |---> | | | | 423 | acc. ctl | | generator | | generator | 424 +===========+ +-------------+ +----------------+ 425 | ^ ^ ^ 426 V +------+ | | 427 +-----------+ | +=============+ +================+ 428 | | | | read | | | 429 | processor |-+ | data node | | access ctl | 430 | | | acc. ctl | | | 431 +-----------+ +=============+ +================+ 432 | | ^ ^ 433 V +----------------+ | | 434 +===========+ | | | 435 | write | | | | 436 | data node | | | | 437 | acc. ctl | -----------+ | | | 438 +===========+ | | | | 439 | | | | | 440 V V V | | 441 +---------------+ +-----------------+ 442 | configuration | ---> | server | 443 | datastore | | instrumentation | 444 | | <--- | | 445 +---------------+ +-----------------+ 447 Figure 2 449 The following high-level sequence of conceptual processing steps is 450 executed for each received message, if access control 451 enforcement is enabled: 453 o Access control is applied to all messages (except ) received by the server, individually, for each active 455 session, unless the session is identified as a "recovery session". 457 o If the user is authorized to execute the specified protocol 458 operation, then processing continues, otherwise the request is 459 rejected with an "access-denied" error. 461 o If the configuration datastore or conceptual state data is 462 accessed by the protocol operation, then the server checks if the 463 client is authorized to access the nodes in the data store. If 464 the user is authorized to perform the requested access operation 465 on the requested data, then processing continues. 467 The following sequence of conceptual processing steps is executed for 468 each generated notification event, if access control enforcement is 469 enabled: 471 o Server instrumentation generates a notification, for a particular 472 subscription. 474 o The notification access control enforcer checks the notification 475 event type, and if it is one which the user is not authorized to 476 read, then the notification is dropped for that subscription. 478 3.2. Datastore Access 480 The same access control rules apply to all datastores. For example, 481 the candidate configuration datastore or the running configuration 482 datastore. 484 Only the standard NETCONF datastores (candidate, running, and 485 startup) are controlled by NACM. Local or remote files or datastores 486 accessed via the parameter are not controlled by NACM. 488 3.2.1. Access Rights 490 A small set of hard-wired datastore access rights is needed to 491 control access to all possible NETCONF protocol operations, including 492 vendor extensions to the standard protocol operation set. 494 The "CRUDX" model can support all NETCONF protocol operations: 496 o Create: Allows the client to add a new data node instance to a 497 datastore. 499 o Read: Allows the client to read a data node instance from a 500 datastore, or receive the notification event type. 502 o Update: Allows the client to update an existing data node instance 503 in a datastore. 505 o Delete: Allows the client to delete a data node instance from a 506 datastore. 508 o eXec: Allows the client to execute the protocol operation. 510 3.2.2. and Operations 512 Data nodes to which the client does not have read access are silently 513 omitted from the message. This is done to allow NETCONF 514 filters for and to function properly, instead of 515 causing an "access-denied" error because the filter criteria would 516 otherwise include unauthorized read access to some data nodes. For 517 NETCONF filtering purposes, the selection criteria is applied to the 518 subset of nodes that the user is authorized to read, not the entire 519 datastore. 521 3.2.3. Operation 523 The NACM access rights are not directly coupled to the 524 "operation" attribute, although they are similar. Instead, a NACM 525 access right applies to all protocol operations which would result in 526 a particular access operation to the target datastore. This section 527 describes how these access rights apply to the specific access 528 operations supported by the protocol operation. 530 If the effective access operation is "none" (i.e., default- 531 operation="none") for a particular data node, then no access control 532 is applied to that data node. This is required to allow access to a 533 sub-tree within larger data structure. For example, a user may be 534 authorized to create a new "/interfaces/interface" list entry, but 535 not be authorized to create or delete its parent container 536 ("/interfaces"). If the "/interfaces" container already exists in 537 the target datastore, then the effective operation will be "none" for 538 the "/interfaces" node if an "/interfaces/interface" list entry is 539 edited. 541 If the protocol operation would result in the creation of a data 542 store node, and the user does not have "create" access permission for 543 that node, the protocol operation is rejected with an "access-denied" 544 error. 546 If the protocol operation would result in the deletion of a data 547 store node, and the user does not have "delete" access permission for 548 that node, the protocol operation is rejected with an "access-denied" 549 error. 551 If the protocol operation would result in the modification of a data 552 store node, and the user does not have "update" access permission for 553 that node, the protocol operation is rejected with an "access-denied" 554 error. 556 A "merge" or "replace" operation may include data nodes 557 which do not alter portions of the existing datastore. For example, 558 a container or list node may be present for naming purposes, but does 559 not actually alter the corresponding datastore node. These unaltered 560 data nodes are ignored by the server, and do not require any access 561 rights by the client. 563 A "merge" operation may include data nodes, but not 564 include particular child data nodes that are present in the 565 datastore. These missing data nodes within the scope of a "merge" 566 operation are ignored by the server, and do not require 567 any access rights by the client. 569 The contents of specific restricted datastore nodes MUST NOT be 570 exposed in any elements within the reply. 572 3.2.4. Operation 574 Access control for the protocol operation requires 575 special consideration because the administrator may be replacing the 576 entire target datastore. 578 If the source of the protocol operation is the running 579 configuration datastore, and the target is the startup configuration 580 datastore, the client is only required to have permission to execute 581 the protocol operation. 583 Otherwise: 585 o If the source of the operation is a datastore, then 586 data nodes to which the client does not have read access are 587 silently omitted. 589 o If the target of the operation is a datastore, the 590 client needs access to the modified nodes. Specifically: 592 If the protocol operation would result in the creation of a 593 data store node, and the user does not have "create" access 594 permission for that node, the protocol operation is rejected 595 with an "access-denied" error. 597 If the protocol operation would result in the deletion of a 598 data store node, and the user does not have "delete" access 599 permission for that node, the protocol operation is rejected 600 with an "access-denied" error. 602 If the protocol operation would result in the modification of a 603 data store node, and the user does not have "update" access 604 permission for that node, the protocol operation is rejected 605 with an "access-denied" error. 607 3.2.5. Operation 609 Access to the protocol operation is denied by 610 default. The 'exec-default' parameter does not apply to this 611 protocol operation. Access control rules must be explicitly 612 configured to allow invocation by a non-recovery session. 614 3.2.6. Operation 616 The server MUST determine the exact nodes in the running 617 configuration datastore which are actually different, and only check 618 "create", "update", and "delete" access permissions for this set of 619 nodes, which could be empty. 621 For example, if a session can read the entire datastore, but only 622 change one leaf, that session needs to be able to edit and commit 623 that one leaf. 625 3.2.7. Operation 627 The client is only required to have permission to execute the 628 protocol operation. No datastore permissions are 629 needed. 631 3.2.8. Operation 633 The operation does not directly alter a datastore. 634 However, it allows one session to disrupt another session which is 635 editing a datastore. 637 Access to the protocol operation is denied by default. 638 The 'exec-default' parameter does not apply to this protocol 639 operation. Access control rules must be explicitly configured to 640 allow invocation by a non-recovery session. 642 3.3. Model Components 644 This section defines the conceptual components related to access 645 control model. 647 3.3.1. Users 649 A "user" is the conceptual entity that is associated with the access 650 permissions granted to a particular session. A user is identified by 651 a string which is unique within the server. 653 As described in [RFC6241], the user name string is derived from the 654 transport layer during session establishment. If the transport layer 655 cannot authenticate the user, the session is terminated. 657 3.3.2. Groups 659 Access to a specific NETCONF protocol operation is granted to a 660 session, associated with a group, not a user. 662 A group is identified by its name. All group names are unique within 663 the server. 665 A group member is identified by a user name string. 667 The same user can be a member of multiple groups. 669 3.3.3. Emergency Recovery Session 671 The server MAY support a "recovery session" mechanism, which will 672 bypass all access control enforcement. This is useful for 673 restricting initial access and repairing a broken access control 674 configuration. 676 3.3.4. Global Enforcement Controls 678 There are five global controls that are used to help control how 679 access control is enforced. 681 3.3.4.1. enable-nacm Switch 683 A global "enable-nacm" on/off switch is provided to enable or disable 684 all access control enforcement. When this global switch is set to 685 "true", then all requests are checked against the access control 686 rules, and only permitted if configured to allow the specific access 687 request. When this global switch is set to "false", then all access 688 requested are permitted. 690 3.3.4.2. read-default Switch 692 An on/off "read-default" switch is provided to enable or disable 693 default access to receive data in replies and notifications. When 694 the "enable-nacm" global switch is set to "true", then this global 695 switch is relevant, if no matching access control rule is found to 696 explicitly permit or deny read access to the requested NETCONF 697 datastore data or notification event type. 699 When this global switch is set to "permit", and no matching access 700 control rule is found for the NETCONF datastore read or notification 701 event requested, then access is permitted. 703 When this global switch is set to "deny", and no matching access 704 control rule is found for the NETCONF datastore read or notification 705 event requested, then access is denied. 707 3.3.4.3. write-default Switch 709 An on/off "write-default" switch is provided to enable or disable 710 default access to alter configuration data. When the "enable-nacm" 711 global switch is set to "true", then this global switch is relevant, 712 if no matching access control rule is found to explicitly permit or 713 deny write access to the requested NETCONF datastore data. 715 When this global switch is set to "permit", and no matching access 716 control rule is found for the NETCONF datastore write requested, then 717 access is permitted. 719 When this global switch is set to "deny", and no matching access 720 control rule is found for the NETCONF datastore write requested, then 721 access is denied. 723 3.3.4.4. exec-default Switch 725 An on/off "exec-default" switch is provided to enable or disable 726 default access to execute protocol operations. When the "enable- 727 nacm" global switch is set to "true", then this global switch is 728 relevant, if no matching access control rule is found to explicitly 729 permit or deny access to the requested NETCONF protocol operation. 731 When this global switch is set to "permit", and no matching access 732 control rule is found for the NETCONF protocol operation requested, 733 then access is permitted. 735 When this global switch is set to "deny", and no matching access 736 control rule is found for the NETCONF protocol operation requested, 737 then access is denied. 739 3.3.4.5. enable-external-groups Switch 741 When this global switch is set to "true", the group names reported by 742 the NETCONF transport layer for a session are used together with the 743 locally configured group names, to determine the access control rules 744 for the session. 746 When this switch is set to "false", the group names reported by the 747 NETCONF transport layer are ignored by NACM. 749 3.3.5. Access Control Rules 751 There are 4 types of rules available in NACM: 753 module rule: Controls access for definitions in a specific YANG 754 module, identified by its name. 756 protocol operation rule: Controls access for a specific protocol 757 operation, identified by its YANG module and name. 759 data node rule: Controls access for a specific data node, identified 760 by its path location within the conceptual XML document for the 761 data node. 763 notification rule: Controls access for a specific notification event 764 type, identified by its YANG module and name. 766 3.4. Access Control Enforcement Procedures 768 There are seven separate phases that need to be addressed, four of 769 which are related to the NETCONF message processing model. In 770 addition, the initial start-up mode for a NETCONF server, session 771 establishment, and "access-denied" error handling procedures also 772 need to be considered. 774 The server MUST use the access control rules in effect at the time it 775 starts processing the message. The same access control rules MUST 776 stay in effect for the processing of the entire message. 778 3.4.1. Initial Operation 780 Upon the very first start-up of the NETCONF server, the access 781 control configuration will probably not be present. If it isn't, a 782 server MUST NOT allow any write access to any session role except a 783 "recovery session". 785 Access rules are enforced any time a request is initiated from a user 786 session. Access control is not enforced for server-initiated access 787 requests, such as the initial load of the running datastore, during 788 bootup. 790 3.4.2. Session Establishment 792 The access control model applies specifically to the well-formed XML 793 content transferred between a client and a server, after session 794 establishment has been completed, and after the exchange has 795 been successfully completed. 797 Once session establishment is completed, and a user has been 798 authenticated, the NETCONF transport layer reports the user name and 799 a possibly empty set of group names associated with the user to the 800 NETCONF server. The NETCONF server will enforce the access control 801 rules, based on the supplied user name, group names, and the 802 configuration data stored on the server. 804 3.4.3. "access-denied" Error Handling 806 The "access-denied" error-tag is generated when the access control 807 system denies access to either a request to invoke a protocol 808 operation or a request to perform a particular access operation on 809 the configuration datastore. 811 A server MUST NOT include any information the client is not allowed 812 to read in any elements within the response. 814 3.4.4. Incoming RPC Message Validation 816 The diagram below shows the basic conceptual structure of the access 817 control processing model for incoming NETCONF messages, within 818 a server. 820 NETCONF server 821 +------------+ 822 | XML | 823 | message | 824 | dispatcher | 825 +------------+ 826 | 827 | 828 V 829 +------------+ 830 | NC-base NS | 831 | | 832 +------------+ 833 | | | 834 | | +-------------------------+ 835 | +------------+ | 836 V V V 837 +-----------+ +---------------+ +------------+ 838 | Vendor NS | | NC-base NS | | NC-base NS | 839 | | | | | | 840 +-----------+ +---------------+ +------------+ 841 | | 842 | | 843 V V 844 +----------------------+ 845 | | 846 | configuration | 847 | datastore | 848 +----------------------+ 850 Figure 3 852 Access control begins with the message dispatcher. 854 After the server validates the element, and determines the 855 namespace URI and the element name of the protocol operation being 856 requested, the server verifies that the user is authorized to invoke 857 the protocol operation. 859 The server MUST separately authorize every protocol operation by 860 following these steps: 862 1. If the "enable-nacm" leaf is set to "false", then the protocol 863 operation is permitted. 865 2. If the requesting session is identified as a "recovery session", 866 then the protocol operation is permitted. 868 3. If the requested operation is the NETCONF 869 protocol operation, then the protocol operation is permitted. 871 4. Check all the "group" entries for ones that contain a "user- 872 name" entry that equals the user name for the session making the 873 request. If the "enable-external-groups" leaf is "true", add to 874 these groups the set of groups provided by the transport layer. 876 5. If no groups are found, continue with step 10. 878 6. Process all rule-list entries, in the order they appear in the 879 configuration. If a rule-list's "group" leaf-list does not 880 match any of the user's groups, proceed to the next rule-list 881 entry. 883 7. For each rule-list entry found, process all rules, in order, 884 until a rule that matches the requested access operation is 885 found. A rule matches if all of the following criteria are met: 887 * The rule's "module-name" leaf is "*", or equals the name of 888 the YANG module where the protocol operation is defined. 890 * The rule does not have a "rule-type" defined, or the "rule- 891 type" is "protocol-operation" and the "rpc-name" is "*" or 892 equals the name of the requested protocol operation. 894 * The rule's "access-operations" leaf has the "exec" bit set, 895 or has the special value "*". 897 8. If a matching rule is found, then the "action" leaf is checked. 898 If it is equal to "permit", then the protocol operation is 899 permitted, otherwise it is denied. 901 9. Otherwise, no matching rule was found in any rule-list entry. 903 10. If the requested protocol operation is defined in a YANG module 904 advertised in the server capabilities, and the "rpc" statement 905 contains a "nacm:default-deny-all" statement, then the protocol 906 operation is denied. 908 11. If the requested protocol operation is the NETCONF or , then the protocol operation is 910 denied. 912 12. If the "exec-default" leaf is set to "permit", then permit the 913 protocol operation, otherwise deny the request. 915 If the user is not authorized to invoke the protocol operation then 916 an is generated with the following information: 918 error-tag: access-denied 920 error-path: Identifies the requested protocol operation. For 921 example: 923 925 /nc:rpc/nc:edit-config 926 928 represents the protocol operation in the NETCONF 929 base namespace. 931 If a datastore is accessed, either directly or as a side effect of 932 the protocol operation, then the server MUST intercept the access 933 operation and make sure the user is authorized to perform the 934 requested access operation on the specified data, as defined in 935 Section 3.4.5. 937 3.4.5. Data Node Access Validation 939 If a data node within a datastore is accessed, then the server MUST 940 ensure that the user is authorized to perform the requested read, 941 create, update, or delete access operation on the specified data 942 node. 944 The data node access request is authorized by following these steps: 946 1. If the "enable-nacm" leaf is set to "false", then the access 947 operation is permitted. 949 2. If the requesting session is identified as a "recovery session", 950 then the access operation is permitted. 952 3. Check all the "group" entries for ones that contain a "user- 953 name" entry that equals the user name for the session making the 954 request. If the the "enable-external-groups" leaf is "true", 955 add to these groups the set of groups provided by the transport 956 layer. 958 4. If no groups are found, continue with step 9. 960 5. Process all rule-list entries, in the order they appear in the 961 configuration. If a rule-list's "group" leaf-list does not 962 match any of the user's groups, proceed to the next rule-list 963 entry. 965 6. For each rule-list entry found, process all rules, in order, 966 until a rule that matches the requested access operation is 967 found. A rule matches if all of the following criteria are met: 969 * The rule's "module-name" leaf is "*", or equals the name of 970 the YANG module where the requested data node is defined. 972 * The rule does not have a "rule-type" defined, or the "rule- 973 type" is "data-node" and the "path" matches the requested 974 data node. 976 * For a read access operation, the rule's "access-operations" 977 leaf has the "read" bit set, or has the special value "*". 979 * For a create access operation, the rule's "access-operations" 980 leaf has the "create" bit set, or has the special value "*". 982 * For a delete access operation, the rule's "access-operations" 983 leaf has the "delete" bit set, or has the special value "*". 985 * For an update access operation, the rule's "access- 986 operations" leaf has the "update" bit set, or has the special 987 value "*". 989 7. If a matching rule is found, then the "action" leaf is checked. 990 If it is equal to "permit", then the data node access is 991 permitted, otherwise it is denied. For a read access operation, 992 "denied" means that the requested data is not returned in the 993 reply. 995 8. Otherwise, no matching rule was found in any rule-list entry. 997 9. For a read access operation, if the requested data node is 998 defined in a YANG module advertised in the server capabilities, 999 and the data definition statement contains a "nacm:default-deny- 1000 all" statement, then the requested data node is not included in 1001 the reply. 1003 10. For a write access operation, if the requested data node is 1004 defined in a YANG module advertised in the server capabilities, 1005 and the data definition statement contains a "nacm:default-deny- 1006 write" or a "nacm:default-deny-all" statement, then the data 1007 node access request is denied. 1009 11. For a read access operation, if the "read-default" leaf is set 1010 to "permit", then include the requested data node in the reply, 1011 otherwise do not include the requested data node in the reply. 1013 12. For a write access operation, if the "write-default" leaf is set 1014 to "permit", then permit the data node access request, otherwise 1015 deny the request. 1017 3.4.6. Outgoing Authorization 1019 Configuration of access control rules specifically for descendant 1020 nodes of the notification event type element are outside the scope of 1021 this document. If the user is authorized to receive the notification 1022 event type, then it is also authorized to receive any data it 1023 contains. 1025 The following figure shows the conceptual message processing model 1026 for outgoing messages. 1028 NETCONF server 1029 +------------+ 1030 | XML | 1031 | message | 1032 | generator | 1033 +------------+ 1034 ^ 1035 | 1036 +----------------+ 1037 | | 1038 | generator | 1039 +----------------+ 1040 ^ 1041 | 1042 +=================+ 1043 | | 1044 | access control | 1045 | | 1046 +=================+ 1047 ^ 1048 | 1049 +------------------------+ 1050 | server instrumentation | 1051 +------------------------+ 1052 | ^ 1053 V | 1054 +----------------------+ 1055 | configuration | 1056 | datastore | 1057 +----------------------+ 1059 Figure 4 1061 The generation of a notification for a specific subscription 1062 [RFC5277] is authorized by following these steps: 1064 1. If the "enable-nacm" leaf is set to "false", then the 1065 notification is permitted. 1067 2. If the session is identified as a "recovery session", then the 1068 notification is permitted. 1070 3. If the notification is the NETCONF or 1071 event type [RFC5277], then the 1072 notification is permitted. 1074 4. Check all the "group" entries for ones that contain a "user- 1075 name" entry that equals the user name for the session making the 1076 request. If the "enable-external-groups" leaf is "true", add to 1077 these groups the set of groups provided by the transport layer. 1079 5. If no groups are found, continue with step 10. 1081 6. Process all rule-list entries, in the order they appear in the 1082 configuration. If a rule-list's "group" leaf-list does not 1083 match any of the user's groups, proceed to the next rule-list 1084 entry. 1086 7. For each rule-list entry found, process all rules, in order, 1087 until a rule that matches the requested access operation is 1088 found. A rule matches if all of the following criteria are met: 1090 * The rule's "module-name" leaf is "*", or equals the name of 1091 the YANG module where the notification is defined. 1093 * The rule does not have a "rule-type" defined, or the "rule- 1094 type" is "notification" and the "notification-name" is "*", 1095 equals the name of the notification. 1097 * The rule's "access-operations" leaf has the "read" bit set, 1098 or has the special value "*". 1100 8. If a matching rule is found, then the "action" leaf is checked. 1101 If it is equal to "permit", then permit the notification, 1102 otherwise drop the notification for the associated subscription. 1104 9. Otherwise, no matching rule was found in any rule-list entry. 1106 10. If the requested notification is defined in a YANG module 1107 advertised in the server capabilities, and the "notification" 1108 statement contains a "nacm:default-deny-all" statement, then the 1109 notification is dropped for the associated subscription. 1111 11. If the "read-default" leaf is set to "permit", then permit the 1112 notification, otherwise drop the notification for the associated 1113 subscription. 1115 3.5. Data Model Definitions 1117 3.5.1. Data Organization 1119 The following diagram highlights the contents and structure of the 1120 NACM YANG module. 1122 +--rw nacm 1123 +--rw enable-nacm? boolean 1124 +--rw read-default? action-type 1125 +--rw write-default? action-type 1126 +--rw exec-default? action-type 1127 +--rw enable-external-groups? boolean 1128 +--ro denied-operations yang:zero-based-counter32 1129 +--ro denied-data-writes yang:zero-based-counter32 1130 +--ro denied-notifications yang:zero-based-counter32 1131 +--rw groups 1132 | +--rw group [name] 1133 | +--rw name group-name-type 1134 | +--rw user-name* user-name-type 1135 +--rw rule-list [name] 1136 +--rw name string 1137 +--rw group* union 1138 +--rw rule [name] 1139 +--rw name string 1140 +--rw module-name? union 1141 +--rw (rule-type)? 1142 | +--:(protocol-operation) 1143 | | +--rw rpc-name? union 1144 | +--:(notification) 1145 | | +--rw notification-name? union 1146 | +--:(data-node) 1147 | +--rw path node-instance-identifier 1148 +--rw access-operations? union 1149 +--rw action action-type 1150 +--rw comment? string 1152 3.5.2. YANG Module 1154 The following YANG module specifies the normative NETCONF content 1155 that MUST by supported by the server. 1157 The "ietf-netconf-acm" YANG module imports typedefs from [RFC6021]. 1159 // RFC Ed.: please update the date to the date of publication 1160 file="ietf-netconf-acm@2011-12-23.yang" 1162 module ietf-netconf-acm { 1164 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-acm"; 1166 prefix "nacm"; 1168 import ietf-yang-types { 1169 prefix yang; 1170 } 1172 organization 1173 "IETF NETCONF (Network Configuration) Working Group"; 1175 contact 1176 "WG Web: 1177 WG List: 1179 WG Chair: Mehmet Ersue 1180 1182 WG Chair: Bert Wijnen 1183 1185 Editor: Andy Bierman 1186 1188 Editor: Martin Bjorklund 1189 "; 1191 description 1192 "NETCONF Access Control Model. 1194 Copyright (c) 2011 IETF Trust and the persons identified as 1195 authors of the code. All rights reserved. 1197 Redistribution and use in source and binary forms, with or 1198 without modification, is permitted pursuant to, and subject 1199 to the license terms contained in, the Simplified BSD 1200 License set forth in Section 4.c of the IETF Trust's 1201 Legal Provisions Relating to IETF Documents 1202 (http://trustee.ietf.org/license-info). 1204 This version of this YANG module is part of RFC XXXX; see 1205 the RFC itself for full legal notices."; 1206 // RFC Ed.: replace XXXX with actual RFC number and 1207 // remove this note 1209 // RFC Ed.: remove this note 1210 // Note: extracted from draft-ietf-netconf-access-control-07.txt 1212 // RFC Ed.: please update the date to the date of publication 1213 revision "2011-12-23" { 1214 description 1215 "Initial version"; 1217 reference 1218 "RFC XXXX: Network Configuration Protocol 1219 Access Control Model"; 1220 } 1222 /* 1223 * Extension statements 1224 */ 1226 extension default-deny-write { 1227 description 1228 "Used to indicate that the data model node 1229 represents a sensitive security system parameter. 1231 If present, and the NACM module is enabled (i.e., 1232 /nacm/enable-nacm object equals 'true'), the NETCONF server 1233 will only allow the designated 'recovery session' to have 1234 write access to the node. An explicit access control rule is 1235 required for all other users. 1237 The 'default-deny-write' extension MAY appear within a data 1238 definition statement. It is ignored otherwise."; 1239 } 1241 extension default-deny-all { 1242 description 1243 "Used to indicate that the data model node 1244 controls a very sensitive security system parameter. 1246 If present, and the NACM module is enabled (i.e., 1247 /nacm/enable-nacm object equals 'true'), the NETCONF server 1248 will only allow the designated 'recovery session' to have 1249 read, write, or execute access to the node. An explicit 1250 access control rule is required for all other users. 1252 The 'default-deny-all' extension MAY appear within a data 1253 definition statement, 'rpc' statement, or 'notification' 1254 statement. It is ignored otherwise."; 1255 } 1257 /* 1258 * Derived types 1259 */ 1261 typedef user-name-type { 1262 type string { 1263 length "1..max"; 1264 } 1265 description 1266 "General Purpose User Name string."; 1267 } 1269 typedef matchall-string-type { 1270 type string { 1271 pattern "\*"; 1272 } 1273 description 1274 "The string containing a single asterisk '*' is used 1275 to conceptually represent all possible values 1276 for the particular leaf using this data type."; 1277 } 1279 typedef access-operations-type { 1280 type bits { 1281 bit create { 1282 description 1283 "Any protocol operation that creates a 1284 new data node."; 1285 } 1286 bit read { 1287 description 1288 "Any protocol operation or notification that 1289 returns the value of a data node."; 1290 } 1291 bit update { 1292 description 1293 "Any protocol operation that alters an existing 1294 data node."; 1295 } 1296 bit delete { 1297 description 1298 "Any protocol operation that removes a data node."; 1299 } 1300 bit exec { 1301 description 1302 "Execution access to the specified protocol operation."; 1303 } 1304 } 1305 description 1306 "NETCONF Access Operation."; 1307 } 1309 typedef group-name-type { 1310 type string { 1311 length "1..max"; 1312 pattern "[^\*].*"; 1314 } 1315 description 1316 "Name of administrative group to which 1317 users can be assigned."; 1318 } 1320 typedef action-type { 1321 type enumeration { 1322 enum permit { 1323 description 1324 "Requested action is permitted."; 1325 } 1326 enum deny { 1327 description 1328 "Requested action is denied."; 1329 } 1330 } 1331 description 1332 "Action taken by the server when a particular 1333 rule matches."; 1334 } 1336 typedef node-instance-identifier { 1337 type yang:xpath1.0; 1338 description 1339 "Path expression used to represent a special 1340 data node instance identifier string. 1342 A node-instance-identifier value is an 1343 unrestricted YANG instance-identifier expression. 1344 All the same rules as an instance-identifier apply 1345 except predicates for keys are optional. If a key 1346 predicate is missing, then the node-instance-identifier 1347 represents all possible server instances for that key. 1349 This XPath expression is evaluated in the following context: 1351 o The set of namespace declarations are those in scope on 1352 the leaf element where this type is used. 1354 o The set of variable bindings contains one variable, 1355 'USER', which contains the name of user of the current 1356 session. 1358 o The function library is the core function library, but 1359 note that due to the syntax restrictions of an 1360 instance-identifier, no functions are allowed. 1362 o The context node is the root node in the data tree."; 1363 } 1365 /* 1366 * Data definition statements 1367 */ 1369 container nacm { 1370 nacm:default-deny-all; 1372 description 1373 "Parameters for NETCONF Access Control Model."; 1375 leaf enable-nacm { 1376 type boolean; 1377 default true; 1378 description 1379 "Enable or disable all NETCONF access control 1380 enforcement. If 'true', then enforcement 1381 is enabled. If 'false', then enforcement 1382 is disabled."; 1383 } 1385 leaf read-default { 1386 type action-type; 1387 default "permit"; 1388 description 1389 "Controls whether read access is granted if 1390 no appropriate rule is found for a 1391 particular read request."; 1392 } 1394 leaf write-default { 1395 type action-type; 1396 default "deny"; 1397 description 1398 "Controls whether create, update, or delete access 1399 is granted if no appropriate rule is found for a 1400 particular write request."; 1401 } 1403 leaf exec-default { 1404 type action-type; 1405 default "permit"; 1406 description 1407 "Controls whether exec access is granted if no appropriate 1408 rule is found for a particular protocol operation request."; 1409 } 1410 leaf enable-external-groups { 1411 type boolean; 1412 default true; 1413 description 1414 "Controls whether the server uses the groups reported by the 1415 NETCONF transport layer when it assigns the user to a set of 1416 NACM groups. If this leaf has the value 'false', any group 1417 names reported by the transport layer are ignored by the 1418 server."; 1419 } 1421 leaf denied-operations { 1422 type yang:zero-based-counter32; 1423 config false; 1424 mandatory true; 1425 description 1426 "Number of times a protocol operation request was denied 1427 since the server last restarted."; 1428 } 1430 leaf denied-data-writes { 1431 type yang:zero-based-counter32; 1432 config false; 1433 mandatory true; 1434 description 1435 "Number of times a protocol operation request to alter 1436 a configuration datastore was denied, since the 1437 server last restarted."; 1438 } 1440 leaf denied-notifications { 1441 type yang:zero-based-counter32; 1442 config false; 1443 mandatory true; 1444 description 1445 "Number of times a notification was dropped 1446 for a subscription because access to 1447 the event type was denied, since the server 1448 last restarted."; 1449 } 1451 container groups { 1452 description 1453 "NETCONF Access Control Groups."; 1455 list group { 1456 key name; 1457 description 1458 "One NACM Group Entry. This list will only contain 1459 configured entries, not any entries learned from 1460 any transport protocols."; 1462 leaf name { 1463 type group-name-type; 1464 description 1465 "Group name associated with this entry."; 1466 } 1468 leaf-list user-name { 1469 type user-name-type; 1470 description 1471 "Each entry identifies the user name of 1472 a member of the group associated with 1473 this entry."; 1474 } 1475 } 1476 } 1478 list rule-list { 1479 key "name"; 1480 ordered-by user; 1481 description 1482 "An ordered collection of access control rules."; 1484 leaf name { 1485 type string { 1486 length "1..max"; 1487 } 1488 description 1489 "Arbitrary name assigned to the rule-list."; 1490 } 1491 leaf-list group { 1492 type union { 1493 type matchall-string-type; 1494 type group-name-type; 1495 } 1496 description 1497 "List of administrative groups that will be 1498 assigned the associated access rights 1499 defined by the 'rule' list. 1501 The string '*' indicates that all groups apply to the 1502 entry."; 1503 } 1504 list rule { 1505 key "name"; 1506 ordered-by user; 1507 description 1508 "One access control rule. 1510 Rules are processed in user-defined order until a match is 1511 found. A rule matches if 'module-name', 'rule-type', and 1512 'access-operations' matches the request. If a rule 1513 matches, the 'action' leaf determines if access is granted 1514 or not."; 1516 leaf name { 1517 type string { 1518 length "1..max"; 1519 } 1520 description 1521 "Arbitrary name assigned to the rule."; 1522 } 1524 leaf module-name { 1525 type union { 1526 type matchall-string-type; 1527 type string; 1528 } 1529 default "*"; 1530 description 1531 "Name of the module associated with this rule. 1533 This leaf matches if it has the value '*', or if the 1534 object being accessed is defined in the module with the 1535 specified module name."; 1536 } 1537 choice rule-type { 1538 description 1539 "This choice matches if all leafs present in the rule 1540 matches the request. If no leafs are present, the 1541 choice matches all requests."; 1542 case protocol-operation { 1543 leaf rpc-name { 1544 type union { 1545 type matchall-string-type; 1546 type string; 1547 } 1548 description 1549 "This leaf matches if it has the value '*', or if 1550 its value equals the requested protocol operation 1551 name."; 1553 } 1554 } 1555 case notification { 1556 leaf notification-name { 1557 type union { 1558 type matchall-string-type; 1559 type string; 1560 } 1561 description 1562 "This leaf matches if it has the value '*', or if its 1563 value equals the requested notification name."; 1564 } 1565 } 1566 case data-node { 1567 leaf path { 1568 type node-instance-identifier; 1569 mandatory true; 1570 description 1571 "Data Node Instance Identifier associated with the 1572 data node controlled by this rule. 1574 Configuration data or state data instance 1575 identifiers start with a top-level data node. A 1576 complete instance identifier is required for this 1577 type of path value. 1579 The special value '/' refers to all possible data 1580 store contents."; 1581 } 1582 } 1583 } 1585 leaf access-operations { 1586 type union { 1587 type matchall-string-type; 1588 type access-operations-type; 1589 } 1590 default "*"; 1591 description 1592 "Access operations associated with this rule. 1594 This leaf matches if it has the value '*', or if the 1595 bit corresponding to the requested operation is set."; 1596 } 1598 leaf action { 1599 type action-type; 1600 mandatory true; 1601 description 1602 "The access control action associated with the 1603 rule. If a rule is determined to match a 1604 particular request, then this object is used 1605 to determine whether to permit or deny the 1606 request."; 1607 } 1609 leaf comment { 1610 type string; 1611 description 1612 "A textual description of the access rule."; 1613 } 1614 } 1615 } 1616 } 1617 } 1619 1621 Figure 5 1623 3.6. IANA Considerations 1625 There are two actions that are requested of IANA: This document 1626 registers one URI in "The IETF XML Registry". Following the format 1627 in [RFC3688], the following has been registered. 1629 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1630 Registrant Contact: The IESG. 1631 XML: N/A, the requested URI is an XML namespace. 1633 This document registers one module in the "YANG Module Names" 1634 registry. Following the format in [RFC6020], the following has been 1635 registered. 1637 name: ietf-netconf-acm 1638 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1639 prefix: nacm 1640 reference: RFC XXXX 1641 // RFC Ed.: Replace XXX with actual RFC number 1642 // and remove this note 1644 3.7. Security Considerations 1646 This entire document discusses access control requirements and 1647 mechanisms for restricting NETCONF protocol behavior within a given 1648 session. 1650 This section highlights the issues for an administrator to consider 1651 when configuring a NETCONF server with NACM. 1653 3.7.1. NACM Configuration and Monitoring Considerations 1655 Configuration of the access control system is highly sensitive to 1656 system security. A server may choose not to allow any user 1657 configuration to some portions of it, such as the global security 1658 level, or the groups which allowed access to system resources. 1660 By default, NACM enforcement is enabled. By default, "read" access 1661 to all datastore contents is enabled, (unless "nacm:default-deny-all" 1662 is specified for the data definition) and "exec" access is enabled 1663 for safe protocol operations. An administrator needs to ensure that 1664 NACM is enabled, and also decide if the default access parameters are 1665 set appropriately. Make sure the following data nodes are properly 1666 configured: 1668 o /nacm/enable-nacm (default "true") 1670 o /nacm/read-default (default "permit") 1672 o /nacm/write-default (default "deny") 1674 o /nacm/exec-default (default "permit") 1676 An administrator needs to restrict write access to all configurable 1677 objects within this data model. 1679 If write access is allowed for configuration of access control rules, 1680 then care needs to be taken not to disrupt the access control 1681 enforcement. For example, if the NACM access control rules are 1682 edited directly within the running configuration datastore (i.e., 1683 :writable-running capability is supported and used), then care needs 1684 to be taken not to allow unintended access while the edits are being 1685 done. 1687 An administrator needs to make sure that the translation from a 1688 transport or implementation dependant user identity to a NACM user 1689 name is unique and correct. This requirement is specified in detail 1690 in section 2.2 of [RFC6241]. 1692 An administrator needs to be aware that the YANG data structures 1693 representing access control rules (/nacm/rule-list and /nacm/ 1694 rule-list/rule) are ordered by the client. The server will evaluate 1695 the access control rules according to their relative conceptual order 1696 within the running datastore configuration. 1698 Note that the /nacm/groups data structure contains the administrative 1699 group names used by the server. These group names may be configured 1700 locally and/or provided through an external protocol, such as RADIUS 1701 [RFC2865] [RFC5607]. 1703 An administrator needs to be aware of the security properties of any 1704 external protocol used by the NETCONF transport layer to determine 1705 group names. For example, if this protocol does not protect against 1706 man-in-the-middle attacks, an attacker might be able to inject group 1707 names that are configured in NACM, so that a user gets more 1708 permissions than it should. In such cases, the administrator may 1709 wish to disable the usage of such group names, by setting /nacm/ 1710 enable-external-groups to "false". 1712 An administrator needs to restrict read access to the following 1713 objects within this data model, which reveal access control 1714 configuration which could be considered sensitive. 1716 o /nacm/enable-nacm 1718 o /nacm/read-default 1720 o /nacm/write-default 1722 o /nacm/exec-default 1724 o /nacm/enable-external-groups 1726 o /nacm/groups 1728 o /nacm/rule-list 1730 3.7.2. General Configuration Issues 1732 There is a risk that invocation of non-standard protocol operations 1733 will have undocumented side effects. An administrator needs to 1734 construct access control rules such that the configuration datastore 1735 is protected from such side effects. 1737 It is possible for a session with some write access (e.g., allowed to 1738 invoke ), but without any access to a particular 1739 datastore subtree containing sensitive data, to determine the 1740 presence or non-presence of that data. This can be done by 1741 repeatedly issuing some sort of edit request (create, update, or 1742 delete) and possibly receiving "access-denied" errors in response. 1743 These "fishing" attacks can identify the presence or non-presence of 1744 specific sensitive data even without the "error-path" field being 1745 present within the "rpc-error" response. 1747 It may be possible for the set of NETCONF capabilities on the server 1748 to change over time. If so, then there is a risk that new protocol 1749 operations, notifications, and/or datastore content have been added 1750 to the device. An administrator needs to be sure the access control 1751 rules are correct for the new content in this case. Mechanisms to 1752 detect NETCONF capability changes on a specific device are outside 1753 the scope of this document. 1755 It is possible that the data model definition itself (e.g., YANG 1756 when-stmt) will help an unauthorized session determine the presence 1757 or even value of sensitive data nodes by examining the presence and 1758 values of different data nodes. 1760 There is a risk that non-standard protocol operations, or even the 1761 standard protocol operation, may return data which "aliases" or 1762 "copies" sensitive data from a different data object. There may 1763 simply be multiple data model definitions which expose or even 1764 configure the same underlying system instrumentation. 1766 A data model may contain external keys (e.g., YANG leafref), which 1767 expose values from a different data structure. An administrator 1768 needs to be aware of sensitive data models which contain leafref 1769 nodes. This entails finding all the leafref objects that "point" at 1770 the sensitive data (i.e., "path-stmt" values) that implicitly or 1771 explicitly include the sensitive data node. 1773 It is beyond the scope of this document to define access control 1774 enforcement procedures for underlying device instrumentation that may 1775 exist to support the NETCONF server operation. An administrator can 1776 identify each protocol operation that the server provides, and decide 1777 if it needs any access control applied to it. 1779 This document incorporates the optional use of a "recovery session" 1780 mechanism, which can be used to bypass access control enforcement in 1781 emergencies, such as NACM configuration errors which disable all 1782 access to the server. The configuration and identification of such a 1783 recovery session mechanism are implementation-specific and outside 1784 the scope of this document. An administrator needs to be aware of 1785 any "recovery session" mechanisms available on the device, and make 1786 sure they are used appropriately. 1788 It is possible for a session to disrupt configuration management, 1789 even without any write access to the configuration, by locking the 1790 datastore. This may be done to insure all or part of the 1791 configuration remains stable while it is being retrieved, or it may 1792 be done as a "denial-of-service" attack. There is no way for the 1793 server to know the difference. An administrator may wish to restrict 1794 "exec" access to the following protocol operations: 1796 o 1798 o 1800 o 1802 o 1804 3.7.3. Data Model Design Considerations 1806 Designers need to clearly identify any sensitive data, notifications, 1807 or protocol operations defined within a YANG module. For such 1808 definitions, a "nacm:default-deny-write" or "nacm:default-deny-all" 1809 statement ought to be present, in addition to a clear description of 1810 the security risks. 1812 Protocol operations need to be properly documented by the data model 1813 designer, so it is clear to administrators what data nodes (if any) 1814 are affected by the protocol operation, and what information (if any) 1815 is returned in the message. 1817 Data models ought to be designed so that different access levels for 1818 input parameters to protocol operations is not required. Use of 1819 generic protocol operations should be avoided, and separate protocol 1820 operations defined instead, if different access levels are needed. 1822 4. References 1824 4.1. Normative References 1826 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1827 Requirement Levels", BCP 14, RFC 2119, March 1997. 1829 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1830 January 2004. 1832 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1833 Notifications", RFC 5277, July 2008. 1835 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1836 Network Configuration Protocol (NETCONF)", RFC 6020, 1837 October 2010. 1839 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1840 October 2010. 1842 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1843 Bierman, "Network Configuration Protocol (NETCONF)", 1844 RFC 6241, June 2011. 1846 4.2. Informative References 1848 [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, 1849 "Remote Authentication Dial In User Service (RADIUS)", 1850 RFC 2865, June 2000. 1852 [RFC5607] Nelson, D. and G. Weber, "Remote Authentication Dial-In 1853 User Service (RADIUS) Authorization for Network Access 1854 Server (NAS) Management", RFC 5607, July 2009. 1856 Appendix A. Usage Examples 1858 The following XML snippets are provided as examples only, to 1859 demonstrate how NACM can be configured to perform some access control 1860 tasks. 1862 A.1. Example 1864 There needs to be at least one entry in order for any of the 1865 access control rules to be useful. 1867 The following XML shows arbitrary groups, and is not intended to 1868 represent any particular use-case. 1870 1871 1872 1873 admin 1874 admin 1875 andy 1876 1878 1879 limited 1880 wilma 1881 bam-bam 1882 1884 1885 guest 1886 guest 1887 guest@example.com 1888 1889 1890 1892 This example shows 3 groups: 1894 1. The "admin" group contains 2 users named "admin" and "andy". 1896 2. The "limited" group contains 2 users named "wilma" and "bam-bam". 1898 3. The "guest" group contains 2 users named "guest" and 1899 "guest@example.com". 1901 A.2. Module Rule Example 1903 Module rules are used to control access to all the content defined in 1904 a specific module. A module rule has the leaf set, but 1905 no case in the "rule-type" choice. 1907 1908 1909 guest-acl 1910 guest 1912 1913 deny-ncm 1914 ietf-netconf-monitoring 1915 * 1916 deny 1917 1918 Do not allow guests any access to the netconf 1919 monitoring information. 1920 1921 1922 1924 1925 limited-acl 1926 limited 1928 1929 permit-ncm 1930 ietf-netconf-monitoring 1931 read 1932 permit 1933 1934 Allow read access to the netconf 1935 monitoring information. 1936 1937 1938 1939 permit-exec 1940 * 1941 exec 1942 permit 1943 1944 Allow invocation of the 1945 supported server operations. 1946 1947 1949 1951 1952 admin-acl 1953 admin 1955 1956 permit-all 1957 * 1958 * 1959 permit 1960 1961 Allow the admin group complete access to all 1962 operations and data. 1963 1964 1965 1966 1968 This example shows 4 module rules: 1970 deny-ncm: This rule prevents the "guest" group from reading any 1971 monitoring information in the "ietf-netconf-monitoring" YANG 1972 module. 1974 permit-ncm: This rule allows the "limited" group to read the "ietf- 1975 netconf-monitoring" YANG module. 1977 permit-exec: This rule allows the "limited" group to invoke any 1978 protocol operation supported by the server. 1980 permit-all: This rule allows the "admin" group complete access to 1981 all content in the server. No subsequent rule will match for the 1982 "admin" group, because of this module rule. 1984 A.3. RPC Rule Example 1986 RPC rules are used to control access to a specific protocol 1987 operation. 1989 1990 1991 guest-limited-acl 1992 limited 1993 guest 1995 1996 deny-kill-session 1997 ietf-netconf 1998 kill-session 1999 exec 2000 deny 2001 2002 Do not allow the limited or guest group 2003 to kill another session. 2004 2005 2006 2007 deny-delete-config 2008 ietf-netconf 2009 delete-config 2010 exec 2011 deny 2012 2013 Do not allow limited or guest group 2014 to delete any configurations. 2015 2016 2017 2019 2020 limited-acl 2021 limited 2023 2024 permit-edit-config 2025 ietf-netconf 2026 edit-config 2027 exec 2028 permit 2029 2030 Allow the limited group to edit the configuration. 2031 2032 2033 2035 2036 This example shows 3 protocol operation rules: 2038 deny-kill-session: This rule prevents the "limited" or "guest" 2039 groups from invoking the NETCONF protocol 2040 operation. 2042 deny-delete-config: This rule prevents the "limited" or "guest" 2043 groups from invoking the NETCONF protocol 2044 operation. 2046 permit-edit-config: This rule allows the "limited" group to invoke 2047 the NETCONF protocol operation. This rule will have 2048 no real effect unless the "exec-default" leaf is set to "deny". 2050 A.4. Data Rule Example 2052 Data rules are used to control access to specific (config and non- 2053 config) data nodes within the NETCONF content provided by the server. 2055 2056 2057 guest-acl 2058 guest 2060 2061 deny-nacm 2062 2063 /n:nacm 2064 2065 * 2066 deny 2067 2068 Deny the guest group any access to the /nacm data. 2069 2070 2071 2073 2074 limited-acl 2075 limited 2077 2078 permit-acme-config 2079 2080 /acme:acme-netconf/acme:config-parameters 2081 2082 2083 read create update delete 2084 2085 permit 2086 2087 Allow the limited group complete access to the acme 2088 netconf configuration parameters. Showing long form 2089 of 'access-operations' instead of shorthand. 2090 2091 2092 2094 2095 guest-limited-acl 2096 guest 2097 limited 2099 2100 permit-dummy-interface 2101 2102 /acme:interfaces/acme:interface[acme:name='dummy'] 2103 2104 read update 2105 permit 2106 2107 Allow the limited and guest groups read 2108 and update access to the dummy interface. 2109 2110 2111 2113 2114 admin-acl 2115 admin 2116 2117 permit-interface 2118 2119 /acme:interfaces/acme:interface 2120 2121 * 2122 permit 2123 2124 Allow admin full access to all acme interfaces. 2125 2126 2127 2128 2129 This example shows 4 data rules: 2131 deny-nacm: This rule denies the "guest" group any access to the 2132 subtree. Note that the default namespace is only 2133 applicable because this subtree is defined in the same namespace 2134 as the element. 2136 permit-acme-config: This rule gives the "limited" group read-write 2137 access to the acme . 2139 permit-dummy-interface: This rule gives the "limited" and "guest" 2140 groups read-update access to the acme entry named 2141 "dummy". This entry cannot be created or deleted by these groups, 2142 just altered. 2144 permit-interface: This rule gives the "admin" group read-write 2145 access to all acme entries. 2147 A.5. Notification Rule Example 2149 Notification rules are used to control access to a specific 2150 notification event type. 2152 2153 2154 sys-acl 2155 limited 2156 guest 2158 2159 deny-config-change 2160 acme-system 2161 sys-config-change 2162 read 2163 deny 2164 2165 Do not allow the guest or limited groups 2166 to receive config change events. 2167 2168 2169 2170 2172 This example shows 1 notification rule: 2174 deny-config-change: This rule prevents the "limited" or "guest" 2175 groups from receiving the acme event type. 2177 Appendix B. Change Log 2179 -- RFC Ed.: remove this section before publication. 2181 B.1. 06-07 2183 Added the leaf "enable-external-groups". 2185 Removed dependency to RFC 6242. 2187 Some editorial changes after IESG review. 2189 B.2. 05-06 2191 Added clarification to Security Considerations section about 2192 ordered-by user lists (/nacm/rule-list and /nacm/rule-list/rule). 2194 Added clarifications to security considerations wrt/ user names and 2195 NETCONF capability changes. 2197 Fixed typos found in review. 2199 B.3. 04-05 2201 Updated Security Considerations section. 2203 Changed term 'operator' to 'administrator'. 2205 Used the terms "access operation" and "protocol operation" 2206 consistently. 2208 Moved some normative text from section 2 to section 3. Also made it 2209 more clear that section 2 is not a requirements section, but 2210 documentation of the objectives for NACM. 2212 Renamed "nacm:secure" to "nacm:default-deny-write", and "nacm:very- 2213 secure" to "nacm:default-deny-all". Explained that "nacm:default- 2214 deny-write" is ignored on rpc statements. 2216 Described that and behave as if 2217 specified with "nacm:default-deny-all". 2219 B.4. 03-04 2221 Introduced rule-lists to group related rules together. 2223 Moved "module-rule", "rpc-rule", "notification-rule", and "data-rule" 2224 into one common "rule", with a choice to select between the four 2225 variants. 2227 Changed "superuser" to "recovery session", and adjusted text 2228 throughout document for this change. 2230 Clarified behavior of global default NACM parameters, enable-nacm, 2231 read-default, write-default, exec-default. 2233 Clarified when access control is applied during system 2234 initialization. 2236 B.5. 02-03 2238 Fixed improper usage of RFC 2119 keywords. 2240 Changed term usage of "database" to "datastore". 2242 Clarified that "secure" and "very-secure" extensions only apply if 2243 the /nacm/enable-nacm object is "true". 2245 B.6. 01-02 2247 Removed authentication text and objects. 2249 Changed module name from ietf-nacm to ietf-netconf-acm. 2251 Updated NETCONF and YANG terminology. 2253 Removed open issues section. 2255 Changed some must to MUST in requirements section. 2257 B.7. 00-01 2259 Updated YANG anf YANG Types references. 2261 Updated module namespace URI to standard format. 2263 Updated module header meta-data to standard format. 2265 Filled in IANA section. 2267 B.8. 00 2269 Initial version cloned from 2270 draft-bierman-netconf-access-control-02.txt. 2272 Authors' Addresses 2274 Andy Bierman 2275 Brocade 2277 Email: andy@netconfcentral.org 2279 Martin Bjorklund 2280 Tail-f Systems 2282 Email: mbj@tail-f.com