idnits 2.17.1 draft-ietf-opsawg-mud-22.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 (May 25, 2018) is 2164 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 1968, but not defined == Unused Reference: 'RFC5911' is defined on line 2125, but no explicit reference was found in the text == Unused Reference: 'RFC5912' is defined on line 2130, 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: November 26, 2018 Google 6 D. Romascanu 7 May 25, 2018 9 Manufacturer Usage Description Specification 10 draft-ietf-opsawg-mud-22 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 November 26, 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 . . . . . . . . . 36 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 . . . . . . . . . . . . . . . . . . . . . 41 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 . . . . . . . . . . . . . 43 115 17.6. The MUD Well Known Universal Resource Name (URNs) . . . 43 116 17.7. Extensions Registry . . . . . . . . . . . . . . . . . . 43 117 18. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 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 . . . . . . . . . . . . . . . . . 53 123 Appendix C. A Sample Extension: DETNET-indicator . . . . . . . . 57 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 61 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 it along to the 291 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-05-22.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-05-22 { 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-05-22.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-05-22 { 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 element is defined as id-pe-mudsigner. 1496 This contains the subject field of the signing certificate of the MUD 1497 file. When this element is present, the MUD manager MUST process it. 1498 The signature is said to be valid if the certificate chain is 1499 otherwise validated AND the id-pe-mudsigner field in the device 1500 manufacturer certificate is equal to that of that of the subject of 1501 the certificate used to sign the MUD file. If id-pe-mudsigner is not 1502 present, the MUD manager SHOULD generate an exception and inform the 1503 administrator prior to further processing. 1505 The purpose of this signature is to make a claim that the MUD file 1506 found on the server is valid for a given device, independent of any 1507 other factors. There are several security considerations below in 1508 Section 16. 1510 A new content-type id-ct-mud is also defined. While signatures are 1511 detached today, should a MUD file be transmitted as part of a CMS 1512 message, this content-type SHOULD be used. 1514 The new extension is identified as follows: 1516 1517 MUDURLExtnModule-2016 { iso(1) identified-organization(3) dod(6) 1518 internet(1) security(5) mechanisms(5) pkix(7) 1519 id-mod(0) id-mod-mudURLExtn2016(88) } 1520 DEFINITIONS IMPLICIT TAGS ::= BEGIN 1522 -- EXPORTS ALL -- 1524 IMPORTS 1526 -- RFC 5912 1527 EXTENSION 1528 FROM PKIX-CommonTypes-2009 1529 { iso(1) identified-organization(3) dod(6) internet(1) 1530 security(5) mechanisms(5) pkix(7) id-mod(0) 1531 id-mod-pkixCommon-02(57) } 1533 -- RFC 5912 1534 id-ct 1535 FROM PKIXCRMF-2009 1536 { iso(1) identified-organization(3) dod(6) internet(1) 1537 security(5) mechanisms(5) pkix(7) id-mod(0) 1538 id-mod-crmf2005-02(55) } 1540 -- RFC 6268 1541 CONTENT-TYPE 1542 FROM CryptographicMessageSyntax-2010 1543 { iso(1) member-body(2) us(840) rsadsi(113549) 1544 pkcs(1) pkcs-9(9) smime(16) modules(0) id-mod-cms-2009(58) } 1546 -- RFC 5912 1547 id-pe, Name 1548 FROM PKIX1Explicit-2009 1549 { iso(1) identified-organization(3) dod(6) internet(1) 1550 security(5) mechanisms(5) pkix(7) id-mod(0) 1551 id-mod-pkix1-explicit-02(51) } ; 1553 -- 1554 -- Certificate Extensions 1555 -- 1557 MUDCertExtensions EXTENSION ::= 1558 { ext-MUDURL | ext-MUDsigner, ... } 1560 ext-MUDURL EXTENSION ::= 1561 { SYNTAX MUDURLSyntax IDENTIFIED BY id-pe-mud-url } 1563 id-pe-mud-url OBJECT IDENTIFIER ::= { id-pe 25 } 1564 MUDURLSyntax ::= IA5String 1566 ext-MUDsigner EXTENSION ::= 1567 { SYNTAX MUDsignerSyntax IDENTIFIED BY id-pe-mudsigner } 1569 id-pe-mudsigner OBJECT IDENTIFIER ::= { id-pe TBD } 1571 MUDsignerSyntax ::= Name 1573 -- 1574 -- CMS Content Types 1575 -- 1577 MUDContentTypes CONTENT-TYPE ::= 1578 { ct-mud, ... } 1580 ct-mud CONTENT-TYPE ::= 1581 { -- directly include the content 1582 IDENTIFIED BY id-ct-mudtype } 1583 -- The binary data that is in the form 1584 -- 'application/mud+json" is directly encoded as the 1585 -- signed data. No additional ASN.1 encoding is added. 1587 id-ct-mudtype OBJECT IDENTIFIER ::= { id-ct TBD } 1589 END 1590 1592 While this extension can appear in either an 802.AR manufacturer 1593 certificate (IDevID) or deployment certificate (LDevID), of course it 1594 is not guaranteed in either, nor is it guaranteed to be carried over. 1595 It is RECOMMENDED that MUD manager implementations maintain a table 1596 that maps a Thing to its MUD URL based on IDevIDs. 1598 12. The Manufacturer Usage Description LLDP extension 1600 The IEEE802.1AB Link Layer Discovery Protocol (LLDP) is a one hop 1601 vendor-neutral link layer protocol used by end hosts network Things 1602 for advertising their identity, capabilities, and neighbors on an 1603 IEEE 802 local area network. Its Type-Length-Value (TLV) design 1604 allows for 'vendor-specific' extensions to be defined. IANA has a 1605 registered IEEE 802 organizationally unique identifier (OUI) defined 1606 as documented in [RFC7042]. The MUD LLDP extension uses a subtype 1607 defined in this document to carry the MUD URL. 1609 The LLDP vendor specific frame has the following format: 1611 +--------+--------+----------+---------+-------------- 1612 |TLV Type| len | OUI |subtype | MUDString 1613 | =127 | |= 00 00 5E| = 1 | 1614 |(7 bits)|(9 bits)|(3 octets)|(1 octet)|(1-255 octets) 1615 +--------+--------+----------+---------+-------------- 1617 where: 1619 o TLV Type = 127 indicates a vendor-specific TLV 1621 o len - indicates the TLV string length 1623 o OUI = 00 00 5E is the organizationally unique identifier of IANA 1625 o subtype = 1 (to be assigned by IANA for the MUD URL) 1627 o MUD URL - the length MUST NOT exceed 255 octets 1629 The intent of this extension is to provide both a new Thing 1630 classifier to the network as well as some recommended configuration 1631 to the routers that implement policy. However, it is entirely the 1632 purview of the network system as managed by the network administrator 1633 to decide what to do with this information. The key function of this 1634 extension is simply to identify the type of Thing to the network in a 1635 structured way such that the policy can be easily found with existing 1636 toolsets. 1638 Hosts, routers, or other network elements that implement this option 1639 are intended to have at most one MUD URL associated with them, so 1640 they may transmit at most one MUD URL value. 1642 Hosts, routers, or other network elements that implement this option 1643 may ignore these options or take action based on receipt of these 1644 options. For example they may fill in information in the respective 1645 extensions of the LLDP Management Information Base (LLDP MIB). LLDP 1646 operates in a one-way direction. LLDPDUs are not exchanged as 1647 information requests by one Thing and response sent by another Thing. 1648 The other Things do not acknowledge LLDP information received from a 1649 Thing. No specific network behavior is guaranteed. When a Thing 1650 consumes this extension, it may either forward the URL and relevant 1651 remote Thing information to a MUD manager, or it will retrieve the 1652 usage description by resolving the URL in accordance with normal HTTP 1653 semantics. 1655 13. Creating and Processing of Signed MUD Files 1657 Because MUD files contain information that may be used to configure 1658 network access lists, they are sensitive. To ensure that they have 1659 not been tampered with, it is important that they be signed. We make 1660 use of DER-encoded Cryptographic Message Syntax (CMS) [RFC5652] for 1661 this purpose. 1663 13.1. Creating a MUD file signature 1665 A MUD file MUST be signed using CMS as an opaque binary object. In 1666 order to make successful verification more likely, intermediate 1667 certificates SHOULD be included. The signature is stored at the 1668 location specified in the MUD file. Signatures are transferred using 1669 content-type "application/pkcs7-signature". 1671 For example: 1673 % openssl cms -sign -signer mancertfile -inkey mankey \ 1674 -in mudfile -binary -outform DER -binary \ 1675 -certfile intermediatecert -out mudfile.p7s 1677 Note: A MUD file may need to be re-signed if the signature expires. 1679 13.2. Verifying a MUD file signature 1681 Prior to processing the rest of a MUD file the MUD manager MUST 1682 retrieve the MUD signature file by retrieving the value of "mud- 1683 signature" and validating the signature across the MUD file. The Key 1684 Usage Extension in the MUD file signature MUST have the bit 1685 digitalSignature(0) set. A MUD manager MUST cease processing of that 1686 file it cannot validate the chain of trust to a known trust anchor or 1687 if it cannot validate the id-pe-mudsigner field until an 1688 administrator has given approval. 1690 The purpose of the signature on the file is to assign accountability 1691 to an entity, whose reputation can be used to guide administrators on 1692 whether or not to accept a given MUD file. It is already common 1693 place to check web reputation on the location of a server on which a 1694 file resides. While it is likely that the manufacturer will be the 1695 signer of the file, this is not strictly necessary, and may not be 1696 desirable. For one thing, in some environments, integrators may 1697 install their own certificates. For another, what is more important 1698 is the accountability of the recommendation, and not just the 1699 relationship between the Thing and the file. 1701 An example: 1703 % openssl cms -verify -in mudfile.p7s -inform DER -content mudfile 1705 Note the additional step of verifying the common trust root. 1707 14. Extensibility 1709 One of our design goals is to see that MUD files are able to be 1710 understood by as broad a cross-section of systems as is possible. 1711 Coupled with the fact that we have also chosen to leverage existing 1712 mechanisms, we are left with no ability to negotiate extensions and a 1713 limited desire for those extensions in any event. A such, a two-tier 1714 extensibility framework is employed, as follows: 1716 1. At a coarse grain, a protocol version is included in a MUD URL. 1717 This memo specifies MUD version 1. Any and all changes are 1718 entertained when this version is bumped. Transition approaches 1719 between versions would be a matter for discussion in future 1720 versions. 1722 2. At a finer grain, only extensions that would not incur additional 1723 risk to the Thing are permitted. Specifically, adding nodes to 1724 the mud container is permitted with the understanding that such 1725 additions will be ignored by unaware implementations. Any such 1726 extensions SHALL be standardized through the IETF process, and 1727 MUST be named in the "extensions" list. MUD managers MUST ignore 1728 YANG nodes they do not understand and SHOULD create an exception 1729 to be resolved by an administrator, so as to avoid any policy 1730 inconsistencies. 1732 15. Deployment Considerations 1734 Because MUD consists of a number of architectural building blocks, it 1735 is possible to assemble different deployment scenarios. One key 1736 aspect is where to place policy enforcement. In order to protect the 1737 Thing from other Things within a local deployment, policy can be 1738 enforced on the nearest switch or access point. In order to limit 1739 unwanted traffic within a network, it may also be advisable to 1740 enforce policy as close to the Internet as possible. In some 1741 circumstances, policy enforcement may not be available at the closest 1742 hop. At that point, the risk of lateral infection (infection of 1743 devices that reside near one another) is increased to the number of 1744 Things that are able to communicate without protection. 1746 A caution about some of the classes: admission of a Thing into the 1747 "manufacturer" and "same-manufacturer" class may have impact on 1748 access of other Things. Put another way, the admission may grow the 1749 access-list on switches connected to other Things, depending on how 1750 access is managed. Some care should be given on managing that 1751 access-list growth. Alternative methods such as additional network 1752 segmentation can be used to keep that growth within reason. 1754 Because as of this writing MUD is a new concept, one can expect a 1755 great many devices to not have implemented it. It remains a local 1756 deployment decision as to whether a device that is first connected 1757 should be allowed broad or limited access. Furthermore, as mentioned 1758 in the introduction, a deployment may choose to ignore a MUD policy 1759 in its entirety, but simply taken into account the MUD URL as a 1760 classifier to be used as part of a local policy decision. 1762 Finally, please see directly below regarding device lifetimes and use 1763 of domain names. 1765 16. Security Considerations 1767 Based on how a MUD URL is emitted, a Thing may be able to lie about 1768 what it is, thus gaining additional network access. This happens 1769 when a device emits a MUD URL using DHCP or LLDP, and is either 1770 inappropriately admitted to a class such as "same-manufacturer" or 1771 given access to a device such as "my-controller", where such access 1772 would otherwise be disallowed. Whether that is the case will depend 1773 on the deployment. Implementations SHOULD be configurable to 1774 disallow additive access for devices using MUD-URLs that not emitted 1775 in a secure fashion such as in a certificate. Similarly, 1776 implementations SHOULD NOT grant elevated permissions (beyond those 1777 of devices presenting no MUD policy) to devices which do not strongly 1778 bind their identity to their L2/L3 transmissions. When insecure 1779 methods are used by the MUD Manager, the classes SHOULD NOT contain 1780 devices that use both insecure and secure methods, in order to 1781 prevent privilege escalation attacks, and MUST NOT contain devices 1782 with the same MUD-URL that are derived from both strong and weak 1783 authentication methods. 1785 Devices may forge source (L2/L3) information. Deployments should 1786 apply appropriate protections to bind communications to the 1787 authentication that has taken place. For 802.1X authentication, IEEE 1788 802.1AE (MACsec) [IEEE8021AE] is one means by which this may happen. 1789 A similar approach can be used with 802.11i (WPA2) [IEEE80211i]. 1790 Other means are available with other lower layer technologies. 1791 Implementations using session-oriented access that is not 1792 cryptographically bound should take care to remove state when any 1793 form of break in the session is detected. 1795 A rogue CA may sign a certificate that contains the same subject name 1796 as is listed in the MUDsigner field in the manufacturer certificate, 1797 thus seemingly permitting a substitute MUD file for a device. There 1798 are two mitigations available: first, if the signer changes, this may 1799 be flagged as an exception by the MUD manager. If the MUD file also 1800 changes, the MUD manager SHOULD seek administrator approval (it 1801 should do this in any case). In all circumstances, the MUD manager 1802 MUST maintain a cache of trusted CAs for this purpose. When such a 1803 rogue is discovered, it SHOULD be removed. 1805 Additional mitigations are described below. 1807 When certificates are not present, Things claiming to be of a certain 1808 manufacturer SHOULD NOT be included in that manufacturer grouping 1809 without additional validation of some form. This will be relevant 1810 when it makes use of primitives such as "manufacturer" for the 1811 purpose of accessing Things of a particular type. Similarly, network 1812 management systems may be able to fingerprint the Thing. In such 1813 cases, the MUD URL can act as a classifier that can be proven or 1814 disproven. Fingerprinting may have other advantages as well: when 1815 802.1AR certificates are used, because they themselves cannot change, 1816 fingerprinting offers the opportunity to add artifacts to the MUD 1817 string in the form of the reserved field discussed in Section 10. 1818 The meaning of such artifacts is left as future work. 1820 MUD managers SHOULD NOT accept a usage description for a Thing with 1821 the same MAC address that has indicated a change of the URL authority 1822 without some additional validation (such as review by a network 1823 administrator). New Things that present some form of unauthenticated 1824 MUD URL SHOULD be validated by some external means when they would be 1825 be given increased network access. 1827 It may be possible for a rogue manufacturer to inappropriately 1828 exercise the MUD file parser, in order to exploit a vulnerability. 1829 There are three recommended approaches to address this threat. The 1830 first is to validate that the signer of the MUD file is known to and 1831 trusted by the MUD manager. The second is to have a system do a 1832 primary scan of the file to ensure that it is both parseable and 1833 believable at some level. MUD files will likely be relatively small, 1834 to start with. The number of ACEs used by any given Thing should be 1835 relatively small as well. It may also be useful to limit retrieval 1836 of MUD URLs to only those sites that are known to have decent web or 1837 domain reputations. 1839 Use of a URL necessitates the use of domain names. If a domain name 1840 changes ownership, the new owner of that domain may be able to 1841 provide MUD files that MUD managers would consider valid. There are 1842 a few approaches that can mitigate this attack. First, MUD managers 1843 SHOULD cache certificates used by the MUD file server. When a new 1844 certificate is retrieved for whatever reason, the MUD manager should 1845 check to see if ownership of the domain has changed. A fair 1846 programmatic approximation of this is when the name servers for the 1847 domain have changed. If the actual MUD file has changed, the MUD 1848 manager MAY check the WHOIS database to see if registration ownership 1849 of a domain has changed. If a change has occurred, or if for some 1850 reason it is not possible to determine whether ownership has changed, 1851 further review may be warranted. Note, this remediation does not 1852 take into account the case of a Thing that was produced long ago and 1853 only recently fielded, or the case where a new MUD manager has been 1854 installed. 1856 The release of a MUD URL by a Thing reveals what the Thing is, and 1857 provides an attacker with guidance on what vulnerabilities may be 1858 present. 1860 While the MUD URL itself is not intended to be unique to a specific 1861 Thing, the release of the URL may aid an observer in identifying 1862 individuals when combined with other information. This is a privacy 1863 consideration. 1865 In addressing both of these concerns, implementors should take into 1866 account what other information they are advertising through 1867 mechanisms such as mDNS[RFC6872], how a Thing might otherwise be 1868 identified, perhaps through how it behaves when it is connected to 1869 the network, whether a Thing is intended to be used by individuals or 1870 carry personal identifying information, and then apply appropriate 1871 data minimization techniques. One approach is to make use of TEAP 1872 [RFC7170] as the means to share information with authorized 1873 components in the network. Network elements may also assist in 1874 limiting access to the MUD URL through the use of mechanisms such as 1875 DHCPv6-Shield [RFC7610]. 1877 There is the risk of the MUD manager itself being spied on to 1878 determine what things are connected to the network. To address this 1879 risk, MUD managers may choose to make use of TLS proxies that they 1880 trust that would aggregate other information. 1882 Please note that the security considerations mentioned in Section 4.7 1883 of [I-D.ietf-netmod-rfc6087bis] are not applicable in this case 1884 because the YANG serialization is not intended to be accessed via 1885 NETCONF. However, for those who try to instantiate this model in a 1886 network element via NETCONF, all objects in each model in this draft 1887 exhibit similar security characteristics as 1888 [I-D.ietf-netmod-acl-model]. The basic purpose of MUD is to 1889 configure access, and so by its very nature can be disruptive if used 1890 by unauthorized parties. 1892 17. IANA Considerations 1894 [ There was originally a registry entry for .well-known suffixes. 1895 This has been removed from the draft and may be marked as deprecated 1896 in the registry. RFC Editor: please remove this comment. ] 1898 17.1. YANG Module Registrations 1900 The following YANG modules are requested to be registered in the 1901 "IANA Module Names" registry: 1903 The ietf-mud module: 1905 o Name: ietf-mud 1907 o URN: urn:ietf:params:xml:ns:yang:ietf-mud 1909 o Prefix: ietf-mud 1911 o Registrant conact: The IESG 1913 o Reference: [RFCXXXX] 1915 The ietf-acldns module: 1917 o Name: ietf-acldns 1919 o URI: urn:ietf:params:xml:ns:yang:ietf-acldns 1921 o Prefix: ietf-acldns 1923 o Registrant: the IESG 1925 o Reference: [RFCXXXX] 1927 17.2. DHCPv4 and DHCPv6 Options 1929 The IANA has allocated option 161 in the Dynamic Host Configuration 1930 Protocol (DHCP) and Bootstrap Protocol (BOOTP) Parameters registry 1931 for the MUD DHCPv4 option, and option 112 for DHCPv6, as described in 1932 Section 10. 1934 17.3. PKIX Extensions 1936 IANA is kindly requested to make the following assignments for: 1938 o The MUDURLExtnModule-2016 ASN.1 module in the "SMI Security for 1939 PKIX Module Identifier" registry (1.3.6.1.5.5.7.0). 1941 o id-pe-mud-url object identifier from the "SMI Security for PKIX 1942 Certificate Extension" registry (1.3.6.1.5.5.7.1). 1944 o id-pe-mudsigner object identifier from the "SMI Security for PKIX 1945 Certificate Extension" registry (TBD). 1947 o id-ct-mud object identifier from the "SMI Security for S/MIME CMS 1948 Content Type" registry. 1950 The use of these values is specified in Section 11. 1952 17.4. MIME Media-type Registration for MUD files 1954 The following media-type is defined for transfer of MUD file: 1956 o Type name: application 1957 o Subtype name: mud+json 1958 o Required parameters: n/a 1959 o Optional parameters: n/a 1960 o Encoding considerations: 8bit; application/mud+json values 1961 are represented as a JSON object; UTF-8 encoding MUST be 1962 employed. [RFC3629] 1963 o Security considerations: See Security Considerations 1964 of RFCXXXX and [RFC8259] Section 12. 1965 o Interoperability considerations: n/a 1966 o Published specification: [RFCXXXX] 1967 o Applications that use this media type: MUD managers as 1968 specified by [RFCXXXX]. 1969 o Fragment identifier considerations: n/a 1970 o Additional information: 1972 Magic number(s): n/a 1973 File extension(s): n/a 1974 Macintosh file type code(s): n/a 1976 o Person & email address to contact for further information: 1977 Eliot Lear , Ralph Droms 1978 o Intended usage: COMMON 1979 o Restrictions on usage: none 1980 o Author: 1981 Eliot Lear 1982 Ralph Droms 1983 o Change controller: IESG 1984 o Provisional registration? (standards tree only): No. 1986 17.5. LLDP IANA TLV Subtype Registry 1988 IANA is requested to create a new registry for IANA Link Layer 1989 Discovery Protocol (LLDP) TLV subtype values. The recommended policy 1990 for this registry is Expert Review. The maximum number of entries in 1991 the registry is 256. 1993 IANA is required to populate the initial registry with the value: 1995 LLDP subtype value = 1 (All the other 255 values should be initially 1996 marked as 'Unassigned'.) 1998 Description = the Manufacturer Usage Description (MUD) Uniform 1999 Resource Locator (URL) 2001 Reference = < this document > 2003 17.6. The MUD Well Known Universal Resource Name (URNs) 2005 The following parameter registry is requested to be added in 2006 accordance with [RFC3553] 2008 Registry name: "urn:ietf:params:mud" is requested. 2009 Specification: this document 2010 Repository: this document 2011 Index value: Encoded identically to a TCP/UDP port service 2012 name, as specified in Section 5.1 of [RFC6335] 2014 The following entries should be added to the "urn:ietf:params:mud" 2015 name space: 2017 "urn:ietf:params:mud:dns" refers to the service specified by 2018 [RFC1123]. "urn:ietf:params:mud:ntp" refers to the service specified 2019 by [RFC5905]. 2021 17.7. Extensions Registry 2023 The IANA is requested to establish a registry of extensions as 2024 follows: 2026 Registry name: MUD extensions registry 2027 Registry policy: Standards action 2028 Standard reference: document 2029 Extension name: UTF-8 encoded string, not to exceed 40 characters. 2031 Each extension MUST follow the rules specified in this specification. 2032 As is usual, the IANA issues early allocations based in accordance 2033 with [RFC7120]. 2035 18. Acknowledgments 2037 The authors would like to thank Einar Nilsen-Nygaard, who 2038 singlehandedly updated the model to match the updated ACL model, 2039 Bernie Volz, Tom Gindin, Brian Weis, Sandeep Kumar, Thorsten Dahm, 2040 John Bashinski, Steve Rich, Jim Bieda, Dan Wing, Joe Clarke, Henk 2041 Birkholz, Adam Montville, Jim Schaad, and Robert Sparks for their 2042 valuable advice and reviews. Russ Housley entirely rewrote 2043 Section 11 to be a complete module. Adrian Farrel provided the basis 2044 for privacy considerations text. Kent Watsen provided a thorough 2045 review of the architecture and the YANG model. The remaining errors 2046 in this work are entirely the responsibility of the authors. 2048 19. References 2050 19.1. Normative References 2052 [I-D.ietf-netmod-acl-model] 2053 Jethanandani, M., Huang, L., Agarwal, S., and D. Blair, 2054 "Network Access Control List (ACL) YANG Data Model", 2055 draft-ietf-netmod-acl-model-19 (work in progress), April 2056 2018. 2058 [IEEE8021AB] 2059 Institute for Electrical and Electronics Engineers, "IEEE 2060 Standard for Local and Metropolitan Area Networks-- 2061 Station and Media Access Control Connectivity Discovery", 2062 n.d.. 2064 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 2065 Application and Support", STD 3, RFC 1123, 2066 DOI 10.17487/RFC1123, October 1989, 2067 . 2069 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2070 Requirement Levels", BCP 14, RFC 2119, 2071 DOI 10.17487/RFC2119, March 1997, 2072 . 2074 [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", 2075 RFC 2131, DOI 10.17487/RFC2131, March 1997, 2076 . 2078 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 2079 DOI 10.17487/RFC2818, May 2000, 2080 . 2082 [RFC3315] Droms, R., Ed., Bound, J., Volz, B., Lemon, T., Perkins, 2083 C., and M. Carney, "Dynamic Host Configuration Protocol 2084 for IPv6 (DHCPv6)", RFC 3315, DOI 10.17487/RFC3315, July 2085 2003, . 2087 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2088 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2089 2003, . 2091 [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. 2092 Levkowetz, Ed., "Extensible Authentication Protocol 2093 (EAP)", RFC 3748, DOI 10.17487/RFC3748, June 2004, 2094 . 2096 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2097 Resource Identifier (URI): Generic Syntax", STD 66, 2098 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2099 . 2101 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 2102 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 2103 January 2005, . 2105 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2106 Specifications: ABNF", STD 68, RFC 5234, 2107 DOI 10.17487/RFC5234, January 2008, 2108 . 2110 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2111 Housley, R., and W. Polk, "Internet X.509 Public Key 2112 Infrastructure Certificate and Certificate Revocation List 2113 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2114 . 2116 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2117 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2118 . 2120 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 2121 "Network Time Protocol Version 4: Protocol and Algorithms 2122 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 2123 . 2125 [RFC5911] Hoffman, P. and J. Schaad, "New ASN.1 Modules for 2126 Cryptographic Message Syntax (CMS) and S/MIME", RFC 5911, 2127 DOI 10.17487/RFC5911, June 2010, 2128 . 2130 [RFC5912] Hoffman, P. and J. Schaad, "New ASN.1 Modules for the 2131 Public Key Infrastructure Using X.509 (PKIX)", RFC 5912, 2132 DOI 10.17487/RFC5912, June 2010, 2133 . 2135 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 2136 Cheshire, "Internet Assigned Numbers Authority (IANA) 2137 Procedures for the Management of the Service Name and 2138 Transport Protocol Port Number Registry", BCP 165, 2139 RFC 6335, DOI 10.17487/RFC6335, August 2011, 2140 . 2142 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2143 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2144 . 2146 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 2147 Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 2148 2014, . 2150 [RFC7227] Hankins, D., Mrugalski, T., Siodelski, M., Jiang, S., and 2151 S. Krishnan, "Guidelines for Creating New DHCPv6 Options", 2152 BCP 187, RFC 7227, DOI 10.17487/RFC7227, May 2014, 2153 . 2155 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2156 Protocol (HTTP/1.1): Message Syntax and Routing", 2157 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2158 . 2160 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2161 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2162 DOI 10.17487/RFC7231, June 2014, 2163 . 2165 [RFC7610] Gont, F., Liu, W., and G. Van de Velde, "DHCPv6-Shield: 2166 Protecting against Rogue DHCPv6 Servers", BCP 199, 2167 RFC 7610, DOI 10.17487/RFC7610, August 2015, 2168 . 2170 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2171 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2172 . 2174 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2175 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2176 . 2178 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2179 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2180 May 2017, . 2182 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2183 Interchange Format", STD 90, RFC 8259, 2184 DOI 10.17487/RFC8259, December 2017, 2185 . 2187 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2188 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2189 . 2191 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A 2192 YANG Data Model for Hardware Management", RFC 8348, 2193 DOI 10.17487/RFC8348, March 2018, 2194 . 2196 19.2. Informative References 2198 [FW95] Chapman, D. and E. Zwicky, "Building Internet Firewalls", 2199 January 1995. 2201 [I-D.ietf-netmod-rfc6087bis] 2202 Bierman, A., "Guidelines for Authors and Reviewers of YANG 2203 Data Model Documents", draft-ietf-netmod-rfc6087bis-20 2204 (work in progress), March 2018. 2206 [IEEE80211i] 2207 Institute for Electrical and Electronics Engineers, "IEEE 2208 Standard for information technology-Telecommunications and 2209 information exchange between systems-Local and 2210 metropolitan area networks-Specific requirements-Part 11- 2211 Wireless LAN Medium Access Control (MAC) and Physical 2212 Layer (PHY) specifications- Amendment 6- Medium Access 2213 Control (MAC) Security Enhancements", 2004. 2215 [IEEE8021AE] 2216 Institute for Electrical and Electronics Engineers, "IEEE 2217 Standard for Local and Metropolitan Area Networks- Media 2218 Access Control (MAC) Security", 2006. 2220 [IEEE8021AR] 2221 Institute for Electrical and Electronics Engineers, 2222 "Secure Device Identity", 1998. 2224 [IEEE8021X] 2225 Institute for Electrical and Electronics Engineers, "IEEE 2226 Standard for Local and metropolitan area networks--Port- 2227 Based Network Access Control", 2010. 2229 [ISO.8601.1988] 2230 International Organization for Standardization, "Data 2231 elements and interchange formats - Information interchange 2232 - Representation of dates and times", ISO Standard 8601, 2233 June 1988. 2235 [RFC1984] IAB and IESG, "IAB and IESG Statement on Cryptographic 2236 Technology and the Internet", BCP 200, RFC 1984, 2237 DOI 10.17487/RFC1984, August 1996, 2238 . 2240 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2241 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2242 . 2244 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 2245 IETF URN Sub-namespace for Registered Protocol 2246 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 2247 2003, . 2249 [RFC6092] Woodyatt, J., Ed., "Recommended Simple Security 2250 Capabilities in Customer Premises Equipment (CPE) for 2251 Providing Residential IPv6 Internet Service", RFC 6092, 2252 DOI 10.17487/RFC6092, January 2011, 2253 . 2255 [RFC6872] Gurbani, V., Ed., Burger, E., Ed., Anjali, T., Abdelnur, 2256 H., and O. Festor, "The Common Log Format (CLF) for the 2257 Session Initiation Protocol (SIP): Framework and 2258 Information Model", RFC 6872, DOI 10.17487/RFC6872, 2259 February 2013, . 2261 [RFC7042] Eastlake 3rd, D. and J. Abley, "IANA Considerations and 2262 IETF Protocol and Documentation Usage for IEEE 802 2263 Parameters", BCP 141, RFC 7042, DOI 10.17487/RFC7042, 2264 October 2013, . 2266 [RFC7170] Zhou, H., Cam-Winget, N., Salowey, J., and S. Hanna, 2267 "Tunnel Extensible Authentication Protocol (TEAP) Version 2268 1", RFC 7170, DOI 10.17487/RFC7170, May 2014, 2269 . 2271 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2272 Application Protocol (CoAP)", RFC 7252, 2273 DOI 10.17487/RFC7252, June 2014, 2274 . 2276 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 2277 "Architectural Considerations in Smart Object Networking", 2278 RFC 7452, DOI 10.17487/RFC7452, March 2015, 2279 . 2281 [RFC7488] Boucadair, M., Penno, R., Wing, D., Patil, P., and T. 2282 Reddy, "Port Control Protocol (PCP) Server Selection", 2283 RFC 7488, DOI 10.17487/RFC7488, March 2015, 2284 . 2286 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 2287 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 2288 . 2290 Appendix A. Changes from Earlier Versions 2292 RFC Editor to remove this section prior to publication. 2294 Draft -19: * Edits after discussion with apps area to address 2295 reserved field for the future. * Correct systeminfo to be utf8. * 2296 Remove "hardware-rev" from list. 2298 Draft -18: * Correct an error in the augment statement * Changes to 2299 the ACL model re ports. 2301 Draft -17: 2303 o One editorial. 2305 Draft -16 2307 o add mud-signature element based on review comments 2309 o redo mud-url 2311 o make clear that systeminfo uses UTF8 2313 Draft -13 to -14: 2315 o Final WGLC comments and review comments 2317 o Move version from MUD-URL to Model 2318 o Have MUD-URL in model 2320 o Update based on update to draft-ietf-netmod-acl-model 2322 o Point to tree diagram draft instead of 6087bis. 2324 Draft -12 to -13: 2326 o Additional WGLC comments 2328 Draft -10 to -12: 2330 These are based on WGLC comments: 2332 o Correct examples based on ACL model changes. 2334 o Change ordering nodes. 2336 o Additional explanatory text around systeminfo. 2338 o Change ordering in examples. 2340 o Make it VERY VERY VERY VERY clear that these are recommendations, 2341 not mandates. 2343 o DHCP -> NTP in some of the intro text. 2345 o Remove masa-server 2347 o "Things" to "network elements" in a few key places. 2349 o Reference to JSON YANG RFC added. 2351 Draft -10 to -11: 2353 o Example corrections 2355 o Typo 2357 o Fix two lists. 2359 o Addition of 'any-acl' and 'mud-acl' in the list of allowed 2360 features. 2362 o Clarification of what should be in a MUD file. 2364 Draft -09 to -10: 2366 o AD input. 2368 o Correct dates. 2370 o Add compliance sentence as to which ACL module features are 2371 implemented. 2373 Draft -08 to -09: 2375 o Resolution of Security Area review, IoT directorate review, GenART 2376 review, YANG doctors review. 2378 o change of YANG structure to address mandatory nodes. 2380 o Terminology cleanup. 2382 o specify out extra portion of MUD-URL. 2384 o consistency changes. 2386 o improved YANG descriptions. 2388 o Remove extra revisions. 2390 o Track ACL model changes. 2392 o Additional cautions on use of ACL model; further clarifications on 2393 extensions. 2395 Draft -07 to -08: 2397 o a number of editorials corrected. 2399 o definition of MUD file tweaked. 2401 Draft -06 to -07: 2403 o Examples updated. 2405 o Additional clarification for direction-initiated. 2407 o Additional implementation guidance given. 2409 Draft -06 to -07: 2411 o Update models to match new ACL model 2412 o extract directionality from the ACL, introducing a new device 2413 container. 2415 Draft -05 to -06: 2417 o Make clear that this is a component architecture (Polk and Watson) 2419 o Add order of operations (Watson) 2421 o Add extensions leaf-list (Pritikin) 2423 o Remove previous-mud-file (Watson) 2425 o Modify text in last-update (Watson) 2427 o Clarify local networks (Weis, Watson) 2429 o Fix contact info (Watson) 2431 o Terminology clarification (Weis) 2433 o Advice on how to handle LDevIDs (Watson) 2435 o Add deployment considerations (Watson) 2437 o Add some additional text about fingerprinting (Watson) 2439 o Appropriate references to 6087bis (Watson) 2441 o Change systeminfo to a URL to be referenced (Lear) 2443 Draft -04 to -05: * syntax error correction 2445 Draft -03 to -04: * Re-add my-controller 2447 Draft -02 to -03: * Additional IANA updates * Format correction in 2448 YANG. * Add reference to TEAP. 2450 Draft -01 to -02: * Update IANA considerations * Accept Russ Housley 2451 rewrite of X.509 text * Include privacy considerations text * Redo 2452 the URL limit. Still 255 bytes, but now stated in the URL 2453 definition. * Change URI registration to be under urn:ietf:params 2455 Draft -00 to -01: * Fix cert trust text. * change supportInformation 2456 to meta-info * Add an informational element in. * add urn registry 2457 and create first entry * add default elements 2459 Appendix B. Default MUD nodes 2461 What follows is the portion of a MUD file that permits DNS traffic to 2462 a controller that is registered with the URN 2463 "urn:ietf:params:mud:dns" and traffic NTP to a controller that is 2464 registered "urn:ietf:params:mud:ntp". This is considered the default 2465 behavior and the ACEs are in effect appended to whatever other "ace" 2466 entries that a MUD file contains. To block DNS or NTP one repeats 2467 the matching statement but replaces the "forwarding" action "accept" 2468 with "drop". Because ACEs are processed in the order they are 2469 received, the defaults would not be reached. A MUD manager might 2470 further decide to optimize to simply not include the defaults when 2471 they are overridden. 2473 Four "acl" list entries that implement default MUD nodes are listed 2474 below. Two are for IPv4 and two are for IPv6 (one in each direction 2475 for both versions of IP). Note that neither access-list name nor ace 2476 name need be retained or used in any way by local implementations, 2477 but are simply there for completeness' sake. 2479 "ietf-access-control-list:acls": { 2480 "acl": [ 2481 { 2482 "name": "mud-59776-v4to", 2483 "type": "ipv4-acl-type", 2484 "aces": { 2485 "ace": [ 2486 { 2487 "name": "ent0-todev", 2488 "matches": { 2489 "ietf-mud:mud": { 2490 "controller": "urn:ietf:params:mud:dns" 2491 }, 2492 "ipv4": { 2493 "protocol": 17 2494 }, 2495 "udp": { 2496 "source-port": { 2497 "operator": "eq", 2498 "port": 53 2499 } 2500 } 2501 }, 2502 "actions": { 2503 "forwarding": "accept" 2504 } 2505 }, 2506 { 2507 "name": "ent1-todev", 2508 "matches": { 2509 "ietf-mud:mud": { 2510 "controller": "urn:ietf:params:mud:ntp" 2511 }, 2512 "ipv4": { 2513 "protocol": 17 2514 }, 2515 "udp": { 2516 "source-port": { 2517 "operator": "eq", 2518 "port": 123 2519 } 2520 } 2521 }, 2522 "actions": { 2523 "forwarding": "accept" 2524 } 2525 } 2526 ] 2527 } 2528 }, 2529 { 2530 "name": "mud-59776-v4fr", 2531 "type": "ipv4-acl-type", 2532 "aces": { 2533 "ace": [ 2534 { 2535 "name": "ent0-frdev", 2536 "matches": { 2537 "ietf-mud:mud": { 2538 "controller": "urn:ietf:params:mud:dns" 2539 }, 2540 "ipv4": { 2541 "protocol": 17 2542 }, 2543 "udp": { 2544 "destination-port": { 2545 "operator": "eq", 2546 "port": 53 2547 } 2548 } 2549 }, 2550 "actions": { 2551 "forwarding": "accept" 2552 } 2553 }, 2554 { 2555 "name": "ent1-frdev", 2556 "matches": { 2557 "ietf-mud:mud": { 2558 "controller": "urn:ietf:params:mud:ntp" 2559 }, 2560 "ipv4": { 2561 "protocol": 17 2562 }, 2563 "udp": { 2564 "destination-port": { 2565 "operator": "eq", 2566 "port": 123 2567 } 2568 } 2569 }, 2570 "actions": { 2571 "forwarding": "accept" 2572 } 2573 } 2574 ] 2575 } 2576 }, 2577 { 2578 "name": "mud-59776-v6to", 2579 "type": "ipv6-acl-type", 2580 "aces": { 2581 "ace": [ 2582 { 2583 "name": "ent0-todev", 2584 "matches": { 2585 "ietf-mud:mud": { 2586 "controller": "urn:ietf:params:mud:dns" 2587 }, 2588 "ipv6": { 2589 "protocol": 17 2590 }, 2591 "udp": { 2592 "source-port": { 2593 "operator": "eq", 2594 "port": 53 2595 } 2596 } 2597 }, 2598 "actions": { 2599 "forwarding": "accept" 2600 } 2601 }, 2602 { 2603 "name": "ent1-todev", 2604 "matches": { 2605 "ietf-mud:mud": { 2606 "controller": "urn:ietf:params:mud:ntp" 2607 }, 2608 "ipv6": { 2609 "protocol": 17 2610 }, 2611 "udp": { 2612 "source-port": { 2613 "operator": "eq", 2614 "port": 123 2615 } 2616 } 2617 }, 2618 "actions": { 2619 "forwarding": "accept" 2620 } 2621 } 2622 ] 2623 } 2624 }, 2625 { 2626 "name": "mud-59776-v6fr", 2627 "type": "ipv6-acl-type", 2628 "aces": { 2629 "ace": [ 2630 { 2631 "name": "ent0-frdev", 2632 "matches": { 2633 "ietf-mud:mud": { 2634 "controller": "urn:ietf:params:mud:dns" 2635 }, 2636 "ipv6": { 2637 "protocol": 17 2638 }, 2639 "udp": { 2640 "destination-port": { 2641 "operator": "eq", 2642 "port": 53 2643 } 2644 } 2645 }, 2646 "actions": { 2647 "forwarding": "accept" 2648 } 2649 }, 2650 { 2651 "name": "ent1-frdev", 2652 "matches": { 2653 "ietf-mud:mud": { 2654 "controller": "urn:ietf:params:mud:ntp" 2655 }, 2656 "ipv6": { 2657 "protocol": 17 2658 }, 2659 "udp": { 2660 "destination-port": { 2661 "operator": "eq", 2662 "port": 123 2663 } 2664 } 2665 }, 2666 "actions": { 2667 "forwarding": "accept" 2668 } 2669 } 2670 ] 2671 } 2672 } 2673 ] 2674 } 2676 Appendix C. A Sample Extension: DETNET-indicator 2678 In this sample extension we augment the core MUD model to indicate 2679 whether the device implements DETNET. If a device claims not to use 2680 NETNET, but then later attempts to do so, a notification or exception 2681 might be generated. Note that this example is intended only for 2682 illustrative purposes. 2684 Extension Name: "Example-Extension" (to be used in the extensions list) 2685 Standard: this document (but do not register the example) 2687 This extension augments the MUD model to include a single node, using 2688 the following sample module that has the following tree structure: 2690 module: ietf-mud-detext-example 2691 augment /ietf-mud:mud: 2692 +--rw is-detnet-required? boolean 2694 The model is defined as follows: 2696 file "ietf-mud-detext-example@2018-05-22.yang" 2697 module ietf-mud-detext-example { 2698 yang-version 1.1; 2699 namespace "urn:ietf:params:xml:ns:yang:ietf-mud-detext-example"; 2700 prefix ietf-mud-detext-example; 2702 import ietf-mud { 2703 prefix ietf-mud; 2704 } 2706 organization 2707 "IETF OPSAWG (Ops Area) Working Group"; 2708 contact 2709 "WG Web: http://tools.ietf.org/wg/opsawg/ 2710 WG List: opsawg@ietf.org 2711 Author: Eliot Lear 2712 lear@cisco.com 2713 Author: Ralph Droms 2714 rdroms@gmail.com 2715 Author: Dan Romascanu 2716 dromasca@gmail.com 2718 "; 2719 description 2720 "Sample extension to a MUD module to indicate a need 2721 for DETNET support."; 2723 revision 2018-05-22 { 2724 description 2725 "Initial revision."; 2726 reference 2727 "RFC XXXX: Manufacturer Usage Description 2728 Specification"; 2729 } 2731 augment "/ietf-mud:mud" { 2732 description 2733 "This adds a simple extension for a manufacturer 2734 to indicate whether DETNET is required by a 2735 device."; 2736 leaf is-detnet-required { 2737 type boolean; 2738 description 2739 "This value will equal true if a device requires 2740 detnet to properly function"; 2741 } 2742 } 2743 } 2744 2746 Using the previous example, we now show how the extension would be 2747 expressed: 2749 { 2750 "ietf-mud:mud": { 2751 "mud-version": 1, 2752 "mud-url": "https://lighting.example.com/lightbulb2000", 2753 "last-update": "2018-03-02T11:20:51+01:00", 2754 "cache-validity": 48, 2755 "extensions": [ 2756 "ietf-mud-detext-example" 2757 ], 2758 "ietf-mud-detext-example:is-detnet-required": "false", 2759 "is-supported": true, 2760 "systeminfo": "The BMS Example Lightbulb", 2761 "from-device-policy": { 2762 "access-lists": { 2763 "access-list": [ 2764 { 2765 "name": "mud-76100-v6fr" 2766 } 2767 ] 2768 } 2769 }, 2770 "to-device-policy": { 2771 "access-lists": { 2772 "access-list": [ 2773 { 2774 "name": "mud-76100-v6to" 2775 } 2776 ] 2777 } 2778 } 2779 }, 2780 "ietf-access-control-list:acls": { 2781 "acl": [ 2782 { 2783 "name": "mud-76100-v6to", 2784 "type": "ipv6-acl-type", 2785 "aces": { 2786 "ace": [ 2787 { 2788 "name": "cl0-todev", 2789 "matches": { 2790 "ipv6": { 2791 "ietf-acldns:src-dnsname": "test.example.com", 2792 "protocol": 6 2793 }, 2794 "tcp": { 2795 "ietf-mud:direction-initiated": "from-device", 2796 "source-port": { 2797 "operator": "eq", 2798 "port": 443 2799 } 2800 } 2801 }, 2802 "actions": { 2803 "forwarding": "accept" 2804 } 2805 } 2806 ] 2807 } 2808 }, 2809 { 2810 "name": "mud-76100-v6fr", 2811 "type": "ipv6-acl-type", 2812 "aces": { 2813 "ace": [ 2814 { 2815 "name": "cl0-frdev", 2816 "matches": { 2817 "ipv6": { 2818 "ietf-acldns:dst-dnsname": "test.example.com", 2819 "protocol": 6 2820 }, 2821 "tcp": { 2822 "ietf-mud:direction-initiated": "from-device", 2823 "destination-port": { 2824 "operator": "eq", 2825 "port": 443 2826 } 2827 } 2828 }, 2829 "actions": { 2830 "forwarding": "accept" 2831 } 2832 } 2833 ] 2834 } 2835 } 2836 ] 2837 } 2838 } 2840 Authors' Addresses 2842 Eliot Lear 2843 Cisco Systems 2844 Richtistrasse 7 2845 Wallisellen CH-8304 2846 Switzerland 2848 Phone: +41 44 878 9200 2849 Email: lear@cisco.com 2851 Ralph Droms 2852 Google 2853 355 Main St., 5th Floor 2854 Cambridge 2856 Phone: +1 978 376 3731 2857 Email: rdroms@gmail.com 2859 Dan Romascanu 2861 Phone: +972 54 5555347 2862 Email: dromasca@gmail.com