idnits 2.17.00 (12 Aug 2021) /tmp/idnits62962/draft-ietf-netconf-access-control-05.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 1107 has weird spacing: '...cations yan...' -- The document date (October 4, 2011) is 3881 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: April 6, 2012 Tail-f Systems 6 October 4, 2011 8 Network Configuration Protocol (NETCONF) Access Control Model 9 draft-ietf-netconf-access-control-05 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 April 6, 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 . . . . . . . . . . . . . . . . . . . . . . . . 16 82 3.3.2. Groups . . . . . . . . . . . . . . . . . . . . . . . . 17 83 3.3.3. Global Enforcement Controls . . . . . . . . . . . . . 17 84 3.3.3.1. enable-nacm Switch . . . . . . . . . . . . . . . . 17 85 3.3.3.2. read-default Switch . . . . . . . . . . . . . . . 17 86 3.3.3.3. write-default Switch . . . . . . . . . . . . . . . 18 87 3.3.3.4. exec-default Switch . . . . . . . . . . . . . . . 18 88 3.3.4. Access Control Rules . . . . . . . . . . . . . . . . . 18 89 3.4. Access Control Enforcement Procedures . . . . . . . . . . 19 90 3.4.1. Initial Operation . . . . . . . . . . . . . . . . . . 19 91 3.4.2. Session Establishment . . . . . . . . . . . . . . . . 19 92 3.4.3. "access-denied" Error Handling . . . . . . . . . . . . 19 93 3.4.4. Incoming RPC Message Validation . . . . . . . . . . . 20 94 3.4.5. Data Node Access Validation . . . . . . . . . . . . . 22 95 3.4.6. Outgoing Authorization . . . . . . . . 24 97 3.5. Data Model Definitions . . . . . . . . . . . . . . . . . . 26 98 3.5.1. Data Organization . . . . . . . . . . . . . . . . . . 27 99 3.5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . 27 100 3.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 37 101 3.7. Security Considerations . . . . . . . . . . . . . . . . . 37 102 3.7.1. NACM Configuration and Monitoring Considerations . . . 37 103 3.7.2. General Configuration Issues . . . . . . . . . . . . . 39 104 3.7.3. Data Model Design Considerations . . . . . . . . . . . 40 105 4. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 106 4.1. Normative References . . . . . . . . . . . . . . . . . . . 41 107 4.2. Informative References . . . . . . . . . . . . . . . . . . 41 108 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 42 109 A.1. Example . . . . . . . . . . . . . . . . . . . . . 42 110 A.2. Module Rule Example . . . . . . . . . . . . . . . . . . . 43 111 A.3. RPC Rule Example . . . . . . . . . . . . . . . . . . . . . 44 112 A.4. Data Rule Example . . . . . . . . . . . . . . . . . . . . 46 113 A.5. Notification Rule Example . . . . . . . . . . . . . . . . 48 114 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 50 115 B.1. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 50 116 B.2. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 50 117 B.3. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 50 118 B.4. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 51 119 B.5. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 51 120 B.6. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 123 1. Introduction 125 The NETCONF protocol does not provide any standard mechanisms to 126 restrict the protocol operations and content that each user is 127 authorized to access. 129 There is a need for inter-operable management of the controlled 130 access to administrator selected portions of the available NETCONF 131 content within a particular server. 133 This document addresses access control mechanisms for the Operation 134 and Content layers of NETCONF, as defined in [RFC6241]. It contains 135 three main sections: 137 1. Access Control Design Objectives 139 2. NETCONF Access Control Model (NACM) 141 3. YANG Data Model (ietf-netconf-acm.yang) 143 1.1. Terminology 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 147 document are to be interpreted as described in [RFC2119]. 149 The following terms are defined in [RFC6241] and are not redefined 150 here: 152 o client 154 o datastore 156 o protocol operation 158 o server 160 o session 162 o user 164 The following terms are defined in [RFC6020] and are not redefined 165 here: 167 o data node 169 o data definition statement 170 The following terms are used throughout this documentation: 172 access control: A security feature provided by the NETCONF server, 173 that allows an administrator to restrict access to a subset of all 174 NETCONF protocol operations and data, based on various criteria. 176 access control model (ACM): A conceptual model used to configure and 177 monitor the access control procedures desired by the administrator 178 to enforce a particular access control policy. 180 access control rule: The criteria used to determine if a particular 181 NETCONF protocol operation will be permitted or denied. 183 access operation: How a request attempts to access a conceptual 184 object. One of "none", "read", "create", "delete", "update", and 185 "execute". 187 recovery session: A special administrative session that is given 188 unlimited NETCONF access, and is exempt from all access control 189 enforcement. The mechanism(s) used by a server to control and 190 identify whether a session is a recovery session or not are 191 implementation-specific and outside the scope of this document. 193 write access: A shorthand for the "create", "delete", and "update" 194 access operations. 196 2. Access Control Design Objectives 198 This section documents the design objectives for the NETCONF Access 199 Control Model presented in Section 3. 201 2.1. Access Control Points 203 NETCONF allows new protocol operations to be added at any time, and 204 the YANG data modeling language supports this feature. It is not 205 possible to design an ACM for NETCONF that only focuses on a static 206 set of protocol operations, like some other protocols. Since few 207 assumptions can be made about an arbitrary protocol operation, the 208 NETCONF architectural server components need to be protected at three 209 conceptual control points. 211 +-------------+ +-------------+ 212 client | protocol | | data node | 213 request --> | operation | -------------> | access | 214 | allowed? | datastore | allowed? | 215 +-------------+ or state +-------------+ 216 data access 218 +----------------+ 219 | notification | 220 event --> | allowed? | 221 +----------------+ 223 Figure 1 225 The following access control points, described in Figure 1, are 226 identified: 228 protocol operation: Permission to invoke specific protocol 229 operations. 231 datastore: Permission to read and/or alter specific data nodes 232 within any datastore. 234 notification: Permission to receive specific notification event 235 types. 237 2.2. Simplicity 239 Experience has shown that a complicated ACM will not be widely 240 deployed, because it is too hard to use. The key factor that is 241 ignored in such solutions is the concept of "localized cost". It 242 needs to be easy to do simple things, and possible to do complex 243 things, instead of hard to do everything. 245 Configuration of the access control system needs to be as simple as 246 possible. Simple and common tasks need to be easy to configure, and 247 require little expertise or domain-specific knowledge. Complex tasks 248 are possible using additional mechanisms, which may require 249 additional expertise. 251 A single set of access control rules ought to be able to control all 252 types of NETCONF protocol operation invocation, all datastore access, 253 and all notification events. 255 Access control ought to be defined with a small and familiar set of 256 permissions, while still allowing full control of NETCONF datastore 257 access. 259 2.3. Procedural Interface 261 The NETCONF protocol uses a remote procedure call model, and an 262 extensible set of protocol operations. Access control for any 263 possible protocol operation is necessary. 265 2.4. Datastore Access 267 It is necessary to control access to specific nodes and subtrees 268 within the NETCONF datastore, regardless of which protocol operation, 269 standard or proprietary, was used to access the datastore. 271 2.5. Users and Groups 273 It is necessary that access control rules for a single user or a 274 configurable group of users can be configured. 276 The ACM needs to support the concept of administrative groups, to 277 support the well-established distinction between a root account and 278 other types of less-privileged conceptual user accounts. These 279 groups needs to be configurable by the administrator. 281 It is necessary that the user-to-group mapping can be delegated to a 282 central server, such as a RADIUS server [RFC2865] [RFC5607]. Since 283 authentication is performed by the NETCONF transport layer, and 284 RADIUS performs authentication and service authorization at the same 285 time, the underlying NETCONF transport needs to be able to report a 286 set of group names associated with the user to the server. 288 2.6. Maintenance 290 It ought to be possible to disable part or all of the access control 291 model without deleting any access control rules. 293 2.7. Configuration Capabilities 295 Suitable configuration and monitoring mechanisms are needed to allow 296 an administrator to easily manage all aspects of the ACM behavior. A 297 standard data model, suitable for use with the protocol 298 operation needs to be available for this purpose. 300 Access control rules to restrict access operations on specific 301 subtrees within the configuration datastore needs to be supported. 303 2.8. Identifying Security-Sensitive Content 305 One of the most important aspects of the data model documentation, 306 and biggest concerns during deployment, is the identification of 307 security-sensitive content. This applies to protocol operations in 308 NETCONF, not just data and notifications. 310 It is mandatory for security-sensitive objects to be documented in 311 the Security Considerations section of an RFC. This is nice, but it 312 is not good enough, for the following reasons: 314 o This documentation-only approach forces administrators to study 315 the RFC and determine if there are any potential security risks 316 introduced by a new data model. 318 o If any security risks are identified, then the administrator can 319 study some more RFC text, and determine how to mitigate the 320 security risk(s). 322 o The ACM on each server can be configured to mitigate the security 323 risks, e.g., require privileged access to read or write the 324 specific data identified in the Security Considerations section. 326 o If the ACM is not pre-configured, then there will be a time window 327 of vulnerability, after the new data model is loaded, and before 328 the new access control rules for that data model are configured, 329 enabled, and debugged. 331 Often, the administrator just wants to disable default access to the 332 secure content, so no inadvertent or malicious changes can be made to 333 the server. This allows the default rules to be more lenient, 334 without significantly increasing the security risk. 336 A data model designer needs to be able to use machine-readable 337 statements to identify NETCONF content which needs to be protected by 338 default. This will allow client and server tools to automatically 339 identify data-model specific security risks, by denying access to 340 sensitive data unless the user is explicitly authorized to perform 341 the requested access operation. 343 3. NETCONF Access Control Model (NACM) 345 3.1. Introduction 347 This section provides a high-level overview of the access control 348 model structure. It describes the NETCONF protocol message 349 processing model, and the conceptual access control requirements 350 within that model. 352 3.1.1. Features 354 The NACM data model provides the following features: 356 o Independent control of RPC, data, and notification access. 358 o Simple access control rules configuration data model that is easy 359 to use. 361 o The concept of an emergency recovery session is supported, but 362 configuration of the server for this purpose is beyond the scope 363 of this document. An emergency recovery session will bypass all 364 access control enforcement, in order to allow it to initialize or 365 repair the NACM configuration. 367 o A simple and familiar set of datastore permissions is used. 369 o Support for YANG security tagging (e.g., "nacm:default-deny-write" 370 statement) allows default security modes to automatically exclude 371 sensitive data. 373 o Separate default access modes for read, write, and execute 374 permissions. 376 o Access control rules are applied to configurable groups of users. 378 o The entire ACM can be disabled during operation, in order to debug 379 operational problems. 381 o Access control rules are simple to configure. 383 o The number of denied protocol operation requests and denied 384 datastore write requests can be monitored by the client. 386 o Simple unconstrained YANG instance identifiers are used to 387 configure access control rules for specific data nodes. 389 3.1.2. External Dependencies 391 The NETCONF [RFC6241] protocol is used for all management purposes 392 within this document. It is expected that the mandatory transport 393 mapping NETCONF Over SSH [RFC6242] is also supported by the server, 394 and that the server has access to the user name associated with each 395 session. 397 The YANG Data Modeling Language [RFC6020] is used to define the 398 NETCONF data models specified in this document. 400 3.1.3. Message Processing Model 402 The following diagram shows the conceptual message flow model, 403 including the points at which access control is applied, during 404 NETCONF message processing. 406 +-------------------------+ 407 | session | 408 | (username) | 409 +-------------------------+ 410 | ^ 411 V | 412 +--------------+ +---------------+ 413 | message | | message | 414 | dispatcher | | generator | 415 +--------------+ +---------------+ 416 | ^ ^ 417 V | | 418 +===========+ +-------------+ +----------------+ 419 | |---> | | | | 420 | acc. ctl | | generator | | generator | 421 +===========+ +-------------+ +----------------+ 422 | ^ ^ ^ 423 V +------+ | | 424 +-----------+ | +=============+ +================+ 425 | | | | read | | | 426 | processor |-+ | data node | | access ctl | 427 | | | acc. ctl | | | 428 +-----------+ +=============+ +================+ 429 | | ^ ^ 430 V +----------------+ | | 431 +===========+ | | | 432 | write | | | | 433 | data node | | | | 434 | acc. ctl | -----------+ | | | 435 +===========+ | | | | 436 | | | | | 437 V V V | | 438 +---------------+ +-----------------+ 439 | configuration | ---> | server | 440 | datastore | | instrumentation | 441 | | <--- | | 442 +---------------+ +-----------------+ 444 Figure 2 446 The following high-level sequence of conceptual processing steps is 447 executed for each received message, if access control 448 enforcement is enabled: 450 o Access control is applied to all messages (except ) received by the server, individually, for each active 452 session, unless the session is identified as a "recovery session". 454 o If the user is authorized to execute the specified protocol 455 operation, then processing continues, otherwise the request is 456 rejected with an "access-denied" error. 458 o If the configuration datastore or conceptual state data is 459 accessed by the protocol operation, then the data node access MUST 460 be authorized. If the user is authorized to perform the requested 461 access operation on the requested data, then processing continues. 463 The following sequence of conceptual processing steps is executed for 464 each generated notification event, if access control enforcement is 465 enabled: 467 o Server instrumentation generates a notification, for a particular 468 subscription. 470 o The notification access control enforcer checks the notification 471 event type, and if it is one which the user is not authorized to 472 read, then the notification is dropped for that subscription. 474 3.2. Datastore Access 476 The same access control rules apply to all datastores. For example, 477 the candidate configuration datastore or the running configuration 478 datastore. 480 Only the standard NETCONF datastores (candidate, running, and 481 startup) are controlled by the ACM. Local or remote files or 482 datastores accessed via the parameter are optional to support. 484 3.2.1. Access Rights 486 A small set of hard-wired datastore access rights is needed to 487 control access to all possible NETCONF protocol operations, including 488 vendor extensions to the standard protocol operation set. 490 The "CRUDX" model can support all NETCONF protocol operations: 492 o Create: Allows the client to add a new data node instance to a 493 datastore. 495 o Read: Allows the client to read a data node instance from a 496 datastore, or receive the notification event type. 498 o Update: Allows the client to update an existing data node instance 499 in a datastore. 501 o Delete: Allows the client to delete a data node instance from a 502 datastore. 504 o eXec: Allows the client to execute the protocol operation. 506 3.2.2. and Operations 508 Data nodes to which the client does not have read access are silently 509 omitted from the message. This is done to allow NETCONF 510 filters for and to function properly, instead of 511 causing an "access-denied" error because the filter criteria would 512 otherwise include unauthorized read access to some data nodes. For 513 NETCONF filtering purposes, the selection criteria is applied to the 514 subset of nodes that the user is authorized to read, not the entire 515 datastore. 517 3.2.3. Operation 519 The NACM access rights are not directly coupled to the 520 "operation" attribute, although they are similar. Instead, a NACM 521 access right applies to all protocol operations which would result in 522 a particular access operation to the target datastore. This section 523 describes how these access rights apply to the specific access 524 operations supported by the protocol operation. 526 If the effective access operation is "none" (i.e., default- 527 operation="none") for a particular data node, then no access control 528 is applied to that data node. 530 If the protocol operation would result in the creation of a data 531 store node, and the user does not have "create" access permission for 532 that node, the protocol operation is rejected with an "access-denied" 533 error. 535 If the protocol operation would result in the deletion of a data 536 store node, and the user does not have "delete" access permission for 537 that node, the protocol operation is rejected with an "access-denied" 538 error. 540 If the protocol operation would result in the modification of a data 541 store node, and the user does not have "update" access permission for 542 that node, the protocol operation is rejected with an "access-denied" 543 error. 545 A "merge" or "replace" operation may include data nodes 546 which do not alter portions of the existing datastore. For example, 547 a container or list node may be present for naming purposes, but does 548 not actually alter the corresponding datastore node. These unaltered 549 data nodes are ignored by the server, and do not require any access 550 rights by the client. 552 A "merge" operation may include data nodes, but not 553 include particular child data nodes that are present in the 554 datastore. These missing data nodes within the scope of a "merge" 555 operation are ignored by the server, and do not require 556 any access rights by the client. 558 The contents of specific restricted datastore nodes MUST NOT be 559 exposed in any elements within the reply. 561 3.2.4. Operation 563 Access control for the protocol operation requires 564 special consideration because the administrator may be replacing the 565 entire target datastore. 567 If the source of the protocol operation is the running 568 configuration datastore, and the target is the startup configuration 569 datastore, the client is only required to have permission to execute 570 the protocol operation. 572 Otherwise: 574 o If the source of the operation is a datastore, then 575 data nodes to which the client does not have read access are 576 silently omitted. 578 o If the target of the operation is a datastore, the 579 client needs access to the modified nodes. Specifically: 581 If the protocol operation would result in the creation of a 582 data store node, and the user does not have "create" access 583 permission for that node, the protocol operation is rejected 584 with an "access-denied" error. 586 If the protocol operation would result in the deletion of a 587 data store node, and the user does not have "delete" access 588 permission for that node, the protocol operation is rejected 589 with an "access-denied" error. 591 If the protocol operation would result in the modification of a 592 data store node, and the user does not have "update" access 593 permission for that node, the protocol operation is rejected 594 with an "access-denied" error. 596 3.2.5. Operation 598 Access to the protocol operation is denied by 599 default. The 'exec-default' parameter does not apply to this 600 protocol operation. Access control rules must be explicitly 601 configured to allow invocation by a non-recovery session. 603 3.2.6. Operation 605 The server MUST determine the exact nodes in the running 606 configuration datastore which are actually different, and only check 607 "create", "update", and "delete" access permissions for this set of 608 nodes, which could be empty. 610 For example, if a session can read the entire datastore, but only 611 change one leaf, that session needs to be able to edit and commit 612 that one leaf. 614 3.2.7. Operation 616 The client is only required to have permission to execute the 617 protocol operation. No datastore permissions are 618 needed. 620 3.2.8. Operation 622 The operation does not directly alter a datastore. 623 However, it allows one session to disrupt another session which is 624 editing a datastore. 626 Access to the protocol operation is denied by default. 627 The 'exec-default' parameter does not apply to this protocol 628 operation. Access control rules must be explicitly configured to 629 allow invocation by a non-recovery session. 631 3.3. Model Components 633 This section defines the conceptual components related to access 634 control model. 636 3.3.1. Users 638 A "user" is the conceptual entity that is associated with the access 639 permissions granted to a particular session. A user is identified by 640 a string which is unique within the server. 642 As described in [RFC6241], the user name string is derived from the 643 transport layer during session establishment. If the transport layer 644 cannot authenticate the user, the session is terminated. 646 The server MAY support a "recovery session" mechanism, which will 647 bypass all access control enforcement. This is useful for 648 restricting initial access and repairing a broken access control 649 configuration. 651 3.3.2. Groups 653 Access to a specific NETCONF protocol operation is granted to a 654 session, associated with a group, not a user. 656 A group is identified by its name. All group names are unique within 657 the server. 659 A group member is identified by a user name string. 661 The same user can be a member of multiple groups. 663 3.3.3. Global Enforcement Controls 665 There are four global controls that are used to help control how 666 access control is enforced. 668 3.3.3.1. enable-nacm Switch 670 A global "enable-nacm" on/off switch is provided to enable or disable 671 all access control enforcement. When this global switch is set to 672 "true", then all requests are checked against the access control 673 rules, and only permitted if configured to allow the specific access 674 request. When this global switch is set to "false", then all access 675 requested are permitted. 677 3.3.3.2. read-default Switch 679 An on/off "read-default" switch is provided to enable or disable 680 default access to receive data in replies and notifications. When 681 the "enable-nacm" global switch is set to "true", then this global 682 switch is relevant, if no matching access control rule is found to 683 explicitly permit or deny read access to the requested NETCONF 684 datastore data or notification event type. 686 When this global switch is set to "permit", and no matching access 687 control rule is found for the NETCONF datastore read or notification 688 event requested, then access is permitted. 690 When this global switch is set to "deny", and no matching access 691 control rule is found for the NETCONF datastore read or notification 692 event requested, then access is denied. 694 3.3.3.3. write-default Switch 696 An on/off "write-default" switch is provided to enable or disable 697 default access to alter configuration data. When the "enable-nacm" 698 global switch is set to "true", then this global switch is relevant, 699 if no matching access control rule is found to explicitly permit or 700 deny write access to the requested NETCONF datastore data. 702 When this global switch is set to "permit", and no matching access 703 control rule is found for the NETCONF datastore write requested, then 704 access is permitted. 706 When this global switch is set to "deny", and no matching access 707 control rule is found for the NETCONF datastore write requested, then 708 access is denied. 710 3.3.3.4. exec-default Switch 712 An on/off "exec-default" switch is provided to enable or disable 713 default access to execute protocol operations. When the "enable- 714 nacm" global switch is set to "true", then this global switch is 715 relevant, if no matching access control rule is found to explicitly 716 permit or deny access to the requested NETCONF protocol operation. 718 When this global switch is set to "permit", and no matching access 719 control rule is found for the NETCONF protocol operation requested, 720 then access is permitted. 722 When this global switch is set to "deny", and no matching access 723 control rule is found for the NETCONF protocol operation requested, 724 then access is denied. 726 3.3.4. Access Control Rules 728 There are 4 types of rules available in NACM: 730 module rule: Controls access for definitions in a specific YANG 731 module, identified by its name. 733 protocol operation rule: Controls access for a specific protocol 734 operation, identified by its YANG module and name. 736 data node rule: Controls access for a specific data node, identified 737 by its path location within the conceptual XML document for the 738 data node. 740 notification rule: Controls access for a specific notification event 741 type, identified by its YANG module and name. 743 3.4. Access Control Enforcement Procedures 745 There are seven separate phases that need to be addressed, four of 746 which are related to the NETCONF message processing model. In 747 addition, the initial start-up mode for a NETCONF server, session 748 establishment, and "access-denied" error handling procedures also 749 need to be considered. 751 The server MUST use the access control rules in effect at the time it 752 starts processing the message. The same access control rules MUST 753 stay in effect for the processing of the entire message. 755 3.4.1. Initial Operation 757 Upon the very first start-up of the NETCONF server, the access 758 control configuration will probably not be present. If it isn't, a 759 server MUST NOT allow any write access to any session role except a 760 "recovery session". 762 Access rules are enforced any time a request is initiated from a user 763 session. Access control is not enforced for server-initiated access 764 requests, such as the initial load of the running datastore, during 765 bootup. 767 3.4.2. Session Establishment 769 The access control model applies specifically to the well-formed XML 770 content transferred between a client and a server, after session 771 establishment has been completed, and after the exchange has 772 been successfully completed. 774 Once session establishment is completed, and a user has been 775 authenticated, the NETCONF transport layer reports the user name and 776 a possibly empty set of group names associated with the user to the 777 NETCONF server. The NETCONF server will enforce the access control 778 rules, based on the supplied user name, group names, and the 779 configuration data stored on the server. 781 3.4.3. "access-denied" Error Handling 783 The "access-denied" error-tag is generated when the access control 784 system denies access to either a request to invoke a protocol 785 operation or a request to perform a particular access operation on 786 the configuration datastore. 788 A server MUST NOT include any sensitive information in any elements within the response. 791 3.4.4. Incoming RPC Message Validation 793 The diagram below shows the basic conceptual structure of the access 794 control processing model for incoming NETCONF messages, within 795 a server. 797 NETCONF server 798 +------------+ 799 | XML | 800 | message | 801 | dispatcher | 802 +------------+ 803 | 804 | 805 V 806 +------------+ 807 | NC-base NS | 808 | | 809 +------------+ 810 | | | 811 | | +-------------------------+ 812 | +------------+ | 813 V V V 814 +-----------+ +---------------+ +------------+ 815 | acme NS | | NC-base NS | | NC-base NS | 816 | | | | | | 817 +-----------+ +---------------+ +------------+ 818 | | 819 | | 820 V V 821 +----------------------+ 822 | | 823 | configuration | 824 | datastore | 825 +----------------------+ 827 Figure 3 829 Access control begins with the message dispatcher. 831 After the server validates the element, and determines the 832 namespace URI and the element name of the protocol operation being 833 requested, the server verifies that the user is authorized to invoke 834 the protocol operation. 836 The protocol operation is authorized by following these steps: 838 1. If the "enable-nacm" leaf is set to "false", then the protocol 839 operation is permitted. 841 2. If the requesting session is identified as a "recovery session", 842 then the protocol operation is permitted. 844 3. If the requested operation is the NETCONF 845 protocol operation, then the protocol operation is permitted. 847 4. Check all the "group" entries for ones that contain a "user- 848 name" entry that equals the user name for the session making the 849 request. Add to these groups the set of groups provided by the 850 transport layer. 852 5. If no groups are found, continue with step 10. 854 6. Process all rule-list entries, in the order they appear in the 855 configuration. If a rule-list's "group" leaf-list does not 856 match any of the user's groups, proceed to the next rule-list 857 entry. 859 7. For each rule-list entry found, process all rules, in order, 860 until a rule that matches the requested access operation is 861 found. A rule matches if all of the following criteria are met: 863 * The rule's "module-name" leaf is "*", or equals the name of 864 the YANG module where the protocol operation is defined. 866 * The rule does not have a "rule-type" defined, or the "rule- 867 type" is "protocol-operation" and the "rpc-name" is "*" or 868 equals the name of the requested protocol operation. 870 * The rule's "access-operations" leaf has the "exec" bit set, 871 or has the special value "*". 873 8. If a matching rule is found, then the "action" leaf is checked. 874 If it is equal to "permit", then the protocol operation is 875 permitted, otherwise it is denied. 877 9. Otherwise, no matching rule was found in any rule-list entry. 879 10. If the requested protocol operation is defined in a YANG module 880 advertised in the server capabilities, and the "rpc" statement 881 contains a "nacm:default-deny-all" statement, then the protocol 882 operation is denied. 884 11. If the requested protocol operation is the NETCONF or , then the protocol operation is 886 denied. 888 12. If the "exec-default" leaf is set to "permit", then permit the 889 protocol operation, otherwise deny the request. 891 If the user is not authorized to invoke the protocol operation then 892 an is generated with the following information: 894 error-tag: access-denied 896 error-path: Identifies the requested protocol operation. For 897 example: 899 901 /nc:rpc/nc:edit-config 902 904 represents the protocol operation in the NETCONF 905 base namespace. 907 If a datastore is accessed, either directly or as a side effect of 908 the protocol operation, then the server MUST intercept the access 909 operation and make sure the user is authorized to perform the 910 requested access operation on the specified data, as defined in 911 Section 3.4.5. 913 3.4.5. Data Node Access Validation 915 If a data node within a datastore is accessed, then the server MUST 916 ensure that the user is authorized to perform the requested read, 917 create, update, or delete access operation on the specified data 918 node. 920 The data node access request is authorized by following these steps: 922 1. If the "enable-nacm" leaf is set to "false", then the access 923 operation is permitted. 925 2. If the requesting session is identified as a "recovery session", 926 then the access operation is permitted. 928 3. Check all the "group" entries for ones that contain a "user- 929 name" entry that equals the user name for the session making the 930 request. Add to these groups the set of groups provided by the 931 transport layer. 933 4. If no groups are found, continue with step 9. 935 5. Process all rule-list entries, in the order they appear in the 936 configuration. If a rule-list's "group" leaf-list does not 937 match any of the user's groups, proceed to the next rule-list 938 entry. 940 6. For each rule-list entry found, process all rules, in order, 941 until a rule that matches the requested access operation is 942 found. A rule matches if all of the following criteria are met: 944 * The rule's "module-name" leaf is "*", or equals the name of 945 the YANG module where the requested data node is defined. 947 * The rule does not have a "rule-type" defined, or the "rule- 948 type" is "data-node" and the "path" matches the requested 949 data node. 951 * For a read access operation, the rule's "access-operations" 952 leaf has the "read" bit set, or has the special value "*". 954 * For a create access operation, the rule's "access-operations" 955 leaf has the "create" bit set, or has the special value "*". 957 * For a delete access operation, the rule's "access-operations" 958 leaf has the "delete" bit set, or has the special value "*". 960 * For an update access operation, the rule's "access- 961 operations" leaf has the "update" bit set, or has the special 962 value "*". 964 7. If a matching rule is found, then the "action" leaf is checked. 965 If it is equal to "permit", then the data node access is 966 permitted, otherwise it is denied. For a read access operation, 967 "denied" means that the requested data is not returned in the 968 reply. 970 8. Otherwise, no matching rule was found in any rule-list entry. 972 9. For a read access operation, if the requested data node is 973 defined in a YANG module advertised in the server capabilities, 974 and the data definition statement contains a "nacm:default-deny- 975 all" statement, then the requested data node is not included in 976 the reply. 978 10. For a write access operation, if the requested data node is 979 defined in a YANG module advertised in the server capabilities, 980 and the data definition statement contains a "nacm:default-deny- 981 write" or a "nacm:default-deny-all" statement, then the data 982 node access request is denied. 984 11. For a read access operation, if the "read-default" leaf is set 985 to "permit", then include the requested data node in the reply, 986 otherwise do not include the requested data node in the reply. 988 12. For a write access operation, if the "write-default" leaf is set 989 to "permit", then permit the data node access request, otherwise 990 deny the request. 992 3.4.6. Outgoing Authorization 994 Configuration of access control rules specifically for descendant 995 nodes of the notification event type element are outside the scope of 996 this document. If the user is authorized to receive the notification 997 event type, then it is also authorized to receive any data it 998 contains. 1000 The following figure shows the conceptual message processing model 1001 for outgoing messages. 1003 NETCONF server 1004 +------------+ 1005 | XML | 1006 | message | 1007 | generator | 1008 +------------+ 1009 ^ 1010 | 1011 +----------------+ 1012 | | 1013 | generator | 1014 +----------------+ 1015 ^ 1016 | 1017 +=================+ 1018 | | 1019 | access control | 1020 | | 1021 +=================+ 1022 ^ 1023 | 1024 +------------------------+ 1025 | server instrumentation | 1026 +------------------------+ 1027 | ^ 1028 V | 1029 +----------------------+ 1030 | configuration | 1031 | datastore | 1032 +----------------------+ 1034 Figure 4 1036 The generation of a notification for a specific subscription is 1037 authorized by following these steps: 1039 1. If the "enable-nacm" leaf is set to "false", then the 1040 notification is permitted. 1042 2. If the session is identified as a "recovery session", then the 1043 notification is permitted. 1045 3. If the notification is the NETCONF or 1046 event type [RFC5277], then the 1047 notification is permitted. 1049 4. Check all the "group" entries for ones that contain a "user- 1050 name" entry that equals the user name for the session making the 1051 request. Add to these groups the set of groups provided by the 1052 transport layer. 1054 5. If no groups are found, continue with step 10. 1056 6. Process all rule-list entries, in the order they appear in the 1057 configuration. If a rule-list's "group" leaf-list does not 1058 match any of the user's groups, proceed to the next rule-list 1059 entry. 1061 7. For each rule-list entry found, process all rules, in order, 1062 until a rule that matches the requested access operation is 1063 found. A rule matches if all of the following criteria are met: 1065 * The rule's "module-name" leaf is "*", or equals the name of 1066 the YANG module where the notification is defined. 1068 * The rule does not have a "rule-type" defined, or the "rule- 1069 type" is "notification" and the "notification-name" is "*", 1070 equals the name of the notification. 1072 * The rule's "access-operations" leaf has the "read" bit set, 1073 or has the special value "*". 1075 8. If a matching rule is found, then the "action" leaf is checked. 1076 If it is equal to "permit", then permit the notification, 1077 otherwise drop the notification for the associated subscription. 1079 9. Otherwise, no matching rule was found in any rule-list entry. 1081 10. If the requested notification is defined in a YANG module 1082 advertised in the server capabilities, and the "notification" 1083 statement contains a "nacm:default-deny-all" statement, then the 1084 notification is dropped for the associated subscription. 1086 11. If the "read-default" leaf is set to "permit", then permit the 1087 notification, otherwise drop the notification for the associated 1088 subscription. 1090 3.5. Data Model Definitions 1092 This section defines the semantics of the conceptual data structures 1093 found in the data model in Section 3.5. 1095 3.5.1. Data Organization 1097 The following diagram highlights the contents and structure of the 1098 NACM YANG module. 1100 +--rw nacm 1101 +--rw enable-nacm? boolean 1102 +--rw read-default? action-type 1103 +--rw write-default? action-type 1104 +--rw exec-default? action-type 1105 +--ro denied-operations yang:zero-based-counter32 1106 +--ro denied-data-writes yang:zero-based-counter32 1107 +--ro denied-notifications yang:zero-based-counter32 1108 +--rw groups 1109 | +--rw group [name] 1110 | +--rw name group-name-type 1111 | +--rw user-name* user-name-type 1112 +--rw rule-list [name] 1113 +--rw name string 1114 +--rw group* union 1115 +--rw rule [name] 1116 +--rw name string 1117 +--rw module-name? union 1118 +--rw (rule-type)? 1119 | +--:(protocol-operation) 1120 | | +--rw rpc-name? union 1121 | +--:(notification) 1122 | | +--rw notification-name? union 1123 | +--:(data-node) 1124 | +--rw path node-instance-identifier 1125 +--rw access-operations? union 1126 +--rw action action-type 1127 +--rw comment? string 1129 3.5.2. YANG Module 1131 The following YANG module specifies the normative NETCONF content 1132 that MUST by supported by the server. 1134 The "ietf-netconf-acm" YANG module imports typedefs from [RFC6021]. 1136 // RFC Ed.: please update the date to the date of publication 1137 file="ietf-netconf-acm@2011-10-04.yang" 1139 module ietf-netconf-acm { 1141 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-acm"; 1142 prefix "nacm"; 1144 import ietf-yang-types { 1145 prefix yang; 1146 } 1148 organization 1149 "IETF NETCONF (Network Configuration) Working Group"; 1151 contact 1152 "WG Web: 1153 WG List: 1155 WG Chair: Mehmet Ersue 1156 1158 WG Chair: Bert Wijnen 1159 1161 Editor: Andy Bierman 1162 1164 Editor: Martin Bjorklund 1165 "; 1167 description 1168 "NETCONF Access Control Model. 1170 Copyright (c) 2011 IETF Trust and the persons identified as 1171 authors of the code. All rights reserved. 1173 Redistribution and use in source and binary forms, with or 1174 without modification, is permitted pursuant to, and subject 1175 to the license terms contained in, the Simplified BSD 1176 License set forth in Section 4.c of the IETF Trust's 1177 Legal Provisions Relating to IETF Documents 1178 (http://trustee.ietf.org/license-info). 1180 This version of this YANG module is part of RFC XXXX; see 1181 the RFC itself for full legal notices."; 1182 // RFC Ed.: replace XXXX with actual RFC number and 1183 // remove this note 1185 // RFC Ed.: remove this note 1186 // Note: extracted from draft-ietf-netconf-access-control-05.txt 1188 // RFC Ed.: please update the date to the date of publication 1189 revision "2011-10-04" { 1190 description 1191 "Initial version"; 1192 reference 1193 "RFC XXXX: Network Configuration Protocol 1194 Access Control Model"; 1195 } 1197 /* 1198 * Extension statements 1199 */ 1201 extension default-deny-write { 1202 description 1203 "Used to indicate that the data model node 1204 represents a sensitive security system parameter. 1206 If present, and the NACM module is enabled (i.e., 1207 /nacm/enable-nacm object equals 'true'), the NETCONF server 1208 will only allow the designated 'recovery session' to have 1209 write access to the node. An explicit access control rule is 1210 required for all other users. 1212 The 'default-deny-write' extension MAY appear within a data 1213 definition statement. It is ignored otherwise."; 1214 } 1216 extension default-deny-all { 1217 description 1218 "Used to indicate that the data model node 1219 controls a very sensitive security system parameter. 1221 If present, and the NACM module is enabled (i.e., 1222 /nacm/enable-nacm object equals 'true'), the NETCONF server 1223 will only allow the designated 'recovery session' to have 1224 read, write, or execute access to the node. An explicit 1225 access control rule is required for all other users. 1227 The 'default-deny-all' extension MAY appear within a data 1228 definition statement, 'rpc' statement, or 'notification' 1229 statement. It is ignored otherwise."; 1230 } 1232 /* 1233 * Derived types 1234 */ 1236 typedef user-name-type { 1237 type string { 1238 length "1..max"; 1239 } 1240 description 1241 "General Purpose User Name string."; 1242 } 1244 typedef matchall-string-type { 1245 type string { 1246 pattern "\*"; 1247 } 1248 description 1249 "The string containing a single asterisk '*' is used 1250 to conceptually represent all possible values 1251 for the particular leaf using this data type."; 1252 } 1254 typedef access-operations-type { 1255 type bits { 1256 bit create { 1257 description 1258 "Any protocol operation that creates a 1259 new data node."; 1260 } 1261 bit read { 1262 description 1263 "Any protocol operation or notification that 1264 returns the value of a data node."; 1265 } 1266 bit update { 1267 description 1268 "Any protocol operation that alters an existing 1269 data node."; 1270 } 1271 bit delete { 1272 description 1273 "Any protocol operation that removes a data node."; 1274 } 1275 bit exec { 1276 description 1277 "Execution access to the specified protocol operation."; 1278 } 1279 } 1280 description 1281 "NETCONF Access Operation."; 1282 } 1284 typedef group-name-type { 1285 type string { 1286 length "1..max"; 1287 pattern "[^\*].*"; 1288 } 1289 description 1290 "Name of administrative group to which 1291 users can be assigned."; 1292 } 1294 typedef action-type { 1295 type enumeration { 1296 enum permit { 1297 description 1298 "Requested action is permitted."; 1299 } 1300 enum deny { 1301 description 1302 "Requested action is denied."; 1303 } 1304 } 1305 description 1306 "Action taken by the server when a particular 1307 rule matches."; 1308 } 1310 typedef node-instance-identifier { 1311 type yang:xpath1.0; 1312 description 1313 "Path expression used to represent a special 1314 data node instance identifier string. 1316 A node-instance-identifier value is an 1317 unrestricted YANG instance-identifier expression. 1318 All the same rules as an instance-identifier apply 1319 except predicates for keys are optional. If a key 1320 predicate is missing, then the node-instance-identifier 1321 represents all possible server instances for that key. 1323 This XPath expression is evaluated in the following context: 1325 o The set of namespace declarations are those in scope on 1326 the leaf element where this type is used. 1328 o The set of variable bindings contains one variable, 1329 'USER', which contains the name of user of the current 1330 session. 1332 o The function library is the core function library, but 1333 note that due to the syntax restrictions of an 1334 instance-identifier, no functions are allowed. 1336 o The context node is the root node in the data tree."; 1337 } 1339 container nacm { 1340 nacm:default-deny-all; 1342 description 1343 "Parameters for NETCONF Access Control Model."; 1345 leaf enable-nacm { 1346 type boolean; 1347 default true; 1348 description 1349 "Enable or disable all NETCONF access control 1350 enforcement. If 'true', then enforcement 1351 is enabled. If 'false', then enforcement 1352 is disabled."; 1353 } 1355 leaf read-default { 1356 type action-type; 1357 default "permit"; 1358 description 1359 "Controls whether read access is granted if 1360 no appropriate rule is found for a 1361 particular read request."; 1362 } 1364 leaf write-default { 1365 type action-type; 1366 default "deny"; 1367 description 1368 "Controls whether create, update, or delete access 1369 is granted if no appropriate rule is found for a 1370 particular write request."; 1371 } 1373 leaf exec-default { 1374 type action-type; 1375 default "permit"; 1376 description 1377 "Controls whether exec access is granted if no appropriate 1378 rule is found for a particular protocol operation request."; 1379 } 1380 leaf denied-operations { 1381 type yang:zero-based-counter32; 1382 config false; 1383 mandatory true; 1384 description 1385 "Number of times a protocol operation request was denied 1386 since the server last restarted."; 1387 } 1389 leaf denied-data-writes { 1390 type yang:zero-based-counter32; 1391 config false; 1392 mandatory true; 1393 description 1394 "Number of times a protocol operation request to alter 1395 a configuration datastore was denied, since the 1396 server last restarted."; 1397 } 1399 leaf denied-notifications { 1400 type yang:zero-based-counter32; 1401 config false; 1402 mandatory true; 1403 description 1404 "Number of times a notification was dropped 1405 for a subscription because access to 1406 the event type was denied, since the server 1407 last restarted."; 1408 } 1410 container groups { 1411 description 1412 "NETCONF Access Control Groups."; 1414 list group { 1415 key name; 1417 description 1418 "One NACM Group Entry."; 1420 leaf name { 1421 type group-name-type; 1422 description 1423 "Group name associated with this entry."; 1424 } 1426 leaf-list user-name { 1427 type user-name-type; 1428 description 1429 "Each entry identifies the user name of 1430 a member of the group associated with 1431 this entry."; 1432 } 1433 } 1434 } 1436 list rule-list { 1437 key "name"; 1438 ordered-by user; 1439 description 1440 "An ordered collection of access control rules."; 1442 leaf name { 1443 type string { 1444 length "1..max"; 1445 } 1446 description 1447 "Arbitrary name assigned to the rule-list."; 1448 } 1449 leaf-list group { 1450 type union { 1451 type matchall-string-type; 1452 type group-name-type; 1453 } 1454 description 1455 "List of administrative groups that will be 1456 assigned the associated access rights 1457 defined by the 'rule' list. 1459 The string '*' indicates that all groups apply to the 1460 entry."; 1461 } 1463 list rule { 1464 key "name"; 1465 ordered-by user; 1466 description 1467 "One access control rule. 1469 Rules are processed in user-defined order until a match is 1470 found. A rule matches if 'module-name', 'rule-type', and 1471 'access-operations' matches the request. If a rule 1472 matches, the 'action' leaf determines if access is granted 1473 or not."; 1475 leaf name { 1476 type string { 1477 length "1..max"; 1478 } 1479 description 1480 "Arbitrary name assigned to the rule."; 1481 } 1483 leaf module-name { 1484 type union { 1485 type matchall-string-type; 1486 type string; 1487 } 1488 default "*"; 1489 description 1490 "Name of the module associated with this rule. 1492 This leaf matches if it has the value '*', or if the 1493 object being accessed is defined in the module with the 1494 specified module name."; 1495 } 1496 choice rule-type { 1497 description 1498 "This choice matches if all leafs present in the rule 1499 matches the request. If no leafs are present, the 1500 choice matches all requests."; 1501 case protocol-operation { 1502 leaf rpc-name { 1503 type union { 1504 type matchall-string-type; 1505 type string; 1506 } 1507 description 1508 "This leaf matches if it has the value '*', or if 1509 its value equals the requested protocol operation 1510 name."; 1511 } 1512 } 1513 case notification { 1514 leaf notification-name { 1515 type union { 1516 type matchall-string-type; 1517 type string; 1518 } 1519 description 1520 "This leaf matches if it has the value '*', or if its 1521 value equals the requested notification name."; 1522 } 1523 } 1524 case data-node { 1525 leaf path { 1526 type node-instance-identifier; 1527 mandatory true; 1528 description 1529 "Data Node Instance Identifier associated with the 1530 data node controlled by this rule. 1532 Configuration data or state data instance 1533 identifiers start with a top-level data node. A 1534 complete instance identifier is required for this 1535 type of path value. 1537 The special value '/' refers to all possible data 1538 store contents."; 1539 } 1540 } 1541 } 1543 leaf access-operations { 1544 type union { 1545 type matchall-string-type; 1546 type access-operations-type; 1547 } 1548 default "*"; 1549 description 1550 "Access operations associated with this rule. 1552 This leaf matches if it has the value '*', or if the 1553 bit corresponding to the requested operation is set."; 1554 } 1556 leaf action { 1557 type action-type; 1558 mandatory true; 1559 description 1560 "The access control action associated with the 1561 rule. If a rule is determined to match a 1562 particular request, then this object is used 1563 to determine whether to permit or deny the 1564 request."; 1565 } 1567 leaf comment { 1568 type string; 1569 description 1570 "A textual description of the access rule."; 1571 } 1573 } 1574 } 1575 } 1576 } 1578 1580 Figure 5 1582 3.6. IANA Considerations 1584 There are two actions that are requested of IANA: This document 1585 registers one URI in "The IETF XML Registry". Following the format 1586 in [RFC3688], the following has been registered. 1588 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1589 Registrant Contact: The IESG. 1590 XML: N/A, the requested URI is an XML namespace. 1592 This document registers one module in the "YANG Module Names" 1593 registry. Following the format in [RFC6020], the following has been 1594 registered. 1596 name: ietf-netconf-acm 1597 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1598 prefix: nacm 1599 reference: RFC XXXX 1600 // RFC Ed.: Replace XXX with actual RFC number 1601 // and remove this note 1603 3.7. Security Considerations 1605 This entire document discusses access control requirements and 1606 mechanisms for restricting NETCONF protocol behavior within a given 1607 session. 1609 This section highlights the issues for an administrator to consider 1610 when configuring a NETCONF server with NACM. 1612 3.7.1. NACM Configuration and Monitoring Considerations 1614 Configuration of the access control system is highly sensitive to 1615 system security. A server may choose not to allow any user 1616 configuration to some portions of it, such as the global security 1617 level, or the groups which allowed access to system resources. 1619 By default, NACM enforcement is enabled. By default, "read" access 1620 to all datastore contents enabled, (unless "nacm:default-deny-all" is 1621 specified for the data definition) and "exec" access is enabled for 1622 safe protocol operations. An administrator needs to ensure that NACM 1623 is enabled, and also decide if the default access parameters are set 1624 appropriately. Make sure the following data nodes are properly 1625 configured: 1627 o /nacm/enable-nacm (default "true") 1629 o /nacm/read-default (default "permit") 1631 o /nacm/write-default (default "deny") 1633 o /nacm/exec-default (default "permit") 1635 An administrator needs to restrict write access to all configurable 1636 objects within this data model. 1638 If write access is allowed for configuration of access control rules, 1639 then care needs to be taken not to disrupt the access control 1640 enforcement. For example, if the NACM access control rules are 1641 editing directly within the running configuration datastore (i.e., 1642 :writable-running capability is supported and used), then care needs 1643 to be taken not to allow unintended access while the edits are being 1644 done. 1646 NACM requires some a user name in each NACM group mapping. An 1647 administrator needs to make sure that the translation from a 1648 transport or implementation dependant user identity to a NACM user 1649 name is unique. 1651 An administrator needs to restrict read access to the following 1652 objects within this data model, which reveal access control 1653 configuration which could be considered sensitive. 1655 o /nacm/enable-nacm 1657 o /nacm/read-default 1659 o /nacm/write-default 1661 o /nacm/exec-default 1663 o /nacm/groups 1665 o /nacm/rule-list 1667 3.7.2. General Configuration Issues 1669 There is a risk that invocation of non-standard protocol operations 1670 will have undocumented side effects. An administrator needs to 1671 construct access control rules such that the configuration datastore 1672 is protected from such side effects. 1674 It is possible for a session with some write access (e.g., allowed to 1675 invoke ), but without any access to a particular 1676 datastore subtree containing sensitive data, to determine the 1677 presence or non-presence of that data. This can be done by 1678 repeatedly issuing some sort of edit request (create, update, or 1679 delete) and possibly receiving "access-denied" errors in response. 1680 These "fishing" attacks can identify the presence or non-presence of 1681 specific sensitive data even without the "error-path" field being 1682 present within the "rpc-error" response. 1684 It is possible that the data model definition itself (e.g., YANG 1685 when-stmt) will help an unauthorized session determine the presence 1686 or even value of sensitive data nodes by examining the presence and 1687 values of different data nodes. 1689 There is a risk that non-standard protocol operations, or even the 1690 standard protocol operation, may return data which "aliases" or 1691 "copies" sensitive data from a different data object. There may 1692 simply be multiple data model definitions which expose or even 1693 configure the same underlying system instrumentation. 1695 A data model may contain external keys (e.g., YANG leafref), which 1696 expose values from a different data structure. An administrator 1697 needs to be aware of sensitive data models which contain leafref 1698 nodes. This entails finding all the leafref objects that "point" at 1699 the sensitive data (i.e., "path-stmt" values that implicitly or 1700 explicitly include the sensitive data node. 1702 It is beyond the scope of this document to define access control 1703 enforcement procedures for underlying device instrumentation that may 1704 exist to support the NETCONF server operation. An administrator can 1705 identify each protocol operation that the server provides, and decide 1706 if it needs any access control applied to it. 1708 This document incorporates the optional use of a "recovery session" 1709 mechanism, which can be used to bypass access control enforcement in 1710 emergencies, such as NACM configuration errors which disable all 1711 access to the server. The configuration and identification of such a 1712 recovery session mechanism are implementation-specific and outside 1713 the scope of this document. An administrator needs to be aware of 1714 any "recovery session" mechanisms available on the device, and make 1715 sure they are used appropriately. 1717 It is possible for a session to disrupt configuration management, 1718 even without any write access to the configuration, by locking the 1719 datastore. This may be done to insure all or part of the 1720 configuration remains stable while it is being retrieved, ot it may 1721 be done as a "denial-of-service" attack. There is no way for the 1722 server to know the difference. An administrator may wish to restrict 1723 "exec" access to the following protocol operations: 1725 o 1727 o 1729 o 1731 o 1733 3.7.3. Data Model Design Considerations 1735 Designers need to clearly identify any sensitive data, notifications, 1736 or protocol operations defined within a YANG module. For such 1737 definitions, a "nacm:default-deny-write" or "nacm:default-deny-all" 1738 statement SHOULD be present, in addition to a clear description of 1739 the security risks. 1741 Protocol operations need to be properly documented by the data model 1742 designer, so it is clear to administrators what data nodes (if any) 1743 are affected by the protocol operation, and what information (if any) 1744 is returned in the message. 1746 Data models ought to be designed so that different access levels for 1747 input parameters to protocol operations is not required. Use of 1748 generic protocol operations should be avoided, and separate protocol 1749 operations defined instead, if different access levels are needed. 1751 4. References 1753 4.1. Normative References 1755 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1756 Requirement Levels", BCP 14, RFC 2119, March 1997. 1758 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1759 January 2004. 1761 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1762 Notifications", RFC 5277, July 2008. 1764 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1765 Network Configuration Protocol (NETCONF)", RFC 6020, 1766 October 2010. 1768 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1769 October 2010. 1771 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1772 Bierman, "Network Configuration Protocol (NETCONF)", 1773 RFC 6241, June 2011. 1775 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1776 Shell (SSH)", RFC 6242, June 2011. 1778 4.2. Informative References 1780 [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, 1781 "Remote Authentication Dial In User Service (RADIUS)", 1782 RFC 2865, June 2000. 1784 [RFC5607] Nelson, D. and G. Weber, "Remote Authentication Dial-In 1785 User Service (RADIUS) Authorization for Network Access 1786 Server (NAS) Management", RFC 5607, July 2009. 1788 Appendix A. Usage Examples 1790 The following XML snippets are provided as examples only, to 1791 demonstrate how NACM can be configured to perform some access control 1792 tasks. 1794 A.1. Example 1796 There needs to be at least one entry in order for any of the 1797 access control rules to be useful. 1799 The following XML shows arbitrary groups, and is not intended to 1800 represent any particular use-case. 1802 1803 1804 1805 admin 1806 admin 1807 andy 1808 1810 1811 limited 1812 wilma 1813 bam-bam 1814 1816 1817 guest 1818 guest 1819 guest@example.com 1820 1821 1822 1824 This example shows 3 groups: 1826 1. The "admin" group contains 2 users named "admin" and "andy". 1828 2. The "limited" group contains 2 users named "wilma" and "bam-bam". 1830 3. The "guest" group contains 2 users named "guest" and 1831 "guest@example.com". 1833 A.2. Module Rule Example 1835 Module rules are used to control access to all the content defined in 1836 a specific module. A module rule has the leaf set, but 1837 no case in the "rule-type" choice. 1839 1840 1841 guest-acl 1842 guest 1844 1845 deny-ncm 1846 ietf-netconf-monitoring 1847 * 1848 deny 1849 1850 Do not allow guests any access to the netconf 1851 monitoring information. 1852 1853 1854 1856 1857 limited-acl 1858 limited 1860 1861 permit-ncm 1862 ietf-netconf-monitoring 1863 read 1864 permit 1865 1866 Allow read access to the netconf 1867 monitoring information. 1868 1869 1870 1871 permit-exec 1872 * 1873 exec 1874 permit 1875 1876 Allow invocation of the 1877 supported server operations. 1878 1879 1881 1883 1884 admin-acl 1885 admin 1887 1888 permit-all 1889 * 1890 * 1891 permit 1892 1893 Allow the admin group complete access to all 1894 operations and data. 1895 1896 1897 1898 1900 This example shows 4 module rules: 1902 deny-ncm: This rule prevents the "guest" group from reading any 1903 monitoring information in the "ietf-netconf-monitoring" YANG 1904 module. 1906 permit-ncm: This rule allows the "limited" group to read the "ietf- 1907 netconf-monitoring" YANG module. 1909 permit-exec: This rule allows the "limited" group to invoke any 1910 protocol operation supported by the server. 1912 permit-all: This rule allows the "admin" group complete access to 1913 all content in the server. No subsequent rule will match for the 1914 "admin" group, because of this module rule. 1916 A.3. RPC Rule Example 1918 RPC rules are used to control access to a specific protocol 1919 operation. 1921 1922 1923 guest-limited-acl 1924 limited 1925 guest 1927 1928 deny-kill-session 1929 ietf-netconf 1930 kill-session 1931 exec 1932 deny 1933 1934 Do not allow the limited or guest group 1935 to kill another session. 1936 1937 1938 1939 deny-delete-config 1940 ietf-netconf 1941 delete-config 1942 exec 1943 deny 1944 1945 Do not allow limited or guest group 1946 to delete any configurations. 1947 1948 1949 1951 1952 limited-acl 1953 limited 1955 1956 permit-edit-config 1957 ietf-netconf 1958 edit-config 1959 exec 1960 permit 1961 1962 Allow the limited group to edit the configuration. 1963 1964 1965 1967 1968 This example shows 3 protocol operation rules: 1970 deny-kill-session: This rule prevents the "limited" or "guest" 1971 groups from invoking the NETCONF protocol 1972 operation. 1974 deny-delete-config: This rule prevents the "limited" or "guest" 1975 groups from invoking the NETCONF protocol 1976 operation. 1978 permit-edit-config: This rule allows the "limited" group to invoke 1979 the NETCONF protocol operation. This rule will have 1980 no real effect unless the "exec-default" leaf is set to "deny". 1982 A.4. Data Rule Example 1984 Data rules are used to control access to specific (config and non- 1985 config) data nodes within the NETCONF content provided by the server. 1987 1988 1989 guest-acl 1990 guest 1992 1993 deny-nacm 1994 1995 /n:nacm 1996 1997 * 1998 deny 1999 2000 Deny the guest group any access to the /nacm data. 2001 2002 2003 2005 2006 limited-acl 2007 limited 2009 2010 permit-acme-config 2011 2012 /acme:acme-netconf/acme:config-parameters 2013 2014 2015 read create update delete 2016 2017 permit 2018 2019 Allow the limited group complete access to the acme 2020 netconf configuration parameters. Showing long form 2021 of 'access-operations' instead of shorthand. 2022 2023 2024 2026 2027 guest-limited-acl 2028 guest 2029 limited 2031 2032 permit-dummy-interface 2033 2034 /acme:interfaces/acme:interface[acme:name='dummy'] 2035 2036 read update 2037 permit 2038 2039 Allow the limited and guest groups read 2040 and update access to the dummy interface. 2041 2042 2043 2045 2046 admin-acl 2047 2048 permit-interface 2049 2050 /acme:interfaces/acme:interface 2051 2052 * 2053 permit 2054 2055 Allow admin full access to all acme interfaces. 2056 2057 2058 2059 2060 This example shows 4 data rules: 2062 deny-nacm: This rule denies the "guest" group any access to the 2063 subtree. Note that the default namespace is only 2064 applicable because this subtree is defined in the same namespace 2065 as the element. 2067 permit-acme-config: This rule gives the "limited" group read-write 2068 access to the acme . 2070 permit-dummy-interface: This rule gives the "limited" and "guest" 2071 groups read-update access to the acme . entry named 2072 "dummy". This entry cannot be created or deleted by these groups, 2073 just altered. 2075 permit-interface: This rule gives the "admin" group read-write 2076 access to all acme . entries. This is an example of an 2077 unreachable rule because the "mod-3" rule already gives the 2078 "admin" group full access to this data. 2080 A.5. Notification Rule Example 2082 Notification rules are used to control access to a specific 2083 notification event type. 2085 2086 2087 sys-acl 2088 limited 2089 guest 2091 2092 deny-config-change 2093 acme-system 2094 sys-config-change 2095 read 2096 deny 2097 2098 Do not allow the guest or limited groups 2099 to receive config change events. 2100 2101 2102 2103 2104 This example shows 1 notification rule: 2106 deny-config-change: This rule prevents the "limited" or "guest" 2107 groups from receiving the acme event type. 2109 Appendix B. Change Log 2111 -- RFC Ed.: remove this section before publication. 2113 B.1. 04-05 2115 Updated Security Considerations section. 2117 Changed term 'operator' to 'administrator'. 2119 Used the terms "access operation" and "protocol operation" 2120 consistently. 2122 Moved some normative text from section 2 to section 3. Also made it 2123 more clear that section 2 is not a requirements section, but 2124 documentation of the objectives for NACM. 2126 Renamed "nacm:secure" to "nacm:default-deny-write", and "nacm:very- 2127 secure" to "nacm:default-deny-all". Explained that "nacm:default- 2128 deny-write" is ignored on rpc statements. 2130 Described that and behave as if 2131 specified with "nacm:default-deny-all". 2133 B.2. 03-04 2135 Introduced rule-lists to group related rules together. 2137 Moved "module-rule", "rpc-rule", "notification-rule", and "data-rule" 2138 into one common "rule", with a choice to select between the four 2139 variants. 2141 Changed "superuser" to "recovery session", and adjusted text 2142 throughout document for this change. 2144 Clarified behavior of global default NACM parameters, enable-nacm, 2145 read-default, write-default, exec-default. 2147 Clarified when access control is applied during system 2148 initialization. 2150 B.3. 02-03 2152 Fixed improper usage of RFC 2119 keywords. 2154 Changed term usage of "database" to "datastore". 2156 Clarified that "secure" and "very-secure" extensions only apply if 2157 the /nacm/enable-nacm object is "true". 2159 B.4. 01-02 2161 Removed authentication text and objects. 2163 Changed module name from ietf-nacm to ietf-netconf-acm. 2165 Updated NETCONF and YANG terminology. 2167 Removed open issues section. 2169 Changed some must to MUST in requirements section. 2171 B.5. 00-01 2173 Updated YANG anf YANG Types references. 2175 Updated module namespace URI to standard format. 2177 Updated module header meta-data to standard format. 2179 Filled in IANA section. 2181 B.6. 00 2183 Initial version cloned from 2184 draft-bierman-netconf-access-control-02.txt. 2186 Authors' Addresses 2188 Andy Bierman 2189 Brocade 2191 Email: andy.bierman@brocade.com 2193 Martin Bjorklund 2194 Tail-f Systems 2196 Email: mbj@tail-f.com