idnits 2.17.1 draft-ietf-netconf-access-control-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 14, 2011) is 4701 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 (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Bierman 3 Internet-Draft Brocade 4 Intended status: Standards Track M. Bjorklund 5 Expires: December 16, 2011 Tail-f Systems 6 June 14, 2011 8 Network Configuration Protocol Access Control Model 9 draft-ietf-netconf-access-control-04 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 operations and content. 19 This document discusses requirements for a suitable access control 20 model, and provides one solution that meets these requirements. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 16, 2011. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1.1. Requirements Notation . . . . . . . . . . . . . . . . 4 59 1.1.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . 4 60 1.1.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . 5 61 1.1.4. NACM Terms . . . . . . . . . . . . . . . . . . . . . . 5 62 2. Access Control Design Objectives . . . . . . . . . . . . . . . 6 63 2.1. Protocol Control Points . . . . . . . . . . . . . . . . . 6 64 2.2. Simplicity . . . . . . . . . . . . . . . . . . . . . . . . 7 65 2.3. Procedural Interface . . . . . . . . . . . . . . . . . . . 7 66 2.4. Datastore Access . . . . . . . . . . . . . . . . . . . . . 8 67 2.4.1. Access Rights . . . . . . . . . . . . . . . . . . . . 8 68 2.4.2. and Operations . . . . . . . . . . 8 69 2.4.3. Operation . . . . . . . . . . . . . . . 9 70 2.4.4. Operation . . . . . . . . . . . . . . . 10 71 2.5. Users and Groups . . . . . . . . . . . . . . . . . . . . . 10 72 2.6. Maintenance . . . . . . . . . . . . . . . . . . . . . . . 11 73 2.7. Configuration Capabilities . . . . . . . . . . . . . . . . 11 74 2.8. Identifying Security Holes . . . . . . . . . . . . . . . . 11 75 2.9. Data Shadowing . . . . . . . . . . . . . . . . . . . . . . 12 76 2.10. NETCONF Specific Requirements . . . . . . . . . . . . . . 12 77 3. NETCONF Access Control Model (NACM) . . . . . . . . . . . . . 14 78 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 14 79 3.1.1. Features . . . . . . . . . . . . . . . . . . . . . . . 14 80 3.1.2. External Dependencies . . . . . . . . . . . . . . . . 15 81 3.1.3. Message Processing Model . . . . . . . . . . . . . . . 15 82 3.2. Model Components . . . . . . . . . . . . . . . . . . . . . 17 83 3.2.1. Users . . . . . . . . . . . . . . . . . . . . . . . . 17 84 3.2.2. Groups . . . . . . . . . . . . . . . . . . . . . . . . 17 85 3.2.3. Sessions . . . . . . . . . . . . . . . . . . . . . . . 18 86 3.2.4. Access Permissions . . . . . . . . . . . . . . . . . . 18 87 3.2.5. Global Enforcement Controls . . . . . . . . . . . . . 18 88 3.2.5.1. enable-nacm Switch . . . . . . . . . . . . . . . . 18 89 3.2.5.2. read-default Switch . . . . . . . . . . . . . . . 19 90 3.2.5.3. write-default Switch . . . . . . . . . . . . . . . 19 91 3.2.5.4. exec-default Switch . . . . . . . . . . . . . . . 19 92 3.2.6. Access Control Rules . . . . . . . . . . . . . . . . . 20 93 3.3. Access Control Enforcement Procedures . . . . . . . . . . 20 94 3.3.1. Initial Operation . . . . . . . . . . . . . . . . . . 20 95 3.3.2. Session Establishment . . . . . . . . . . . . . . . . 21 96 3.3.3. "access-denied" Error Handling . . . . . . . . . . . . 21 97 3.3.4. Incoming RPC Message Validation . . . . . . . . . . . 21 98 3.3.5. Data Node Access Validation . . . . . . . . . . . . . 24 99 3.3.6. Outgoing Authorization . . . . . . . . 26 100 3.4. Data Model Definitions . . . . . . . . . . . . . . . . . . 28 101 3.4.1. Data Organization . . . . . . . . . . . . . . . . . . 28 102 3.4.2. YANG Module . . . . . . . . . . . . . . . . . . . . . 29 103 3.5. IANA Considerations . . . . . . . . . . . . . . . . . . . 38 104 3.6. Security Considerations . . . . . . . . . . . . . . . . . 39 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. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 50 116 B.2. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 50 117 B.3. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 50 118 B.4. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 50 119 B.5. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 120 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 122 1. Introduction 124 The NETCONF protocol does not provide any standard mechanisms to 125 restrict the operations and content that each user is authorized to 126 use. 128 There is a need for inter-operable management of the controlled 129 access to operator selected portions of the available NETCONF content 130 within a particular server. 132 This document addresses access control mechanisms for the Operation 133 and Content layers of NETCONF, as defined in 134 [I-D.ietf-netconf-4741bis], and [RFC5277]. It contains three main 135 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 1.1.1. Requirements Notation 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 149 document are to be interpreted as described in [RFC2119]. 151 1.1.2. NETCONF Terms 153 The following terms are defined in [I-D.ietf-netconf-4741bis] and are 154 not redefined here: 156 o client 158 o datastore 160 o operation 162 o protocol operation 164 o server 166 o session 168 o user 170 1.1.3. YANG Terms 172 The following terms are defined in [RFC6020] and are not redefined 173 here: 175 o data node 177 o data definition statement 179 1.1.4. NACM Terms 181 The following terms are used throughout this documentation: 183 access control: A security feature provided by the NETCONF server, 184 that allows an operator to restrict access to a subset of all 185 NETCONF protocol operations and data, based on various criteria. 187 access control model (ACM): A conceptual model used to configure and 188 monitor the access control procedures desired by the operator to 189 enforce a particular access control policy. 191 access control rule: The conceptual criteria used to determine if a 192 particular NETCONF protocol operation will be permitted or denied. 194 access operation: How a request attempts to access a conceptual 195 object. One of "read", "create", "delete", "update", and 196 "execute". 198 recovery session: A special administrative session that is given 199 unlimited NETCONF access, and is exempt from all access control 200 enforcement. The specific mechanism(s) used by an implementation 201 to control and identify whether a session is a recovery session or 202 not are outside the scope of this document. 204 2. Access Control Design Objectives 206 [Editor's note: some things described here are requirements (MUST, 207 SHOULD, etc), but some things are descriptions how NACM works, e.g. 208 2.4.1, 2.4.3...] 210 2.1. Protocol Control Points 212 The NETCONF protocol allows new operations to be added at any time, 213 and the YANG data modeling language supports this feature. It is not 214 possible to design an ACM for NETCONF which only focuses on a static 215 set of operations, like some other protocols. Since few assumptions 216 can be made about an arbitrary protocol operation, the NETCONF 217 architectural server components need to be protected at several 218 conceptual control points. 220 +-------------+ +-------------+ 221 client | protocol | | prune | client 222 request --> | operation | | restricted | ---> reply 223 | allowed? | | | 224 +-------------+ | nodes? | 225 | +-------------+ 226 | if any datastore or 227 | state data is accessed 228 | by the operation 229 V 230 +-------------+ +----------------+ 231 | data node | | prune | 232 | access | | restricted | 233 | allowed? | | | ---> client 234 +-------------+ | event or data? | session 235 +----------------+ 237 Figure 1 239 The following access control points are defined: 241 protocol operation: Configurable permission to invoke specific 242 protocol operations is required. Wildcard or multiple target 243 mechanisms to reduce configuration and effort are also required. 245 NETCONF datastore: Configurable permission to read and/or alter 246 specific data nodes within any conceptual datastore is required. 247 Wildcard or multiple target mechanisms to reduce configuration and 248 effort are also required. 250 RPC Reply Content: Configurable permission to read specific data 251 nodes within any conceptual RPC output section is required. 252 Unauthorized data is silently omitted from the reply, instead of 253 dropping the reply or sending an "access-denied" error. 255 Notification Content: Configurable permission to receive specific 256 notification event types is required. 258 2.2. Simplicity 260 Experience has shown that a complicated ACM will not be widely 261 deployed, because it is too hard to use. The key factor that is 262 ignored in such solutions is the concept of "localized cost". It 263 needs to be easy to do simple things, and possible to do complex 264 things, instead of hard to do everything. 266 Configuration of the access control system needs to be as simple as 267 possible. Simple and common tasks need to be easy to configure, and 268 require little expertise or domain-specific knowledge. Complex tasks 269 are possible using additional mechanisms, which may require 270 additional expertise. 272 A single set of access control rules SHOULD be able to control all 273 types of NETCONF protocol operation invocation, all conceptual 274 datastore access, and all NETCONF session output. 276 Access control SHOULD be defined with a small and familiar set of 277 permissions, while still allowing full control of NETCONF datastore 278 access. 280 Access control does not need to be applied to NETCONF 281 messages. 283 2.3. Procedural Interface 285 The NETCONF protocol uses a procedural interface model, and an 286 extensible set of protocol operations. Access control for any 287 possible protocol operation is required. 289 It MUST be possible to configure the ACM to permit or deny access to 290 specific NETCONF operations. 292 YANG modules SHOULD be designed so that different access levels for 293 input parameters to protocol operations is not required. Use of 294 generic operations should be avoided, and separate operations defined 295 instead, if different access levels are needed. 297 2.4. Datastore Access 299 It MUST be possible to control access to specific nodes and subtrees 300 within the conceptual NETCONF datastore. 302 The same access control rules apply to all conceptual datastores. 303 For example, the candidate configuration or the running 304 configuration. 306 Only the standard NETCONF datastores (candidate, running, and 307 startup) are controlled by the ACM. Local or remote files or 308 datastores accessed via the parameter are optional to support. 310 The non-volatile startup configuration needs to be loaded at boot- 311 time into the running configuration without applying any access 312 control rules. Access control is applied after the server has 313 booted, and user sessions are active. 315 2.4.1. Access Rights 317 A small set of hard-wired datastore access rights is needed to 318 control access to all possible NETCONF datastore operations, 319 including vendor extensions to the standard operation set. 321 The familiar "CRUDX" model can support all NETCONF operations: 323 o Create: Allows the client to add a new data node instance to a 324 datastore. 326 o Read: Allows the client to read a data node instance from a 327 datastore, or receive the notification event type. 329 o Update: Allows the client to update an existing data node instance 330 in a datastore. 332 o Delete: Allows the client to delete a data node instance from a 333 datastore. 335 o eXec: Allows the client to execute the protocol operation. 337 2.4.2. and Operations 339 Data nodes to which the client does not have read access, either 340 directly or via wildcard access, are silently omitted from the message. This is done to allow NETCONF filters for and 342 to function properly, instead of causing an "access- 343 denied" error because the filter criteria would otherwise include 344 unauthorized read access to some data nodes. For NETCONF filtering 345 purposes, the selection criteria is applied to the subset of nodes 346 that the client is authorized to read, not the entire datastore. 348 2.4.3. Operation 350 The NACM access rights are not directly coupled to the 351 "operation" attribute, although they are similar. Instead, a NACM 352 access right applies to all operations which would result in a 353 particular access operation to the target datastore. This section 354 describes how these access rights apply to the specific datastore 355 operations supported by the operation. 357 If the effective operation is "none" (i.e., default-operation="none") 358 for a particular data node, then no access control is applied to that 359 data node. 361 A "create", "merge", or "replace" operation on a datastore node which 362 would result in the creation of a new data node instance, for which 363 the user does not have "create" access permission, is rejected with 364 an "access-denied" error. 366 A "merge" or "replace" operation on a datastore node which would 367 result in the modification of an existing data node instance, for 368 which the user does not have "update" access permission, is rejected 369 with an "access-denied" error. 371 A "replace", "delete", or "remove" operation on a datastore node 372 which would result in the deletion of an existing data node instance, 373 for which the user does not have "delete" access permission, is 374 rejected with an "access-denied" error. 376 A "merge" operation may include data nodes which do not alter 377 portions of the existing datastore. For example, a container or list 378 node may be present for naming purposes, but does not actually alter 379 the corresponding datastore node. These unaltered data nodes within 380 the scope of a "merge" operation are ignored by the server, and do 381 not require any access rights by the client. 383 [Editor's note: ditto for "replace" (and copy-config...) Note that 384 with this rule, a client w/o read access can guess db content by 385 sending merge requests - if access-denied is not returned, it means 386 the db has that value.] 388 A "merge" operation may include data nodes, but not include 389 particular child data nodes that are present in the datastore. These 390 missing data nodes within the scope of a "merge" operation are 391 ignored by the server, and do not require any access rights by the 392 client. 394 The contents of specific restricted datastore nodes MUST NOT be 395 exposed in any elements within the reply. 397 2.4.4. Operation 399 Access control for the operation requires special 400 consideration because the operator is replacing the entire target 401 datastore. Read access to the entire source datastore, and write 402 access to the entire target datastore is needed for this operation to 403 succeed. 405 The server SHOULD determine the exact nodes in the target datastore 406 which are actually different, and only check write access permissions 407 for this set of nodes, which could be empty. For example, if a 408 session can read the entire datastore, but only change one leaf, that 409 session SHOULD be able to edit and save that one leaf. E.g., the 410 operation from to SHOULD succeed if 411 the only effective changes are for data nodes that session is 412 authorized to change. 414 A client MUST have access to every datastore node, even ones that are 415 not present in the source configuration data. 417 For example, consider a common use-case such as a simple backup and 418 restore procedure. The operator (client) MUST have full read access 419 to the datastore in order to receive a complete copy of its contents. 420 If the server simply omits these subtrees from the reply, and that 421 copy is later used to restore the server datastore, the server will 422 interpret the missing nodes as a request to delete those nodes, and 423 return an error. 425 2.5. Users and Groups 427 The server MUST obtain a user name from the underlying NETCONF 428 transport, such as an SSH user name. 430 It MUST be possible to specify access control rules for a single user 431 or a configurable group of users. 433 The ACM MUST support the concept of administrative groups, to support 434 the well-established distinction between a root account and other 435 types of less-privileged conceptual user accounts. These groups MUST 436 be configurable by the operator. 438 It MUST be possible to delegate the user-to-group mapping to a 439 central server, such as a RADIUS server [RFC2865] [RFC5607]. Since 440 authentication is performed by the NETCONF transport layer, and 441 RADIUS performs authentication and service authorization at the same 442 time, it MUST be possible for the underlying NETCONF transport to 443 report a set of group names associated with the user to the server. 445 2.6. Maintenance 447 It SHOULD be possible to disable part or all of the access control 448 model without deleting any configuration. 450 2.7. Configuration Capabilities 452 Suitable control and monitoring mechanisms are needed to allow an 453 operator to easily manage all aspects of the ACM behavior. A 454 standard data model, suitable for use with the 455 operation MUST be available for this purpose. 457 Access control rules to restrict operations on specific subtrees 458 within the configuration datastore MUST be supported. Existing 459 mechanisms can be used to identify the subtree(s) for this purpose. 461 2.8. Identifying Security Holes 463 One of the most important aspects of the data model documentation, 464 and biggest concerns during deployment, is the identification of 465 security-sensitive content. This applies to operations in NETCONF, 466 not just data and notifications. 468 It is mandatory for security-sensitive objects to be documented in 469 the Security Considerations section of an RFC. This is nice, but it 470 is not good enough, for the following reasons: 472 o This documentation-only approach forces operators to study the RFC 473 and determine if there are any potential security holes introduced 474 by a new YANG module. 476 o If any security holes are identified, then the operator can study 477 some more RFC text, and determine how to close the security 478 hole(s). 480 o The ACM on each server can be configured to close the security 481 holes, e.g., require privileged access to read or write the 482 specific data identified in the Security Considerations section. 484 o If the ACM is not pre-configured, then there will be a time window 485 of vulnerability, after the new module is loaded, and before the 486 new access control rules for that module are configured, enabled, 487 and debugged. 489 Often, the operator just wants to disable default access to the 490 secure content, so no inadvertent or malicious changes can be made to 491 the server. This allows the default rules to be more lenient, 492 without significantly increasing the security risk. 494 A data model designer needs to be able to use machine-readable 495 statements to identify NETCONF content which needs to be protected by 496 default. This will allow client and server tools to automatically 497 close data-model specific security holes, by denying access to 498 sensitive data unless the user is explicitly authorized to perform 499 the requested operation. 501 2.9. Data Shadowing 503 One of the more complicated security administration problems is 504 identifying data nodes which shadow or mirror the content of another 505 data node. An access control rule to prevent read operations for a 506 particular node may be insufficient to prevent access to the data 507 node with the copied value. 509 If the description statement, other documentation, or no 510 documentation exists to identify a data shadow problem, then it may 511 not be detected. 513 Since NETCONF allows any vendor operation to be added to the 514 protocol, there is no way to reliably identify all of the operations 515 that may expose copies of sensitive data nodes in 516 messages. 518 A NETCONF server MUST ensure that unauthorized access to its 519 conceptual datastores and non-configuration data nodes is prevented. 521 It is beyond the scope of this document to define access control 522 enforcement procedures for underlying device instrumentation that may 523 exist to support the NETCONF server operation. An operator can 524 identify each operation that the server provides, and decide if it 525 needs any access control applied to it. 527 Proprietary protocol operations SHOULD be properly documented by the 528 vendor, so it is clear to operators what data nodes (if any) are 529 affected by the operation, and what information (if any) is returned 530 in the message. 532 2.10. NETCONF Specific Requirements 534 The server MUST be able to identify the specific protocol access 535 request at the 4 access control points defined above. 537 The server MUST be able to identify any datastore access request, 538 even for proprietary operations. 540 A client MUST always be authorized to invoke the 541 operation, defined in [I-D.ietf-netconf-4741bis]. 543 A client MUST always be authorized to receive the 544 and notification events, defined in [RFC5277] 546 The set of module name strings used within one particular server MUST 547 be unique. 549 3. NETCONF Access Control Model (NACM) 551 3.1. Introduction 553 This section provides a high-level overview of the access control 554 model structure. It describes the NETCONF protocol message 555 processing model, and the conceptual access control requirements 556 within that model. 558 3.1.1. Features 560 The NACM data model provides the following features: 562 o Independent control of RPC, data, and notification access. 564 o Simple access control rules configuration data model that is easy 565 to use. 567 o The concept of an emergency recovery session is supported, but 568 configuration of the server for this purpose is beyond the scope 569 of this document. An emergency recovery session will bypass all 570 access control enforcement, in order to allow it to initialize or 571 repair the NACM configuration. 573 o A simple and familiar set of datastore permissions is used. 575 o Support for YANG security tagging (e.g., nacm:secure extension) 576 allows default security modes to automatically exclude sensitive 577 data. 579 o Separate default access modes for read, write, and execute 580 permissions. 582 o Access control rules are applied to configurable groups of users. 584 o The entire ACM can be disabled during operation, in order to debug 585 operational problems. 587 o Access control rules are simple to configure. 589 o The number of denied protocol operation requests and denied 590 datastore write requests can be monitored by the client. 592 o Simple unconstrained YANG instance identifiers are used to 593 configure access control rules for specific data nodes. 595 3.1.2. External Dependencies 597 The NETCONF [I-D.ietf-netconf-4741bis] protocol is used for all 598 management purposes within this document. It is expected that the 599 mandatory transport mapping NETCONF Over SSH 600 [I-D.ietf-netconf-rfc4742bis] is also supported by the server, and 601 that the server has access to the user name associated with each 602 session. 604 The YANG Data Modeling Language [RFC6020] is used to define the 605 NETCONF data models specified in this document. 607 3.1.3. Message Processing Model 609 The following diagram shows the NETCONF message flow model, including 610 the points at which access control is applied, during NETCONF message 611 processing. 613 +-------------------------+ 614 | session | 615 | (username) | 616 +-------------------------+ 617 | ^ 618 V | 619 +--------------+ +---------------+ 620 | message | | message | 621 | dispatcher | | generator | 622 +--------------+ +---------------+ 623 | ^ ^ 624 V | | 625 +===========+ +-------------+ +----------------+ 626 | |---> | | | | 627 | acc. ctl | | generator | | generator | 628 +===========+ +-------------+ +----------------+ 629 | ^ ^ ^ 630 V +------+ | | 631 +-----------+ | +=============+ +================+ 632 | | | | | | | 633 | processor |-+ | acc. ctl | | access ctl | 634 +-----------+ +=============+ +================+ 635 | | ^ ^ 636 V +----------------+ | | 637 +===========+ | | | 638 | data node | | | | 639 | acc. ctl | -----------+ | | | 640 +===========+ | | | | 641 | | | | | 642 V V V | | 643 +---------------+ +-----------------+ 644 | configuration | ---> | server | 645 | datastore | | instrumentation | 646 | | <--- | | 647 +---------------+ +-----------------+ 649 Figure 2 651 The following high-level sequence of conceptual processing steps is 652 executed for each received message, if access control 653 enforcement is enabled: 655 o Access control is applied to all messages (except ) received by the server, individually, for each active 657 session, unless the session is identified as a "recovery session". 659 o If the session is authorized to execute the specified RPC 660 operation, then processing continues, otherwise the request is 661 rejected with an "access-denied" error. 663 o If the configuration datastore or conceptual state data is 664 accessed by the protocol operation, then the data node access MUST 665 be authorized. If the session is authorized to perform the 666 requested operation on the requested data, then processing 667 continues. 669 The following sequence of conceptual processing steps is executed for 670 each generated notification event, if access control enforcement is 671 enabled: 673 o Server instrumentation generates a conceptual notification, for a 674 particular subscription. 676 o The notification access control enforcer checks the notification 677 event type, and if it is one which the session is not authorized 678 to read, then the notification is dropped for that subscription. 680 3.2. Model Components 682 This section defines the conceptual components related to access 683 control model. 685 3.2.1. Users 687 A "user" is the conceptual entity that is associated with the access 688 permissions granted to a particular session. A user is identified by 689 a string which MUST be unique within the server. 691 As described in [I-D.ietf-netconf-4741bis], the user name string is 692 derived from the transport layer during session establishment. If 693 the transport layer cannot authenticate the user, the session is 694 terminated. 696 The server MAY support a "recovery session" mechanism, which will 697 bypass all access control enforcement. This is useful for 698 restricting initial access and repairing a broken access control 699 configuration. 701 3.2.2. Groups 703 Access to a specific NETCONF operation is granted to a session, 704 associated with a group, not a user. 706 A group is identified by its name. All group names MUST be unique 707 within the server. 709 A group member is identified by a user name string. 711 The same user may be configured in multiple groups. 713 3.2.3. Sessions 715 A session is simply a NETCONF session, which is the entity that is 716 granted access to specific NETCONF operations. 718 A session is associated with a single user name for the lifetime of 719 the session. 721 3.2.4. Access Permissions 723 The access permissions are the NETCONF protocol specific set of 724 permissions that have been assigned to a particular session. 726 The same access permissions MUST stay in effect for the processing of 727 a particular message. 729 The server MUST use the access control rules in effect at the time 730 the message is processed. 732 The access control model treats protocol operation execution 733 separately from configuration datastore access and outgoing messages: 735 create: Permission to create conceptual server data. 737 read: Read access to conceptual server data, and 738 content. 740 update: Permission to modify existing conceptual server data. 742 delete: Permission to delete existing conceptual server data. 744 exec: Permission to invoke a protocol operation. 746 3.2.5. Global Enforcement Controls 748 There are four global controls that are used to help control how 749 access control is enforced. 751 3.2.5.1. enable-nacm Switch 753 A global "enable-nacm" on/off switch is provided to enable or disable 754 all access control enforcement. When this global switch is set to 755 "true", then all access requested are checked against the access 756 control rules, and only permitted if configured to allow the specific 757 access request. When this global switch is set to "false", then all 758 access requested are permitted. 760 3.2.5.2. read-default Switch 762 An on/off "read-default" switch is provided to enable or disable 763 default access to receive data in replies and notifications. When 764 the "enable-nacm" global switch is set to "true", then this global 765 switch is relevant, if no matching access control rule is found to 766 explicitly permit or deny read access to the requested NETCONF 767 datastore data or notification event type. 769 When this global switch is set to "permit", and no matching access 770 control rule is found for the NETCONF datastore read or notification 771 event requested, then access is permitted. 773 When this global switch is set to "deny", and no matching access 774 control rule is found for the NETCONF datastore read or notification 775 event requested, then access is denied. 777 3.2.5.3. write-default Switch 779 An on/off "write-default" switch is provided to enable or disable 780 default access to alter configuration data. When the "enable-nacm" 781 global switch is set to "true", then this global switch is relevant, 782 if no matching access control rule is found to explicitly permit or 783 deny write access to the requested NETCONF datastore data. 785 When this global switch is set to "permit", and no matching access 786 control rule is found for the NETCONF datastore write requested, then 787 access is permitted. 789 When this global switch is set to "deny", and no matching access 790 control rule is found for the NETCONF datastore write requested, then 791 access is denied. 793 3.2.5.4. exec-default Switch 795 An on/off "exec-default" switch is provided to enable or disable 796 default access to execute protocol operations. When the "enable- 797 nacm" global switch is set to "true", then this global switch is 798 relevant, if no matching access control rule is found to explicitly 799 permit or deny access to the requested NETCONF protocol operation. 801 When this global switch is set to "permit", and no matching access 802 control rule is found for the NETCONF protocol operation requested, 803 then access is permitted. 805 When this global switch is set to "deny", and no matching access 806 control rule is found for the NETCONF protocol operation requested, 807 then access is denied. 809 3.2.6. Access Control Rules 811 There are 4 types of rules available in NACM: 813 module rule: Controls access for definitions in a specific module, 814 identified by its name. 816 protocol operation rule: Controls access for a specific protocol 817 operation, identified by its module and name. 819 data node rule: Controls access for a specific data node, identified 820 by its path location within the conceptual XML document for the 821 data node. 823 notification rule: Controls access for a specific notification event 824 type, identified by its module and name. 826 3.3. Access Control Enforcement Procedures 828 There are seven separate phases that need to be addressed, four of 829 which are related to the NETCONF message processing model. In 830 addition, the initial start-up mode for a NETCONF server, session 831 establishment, and "access-denied" error handling procedures also 832 need to be considered. 834 3.3.1. Initial Operation 836 Upon the very first start-up of the NETCONF server, the access 837 control configuration will probably not be present. If it isn't, a 838 server MUST NOT allow any write access to any session role except a 839 "recovery session", if supported. 841 Access control rules are not enforced before or while the non- 842 volatile configuration data is processed and loaded into the running 843 configuration, when the server is booting or rebooting. Access rules 844 are enforced any time a request is initiated from a user session. 845 Access control is not enforced for server-initiated access requests, 846 such as the initial load of the running datastore, during bootup. 848 3.3.2. Session Establishment 850 The access control model applies specifically to the well-formed XML 851 content transferred between a client and a server, after session 852 establishment has been completed, and after the exchange has 853 been successfully completed. 855 A server SHOULD NOT include any sensitive information in any 856 elements within the exchange. 858 Once session establishment is completed, and a user has been 859 authenticated, the NETCONF transport layer reports the user name and 860 a possibly empty set of group names associated with the user to the 861 NETCONF server. The NETCONF server will enforce the access control 862 rules, based on the supplied user name, group names, and the 863 configuration data stored on the server. 865 3.3.3. "access-denied" Error Handling 867 The "access-denied" error-tag is generated when the access control 868 system denies access to either a request to invoke a protocol 869 operation or a request to perform a particular operation on the 870 configuration datastore. 872 A server MUST NOT include any sensitive information in any elements within the response. 875 3.3.4. Incoming RPC Message Validation 877 The diagram below shows the basic conceptual structure of the access 878 control processing model for incoming NETCONF messages, within 879 a server. 881 NETCONF server 882 +------------+ 883 | XML | 884 | message | 885 | dispatcher | 886 +------------+ 887 | 888 | 889 V 890 +------------+ 891 | NC-base NS | 892 | | 893 +------------+ 894 | | | 895 | | +-------------------------+ 896 | +------------+ | 897 V V V 898 +-----------+ +---------------+ +------------+ 899 | acme NS | | NC-base NS | | NC-base NS | 900 | | | | | | 901 +-----------+ +---------------+ +------------+ 902 | | 903 | | 904 V V 905 +----------------------+ 906 | | 907 | configuration | 908 | datastore | 909 +----------------------+ 911 Figure 3 913 Access control begins with the message dispatcher. 915 After the server validates the element, and determines the 916 namespace URI and the element name of the protocol operation being 917 requested, the RPC access control enforcer verifies that the session 918 is authorized to invoke the protocol operation. 920 The protocol operation is authorized by following these steps: 922 1. If the "enable-nacm" leaf is set to "false", then the protocol 923 operation is permitted. 925 2. If the requesting session is identified as a "recovery session", 926 then the protocol operation is permitted. 928 3. If the requested operation is the NETCONF 929 operation, then the protocol operation is permitted. 931 4. Check all the "group" entries for ones that contain a "user- 932 name" entry that equals the user name for the session making the 933 request. Add to these groups the set of groups provided by the 934 transport layer. 936 5. If no groups are found, continue with step 10. 938 6. Process all rule-list entries, in order. If a rule-list's 939 "group" leaf-list does not match any of the user's groups, 940 proceed to the next rule-list entry. 942 7. For each rule-list entry found, process all rules, in order, 943 until a rule that matches the requested operation is found. A 944 rule matches if all of the following criteria are met: 946 * The rule's "module-name" leaf is "*", or equals the name of 947 the YANG module where the protocol operation is defined. 949 * The rule does not have a "rule-type" defined, or the "rule- 950 type" is "protocol-operation" and the "rpc-name" is "*" or 951 equals the name of the requested protocol operation. 953 * The rule's "access-operations" leaf has the "exec" bit set, 954 or has the special value "*". 956 8. If a matching rule is found, then the "action" leaf is checked. 957 If it is equal to "permit", then the protocol operation is 958 permitted, otherwise it is denied. 960 9. Otherwise, no matching rule was found in any rule-list entry. 962 10. If the requested protocol operation is defined in a YANG module 963 advertised in the server capabilities, and the "rpc" statement 964 contains a "nacm:secure" or a "nacm:very-secure" statement, then 965 the protocol operation is denied. 967 11. If the "exec-default" leaf is set to "permit", then permit the 968 protocol operation, otherwise deny the request. 970 If the session is not authorized to invoke the protocol operation 971 then an is generated with the following information: 973 error-tag: access-denied 975 error-path: Identifies the requested protocol operation. For 976 example: 978 980 /nc:rpc/nc:edit-config 981 983 represents the operation in the NETCONF base 984 namespace. 986 If a datastore is accessed, either directly or as a side effect of 987 the protocol operation, then the server MUST intercept the operation 988 and make sure the session is authorized to perform the requested 989 operation on the specified data, as defined in Section 3.3.5. 991 3.3.5. Data Node Access Validation 993 If a data node within a datastore is accessed, then the server MUST 994 ensure that the client session is authorized to perform the requested 995 read, create, update, or delete operation on the specified data node. 997 The data node access request is authorized by following these steps: 999 1. If the "enable-nacm" leaf is set to "false", then the protocol 1000 operation is permitted. 1002 2. If the requesting session is identified as a "recovery session", 1003 then the protocol operation is permitted. 1005 3. Check all the "group" entries for ones that contain a "user- 1006 name" entry that equals the user name for the session making the 1007 request. Add to these groups the set of groups provided by the 1008 transport layer. 1010 4. If no groups are found, continue with step 9. 1012 5. Process all rule-list entries, in order. If a rule-list's 1013 "group" leaf-list does not match any of the user's groups, 1014 proceed to the next rule-list entry. 1016 6. For each rule-list entry found, process all rules, in order, 1017 until a rule that matches the requested operation is found. A 1018 rule matches if all of the following criteria are met: 1020 * The rule's "module-name" leaf is "*", or equals the name of 1021 the YANG module where the protocol operation is defined. 1023 * The rule does not have a "rule-type" defined, or the "rule- 1024 type" is "data-node" and the "path" matches the requested 1025 data node. 1027 * For a read operation, the rule's "access-operations" leaf has 1028 the "read" bit set, or has the special value "*". 1030 * For a creation operation, the rule's "access-operations" leaf 1031 has the "create" bit set, or has the special value "*". 1033 * For a deletion operation, the rule's "access-operations" leaf 1034 has the "delete" bit set, or has the special value "*". 1036 * For an update operation, the rule's "access-operations" leaf 1037 has the "update" bit set, or has the special value "*". 1039 7. If a matching rule is found, then the "action" leaf is checked. 1040 If it is equal to "permit", then the data node access is 1041 permitted, otherwise it is denied. For a read operation, 1042 "denied" means that the requested data is not returned in the 1043 reply. 1045 8. Otherwise, no matching rule was found in any rule-list entry. 1047 9. For a read operation, if the requested data node is defined in a 1048 YANG module advertised in the server capabilities, and the data 1049 definition statement contains a "nacm:very-secure" statement, 1050 then the requested data node is not included in the reply. 1052 10. For a write operation, if the requested data node is defined in 1053 a YANG module advertised in the server capabilities, and the 1054 data definition statement contains a "nacm:secure" or a "nacm: 1055 very-secure" statement, then the data node access request is 1056 denied. 1058 11. For a read operation, if the "read-default" leaf is set to 1059 "permit", then include the requested data node in the reply, 1060 otherwise do not include the requested data node in the reply. 1062 12. For a write operation, if the "write-default" leaf is set to 1063 "permit", then permit the data node access request, otherwise 1064 deny the request. 1066 3.3.6. Outgoing Authorization 1068 Configuration of access control rules specifically for descendant 1069 nodes of the notification event type element are outside the scope of 1070 this document. If the session is authorized to receive the 1071 notification event type, then it is also authorized to receive any 1072 data it contains. 1074 The following figure shows the conceptual message processing model 1075 for outgoing messages. 1077 NETCONF server 1078 +------------+ 1079 | XML | 1080 | message | 1081 | generator | 1082 +------------+ 1083 ^ 1084 | 1085 +----------------+ 1086 | | 1087 | generator | 1088 +----------------+ 1089 ^ 1090 | 1091 +=================+ 1092 | | 1093 | access control | 1094 | | 1095 +=================+ 1096 ^ 1097 | 1098 +------------------------+ 1099 | server instrumentation | 1100 +------------------------+ 1101 | ^ 1102 V | 1103 +----------------------+ 1104 | configuration | 1105 | datastore | 1106 +----------------------+ 1108 Figure 4 1110 The generation of a notification for a specific subscription is 1111 authorized by following these steps: 1113 1. If the "enable-nacm" leaf is set to "false", then the 1114 notification is permitted. 1116 2. If the session is identified as a "recovery session", then the 1117 notification is permitted. 1119 3. If the notification is the NETCONF or 1120 event type, then the notification is 1121 permitted. 1123 4. Check all the "group" entries for ones that contain a "user- 1124 name" entry that equals the user name for the session making the 1125 request. Add to these groups the set of groups provided by the 1126 transport layer. 1128 5. If no groups are found, continue with step 10. 1130 6. Process all rule-list entries, in order. If a rule-list's 1131 "group" leaf-list does not match any of the user's groups, 1132 proceed to the next rule-list entry. 1134 7. For each rule-list entry found, process all rules, in order, 1135 until a rule that matches the requested operation is found. A 1136 rule matches if all of the following criteria are met: 1138 * The rule's "module-name" leaf is "*", or equals the name of 1139 the YANG module where the protocol operation is defined. 1141 * The rule does not have a "rule-type" defined, or the "rule- 1142 type" is "notification" and the "notification-name" is "*", 1143 equals the name of the notification. 1145 * The rule's "access-operations" leaf has the "read" bit set, 1146 or has the special value "*". 1148 8. If a matching rule is found, then the "action" leaf is checked. 1149 If it is equal to "permit", then permit the notification, 1150 otherwise drop the notification for the associated subscription. 1152 9. Otherwise, no matching rule was found in any rule-list entry. 1154 10. If the requested notification is defined in a YANG module 1155 advertised in the server capabilities, and the "notification" 1156 statement contains a "nacm:very-secure" statement, then the 1157 notification is dropped for the associated subscription. 1159 11. If the "read-default" leaf is set to "permit", then permit the 1160 notification, otherwise drop the notification for the associated 1161 subscription. 1163 3.4. Data Model Definitions 1165 This section defines the semantics of the conceptual data structures 1166 found in the data model in Section 3.4. 1168 3.4.1. Data Organization 1170 The top-level element is called , and it is defined in the 1171 "ietf-netconf-acm" module's namespace. 1173 There are several data structures defined as child nodes of the 1174 element: 1176 leaf : On/off boolean switch to enable or disable 1177 access control enforcement. 1179 leaf : Enumeration to permit or deny default read 1180 access requests. 1182 leaf : Enumeration to permit or deny default write 1183 access requests. 1185 leaf : Enumeration to permit or deny default protocol 1186 operation execution requests. 1188 leaf : Read-only counter of the number of times the 1189 server has denied an RPC operation request, since the last reboot 1190 of the server. 1192 leaf : Read-only counter of the number of times 1193 the server has denied a data node write request, since the last 1194 reboot of the server. 1196 leaf : Read-only counter of the number of 1197 times the server has denied a notification, since the last reboot 1198 of the server. 1200 container : Configures the groups used within the access 1201 control system. 1203 list : A list of user names belonging to the same 1204 administrative group. 1206 container : Configures the access control rules used within 1207 the server. 1209 list : An ordered collection of related access control 1210 rules. 1212 list : Configures the access control rules for protocol 1213 operation invocation, configuration datastore access, and 1214 for controlling delivery of events. 1216 3.4.2. YANG Module 1218 The following YANG module specifies the normative NETCONF content 1219 that MUST by supported by the server. 1221 The ietf-netconf-acm YANG module imports typedefs from [RFC6021]. 1223 // RFC Ed.: please update the date to the date of publication 1224 file="ietf-netconf-acm@2011-06-14.yang" 1226 module ietf-netconf-acm { 1228 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-acm"; 1230 prefix "nacm"; 1232 import ietf-yang-types { 1233 prefix yang; 1234 } 1236 organization 1237 "IETF NETCONF (Network Configuration) Working Group"; 1239 contact 1240 "WG Web: 1241 WG List: 1243 WG Chair: Mehmet Ersue 1244 1246 WG Chair: Bert Wijnen 1247 1249 Editor: Andy Bierman 1250 1252 Editor: Martin Bjorklund 1253 "; 1255 description 1256 "NETCONF Server Access Control Model. 1258 Copyright (c) 2011 IETF Trust and the persons identified as 1259 authors of the code. All rights reserved. 1261 Redistribution and use in source and binary forms, with or 1262 without modification, is permitted pursuant to, and subject 1263 to the license terms contained in, the Simplified BSD 1264 License set forth in Section 4.c of the IETF Trust's 1265 Legal Provisions Relating to IETF Documents 1266 (http://trustee.ietf.org/license-info). 1268 This version of this YANG module is part of RFC XXXX; see 1269 the RFC itself for full legal notices."; 1270 // RFC Ed.: replace XXXX with actual RFC number and 1271 // remove this note 1273 // RFC Ed.: remove this note 1274 // Note: extracted from draft-ietf-netconf-access-control-04.txt 1276 // RFC Ed.: please update the date to the date of publication 1277 revision "2011-06-14" { 1278 description 1279 "Initial version"; 1280 reference 1281 "RFC XXXX: Network Configuration Protocol 1282 Access Control Model"; 1283 } 1285 /* 1286 * Extension statements 1287 */ 1289 extension secure { 1290 description 1291 "Used to indicate that the data model node 1292 represents a sensitive security system parameter. 1294 If present, and the NACM module is enabled (i.e., 1295 /nacm/enable-nacm object equals 'true'), the NETCONF server 1296 will only allow the designated 'recovery session' to have 1297 write or execute access to the node. An explicit access 1298 control rule is required for all other users. 1300 The 'secure' extension MAY appear within a data definition 1301 statement or rpc statement. It is ignored otherwise."; 1302 } 1304 extension very-secure { 1305 description 1306 "Used to indicate that the data model node 1307 controls a very sensitive security system parameter. 1309 If present, and the NACM module is enabled (i.e., 1310 /nacm/enable-nacm object equals 'true'), the NETCONF server 1311 will only allow the designated 'recovery session' to have 1312 read, write, or execute access to the node. An explicit 1313 access control rule is required for all other users. 1315 The 'very-secure' extension MAY appear within a data 1316 definition statement, rpc statement, or notification 1317 statement. It is ignored otherwise."; 1318 } 1320 /* 1321 * Derived types 1322 */ 1324 typedef user-name-type { 1325 type string { 1326 length "1..max"; 1327 } 1328 description 1329 "General Purpose User Name string."; 1330 } 1332 typedef matchall-string-type { 1333 type string { 1334 pattern "\*"; 1335 } 1336 description 1337 "The string containing a single asterisk '*' is used 1338 to conceptually represent all possible values 1339 for the particular leaf using this data type."; 1340 } 1342 typedef access-operations-type { 1343 type bits { 1344 bit create { 1345 description 1346 "Any operation that creates a 1347 new instance of the specified data is a create 1348 operation."; 1349 } 1350 bit read { 1351 description 1352 "Any operation or notification that 1353 returns data to an application is a read 1354 operation."; 1355 } 1356 bit update { 1357 description 1358 "Any operation that alters an existing 1359 data node is an update operation."; 1360 } 1361 bit delete { 1362 description 1363 "Any operation that removes a datastore 1364 node instance is a delete operation."; 1365 } 1366 bit exec { 1367 description 1368 "Execution access to the specified RPC operation. 1369 Any RPC operation invocation is an exec operation."; 1370 } 1371 } 1372 description 1373 "NETCONF Access Operation."; 1374 } 1376 typedef group-name-type { 1377 type string { 1378 length "1..max"; 1379 pattern "[^\*].*"; 1380 } 1381 description 1382 "Name of administrative group that can be 1383 assigned to the user, and specified in 1384 an access control rule-list."; 1385 } 1387 typedef action-type { 1388 type enumeration { 1389 enum permit { 1390 description 1391 "Requested action is permitted."; 1392 } 1393 enum deny { 1394 description 1395 "Requested action is denied."; 1397 } 1398 } 1399 description 1400 "Action taken by the server when a particular 1401 rule matches."; 1402 } 1404 typedef node-instance-identifier { 1405 type yang:xpath1.0; 1406 description 1407 "Path expression used to represent a special 1408 data node instance identifier string. 1410 A node-instance-identifier value is an 1411 unrestricted YANG instance-identifier expression. 1412 All the same rules as an instance-identifier apply 1413 except predicates for keys are optional. If a key 1414 predicate is missing, then the node-instance-identifier 1415 represents all possible server instances for that key. 1417 This XPath expression is evaluated in the following context: 1419 o The set of namespace declarations are those in scope on 1420 the leaf element where this type is used. 1422 o The set of variable bindings contains one variable, 1423 'USER', which contains the name of user of the current 1424 session. 1426 o The function library is the core function library, but 1427 note that due to the syntax restrictions of an 1428 instance-identifier, no functions are allowed. 1430 o The context node is the root node in the data tree."; 1431 } 1433 container nacm { 1434 nacm:very-secure; 1436 description 1437 "Parameters for NETCONF Access Control Model."; 1439 leaf enable-nacm { 1440 type boolean; 1441 default true; 1442 description 1443 "Enable or disable all NETCONF access control 1444 enforcement. If 'true', then enforcement 1445 is enabled. If 'false', then enforcement 1446 is disabled."; 1447 } 1449 leaf read-default { 1450 type action-type; 1451 default "permit"; 1452 description 1453 "Controls whether read access is granted if 1454 no appropriate rule is found for a 1455 particular read request."; 1456 } 1458 leaf write-default { 1459 type action-type; 1460 default "deny"; 1461 description 1462 "Controls whether create, update, or delete access 1463 is granted if no appropriate rule is found for a 1464 particular write request."; 1465 } 1467 leaf exec-default { 1468 type action-type; 1469 default "permit"; 1470 description 1471 "Controls whether exec access is granted if no appropriate 1472 rule is found for a particular RPC operation request."; 1473 } 1475 leaf denied-rpcs { 1476 type yang:zero-based-counter32; 1477 config false; 1478 mandatory true; 1479 description 1480 "Number of times an RPC operation request was denied 1481 since the server last restarted."; 1482 } 1484 leaf denied-data-writes { 1485 type yang:zero-based-counter32; 1486 config false; 1487 mandatory true; 1488 description 1489 "Number of times a request to alter a data node 1490 was denied, since the server last restarted."; 1491 } 1492 leaf denied-notifications { 1493 type yang:zero-based-counter32; 1494 config false; 1495 mandatory true; 1496 description 1497 "Number of times a notification was denied 1498 since the server last restarted."; 1499 } 1501 container groups { 1502 description 1503 "NETCONF Access Control Groups."; 1505 list group { 1506 key name; 1508 description 1509 "One NACM Group Entry."; 1511 leaf name { 1512 type group-name-type; 1513 description 1514 "Group name associated with this entry."; 1515 } 1517 leaf-list user-name { 1518 type user-name-type; 1519 description 1520 "Each entry identifies the user name of 1521 a member of the group associated with 1522 this entry."; 1523 } 1524 } 1525 } 1527 list rule-list { 1528 key "name"; 1529 ordered-by user; 1530 description 1531 "An ordered collection of access control rules."; 1533 leaf name { 1534 type string { 1535 length "1..256"; 1536 } 1537 description 1538 "Arbitrary name assigned to the rule-list."; 1539 } 1540 leaf-list group { 1541 type union { 1542 type matchall-string-type; 1543 type group-name-type; 1544 } 1545 description 1546 "List of administrative groups that will be 1547 assigned the associated access rights 1548 defined by the 'rule' list. 1550 The string '*' indicates that all groups apply to the 1551 entry."; 1552 } 1554 list rule { 1555 key "name"; 1556 ordered-by user; 1557 description 1558 "One access control rule. 1560 Rules are processed in user-defined order until a match is 1561 found. A rule matches if 'module-name', 'rule-type', and 1562 'access-operations' matches the request. If a rule 1563 matches, the 'action' leaf determines if access is granted 1564 or not."; 1566 leaf name { 1567 type string { 1568 length "1..256"; 1569 } 1570 description 1571 "Arbitrary name assigned to the rule."; 1572 } 1574 leaf module-name { 1575 type union { 1576 type matchall-string-type; 1577 type string; 1578 } 1579 default "*"; 1580 description 1581 "Name of the module associated with this rule. 1583 This leaf matches if it has the value '*', or if the 1584 object being accessed is defined in the module with the 1585 specified module name."; 1586 } 1587 choice rule-type { 1588 description 1589 "This choice matches if all leafs present in the rule 1590 matches the request. If no leafs are present, the 1591 choice matches all requests."; 1592 case protocol-operation { 1593 leaf rpc-name { 1594 type union { 1595 type matchall-string-type; 1596 type string; 1597 } 1598 description 1599 "This leaf matches if it has the value '*', or if its 1600 value equals the requested RPC operation name."; 1601 } 1602 } 1603 case notification { 1604 leaf notification-name { 1605 type union { 1606 type matchall-string-type; 1607 type string; 1608 } 1609 description 1610 "This leaf matches if it has the value '*', or if its 1611 value equals the requested notification name."; 1612 } 1613 } 1614 case data-node { 1615 leaf path { 1616 type node-instance-identifier; 1617 mandatory true; 1618 description 1619 "Data Node Instance Identifier associated with the data 1620 node controlled by this rule. 1622 Configuration data or state data instance 1623 identifiers start with a top-level data node. A 1624 complete instance identifier is required for this 1625 type of path value. 1627 The special value '/' refers to all possible data 1628 store contents."; 1629 } 1630 } 1631 } 1633 leaf access-operations { 1634 type union { 1635 type matchall-string-type; 1636 type access-operations-type; 1637 } 1638 default "*"; 1639 description 1640 "Access operations associated with this rule. 1642 This leaf matches if it has the value '*', or if the 1643 bit corresponding to the requested operation is set."; 1644 } 1646 leaf action { 1647 type action-type; 1648 mandatory true; 1649 description 1650 "The access control action associated with the 1651 rule. If a rule is determined to match a 1652 particular request, then this object is used 1653 to determine whether to permit or deny the 1654 request."; 1655 } 1657 leaf comment { 1658 type string; 1659 description 1660 "A textual description of the access rule."; 1661 } 1662 } 1663 } 1664 } 1665 } 1667 1669 Figure 5 1671 3.5. IANA Considerations 1673 There are two actions that are requested of IANA: This document 1674 registers one URI in "The IETF XML Registry". Following the format 1675 in [RFC3688], the following has been registered. 1677 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1678 Registrant Contact: The IESG. 1679 XML: N/A, the requested URI is an XML namespace. 1681 This document registers one module in the "YANG Module Names" 1682 registry. Following the format in [RFC6020], the following has been 1683 registered. 1685 name: ietf-netconf-acm 1686 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1687 prefix: nacm 1688 reference: RFC XXXX 1689 // RFC Ed.: Replace XXX with actual RFC number 1690 // and remove this note 1692 3.6. Security Considerations 1694 This entire document discusses access control requirements and 1695 mechanisms for restricting NETCONF protocol behavior within a given 1696 session. 1698 Configuration of the access control system is highly sensitive to 1699 system security. A server may choose not to allow any user 1700 configuration to some portions of it, such as the global security 1701 level, or the groups which allowed access to system resources. 1703 This document incorporates the optional use of a "recovery session" 1704 mechanism, which can be used to bypass access control enforcement in 1705 emergencies, such as NACM configuration errors which disable all 1706 access to the server. The configuration and identification of such a 1707 recovery session mechanism are outside the scope of this document. 1709 There is a risk that invocation of non-standard protocol operations 1710 will have undocumented side effects. An administrator needs to 1711 construct access control rules such that the configuration datastore 1712 is protected from such side effects. Also, such protocol operations 1713 SHOULD never be invoked by a session during a "recovery session". 1715 There is a risk that non-standard protocol operations, or even the 1716 standard operation, may return data which "aliases" or "copies" 1717 sensitive data from a different data object. In this case, the 1718 namespace and/or the element name will not match the values for the 1719 sensitive data, which is then fully or partially copied into a 1720 different namespace and/or element. An administrator needs to avoid 1721 using data models which use this practice. 1723 An administrator needs to restrict write access to all configurable 1724 objects within this data model. 1726 If write access is allowed for configuration of access control rules, 1727 then care needs to be taken not to disrupt the access control 1728 enforcement. 1730 An administrator needs to restrict read access to the following 1731 objects within this data model, which reveal access control 1732 configuration which could be considered sensitive. 1734 o enable-nacm 1736 o read-default 1738 o write-default 1740 o exec-default 1742 o groups 1744 o rules 1746 4. References 1748 4.1. Normative References 1750 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1751 Requirement Levels", BCP 14, RFC 2119, March 1997. 1753 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1754 January 2004. 1756 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1757 Notifications", RFC 5277, July 2008. 1759 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1760 Network Configuration Protocol (NETCONF)", RFC 6020, 1761 October 2010. 1763 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1764 October 2010. 1766 [I-D.ietf-netconf-4741bis] 1767 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1768 Bierman, "Network Configuration Protocol (NETCONF)", 1769 draft-ietf-netconf-4741bis-10 (work in progress), 1770 March 2011. 1772 [I-D.ietf-netconf-rfc4742bis] 1773 Wasserman, M. and T. Goddard, "Using the NETCONF 1774 Configuration Protocol over Secure Shell (SSH)", 1775 draft-ietf-netconf-rfc4742bis-08 (work in progress), 1776 March 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 monitor 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 "monitor" 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 1842 guest 1844 1845 mod-1 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 monitor example 1858 monitor 1860 1861 mod-2 1862 ietf-netconf-monitoring 1863 read 1864 permit 1865 1866 Allow read access to the netconf 1867 monitoring information. 1868 1869 1870 1871 mod-3 1872 * 1873 exec 1874 permit 1875 1876 Allow invocation of the 1877 supported server operations. 1878 1879 1881 1883 1884 admin example 1885 admin 1887 1888 mod-4 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 mod-1: This rule prevents the guest group from reading any 1903 monitoring information in the ietf-netconf-monitoring YANG module. 1905 mod-2: This rule allows the monitor group to read the ietf-netconf- 1906 monitoring YANG module. 1908 mod-3: This rule allows the monitor group to invoke any protocol 1909 operation supported by the server. 1911 mod-4: This rule allows the admin group complete access to all 1912 content in the server. No subsequent rule will match for the 1913 admin group, because of this module rule. 1915 A.3. RPC Rule Example 1917 RPC rules are used to control access to a specific protocol 1918 operation. 1920 1921 1922 guest 1923 monitor 1924 guest 1926 1927 rpc-1 1928 ietf-netconf 1929 kill-session 1930 exec 1931 deny 1932 1933 Do not allow the monitor or guest group 1934 to kill another session. 1935 1936 1937 1938 rpc-2 1939 ietf-netconf 1940 delete-config 1941 exec 1942 deny 1943 1944 Do not allow monitor or guest group 1945 to delete any configurations. 1946 1947 1948 1950 1951 monitor 1952 monitor 1954 1955 rpc-3 1956 ietf-netconf 1957 edit-config 1958 exec 1959 permit 1960 1961 Allow the monitor group to edit the configuration. 1962 1963 1964 1966 1967 This example shows 3 protocol operation rules: 1969 rpc-1: This rule prevents the monitor or guest groups from invoking 1970 the NETCONF protocol operation. 1972 rpc-2: This rule prevents the monitor or guest groups from invoking 1973 the NETCONF protocol operation. 1975 rpc-3: This rule allows the monitor group to invoke the NETCONF 1976 protocol operation. This rule will have no real 1977 effect unless the "exec-default" leaf is set to "deny". 1979 A.4. Data Rule Example 1981 Data rules are used to control access to specific (config and non- 1982 config) data nodes within the NETCONF content provided by the server. 1984 1985 1986 guest rules 1987 guest 1989 1990 data-1 1991 1992 /n:nacm 1993 1994 * 1995 deny 1996 1997 Deny the guest group any access to the /nacm data. 1998 1999 2000 2002 2003 monitor rules 2004 monitor 2006 2007 data-acme-config 2008 2009 /acme:acme-netconf/acme:config-parameters 2010 2011 2012 read create update delete 2013 2014 permit 2015 2016 Allow the monitor group complete access to the acme 2017 netconf configuration parameters. Showing long form 2018 of 'access-operations' instead of shorthand. 2019 2020 2021 2023 2024 dummy-itf 2025 guest monitor 2027 2028 dummy-itf 2029 2030 /acme:interfaces/acme:interface[acme:name='dummy'] 2031 2032 read update 2033 permit 2034 2035 Allow the monitor and guest groups read 2036 and update access to the dummy interface. 2037 2038 2039 2041 2042 admin rules 2043 2044 admin-itf 2045 2046 /acme:interfaces/acme:interface 2047 2048 * 2049 permit 2050 2051 Allow admin full access to all acme interfaces. 2052 2053 2054 2055 2057 This example shows 4 data rules: 2059 data-1: This rule denies the guest group any access to the 2060 subtree. Note that the default namespace is only applicable 2061 because this subtree is defined in the same namespace as the 2062 element. 2064 data-acme-config: This rule gives the monitor group read-write 2065 access to the acme . 2067 dummy-itf: This rule gives the monitor and guest groups read-update 2068 access to the acme . entry named "dummy". This entry 2069 cannot be created or deleted by these groups, just altered. 2071 admin-itf: This rule gives the admin group read-write access to all 2072 acme . entries. This is an example of an unreachable 2073 rule because the "mod-3" rule already gives the admin group full 2074 access to this data. 2076 A.5. Notification Rule Example 2078 Notification rules are used to control access to a specific 2079 notification event type. 2081 2082 2083 sys 2084 monitor 2085 guest 2087 2088 notif-1 2089 acme-system 2090 sys-config-change 2091 read 2092 deny 2093 2094 Do not allow the guest or monitor groups 2095 to receive config change events. 2096 2097 2098 2099 2101 This example shows 1 notification rule: 2103 notif-1: This rule prevents the monitor or guest groups from 2104 receiving the acme event type. 2106 Appendix B. Change Log 2108 -- RFC Ed.: remove this section before publication. 2110 B.1. 03-04 2112 Introduced rule-lists to group related rules together. 2114 Moved "module-rule", "rpc-rule", "notification-rule", and "data-rule" 2115 into one common "rule", with a choice to select between the four 2116 variants. 2118 Changed "superuser" to "recovery session", and adjusted text 2119 throughout document for this change. 2121 Clarified behavior of global default NACM parameters, enable-nacm, 2122 read-default, write-default, exec-default. 2124 Clarified when access control is applied during system 2125 initialization. 2127 B.2. 02-03 2129 Fixed improper usage of RFC 2119 keywords. 2131 Changed term usage of "database" to "datastore". 2133 Clarified that "secure" and "very-secure" extensions only apply if 2134 the /nacm/enable-nacm object is "true". 2136 B.3. 01-02 2138 Removed authentication text and objects. 2140 Changed module name from ietf-nacm to ietf-netconf-acm. 2142 Updated NETCONF and YANG terminology. 2144 Removed open issues section. 2146 Changed some must to MUST in requirements section. 2148 B.4. 00-01 2150 Updated YANG anf YANG Types references. 2152 Updated module namespace URI to standard format. 2154 Updated module header meta-data to standard format. 2156 Filled in IANA section. 2158 B.5. 00 2160 Initial version cloned from 2161 draft-bierman-netconf-access-control-02.txt. 2163 Authors' Addresses 2165 Andy Bierman 2166 Brocade 2168 Email: andy.bierman@brocade.com 2170 Martin Bjorklund 2171 Tail-f Systems 2173 Email: mbj@tail-f.com