idnits 2.17.1 draft-ietf-opsawg-mud-25.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 15, 2018) is 2142 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) == Missing Reference: 'RFCXXXX' is mentioned on line 1965, but not defined == Unused Reference: 'RFC5911' is defined on line 2122, but no explicit reference was found in the text == Unused Reference: 'RFC5912' is defined on line 2127, but no explicit reference was found in the text == Outdated reference: A later version (-21) exists of draft-ietf-netmod-acl-model-19 -- 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 5911 ** Downref: Normative reference to an Informational RFC: RFC 5912 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7042 (Obsoleted by RFC 9542) Summary: 6 errors (**), 0 flaws (~~), 5 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 Cisco Systems 4 Intended status: Standards Track R. Droms 5 Expires: December 17, 2018 Google 6 D. Romascanu 7 June 15, 2018 9 Manufacturer Usage Description Specification 10 draft-ietf-opsawg-mud-25 12 Abstract 14 This memo specifies a component-based architecture for manufacturer 15 usage descriptions (MUD). The goal of MUD is to provide a means for 16 end devices to signal to the network what sort of access and network 17 functionality they require to properly function. The initial focus 18 is on access control. Later work can delve into other aspects. 20 This memo specifies two YANG modules, IPv4 and IPv6 DHCP options, an 21 LLDP TLV, a URL, an X.509 certificate extension and a means to sign 22 and verify the descriptions. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on December 17, 2018. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. What MUD Doesn't Do . . . . . . . . . . . . . . . . . . . 5 60 1.2. A Simple Example . . . . . . . . . . . . . . . . . . . . 5 61 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 62 1.4. Determining Intended Use . . . . . . . . . . . . . . . . 6 63 1.5. Finding A Policy: The MUD URL . . . . . . . . . . . . . . 6 64 1.6. Processing of the MUD URL . . . . . . . . . . . . . . . . 7 65 1.7. Types of Policies . . . . . . . . . . . . . . . . . . . . 8 66 1.8. The Manufacturer Usage Description Architecture . . . . . 10 67 1.9. Order of operations . . . . . . . . . . . . . . . . . . . 11 68 2. The MUD Model and Semantic Meaning . . . . . . . . . . . . . 12 69 2.1. The IETF-MUD YANG Module . . . . . . . . . . . . . . . . 13 70 3. MUD model definitions for the root mud container . . . . . . 14 71 3.1. mud-version . . . . . . . . . . . . . . . . . . . . . . . 14 72 3.2. mud-url . . . . . . . . . . . . . . . . . . . . . . . . . 15 73 3.3. to-device-policy and from-device-policy containers . . . 15 74 3.4. last-update . . . . . . . . . . . . . . . . . . . . . . . 15 75 3.5. cache-validity . . . . . . . . . . . . . . . . . . . . . 15 76 3.6. is-supported . . . . . . . . . . . . . . . . . . . . . . 15 77 3.7. systeminfo . . . . . . . . . . . . . . . . . . . . . . . 15 78 3.8. mfg-name, software-rev, model-name firmware-rev . . . . . 16 79 3.9. extensions . . . . . . . . . . . . . . . . . . . . . . . 16 80 4. Augmentation to the ACL Model . . . . . . . . . . . . . . . . 16 81 4.1. manufacturer . . . . . . . . . . . . . . . . . . . . . . 16 82 4.2. same-manufacturer . . . . . . . . . . . . . . . . . . . . 16 83 4.3. documentation . . . . . . . . . . . . . . . . . . . . . . 17 84 4.4. model . . . . . . . . . . . . . . . . . . . . . . . . . . 17 85 4.5. local-networks . . . . . . . . . . . . . . . . . . . . . 17 86 4.6. controller . . . . . . . . . . . . . . . . . . . . . . . 17 87 4.7. my-controller . . . . . . . . . . . . . . . . . . . . . . 18 88 4.8. direction-initiated . . . . . . . . . . . . . . . . . . . 18 89 5. Processing of the MUD file . . . . . . . . . . . . . . . . . 18 90 6. What does a MUD URL look like? . . . . . . . . . . . . . . . 18 91 7. The MUD YANG Model . . . . . . . . . . . . . . . . . . . . . 19 92 8. The Domain Name Extension to the ACL Model . . . . . . . . . 25 93 8.1. src-dnsname . . . . . . . . . . . . . . . . . . . . . . . 26 94 8.2. dst-dnsname . . . . . . . . . . . . . . . . . . . . . . . 26 95 8.3. The ietf-acldns Model . . . . . . . . . . . . . . . . . . 26 96 9. MUD File Example . . . . . . . . . . . . . . . . . . . . . . 28 97 10. The MUD URL DHCP Option . . . . . . . . . . . . . . . . . . . 30 98 10.1. Client Behavior . . . . . . . . . . . . . . . . . . . . 31 99 10.2. Server Behavior . . . . . . . . . . . . . . . . . . . . 31 100 10.3. Relay Requirements . . . . . . . . . . . . . . . . . . . 32 101 11. The Manufacturer Usage Description (MUD) URL X.509 Extension 32 102 12. The Manufacturer Usage Description LLDP extension . . . . . . 34 103 13. Creating and Processing of Signed MUD Files . . . . . . . . . 35 104 13.1. Creating a MUD file signature . . . . . . . . . . . . . 36 105 13.2. Verifying a MUD file signature . . . . . . . . . . . . . 36 106 14. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 37 107 15. Deployment Considerations . . . . . . . . . . . . . . . . . . 37 108 16. Security Considerations . . . . . . . . . . . . . . . . . . . 38 109 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 110 17.1. YANG Module Registrations . . . . . . . . . . . . . . . 41 111 17.2. DHCPv4 and DHCPv6 Options . . . . . . . . . . . . . . . 41 112 17.3. PKIX Extensions . . . . . . . . . . . . . . . . . . . . 41 113 17.4. MIME Media-type Registration for MUD files . . . . . . . 42 114 17.5. LLDP IANA TLV Subtype Registry . . . . . . . . . . . . . 42 115 17.6. The MUD Well Known Universal Resource Name (URNs) . . . 43 116 17.7. Extensions Registry . . . . . . . . . . . . . . . . . . 43 117 18. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 118 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 119 19.1. Normative References . . . . . . . . . . . . . . . . . . 44 120 19.2. Informative References . . . . . . . . . . . . . . . . . 47 121 Appendix A. Changes from Earlier Versions . . . . . . . . . . . 49 122 Appendix B. Default MUD nodes . . . . . . . . . . . . . . . . . 52 123 Appendix C. A Sample Extension: DETNET-indicator . . . . . . . . 57 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 60 126 1. Introduction 128 The Internet has largely been constructed for general purpose 129 computers, those devices that may be used for a purpose that is 130 specified by those who own the device. [RFC1984] presumed that an 131 end device would be most capable of protecting itself. This made 132 sense when the typical device was a workstation or a mainframe, and 133 it continues to make sense for general purpose computing devices 134 today, including laptops, smart phones, and tablets. 136 [RFC7452] discusses design patterns for, and poses questions about, 137 smart objects. Let us then posit a group of objects that are 138 specifically not intended to be used for general purpose computing 139 tasks. These devices, which this memo refers to as Things, have a 140 specific purpose. By definition, therefore, all other uses are not 141 intended. If a small number of communication patterns follows from 142 those small number of uses, the combination of these two statements 143 can be restated as a manufacturer usage description (MUD) that can be 144 applied at various points within a network. MUD primarily addresses 145 threats to the device rather than the device as a threat. In some 146 circumstances, however, MUD may offer some protection in the latter 147 case, depending on the MUD-URL is communicated, and how devices and 148 their communications are authenticated. 150 We use the notion of "manufacturer" loosely in this context to refer 151 to the entity or organization that will state how a device is 152 intended to be used. For example, in the context of a lightbulb, 153 this might indeed be the lightbulb manufacturer. In the context of a 154 smarter device that has a built in Linux stack, it might be an 155 integrator of that device. The key points are that the device itself 156 is assumed to serve a limited purpose, and that there exists an 157 organization in the supply chain of that device that will take 158 responsibility for informing the network about that purpose. 160 The intent of MUD is to provide the following: 162 o Substantially reduce the threat surface on a device to those 163 communications intended by the manufacturer. 165 o Provide a means to scale network policies to the ever-increasing 166 number of types of devices in the network. 168 o Provide a means to address at least some vulnerabilities in a way 169 that is faster than the time it might take to update systems. 170 This will be particularly true for systems that are no longer 171 supported. 173 o Keep the cost of implementation of such a system to the bare 174 minimum. 176 o Provide a means of extensibility for manufacturers to express 177 other device capabilities or requirements. 179 MUD consists of three architectural building blocks: 181 o A URL that can be used to locate a description; 183 o The description itself, including how it is interpreted, and; 185 o A means for local network management systems to retrieve the 186 description. 188 MUD is most effective when the network is able to identify in some 189 way the remote endpoints that Things will talk to. 191 In this specification we describe each of these building blocks and 192 how they are intended to be used together. However, they may also be 193 used separately, independent of this specification, by local 194 deployments for their own purposes. 196 1.1. What MUD Doesn't Do 198 MUD is not intended to address network authorization of general 199 purpose computers, as their manufacturers cannot envision a specific 200 communication pattern to describe. In addition, even those devices 201 that have a single or small number of uses might have very broad 202 communication patterns. MUD on its own is not for them either. 204 Although MUD can provide network administrators with some additional 205 protection when device vulnerabilities exist, it will never replace 206 the need for manufacturers to patch vulnerabilities. 208 Finally, no matter what the manufacturer specifies in a MUD file, 209 these are not directives, but suggestions. How they are instantiated 210 locally will depend on many factors and will be ultimately up to the 211 local network administrator, who must decide what is appropriate in a 212 given circumstances. 214 1.2. A Simple Example 216 A light bulb is intended to light a room. It may be remotely 217 controlled through the network, and it may make use of a rendezvous 218 service of some form that an application on a smart phone. What we 219 can say about that light bulb, then, is that all other network access 220 is unwanted. It will not contact a news service, nor speak to the 221 refrigerator, and it has no need of a printer or other devices. It 222 has no social networking friends. Therefore, an access list applied 223 to it that states that it will only connect to the single rendezvous 224 service will not impede the light bulb in performing its function, 225 while at the same time allowing the network to provide both it and 226 other devices an additional layer of protection. 228 1.3. Terminology 230 MUD: manufacturer usage description. 232 MUD file: a file containing YANG-based JSON that describes a Thing 233 and associated suggested specific network behavior. 235 MUD file server: a web server that hosts a MUD file. 237 MUD manager: the system that requests and receives the MUD file from 238 the MUD server. After it has processed a MUD file, it may direct 239 changes to relevant network elements. 241 MUD controller: a synonym that has been used in the past for MUD 242 manager. 244 MUD URL: a URL that can be used by the MUD manager to receive the 245 MUD file. 247 Thing: the device emitting a MUD URL. 249 Manufacturer: the entity that configures the Thing to emit the MUD 250 URL and the one who asserts a recommendation in a MUD file. The 251 manufacturer might not always be the entity that constructs a 252 Thing. It could, for instance, be a systems integrator, or even a 253 component provider. 255 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 256 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 257 "OPTIONAL" in this document are to be interpreted as described in BCP 258 14 [RFC2119] [RFC8174] when, and only when, they appear in all 259 capitals, as shown here. 261 1.4. Determining Intended Use 263 The notion of intended use is in itself not new. Network 264 administrators apply access lists every day to allow for only such 265 use. This notion of white listing was well described by Chapman and 266 Zwicky in [FW95]. Profiling systems that make use of heuristics to 267 identify types of systems have existed for years as well. 269 A Thing could just as easily tell the network what sort of access it 270 requires without going into what sort of system it is. This would, 271 in effect, be the converse of [RFC7488]. In seeking a general 272 solution, however, we assume that a device will implement 273 functionality necessary to fulfill its limited purpose. This is 274 basic economic constraint. Unless the network would refuse access to 275 such a device, its developers would have no reason to provide the 276 network any information. To date, such an assertion has held true. 278 1.5. Finding A Policy: The MUD URL 280 Our work begins with the device emitting a Universal Resource Locator 281 (URL) [RFC3986]. This URL serves both to classify the device type 282 and to provide a means to locate a policy file. 284 MUD URLs MUST use the HTTPS scheme [RFC7230]. 286 In this memo three means are defined to emit the MUD URL, as follows: 288 o A DHCP option[RFC2131],[RFC3315] that the DHCP client uses to 289 inform the DHCP server. The DHCP server may take further actions, 290 such as act as the MUD manager or otherwise pass the MUD URL along 291 to the MUD manager. 293 o An X.509 constraint. The IEEE has developed [IEEE8021AR] that 294 provides a certificate-based approach to communicate device 295 characteristics, which itself relies on [RFC5280]. The MUD URL 296 extension is non-critical, as required by IEEE 802.1AR. Various 297 means may be used to communicate that certificate, including 298 Tunnel Extensible Authentication Protocol (TEAP) [RFC7170]. 300 o Finally, a Link Layer Discovery Protocol (LLDP) frame is defined 301 [IEEE8021AB]. 303 It is possible that there may be other means for a MUD URL to be 304 learned by a network. For instance, some devices may already be 305 fielded or have very limited ability to communicate a MUD URL, and 306 yet can be identified through some means, such as a serial number or 307 a public key. In these cases, manufacturers may be able to map those 308 identifiers to particular MUD URLs (or even the files themselves). 309 Similarly, there may be alternative resolution mechanisms available 310 for situations where Internet connectivity is limited or does not 311 exist. Such mechanisms are not described in this memo, but are 312 possible. Implementors are encouraged to allow for this sort of 313 flexibility of how MUD URLs may be learned. 315 1.6. Processing of the MUD URL 317 MUD managers that are able to do so SHOULD retrieve MUD URLs and 318 signature files as per [RFC7230], using the GET method [RFC7231]. 319 They MUST validate the certificate using the rules in [RFC2818], 320 Section 3.1. 322 Requests for MUD URLs SHOULD include an "Accept" header ([RFC7231], 323 Section 5.3.2) containing "application/mud+json", an "Accept- 324 Language" header field ([RFC7231], Section 5.3.5), and a "User-Agent" 325 header ([RFC7231], Section 5.5.3). 327 MUD managers SHOULD automatically process 3xx response status codes. 329 If a MUD manager is not able to fetch a MUD URL, other means MAY be 330 used to import MUD files and associated signature files. So long as 331 the signature of the file can be validated, the file can be used. In 332 such environments, controllers SHOULD warn administrators when cache- 333 validity expiry is approaching so that they may check for new files. 335 It may not be possible for a MUD manager to retrieve a MUD file at 336 any given time. Should a MUD manager fail to retrieve a MUD file, it 337 SHOULD consider the existing one safe to use, at least for a time. 338 After some period, it SHOULD log that it has been unable to retrieve 339 the file. There may be very good reasons for such failures, 340 including the possibility that the MUD manager is in an off-line 341 environment, the local Internet connection has failed, or the remote 342 Internet connection has failed. It is also possible that an attacker 343 is attempting to interfere with the deployment of a device. It is a 344 local decision as to how to handle such circumstances. 346 1.7. Types of Policies 348 When the MUD URL is resolved, the MUD manager retrieves a file that 349 describes what sort of communications a device is designed to have. 350 The manufacturer may specify either specific hosts for cloud based 351 services or certain classes for access within an operational network. 352 An example of a class might be "devices of a specified manufacturer 353 type", where the manufacturer type itself is indicated simply by the 354 authority component (e.g, the domain name) of the MUD URL. Another 355 example might be to allow or disallow local access. Just like other 356 policies, these may be combined. For example: 358 o Allow access to devices of the same manufacturer 360 o Allow access to and from controllers via Constrained Application 361 Protocol (COAP)[RFC7252] 363 o Allow access to local DNS/NTP 365 o Deny all other access 367 A printer might have a description that states: 369 o Allow access for port IPP or port LPD 371 o Allow local access for port HTTP 373 o Deny all other access 375 In this way anyone can print to the printer, but local access would 376 be required for the management interface. 378 The files that are retrieved are intended to be closely aligned to 379 existing network architectures so that they are easy to deploy. We 380 make use of YANG [RFC7950] because it provides accurate and adequate 381 models for use by network devices. JSON[RFC8259] is used as a 382 serialization format for compactness and readability, relative to 383 XML. Other formats may be chosen with later versions of MUD. 385 While the policy examples given here focus on access control, this is 386 not intended to be the sole focus. By structuring the model 387 described in this document with clear extension points, other 388 descriptions could be included. One that often comes to mind is 389 quality of service. 391 The YANG modules specified here are extensions of 392 [I-D.ietf-netmod-acl-model]. The extensions to this model allow for 393 a manufacturer to express classes of systems that a manufacturer 394 would find necessary for the proper function of the device. Two 395 modules are specified. The first module specifies a means for domain 396 names to be used in ACLs so that devices that have their controllers 397 in the cloud may be appropriately authorized with domain names, where 398 the mapping of those names to addresses may rapidly change. 400 The other module abstracts away IP addresses into certain classes 401 that are instantiated into actual IP addresses through local 402 processing. Through these classes, manufacturers can specify how the 403 device is designed to communicate, so that network elements can be 404 configured by local systems that have local topological knowledge. 405 That is, the deployment populates the classes that the manufacturer 406 specifies. The abstractions below map to zero or more hosts, as 407 follows: 409 Manufacturer: A device made by a particular manufacturer, as 410 identified by the authority component of its MUD URL 412 same-manufacturer: Devices that have the same authority component of 413 their MUD URL. 415 controller: Devices that the local network administrator admits to 416 the particular class. 418 my-controller: Devices intended to serve as controllers for the MUD- 419 URL that the Thing emitted. 421 local: The class of IP addresses that are scoped within some 422 administrative boundary. By default it is suggested that this be 423 the local subnet. 425 The "manufacturer" classes can be easily specified by the 426 manufacturer, whereas controller classes are initially envisioned to 427 be specified by the administrator. 429 Because manufacturers do not know who will be using their devices, it 430 is important for functionality referenced in usage descriptions to be 431 relatively ubiquitous and mature. For these reasons the YANG-based 432 configuration in a MUD file is limited to either the modules 433 specified or referenced in this document, or those specified in 434 documented extensions. 436 1.8. The Manufacturer Usage Description Architecture 438 With these components laid out we now have the basis for an 439 architecture. This leads us to ASCII art. 441 ....................................... 442 . ____________ . _____________ 443 . | | . | | 444 . | MUD |-->get URL-->| MUD | 445 . | Manager | .(https) | File Server | 446 . End system network |____________|<-MUD file<-<|_____________| 447 . . . 448 . . . 449 . _______ _________ . 450 .| | (dhcp et al) | router | . 451 .| Thing |---->MUD URL-->| or | . 452 .|_______| | switch | . 453 . |_________| . 454 ....................................... 456 Figure 1: MUD Architecture 458 In the above diagram, the switch or router collects MUD URLs and 459 forwards them to the MUD manager (a network management system) for 460 processing. This happens in different ways, depending on how the URL 461 is communicated. For instance, in the case of DHCP, the DHCP server 462 might receive the URL and then process it. In the case of IEEE 463 802.1X [IEEE8021X], the switch would carry the URL via a certificate 464 to the authentication server via EAP over Radius[RFC3748], which 465 would then process it. One method to do this is TEAP, described in 466 [RFC7170]. The certificate extension is described below. 468 The information returned by the MUD file server is valid for as long 469 as the Thing is connected. There is no expiry. However, if the MUD 470 manager has detected that the MUD file for a Thing has changed, it 471 SHOULD update the policy expeditiously, taking into account whatever 472 approval flow is required in a deployment. In this way, new 473 recommendations from the manufacturer can be processed in a timely 474 fashion. 476 The information returned by the MUD file server (a web server) is 477 valid for the duration of the Thing's connection, or as specified in 478 the description. Thus if the Thing is disconnected, any associated 479 configuration in the switch can be removed. Similarly, from time to 480 time the description may be refreshed, based on new capabilities or 481 communication patterns or vulnerabilities. 483 The web server is typically run by or on behalf of the manufacturer. 484 Its domain name is that of the authority found in the MUD URL. For 485 legacy cases where Things cannot emit a URL, if the switch is able to 486 determine the appropriate URL, it may proxy it. In the trivial case 487 it may hardcode MUD-URL on a switch port or a map from some available 488 identifier such as an L2 address or certificate hash to a MUD-URL. 490 The role of the MUD manager in this environment is to do the 491 following: 493 o receive MUD URLs, 495 o fetch MUD files, 497 o translate abstractions in the MUD files to specific network 498 element configuration, 500 o maintain and update any required mappings of the abstractions, and 502 o update network elements with appropriate configuration. 504 A MUD manager may be a component of a AAA or network management 505 system. Communication within those systems and from those systems to 506 network elements is beyond the scope of this memo. 508 1.9. Order of operations 510 As mentioned above, MUD contains architectural building blocks, and 511 so order of operation may vary. However, here is one clear intended 512 example: 514 1. Thing emits URL. 516 2. That URL is forwarded to a MUD manager by the nearest switch (how 517 this happens depends on the way in which the MUD URL is emitted). 519 3. The MUD manager retrieves the MUD file and signature from the MUD 520 file server, assuming it doesn't already have copies. After 521 validating the signature, it may test the URL against a web or 522 domain reputation service, and it may test any hosts within the 523 file against those reputation services, as it deems fit. 525 4. The MUD manager may query the administrator for permission to add 526 the Thing and associated policy. If the Thing is known or the 527 Thing type is known, it may skip this step. 529 5. The MUD manager instantiates local configuration based on the 530 abstractions defined in this document. 532 6. The MUD manager configures the switch nearest the Thing. Other 533 systems may be configured as well. 535 7. When the Thing disconnects, policy is removed. 537 2. The MUD Model and Semantic Meaning 539 A MUD file consists of a YANG model instance that has been serialized 540 in JSON [RFC7951]. For purposes of MUD, the nodes that can be 541 modified are access lists as augmented by this model. The MUD file 542 is limited to the serialization of only the following YANG schema: 544 o ietf-access-control-list [I-D.ietf-netmod-acl-model] 546 o ietf-mud (this document) 548 o ietf-acldns (this document) 550 Extensions may be used to add additional schema. This is described 551 further on. 553 To provide the widest possible deployment, publishers of MUD files 554 SHOULD make use of the abstractions in this memo and avoid the use of 555 IP addresses. A MUD manager SHOULD NOT automatically implement any 556 MUD file that contains IP addresses, especially those that might have 557 local significance. The addressing of one side of an access list is 558 implicit, based on whether it is applied as to-device-policy or from- 559 device-policy. 561 With the exceptions of "name" of the ACL, "type", "name" of the ACE, 562 and TCP and UDP source and destination port information, publishers 563 of MUD files SHOULD limit the use of ACL model leaf nodes expressed 564 to those found in this specification. Absent any extensions, MUD 565 files are assumed to implement only the following ACL model features: 567 o match-on-ipv4, match-on-ipv6, match-on-tcp, match-on-udp, match- 568 on-icmp 570 Furthermore, only "accept" or "drop" actions SHOULD be included. A 571 MUD manager MAY choose to interpret "reject" as "drop". A MUD 572 manager SHOULD ignore all other actions. This is because 573 manufacturers do not have sufficient context within a local 574 deployment to know whether reject is appropriate. That is a decision 575 that should be left to a network administrator. 577 Given that MUD does not deal with interfaces, the support of the 578 "ietf-interfaces" module [RFC8343] is not required. Specifically, 579 the support of interface-related features and branches (e.g., 580 interface-attachment and interface-stats) of the ACL YANG module is 581 not required. 583 In fact, MUD managers MAY ignore any particular component of a 584 description or MAY ignore the description in its entirety, and SHOULD 585 carefully inspect all MUD descriptions. Publishers of MUD files MUST 586 NOT include other nodes except as described in Section 3.9. See that 587 section for more information. 589 2.1. The IETF-MUD YANG Module 591 This module is structured into three parts: 593 o The first component, the "mud" container, holds information that 594 is relevant to retrieval and validity of the MUD file itself, as 595 well as policy intended to and from the Thing. 597 o The second component augments the matching container of the ACL 598 model to add several nodes that are relevant to the MUD URL, or 599 otherwise abstracted for use within a local environment. 601 o The third component augments the tcp-acl container of the ACL 602 model to add the ability to match on the direction of initiation 603 of a TCP connection. 605 A valid MUD file will contain two root objects, a "mud" container and 606 an "acls" container. Extensions may add additional root objects as 607 required. As a reminder, when parsing acls, elements within a 608 "match" block are logically ANDed. In general, a single abstraction 609 in a match statement should be used. For instance, it makes little 610 sense to match both "my-controller" and "controller" with an 611 argument, since they are highly unlikely to be the same value. 613 A simplified graphical representation of the data models is used in 614 this document. The meaning of the symbols in these diagrams is 615 explained in [RFC8340]. 617 module: ietf-mud 618 +--rw mud! 619 +--rw mud-version uint8 620 +--rw mud-url inet:uri 621 +--rw last-update yang:date-and-time 622 +--rw mud-signature? inet:uri 623 +--rw cache-validity? uint8 624 +--rw is-supported boolean 625 +--rw systeminfo? string 626 +--rw mfg-name? string 627 +--rw model-name? string 628 +--rw firmware-rev? string 629 +--rw software-rev? string 630 +--rw documentation? inet:uri 631 +--rw extensions* string 632 +--rw from-device-policy 633 | +--rw acls 634 | +--rw access-list* [name] 635 | +--rw name -> /acl:acls/acl/name 636 +--rw to-device-policy 637 +--rw acls 638 +--rw access-list* [name] 639 +--rw name -> /acl:acls/acl/name 641 augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches: 642 +--rw mud 643 +--rw manufacturer? inet:host 644 +--rw same-manufacturer? empty 645 +--rw model? inet:uri 646 +--rw local-networks? empty 647 +--rw controller? inet:uri 648 +--rw my-controller? empty 649 augment 650 /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches 651 /acl:l4/acl:tcp/acl:tcp: 652 +--rw direction-initiated? direction 654 3. MUD model definitions for the root mud container 656 3.1. mud-version 658 This node specifies the integer version of the MUD specification. 659 This memo specifies version 1. 661 3.2. mud-url 663 This URL identifies the MUD file. This is useful when the file and 664 associated signature are manually uploaded, say, in an offline mode. 666 3.3. to-device-policy and from-device-policy containers 668 [I-D.ietf-netmod-acl-model] describes access-lists. In the case of 669 MUD, a MUD file must be explicit in describing the communication 670 pattern of a Thing, and that includes indicating what is to be 671 permitted or denied in either direction of communication. Hence each 672 of these containers indicates the appropriate direction of a flow in 673 association with a particular Thing. They contain references to 674 specific access-lists. 676 3.4. last-update 678 This is a date-and-time value of when the MUD file was generated. 679 This is akin to a version number. Its form is taken from [RFC6991] 680 which, for those keeping score, in turn was taken from Section 5.6 of 681 [RFC3339], which was taken from [ISO.8601.1988]. 683 3.5. cache-validity 685 This uint8 is the period of time in hours that a network management 686 station MUST wait since its last retrieval before checking for an 687 update. It is RECOMMENDED that this value be no less than 24 and 688 MUST NOT be more than 168 for any Thing that is supported. This 689 period SHOULD be no shorter than any period determined through HTTP 690 caching directives (e.g., "cache-control" or "Expires"). N.B., 691 expiring of this timer does not require the MUD manager to discard 692 the MUD file, nor terminate access to a Thing. See Section 16 for 693 more information. 695 3.6. is-supported 697 This boolean is an indication from the manufacturer to the network 698 administrator as to whether or not the Thing is supported. In this 699 context a Thing is said to not be supported if the manufacturer 700 intends never to issue a firmware or software update to the Thing or 701 never update the MUD file. A MUD manager MAY still periodically 702 check for updates. 704 3.7. systeminfo 706 This is a textual UTF-8 description of the Thing to be connected. 707 The intent is for administrators to be able to see a brief 708 displayable description of the Thing. It SHOULD NOT exceed 60 709 characters worth of display space. 711 3.8. mfg-name, software-rev, model-name firmware-rev 713 These optional fields are filled in as specified by [RFC8348]. Note 714 that firmware-rev and software-rev MUST NOT be populated in a MUD 715 file if the device can be upgraded but the MUD-URL cannot be. This 716 would be the case, for instance, with MUD-URLs that are contained in 717 802.1AR certificates. 719 3.9. extensions 721 This optional leaf-list names MUD extensions that are used in the MUD 722 file. Note that MUD extensions MUST NOT be used in a MUD file 723 without the extensions being declared. Implementations MUST ignore 724 any node in this file that they do not understand. 726 Note that extensions can either extend the MUD file as described in 727 the previous paragraph, or they might reference other work. An 728 extension example can be found in Appendix C. 730 4. Augmentation to the ACL Model 732 Note that in this section, when we use the term "match" we are 733 referring to the ACL model "matches" node. 735 4.1. manufacturer 737 This node consists of a hostname that would be matched against the 738 authority component of another Thing's MUD URL. In its simplest form 739 "manufacturer" and "same-manufacturer" may be implemented as access- 740 lists. In more complex forms, additional network capabilities may be 741 used. For example, if one saw the line "manufacturer" : 742 "flobbidy.example.com", then all Things that registered with a MUD 743 URL that contained flobbity.example.com in its authority section 744 would match. 746 4.2. same-manufacturer 748 This null-valued node is an equivalent for when the manufacturer 749 element is used to indicate the authority that is found in another 750 Thing's MUD URL matches that of the authority found in this Thing's 751 MUD URL. For example, if the Thing's MUD URL were 752 https://b1.example.com/ThingV1, then all devices that had MUD URL 753 with an authority section of b1.example.com would match. 755 4.3. documentation 757 This URI consists of a URL that points to documentation relating to 758 the device and the MUD file. This can prove particularly useful when 759 the "controller" class is used, so that its use can be explained. 761 4.4. model 763 This string matches the entire MUD URL, thus covering the model that 764 is unique within the context of the authority. It may contain not 765 only model information, but versioning information as well, and any 766 other information that the manufacturer wishes to add. The intended 767 use is for devices of this precise class to match, to permit or deny 768 communication between one another. 770 4.5. local-networks 772 This null-valued node expands to include local networks. Its default 773 expansion is that packets must not traverse toward a default route 774 that is received from the router. However, administrators may expand 775 the expression as is appropriate in their deployments. 777 4.6. controller 779 This URI specifies a value that a controller will register with the 780 MUD manager. The node then is expanded to the set of hosts that are 781 so registered. This node may also be a URN. In this case, the URN 782 describes a well known service, such as DNS or NTP, that has been 783 standardized. Both of those URNs may be found in Section 17.6. 785 When "my-controller" is used, it is possible that the administrator 786 will be prompted to populate that class for each and every model. 787 Use of "controller" with a named class allows the user to populate 788 that class only once for many different models that a manufacturer 789 may produce. 791 Controller URIs MAY take the form of a URL (e.g. "http[s]://"). 792 However, MUD managers MUST NOT resolve and retrieve such files, and 793 it is RECOMMENDED that there be no such file at this time, as their 794 form and function may be defined at a point in the future. For now, 795 URLs should serve simply as class names and may be populated by the 796 local deployment administrator. 798 Great care should be taken by MUD managers when invoking the 799 controller class in the form of URLs. For one thing, it requires 800 some understanding by the administrator as to when it is appropriate. 801 Pre-registration in such classes by controllers with the MUD server 802 is encouraged. The mechanism to do that is beyond the scope of this 803 work. 805 4.7. my-controller 807 This null-valued node signals to the MUD manager to use whatever 808 mapping it has for this MUD URL to a particular group of hosts. This 809 may require prompting the administrator for class members. Future 810 work should seek to automate membership management. 812 4.8. direction-initiated 814 This MUST only be applied to TCP. This matches the direction in 815 which a TCP connection is initiated. When direction initiated is 816 "from-device", packets that are transmitted in the direction of a 817 thing MUST be dropped unless the thing has first initiated a TCP 818 connection. By way of example, this node may be implemented in its 819 simplest form by looking at naked SYN bits, but may also be 820 implemented through more stateful mechanisms. 822 When applied this matches packets when the flow was initiated in the 823 corresponding direction. [RFC6092] specifies IPv6 guidance best 824 practices. While that document is scoped specifically to IPv6, its 825 contents are applicable for IPv4 as well. 827 5. Processing of the MUD file 829 To keep things relatively simple in addition to whatever definitions 830 exist, we also apply two additional default behaviors: 832 o Anything not explicitly permitted is denied. 834 o Local DNS and NTP are, by default, permitted to and from the 835 Thing. 837 An explicit description of the defaults can be found in Appendix B. 838 These are applied AFTER all other explicit rules. Thus, a default 839 behavior can be changed with a "drop" action. 841 6. What does a MUD URL look like? 843 MUD URLs are required to use the HTTPS scheme, in order to establish 844 the MUD file server's identity and assure integrity of the MUD file. 846 Any "https://" URL can be a MUD URL. For example: 848 https://things.example.org/product_abc123/v5 849 https://www.example.net/mudfiles/temperature_sensor/ 850 https://example.com/lightbulbs/colour/v1 852 A manufacturer may construct a MUD URL in any way, so long as it 853 makes use of the "https" schema. 855 7. The MUD YANG Model 857 file "ietf-mud@2018-06-15.yang" 858 module ietf-mud { 859 yang-version 1.1; 860 namespace "urn:ietf:params:xml:ns:yang:ietf-mud"; 861 prefix ietf-mud; 863 import ietf-access-control-list { 864 prefix acl; 865 } 866 import ietf-yang-types { 867 prefix yang; 868 } 869 import ietf-inet-types { 870 prefix inet; 871 } 873 organization 874 "IETF OPSAWG (Ops Area) Working Group"; 875 contact 876 "WG Web: http://tools.ietf.org/wg/opsawg/ 877 WG List: opsawg@ietf.org 878 Author: Eliot Lear 879 lear@cisco.com 880 Author: Ralph Droms 881 rdroms@gmail.com 882 Author: Dan Romascanu 883 dromasca@gmail.com 885 "; 886 description 887 "This YANG module defines a component that augments the 888 IETF description of an access list. This specific module 889 focuses on additional filters that include local, model, 890 and same-manufacturer. 892 This module is intended to be serialized via JSON and stored 893 as a file, as described in RFC XXXX [RFC Editor to fill in with 894 this document #]. 896 Copyright (c) 2016,2017 IETF Trust and the persons 897 identified as the document authors. All rights reserved. 898 Redistribution and use in source and binary forms, with or 899 without modification, is permitted pursuant to, and subject 900 to the license terms contained in, the Simplified BSD 901 License set forth in Section 4.c of the IETF Trust's Legal 902 Provisions Relating to IETF Documents 903 (http://trustee.ietf.org/license-info). 904 This version of this YANG module is part of RFC XXXX; see 905 the RFC itself for full legal notices."; 907 revision 2018-06-15 { 908 description 909 "Initial proposed standard."; 910 reference 911 "RFC XXXX: Manufacturer Usage Description 912 Specification"; 913 } 915 typedef direction { 916 type enumeration { 917 enum to-device { 918 description 919 "packets or flows destined to the target 920 Thing"; 921 } 922 enum from-device { 923 description 924 "packets or flows destined from 925 the target Thing"; 926 } 927 } 928 description 929 "Which way are we talking about?"; 930 } 932 container mud { 933 presence "Enabled for this particular MUD URL"; 934 description 935 "MUD related information, as specified 936 by RFC-XXXX [RFC Editor to fill in]."; 937 uses mud-grouping; 938 } 940 grouping mud-grouping { 941 description 942 "Information about when support end(ed), and 943 when to refresh"; 945 leaf mud-version { 946 type uint8; 947 mandatory true; 948 description 949 "This is the version of the MUD 950 specification. This memo specifies version 1."; 951 } 952 leaf mud-url { 953 type inet:uri; 954 mandatory true; 955 description 956 "This is the MUD URL associated with the entry found 957 in a MUD file."; 958 } 959 leaf last-update { 960 type yang:date-and-time; 961 mandatory true; 962 description 963 "This is intended to be when the current MUD file 964 was generated. MUD Managers SHOULD NOT check 965 for updates between this time plus cache validity"; 966 } 967 leaf mud-signature { 968 type inet:uri; 969 description 970 "A URI that resolves to a signature as 971 described in this specification."; 972 } 973 leaf cache-validity { 974 type uint8 { 975 range "1..168"; 976 } 977 units "hours"; 978 default "48"; 979 description 980 "The information retrieved from the MUD server is 981 valid for these many hours, after which it should 982 be refreshed. N.B. MUD manager implementations 983 need not discard MUD files beyond this period."; 984 } 985 leaf is-supported { 986 type boolean; 987 mandatory true; 988 description 989 "This boolean indicates whether or not the Thing is 990 currently supported by the manufacturer."; 991 } 992 leaf systeminfo { 993 type string; 994 description 995 "A UTF-8 description of this Thing. This 996 should be a brief description that may be 997 displayed to the user to determine whether 998 to allow the Thing on the 999 network."; 1000 } 1001 leaf mfg-name { 1002 type string; 1003 description 1004 "Manufacturer name, as described in 1005 the ietf-hardware YANG module."; 1006 } 1007 leaf model-name { 1008 type string; 1009 description 1010 "Model name, as described in the 1011 ietf-hardware YANG module."; 1012 } 1013 leaf firmware-rev { 1014 type string; 1015 description 1016 "firmware-rev, as described in the 1017 ietf-hardware YANG module. Note this field MUST 1018 NOT be included when the device can be updated 1019 but the MUD-URL cannot."; 1020 } 1021 leaf software-rev { 1022 type string; 1023 description 1024 "software-rev, as described in the 1025 ietf-hardware YANG module. Note this field MUST 1026 NOT be included when the device can be updated 1027 but the MUD-URL cannot."; 1028 } 1029 leaf documentation { 1030 type inet:uri; 1031 description 1032 "This URL points to documentation that 1033 relates to this device and any classes that it uses 1034 in its MUD file. A caution: MUD managers need 1035 not resolve this URL on their own, but rather simply 1036 provide it to the administrator. Parsing HTML is 1037 not an intended function of a MUD manager."; 1038 } 1039 leaf-list extensions { 1040 type string { 1041 length "1..40"; 1042 } 1043 description 1044 "A list of extension names that are used in this MUD 1045 file. Each name is registered with the IANA and 1046 described in an RFC."; 1047 } 1048 container from-device-policy { 1049 description 1050 "The policies that should be enforced on traffic 1051 coming from the device. These policies are not 1052 necessarily intended to be enforced at a single 1053 point, but may be rendered by the controller to any 1054 relevant enforcement points in the network or 1055 elsewhere."; 1056 uses access-lists; 1057 } 1058 container to-device-policy { 1059 description 1060 "The policies that should be enforced on traffic 1061 going to the device. These policies are not 1062 necessarily intended to be enforced at a single 1063 point, but may be rendered by the controller to any 1064 relevant enforcement points in the network or 1065 elsewhere."; 1066 uses access-lists; 1067 } 1068 } 1070 grouping access-lists { 1071 description 1072 "A grouping for access lists in the context of device 1073 policy."; 1074 container access-lists { 1075 description 1076 "The access lists that should be applied to traffic 1077 to or from the device."; 1078 list access-list { 1079 key "name"; 1080 description 1081 "Each entry on this list refers to an ACL that 1082 should be present in the overall access list 1083 data model. Each ACL is identified by name and 1084 type."; 1085 leaf name { 1086 type leafref { 1087 path "/acl:acls/acl:acl/acl:name"; 1088 } 1089 description 1090 "The name of the ACL for this entry."; 1091 } 1092 } 1093 } 1094 } 1096 augment "/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches" { 1097 description 1098 "adding abstractions to avoid need of IP addresses"; 1099 container mud { 1100 description 1101 "MUD-specific matches."; 1102 leaf manufacturer { 1103 type inet:host; 1104 description 1105 "A domain that is intended to match the authority 1106 section of the MUD URL. This node is used to specify 1107 one or more manufacturers a device should 1108 be authorized to access."; 1109 } 1110 leaf same-manufacturer { 1111 type empty; 1112 description 1113 "This node matches the authority section of the MUD URL 1114 of a Thing. It is intended to grant access to all 1115 devices with the same authority section."; 1116 } 1117 leaf model { 1118 type inet:uri; 1119 description 1120 "Devices of the specified model type will match if 1121 they have an identical MUD URL."; 1122 } 1123 leaf local-networks { 1124 type empty; 1125 description 1126 "IP addresses will match this node if they are 1127 considered local addresses. A local address may be 1128 a list of locally defined prefixes and masks 1129 that indicate a particular administrative scope."; 1130 } 1131 leaf controller { 1132 type inet:uri; 1133 description 1134 "This node names a class that has associated with it 1135 zero or more IP addresses to match against. These 1136 may be scoped to a manufacturer or via a standard 1137 URN."; 1138 } 1139 leaf my-controller { 1140 type empty; 1141 description 1142 "This node matches one or more network elements that 1143 have been configured to be the controller for this 1144 Thing, based on its MUD URL."; 1145 } 1146 } 1147 } 1148 augment "/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches" + 1149 "/acl:l4/acl:tcp/acl:tcp" { 1150 description 1151 "add direction-initiated"; 1152 leaf direction-initiated { 1153 type direction; 1154 description 1155 "This node matches based on which direction a 1156 connection was initiated. The means by which that 1157 is determined is discussed in this document."; 1158 } 1159 } 1160 } 1161 1163 8. The Domain Name Extension to the ACL Model 1165 This module specifies an extension to IETF-ACL model such that domain 1166 names may be referenced by augmenting the "matches" node. Different 1167 implementations may deploy differing methods to maintain the mapping 1168 between IP address and domain name, if indeed any are needed. 1169 However, the intent is that resources that are referred to using a 1170 name should be authorized (or not) within an access list. 1172 The structure of the change is as follows: 1174 module: ietf-acldns 1175 augment /acl:acls/acl:acl/acl:aces/acl:ace/ 1176 acl:matches/acl:l3/acl:ipv4/acl:ipv4: 1177 +--rw src-dnsname? inet:host 1178 +--rw dst-dnsname? inet:host 1179 augment /acl:acls/acl:acl/acl:aces/acl:ace/ 1180 acl:matches/acl:l3/acl:ipv6/acl:ipv6: 1181 +--rw src-dnsname? inet:host 1182 +--rw dst-dnsname? inet:host 1184 The choice of these particular points in the access-list model is 1185 based on the assumption that we are in some way referring to IP- 1186 related resources, as that is what the DNS returns. A domain name in 1187 our context is defined in [RFC6991]. The augmentations are 1188 replicated across IPv4 and IPv6 to allow MUD file authors the ability 1189 to control the IP version that the Thing may utilize. 1191 The following node are defined. 1193 8.1. src-dnsname 1195 The argument corresponds to a domain name of a source as specified by 1196 inet:host. A number of means may be used to resolve hosts. What is 1197 important is that such resolutions be consistent with ACLs required 1198 by Things to properly operate. 1200 8.2. dst-dnsname 1202 The argument corresponds to a domain name of a destination as 1203 specified by inet:host See the previous section relating to 1204 resolution. 1206 Note when using either of these with a MUD file, because access is 1207 associated with a particular Thing, MUD files MUST NOT contain either 1208 a src-dnsname in an ACL associated with from-device-policy or a dst- 1209 dnsname associated with to-device-policy. 1211 8.3. The ietf-acldns Model 1213 file "ietf-acldns@2018-06-15.yang" 1214 module ietf-acldns { 1215 yang-version 1.1; 1216 namespace "urn:ietf:params:xml:ns:yang:ietf-acldns"; 1217 prefix ietf-acldns; 1219 import ietf-access-control-list { 1220 prefix acl; 1221 } 1222 import ietf-inet-types { 1223 prefix inet; 1224 } 1226 organization 1227 "IETF OPSAWG (Ops Area) Working Group"; 1228 contact 1229 "WG Web: http://tools.ietf.org/wg/opsawg/ 1230 WG List: opsawg@ietf.org 1231 Author: Eliot Lear 1232 lear@cisco.com 1233 Author: Ralph Droms 1234 rdroms@gmail.com 1235 Author: Dan Romascanu 1236 dromasca@gmail.com 1237 "; 1238 description 1239 "This YANG module defines a component that augments the 1240 IETF description of an access list to allow DNS names 1241 as matching criteria."; 1243 revision 2018-06-15 { 1244 description 1245 "Base version of dnsname extension of ACL model"; 1246 reference 1247 "RFC XXXX: Manufacturer Usage Description 1248 Specification"; 1249 } 1251 grouping dns-matches { 1252 description 1253 "Domain names for matching."; 1254 leaf src-dnsname { 1255 type inet:host; 1256 description 1257 "domain name to be matched against"; 1258 } 1259 leaf dst-dnsname { 1260 type inet:host; 1261 description 1262 "domain name to be matched against"; 1263 } 1264 } 1266 augment "/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches" + 1267 "/acl:l3/acl:ipv4/acl:ipv4" { 1268 description 1269 "Adding domain names to matching"; 1270 uses dns-matches; 1271 } 1272 augment "/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches" + 1273 "/acl:l3/acl:ipv6/acl:ipv6" { 1274 description 1275 "Adding domain names to matching"; 1276 uses dns-matches; 1277 } 1278 } 1279 1281 9. MUD File Example 1283 This example contains two access lists that are intended to provide 1284 outbound access to a cloud service on TCP port 443. 1286 { 1287 "ietf-mud:mud": { 1288 "mud-version": 1, 1289 "mud-url": "https://lighting.example.com/lightbulb2000", 1290 "last-update": "2018-03-02T11:20:51+01:00", 1291 "cache-validity": 48, 1292 "is-supported": true, 1293 "systeminfo": "The BMS Example Lightbulb", 1294 "from-device-policy": { 1295 "access-lists": { 1296 "access-list": [ 1297 { 1298 "name": "mud-76100-v6fr" 1299 } 1300 ] 1301 } 1302 }, 1303 "to-device-policy": { 1304 "access-lists": { 1305 "access-list": [ 1306 { 1307 "name": "mud-76100-v6to" 1308 } 1309 ] 1310 } 1311 } 1312 }, 1313 "ietf-access-control-list:acls": { 1314 "acl": [ 1315 { 1316 "name": "mud-76100-v6to", 1317 "type": "ipv6-acl-type", 1318 "aces": { 1319 "ace": [ 1320 { 1321 "name": "cl0-todev", 1322 "matches": { 1323 "ipv6": { 1324 "ietf-acldns:src-dnsname": "test.example.com", 1325 "protocol": 6 1326 }, 1327 "tcp": { 1328 "ietf-mud:direction-initiated": "from-device", 1329 "source-port": { 1330 "operator": "eq", 1331 "port": 443 1332 } 1333 } 1334 }, 1335 "actions": { 1336 "forwarding": "accept" 1337 } 1338 } 1339 ] 1340 } 1341 }, 1342 { 1343 "name": "mud-76100-v6fr", 1344 "type": "ipv6-acl-type", 1345 "aces": { 1346 "ace": [ 1347 { 1348 "name": "cl0-frdev", 1349 "matches": { 1350 "ipv6": { 1351 "ietf-acldns:dst-dnsname": "test.example.com", 1352 "protocol": 6 1353 }, 1354 "tcp": { 1355 "ietf-mud:direction-initiated": "from-device", 1356 "destination-port": { 1357 "operator": "eq", 1358 "port": 443 1359 } 1360 } 1361 }, 1362 "actions": { 1363 "forwarding": "accept" 1364 } 1365 } 1366 ] 1367 } 1368 } 1369 ] 1370 } 1371 } 1373 In this example, two policies are declared, one from the Thing and 1374 the other to the Thing. Each policy names an access list that 1375 applies to the Thing, and one that applies from. Within each access 1376 list, access is permitted to packets flowing to or from the Thing 1377 that can be mapped to the domain name of "service.bms.example.com". 1378 For each access list, the enforcement point should expect that the 1379 Thing initiated the connection. 1381 10. The MUD URL DHCP Option 1383 The IPv4 MUD URL client option has the following format: 1385 +------+-----+------------------------------ 1386 | code | len | MUDstring 1387 +------+-----+------------------------------ 1389 Code OPTION_MUD_URL_V4 (161) is assigned by IANA. len is a single 1390 octet that indicates the length of MUD string in octets. The MUD 1391 string is defined as follows: 1393 MUDstring = mudurl [ " " reserved ] 1394 mudurl = URI; a URL [RFC3986] that uses the "https" schema [RFC7230] 1395 reserved = 1*( OCTET ) ; from [RFC5234] 1397 The entire option MUST NOT exceed 255 octets. If a space follows the 1398 MUD URL, a reserved string that will be defined in future 1399 specifications follows. MUD managers that do not understand this 1400 field MUST ignore it. 1402 The IPv6 MUD URL client option has the following format: 1404 0 1 2 3 1405 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 1406 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1407 | OPTION_MUD_URL_V6 | option-length | 1408 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1409 | MUDstring | 1410 | | 1411 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1413 OPTION_MUD_URL_V6 (112; assigned by IANA). 1415 option-length contains the length of the MUDstring, as defined above, 1416 in octets. 1418 The intent of this option is to provide both a new Thing classifier 1419 to the network as well as some recommended configuration to the 1420 routers that implement policy. However, it is entirely the purview 1421 of the network system as managed by the network administrator to 1422 decide what to do with this information. The key function of this 1423 option is simply to identify the type of Thing to the network in a 1424 structured way such that the policy can be easily found with existing 1425 toolsets. 1427 10.1. Client Behavior 1429 A DHCPv4 client MAY emit a DHCPv4 option and a DHCPv6 client MAY emit 1430 DHCPv6 option. These options are singletons, as specified in 1431 [RFC7227]. Because clients are intended to have at most one MUD URL 1432 associated with them, they may emit at most one MUD URL option via 1433 DHCPv4 and one MUD URL option via DHCPv6. In the case where both v4 1434 and v6 DHCP options are emitted, the same URL MUST be used. 1436 10.2. Server Behavior 1438 A DHCP server may ignore these options or take action based on 1439 receipt of these options. When a server consumes this option, it 1440 will either forward the URL and relevant client information (such as 1441 the gateway address or giaddr and requested IP address, and lease 1442 length) to a network management system, or it will retrieve the usage 1443 description itself by resolving the URL. 1445 DHCP servers may implement MUD functionality themselves or they may 1446 pass along appropriate information to a network management system or 1447 MUD manager. A DHCP server that does process the MUD URL MUST adhere 1448 to the process specified in [RFC2818] and [RFC5280] to validate the 1449 TLS certificate of the web server hosting the MUD file. Those 1450 servers will retrieve the file, process it, create and install the 1451 necessary configuration on the relevant network element. Servers 1452 SHOULD monitor the gateway for state changes on a given interface. A 1453 DHCP server that does not provide MUD functionality and has forwarded 1454 a MUD URL to a MUD manager MUST notify the MUD manager of any 1455 corresponding change to the DHCP state of the client (such as 1456 expiration or explicit release of a network address lease). 1458 Should the DHCP server fail, in the case when it implements the MUD 1459 manager functionality, any backup mechanisms SHOULD include the MUD 1460 state, and the server SHOULD resolve the status of clients upon its 1461 restart, similar to what it would do, absent MUD manager 1462 functionality. In the case where the DHCP server forwards 1463 information to the MUD manager, the MUD manager will either make use 1464 of redundant DHCP servers for information, or otherwise clear state 1465 based on other network information, such as monitoring port status on 1466 a switch via SNMP, Radius accounting, or similar mechanisms. 1468 10.3. Relay Requirements 1470 There are no additional requirements for relays. 1472 11. The Manufacturer Usage Description (MUD) URL X.509 Extension 1474 This section defines an X.509 non-critical certificate extension that 1475 contains a single Uniform Resource Locator (URL) that points to an 1476 on-line Manufacturer Usage Description concerning the certificate 1477 subject. URI must be represented as described in Section 7.4 of 1478 [RFC5280]. 1480 Any Internationalized Resource Identifiers (IRIs) MUST be mapped to 1481 URIs as specified in Section 3.1 of [RFC3987] before they are placed 1482 in the certificate extension. 1484 The semantics of the URL are defined Section 6 of this document. 1486 The choice of id-pe is based on guidance found in Section 4.2.2 of 1487 [RFC5280]: 1489 These extensions may be used to direct applications to on-line 1490 information about the issuer or the subject. 1492 The MUD URL is precisely that: online information about the 1493 particular subject. 1495 In addition, a separate new extension is defined as id-pe-mudsigner. 1496 This contains the subject field of the signing certificate of the MUD 1497 file. Processing of this field is specified in Section 13.2. 1499 The purpose of this signature is to make a claim that the MUD file 1500 found on the server is valid for a given device, independent of any 1501 other factors. There are several security considerations below in 1502 Section 16. 1504 A new content-type id-ct-mud is also defined. While signatures are 1505 detached today, should a MUD file be transmitted as part of a CMS 1506 message, this content-type SHOULD be used. 1508 The new extension is identified as follows: 1510 1511 MUDURLExtnModule-2016 { iso(1) identified-organization(3) dod(6) 1512 internet(1) security(5) mechanisms(5) pkix(7) 1513 id-mod(0) id-mod-mudURLExtn2016(88) } 1514 DEFINITIONS IMPLICIT TAGS ::= BEGIN 1515 -- EXPORTS ALL -- 1517 IMPORTS 1519 -- RFC 5912 1520 EXTENSION 1521 FROM PKIX-CommonTypes-2009 1522 { iso(1) identified-organization(3) dod(6) internet(1) 1523 security(5) mechanisms(5) pkix(7) id-mod(0) 1524 id-mod-pkixCommon-02(57) } 1526 -- RFC 5912 1527 id-ct 1528 FROM PKIXCRMF-2009 1529 { iso(1) identified-organization(3) dod(6) internet(1) 1530 security(5) mechanisms(5) pkix(7) id-mod(0) 1531 id-mod-crmf2005-02(55) } 1533 -- RFC 6268 1534 CONTENT-TYPE 1535 FROM CryptographicMessageSyntax-2010 1536 { iso(1) member-body(2) us(840) rsadsi(113549) 1537 pkcs(1) pkcs-9(9) smime(16) modules(0) id-mod-cms-2009(58) } 1539 -- RFC 5912 1540 id-pe, Name 1541 FROM PKIX1Explicit-2009 1542 { iso(1) identified-organization(3) dod(6) internet(1) 1543 security(5) mechanisms(5) pkix(7) id-mod(0) 1544 id-mod-pkix1-explicit-02(51) } ; 1546 -- 1547 -- Certificate Extensions 1548 -- 1550 MUDCertExtensions EXTENSION ::= 1551 { ext-MUDURL | ext-MUDsigner, ... } 1553 ext-MUDURL EXTENSION ::= 1554 { SYNTAX MUDURLSyntax IDENTIFIED BY id-pe-mud-url } 1556 id-pe-mud-url OBJECT IDENTIFIER ::= { id-pe 25 } 1558 MUDURLSyntax ::= IA5String 1560 ext-MUDsigner EXTENSION ::= 1561 { SYNTAX MUDsignerSyntax IDENTIFIED BY id-pe-mudsigner } 1563 id-pe-mudsigner OBJECT IDENTIFIER ::= { id-pe TBD1 } 1565 MUDsignerSyntax ::= Name 1567 -- 1568 -- CMS Content Types 1569 -- 1571 MUDContentTypes CONTENT-TYPE ::= 1572 { ct-mud, ... } 1574 ct-mud CONTENT-TYPE ::= 1575 { -- directly include the content 1576 IDENTIFIED BY id-ct-mudtype } 1577 -- The binary data that is in the form 1578 -- 'application/mud+json" is directly encoded as the 1579 -- signed data. No additional ASN.1 encoding is added. 1581 id-ct-mudtype OBJECT IDENTIFIER ::= { id-ct TBD2 } 1583 END 1584 1586 While this extension can appear in either an 802.AR manufacturer 1587 certificate (IDevID) or deployment certificate (LDevID), of course it 1588 is not guaranteed in either, nor is it guaranteed to be carried over. 1589 It is RECOMMENDED that MUD manager implementations maintain a table 1590 that maps a Thing to its MUD URL based on IDevIDs. 1592 12. The Manufacturer Usage Description LLDP extension 1594 The IEEE802.1AB Link Layer Discovery Protocol (LLDP) is a one hop 1595 vendor-neutral link layer protocol used by end hosts network Things 1596 for advertising their identity, capabilities, and neighbors on an 1597 IEEE 802 local area network. Its Type-Length-Value (TLV) design 1598 allows for 'vendor-specific' extensions to be defined. IANA has a 1599 registered IEEE 802 organizationally unique identifier (OUI) defined 1600 as documented in [RFC7042]. The MUD LLDP extension uses a subtype 1601 defined in this document to carry the MUD URL. 1603 The LLDP vendor specific frame has the following format: 1605 +--------+--------+----------+---------+-------------- 1606 |TLV Type| len | OUI |subtype | MUDString 1607 | =127 | |= 00 00 5E| = 1 | 1608 |(7 bits)|(9 bits)|(3 octets)|(1 octet)|(1-255 octets) 1609 +--------+--------+----------+---------+-------------- 1610 where: 1612 o TLV Type = 127 indicates a vendor-specific TLV 1614 o len - indicates the TLV string length 1616 o OUI = 00 00 5E is the organizationally unique identifier of IANA 1618 o subtype = 1 (to be assigned by IANA for the MUD URL) 1620 o MUD URL - the length MUST NOT exceed 255 octets 1622 The intent of this extension is to provide both a new Thing 1623 classifier to the network as well as some recommended configuration 1624 to the routers that implement policy. However, it is entirely the 1625 purview of the network system as managed by the network administrator 1626 to decide what to do with this information. The key function of this 1627 extension is simply to identify the type of Thing to the network in a 1628 structured way such that the policy can be easily found with existing 1629 toolsets. 1631 Hosts, routers, or other network elements that implement this option 1632 are intended to have at most one MUD URL associated with them, so 1633 they may transmit at most one MUD URL value. 1635 Hosts, routers, or other network elements that implement this option 1636 may ignore these options or take action based on receipt of these 1637 options. For example they may fill in information in the respective 1638 extensions of the LLDP Management Information Base (LLDP MIB). LLDP 1639 operates in a one-way direction. LLDPDUs are not exchanged as 1640 information requests by one Thing and response sent by another Thing. 1641 The other Things do not acknowledge LLDP information received from a 1642 Thing. No specific network behavior is guaranteed. When a Thing 1643 consumes this extension, it may either forward the URL and relevant 1644 remote Thing information to a MUD manager, or it will retrieve the 1645 usage description by resolving the URL in accordance with normal HTTP 1646 semantics. 1648 13. Creating and Processing of Signed MUD Files 1650 Because MUD files contain information that may be used to configure 1651 network access lists, they are sensitive. To ensure that they have 1652 not been tampered with, it is important that they be signed. We make 1653 use of DER-encoded Cryptographic Message Syntax (CMS) [RFC5652] for 1654 this purpose. 1656 13.1. Creating a MUD file signature 1658 A MUD file MUST be signed using CMS as an opaque binary object. In 1659 order to make successful verification more likely, intermediate 1660 certificates SHOULD be included. The signature is stored at the 1661 location specified in the MUD file. Signatures are transferred using 1662 content-type "application/pkcs7-signature". 1664 For example: 1666 % openssl cms -sign -signer mancertfile -inkey mankey \ 1667 -in mudfile -binary -outform DER -binary \ 1668 -certfile intermediatecert -out mudfile.p7s 1670 Note: A MUD file may need to be re-signed if the signature expires. 1672 13.2. Verifying a MUD file signature 1674 Prior to processing the rest of a MUD file, the MUD manager MUST 1675 retrieve the MUD signature file by retrieving the value of "mud- 1676 signature" and validating the signature across the MUD file. The Key 1677 Usage Extension in the signing certificate MUST be present and have 1678 the bit digitalSignature(0) set. When the id-pe-mudsigner extension 1679 is present in a device's X.509 certificate, the MUD signature file 1680 MUST have been generated by a certificate whose subject matches the 1681 contents of that id-pe-mudsigner extension. If these conditions are 1682 not met, or if it cannot validate the chain of trust to a known trust 1683 anchor, the MUD manager MUST cease processing the MUD file until an 1684 administrator has given approval. 1686 The purpose of the signature on the file is to assign accountability 1687 to an entity, whose reputation can be used to guide administrators on 1688 whether or not to accept a given MUD file. It is already common 1689 place to check web reputation on the location of a server on which a 1690 file resides. While it is likely that the manufacturer will be the 1691 signer of the file, this is not strictly necessary, and may not be 1692 desirable. For one thing, in some environments, integrators may 1693 install their own certificates. For another, what is more important 1694 is the accountability of the recommendation, and not just the 1695 relationship between the Thing and the file. 1697 An example: 1699 % openssl cms -verify -in mudfile.p7s -inform DER -content mudfile 1701 Note the additional step of verifying the common trust root. 1703 14. Extensibility 1705 One of our design goals is to see that MUD files are able to be 1706 understood by as broad a cross-section of systems as is possible. 1707 Coupled with the fact that we have also chosen to leverage existing 1708 mechanisms, we are left with no ability to negotiate extensions and a 1709 limited desire for those extensions in any event. A such, a two-tier 1710 extensibility framework is employed, as follows: 1712 1. At a coarse grain, a protocol version is included in a MUD URL. 1713 This memo specifies MUD version 1. Any and all changes are 1714 entertained when this version is bumped. Transition approaches 1715 between versions would be a matter for discussion in future 1716 versions. 1718 2. At a finer grain, only extensions that would not incur additional 1719 risk to the Thing are permitted. Specifically, adding nodes to 1720 the mud container is permitted with the understanding that such 1721 additions will be ignored by unaware implementations. Any such 1722 extensions SHALL be standardized through the IETF process, and 1723 MUST be named in the "extensions" list. MUD managers MUST ignore 1724 YANG nodes they do not understand and SHOULD create an exception 1725 to be resolved by an administrator, so as to avoid any policy 1726 inconsistencies. 1728 15. Deployment Considerations 1730 Because MUD consists of a number of architectural building blocks, it 1731 is possible to assemble different deployment scenarios. One key 1732 aspect is where to place policy enforcement. In order to protect the 1733 Thing from other Things within a local deployment, policy can be 1734 enforced on the nearest switch or access point. In order to limit 1735 unwanted traffic within a network, it may also be advisable to 1736 enforce policy as close to the Internet as possible. In some 1737 circumstances, policy enforcement may not be available at the closest 1738 hop. At that point, the risk of lateral infection (infection of 1739 devices that reside near one another) is increased to the number of 1740 Things that are able to communicate without protection. 1742 A caution about some of the classes: admission of a Thing into the 1743 "manufacturer" and "same-manufacturer" class may have impact on 1744 access of other Things. Put another way, the admission may grow the 1745 access-list on switches connected to other Things, depending on how 1746 access is managed. Some care should be given on managing that 1747 access-list growth. Alternative methods such as additional network 1748 segmentation can be used to keep that growth within reason. 1750 Because as of this writing MUD is a new concept, one can expect a 1751 great many devices to not have implemented it. It remains a local 1752 deployment decision as to whether a device that is first connected 1753 should be allowed broad or limited access. Furthermore, as mentioned 1754 in the introduction, a deployment may choose to ignore a MUD policy 1755 in its entirety, but simply taken into account the MUD URL as a 1756 classifier to be used as part of a local policy decision. 1758 Finally, please see directly below regarding device lifetimes and use 1759 of domain names. 1761 16. Security Considerations 1763 Based on how a MUD URL is emitted, a Thing may be able to lie about 1764 what it is, thus gaining additional network access. This can happen 1765 in a number of ways when a device emits a MUD URL using DHCP or LLDP, 1766 such as being inappropriately admitted to a class such as "same- 1767 manufacturer", given access to a device such as "my-controller", or 1768 being permitted access to an Internet resource, where such access 1769 would otherwise be disallowed. Whether that is the case will depend 1770 on the deployment. Implementations SHOULD be configurable to 1771 disallow additive access for devices using MUD-URLs that are not 1772 emitted in a secure fashion such as in a certificate. Similarly, 1773 implementations SHOULD NOT grant elevated permissions (beyond those 1774 of devices presenting no MUD policy) to devices which do not strongly 1775 bind their identity to their L2/L3 transmissions. When insecure 1776 methods are used by the MUD Manager, the classes SHOULD NOT contain 1777 devices that use both insecure and secure methods, in order to 1778 prevent privilege escalation attacks, and MUST NOT contain devices 1779 with the same MUD-URL that are derived from both strong and weak 1780 authentication methods. 1782 Devices may forge source (L2/L3) information. Deployments should 1783 apply appropriate protections to bind communications to the 1784 authentication that has taken place. For 802.1X authentication, IEEE 1785 802.1AE (MACsec) [IEEE8021AE] is one means by which this may happen. 1786 A similar approach can be used with 802.11i (WPA2) [IEEE80211i]. 1787 Other means are available with other lower layer technologies. 1788 Implementations using session-oriented access that is not 1789 cryptographically bound should take care to remove state when any 1790 form of break in the session is detected. 1792 A rogue CA may sign a certificate that contains the same subject name 1793 as is listed in the MUDsigner field in the manufacturer certificate, 1794 thus seemingly permitting a substitute MUD file for a device. There 1795 are two mitigations available: first, if the signer changes, this may 1796 be flagged as an exception by the MUD manager. If the MUD file also 1797 changes, the MUD manager SHOULD seek administrator approval (it 1798 should do this in any case). In all circumstances, the MUD manager 1799 MUST maintain a cache of trusted CAs for this purpose. When such a 1800 rogue is discovered, it SHOULD be removed. 1802 Additional mitigations are described below. 1804 When certificates are not present, Things claiming to be of a certain 1805 manufacturer SHOULD NOT be included in that manufacturer grouping 1806 without additional validation of some form. This will be relevant 1807 whenthe MUD manager makes use of primitives such as "manufacturer" 1808 for the purpose of accessing Things of a particular type. Similarly, 1809 network management systems may be able to fingerprint the Thing. In 1810 such cases, the MUD URL can act as a classifier that can be proven or 1811 disproven. Fingerprinting may have other advantages as well: when 1812 802.1AR certificates are used, because they themselves cannot change, 1813 fingerprinting offers the opportunity to add artifacts to the MUD 1814 string in the form of the reserved field discussed in Section 10. 1815 The meaning of such artifacts is left as future work. 1817 MUD managers SHOULD NOT accept a usage description for a Thing with 1818 the same MAC address that has indicated a change of the URL authority 1819 without some additional validation (such as review by a network 1820 administrator). New Things that present some form of unauthenticated 1821 MUD URL SHOULD be validated by some external means when they would be 1822 be given increased network access. 1824 It may be possible for a rogue manufacturer to inappropriately 1825 exercise the MUD file parser, in order to exploit a vulnerability. 1826 There are three recommended approaches to address this threat. The 1827 first is to validate that the signer of the MUD file is known to and 1828 trusted by the MUD manager. The second is to have a system do a 1829 primary scan of the file to ensure that it is both parseable and 1830 believable at some level. MUD files will likely be relatively small, 1831 to start with. The number of ACEs used by any given Thing should be 1832 relatively small as well. It may also be useful to limit retrieval 1833 of MUD URLs to only those sites that are known to have decent web or 1834 domain reputations. 1836 Use of a URL necessitates the use of domain names. If a domain name 1837 changes ownership, the new owner of that domain may be able to 1838 provide MUD files that MUD managers would consider valid. There are 1839 a few approaches that can mitigate this attack. First, MUD managers 1840 SHOULD cache certificates used by the MUD file server. When a new 1841 certificate is retrieved for whatever reason, the MUD manager should 1842 check to see if ownership of the domain has changed. A fair 1843 programmatic approximation of this is when the name servers for the 1844 domain have changed. If the actual MUD file has changed, the MUD 1845 manager MAY check the WHOIS database to see if registration ownership 1846 of a domain has changed. If a change has occurred, or if for some 1847 reason it is not possible to determine whether ownership has changed, 1848 further review may be warranted. Note, this remediation does not 1849 take into account the case of a Thing that was produced long ago and 1850 only recently fielded, or the case where a new MUD manager has been 1851 installed. 1853 The release of a MUD URL by a Thing reveals what the Thing is, and 1854 provides an attacker with guidance on what vulnerabilities may be 1855 present. 1857 While the MUD URL itself is not intended to be unique to a specific 1858 Thing, the release of the URL may aid an observer in identifying 1859 individuals when combined with other information. This is a privacy 1860 consideration. 1862 In addressing both of these concerns, implementors should take into 1863 account what other information they are advertising through 1864 mechanisms such as mDNS[RFC6872], how a Thing might otherwise be 1865 identified, perhaps through how it behaves when it is connected to 1866 the network, whether a Thing is intended to be used by individuals or 1867 carry personal identifying information, and then apply appropriate 1868 data minimization techniques. One approach is to make use of TEAP 1869 [RFC7170] as the means to share information with authorized 1870 components in the network. Network elements may also assist in 1871 limiting access to the MUD URL through the use of mechanisms such as 1872 DHCPv6-Shield [RFC7610]. 1874 There is the risk of the MUD manager itself being spied on to 1875 determine what things are connected to the network. To address this 1876 risk, MUD managers may choose to make use of TLS proxies that they 1877 trust that would aggregate other information. 1879 Please note that the security considerations mentioned in Section 4.7 1880 of [I-D.ietf-netmod-rfc6087bis] are not applicable in this case 1881 because the YANG serialization is not intended to be accessed via 1882 NETCONF. However, for those who try to instantiate this model in a 1883 network element via NETCONF, all objects in each model in this draft 1884 exhibit similar security characteristics as 1885 [I-D.ietf-netmod-acl-model]. The basic purpose of MUD is to 1886 configure access, and so by its very nature can be disruptive if used 1887 by unauthorized parties. 1889 17. IANA Considerations 1891 [ There was originally a registry entry for .well-known suffixes. 1892 This has been removed from the draft and may be marked as deprecated 1893 in the registry. RFC Editor: please remove this comment. ] 1895 17.1. YANG Module Registrations 1897 The following YANG modules are requested to be registered in the 1898 "IANA Module Names" registry: 1900 The ietf-mud module: 1902 o Name: ietf-mud 1904 o URN: urn:ietf:params:xml:ns:yang:ietf-mud 1906 o Prefix: ietf-mud 1908 o Registrant conact: The IESG 1910 o Reference: [RFCXXXX] 1912 The ietf-acldns module: 1914 o Name: ietf-acldns 1916 o URI: urn:ietf:params:xml:ns:yang:ietf-acldns 1918 o Prefix: ietf-acldns 1920 o Registrant: the IESG 1922 o Reference: [RFCXXXX] 1924 17.2. DHCPv4 and DHCPv6 Options 1926 The IANA has allocated option 161 in the Dynamic Host Configuration 1927 Protocol (DHCP) and Bootstrap Protocol (BOOTP) Parameters registry 1928 for the MUD DHCPv4 option, and option 112 for DHCPv6, as described in 1929 Section 10. 1931 17.3. PKIX Extensions 1933 IANA is kindly requested to make the following assignments for: 1935 o The MUDURLExtnModule-2016 ASN.1 module in the "SMI Security for 1936 PKIX Module Identifier" registry (1.3.6.1.5.5.7.0). 1938 o id-pe-mud-url object identifier from the "SMI Security for PKIX 1939 Certificate Extension" registry (1.3.6.1.5.5.7.1). 1941 o id-pe-mudsigner object identifier from the "SMI Security for PKIX 1942 Certificate Extension" registry (TBD1). 1944 o id-ct-mudtype object identifier from the "SMI Security for S/MIME 1945 CMS Content Type" registry (TBD2). 1947 The use of these values is specified in Section 11. 1949 17.4. MIME Media-type Registration for MUD files 1951 The following media-type is defined for transfer of MUD file: 1953 o Type name: application 1954 o Subtype name: mud+json 1955 o Required parameters: n/a 1956 o Optional parameters: n/a 1957 o Encoding considerations: 8bit; application/mud+json values 1958 are represented as a JSON object; UTF-8 encoding MUST be 1959 employed. [RFC3629] 1960 o Security considerations: See Security Considerations 1961 of RFCXXXX and [RFC8259] Section 12. 1962 o Interoperability considerations: n/a 1963 o Published specification: [RFCXXXX] 1964 o Applications that use this media type: MUD managers as 1965 specified by [RFCXXXX]. 1966 o Fragment identifier considerations: n/a 1967 o Additional information: 1969 Magic number(s): n/a 1970 File extension(s): n/a 1971 Macintosh file type code(s): n/a 1973 o Person & email address to contact for further information: 1974 Eliot Lear , Ralph Droms 1975 o Intended usage: COMMON 1976 o Restrictions on usage: none 1977 o Author: 1978 Eliot Lear 1979 Ralph Droms 1980 o Change controller: IESG 1981 o Provisional registration? (standards tree only): No. 1983 17.5. LLDP IANA TLV Subtype Registry 1985 IANA is requested to create a new registry for IANA Link Layer 1986 Discovery Protocol (LLDP) TLV subtype values. The recommended policy 1987 for this registry is Expert Review. The maximum number of entries in 1988 the registry is 256. 1990 IANA is required to populate the initial registry with the value: 1992 LLDP subtype value = 1 (All the other 255 values should be initially 1993 marked as 'Unassigned'.) 1995 Description = the Manufacturer Usage Description (MUD) Uniform 1996 Resource Locator (URL) 1998 Reference = < this document > 2000 17.6. The MUD Well Known Universal Resource Name (URNs) 2002 The following parameter registry is requested to be added in 2003 accordance with [RFC3553] 2005 Registry name: "urn:ietf:params:mud" is requested. 2006 Specification: this document 2007 Repository: this document 2008 Index value: Encoded identically to a TCP/UDP port service 2009 name, as specified in Section 5.1 of [RFC6335] 2011 The following entries should be added to the "urn:ietf:params:mud" 2012 name space: 2014 "urn:ietf:params:mud:dns" refers to the service specified by 2015 [RFC1123]. "urn:ietf:params:mud:ntp" refers to the service specified 2016 by [RFC5905]. 2018 17.7. Extensions Registry 2020 The IANA is requested to establish a registry of extensions as 2021 follows: 2023 Registry name: MUD extensions registry 2024 Registry policy: Standards action 2025 Standard reference: document 2026 Extension name: UTF-8 encoded string, not to exceed 40 characters. 2028 Each extension MUST follow the rules specified in this specification. 2029 As is usual, the IANA issues early allocations based in accordance 2030 with [RFC7120]. 2032 18. Acknowledgments 2034 The authors would like to thank Einar Nilsen-Nygaard, who 2035 singlehandedly updated the model to match the updated ACL model, 2036 Bernie Volz, Tom Gindin, Brian Weis, Sandeep Kumar, Thorsten Dahm, 2037 John Bashinski, Steve Rich, Jim Bieda, Dan Wing, Joe Clarke, Henk 2038 Birkholz, Adam Montville, Jim Schaad, and Robert Sparks for their 2039 valuable advice and reviews. Russ Housley entirely rewrote 2040 Section 11 to be a complete module. Adrian Farrel provided the basis 2041 for privacy considerations text. Kent Watsen provided a thorough 2042 review of the architecture and the YANG model. The remaining errors 2043 in this work are entirely the responsibility of the authors. 2045 19. References 2047 19.1. Normative References 2049 [I-D.ietf-netmod-acl-model] 2050 Jethanandani, M., Huang, L., Agarwal, S., and D. Blair, 2051 "Network Access Control List (ACL) YANG Data Model", 2052 draft-ietf-netmod-acl-model-19 (work in progress), April 2053 2018. 2055 [IEEE8021AB] 2056 Institute for Electrical and Electronics Engineers, "IEEE 2057 Standard for Local and Metropolitan Area Networks-- 2058 Station and Media Access Control Connectivity Discovery", 2059 n.d.. 2061 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 2062 Application and Support", STD 3, RFC 1123, 2063 DOI 10.17487/RFC1123, October 1989, 2064 . 2066 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2067 Requirement Levels", BCP 14, RFC 2119, 2068 DOI 10.17487/RFC2119, March 1997, 2069 . 2071 [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", 2072 RFC 2131, DOI 10.17487/RFC2131, March 1997, 2073 . 2075 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2076 DOI 10.17487/RFC2818, May 2000, 2077 . 2079 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2080 C., and M. Carney, "Dynamic Host Configuration Protocol 2081 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2082 2003, . 2084 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2085 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2086 2003, . 2088 [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. 2089 Levkowetz, Ed., "Extensible Authentication Protocol 2090 (EAP)", RFC 3748, DOI 10.17487/RFC3748, June 2004, 2091 . 2093 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2094 Resource Identifier (URI): Generic Syntax", STD 66, 2095 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2096 . 2098 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 2099 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 2100 January 2005, . 2102 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2103 Specifications: ABNF", STD 68, RFC 5234, 2104 DOI 10.17487/RFC5234, January 2008, 2105 . 2107 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2108 Housley, R., and W. Polk, "Internet X.509 Public Key 2109 Infrastructure Certificate and Certificate Revocation List 2110 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2111 . 2113 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2114 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2115 . 2117 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 2118 "Network Time Protocol Version 4: Protocol and Algorithms 2119 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 2120 . 2122 [RFC5911] Hoffman, P. and J. Schaad, "New ASN.1 Modules for 2123 Cryptographic Message Syntax (CMS) and S/MIME", RFC 5911, 2124 DOI 10.17487/RFC5911, June 2010, 2125 . 2127 [RFC5912] Hoffman, P. and J. Schaad, "New ASN.1 Modules for the 2128 Public Key Infrastructure Using X.509 (PKIX)", RFC 5912, 2129 DOI 10.17487/RFC5912, June 2010, 2130 . 2132 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 2133 Cheshire, "Internet Assigned Numbers Authority (IANA) 2134 Procedures for the Management of the Service Name and 2135 Transport Protocol Port Number Registry", BCP 165, 2136 RFC 6335, DOI 10.17487/RFC6335, August 2011, 2137 . 2139 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2140 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2141 . 2143 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 2144 Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 2145 2014, . 2147 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2148 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2149 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2150 . 2152 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2153 Protocol (HTTP/1.1): Message Syntax and Routing", 2154 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2155 . 2157 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2158 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2159 DOI 10.17487/RFC7231, June 2014, 2160 . 2162 [RFC7610] Gont, F., Liu, W., and G. Van de Velde, "DHCPv6-Shield: 2163 Protecting against Rogue DHCPv6 Servers", BCP 199, 2164 RFC 7610, DOI 10.17487/RFC7610, August 2015, 2165 . 2167 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2168 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2169 . 2171 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2172 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2173 . 2175 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2176 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2177 May 2017, . 2179 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2180 Interchange Format", STD 90, RFC 8259, 2181 DOI 10.17487/RFC8259, December 2017, 2182 . 2184 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2185 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2186 . 2188 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A 2189 YANG Data Model for Hardware Management", RFC 8348, 2190 DOI 10.17487/RFC8348, March 2018, 2191 . 2193 19.2. Informative References 2195 [FW95] Chapman, D. and E. Zwicky, "Building Internet Firewalls", 2196 January 1995. 2198 [I-D.ietf-netmod-rfc6087bis] 2199 Bierman, A., "Guidelines for Authors and Reviewers of YANG 2200 Data Model Documents", draft-ietf-netmod-rfc6087bis-20 2201 (work in progress), March 2018. 2203 [IEEE80211i] 2204 Institute for Electrical and Electronics Engineers, "IEEE 2205 Standard for information technology-Telecommunications and 2206 information exchange between systems-Local and 2207 metropolitan area networks-Specific requirements-Part 11- 2208 Wireless LAN Medium Access Control (MAC) and Physical 2209 Layer (PHY) specifications- Amendment 6- Medium Access 2210 Control (MAC) Security Enhancements", 2004. 2212 [IEEE8021AE] 2213 Institute for Electrical and Electronics Engineers, "IEEE 2214 Standard for Local and Metropolitan Area Networks- Media 2215 Access Control (MAC) Security", 2006. 2217 [IEEE8021AR] 2218 Institute for Electrical and Electronics Engineers, 2219 "Secure Device Identity", 1998. 2221 [IEEE8021X] 2222 Institute for Electrical and Electronics Engineers, "IEEE 2223 Standard for Local and metropolitan area networks--Port- 2224 Based Network Access Control", 2010. 2226 [ISO.8601.1988] 2227 International Organization for Standardization, "Data 2228 elements and interchange formats - Information interchange 2229 - Representation of dates and times", ISO Standard 8601, 2230 June 1988. 2232 [RFC1984] IAB and IESG, "IAB and IESG Statement on Cryptographic 2233 Technology and the Internet", BCP 200, RFC 1984, 2234 DOI 10.17487/RFC1984, August 1996, 2235 . 2237 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2238 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2239 . 2241 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 2242 IETF URN Sub-namespace for Registered Protocol 2243 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 2244 2003, . 2246 [RFC6092] Woodyatt, J., Ed., "Recommended Simple Security 2247 Capabilities in Customer Premises Equipment (CPE) for 2248 Providing Residential IPv6 Internet Service", RFC 6092, 2249 DOI 10.17487/RFC6092, January 2011, 2250 . 2252 [RFC6872] Gurbani, V., Ed., Burger, E., Ed., Anjali, T., Abdelnur, 2253 H., and O. Festor, "The Common Log Format (CLF) for the 2254 Session Initiation Protocol (SIP): Framework and 2255 Information Model", RFC 6872, DOI 10.17487/RFC6872, 2256 February 2013, . 2258 [RFC7042] Eastlake 3rd, D. and J. Abley, "IANA Considerations and 2259 IETF Protocol and Documentation Usage for IEEE 802 2260 Parameters", BCP 141, RFC 7042, DOI 10.17487/RFC7042, 2261 October 2013, . 2263 [RFC7170] Zhou, H., Cam-Winget, N., Salowey, J., and S. Hanna, 2264 "Tunnel Extensible Authentication Protocol (TEAP) Version 2265 1", RFC 7170, DOI 10.17487/RFC7170, May 2014, 2266 . 2268 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2269 Application Protocol (CoAP)", RFC 7252, 2270 DOI 10.17487/RFC7252, June 2014, 2271 . 2273 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 2274 "Architectural Considerations in Smart Object Networking", 2275 RFC 7452, DOI 10.17487/RFC7452, March 2015, 2276 . 2278 [RFC7488] Boucadair, M., Penno, R., Wing, D., Patil, P., and T. 2279 Reddy, "Port Control Protocol (PCP) Server Selection", 2280 RFC 7488, DOI 10.17487/RFC7488, March 2015, 2281 . 2283 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 2284 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 2285 . 2287 Appendix A. Changes from Earlier Versions 2289 RFC Editor to remove this section prior to publication. 2291 Draft -19: * Edits after discussion with apps area to address 2292 reserved field for the future. * Correct systeminfo to be utf8. * 2293 Remove "hardware-rev" from list. 2295 Draft -18: * Correct an error in the augment statement * Changes to 2296 the ACL model re ports. 2298 Draft -17: 2300 o One editorial. 2302 Draft -16 2304 o add mud-signature element based on review comments 2306 o redo mud-url 2308 o make clear that systeminfo uses UTF8 2310 Draft -13 to -14: 2312 o Final WGLC comments and review comments 2314 o Move version from MUD-URL to Model 2316 o Have MUD-URL in model 2318 o Update based on update to draft-ietf-netmod-acl-model 2320 o Point to tree diagram draft instead of 6087bis. 2322 Draft -12 to -13: 2324 o Additional WGLC comments 2326 Draft -10 to -12: 2328 These are based on WGLC comments: 2330 o Correct examples based on ACL model changes. 2332 o Change ordering nodes. 2334 o Additional explanatory text around systeminfo. 2336 o Change ordering in examples. 2338 o Make it VERY VERY VERY VERY clear that these are recommendations, 2339 not mandates. 2341 o DHCP -> NTP in some of the intro text. 2343 o Remove masa-server 2345 o "Things" to "network elements" in a few key places. 2347 o Reference to JSON YANG RFC added. 2349 Draft -10 to -11: 2351 o Example corrections 2353 o Typo 2355 o Fix two lists. 2357 o Addition of 'any-acl' and 'mud-acl' in the list of allowed 2358 features. 2360 o Clarification of what should be in a MUD file. 2362 Draft -09 to -10: 2364 o AD input. 2366 o Correct dates. 2368 o Add compliance sentence as to which ACL module features are 2369 implemented. 2371 Draft -08 to -09: 2373 o Resolution of Security Area review, IoT directorate review, GenART 2374 review, YANG doctors review. 2376 o change of YANG structure to address mandatory nodes. 2378 o Terminology cleanup. 2380 o specify out extra portion of MUD-URL. 2382 o consistency changes. 2384 o improved YANG descriptions. 2386 o Remove extra revisions. 2388 o Track ACL model changes. 2390 o Additional cautions on use of ACL model; further clarifications on 2391 extensions. 2393 Draft -07 to -08: 2395 o a number of editorials corrected. 2397 o definition of MUD file tweaked. 2399 Draft -06 to -07: 2401 o Examples updated. 2403 o Additional clarification for direction-initiated. 2405 o Additional implementation guidance given. 2407 Draft -06 to -07: 2409 o Update models to match new ACL model 2411 o extract directionality from the ACL, introducing a new device 2412 container. 2414 Draft -05 to -06: 2416 o Make clear that this is a component architecture (Polk and Watson) 2418 o Add order of operations (Watson) 2419 o Add extensions leaf-list (Pritikin) 2421 o Remove previous-mud-file (Watson) 2423 o Modify text in last-update (Watson) 2425 o Clarify local networks (Weis, Watson) 2427 o Fix contact info (Watson) 2429 o Terminology clarification (Weis) 2431 o Advice on how to handle LDevIDs (Watson) 2433 o Add deployment considerations (Watson) 2435 o Add some additional text about fingerprinting (Watson) 2437 o Appropriate references to 6087bis (Watson) 2439 o Change systeminfo to a URL to be referenced (Lear) 2441 Draft -04 to -05: * syntax error correction 2443 Draft -03 to -04: * Re-add my-controller 2445 Draft -02 to -03: * Additional IANA updates * Format correction in 2446 YANG. * Add reference to TEAP. 2448 Draft -01 to -02: * Update IANA considerations * Accept Russ Housley 2449 rewrite of X.509 text * Include privacy considerations text * Redo 2450 the URL limit. Still 255 bytes, but now stated in the URL 2451 definition. * Change URI registration to be under urn:ietf:params 2453 Draft -00 to -01: * Fix cert trust text. * change supportInformation 2454 to meta-info * Add an informational element in. * add urn registry 2455 and create first entry * add default elements 2457 Appendix B. Default MUD nodes 2459 What follows is the portion of a MUD file that permits DNS traffic to 2460 a controller that is registered with the URN 2461 "urn:ietf:params:mud:dns" and traffic NTP to a controller that is 2462 registered "urn:ietf:params:mud:ntp". This is considered the default 2463 behavior and the ACEs are in effect appended to whatever other "ace" 2464 entries that a MUD file contains. To block DNS or NTP one repeats 2465 the matching statement but replaces the "forwarding" action "accept" 2466 with "drop". Because ACEs are processed in the order they are 2467 received, the defaults would not be reached. A MUD manager might 2468 further decide to optimize to simply not include the defaults when 2469 they are overridden. 2471 Four "acl" list entries that implement default MUD nodes are listed 2472 below. Two are for IPv4 and two are for IPv6 (one in each direction 2473 for both versions of IP). Note that neither access-list name nor ace 2474 name need be retained or used in any way by local implementations, 2475 but are simply there for completeness' sake. 2477 "ietf-access-control-list:acls": { 2478 "acl": [ 2479 { 2480 "name": "mud-59776-v4to", 2481 "type": "ipv4-acl-type", 2482 "aces": { 2483 "ace": [ 2484 { 2485 "name": "ent0-todev", 2486 "matches": { 2487 "ietf-mud:mud": { 2488 "controller": "urn:ietf:params:mud:dns" 2489 }, 2490 "ipv4": { 2491 "protocol": 17 2492 }, 2493 "udp": { 2494 "source-port": { 2495 "operator": "eq", 2496 "port": 53 2497 } 2498 } 2499 }, 2500 "actions": { 2501 "forwarding": "accept" 2502 } 2503 }, 2504 { 2505 "name": "ent1-todev", 2506 "matches": { 2507 "ietf-mud:mud": { 2508 "controller": "urn:ietf:params:mud:ntp" 2509 }, 2510 "ipv4": { 2511 "protocol": 17 2512 }, 2513 "udp": { 2514 "source-port": { 2515 "operator": "eq", 2516 "port": 123 2517 } 2518 } 2519 }, 2520 "actions": { 2521 "forwarding": "accept" 2522 } 2523 } 2524 ] 2525 } 2526 }, 2527 { 2528 "name": "mud-59776-v4fr", 2529 "type": "ipv4-acl-type", 2530 "aces": { 2531 "ace": [ 2532 { 2533 "name": "ent0-frdev", 2534 "matches": { 2535 "ietf-mud:mud": { 2536 "controller": "urn:ietf:params:mud:dns" 2537 }, 2538 "ipv4": { 2539 "protocol": 17 2540 }, 2541 "udp": { 2542 "destination-port": { 2543 "operator": "eq", 2544 "port": 53 2545 } 2546 } 2547 }, 2548 "actions": { 2549 "forwarding": "accept" 2550 } 2551 }, 2552 { 2553 "name": "ent1-frdev", 2554 "matches": { 2555 "ietf-mud:mud": { 2556 "controller": "urn:ietf:params:mud:ntp" 2557 }, 2558 "ipv4": { 2559 "protocol": 17 2560 }, 2561 "udp": { 2562 "destination-port": { 2563 "operator": "eq", 2564 "port": 123 2565 } 2566 } 2567 }, 2568 "actions": { 2569 "forwarding": "accept" 2570 } 2571 } 2572 ] 2573 } 2574 }, 2575 { 2576 "name": "mud-59776-v6to", 2577 "type": "ipv6-acl-type", 2578 "aces": { 2579 "ace": [ 2580 { 2581 "name": "ent0-todev", 2582 "matches": { 2583 "ietf-mud:mud": { 2584 "controller": "urn:ietf:params:mud:dns" 2585 }, 2586 "ipv6": { 2587 "protocol": 17 2588 }, 2589 "udp": { 2590 "source-port": { 2591 "operator": "eq", 2592 "port": 53 2593 } 2594 } 2595 }, 2596 "actions": { 2597 "forwarding": "accept" 2598 } 2599 }, 2600 { 2601 "name": "ent1-todev", 2602 "matches": { 2603 "ietf-mud:mud": { 2604 "controller": "urn:ietf:params:mud:ntp" 2605 }, 2606 "ipv6": { 2607 "protocol": 17 2608 }, 2609 "udp": { 2610 "source-port": { 2611 "operator": "eq", 2612 "port": 123 2613 } 2614 } 2615 }, 2616 "actions": { 2617 "forwarding": "accept" 2618 } 2619 } 2620 ] 2621 } 2622 }, 2623 { 2624 "name": "mud-59776-v6fr", 2625 "type": "ipv6-acl-type", 2626 "aces": { 2627 "ace": [ 2628 { 2629 "name": "ent0-frdev", 2630 "matches": { 2631 "ietf-mud:mud": { 2632 "controller": "urn:ietf:params:mud:dns" 2633 }, 2634 "ipv6": { 2635 "protocol": 17 2636 }, 2637 "udp": { 2638 "destination-port": { 2639 "operator": "eq", 2640 "port": 53 2641 } 2642 } 2643 }, 2644 "actions": { 2645 "forwarding": "accept" 2646 } 2647 }, 2648 { 2649 "name": "ent1-frdev", 2650 "matches": { 2651 "ietf-mud:mud": { 2652 "controller": "urn:ietf:params:mud:ntp" 2653 }, 2654 "ipv6": { 2655 "protocol": 17 2656 }, 2657 "udp": { 2658 "destination-port": { 2659 "operator": "eq", 2660 "port": 123 2661 } 2662 } 2663 }, 2664 "actions": { 2665 "forwarding": "accept" 2666 } 2667 } 2668 ] 2669 } 2670 } 2671 ] 2672 } 2674 Appendix C. A Sample Extension: DETNET-indicator 2676 In this sample extension we augment the core MUD model to indicate 2677 whether the device implements DETNET. If a device claims not to use 2678 DETNET, but then later attempts to do so, a notification or exception 2679 might be generated. Note that this example is intended only for 2680 illustrative purposes. 2682 Extension Name: "Example-Extension" (to be used in the extensions list) 2683 Standard: this document (but do not register the example) 2685 This extension augments the MUD model to include a single node, using 2686 the following sample module that has the following tree structure: 2688 module: ietf-mud-detext-example 2689 augment /ietf-mud:mud: 2690 +--rw is-detnet-required? boolean 2692 The model is defined as follows: 2694 file "ietf-mud-detext-example@2018-06-15.yang" 2695 module ietf-mud-detext-example { 2696 yang-version 1.1; 2697 namespace "urn:ietf:params:xml:ns:yang:ietf-mud-detext-example"; 2698 prefix ietf-mud-detext-example; 2700 import ietf-mud { 2701 prefix ietf-mud; 2702 } 2703 organization 2704 "IETF OPSAWG (Ops Area) Working Group"; 2705 contact 2706 "WG Web: http://tools.ietf.org/wg/opsawg/ 2707 WG List: opsawg@ietf.org 2708 Author: Eliot Lear 2709 lear@cisco.com 2710 Author: Ralph Droms 2711 rdroms@gmail.com 2712 Author: Dan Romascanu 2713 dromasca@gmail.com 2715 "; 2716 description 2717 "Sample extension to a MUD module to indicate a need 2718 for DETNET support."; 2720 revision 2018-06-15 { 2721 description 2722 "Initial revision."; 2723 reference 2724 "RFC XXXX: Manufacturer Usage Description 2725 Specification"; 2726 } 2728 augment "/ietf-mud:mud" { 2729 description 2730 "This adds a simple extension for a manufacturer 2731 to indicate whether DETNET is required by a 2732 device."; 2733 leaf is-detnet-required { 2734 type boolean; 2735 description 2736 "This value will equal true if a device requires 2737 detnet to properly function"; 2738 } 2739 } 2740 } 2741 2743 Using the previous example, we now show how the extension would be 2744 expressed: 2746 { 2747 "ietf-mud:mud": { 2748 "mud-version": 1, 2749 "mud-url": "https://lighting.example.com/lightbulb2000", 2750 "last-update": "2018-03-02T11:20:51+01:00", 2751 "cache-validity": 48, 2752 "extensions": [ 2753 "ietf-mud-detext-example" 2754 ], 2755 "ietf-mud-detext-example:is-detnet-required": "false", 2756 "is-supported": true, 2757 "systeminfo": "The BMS Example Lightbulb", 2758 "from-device-policy": { 2759 "access-lists": { 2760 "access-list": [ 2761 { 2762 "name": "mud-76100-v6fr" 2763 } 2764 ] 2765 } 2766 }, 2767 "to-device-policy": { 2768 "access-lists": { 2769 "access-list": [ 2770 { 2771 "name": "mud-76100-v6to" 2772 } 2773 ] 2774 } 2775 } 2776 }, 2777 "ietf-access-control-list:acls": { 2778 "acl": [ 2779 { 2780 "name": "mud-76100-v6to", 2781 "type": "ipv6-acl-type", 2782 "aces": { 2783 "ace": [ 2784 { 2785 "name": "cl0-todev", 2786 "matches": { 2787 "ipv6": { 2788 "ietf-acldns:src-dnsname": "test.example.com", 2789 "protocol": 6 2790 }, 2791 "tcp": { 2792 "ietf-mud:direction-initiated": "from-device", 2793 "source-port": { 2794 "operator": "eq", 2795 "port": 443 2796 } 2797 } 2798 }, 2799 "actions": { 2800 "forwarding": "accept" 2801 } 2802 } 2803 ] 2804 } 2805 }, 2806 { 2807 "name": "mud-76100-v6fr", 2808 "type": "ipv6-acl-type", 2809 "aces": { 2810 "ace": [ 2811 { 2812 "name": "cl0-frdev", 2813 "matches": { 2814 "ipv6": { 2815 "ietf-acldns:dst-dnsname": "test.example.com", 2816 "protocol": 6 2817 }, 2818 "tcp": { 2819 "ietf-mud:direction-initiated": "from-device", 2820 "destination-port": { 2821 "operator": "eq", 2822 "port": 443 2823 } 2824 } 2825 }, 2826 "actions": { 2827 "forwarding": "accept" 2828 } 2829 } 2830 ] 2831 } 2832 } 2833 ] 2834 } 2835 } 2837 Authors' Addresses 2838 Eliot Lear 2839 Cisco Systems 2840 Richtistrasse 7 2841 Wallisellen CH-8304 2842 Switzerland 2844 Phone: +41 44 878 9200 2845 Email: lear@cisco.com 2847 Ralph Droms 2848 Google 2849 355 Main St., 5th Floor 2850 Cambridge 2852 Phone: +1 978 376 3731 2853 Email: rdroms@gmail.com 2855 Dan Romascanu 2857 Phone: +972 54 5555347 2858 Email: dromasca@gmail.com