idnits 2.17.1 draft-mahesh-netconf-accounting-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 == Line 204 has weird spacing: '...sion-id nc:...' == Line 205 has weird spacing: '...sage-id uin...' -- The document date (July 17, 2017) is 2474 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 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-01 Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jethanandani 3 Internet-Draft Cisco Systems, Inc 4 Intended status: Standards Track July 17, 2017 5 Expires: January 18, 2018 7 Accounting in NETCONF and RESTCONF 8 draft-mahesh-netconf-accounting-03 10 Abstract 12 This document defines an accounting record for NETCONF and RESTCONF. 14 Requirements Language 16 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 17 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 18 document are to be interpreted as described in RFC 2119 [RFC2119]. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 18, 2018. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Compatability with remote AAA servers . . . . . . . . . . 2 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Accounting Record . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Data Model Definitions . . . . . . . . . . . . . . . . . . . 5 59 3.1. Data Organization . . . . . . . . . . . . . . . . . . . . 5 60 3.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 5 61 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 62 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 63 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 64 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 66 7.2. Informative References . . . . . . . . . . . . . . . . . 12 67 Appendix A. Accounting model examples . . . . . . . . . . . . . 12 68 A.1. Example for Accounting . . . . . . . . . . 12 69 A.2. Example for Accounting . . . . . . . . . . . . . . 12 70 A.3. NACM rule for Accounting . . . . . . . . . . . . . . . . 13 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 73 1. Introduction 75 NETCONF [RFC6241] and RESTCONF [RFC8040] protocol operations are 76 authenticated and authorized as part of the Authentication, 77 Authorization and Accounting (AAA) framework. An accounting record 78 is generated as part of the same framework for each of these 79 operations to satisfy the accounting part of AAA, but there has been 80 no effort to define such a record. Having an accounting record that 81 is consistent across vendors allows for the operator to compare 82 operations across devices from different vendors. This document 83 defines such a record and a corresponding YANG data model (ietf- 84 netconf-am.yang). 86 The rest of this document will use NETCONF to imply both NETCONF and 87 RESTCONF, but where applicable will call out each protocol 88 specifically. 90 1.1. Compatability with remote AAA servers 92 This document does not cover how the server interacts with remote AAA 93 servers and any interaction is out of scope of this document. A 94 particular implementation can make the records available as part of 95 request, send a notification every time a accounting record is 96 generated or use any existing protocol to update the remote AAA 97 server. 99 1.2. Terminology 101 The following terms are defined in NETCONF [RFC6241] and are not 102 redefined here: 104 o client 106 o 108 o notification 110 o server 112 o session 114 o user 116 And the following terms are defined in NACM [RFC6536] and are not 117 redefined here. 119 o data-node 121 o action 123 o rule 125 2. Accounting Record 127 An accounting record for NETCONF consists of the following fields. 128 Note, there is no accounting record for reading or notification of an 129 accounting record. 131 +------+------+----+-----+-----+-----+-----+------+-----+-----+-----+ 132 | mess | sess | sr | dat | use | gro | rul | data | val | act | sta | 133 | age- | ion- | c- | e-t | r | ups | e | - | ue | ion | tus | 134 | id | id | ip | ime | | | | node | | | | 135 +------+------+----+-----+-----+-----+-----+------+-----+-----+-----+ 136 +------+------+----+-----+-----+-----+-----+------+-----+-----+-----+ 138 where: 140 message-id: This is the id within a given NETCONF session assigned to 141 each RPC. RESTCONF has no concept of a session, so this field would 142 be left blank. 144 session-id: The session-id in case of NETCONF and would be blank in 145 case of RESTCONF. If the accounting record needs to be fragmented 146 for any reason, it is suggested that this field not be repeated in 147 subsequent packets. Instead a combination of start and end record 148 marker, and the message-id should be used to reassemble fragmented 149 records. 151 src-ip: The source IP address that was used to request the operation. 152 If the accounting record needs to be fragmented for any reason, it is 153 suggested that this field not be repeated in subsequent packets. 154 Instead a combination of start and end record marker, and the 155 message-id should be used to reassemble fragmented records. 157 date-time: The date and time when the operation was performed (UTC 158 Timezone). If the accounting record needs to be fragmented for any 159 reason, it is suggested that this field not be repeated in subsequent 160 packets. Instead a combination of start and end record marker, and 161 the message-id should be used to reassemble fragmented records. 163 user: The NETCONF user that requesed this operation. If the 164 accounting record needs to be fragmented for any reason, it is 165 suggested that this field not be repeated in subsequent packets. 166 Instead a combination of start and end record marker, and the 167 message-id should be used to reassemble fragmented records. 169 groups: The group the user belongs to. If the accounting record 170 needs to be fragmented for any reason, it is suggested that this 171 field not be repeated in subsequent packets. Instead a combination 172 of start and end record marker, and the message-id should be used to 173 reassemble fragmented records. 175 data-node: The data-node in the NACM [RFC6536] rule on which the 176 operations is being performed 178 value: The value that was set for any of the attributes in the 179 request 181 action: The action in the NACM [RFC6536] rule 183 rule: The rule in the NACM [RFC6536] that was matched to authorize 184 the action. 186 status: Whether the operations was permitted or denied. 188 3. Data Model Definitions 190 The model uses the NACM extension statement of default-deny-all to 191 protect accounting records. Explicit rules have to be defined to be 192 enable access to the accounting records. 194 3.1. Data Organization 196 The following diagram highlights the contents and structure of the 197 Accounting YANG module. For information on annotations, please refer 198 to YANG Tree Diagrams [I-D.ietf-netmod-yang-tree-diagrams]. 200 module: ietf-netconf-am 201 +--rw nam 202 +--rw enable-nam? boolean 203 +--ro accounting-record* [session-id message-id] 204 +--ro session-id nc:session-id-type 205 +--ro message-id uint32 206 +--ro date-time yang:date-and-time 207 +--ro src-ip inet:ip-address 208 +--ro group nacm:group-name-type 209 +--ro user? nacm:user-name-type 210 +--ro rule? string 211 +--ro data-node nacm:node-instance-identifier 212 +--ro value? 213 +--ro action nacm:access-operations-type 214 +--ro status? nacm:action-type 216 3.2. YANG Module 218 The following YANG module specifies the normative NETCONF content 219 that MUST be supported by the server. 221 The "ietf-netconf-am" YANG module imports typedefs from YANG-TYPES 222 [RFC6991], from NETCONF [RFC6241] and from NACM [RFC6536]. 224 file "ietf-netconf-am@2017-07-16.yang" 226 module ietf-netconf-am { 227 yang-version 1.1; 228 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-am"; 229 prefix "nam"; 231 import ietf-inet-types { 232 prefix inet; 233 } 235 import ietf-yang-types { 236 prefix yang; 237 } 239 import ietf-netconf { 240 prefix nc; 241 } 243 import ietf-netconf-acm { 244 prefix nacm; 245 } 247 organization 248 "IETF NETCONF (Network Configuration) Working Group"; 250 contact 251 "WG Web: 252 WG List: 254 WG Chair: Mehmet Ersue 255 257 WG Chair: Mahesh Jethanandani 258 260 Editor: Mahesh Jethanandani 261 "; 263 description 264 "This module defines an accounting record for NETCONF operations 265 performed on the server. If these operations are authorized 266 using rules defined by NACM [RFC6536], then that information is 267 also captured by this module. 269 Copyright (c) 2014 IETF Trust and the persons identified as 270 authors of the code. All rights reserved. 272 Redistribution and use in source and binary forms, with or 273 without modification, is permitted pursuant to, and subject 274 to the license terms contained in, the Simplified BSD 275 License set forth in Section 4.c of the IETF Trust's 276 Legal Provisions Relating to IETF Documents 277 (http://trustee.ietf.org/license-info). 279 This version of this YANG module is part of RFC XXXX; see 280 the RFC itself for full legal notices."; 282 revision "2017-07-16" { 283 description 284 "Initial version"; 285 reference 286 "RFC XXXX: NETCONF and RESTCONF Accounting"; 287 } 289 /* 290 * Data definition statements. 291 */ 293 container nam { 294 nacm:default-deny-all; 296 description 297 "Parameters for NETCONF Accounting Model."; 299 leaf enable-nam { 300 type boolean; 301 default true; 302 description 303 "Enable or disable generation of NETCONF 304 accounting records. If 'true', accounting 305 records will be generated. If set to 'false' 306 no accounting records will be generated."; 307 } 309 list accounting-record { 310 key "session-id message-id"; 311 config false; 312 description 313 "A list of accounting records generated by the server"; 315 leaf session-id { 316 type nc:session-id-type; 317 description 318 "If this operation happened over NETCONF, this 319 field captures the NETCONF session-id. In case 320 of RESTCONF this field can be left blank."; 321 } 323 leaf message-id { 324 type uint32; 325 description 326 "Id that is assigned to each RPC within a given 327 NETCONF session. Should be blank in case of 328 RESTCONF."; 329 } 330 leaf date-time { 331 type yang:date-and-time; 332 mandatory true; 333 description 334 "The date and time when the operation was 335 requested."; 336 } 338 leaf src-ip { 339 type inet:ip-address; 340 mandatory true; 341 description 342 "The source IP address where the request was made 343 from."; 344 } 346 leaf group { 347 type nacm:group-name-type; 348 mandatory true; 349 description 350 "The name of the group that the user who requested 351 the operation belongs to."; 352 } 354 leaf user { 355 type nacm:user-name-type; 356 description 357 "The user within the group that is requesting this 358 operation."; 359 } 361 leaf rule { 362 type string { 363 length "1..max"; 364 } 365 description 366 "The name assigned to the rule that was used to 367 authorize the action, if authorization was 368 enabled."; 369 } 371 leaf data-node { 372 type nacm:node-instance-identifier; 373 mandatory true; 374 description 375 "Data Node Instance Identifier associated with the 376 data node that the request is being made on. 378 Instance identifiers start with the top-level 379 data node, and a complete identifier is required 380 for this value."; 381 } 383 anydata value { 384 description 385 "An optional field, it contains the value of any 386 of the attribute that form the record. 388 It could be as simple as the filter value 389 'http' specified that the user requested as part 390 of the authorization request such as in this 391 example: 393 394 http 395 397 or it could be value being set for a ssh port 398 in this example: 400 401 2022 402 "; 403 } 405 leaf action { 406 type nacm:access-operations-type; 407 mandatory true; 408 description 409 "The type of NETCONF operation being requested."; 410 } 412 leaf status { 413 type nacm:action-type; 414 description 415 "Action taken by the server when the above 416 mentioned rule matched, if authorization was 417 enable."; 418 } 419 } 420 } 421 } 423 424 4. IANA Considerations 426 This document makes two requests of IANA. 428 The first request is to register one URI in "The IETF XML Registry". 429 Following the format in The IETF XML Registry [RFC3688], the 430 following needs to be registered. 432 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-am 434 Registrant Contact: The IESG 436 XML: N/A, the requested URI is an XML namespace 438 The second request is to register one module in the "YANG Module 439 Names" registry. Following the format in YANG [RFC7950], the 440 following needs to be registered. 442 Name: ietf-netconf-am 444 Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-am 446 Prefix: nam 448 Reference: RFC XXXX 450 Note to RFC Editor - Please replace XXXX here and in the rest of the 451 draft with the RFC id assigned to this draft. 453 5. Security Considerations 455 The YANG module defined in this document is designed to be accessed 456 via network management protocol such as NETCONF [RFC6241] or RESTCONF 457 [RFC8040]. The lowest NETCONF layer is the secure transport layer, 458 and the mandatory-to-implement secure transport is Secure Shell (SSH) 459 [RFC6242]. The lowest RESTCONF layers is HTTPS, and the mandatory- 460 to-implement secure transport is TLS [RFC5246]. 462 The NETCONF Access Control Model (NACM) [RFC6536] provides the means 463 to restrict access for particular NETCONF or RESTCONF users to a pre- 464 configured subset of all available NETCONF or RESTCONF protocol 465 operations and content. 467 Most of the data nodes defined in this YANG module are readonly, i.e. 468 config false, and are therefore not vulnerable to manipulation in 469 network environments. However, they might contain data that might be 470 sensitive and should be protected with the right NACM [RFC6536] 471 rules. 473 6. Acknowledgements 475 7. References 477 7.1. Normative References 479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 480 Requirement Levels", BCP 14, RFC 2119, 481 DOI 10.17487/RFC2119, March 1997, 482 . 484 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 485 DOI 10.17487/RFC3688, January 2004, 486 . 488 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 489 (TLS) Protocol Version 1.2", RFC 5246, 490 DOI 10.17487/RFC5246, August 2008, 491 . 493 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 494 and A. Bierman, Ed., "Network Configuration Protocol 495 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 496 . 498 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 499 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 500 . 502 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 503 Protocol (NETCONF) Access Control Model", RFC 6536, 504 DOI 10.17487/RFC6536, March 2012, 505 . 507 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 508 RFC 6991, DOI 10.17487/RFC6991, July 2013, 509 . 511 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 512 RFC 7950, DOI 10.17487/RFC7950, August 2016, 513 . 515 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 516 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 517 . 519 7.2. Informative References 521 [I-D.ietf-netmod-yang-tree-diagrams] 522 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 523 ietf-netmod-yang-tree-diagrams-01 (work in progress), June 524 2017. 526 Appendix A. Accounting model examples 528 A.1. Example for Accounting 530 This example demonstrates how the configuration could be updated to 531 enable accounting. The attribute in the model that enables 532 accounting is enable-nam. 534 536 537 538 539 540 test-then-set 541 rollback-on-error 542 543 544 true 545 546 547 548 550 A.2. Example for Accounting 552 This example demonsrates what a request and response might look 553 like. 555 557 558 559 560 561 562 563 564 566 568 569 570 571 101 572 100 573 2017-06-19T16:39:57-08:00 574 172.20.39.46 575 netconf-group 576 netconf 577 578 /acme:interfaces/acme:interface 579 580 581 GigabitEthernet0/0/0/0 582 UP 583 584 read 585 51 586 permit 587 588 589 590 592 A.3. NACM rule for Accounting 594 This example demonstrates how NACM could be configured to permit 595 access to accounting records. Note, the model has default-deny-all 596 set to prevent access to accounting records by default, and expects 597 explicit rules to be configured to permit access. 599 600 601 root 602 root 604 605 allow-nam 606 607 /n:nam 608 609 read 610 permit 611 612 Allow the root group read access to the /nam data. 613 614 615 616 618 Author's Address 620 Mahesh Jethanandani 621 Cisco Systems, Inc 622 170 West Tasman Drive 623 San Jose, CA 95070 624 USA 626 Email: mjethanandani@gmail.com