idnits 2.17.1 draft-lear-opsawg-mud-reporter-00.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 123 has weird spacing: '...ort-uri ine...' == Line 142 has weird spacing: '...thority ine...' == Line 217 has weird spacing: '...rmation group...' == Line 446 has weird spacing: '...olating packe...' == Line 534 has weird spacing: '... uses repor...' -- The document date (July 05, 2019) is 1751 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) == Unused Reference: 'RFC6991' is defined on line 588, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Lear 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track M. Ranganathan 5 Expires: January 6, 2020 NIST 6 July 05, 2019 8 Reporting MUD behavior to vendors 9 draft-lear-opsawg-mud-reporter-00 11 Abstract 13 As with other technology, manufacturers would like to understand how 14 networks implementing MUD are treating devices that are providing MUD 15 URLs and MUD files. This memo specifies an extension to MUD that 16 permits certain behaviors to be reported. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 6, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. The mud-reporter-extension model extension . . . . . . . . . 3 54 2.1. The mud-reporter-extension augmentation to the MUD YANG 55 model . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.2. The Reporter record format . . . . . . . . . . . . . . . 6 57 3. RESTful interface at the collector . . . . . . . . . . . . . 11 58 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 12 59 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12 60 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 61 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 62 7.1. Normative References . . . . . . . . . . . . . . . . . . 13 63 7.2. Informative References . . . . . . . . . . . . . . . . . 13 64 Appendix A. Changes from Earlier Versions . . . . . . . . . . . 14 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 67 1. Introduction 69 Manufacturer Usage Descriptions (MUD) [RFC8520] provides a means for 70 devices to identify what they are and what sort of network access 71 they need. When a device with a MUD URL and a MUD file is fielded in 72 volume, manufacturers may be curious as to whether it is getting the 73 access it needs. There a few several reasons why a device would not 74 be getting the access it needs. Some examples include: 76 o The MUD file permits access only to a controller but there is 77 none. 79 o The MUD file permits access only to same-manufacturer or model but 80 there is none. 82 o The MUD file permits access to a particular Internet service, but 83 the name of that service has not been resolved (or name resolution 84 failed). 86 o The administrator overrode the recommendations in the MUD file. 88 This memo sets out to provide manufacturers indications regarding 89 what has happened, in a similar vein to how DMARC is usd to report 90 message drops to messag senders [RFC7489]. 92 In order to provide meaningful reporting, it is necessary to indicate 93 whether or not the above abstractions are in use at a given time, and 94 any public IP addresses that have been mapped to domain names by the 95 local deployment. A communication method that may establish the 96 source of the reporter is also necessary, as well as the MUD URL in 97 use at the time of the report. 99 This memo specifies a YANG model for reporting and a means for 100 transmitting the report, and appropriate extensions to the MUD file 101 to indicate how to report and how often. 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 105 "OPTIONAL" in this document are to be interpreted as described in BCP 106 14 [RFC2119] [RFC8174] when, and only when, they appear in all 107 capitals, as shown here. 109 2. The mud-reporter-extension model extension 111 We now formally define this extension. This is done in two parts. 112 First, the extension name "reporter" is listed in the "extensions" 113 array of the MUD file. 115 Second, the "mud" container is augmented with a container that points 116 to where to report and how often. 118 This is done as follows: 120 module: ietf-mud-controller-candidate 121 augment /mud:mud: 122 +--rw reporter 123 +--rw report-uri inet:uri 124 +--rw frequency? uint32 126 Finally the logging format is defined as follows: 128 module: ietf-mud-reporter 129 +--rw mud-reporter 130 +--rw mudurl? inet:uri 131 +--rw mud-report* [time] 132 +--rw time yang:timestamp 133 +--rw opaqueidentifier? string 134 +--rw direction? enumeration 135 +--rw mycontrollers? uint32 136 +--rw controllers* [uri] 137 | +--rw uri inet:uri 138 | +--rw count? uint32 139 | +--rw ipaddress? inet:ip-address 140 +--rw samemanufacturers? uint32 141 +--rw manufacturers* [authority] 142 | +--rw authority inet:host 143 | +--rw count? uint32 144 | +--rw ipaddress? inet:ip-address 145 +--rw models* [uri] 146 | +--rw uri inet:uri 147 | +--rw count? uint32 148 | +--rw ipaddress? inet:ip-address 149 +--rw domains* [hostname] 150 | +--rw hostname inet:host 151 | +--rw ip-addresses* inet:ip-address 152 +--rw manufacturer? string 153 +--rw model? string 154 +--rw local-networks? boolean 155 +--rw controller? string 156 +--rw drop-count? uint32 158 2.1. The mud-reporter-extension augmentation to the MUD YANG model 160 file "ietf-mud-reporter-extension@2019-06-21.yang" 161 module ietf-mud-reporter-extension { 162 yang-version 1.1; 163 namespace "urn:ietf:params:xml:ns:yang:ietf-mud-reporter-extension"; 164 prefix mud-reporter-extension; 166 import ietf-mud { 167 prefix "mud"; 168 } 170 import ietf-inet-types { 171 prefix "inet"; 172 } 174 organization 175 "IETF OPSAWG (Ops Area) Working Group"; 176 contact 177 "WG Web: http://tools.ietf.org/wg/opsawg/ 178 WG List: opsawg@ietf.org 179 Author: Eliot Lear 180 lear@cisco.com 181 "; 182 description 184 "This YANG module augments the ietf-mud model to provide for two 185 optional lists to indicate that this device type may be used as 186 a controller for other MUD-enabled devices. 188 Copyright (c) 2019 IETF Trust and the persons identified as 189 authors of the code. All rights reserved. 191 Redistribution and use in source and binary forms, with or 192 without modification, is permitted pursuant to, and subject to 193 the license terms contained in, the Simplified BSD License set 194 forth in Section 4.c of the IETF Trust's Legal Provisions 195 Relating to IETF Documents 196 (https://trustee.ietf.org/license-info). 198 This version of this YANG module is part of RFC XXXX 199 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 200 for full legal notices. 202 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 203 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 204 'MAY', and 'OPTIONAL' in this document are to be interpreted as 205 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 206 they appear in all capitals, as shown here. 207 "; 209 revision 2019-06-21 { 210 description 211 "Initial proposed standard."; 212 reference "RFC XXXX: Extension for MUD Reporting"; 213 } 215 grouping mud-reporter-extension { 216 description 217 "Reporter information grouping"; 218 container reporter { 219 description "Reporter information"; 220 leaf report-uri { 221 type inet:uri; 222 description 223 "Restful endpoint for reporter information."; 224 } 225 leaf frequency { 226 type uint32 227 { 228 range "60..max"; 229 } 230 default 1440; 231 description 232 "The minimum period of time in minutes that a deployment 233 should report."; 234 } 235 } 236 } 238 augment "/mud:mud" { 239 uses mud-reporter-extension; 240 description 241 "add reporter extension"; 242 } 243 } 244 246 2.2. The Reporter record format 248 file "ietf-mud-reporter@2019-06-21.yang" 249 module ietf-mud-reporter { 250 yang-version 1.1; 251 namespace "urn:ietf:params:xml:ns:yang:ietf-mud-reporter"; 252 prefix mud-reporter; 254 import ietf-inet-types { 255 prefix inet; 256 } 257 import ietf-yang-types { 258 prefix yang; 259 } 261 organization 262 "IETF OPSAWG (Ops Area) Working Group"; 263 contact 264 "WG Web: http://tools.ietf.org/wg/opsawg/ 265 WG List: opsawg@ietf.org 266 Author: Eliot Lear 267 lear@cisco.com 268 "; 269 description 270 "This YANG module specifies the reporting format for MUD managers 271 to use when they are reporting to manufacturers. 273 Copyright (c) 2019 IETF Trust and the persons identified as 274 authors of the code. All rights reserved. 276 Redistribution and use in source and binary forms, with or 277 without modification, is permitted pursuant to, and subject to 278 the license terms contained in, the Simplified BSD License set 279 forth in Section 4.c of the IETF Trust's Legal Provisions 280 Relating to IETF Documents 281 (https://trustee.ietf.org/license-info). 283 This version of this YANG module is part of RFC XXXX 284 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 285 for full legal notices. 287 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 288 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 289 'MAY', and 'OPTIONAL' in this document are to be interpreted as 290 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 291 they appear in all capitals, as shown here. 292 "; 294 revision 2019-06-21 { 295 description 296 "Initial proposed standard."; 297 reference 298 "RFC XXXX: Extension for MUD Reporting"; 299 } 301 container mud-reporter { 302 uses mud-reporter-grouping; 303 description "Reporter Information."; 304 } 306 grouping mud-reporter-grouping { 308 description 309 "MUD reporter container."; 310 leaf mudurl { 311 type inet:uri; 312 description 313 "The MUD-URL for which the report is being sent."; 314 } 315 list mud-report { 316 key "time"; 317 description 318 "individual records."; 320 leaf time { 321 type yang:timestamp; 322 description 323 "when this happened."; 324 } 325 leaf opaqueidentifier { 326 type string; 327 description 328 "This is an identifier that maps to a particular 329 device. Its value MUST NOT be mappable back to 330 any identifying information about the device. It 331 may be a suitable hash, such as SHA256."; 332 } 333 leaf direction { 334 type enumeration { 335 enum to-device { 336 description 337 "packet was traveling toward the device"; 338 } 339 enum from-device { 340 description 341 "packet was traveling away from the device"; 342 } 343 } 344 description 345 "which way packet is going"; 346 } 347 leaf mycontrollers { 348 type uint32; 349 description 350 "how many entries for my-controller."; 351 } 352 list controllers { 353 key "uri"; 354 description 355 "list of controllers and how many there were."; 356 leaf uri { 357 type inet:uri; 358 description 359 "the class URI of this controller"; 360 } 361 leaf count { 362 type uint32; 363 description 364 "number of devices serving this class."; 365 } 366 leaf ipaddress { 367 type inet:ip-address; 368 description 369 "IP address of the controller. Note that the MUD 370 reporter MUST NOT transmit this contents of this 371 node to the manufacturer."; 372 } 373 } 374 leaf samemanufacturers { 375 type uint32; 376 description 377 "number of devices matching same 378 manufacturer."; 379 } 380 list manufacturers { 381 key "authority"; 382 description 383 "list of models and how many there were."; 384 leaf authority { 385 type inet:host; 386 description 387 "the manufacturer domain"; 388 } 389 leaf count { 390 type uint32; 391 description 392 "number of devices serving this class."; 393 } 394 leaf ipaddress { 395 type inet:ip-address; 396 description 397 "IP address of the controller. Note that the MUD 398 reporter MUST NOT transmit this contents of this 399 node to the manufacturer."; 400 } 401 } 402 list models { 403 key "uri"; 404 description 405 "list of models and how many there were."; 406 leaf uri { 407 type inet:uri; 408 description 409 "the URI of this model"; 410 } 411 leaf count { 412 type uint32; 413 description 414 "number of devices serving this class."; 415 } 416 leaf ipaddress { 417 type inet:ip-address; 418 description 419 "IP address of the controller. Note that the MUD 420 reporter MUST NOT transmit this contents of this 421 node to the manufacturer."; 422 } 423 } 424 list domains { 425 key "hostname"; 426 description 427 "list of hosts, and ip addresses if known."; 428 leaf hostname { 429 type inet:host; 430 description 431 "the host listed"; 432 } 433 leaf-list ip-addresses { 434 type inet:ip-address; 435 description 436 "ipv4 or v6 address mapping for this host if 437 known."; 438 } 439 } 440 uses class-drop-count; 441 } 442 } 444 grouping class-drop-count { 445 description 446 "Destination fields of acl violating packet are classfied."; 447 leaf manufacturer { 448 type string; 449 description 450 "manufacturer name"; 451 } 452 leaf model { 453 type string; 454 description 455 "model name"; 456 } 457 leaf local-networks { 458 type boolean; 459 description 460 "this packet matches the local networks 461 classification"; 462 } 463 leaf controller { 464 type string; 465 description 466 "controller name"; 467 } 468 leaf drop-count { 469 type uint32; 470 description 471 "number of packets dropped for this classification"; 472 } 473 } 474 } 476 478 3. RESTful interface at the collector 480 file "ietf-mud-reporter-collector@2019-06-21.yang" 481 module ietf-mud-reporter-collector { 482 yang-version 1.1; 483 namespace "urn:ietf:params:xml:ns:yang:ietf-mud-reporter-collector"; 484 prefix "mud-collector"; 486 import ietf-mud-reporter { 487 prefix "reporter"; 488 } 489 organization 490 "IETF OPSAWG (Ops Area) Working Group"; 491 contact 492 "WG Web: http://tools.ietf.org/wg/opsawg/ 493 WG List: opsawg@ietf.org 494 Author: Eliot Lear 495 lear@cisco.com 496 Author: Mudumbai Ranganathan 497 mranga@nist.gov 498 "; 499 description 500 "This YANG module specifies the reporting format for MUD managers 501 to use when they are reporting to manufacturers. 503 Copyright (c) 2019 IETF Trust and the persons identified as 504 authors of the code. All rights reserved. 506 Redistribution and use in source and binary forms, with or 507 without modification, is permitted pursuant to, and subject to 508 the license terms contained in, the Simplified BSD License set 509 forth in Section 4.c of the IETF Trust's Legal Provisions 510 Relating to IETF Documents 511 (https://trustee.ietf.org/license-info). 513 This version of this YANG module is part of RFC XXXX 514 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 515 for full legal notices. 517 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 518 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 519 'MAY', and 'OPTIONAL' in this document are to be interpreted as 520 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 521 they appear in all capitals, as shown here. 522 "; 523 revision 2019-06-21 { 524 description 525 "Initial proposed standard."; 526 reference 527 "RFC XXXX: Extension for MUD Reporting"; 528 } 529 rpc post-mud-report { 530 description 531 "Rpc interface that must be supported by collection point."; 532 input { 533 container mud-report { 534 uses reporter:mud-reporter-grouping; 535 description "MUD report"; 536 } 537 } 538 } 539 } 541 543 4. Examples 545 TBD 547 5. Privacy Considerations 549 Using this reporting mechanisms does not reveal internal IP 550 addresses. Instead, it simply indicates whether a given abstraction 551 is in use, and how many instances there are. What is revealed to the 552 manufacturer is that one or more devices reporting a particular MUD- 553 URL is located at a particular deployment. In addition, as of this 554 draft, reportable events include only administratively dropped 555 packets, and the times they were dropped. 557 In order to report the sorts of errors discussed in this memo, a 558 deployment must determine which packets from a given device have 559 either been or would be dropped due to an administrative filter rule. 561 6. Security Considerations 563 All security considerations of [RFC8520] apply equally to this 564 extension. In addition, some care should be given to claims that a 565 device is permitted to be a controller in any given circumstances. 566 Complete automation requires far more context than is currently 567 specified here. Some form of confirmation or selection is required 568 by an administrator. This memo simply makes it easier for 569 administrator to identify candidates for controller selection. 571 IANA Considerations =================== 573 The IANA is requested to add "controller-candidate" to the MUD 574 extensions registry as follows: 576 Extension Name: reporter 577 Standard reference: This document 579 7. References 581 7.1. Normative References 583 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 584 Requirement Levels", BCP 14, RFC 2119, 585 DOI 10.17487/RFC2119, March 1997, 586 . 588 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 589 RFC 6991, DOI 10.17487/RFC6991, July 2013, 590 . 592 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 593 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 594 May 2017, . 596 [RFC8520] Lear, E., Droms, R., and D. Romascanu, "Manufacturer Usage 597 Description Specification", RFC 8520, 598 DOI 10.17487/RFC8520, March 2019, 599 . 601 7.2. Informative References 603 [RFC7489] Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based 604 Message Authentication, Reporting, and Conformance 605 (DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015, 606 . 608 Appendix A. Changes from Earlier Versions 610 Draft -00: 612 o Initial revision 614 Authors' Addresses 616 Eliot Lear 617 Cisco Systems 618 Richtistrasse 7 619 Wallisellen CH-8304 620 Switzerland 622 Phone: +41 44 878 9200 623 Email: lear@cisco.com 625 Mudumbai Ranganathan 626 NIST 627 100 Bureau Dr. 628 Gaithersburg 629 U.S.A 631 Phone: +1 301 975 2857 632 Email: mranga@nist.gov