idnits 2.17.1 draft-ietf-netconf-access-control-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2011) is 4796 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) == Outdated reference: A later version (-10) exists of draft-ietf-netconf-4741bis-09 == Outdated reference: A later version (-08) exists of draft-ietf-netconf-rfc4742bis-07 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Bierman 3 Internet-Draft Brocade 4 Intended status: Standards Track M. Bjorklund 5 Expires: September 12, 2011 Tail-f Systems 6 March 11, 2011 8 Network Configuration Protocol Access Control Model 9 draft-ietf-netconf-access-control-03 11 Abstract 13 The standardization of network configuration interfaces for use with 14 the NETCONF protocol requires a structured and secure operating 15 environment, which 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 which 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 September 12, 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 Requirements . . . . . . . . . . . . . . . . . 6 63 2.1. Protocol Control Points . . . . . . . . . . . . . . . . . 6 64 2.2. Simplicity . . . . . . . . . . . . . . . . . . . . . . . . 7 65 2.3. Procedural Interface . . . . . . . . . . . . . . . . . . . 7 66 2.4. Datastore Access . . . . . . . . . . . . . . . . . . . . . 7 67 2.4.1. Access Rights . . . . . . . . . . . . . . . . . . . . 8 68 2.4.2. and Operations . . . . . . . . . . 8 69 2.4.3. Operation . . . . . . . . . . . . . . . 8 70 2.4.4. Operation . . . . . . . . . . . . . . . 9 71 2.5. Users and Groups . . . . . . . . . . . . . . . . . . . . . 10 72 2.6. Maintenance . . . . . . . . . . . . . . . . . . . . . . . 10 73 2.7. Configuration Capabilities . . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . . . . . . . . 18 85 3.2.3. Sessions . . . . . . . . . . . . . . . . . . . . . . . 18 86 3.2.4. Access Permissions . . . . . . . . . . . . . . . . . . 18 87 3.2.5. Global Enforcement Controls . . . . . . . . . . . . . 19 88 3.2.6. Access Control Rules . . . . . . . . . . . . . . . . . 19 89 3.3. Access Control Enforcement Procedures . . . . . . . . . . 19 90 3.3.1. Initial Operation . . . . . . . . . . . . . . . . . . 19 91 3.3.2. Session Establishment . . . . . . . . . . . . . . . . 20 92 3.3.3. 'access-denied' Error Handling . . . . . . . . . . . . 20 93 3.3.4. Incoming RPC Message Validation . . . . . . . . . . . 20 94 3.3.5. Data Node Access Validation . . . . . . . . . . . . . 23 95 3.3.6. Outgoing Authorization . . . . . . . . . . 26 96 3.3.7. Outgoing Authorization . . . . . . . . 26 97 3.4. Data Model Definitions . . . . . . . . . . . . . . . . . . 29 98 3.4.1. High Level Procedures . . . . . . . . . . . . . . . . 29 99 3.4.2. Data Organization . . . . . . . . . . . . . . . . . . 29 100 3.4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . 30 101 3.5. IANA Considerations . . . . . . . . . . . . . . . . . . . 41 102 3.6. Security Considerations . . . . . . . . . . . . . . . . . 41 103 4. References . . . . . . . . . . . . . . . . . . . . . . . . . . 44 104 4.1. Normative References . . . . . . . . . . . . . . . . . . . 44 105 4.2. Informative References . . . . . . . . . . . . . . . . . . 44 106 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 45 107 A.1. Example . . . . . . . . . . . . . . . . . . . . . 45 108 A.2. Example . . . . . . . . . . . . . . . . . . 46 109 A.3. Example . . . . . . . . . . . . . . . . . . . . 47 110 A.4. Example . . . . . . . . . . . . . . . . . . . 49 111 A.5. Example . . . . . . . . . . . . . . . 51 112 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 52 113 B.1. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 52 114 B.2. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 52 115 B.3. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 52 116 B.4. 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 119 1. Introduction 121 The NETCONF protocol does not provide any standard mechanisms to 122 restrict the operations and content that each user is authorized to 123 use. 125 There is a need for inter-operable management of the controlled 126 access to operator selected portions of the available NETCONF content 127 within a particular server. 129 This document addresses access control mechanisms for the Operation 130 and Content layers of NETCONF, as defined in 131 [I-D.ietf-netconf-4741bis], and [RFC5277]. It contains three main 132 sections: 134 1. Access Control Requirements 136 2. NETCONF Access Control Model (NACM) 138 3. YANG Data Model (ietf-netconf-acm.yang) 140 1.1. Terminology 142 1.1.1. Requirements Notation 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 146 document are to be interpreted as described in [RFC2119]. 148 1.1.2. NETCONF Terms 150 The following terms are defined in [I-D.ietf-netconf-4741bis] and are 151 not redefined here: 153 o client 155 o datastore 157 o operation 159 o protocol operation 161 o server 163 o session 165 o user 167 1.1.3. YANG Terms 169 The following terms are defined in [RFC6020] and are not redefined 170 here: 172 o data node 174 1.1.4. NACM Terms 176 The following terms are used throughout this documentation: 178 access control: A security feature provided by the NETCONF server, 179 which allows an operator to restrict access to a subset of all 180 NETCONF protocol operations and data, based on various criteria. 182 access control model (ACM): A conceptual model used to configure and 183 monitor the access control procedures desired by the operator to 184 enforce a particular access control policy. 186 access control rule: The conceptual criteria used to determine if a 187 particular NETCONF protocol operation will be permitted or denied. 189 authentication: The process of verifying a user's identity. 191 superuser: The special administrative user account which is given 192 unlimited NETCONF access, and is exempt from all access control 193 enforcement. 195 2. Access Control Requirements 197 2.1. Protocol Control Points 199 The NETCONF protocol allows new operations to be added at any time, 200 and the YANG data modeling language supports this feature. It is not 201 possible to design an ACM for NETCONF which only focuses on a static 202 set of operations, like some other protocols. Since few assumptions 203 can be made about an arbitrary protocol operation, the NETCONF 204 architectural server components need to be protected at several 205 conceptual control points. 207 +-------------+ +-------------+ 208 client | protocol | | prune | client 209 request --> | operation | | restricted | ---> reply 210 | allowed? | | | 211 +-------------+ | nodes? | 212 | +-------------+ 213 | if any datastore or 214 | state data is accessed 215 | by the operation 216 V 217 +-------------+ +----------------+ 218 | data node | | prune | 219 | access | | restricted | 220 | allowed? | | | ---> client 221 +-------------+ | event or data? | session 222 +----------------+ 224 Figure 1 226 The following access control points are defined: 228 protocol operation: Configurable permission to invoke specific 229 protocol operations is required. Wildcard or multiple target 230 mechanisms to reduce configuration and effort are also required. 232 NETCONF datastore: Configurable permission to read and/or alter 233 specific data nodes within any conceptual datastore is required. 234 Wildcard or multiple target mechanisms to reduce configuration and 235 effort are also required. 237 RPC Reply Content: Configurable permission to read specific data 238 nodes within any conceptual RPC output section is required. 239 Unauthorized data is silently omitted from the reply, instead of 240 dropping the reply or sending an 'access-denied' error. 242 Notification Content: Configurable permission to receive specific 243 notification event types is required. 245 2.2. Simplicity 247 Experience has shown that a complicated ACM will not be widely 248 deployed, because it is too hard to use. The key factor that is 249 ignored in such solutions is the concept of 'localized cost'. It 250 needs to be easy to do simple things, and hard to do complex things, 251 instead of hard to do everything. 253 Configuration of the access control system needs to be simple to use. 254 Simple and common tasks need to be easy to configure, and require 255 little expertise or domain-specific knowledge. Complex tasks are 256 possible using additional mechanisms, which may require additional 257 expertise. 259 A single set of access control rules SHOULD be able to control all 260 types of NETCONF protocol operation invocation, all conceptual 261 datastore access, and all NETCONF session output. 263 Default access control policy needs to be as secure as possible. 265 Protocol access SHOULD be defined with a small and familiar set of 266 permissions, while still allowing full control of NETCONF datastore 267 access. 269 Access control does not need to be applied to NETCONF 270 messages. 272 2.3. Procedural Interface 274 The NETCONF protocol uses a procedural interface model, and an 275 extensible set of protocol operations. Access control for any 276 possible protocol operation is required. 278 It MUST be possible to configure the ACM to permit or deny access to 279 specific NETCONF operations. 281 YANG modules SHOULD be designed so that different access levels for 282 input parameters to protocol operations is not required. 284 2.4. Datastore Access 286 It MUST be possible to control access to specific nodes and sub-trees 287 within the conceptual NETCONF datastore. 289 In order for a user to obtain access to a particular datastore node, 290 the user MUST be authorized to have the same requested access to the 291 specified node, and all of its ancestors. 293 The same access control rules apply to all conceptual datastores. 294 For example, the candidate configuration or the running 295 configuration. 297 Only the standard NETCONF datastores (candidate, running, and 298 startup) are controlled by the ACM. Local or remote files or 299 datastores accessed via the parameter are optional to support. 301 The non-volatile startup configuration needs to be loaded into the 302 running configuration without applying any access control rules. 304 2.4.1. Access Rights 306 A small set of hard-wired datastore access rights is needed to 307 control access to all possible NETCONF datastore operations, 308 including vendor extensions to the standard operation set. 310 The familiar 'CRUDX' model can support all NETCONF operations: 312 o Create: Allows the client to add a new data node instance to a 313 datastore. 315 o Read: Allows the client to read a data node instance from a 316 datastore, or receive the notification event type. 318 o Update: Allows the client to update an existing data node instance 319 in a datastore. 321 o Delete: Allows the client to delete a data node instance from a 322 datastore. 324 o eXec: Allows the client to execute the protocol operation. 326 2.4.2. and Operations 328 Data nodes to which the client does not have 'read' access, either 329 directly or via wildcard access, are silently omitted from the message. 332 2.4.3. Operation 334 The NACM access rights are not directly coupled to the 335 "operation" attribute, although they are similar. Instead, a NACM 336 access right applies to all operations which would result in a 337 particular access operation to the target datastore. This section 338 describes how these access rights apply to the specific datastore 339 operations supported by the operation. 341 If the effective operation is 'none' (i.e., default-operation='none') 342 for a particular data node, then no access control is applied to that 343 data node. 345 A 'create', 'merge', or 'replace' operation on a datastore node which 346 would result in the creation of a new data node instance, for which 347 the user does not have 'create' access permission, is rejected with 348 an 'access-denied' error. 350 A 'merge' or 'replace' operation on a datastore node which would 351 result in the modification of an existing data node instance, for 352 which the user does not have 'update' access permission, is rejected 353 with an 'access-denied' error. 355 A 'replace', 'delete', or 'remove' operation on a datastore node 356 which would result in the deletion of an existing data node instance, 357 for which the user does not have 'delete' access permission, is 358 rejected with an 'access-denied' error. 360 A 'merge' operation may include data nodes which do not alter 361 portions of the existing datastore. For example, a container or list 362 nodes may be present for naming purposes, which do not actually alter 363 the corresponding datastore node. These unaltered data nodes within 364 the scope of a 'merge' operation are ignored by the server, and do 365 not require any access rights by the client. 367 A 'merge' operation may include data nodes, but not include 368 particular child data nodes that are present in the datastore. These 369 missing data nodes within the scope of a 'merge' operation are 370 ignored by the server, and do not require any access rights by the 371 client. 373 The contents of specific restricted datastore nodes MUST NOT be 374 exposed in any elements within the reply. 376 2.4.4. Operation 378 Access control for the operation requires special 379 consideration because the operator is replacing the entire target 380 datastore. Read access to the entire source datastore, and write 381 access to the entire target datastore is needed for this operation to 382 succeed. 384 A client MUST have access to every datastore node, even ones that are 385 not present in the source configuration data. 387 For example, consider a common use-case such as a simple backup and 388 restore procedure. The operator (client) MUST have full read access 389 to the datastore in order to receive a complete copy of its contents. 390 If not, the server will simply omit these sub-trees from the reply. 391 If that copy is later used to restore the server datastore, the 392 server will interpret the missing nodes as a request to delete those 393 nodes, and return an error. 395 2.5. Users and Groups 397 The server MUST obtain a user name from the underlying NETCONF 398 transport, such as an SSH user name. 400 It MUST be possible to specify access control rules for a single user 401 or a configurable group of users. 403 A configurable superuser account may be needed which bypasses all 404 access control rules. This could be needed in case the access 405 control rules are mis-configured, and all access is denied by 406 mistake. 408 The ACM MUST support the concept of administrative groups, to support 409 the well-established distinction between a root account and other 410 types of less-privileged conceptual user accounts. These groups MUST 411 be configurable by the operator. 413 It MUST be possible to delegate the user-to-group mapping to a 414 central server, such as RADIUS [RFC2865] [RFC5607]. Since 415 authentication is performed by the NETCONF transport layer, and 416 RADIUS performs authentication and service authorization at the same 417 time, it MUST be possible for the underlying NETCONF transport to 418 report a set of group names associated with the user to the server. 420 2.6. Maintenance 422 It SHOULD be possible to disable part or all of the access control 423 model without deleting any configuration. By default, only the 424 'superuser' SHOULD be able to perform this task. 426 It SHOULD be possible to configure a 'superuser' account so that all 427 access control is disabled for just this user. This allows the 428 access control rules to always be modified without completely 429 disabling access control for all users. 431 2.7. Configuration Capabilities 433 Suitable control and monitoring mechanisms are needed to allow an 434 operator to easily manage all aspects of the ACM behavior. A 435 standard data model, suitable for use with the 436 operation MUST be available for this purpose. 438 Access control rules to restrict operations on specific sub-trees 439 within the configuration datastore MUST be supported. Existing 440 mechanisms can be used to identify the sub-tree(s) for this purpose. 442 2.8. Identifying Security Holes 444 One of the most important aspects of the data model documentation, 445 and biggest concerns during deployment, is the identification of 446 security-sensitive content. This applies to operations in NETCONF, 447 not just data and notifications. 449 It is mandatory for security-sensitive objects to be documented in 450 the Security Considerations section of an RFC. This is nice, but it 451 is not good enough, for the following reasons: 453 o This documentation-only approach forces operators to study the RFC 454 and determine if there are any potential security holes introduced 455 by a new YANG module. 457 o If any security holes are identified, then the operator can study 458 some more RFC text, and determine how to close the security 459 hole(s). 461 o The ACM on each server can be configured to close the security 462 holes, e.g., require privileged access to read or write the 463 specific data identified in the Security Considerations section. 465 o If the ACM is not pre-configured, then there will be a time window 466 of vulnerability, after the new module is loaded, and before the 467 new access control rules for that module are configured, enabled, 468 and debugged. 470 Often, the operator just wants to disable default access to the 471 secure content, so no inadvertent or malicious changes can be made to 472 the server. This allows the default rules to be more lenient, 473 without significantly increasing the security risk. 475 A data model designer needs to be able to use machine-readable 476 statements to identify NETCONF content which needs to be protected by 477 default. This will allow client and server tools to automatically 478 close data-model specific security holes, by denying access to 479 sensitive data unless the user is explicitly authorized to perform 480 the requested operation. 482 2.9. Data Shadowing 484 One of the more complicated security administration problems is 485 identifying data nodes which shadow or mirror the content of another 486 data node. An access control rule to prevent read operations for a 487 particular node may be insufficient to prevent access to the data 488 node with the copied value. 490 If the YANG leafref data type is used, then this data shadowing can 491 be detected by applications (and the server stack), and prevented. 493 If the description statement, other documentation, or no 494 documentation exists to identify a data shadow problem, then it may 495 not be detected. 497 Since NETCONF allows any vendor operation to be added to the 498 protocol, there is no way to reliably identify all of the operations 499 that may expose copies of sensitive data nodes in 500 messages. 502 A NETCONF server MUST ensure that unauthorized access to its 503 conceptual datastores and non-configuration data nodes is prevented. 505 It is beyond the scope of this document to define access control 506 enforcement procedures for underlying device instrumentation that may 507 exist to support the NETCONF server operation. An operator can 508 identify each operation that the server provides, and decide if it 509 needs any access control applied to it. 511 Proprietary protocol operations SHOULD be properly documented by the 512 vendor, so it is clear to operators what data nodes (if any) are 513 affected by the operation, and what information (if any) is returned 514 in the message. 516 2.10. NETCONF Specific Requirements 518 The server MUST be able to identify the specific protocol access 519 request at the 4 access control points defined above. 521 The server MUST be able to identify any datastore access request, 522 even for proprietary operations. 524 A client MUST always be authorized to invoke the 525 operation, defined in [I-D.ietf-netconf-4741bis]. 527 A client MUST always be authorized to receive the 528 and notification events, defined in [RFC5277] 529 The set of module name strings used within one particular server MUST 530 be unique. 532 3. NETCONF Access Control Model (NACM) 534 3.1. Introduction 536 This section provides a high-level overview of the access control 537 model structure. It describes the NETCONF protocol message 538 processing model, and the conceptual access control requirements 539 within that model. 541 3.1.1. Features 543 The NACM data model provides the following features: 545 o Independent control of RPC, data, and notification access. 547 o Very simple access control rules configuration data model which is 548 easy to use. 550 o The concept of a 'superuser' type of account is supported, but 551 configuration such an account is beyond the scope of this 552 document. If the server supports a 'superuser' account, then it 553 MUST be able to determine the actual user name for this account. 554 A session associated with the superuser account will bypass all 555 access control enforcement. 557 o A simple and familiar set of datastore permissions is used. 559 o Support for YANG security tagging (e.g., nacm:secure extension) 560 allows default security modes to automatically exclude sensitive 561 data. 563 o Separate default access modes for read, write, and execute 564 permissions. 566 o Access control rules are applied to configurable groups of users. 568 o The entire ACM can be disabled during operation, in order to debug 569 operational problems. 571 o Access control rules are simple to configure. 573 o The number of denied protocol operation requests and denied 574 datastore write requests can be monitored by the client. 576 o Simple unconstrained YANG instance identifiers are used to 577 configure access control rules for specific data nodes. 579 3.1.2. External Dependencies 581 The NETCONF [I-D.ietf-netconf-4741bis] protocol is used for all 582 management purposes within this document. It is expected that the 583 mandatory transport mapping NETCONF Over SSH 584 [I-D.ietf-netconf-rfc4742bis] is also supported by the server, and 585 that the server has access to the user name associated with each 586 session. 588 The YANG Data Modeling Language [RFC6020] is used to define the 589 NETCONF data models specified in this document. The YANG instance- 590 identifier data type is used to configure data-node-specific access 591 control rules. 593 3.1.3. Message Processing Model 595 The following diagram shows the NETCONF message flow model, including 596 the points at which access control is applied, during NETCONF message 597 processing. 599 +-------------------------+ 600 | session | 601 | (username) | 602 +-------------------------+ 603 | ^ 604 V | 605 +--------------+ +---------------+ 606 | message | | message | 607 | dispatcher | | generator | 608 +--------------+ +---------------+ 609 | ^ ^ 610 V | | 611 +===========+ +-------------+ +----------------+ 612 | |---> | | | | 613 | acc. ctl | | generator | | generator | 614 +===========+ +-------------+ +----------------+ 615 | ^ ^ ^ 616 V +------+ | | 617 +-----------+ | +=============+ +================+ 618 | | | | | | | 619 | processor |-+ | acc. ctl | | access ctl | 620 +-----------+ +=============+ +================+ 621 | | ^ ^ 622 V +----------------+ | | 623 +===========+ | | | 624 | data node | | | | 625 | acc. ctl | -----------+ | | | 626 +===========+ | | | | 627 | | | | | 628 V V V | | 629 +---------------+ +-----------------+ 630 | configuration | ---> | server | 631 | datastore | | instrumentation | 632 | | <--- | | 633 +---------------+ +-----------------+ 635 Figure 2 637 The following high-level sequence of conceptual processing steps is 638 executed for each received message, if access control 639 enforcement is enabled: 641 o Access control is applied to all messages (except ) received by the server, individually, for each active 643 session, unless the session is associated with the 'superuser' 644 account. 646 o If the session is authorized to execute the specified RPC 647 operation, then processing continues, otherwise the request is 648 rejected with an 'access-denied' error. 650 o If the configuration datastore or conceptual state data is 651 accessed by the protocol operation, then the data node access MUST 652 be authorized. If the session is authorized to perform the 653 requested operation on the requested data, then processing 654 continues. 656 The following sequence of conceptual processing steps is executed for 657 each generated notification event, if access control enforcement is 658 enabled: 660 o Server instrumentation generates a conceptual notification, for a 661 particular subscription. 663 o The notification access control enforcer checks the notification 664 event type, and if it is one which the session is not authorized 665 to read, then the notification is dropped for that subscription. 667 3.2. Model Components 669 This section defines the conceptual components related to access 670 control model. 672 3.2.1. Users 674 A 'user' is the conceptual entity, which is associated with the 675 access permissions granted to a particular session. A user is 676 identified by a string which MUST be unique within the server. 678 As described in [I-D.ietf-netconf-4741bis], the user name string is 679 derived from the transport layer during session establishment. If 680 the transport layer cannot authenticate the user, the session is 681 terminated. 683 The server MAY support a 'superuser' administrative user account, 684 which will bypass all access control enforcement. This is useful for 685 restricting initial access and repairing a broken access control 686 configuration. This account may be configurable to use a specific 687 user, or disabled completely. Some systems have factory-selected 688 superuser account names. There is no need to standardize the exact 689 user name for the superuser account. If no such account exists, then 690 all NETCONF access will be controlled by NACM. 692 3.2.2. Groups 694 Access to a specific NETCONF operation is granted to a session, 695 associated with a group, not a user. 697 A group is identified by its name. All group names MUST be unique 698 within the server. 700 A group member is identified by a user name string. 702 The same user may be configured in multiple groups. 704 3.2.3. Sessions 706 A session is simply a NETCONF session, which is the entity which is 707 granted access to specific NETCONF operations. 709 A session is associated with a single user name for the lifetime of 710 the session. 712 3.2.4. Access Permissions 714 The access permissions are the NETCONF protocol specific set of 715 permissions that have been assigned to a particular session. 717 The same access permissions MUST stay in effect for the processing of 718 a particular message. 720 The server MUST use the access control rules in effect at the time 721 the message is processed. 723 The access control model treats protocol operation execution 724 separately from configuration datastore access and outgoing messages: 726 create: Permission to create conceptual server data. 728 read: Read access to conceptual server data, and 729 content. 731 update: Permission to modify existing conceptual server data. 733 delete: Permission to delete existing conceptual server data. 735 exec: Permission to invoke an protocol operation. 737 3.2.5. Global Enforcement Controls 739 A global on/off switch is provided to enable or disable all access 740 control enforcement. 742 An on/off switch is provided to enable or disable default access to 743 invoke protocol operations. 745 An on/off switch is provided to enable or disable default permission 746 to receive data in replies and notifications. 748 An on/off switch is provided to enable or disable default access to 749 alter configuration data. 751 3.2.6. Access Control Rules 753 There are 4 types of rules available in NACM: 755 module rule: Controls access for definitions in a specific module, 756 identified by its name. 758 protocol operation rule: Controls access for a specific protocol 759 operation, identified by its module and name. 761 data node rule: Controls access for a specific data node, identified 762 by its path location within the conceptual XML document for the 763 data node. 765 notification rule: Controls access for a specific notification event 766 type, identified by its module and name. 768 3.3. Access Control Enforcement Procedures 770 There are seven separate phases that need to be addressed, four of 771 which are related to the NETCONF message processing model. In 772 addition, the initial start-up mode for a NETCONF server, session 773 establishment, and 'access-denied' error handling procedures also 774 need to be considered. 776 3.3.1. Initial Operation 778 Upon the very first start-up of the NETCONF server, the access 779 control configuration will probably not be present. If not, a server 780 MUST NOT allow any write access to any session role except 781 'superuser' type of account in this state. 783 There is no requirement to enforce access control rules before or 784 while the non-volatile configuration data is processed and loaded 785 into the running configuration. 787 3.3.2. Session Establishment 789 The access control model applies specifically to the well-formed XML 790 content transferred between a client and a server, after session 791 establishment has been completed, and after the exchange has 792 been successfully completed. 794 A server SHOULD NOT include any sensitive information in any 795 elements within the exchange. 797 Once session establishment is completed, and a user identity has been 798 authenticated, the NETCONF transport layer reports the username and a 799 possibly empty set of group names associated with the user to the 800 NETCONF server. The NETCONF server will enforce the access control 801 rules, based on the supplied user identity, group names, and the 802 configuration data stored on the server. 804 3.3.3. 'access-denied' Error Handling 806 The 'access-denied' error-tag is generated when the access control 807 system denies access to either a request to invoke a protocol 808 operation or a request to perform a particular operation on the 809 configuration datastore. 811 A server MUST NOT include any sensitive information in any elements within the response. 814 3.3.4. Incoming RPC Message Validation 816 The diagram below shows the basic conceptual structure of the access 817 control processing model for incoming NETCONF messages, within 818 a server. 820 NETCONF server 821 +------------+ 822 | XML | 823 | message | 824 | dispatcher | 825 +------------+ 826 | 827 | 828 V 829 +------------+ 830 | NC-base NS | 831 | | 832 +------------+ 833 | | | 834 | | +-------------------------+ 835 | +------------+ | 836 V V V 837 +-----------+ +---------------+ +------------+ 838 | acme NS | | NC-base NS | | NC-base NS | 839 | | | | | | 840 +-----------+ +---------------+ +------------+ 841 | | 842 | | 843 V V 844 +----------------------+ 845 | | 846 | configuration | 847 | datastore | 848 +----------------------+ 850 Figure 3 852 Access control begins with the message dispatcher. Only well-formed 853 XML messages will be processed by the server. 855 After the server validates the element, and determines the 856 namespace URI and the element name of the protocol operation being 857 requested, the RPC access control enforcer verifies that the session 858 is authorized to invoke the protocol operation. 860 The protocol operation is authorized by following these steps: 862 1. If the parameter is set to 'false', then the 863 protocol operation is permitted. 865 2. If the session is associated with the 'superuser' account, then 866 the protocol operation is permitted. 868 3. If the requested operation is the NETCONF 869 operation, then the protocol operation is permitted. 871 4. Check all the entries for ones that contain a entry that matches the user name for the session making 873 the request. Add to these groups the set of groups provided by 874 the transport layer. 876 5. If no groups are found: 878 * If the requested protocol operation is associated with a YANG 879 module advertised in the server capabilities, and the rpc 880 statement contains a nacm:secure or nacm:very-secure 881 extension, then the protocol operation is denied. 883 * If the parameter is set to 'permit', then 884 permit the protocol operation, otherwise deny the request. 886 6. Check if there are any matching entries for the 887 requested protocol operation. Any matching rules are processed 888 in user-defined order, in case there are multiple 889 entries for the requested protocol operation. 891 7. If an entry is found, then check the 892 bits field for the entry, otherwise continue. The 'exec' bit 893 MUST be present in the bits field for an , so it is not used in this procedure. 896 8. If the entry is considered a match, then the 'nacm- 897 action' leaf is checked. If is equal to 'permit', then the 898 protocol operation is permitted, otherwise it is denied. 900 9. Check if there are any matching entries for the 901 same module as the requested protocol operation. Any matching 902 rules are processed in user-defined order, in case there are 903 multiple entries for the module containing the 904 requested protocol operation. 906 10. If a entry is found, then check the bits field for the entry, otherwise continue. If the 908 'exec' bit is present in the bits field then 909 the RPC rule is considered a match. otherwise it is not 910 considered to match the request. 912 11. If the entry is considered a match, then the 913 'nacm-action' leaf is checked. If is equal to 'permit', then 914 the protocol operation is permitted, otherwise it is denied. 916 12. If the requested operation is identified an a nacm:secure or 917 nacm:very-secure protocol operation, then the protocol operation 918 is denied. 920 13. If the parameter is set to 'permit', then permit 921 the protocol operation, otherwise the protocol operation is 922 denied. 924 If the session is not authorized to invoke the protocol operation 925 then an is generated with the following information: 927 error-tag: access-denied 929 error-path: /rpc/method-QName, where 'method-QName' is a qualified 930 name identifying the actual protocol operation name. For example, 931 '/rpc/edit-config' represents the operation in the 932 NETCONF base namespace. 934 If the configuration datastore is accessed, either directly or as a 935 side effect of the protocol operation, then the server MUST intercept 936 the operation and make sure the session is authorized to perform the 937 requested operation on the specified data. 939 3.3.5. Data Node Access Validation 941 If a data node within a configuration datastore is accessed, or a 942 conceptual non-configuration node is accessed, then the server MUST 943 ensure that the client session is authorized to perform the requested 944 operation create, read, update, or delete operation on the specified 945 data node. 947 The data node access request is authorized by following these steps: 949 1. If the parameter is set to 'false', then the data 950 node access request is permitted. 952 2. If the session is associated with the 'superuser' account, then 953 the data node access request is permitted. 955 3. Check all the entries for ones that contain a entry that matches the user name for the session making 957 the request. Add to these groups the set of groups provided by 958 the transport layer. 960 4. If no groups are found: 962 * If the requested data node is associated with a YANG module 963 advertised in the server capabilities, and the data 964 definition statement or any of its ancestors contains a nacm: 965 secure or nacm:very-secure extension, then the data node 966 access request is denied. 968 * For a read request, if the parameter is set to 969 'permit', then permit the data node access request, otherwise 970 deny the request. For a read operation, this means that the 971 requested node is not included in the rpc-reply. 973 * For a write request, if the parameter is set 974 to 'permit', then permit the data node access request, 975 otherwise deny the request. 977 5. Check if there are any matching entries for the 978 requested data node access request. Any matching rules are 979 processed in user-defined order, in case there are multiple 980 entries for the requested data node. 982 6. If an entry is found, then check the bits field for the entry, otherwise continue. 985 1. For a creation operation, if the 'create' bit is present in 986 the bits field then the entry is considered 987 to be a match. 989 2. For a read operation, if the 'read' bit is present in the 990 bits field, then the entry is considered to 991 be a match. 993 3. For an update (e.g., 'merge' or 'replace') operation, if the 994 'update' bit is present in the bits field 995 then the entry is considered to be a match. 997 4. For a deletion (e.g., 'delete') operation, if the 'delete' 998 bit is present in the bits field then the 999 entry is considered to be a match. 1001 7. If the entry is considered a match, then the 'nacm- 1002 action' leaf is checked. If it is equal to 'permit', then the 1003 data operation is permitted, otherwise it is denied. For 'read' 1004 operations, 'denied' means the requested data is not returned in 1005 the reply. 1007 8. Check if there are any matching entries for the 1008 same module as the requested data node. Any matching rules are 1009 processed in user-defined order, in case there are multiple 1010 entries for the module containing the requested 1011 data node. 1013 9. If a entry is found, then check the bits field for the entry, otherwise continue. 1016 1. For a creation operation, if the 'create' bit is present in 1017 the bits field then the entry is considered 1018 to be a match. 1020 2. For a read operation, if the 'read' bit is present in the 1021 bits field, then the entry is considered to 1022 be a match. 1024 3. For an update (e.g., 'merge' or 'replace') operation, if the 1025 'update' bit is present in the bits field 1026 then the entry is considered to be a match. 1028 4. For a deletion (e.g., 'delete') operation, if the 'delete' 1029 bit is present in the bits field then the 1030 entry is considered to be a match. 1032 10. If the entry is considered a match, then the 1033 'nacm-action' leaf is checked. If it is equal to 'permit', then 1034 the data operation is permitted, otherwise it is denied. For 1035 'read' operations, 'denied' means the requested data is not 1036 returned in the reply. 1038 11. For a read request, if the requested data node is identified an 1039 a nacm:very-secure definition, then the requested data node is 1040 not included in the reply. 1042 12. For a write request, if the requested data node is identified an 1043 a nacm:secure or nacm:very-secure definition, then the data node 1044 access request is denied. 1046 13. For a read request, if the parameter is set to 1047 'permit', then include the requested data in the reply, 1048 otherwise do not include the requested data in the reply. 1050 14. For a write request, if the parameter is set to 1051 'permit', then permit the data node access request, otherwise 1052 deny the request. 1054 3.3.6. Outgoing Authorization 1056 The message MUST be checked by the server to make sure no 1057 unauthorized data is contained within it. If so, the restricted data 1058 MUST be removed from the message before it is sent to the client. 1060 For protocol operations which do not access any data nodes, then any 1061 client authorized to invoke the protocol operation is also authorized 1062 to receive the for that protocol operation. 1064 3.3.7. Outgoing Authorization 1066 The message MUST be checked by the server to make sure 1067 no unauthorized data is contained within it. If so, the restricted 1068 data MUST be removed from the message before it is sent to the 1069 client. 1071 Configuration of access control rules specifically for descendent 1072 nodes of the notification event type element are outside the scope of 1073 this document. If the session is authorized to receive the 1074 notification event type, then it is also authorized to receive any 1075 data it contains. 1077 The following figure shows the conceptual message processing model 1078 for outgoing messages. 1080 NETCONF server 1081 +------------+ 1082 | XML | 1083 | message | 1084 | generator | 1085 +------------+ 1086 ^ 1087 | 1088 +----------------+ 1089 | | 1090 | generator | 1091 +----------------+ 1092 ^ 1093 | 1094 +=================+ 1095 | | 1096 | access control | 1097 | | 1098 +=================+ 1099 ^ 1100 | 1101 +------------------------+ 1102 | server instrumentation | 1103 +------------------------+ 1104 | ^ 1105 V | 1106 +----------------------+ 1107 | configuration | 1108 | datastore | 1109 +----------------------+ 1111 Figure 4 1113 The generation of a notification event for a specific subscription is 1114 authorized by following these steps: 1116 1. If the parameter is set to 'false', then the 1117 notification event is permitted. 1119 2. If the session is associated with the 'superuser' account, then 1120 the notification event is permitted. 1122 3. If the requested operation is the NETCONF or 1123 event type, then the notification event 1124 is permitted. 1126 4. Check all the entries for ones that contain a entry that matches the user name for the session that 1128 started the notification subscription. Add to these groups the 1129 set of groups provided by the transport layer. 1131 5. If no groups are found: 1133 * If the requested notification is associated with a YANG 1134 module advertised in the server capabilities, and the 1135 notification statement contains a nacm:secure or nacm:very- 1136 secure extension, then the notification event is dropped for 1137 the associated subscription. 1139 * If the parameter is set to 'permit', then 1140 permit the notification event, otherwise drop this event type 1141 for the associated subscription. 1143 6. Check if there are any matching entries for 1144 the specific notification event type being delivered to the 1145 subscription. Any matching rules are processed in user-defined 1146 order, in case there are multiple entries 1147 for the requested notification event type. 1149 7. If a entry is found, then check the 1150 bits field for the entry, otherwise continue. 1151 If the 'read' bit is present in the bits field 1152 then the notification event type is permitted, otherwise it is 1153 dropped for the associated subscription. 1155 8. Check if there are any matching entries for the 1156 same module as the notification event type. Any matching rules 1157 are processed in user-defined order, in case there are multiple 1158 entries for the module containing the notification 1159 event type. 1161 9. If a entry is found, then check the bits field for the entry, otherwise continue. If the 1163 'read' bit is present in the bits field then 1164 the notification event type is permitted, otherwise it is 1165 dropped for the associated subscription. 1167 10. If the requested event type is identified an a nacm:very-secure 1168 notification definition, then the notification event type is 1169 denied. 1171 11. If the parameter is set to 'permit', then permit 1172 the notification event type, otherwise it is dropped for the 1173 associated subscription. 1175 3.4. Data Model Definitions 1177 This section defines the semantics of the conceptual data structures 1178 found in the data model in Section 3.4. 1180 3.4.1. High Level Procedures 1182 There are some high level management procedures that an administrator 1183 needs to consider before using this access control model: 1185 1. Configure the global settings. 1187 2. Configure one or more user groups. 1189 3. Configure zero or more access control rules for specific modules. 1191 4. Configure zero or more access control rules for specific protocol 1192 operations. 1194 5. Configure zero or more access control rules for data node access. 1196 6. Configure zero or more access control rules for notification 1197 event type access. 1199 3.4.2. Data Organization 1201 The top-level element is called , and it is defined in the 1202 'ietf-netconf-acm' module namespace. 1204 There are several data structures defined as child nodes of the 1205 element: 1207 leaf : On/off boolean switch to enable or disable 1208 access control enforcement. 1210 leaf : Enumeration to permit or deny default read 1211 access requests. 1213 leaf : Enumeration to permit or deny default write 1214 access requests. 1216 leaf : Enumeration to permit or deny default protocol 1217 operation execution requests. 1219 leaf : Read-only counter of the number of times the 1220 server has denied an RPC operation request, since the last reboot 1221 of the server. 1223 leaf : Read-only counter of the number of times 1224 the server has denied a data node write request, since the last 1225 reboot of the server. 1227 container : Configures the groups used within the access 1228 control system. 1230 list : A list of user names belonging to the same 1231 administrative group. 1233 container : Configures the access control rules used within 1234 the server. 1236 list : Configures the access control rules for a 1237 specific module. 1239 list : Configures the access control rules for protocol 1240 operation invocation. 1242 list : Configures the access control rules for 1243 configuration datastore access. 1245 list : Configures the access control rules for 1246 controlling delivery of events. 1248 3.4.3. YANG Module 1250 The following YANG module is provided to specify the normative 1251 NETCONF content that MUST by supported by the server. 1253 The ietf-netconf-acm YANG module imports typedefs from [RFC6021]. 1255 // RFC Ed.: please update the date to the date of publication 1256 file="ietf-netconf-acm@2011-03-11.yang" 1258 module ietf-netconf-acm { 1260 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-acm"; 1262 prefix "nacm"; 1264 import ietf-yang-types { 1265 prefix yang; 1266 } 1268 organization 1269 "IETF NETCONF (Network Configuration) Working Group"; 1271 contact 1272 "WG Web: 1273 WG List: 1275 WG Chair: Mehmet Ersue 1276 1278 WG Chair: Bert Wijnen 1279 1281 Editor: Andy Bierman 1282 1284 Editor: Martin Bjorklund 1285 "; 1287 description 1288 "NETCONF Server Access Control Model. 1290 Copyright (c) 2011 IETF Trust and the persons identified as 1291 authors of the code. All rights reserved. 1293 Redistribution and use in source and binary forms, with or 1294 without modification, is permitted pursuant to, and subject 1295 to the license terms contained in, the Simplified BSD 1296 License set forth in Section 4.c of the IETF Trust's 1297 Legal Provisions Relating to IETF Documents 1298 (http://trustee.ietf.org/license-info). 1300 This version of this YANG module is part of RFC XXXX; see 1301 the RFC itself for full legal notices."; 1302 // RFC Ed.: replace XXXX with actual RFC number and 1303 // remove this note 1305 // RFC Ed.: remove this note 1306 // Note: extracted from draft-ietf-netconf-access-control-03.txt 1308 // RFC Ed.: please update the date to the date of publication 1309 revision "2011-03-11" { 1310 description 1311 "Initial version"; 1312 reference 1313 "RFC XXXX: Network Configuration Protocol 1314 Access Control Model"; 1315 } 1317 /* 1318 * Extension statements 1319 */ 1321 extension secure { 1322 description 1323 "Used to indicate that the data model node 1324 represents a sensitive security system parameter. 1326 If present, and the NACM module is enabled 1327 (i.e., /nacm/enable-nacm object equals 'true'), 1328 the NETCONF server will only allow 1329 the designated 'superuser' to have write or execute 1330 default nacm-rights-type for the node. An explicit access 1331 control rule is required for all other users. 1333 The 'secure' extension MAY appear within a data, rpc, 1334 or notification node definition. It is ignored 1335 otherwise."; 1336 } 1338 extension very-secure { 1339 description 1340 "Used to indicate that the data model node 1341 controls a very sensitive security system parameter. 1343 If present, and the NACM module is enabled 1344 (i.e., /nacm/enable-nacm object equals 'true'), 1345 the NETCONF server will only allow 1346 the designated 'superuser' to have read, write, or execute 1347 default nacm-rights-type for the node. An explicit access 1348 control rule is required for all other users. 1350 The 'very-secure' extension MAY appear within a data, rpc, 1351 or notification node definition. It is ignored 1352 otherwise."; 1353 } 1355 /* 1356 * Derived types 1357 */ 1359 typedef nacm-user-name-type { 1360 type string { 1361 length "1..max"; 1362 } 1363 description 1364 "General Purpose User Name string."; 1365 } 1366 typedef nacm-matchall-string-type { 1367 type string { 1368 pattern "\*"; 1369 } 1370 description 1371 "The string containing a single asterisk '*' is used 1372 to conceptually represent all possible values 1373 for the particular leaf using this data type."; 1374 } 1376 typedef nacm-rights-type { 1377 type union { 1378 type nacm-matchall-string-type; 1380 type bits { 1381 bit create { 1382 description 1383 "Create access allowed to all specified data. 1384 Any protocol operation that creates a 1385 new instance of the specified data is a create 1386 operation."; 1387 } 1388 bit read { 1389 description 1390 "Read access allowed to all specified data. 1391 Any protocol operation or notification that 1392 returns data to an application is a read 1393 operation."; 1394 } 1395 bit update { 1396 description 1397 "Update access allowed to all specified data. 1398 Any protocol operation that alters an existing 1399 data node is an update operation."; 1400 } 1401 bit delete { 1402 description 1403 "Delete access allowed to all specified data. 1404 Any protocol operation that removes a datastore 1405 node instance is a delete operation."; 1406 } 1407 bit exec { 1408 description 1409 "Execution access to the specified RPC operation. 1410 Any RPC operation invocation is an exec operation."; 1411 } 1412 } 1413 } 1414 description 1415 "NETCONF Access Rights. 1416 The string '*' indicates that all possible access 1417 rights apply to the access rule. Otherwise, only 1418 the specific access rights represented by the bit names 1419 that are present apply to the access rule."; 1420 } 1422 typedef nacm-group-name-type { 1423 type string { 1424 length "1..max"; 1425 pattern "[^\*].*"; 1426 } 1427 description 1428 "Name of administrative group that can be 1429 assigned to the user, and specified in 1430 an access control rule."; 1431 } 1433 typedef nacm-action-type { 1434 type enumeration { 1435 enum permit { 1436 description 1437 "Requested action is permitted."; 1438 } 1439 enum deny { 1440 description 1441 "Requested action is denied."; 1442 } 1443 } 1444 description 1445 "Action taken by the server when a particular 1446 rule matches."; 1447 } 1449 typedef schema-instance-identifier { 1450 type yang:xpath1.0; 1451 description 1452 "Path expression used to represent a special 1453 schema-instance identifier string. 1455 A schema-instance-identifier value is an 1456 unrestricted YANG instance-identifier expression. 1457 All the same rules as an instance-identifier apply 1458 except predicates for keys are optional. If a key 1459 predicate is missing, then the schema-instance-identifier 1460 represents all possible server instances for that key. 1462 This XPath expression is evaluated in the following context: 1464 o The set of namespace declarations are those in scope on 1465 the leaf element where this type is used. 1467 o The set of variable bindings contains one variable, 1468 'USER', which contains the name of user of the current 1469 session. 1471 o The function library is the core function library, but 1472 note that due to the syntax restrictions of an 1473 instance-identifier, no functions are allowed. 1475 o The context node is the root node in the data tree."; 1476 } 1478 container nacm { 1479 nacm:very-secure; 1481 description 1482 "Parameters for NETCONF Access Control Model."; 1484 leaf enable-nacm { 1485 type boolean; 1486 default true; 1487 description 1488 "Enable or disable all NETCONF access control 1489 enforcement. If 'true', then enforcement 1490 is enabled. If 'false', then enforcement 1491 is disabled."; 1492 } 1494 leaf read-default { 1495 type nacm-action-type; 1496 default "permit"; 1497 description 1498 "Controls whether read access is granted if 1499 no appropriate rule is found for a 1500 particular read request."; 1501 } 1503 leaf write-default { 1504 type nacm-action-type; 1505 default "deny"; 1506 description 1507 "Controls whether create, update, or delete access 1508 is granted if no appropriate rule is found for a 1509 particular write request."; 1511 } 1513 leaf exec-default { 1514 type nacm-action-type; 1515 default "permit"; 1516 description 1517 "Controls whether exec access is granted if no appropriate 1518 rule is found for a particular RPC operation request."; 1519 } 1521 leaf denied-rpcs { 1522 type yang:zero-based-counter32; 1523 config false; 1524 mandatory true; 1525 description 1526 "Number of times an RPC operation request was denied 1527 since the server last restarted."; 1528 } 1530 leaf denied-data-writes { 1531 type yang:zero-based-counter32; 1532 config false; 1533 mandatory true; 1534 description 1535 "Number of times a request to alter a data node 1536 was denied, since the server last restarted."; 1537 } 1539 container groups { 1540 description 1541 "NETCONF Access Control Groups."; 1543 list group { 1544 key name; 1546 description 1547 "One NACM Group Entry."; 1549 leaf name { 1550 type nacm-group-name-type; 1551 description 1552 "Group name associated with this entry."; 1553 } 1555 leaf-list user-name { 1556 type nacm-user-name-type; 1557 description 1558 "Each entry identifies the user name of 1559 a member of the group associated with 1560 this entry."; 1561 } 1562 } 1563 } 1565 container rules { 1566 description 1567 "NETCONF Access Control Rules."; 1569 grouping common-rule-parms { 1570 description 1571 "Common rule parameters."; 1573 leaf rule-name { 1574 type string { 1575 length "1..256"; 1576 } 1577 description 1578 "Arbitrary name assigned to the 1579 access control rule."; 1580 } 1582 leaf allowed-rights { 1583 type nacm-rights-type; 1584 description 1585 "List of access rights granted to 1586 specified administrative groups for the 1587 content specified by the associated path."; 1588 } 1590 leaf-list allowed-group { 1591 type union { 1592 type nacm-matchall-string-type; 1593 type nacm-group-name-type; 1594 } 1595 min-elements 1; 1596 description 1597 "List of administrative groups which will be 1598 assigned the associated access rights 1599 for the content specified by the associated path. 1601 The string '*' indicates that all configured 1602 administrative groups apply to the entry."; 1603 } 1605 leaf nacm-action { 1606 type nacm-action-type; 1607 mandatory true; 1608 description 1609 "The access control action associated with the 1610 rule. If a rule is determined to match a 1611 particular request, then this object is used 1612 to determine whether to permit or deny the 1613 request."; 1614 } 1616 leaf comment { 1617 type string { 1618 length "1..4095"; 1619 } 1620 description 1621 "A textual description of the access rule."; 1622 } 1623 } 1625 list module-rule { 1626 key "module-name rule-name"; 1627 ordered-by user; 1629 description 1630 "One Module Access Rule. 1632 Rules are processed in user-defined order. A module rule 1633 is considered a match if the XML namespace for the 1634 specified module name matches the XML namespace used 1635 within a NETCONF PDU, and the administrative group 1636 associated with the requesting session is specified in the 1637 'allowed-group' leaf-list, and the requested operation 1638 is included in the 'allowed-rights' leaf."; 1640 leaf module-name { 1641 type string; 1642 description 1643 "Name of the module associated with this rule."; 1644 } 1646 uses common-rule-parms { 1647 refine allowed-rights { 1648 mandatory true; 1649 } 1650 } 1651 } 1653 list rpc-rule { 1654 key "module-name rpc-name rule-name"; 1655 ordered-by user; 1657 description 1658 "One RPC Operation Access Rule. 1660 Rules are processed in user-defined order. An RPC rule is 1661 considered a match if the module name of the requested RPC 1662 operation matches 'module-name', the requested RPC 1663 operation matches 'rpc-name', and an administrative group 1664 associated with the session user is listed in the 1665 'allowed-group' leaf-list. The 'allowed-rights' leaf 1666 is ignored by the server if it is present. 1667 Only the 'exec' bit can possibly cause 1668 a match for an RPC rule."; 1670 leaf module-name { 1671 type string; 1672 description 1673 "Name of the module defining this RPC operation."; 1674 } 1676 leaf rpc-name { 1677 type string; 1678 description 1679 "Name of the RPC operation."; 1680 } 1682 uses common-rule-parms; 1683 } 1685 list data-rule { 1686 key "rule-name"; 1687 ordered-by user; 1689 description 1690 "One Data Access Control Rule. 1692 Rules are processed in user-defined order. A data rule is 1693 considered to match when the path expression identifies 1694 the same node that is being accessed in the NETCONF 1695 datastore, and the administrative group associated with the 1696 session is identified in the 'allowed-group' leaf-list, 1697 and the requested operation is included in the 1698 'allowed-rights' leaf."; 1700 leaf path { 1701 type schema-instance-identifier; 1702 mandatory true; 1703 description 1704 "Schema Instance Identifier associated with the data node 1705 controlled by this rule. 1707 Configuration data or state data instance identifiers 1708 start with a top-level data node. A complete instance 1709 identifier is required for this type of path value. 1711 The special value '/' refers to all possible datastore 1712 contents."; 1713 } 1715 uses common-rule-parms { 1716 refine allowed-rights { 1717 mandatory true; 1718 } 1719 } 1720 } 1722 list notification-rule { 1723 key "module-name 1724 notification-name 1725 rule-name"; 1726 ordered-by user; 1728 description 1729 "One Notification Access Rule. 1731 A notification is considered a match if the module name of 1732 the requested event type matches 1733 'module-name', the requested event type 1734 matches the 'notification-name', and the administrative 1735 group associated with the requesting session is listed in 1736 the 'allowed-group' leaf-list. If the 'allowed-rights' 1737 leaf is present, it is ignored by the server. 1738 Only the 'read' bit can possibly cause 1739 a match for a notification rule."; 1741 leaf module-name { 1742 type string; 1743 description 1744 "Name of the module defining this 1745 notification event type."; 1746 } 1748 leaf notification-name { 1749 type string; 1750 description 1751 "Name of the notification event."; 1752 } 1754 uses common-rule-parms; 1755 } 1756 } 1757 } 1758 } 1760 1762 Figure 5 1764 3.5. IANA Considerations 1766 There are two actions that are requested of IANA: This document 1767 registers one URI in "The IETF XML Registry". Following the format 1768 in [RFC3688], the following has been registered. 1770 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1771 Registrant Contact: The IESG. 1772 XML: N/A, the requested URI is an XML namespace. 1774 This document registers one module in the "YANG Module Names" 1775 registry. Following the format in [RFC6020], the following has been 1776 registered. 1778 name: ietf-netconf-acm 1779 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-acm 1780 prefix: nacm 1781 reference: RFC XXXX 1782 // RFC Ed.: Replace XXX with actual RFC number 1783 // and remove this note 1785 3.6. Security Considerations 1787 This entire document discusses access control requirements and 1788 mechanisms for restricting NETCONF protocol behavior within a given 1789 session. 1791 Configuration of the access control system is highly sensitive to 1792 system security. A server may choose not to allow any user 1793 configuration to some portions of it, such as the global security 1794 level, or the groups which allowed access to system resources. 1796 This document incorporates the optional use of a 'superuser' account, 1797 which can be used to bypass access control enforcement. It is 1798 suggested that the 'root' account not be used for NETCONF over SSH 1799 servers, because 'root' SSH logins SHOULD be disabled in the SSH 1800 server. 1802 If the server chooses to allow user configuration of the access 1803 control system, then only sessions using the 'superuser' 1804 administrative user SHOULD be allowed to have write access to the 1805 data model. 1807 If the server chooses to allow user retrieval of the access control 1808 system configuration, then only sessions using the 'superuser' 1809 administrative user SHOULD be allowed to have read access to the data 1810 model. 1812 There is a risk that invocation of non-standard protocol operations 1813 will have undocumented side effects. An administrator needs to 1814 construct access control rules such that the configuration datastore 1815 is protected from such side effects. Also, such protocol operations 1816 SHOULD never be invoked by a session using the 'superuser' 1817 administrative user. 1819 There is a risk that non-standard protocol operations, or even the 1820 standard operation, may return data which 'aliases' or 'copies' 1821 sensitive data from a different data object. In this case, the 1822 namespace and/or the element name will not match the values for the 1823 sensitive data, which is then fully or partially copied into a 1824 different namespace and/or element. An administrator needs to avoid 1825 using data models which use this practice. 1827 An administrator needs to restrict write access to all configurable 1828 objects within this data model. It is suggested that only sessions 1829 using the 'superuser' administrative role be permitted to configure 1830 the data model defined in this document. 1832 If write access is allowed for configuration of access control rules, 1833 then care needs to be taken not to disrupt the access control 1834 enforcement. 1836 An administrator needs to restrict read access to the following 1837 objects within this data model, which reveal access control 1838 configuration which could be considered sensitive. 1840 o enable-nacm 1842 o read-default 1843 o write-default 1845 o exec-default 1847 o groups 1849 o rules 1851 4. References 1853 4.1. Normative References 1855 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1856 Requirement Levels", BCP 14, RFC 2119, March 1997. 1858 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1859 January 2004. 1861 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1862 Notifications", RFC 5277, July 2008. 1864 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1865 Network Configuration Protocol (NETCONF)", RFC 6020, 1866 October 2010. 1868 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 1869 October 2010. 1871 [I-D.ietf-netconf-4741bis] 1872 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1873 Bierman, "Network Configuration Protocol (NETCONF)", 1874 draft-ietf-netconf-4741bis-09 (work in progress), 1875 February 2011. 1877 [I-D.ietf-netconf-rfc4742bis] 1878 Wasserman, M. and T. Goddard, "Using the NETCONF 1879 Configuration Protocol over Secure Shell (SSH)", 1880 draft-ietf-netconf-rfc4742bis-07 (work in progress), 1881 February 2011. 1883 4.2. Informative References 1885 [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, 1886 "Remote Authentication Dial In User Service (RADIUS)", 1887 RFC 2865, June 2000. 1889 [RFC5607] Nelson, D. and G. Weber, "Remote Authentication Dial-In 1890 User Service (RADIUS) Authorization for Network Access 1891 Server (NAS) Management", RFC 5607, July 2009. 1893 Appendix A. Usage Examples 1895 The following XML snippets are provided as examples only, to 1896 demonstrate how NACM can be configured to perform some access control 1897 tasks. 1899 A.1. Example 1901 There needs to be at least one entry in order for any of the 1902 access control rules to be useful. 1904 The following XML shows arbitrary groups, and is not intended to 1905 represent any particular use-case. 1907 1908 1909 1910 admin 1911 admin 1912 andy 1913 1915 1916 monitor 1917 wilma 1918 bam-bam 1919 1921 1922 guest 1923 guest 1924 guest@example.com 1925 1926 1927 1929 This example shows 3 groups: 1931 1. The nacm:admin group contains 2 users named 'admin' and 'andy'. 1933 2. The nacm:monitor group contains 2 users named 'wilma' and 'bam- 1934 bam'. 1936 3. The nacm:guest group contains 2 users named 'guest' and 1937 'guest@example.com'. 1939 A.2. Example 1941 Module rules are used to control access to all the content defined in 1942 a specific module. These rules are checked after none of the 1943 specific rules (i.e., rpc-rule, data-rule, or notification-rule) 1944 matched the current access request. 1946 1947 1948 1949 ietf-netconf-monitoring 1950 mod-1 1951 * 1952 guest 1953 deny 1954 1955 Do not allow guests any access to the netconf 1956 monitoring information. 1957 1958 1960 1961 ietf-netconf-monitoring 1962 mod-2 1963 read 1964 monitor 1965 permit 1966 1967 Allow the monitor group read access to the netconf 1968 monitoring information. 1969 1970 1972 1973 * 1974 mod-3 1975 exec 1976 monitor 1977 permit 1978 1979 Allow the monitor group to invoke any of the 1980 supported server operations. 1981 1982 1983 1984 * 1985 mod-4 1986 * 1987 admin 1988 permit 1989 1990 Allow the admin group complete access to all 1991 operations and data. 1992 1993 1995 1996 1998 This example shows 4 module rules: 2000 mod-1: This rule prevents the guest group from reading any 2001 monitoring information in the ietf-netconf-monitoring YANG module. 2003 mod-2: This rule allows the monitor group to read the ietf-netconf- 2004 monitoring YANG module. 2006 mod-3: This rule allows the monitor group to invoke any protocol 2007 operation supported by the server. 2009 mod-4: This rule allows the admin group complete access to all 2010 content in the server. No subsequent rule will match for the 2011 admin group, because of this module rule. 2013 A.3. Example 2015 RPC rules are used to control access to a specific protocol 2016 operation. 2018 2019 2020 2021 ietf-netconf 2022 kill-session 2023 rpc-1 2024 monitor 2025 guest 2026 deny 2027 2028 Do not allow the monitor or guest group 2029 to kill another session. 2030 2031 2033 2034 ietf-netconf 2035 delete-config 2036 rpc-2 2037 monitor 2038 guest 2039 deny 2040 2041 Do not allow monitor or guest group 2042 to delete any configurations. 2043 2044 2046 2047 ietf-netconf 2048 edit-config 2049 rpc-3 2050 monitor 2051 permit 2052 2053 Allow the monitor group to edit the configuration. 2054 2055 2056 2057 2059 This example shows 3 protocol operation rules: 2061 rpc-1: This rule prevents the monitor or guest groups from invoking 2062 the NETCONF protocol operation. 2064 rpc-2: This rule prevents the monitor or guest groups from invoking 2065 the NETCONF protocol operation. 2067 rpc-3: This rule allows the monitor group to invoke the NETCONF 2068 protocol operation. This rule will have no real 2069 affect unless the 'exec-default' leaf is set to 'deny'. 2071 A.4. Example 2073 Data rules are used to control access to specific (config and non- 2074 config) data nodes within the NETCONF content provided by the server. 2076 2077 2078 2079 data-1 2080 /nacm 2081 * 2082 guest 2083 deny 2084 2085 Deny the guest group any access to the /nacm data. 2086 2087 2089 2090 data-acme-config 2091 2092 /acme:acme-netconf/acme:config-parameters 2093 2094 read create update delete 2095 monitor 2096 permit 2097 2098 Allow the monitor group complete access to the acme 2099 netconf configuration parameters. Showing long form 2100 of 'allowed-rights' instead of shorthand. 2101 2102 2104 2105 dummy-itf 2106 2107 /acme:interfaces/acme:interface[acme:name='dummy'] 2109 2110 read update 2111 monitor 2112 guest 2113 permit 2114 2115 Allow the monitor and guest groups read 2116 and update access to the dummy interface. 2117 2118 2120 2121 admin-itf 2122 2123 /acme:interfaces/acme:interface 2124 2125 * 2126 admin 2127 permit 2128 2129 Allow admin full access to all acme interfaces. 2130 This is an example of an unreachable rule, 2131 because the admin group already has full access 2132 to all modules (see rule 'mod-4'). 2133 All 'module-rule' entries will be checked 2134 before this 'data-rule' entry is checked. 2135 2136 2137 2138 2140 This example shows 4 data rules: 2142 data-1: This rule denies the guest group any access to the 2143 sub-tree. Note that the default namespace is only applicable 2144 because this sub-tree is defined in the same namespace as the 2145 element. 2147 data-acme-config: This rule gives the monitor group read-write 2148 access to the acme . 2150 dummy-itf: This rule gives the monitor and guest groups read-update 2151 access to the acme . entry named 'dummy'. This entry 2152 cannot be created or deleted by these groups, just altered. 2154 admin-itf: This rule gives the admin group read-write access to all 2155 acme . entries. This is an example of an unreachable 2156 rule because the 'mod-3' rule already gives the admin group full 2157 access to this data. 2159 A.5. Example 2161 Notification rules are used to control access to a specific 2162 notification event type. 2164 2165 2166 2167 acme-system 2168 sys-config-change 2169 notif-1 2170 monitor 2171 guest 2172 deny 2173 2174 Do not allow the guest or monitor groups 2175 to receive config change events. 2176 2177 2178 2179 2181 This example shows 1 notification rule: 2183 notif-1: This rule prevents the monitor or guest groups from 2184 receiving the acme event type. 2186 Appendix B. Change Log 2188 -- RFC Ed.: remove this section before publication. 2190 B.1. 02-03 2192 Fixed improper usage of RFC 2119 keywords. 2194 Changed term usage of 'database' to 'datastore'. 2196 Clarified that 'secure' and 'very-secure' extensions only apply if 2197 the /nacm/enable-nacm object is 'true'. 2199 B.2. 01-02 2201 Removed authentication text and objects. 2203 Changed module name from ietf-nacm to ietf-netconf-acm. 2205 Updated NETCONF and YANG terminology. 2207 Removed open issues section. 2209 Changed some must to MUST in requirements section. 2211 B.3. 00-01 2213 Updated YANG anf YANG Types references. 2215 Updated module namespace URI to standard format. 2217 Updated module header meta-data to standard format. 2219 Filled in IANA section. 2221 B.4. 00 2223 Initial version cloned from 2224 draft-bierman-netconf-access-control-02.txt. 2226 Authors' Addresses 2228 Andy Bierman 2229 Brocade 2231 Email: andy.bierman@brocade.com 2233 Martin Bjorklund 2234 Tail-f Systems 2236 Email: mbj@tail-f.com