idnits 2.17.1 draft-lear-ietf-netmod-mud-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 01, 2016) is 2825 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) == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-03 == Outdated reference: A later version (-21) exists of draft-ietf-netmod-acl-model-08 -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE8021AB' ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 3315 (Obsoleted by RFC 8415) ** Downref: Normative reference to an Informational RFC: RFC 6092 ** Downref: Normative reference to an Informational RFC: RFC 7299 -- Obsolete informational reference (is this intentional?): RFC 7042 (Obsoleted by RFC 9542) Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Lear 3 Internet-Draft R. Droms 4 Intended status: Standards Track Cisco Systems 5 Expires: February 2, 2017 D. Romascanu 6 Avaya 7 August 01, 2016 9 Manufacturer Usage Description Specification 10 draft-lear-ietf-netmod-mud-04 12 Abstract 14 This memo specifies the necessary components to implement 15 manufacturer usage descriptions (MUD). This includes two YANG 16 modules, IPv4 and IPv6 DHCP options, an LLDP TLV, a URL suffix 17 specification, an X.509 certificate extension and a means to sign and 18 verify the descriptions. 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 February 2, 2017. 37 Copyright Notice 39 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 56 2. The MUD Model and Semantic Meaning . . . . . . . . . . . . . 4 57 3. Element Definitions . . . . . . . . . . . . . . . . . . . . . 5 58 3.1. last-update . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.2. previous-mud-file . . . . . . . . . . . . . . . . . . . . 5 60 3.3. cache-validity . . . . . . . . . . . . . . . . . . . . . 5 61 3.4. masa-server . . . . . . . . . . . . . . . . . . . . . . . 6 62 3.5. is-supported . . . . . . . . . . . . . . . . . . . . . . 6 63 3.6. packet-direction . . . . . . . . . . . . . . . . . . . . 6 64 3.7. manufacturer . . . . . . . . . . . . . . . . . . . . . . 6 65 3.8. same-manufacturer . . . . . . . . . . . . . . . . . . . . 6 66 3.9. model . . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 3.10. local-networks . . . . . . . . . . . . . . . . . . . . . 6 68 3.11. controller . . . . . . . . . . . . . . . . . . . . . . . 7 69 3.12. direction-initiated . . . . . . . . . . . . . . . . . . . 7 70 4. Processing of the MUD file . . . . . . . . . . . . . . . . . 7 71 5. What does a MUD URL look like? . . . . . . . . . . . . . . . 7 72 6. The MUD YANG Model . . . . . . . . . . . . . . . . . . . . . 8 73 7. The Domain Name Extension to the ACL Model . . . . . . . . . 11 74 7.1. source-dnsname . . . . . . . . . . . . . . . . . . . . . 12 75 7.2. destination-dnsname . . . . . . . . . . . . . . . . . . . 12 76 7.3. The ietf-acldns Model . . . . . . . . . . . . . . . . . . 12 77 8. MUD File Example . . . . . . . . . . . . . . . . . . . . . . 13 78 9. The MUD URL DHCP Option . . . . . . . . . . . . . . . . . . . 15 79 9.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 15 80 9.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 16 81 9.3. Relay Requirements . . . . . . . . . . . . . . . . . . . 16 82 10. The Manufacturer Usage Description (MUD) URL X.509 Extension 16 83 11. The Manufacturer Usage Description LLDP extension . . . . . . 17 84 12. Creating and Processing of Signed MUD Files . . . . . . . . . 18 85 12.1. Creating a MUD file signature . . . . . . . . . . . . . 18 86 12.2. Verifying a MUD file signature . . . . . . . . . . . . . 19 87 13. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 19 88 14. Security Considerations . . . . . . . . . . . . . . . . . . . 20 89 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 90 15.1. DHCPv4 and DHCPv6 Options . . . . . . . . . . . . . . . 21 91 15.2. PKIX Extensions . . . . . . . . . . . . . . . . . . . . 21 92 15.3. Well Known URI Suffix . . . . . . . . . . . . . . . . . 21 93 15.4. MIME Media-type Registration for MUD files . . . . . . . 21 94 15.5. LLDP IANA TLV Subtype Registry . . . . . . . . . . . . . 22 95 16. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 96 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 97 17.1. Normative References . . . . . . . . . . . . . . . . . . 23 98 17.2. Informative References . . . . . . . . . . . . . . . . . 24 99 Appendix A. Changes from Earlier Versions . . . . . . . . . . . 25 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 102 1. Introduction 104 Manufacturer Usage Descriptions (MUDs) provide advice to end networks 105 on how to treat specific classes of devices. The MUD architecture is 106 explained in [I-D.lear-mud-framework]. The files that are retrieved 107 are intended to be closely aligned to existing network architectures 108 so that they are easy to deploy. We make use of YANG [RFC6020] 109 because of the time and effort spent to develop accurate and adequate 110 models for use by network devices. JSON is used as a serialization 111 for compactness and readability. 113 The YANG modules specified here are extensions of 114 [I-D.ietf-netmod-acl-model]. The extensions to this model allow for 115 a manufacturer to express classes of systems that a manufacturer 116 would find necessary for the proper function of the device. Two 117 modules are specified. The first module specifies a means for domain 118 names to be used in ACLs so that devices that have their controllers 119 in the cloud may be appropriately authorized with domain names, where 120 the mapping of those names to addresses may rapidly change. 122 The second module abstracts away IP addresses into certain classes 123 that are instantiated into actual IP addresses through local 124 processing. Through these classes, manufacturers can specify how the 125 device is designed to communicate, so that network elements can be 126 configured by local systems that have local topological knowledge. 127 That is, the deployment populates the classes that the manufacturer 128 specifies. 130 In this memo three means are defined to emit the MUD URL. One is a 131 DHCP option[RFC2131],[RFC3315] that the DHCP client uses to inform 132 the DHCP server. The DHCP server may take further actions, such as 133 retrieve the URL or otherwise pass it along to network management 134 system or controller. Finally, an LLDP frame is defined. 136 The other method defined is an X.509 constraint. The IEEE has 137 developed [IEEE8021AR] that provides a certificate-based approach to 138 communicate device characteristics, which itself relies on [RFC5280]. 139 The MUD URL extension is non-critical, as required by IEEE 802.1AR. 141 Because manufacturers do not know who will be using their devices, it 142 is important for functionality referenced in usage descriptions to be 143 relatively ubiquitous, and therefore, mature. Therefore, only a 144 limited subset of NETCONF-like content is permitted. 146 1.1. Terminology 148 MUD: manufacturer usage description. 150 MUD file: a file containing YANG-based JSON that describes a 151 recommended behavior. 153 MUD file server: a web server that hosts a MUD file. 155 MUD controller: the system that requests and receives the MUD file 156 from the MUD server. After it has processed a MUD file it may 157 direct changes to relevant network elements. 159 MUD URL: a URL that can be used by the MUD controller to receive the 160 MUD file. 162 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 163 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 164 document are to be interpreted as described in [RFC2119]. 166 2. The MUD Model and Semantic Meaning 168 A MUD file consists of JSON based on a YANG model. For purposes of 169 MUD, the elements that can be modified are access lists as augmented 170 by this model. The MUD file is limited to the serialization of a 171 small number of YANG schema, including the models specified in the 172 following documents: 174 o [I-D.ietf-netmod-acl-model] 176 o [RFC6991] 178 Publishers of MUD files MUST NOT include other elements except as 179 described in Section 13, and MUST only contain information relevant 180 to the device being described. Devices parsing MUD files MUST cease 181 processing if they find other elements. 183 This module is structured into three parts. The first container 184 holds information that is relevant to retrieval and validity of the 185 MUD file itself. The second container augments the access list to 186 indicate direction the ACL is to be applied. The final container 187 augments the matching container of the ACL model to add several 188 elements that are relevant to the MUD URL, or other otherwise 189 abstracted for use within a local environment. 191 module: ietf-mud 192 +--rw meta-information 193 +--rw last-update? yang:date-and-time 194 +--rw previous-mud-file? yang:uri 195 +--rw cache-validity? uint32 196 +--rw masa-server? inet:uri 197 +--rw is-supported? boolean 198 augment /acl:access-lists/acl:acl: 199 +--rw packet-direction? direction 200 augment /acl:access-lists/acl:acl 201 /acl:access-list-entries/acl:ace/acl:matches: 202 +--rw manufacturer? inet:host 203 +--rw same-manufacturer? empty 204 +--rw model? string 205 +--rw local-networks? empty 206 +--rw controller? inet:uri 207 +--rw direction-initiated? direction 209 3. Element Definitions 211 The following elements are defined. 213 3.1. last-update 215 This is a date-and-time value of the last time the MUD file was 216 updated. This is akin to a version number. Its form is taken from 217 [RFC6991] which, for those keeping score, turn was taken from 218 Section 5.6 of [RFC3339], which was taken from [ISO.8601.1988]. 220 3.2. previous-mud-file 222 This is a URL that should point to the previous MUD URL for auditing 223 purposes. Because it should not be necessary to resign a MUD file 224 when a new one is released, the archival location of a current MUD 225 file should be identified prior to its release. Note the signature 226 file MUST also be available. For example, if previous-mud-file is 227 set to "https://example.com/.mud/v1/xxx", the corresponding signature 228 would be found at "https://example.com/.mud/v1/xxx.p7s". 230 3.3. cache-validity 232 This uint32 is the period of time in hours that a network management 233 station MUST wait since its last retrieval before checking for an 234 update. It is RECOMMENDED that this value be no less than 24 and no 235 more than 1440 for any device that is supported. 237 3.4. masa-server 239 This optional element refers to the URL that should be used to 240 resolve the location any MASA service, as specified in 241 [I-D.ietf-anima-bootstrapping-keyinfra]. 243 3.5. is-supported 245 This boolean is an indication from the manufacturer to the network 246 administrator as to whether or not the device is supported. In this 247 context a device is said to be supported if the manufacturer might 248 issue an update to the device or if the manufacturer might update the 249 MUD file. 251 3.6. packet-direction 253 [I-D.ietf-netmod-acl-model] describes access-lists but does not 254 attempt to indicate where they are applied as that is handled 255 elsewhere in a configuration. However, in this case, a MUD file must 256 be explicit in describing the communcation pattern of a device, and 257 that includes indicating what is to be permitted or denied in either 258 direction of communication. This element takes a single value of 259 either "to-device" or "from-device", based on a typedef "direction". 261 3.7. manufacturer 263 This element consists of a hostname that would be matched against the 264 authority section of another device's MUD URL. 266 3.8. same-manufacturer 268 This is an equivalent for when the manufacturer element is used to 269 indicate the authority that is found in another device's MUD URL 270 matches that of the authority found in this device's MUD URL. 272 3.9. model 274 This string matches the one and only segment following the authority 275 section of the MUD URL. It refers to a model that is unique within 276 the context of the authority. It may also include product version 277 information. Thus how this field is constructed is entirely a local 278 matter for the manufacturer. 280 3.10. local-networks 282 This null-valued element expands to include local networks. Its 283 default expansion is that packets must not traverse toward a default 284 route that is received from the router. 286 3.11. controller 288 This URI specifies a value that a controller will register with the 289 network management station. The element then is expanded to the set 290 of hosts that are so registered. 292 In addition, some meta information is defined in order to determine 293 when a usage description should be refreshed. 295 3.12. direction-initiated 297 When applied this matches packets when the flow was initiated in the 298 corresponding direction. [RFC6092] provides guidance for IPv6 299 guidance best practices. While that document is scoped specifically 300 to IPv6, its contents are applicable for IPv4 as well. When this 301 flag is set, and the system has no reason to believe a flow has been 302 initiated it MUST drop the packet. This match SHOULD be applied with 303 specific transport parameters, such as protocol. 305 4. Processing of the MUD file 307 To keep things relatively simple in addition to whatever definitions 308 exist, we also apply two additional default behaviors: 310 o Anything not explicitly permitted is denied. 312 o Local DNS, DHCP, and NTP are, by default, permitted to and from 313 the device. 315 5. What does a MUD URL look like? 317 To begin with, MUD takes full advantage of both the https: scheme and 318 the use of .well-known. HTTPS is important in this case because a 319 man in the middle attack could otherwise harm the operation of a 320 class of devices. .well-known is used because we wish to add 321 additional structure to the URL. And so the URL appears as follows: 323 mud-url = "https://" authority "/.well-known/mud/" mud-rev 324 "/" model ( "?" extras ) 325 ; authority is from RFC3986 326 mud-rev = "v1" 327 model = segment ; from RFC3986 328 extras = query ; from RFC3986 330 mud-rev signifies the version of the manufacturer usage description 331 file. This memo specifies "v1" of that file. Later versions may 332 permit additional schemas or modify the format. 334 "model" represents a device model as the manufacturer wishes to 335 represent it. It could be a brand name or something more specific. 336 It also may provide a means to indicate what version the product is. 337 Specifically if it has been updated in the field, this is the place 338 where evidence of that update would appear. The field should be 339 changed when the intended communication patterns of a device change. 340 While from a controller standpoint, only comparison and matching 341 operations are safe, it is envisioned that updates will require some 342 administrative review. Processing of this URL occurs as specified in 343 [RFC2818] and [RFC3986]. 345 6. The MUD YANG Model 347 file "ietf-mud@2016-07-20.yang"; 349 module ietf-mud { 350 yang-version 1.1; 351 namespace "urn:ietf:params:xml:ns:yang:ietf-mud"; 352 prefix "ietf-mud"; 354 import ietf-access-control-list { 355 prefix "acl"; 356 } 358 import ietf-yang-types { 359 prefix "yang"; 360 } 362 import ietf-inet-types { 363 prefix "inet"; 364 } 366 organization 367 "IETF OPSAWG (Ops Area) Working Group"; 369 contact 370 "WG Web: http://tools.ietf.org/wg/opsawg/ 371 WG List: opsawg@ietf.org 372 WG Chair: Warren Kumari 373 warren@kumari.net 374 WG Chair: Zhou Tianran 375 zhoutianran@huawei.com 376 Editor: Eliot Lear 377 lear@cisco.com 378 Editor: Ralph Droms 379 rdroms@cisco.com 380 "; 382 description 383 "This YANG module defines a component that augments the 384 IETF description of an access list. This specific module 385 focuses on additional filters that include local, model, 386 and same-manufacturer. 388 Copyright (c) 2016 IETF Trust and the persons identified as 389 the document authors. All rights reserved. 390 Redistribution and use in source and binary forms, with or 391 without modification, is permitted pursuant to, and subject 392 to the license terms contained in, the Simplified BSD 393 License set forth in Section 4.c of the IETF Trust's Legal 394 Provisions Relating to IETF Documents 395 (http://trustee.ietf.org/license-info). 396 This version of this YANG module is part of RFC XXXX; see 397 the RFC itself for full legal notices."; 399 revision "2016-07-20" { 400 description "Base version of MUD extensions to ACL model"; 401 reference "RFC XXXX: Manufacturer Usage Description Specification"; 402 } 404 typedef direction { 405 type enumeration { 406 enum to-device { 407 description "packets or flows destined to the target device"; 408 } 409 enum from-device { 410 description "packets or flows destined from 411 the target device"; 412 } 413 } 414 description "Which way are we talking about?"; 415 } 417 container meta-information { 419 description "Information about when support end(ed), and 420 when to refresh"; 422 leaf last-update { 423 type yang:date-and-time; 424 description "This is intended to be the time and date that 425 the MUD file was generated."; 426 } 428 leaf previous-mud-file { 429 type inet:uri; 430 description "Use to find the previous MUD file location 431 for auditing purposes."; 432 } 434 leaf cache-validity { 435 type uint32; 436 description "The information retrieved from the MUD server is 437 valid for these many hours, after which it should 438 be refreshed."; 439 } 441 leaf masa-server { 442 type inet:uri; 443 description "The URI of the MASA server that network 444 elements should forward requests to for this device."; 445 } 447 leaf is-supported { 448 type boolean; 449 description "The element is currently supported 450 by the manufacturer."; 451 } 452 } 454 augment "/acl:access-lists/acl:acl" { 455 description "add inbound or outbound. Normally access lists 456 are applied in an inbound or outbound direction 457 separately from their definition. This is not 458 possible with MUD."; 459 leaf packet-direction 460 { 461 type direction; 462 description "inbound or outbound ACL."; 463 } 464 } 466 augment "/acl:access-lists/acl:acl/" + 467 "acl:access-list-entries/acl:ace/" + 468 "acl:matches" { 469 description "adding abstractions to avoid need of IP addresses"; 471 leaf manufacturer { 472 type inet:host; 473 description "authority component of the manufacturer URI"; 474 } 476 leaf same-manufacturer { 477 type empty; 478 description "expand to ACEs for each device 479 with the same origin"; 480 } 482 leaf model { 483 type string; 484 description "specific model (including version) for a 485 given manufacturer"; 486 } 488 leaf local-networks { 489 type empty; 490 description "this string is used to indicate networks 491 considered local in a given environment."; 492 } 493 leaf controller { 494 type inet:uri; 495 description "expands to one or more controllers for a 496 given service that is codified by inet:uri."; 497 } 498 leaf direction-initiated { 499 type direction; 500 description "which direction a flow was initiated"; 501 } 502 } 503 } 505 507 7. The Domain Name Extension to the ACL Model 509 This module specifies an extension to IETF-ACL model such that domain 510 names may be referenced by augmenting the "matches" element. 511 Different implementations may deploy differing methods to maintain 512 the mapping between IP address and domain name, if indeed any are 513 needed. However, the intent is that resources that are referred to 514 using a name should be authorized (or not) within an access list. 516 The structure of the change is as follows: 518 augment 519 /acl:access-lists/acl:acl/acl:access-list-entries 520 /acl:ace/acl:matches/acl:ace-type/acl:ace-ip: 521 +--rw src-dnsname? inet:host 522 +--rw dst-dnsname? inet:host 524 The choice of this particular point in the access-list model is based 525 on the assumption that we are in some way referring to IP-related 526 resources, as that is what the DNS returns. A domain name in our 527 context is defined in [RFC6991]. 529 The following elements are defined. 531 7.1. source-dnsname 533 The argument corresponds to a domain name of a source as specified by 534 inet:host. Depending on how the model is used, it may or may not be 535 resolved, as required by the implementation and circumstances. 537 7.2. destination-dnsname 539 The argument corresponds to a domain name of a destination as 540 specified by inet:host. Depending on how the model is used, it may 541 or may not be resolved, as required by the implementation and 542 circumstances. 544 7.3. The ietf-acldns Model 546 file "ietf-acldns@2007-07020.yang"; 548 module ietf-acldns { 549 yang-version 1.1; 550 namespace "urn:ietf:params:xml:ns:yang:ietf-acldns"; 551 prefix "ietf-acldns"; 553 import ietf-access-control-list { 554 prefix "acl"; 555 } 557 import ietf-inet-types { 558 prefix "inet"; 559 } 561 organization 562 "IETF OPSAWG (Ops Area) Working Group"; 564 contact 565 "WG Web: http://tools.ietf.org/wg/opsawg/ 566 WG List: opsawg@ietf.org 567 WG Chair: Warren Kumari 568 warren@kumari.net 569 WG Chair: Zhou Tianran 570 zhoutianran@huawei.com 571 Editor: Eliot Lear 572 lear@cisco.com 573 Editor: Ralph Droms 574 rdroms@cisco.com 575 "; 577 description 578 "This YANG module defines a component that augments the 579 IETF description of an access list to allow dns names 580 as matching criteria."; 582 revision "2016-07-20" { 583 description "Base version of dnsname extension of ACL model"; 584 reference "RFC XXXX: Manufacturer Usage Description Specification"; 585 } 587 augment "/acl:access-lists/acl:acl/" + 588 "acl:access-list-entries/acl:ace/" + 589 "acl:matches/acl:ace-type/acl:ace-ip" { 590 description "adding domain names to matching"; 592 leaf src-dnsname { 593 type inet:host; 594 description "domain name to be matched against"; 595 } 596 leaf dst-dnsname { 597 type inet:host; 598 description "domain name to be matched against"; 599 } 600 } 601 } 603 605 8. MUD File Example 607 This example contains two access lists that are intended to provide 608 outbound access to a cloud service on TCP port 443. 610 { 611 "ietf-mud:support-information": { 612 "last-update": "2016-05-18T20:00:50Z", 613 "cache-validity": 1440 614 }, 615 "ietf-access-control-list:access-lists": { 616 "acl": [ { 617 "acl-name": "inbound-stuff", 618 "acl-type" : "ipv4-acl", 619 "ietf-mud:direction" : "to-device", 620 "access-list-entries": { 621 "ace": [ 622 { 623 "rule-name": "access-cloud", 624 "matches": { 625 "ietf-acldns:src-dnsname": 626 "lighting-system.example.com", 627 "protocol" : 6, 628 "source-port-range" : { 629 "lower-port" : 443, 630 "upper-port" : 443 631 } 632 }, 633 "actions" : { 634 "permit" : [null] 635 } 636 } 637 ] 638 } 639 }, 640 { 641 "acl-name": "outbound-stuff", 642 "acl-type" : "ipv4-acl", 643 "ietf-mud:direction" : "from-device", 644 "access-list-entries": { 645 "ace": [ 646 { 647 "rule-name": "access-cloud", 648 "matches": { 649 "ietf-acldns:dst-dnsname": 650 "lighting-system.example.com", 651 "protocol" : 6, 652 "destination-port-range" : { 653 "lower-port" : 443, 654 "upper-port" : 443 655 } 656 }, 657 "actions" : { 658 "permit" : [null] 659 } 660 } 661 ] 662 } 663 } 664 ] 665 } 666 } 668 9. The MUD URL DHCP Option 670 The IPv4 MUD URL client option has the following format: 672 +------+-----+------------------------------ 673 | code | len | MUD URL 674 +------+-----+------------------------------ 676 Code OPTION_MUD_URL_V4 (TBD) is assigned by IANA. len is a single 677 octet that indicates the length of the URL in octets. MUD URL is a 678 URL. The length of a MUD URL does not exceed 255 bytes. 680 The IPv6 MUD URL client option has the following format: 682 0 1 2 3 683 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 684 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 685 | OPTION_MUD_URL_V6 | option-length | 686 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 687 | MUD URL | 688 | ... | 689 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 691 OPTION_MUD_URL_V6 (TBD; assigned by IANA). 693 option-length contains the length of the URL in octets. The length 694 MUST NOT exceed 255 octets. 696 The intent of this option is to provide both a new device classifier 697 to the network as well as some recommended configuration to the 698 routers that implement policy. However, it is entirely the purview 699 of the network system as managed by the network administrator to 700 decide what to do with this information. The key function of this 701 option is simply to identify the type of device to the network in a 702 structured way such that the policy can be easily found with existing 703 toolsets. 705 9.1. Client Behavior 707 A DHCP client MAY emit either a DHCPv4 or DHCPv6 option or both. 708 These options singletons, as specified in [RFC7227]. Because clients 709 are intended to have at most one MUD URL associated with them, they 710 may emit at most one MUD URL option via DHCPv4 and one MUD URL option 711 via DHCPv6. In the case where both v4 and v6 DHCP options are 712 emitted, the same URL MUST be used. 714 Clients SHOULD log or otherwise report improper acknowledgments from 715 servers, but they MUST NOT modify their MUD URL configuration based 716 on a server's response. The server's response is only an 717 acknowledgment that the server has processed the option, and promises 718 no specific network behavior to the client. In particular, it may 719 not be possible for the server to retrieve the file associated with 720 the MUD URL, or the local network administration may not wish to use 721 the usage description. Neither of these situations should be 722 considered in any way exceptional. 724 9.2. Server Behavior 726 A DHCP server may ignore these options or take action based on 727 receipt of these options. For purposes of debugging, if a server 728 successfully parses the option and the URL, it MUST return the option 729 with the same URL as an acknowledgment. Even in this circumstance, 730 no specific network behavior is guaranteed. When a server consumes 731 this option, it will either forward the URL and relevant client 732 information to a network management system (such as the giaddr), or 733 it will retrieve the usage description by resolving the URL. 735 DHCP servers may implement MUD functionality themselves or they may 736 pass along appropriate information to a network management system or 737 controller. A DHCP server that does process the MUD URL MUST adhere 738 to the process specified in [RFC2818] and [RFC5280] to validate the 739 TLS certificate of the web server hosting the MUD file. Those 740 servers will retrieve the file, process it, create and install the 741 necessary configuration on the relevant network element. Servers 742 SHOULD monitor the gateway for state changes on a given interface. A 743 DHCP server that does not provide MUD functionality and has forwarded 744 a MUD URL to a network management system MUST notify the network 745 management of any corresponding change to the DHCP state of the 746 client (such as expiration or explicit release of a network address 747 lease). 749 9.3. Relay Requirements 751 There are no additional requirements for relays. 753 10. The Manufacturer Usage Description (MUD) URL X.509 Extension 755 [RFC7299] provides a procedure and means to specify extensions to 756 X.509 certificates. The MUD URL is a non-critical Certificate 757 extension that points to an on-line Manufacturer Usage Description 758 concerning the certificate subject. This extension contains a single 759 Uniform Resource Identifier (URI). Internationalized Resource 760 Identifiers must be represented as URI's in the way described in RFC 761 5280, section 7.4. 763 The choice of id-pe is based on guidance found in Section 4.2.2 of 764 [RFC5280]: 766 These extensions may be used to direct applications to on-line 767 information about the issuer or the subject. 769 The MUD URL is precisely that: online information about the 770 particular subject. 772 The new extension is identified as follows: 774 - The MUD URI extension id-pe-mud-url OBJECT IDENTIFER ::= { id-pe 775 TBD } 777 The extension returns a single value: 779 mudURLSyntax ::= IA5String - for use with MUD architecture. 781 The semantics of the URI are defined Section 5. 783 11. The Manufacturer Usage Description LLDP extension 785 The IEEE802.1AB Link Layer Discovery Protocol (LLDP) [IEEE8021AB] is 786 a one hop vendor-neutral link layer protocols used by end hosts 787 network devices for advertising their identity, capabilities, and 788 neighbors on an IEEE 802 local area network. Its Type-Length-Value 789 (TLV) design allows for 'vendor-specific' extensions to be defined. 790 IANA has a registered IEEE 802 organizationally unique identifier 791 (OUI) defined as documented in [RFC7042]. The MUD LLDP extension 792 uses a subtype defined in this document to carry the MUD URL. 794 The LLDP vendor specific frame has the following format: 796 +--------+--------+----------+---------+-------------- 797 |TLV Type| len | OUI |subtype | MUD URL 798 | =127 | |= 00 00 5E| = 1 | 799 |(7 bits)|(9 bits)|(3 octets)|(1 octet)|(1-256 octets) 800 +--------+--------+----------+---------+-------------- 802 where: 804 o TLV Type = 127 indicates a vendor-specific TLV 806 o len - indicates the TLV string length 808 o OUI = 00 00 5E is the organizationally unique identifier of IANA 809 o subtype = 1 (to be assigned by IANA for the MUD URL) 811 o MUD URL - the length MUST NOT exceed 256 octets (consistent with 812 the DHCP option defined in Section 9) 814 The intent of this extension is to provide both a new device 815 classifier to the network as well as some recommended configuration 816 to the routers that implement policy. However, it is entirely the 817 purview of the network system as managed by the network administrator 818 to decide what to do with this information. The key function of this 819 extension is simply to identify the type of device to the network in 820 a structured way such that the policy can be easily found with 821 existing toolsets. 823 Hosts, routers, or other network devices that implement this option 824 are intended to have at most one MUD URL associated with them, so 825 they may transmit at most one MUD URL value. 827 Hosts, routers, or other network devices that implement this option 828 may ignore these options or take action based on receipt of these 829 options. For example they may fill in information in the respective 830 extensions of the LLDP Management Information Base (LLDP MIB). LLDP 831 operates in a one-way direction. LLDPDUs are not exchanged as 832 information requests by one device and response sent by another 833 device. The other devices do not acknowledge LLDP information 834 received from a device. No specific network behavior is guaranteed. 835 When a device consumes this extension, it may either forward the URL 836 and relevant remote device information to a network management 837 system, or it will retrieve the usage description by resolving the 838 URL. 840 12. Creating and Processing of Signed MUD Files 842 Because MUD files contain information that may be used to configure 843 network access lists, they are sensitive. To insure that they have 844 not been tampered with, it is important that they be signed. We make 845 use of DER-encoded Cryptographic Message Syntax (CMS) [RFC5652] for 846 this purpose. 848 12.1. Creating a MUD file signature 850 A MUD file MUST be signed using CMS as an opaque binary object. In 851 order to make successful verification more likely, intermediate 852 certificates SHOULD be included. If the device that is being 853 described supports IEEE 802.1AR, its manufacturer certificate and the 854 certificate in the MUD file MUST share a common trust anchor in order 855 to insure that manufacturer of the device is also the provider of the 856 MUD file. The signature is stored at the same location as the MUD 857 URL but with the suffix of ".p7s". Signatures are transferred using 858 content-type "Application/pkcs7-signature". 860 For example: 862 % openssl cms -sign -signer mancertfile -inkey mankey \ 863 -in mudfile -binary -outform DER - \ 864 -certfile intermediatecert -out mudfile.p7s 866 Note: A MUD file may need to be resigned if the signature expires. 868 12.2. Verifying a MUD file signature 870 Prior to retrieving a MUD file the MUD controller SHOULD retrieve the 871 MUD signature file using the MUD URL with a suffix of ".p7s". For 872 example, if the MUD URL is "https://example.com/.well-known/v1/ 873 modela", the MUD signature URL will be "https://example.com/.well- 874 known/v1/modela.p7s". 876 Upon retrieving a MUD file, a MUD controller MUST validate the 877 signature of the file before continuing with further processing. A 878 MUD controller SHOULD produce an error and it MUST cease all 879 processing of that file if the signature cannot be validated. If the 880 MUD controller has received the MUD URL via IEEE 802.1AR containing 881 an IDevID (a manufacturer certificate), it MUST further confirm that 882 the manufacturer certificate and that of the MUD file share a common 883 trust anchor. 885 For Example: 887 % openssl cms -verify -in mudfile.p7s -inform DER -content mudfile 889 Note the additional step of verifying the common trust root. 891 13. Extensibility 893 One of our design goals is to see that MUD files are able to be 894 understood by as broad a cross-section of systems as is possible. 895 Coupled with the fact that we have also chosen to leverage existing 896 mechanisms, we are left with no ability to negotiate extensions and a 897 limited desire for those extensions in any event. A such, a two-tier 898 extensibility framework is employed, as follows: 900 1. At a coarse grain, a protocol version is included in a MUD URL. 901 This memo specifies MUD version 1. Any and all changes are 902 entertained when this version is bumped. Transition approaches 903 between versions would be a matter for discussion in future 904 versions. 906 2. At a finer grain, only extensions that would not incur additional 907 risk to the device are permitted. Specifically, augmenting of 908 the meta-information container is permitted with the 909 understanding that such additions may be ignored. In addition, 910 augmentation of the ACL model is permitted so long as it remains 911 safe for a given ACE to be ignored by the MUD Controller or the 912 network elements it configures. Most specifically, is is not 913 permitted to include as an augmentation that modifies "deny" 914 behavior without bumping the version. Furthermore, 915 implementations that are not able to parse a component of the ACE 916 array MUST ignore the entire array entry (e.g., not the entire 917 array) and MAY ignore the entire MUD file. 919 14. Security Considerations 921 Based on the means a URL is procured, a device may be able to lie 922 about what it is, thus gaining additional network access. There are 923 several means to limit risk in this case. The most obvious is to 924 only believe devices that make use of certificate-based 925 authentication such as IEEE 802.1AR certificates. When those 926 certificates are not present, devices claiming to be of a certain 927 manufacturer SHOULD NOT be included in that manufacturer grouping 928 without additional validation of some form. This will occur when it 929 makes use of primitives such as "manufacturer" for the purpose of 930 accessing devices of a particular type. 932 Network management systems SHOULD NOT deploy a usage description for 933 a device with the same MAC address that has indicated a change of 934 authority without some additional validation (such as review of the 935 class). New devices that present some form of unauthenticated MUD 936 URL SHOULD be validated by some external means when they would be 937 otherwise be given increased network access. 939 It may be possible for a rogue manufacturer to inappropriately 940 exercise the MUD file parser, in order to exploit a vulnerability. 941 There are three recommended approaches to address this threat. The 942 first is to validate the signature of the MUD file. The second is to 943 have a system do a primary scan of the file to ensure that it is both 944 parseable and believable at some level. MUD files will likely be 945 relatively small, to start with. The number of ACEs used by any 946 given device should be relatively small as well. Second, it may be 947 useful to limit retrieval of MUD URLs to only those sites that are 948 known to have decent web reputations. 950 Use of a URL necessitates the use of domain names. If a domain name 951 changes ownership, the new owner of that domain may be able to 952 provide MUD files that MUD controllers would consider valid. There 953 are a few approaches that can mitigate this attack. First, MUD file 954 servers SHOULD cache certificates used by the MUD file server. When 955 a new certificate is retrieved for whatever reason, the MUD 956 controller should check to see if ownership of the domain has 957 changed. A fair programmatic approximation of this is when the name 958 servers for the domain have changed. If the actual MUD file has 959 changed, the controller MAY check the WHOIS database to see if 960 registration ownership of a domain has changed. If a change has 961 occured, or if for some reason it is not possible to determine 962 whether ownership has changed, further review may be warranted. 963 Note, this remediation does not take into account the case of a 964 device that was produced long ago and only recently fielded, or the 965 case where a new MUD controller has been installed. 967 15. IANA Considerations 969 15.1. DHCPv4 and DHCPv6 Options 971 IANA is requested to allocated the DHCPv4 and v6 options as specified 972 in Section 9. 974 15.2. PKIX Extensions 976 The IANA is requested to assign a value for id-pe-mud-uri in the "SMI 977 Security for PKIX Certificate Extension" Registry. Its use is 978 specified in Section 10. 980 15.3. Well Known URI Suffix 982 The IANA is requested to register the URL suffix of "mud" as follows: 984 o URI Suffix: "mud" o Specification documents: this document o 985 Related information: n/a 987 15.4. MIME Media-type Registration for MUD files 989 The following media-type is defined for transfer of MUD file: 991 o Type name: application 992 o Subtype name: mud+json 993 o Required parameters: n/a 994 o Optional parameters: n/a 995 o Encoding considerations: 8bit; application/mud+json values 996 are represented as a JSON object; UTF-8 encoding SHOULD be 997 employed. 998 o Security considerations: See {{secon}} of this document. 999 o Interoperability considerations: n/a 1000 o Published specification: this document 1001 o Applications that use this media type: MUD controllers as 1002 specified by this document. 1003 o Fragment identifier considerations: n/a 1004 o Additional information: 1006 Magic number(s): n/a 1007 File extension(s): n/a 1008 Macintosh file type code(s): n/a 1010 o Person & email address to contact for further information: 1011 Eliot Lear , Ralph Droms 1012 o Intended usage: COMMON 1013 o Restrictions on usage: none 1015 o Author: Eliot Lear , Ralph Droms 1016 o Change controller: IESG 1017 o Provisional registration? (standards tree only): No. 1019 15.5. LLDP IANA TLV Subtype Registry 1021 IANA is requested to create a new registry for IANA Link Layer 1022 Discovery Protocol (LLDP) TLV subtype values. The recommended policy 1023 for this registry is Expert Review. The maximum number of entries in 1024 the registry is 256. 1026 IANA is required to populate the initial registry with the value: 1028 LLDP subtype value = 1 1030 Description = the Manufacturer Usage Description (MUD) Uniform 1031 Resource Locator (URL) 1033 Reference = < this document > 1035 16. Acknowledgments 1037 The authors would like to thank Einar Nilsen-Nygaard, Bernie Volz, 1038 Tom Gindin, Brian Weis, Sandeep Kumar, Thorsten Dahm, John Bashinski, 1039 Steve Rich, Jim Bieda, and Dan Wing for their valuable advice and 1040 reviews. The remaining errors in this work are entirely the 1041 responsibility of the author. 1043 17. References 1045 17.1. Normative References 1047 [I-D.ietf-anima-bootstrapping-keyinfra] 1048 Pritikin, M., Richardson, M., Behringer, M., and S. 1049 Bjarnason, "Bootstrapping Remote Secure Key 1050 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 1051 keyinfra-03 (work in progress), June 2016. 1053 [I-D.ietf-netmod-acl-model] 1054 Bogdanovic, D., Koushik, K., Huang, L., and D. Blair, 1055 "Network Access Control List (ACL) YANG Data Model", 1056 draft-ietf-netmod-acl-model-08 (work in progress), July 1057 2016. 1059 [IEEE8021AB] 1060 Institute for Electrical and Electronics Engineers, "IEEE 1061 Standard for Local and Metropolitan Area Networks-- 1062 Station and Media Access Control Connectivity Discovery", 1063 n.d.. 1065 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1066 Requirement Levels", BCP 14, RFC 2119, 1067 DOI 10.17487/RFC2119, March 1997, 1068 . 1070 [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", 1071 RFC 2131, DOI 10.17487/RFC2131, March 1997, 1072 . 1074 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1075 DOI 10.17487/RFC2818, May 2000, 1076 . 1078 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 1079 C., and M. Carney, "Dynamic Host Configuration Protocol 1080 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 1081 2003, . 1083 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1084 Resource Identifier (URI): Generic Syntax", STD 66, 1085 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1086 . 1088 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1089 Housley, R., and W. Polk, "Internet X.509 Public Key 1090 Infrastructure Certificate and Certificate Revocation List 1091 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1092 . 1094 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1095 RFC 5652, DOI 10.17487/RFC5652, September 2009, 1096 . 1098 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1099 the Network Configuration Protocol (NETCONF)", RFC 6020, 1100 DOI 10.17487/RFC6020, October 2010, 1101 . 1103 [RFC6092] Woodyatt, J., Ed., "Recommended Simple Security 1104 Capabilities in Customer Premises Equipment (CPE) for 1105 Providing Residential IPv6 Internet Service", RFC 6092, 1106 DOI 10.17487/RFC6092, January 2011, 1107 . 1109 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1110 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1111 . 1113 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 1114 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 1115 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 1116 . 1118 [RFC7299] Housley, R., "Object Identifier Registry for the PKIX 1119 Working Group", RFC 7299, DOI 10.17487/RFC7299, July 2014, 1120 . 1122 17.2. Informative References 1124 [I-D.lear-mud-framework] 1125 Lear, E., "Manufacturer Usage Description Framework", 1126 draft-lear-mud-framework-00 (work in progress), January 1127 2016. 1129 [IEEE8021AR] 1130 Institute for Electrical and Electronics Engineers, 1131 "Secure Device Identity", 1998. 1133 [ISO.8601.1988] 1134 International Organization for Standardization, "Data 1135 elements and interchange formats - Information interchange 1136 - Representation of dates and times", ISO Standard 8601, 1137 June 1988. 1139 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1140 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1141 . 1143 [RFC7042] Eastlake 3rd, D. and J. Abley, "IANA Considerations and 1144 IETF Protocol and Documentation Usage for IEEE 802 1145 Parameters", BCP 141, RFC 7042, DOI 10.17487/RFC7042, 1146 October 2013, . 1148 Appendix A. Changes from Earlier Versions 1150 RFC Editor to remove this section prior to publication. 1152 Draft -03 to -04: * add LLDP extension. * add Dan Romascanu as co- 1153 author. 1155 Draft -02 to -03: * incorporate domain name model. * discuss 1156 extensibility. * leave placeholder for LLDP TLV. 1158 Draft -01 to -02: 1160 o XML->JSON 1162 o Remove device versioning information from URL 1164 o Add PKIX and DHCP options 1166 o Add Content-type information 1168 o Clean up IANA considerations to match registration templates 1170 o Ralph Droms carried over as author from DHCP option. 1172 o Signing information 1174 o Expanded Security Considerations 1176 o Add directionality for both packets and flows. 1178 o add previous-mud-file 1180 Draft -00 to -01: 1182 o Add MASA server element 1184 Authors' Addresses 1186 Eliot Lear 1187 Cisco Systems 1188 Richtistrasse 7 1189 Wallisellen CH-8304 1190 Switzerland 1192 Phone: +41 44 878 9200 1193 Email: lear@cisco.com 1195 Ralph Droms 1196 Cisco Systems 1197 55 Cambridge Parkway 1198 Cambridge 1057 1199 United States 1201 Phone: +1 617 621 1904 1202 Email: rdroms@cisco.com 1204 Dan Romascanu 1205 Avaya 1206 26, HaRokhmim Str., Bldg. D 1207 Holon 5885849 1208 Israel 1210 Phone: +972-3-645-8414 1211 Email: dromasca@avaya.com