RFC 8520
Manufacturer Usage Description Specification
Internet Engineering Task Force (IETF) E. Lear Request for Comments: 8520 Cisco Systems Category: Standards Track R. Droms ISSN: 2070-1721 Google D. Romascanu March 2019 Manufacturer Usage Description SpecificationAbstract
This memo specifies a component-based architecture for Manufacturer Usage Descriptions (MUDs). The goal of MUD is to provide a means for end devices to signal to the network what sort of access and network functionality they require to properly function. The initial focus is on access control. Later work can delve into other aspects. This memo specifies two YANG modules, IPv4 and IPv6 DHCP options, a Link Layer Discovery Protocol (LLDP) TLV, a URL, an X.509 certificate extension, and a means to sign and verify the descriptions. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8520.
Copyright Notice Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. What MUD Doesn't Do . . . . . . . . . . . . . . . . . . . 5 1.2. A Simple Example . . . . . . . . . . . . . . . . . . . . 5 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.4. Determining Intended Use . . . . . . . . . . . . . . . . 6 1.5. Finding a Policy: The MUD URL . . . . . . . . . . . . . . 7 1.6. Processing of the MUD URL . . . . . . . . . . . . . . . . 8 1.7. Types of Policies . . . . . . . . . . . . . . . . . . . . 8 1.8. The Manufacturer Usage Description Architecture . . . . . 10 1.9. Order of Operations . . . . . . . . . . . . . . . . . . . 12 2. The MUD Model and Semantic Meaning . . . . . . . . . . . . . 12 2.1. The IETF-MUD YANG Module . . . . . . . . . . . . . . . . 14 3. MUD Model Definitions for the Root "mud" Container . . . . . 15 3.1. mud-version . . . . . . . . . . . . . . . . . . . . . . . 15 3.2. MUD URL . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.3. to-device-policy and from-device-policy Containers . . . 16 3.4. last-update . . . . . . . . . . . . . . . . . . . . . . . 16 3.5. cache-validity . . . . . . . . . . . . . . . . . . . . . 16 3.6. is-supported . . . . . . . . . . . . . . . . . . . . . . 16 3.7. systeminfo . . . . . . . . . . . . . . . . . . . . . . . 16 3.8. mfg-name, software-rev, model-name, and firmware-rev . . 17 3.9. extensions . . . . . . . . . . . . . . . . . . . . . . . 17 4. Augmentation to the ACL Model . . . . . . . . . . . . . . . . 17 4.1. manufacturer . . . . . . . . . . . . . . . . . . . . . . 17 4.2. same-manufacturer . . . . . . . . . . . . . . . . . . . . 17 4.3. documentation . . . . . . . . . . . . . . . . . . . . . . 18 4.4. model . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.5. local-networks . . . . . . . . . . . . . . . . . . . . . 18 4.6. controller . . . . . . . . . . . . . . . . . . . . . . . 18 4.7. my-controller . . . . . . . . . . . . . . . . . . . . . . 19 4.8. direction-initiated . . . . . . . . . . . . . . . . . . . 19
5. Processing of the MUD File . . . . . . . . . . . . . . . . . 19 6. What Does a MUD URL Look Like? . . . . . . . . . . . . . . . 19 7. The MUD YANG Model . . . . . . . . . . . . . . . . . . . . . 20 8. The Domain Name Extension to the ACL Model . . . . . . . . . 26 8.1. src-dnsname . . . . . . . . . . . . . . . . . . . . . . . 27 8.2. dst-dnsname . . . . . . . . . . . . . . . . . . . . . . . 27 8.3. The ietf-acldns Model . . . . . . . . . . . . . . . . . . 28 9. MUD File Example . . . . . . . . . . . . . . . . . . . . . . 30 10. The MUD URL DHCP Option . . . . . . . . . . . . . . . . . . . 32 10.1. Client Behavior . . . . . . . . . . . . . . . . . . . . 33 10.2. Server Behavior . . . . . . . . . . . . . . . . . . . . 33 10.3. Relay Requirements . . . . . . . . . . . . . . . . . . . 33 11. The Manufacturer Usage Description (MUD) URL X.509 Extension 34 12. The Manufacturer Usage Description LLDP Extension . . . . . . 36 13. The Creating and Processing of Signed MUD Files . . . . . . . 38 13.1. Creating a MUD File Signature . . . . . . . . . . . . . 38 13.2. Verifying a MUD File Signature . . . . . . . . . . . . . 38 14. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 39 15. Deployment Considerations . . . . . . . . . . . . . . . . . . 39 16. Security Considerations . . . . . . . . . . . . . . . . . . . 40 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 17.1. YANG Module Registrations . . . . . . . . . . . . . . . 43 17.2. URI Registrations . . . . . . . . . . . . . . . . . . . 43 17.3. DHCPv4 and DHCPv6 Options . . . . . . . . . . . . . . . 43 17.4. PKIX Extensions . . . . . . . . . . . . . . . . . . . . 43 17.5. Media Type Registration for MUD Files . . . . . . . . . 44 17.6. IANA LLDP TLV Subtype Registry . . . . . . . . . . . . . 45 17.7. The MUD Well-Known Universal Resource Name (URNs) . . . 45 17.8. Extensions Registry . . . . . . . . . . . . . . . . . . 46 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 18.1. Normative References . . . . . . . . . . . . . . . . . . 46 18.2. Informative References . . . . . . . . . . . . . . . . . 49 Appendix A. Default MUD Nodes . . . . . . . . . . . . . . . . . 52 Appendix B. A Sample Extension: DETNET-indicator . . . . . . . . 56 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 60 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 60
1. Introduction
The Internet has largely been constructed for general purpose computers, those devices that may be used for a purpose that is specified by those who own the device. In [RFC1984], it was presumed that an end device would be most capable of protecting itself. This made sense when the typical device was a workstation or a mainframe, and it continues to make sense for general purpose computing devices today, including laptops, smart phones, and tablets. [RFC7452] discusses design patterns for, and poses questions about, smart objects. Let us then posit a group of objects that are specifically not intended to be used for general purpose computing tasks. These devices, which this memo refers to as Things, have a specific purpose. By definition, therefore, all other uses are not intended. If a small number of communication patterns follows from those small number of uses, the combination of these two statements can be restated as a Manufacturer Usage Description (MUD) that can be applied at various points within a network. MUD primarily addresses threats to the device rather than the device as a threat. In some circumstances, however, MUD may offer some protection in the latter case, depending on how the MUD URL is communicated and how devices and their communications are authenticated. We use the notion of "manufacturer" loosely in this context to refer to the entity or organization that will state how a device is intended to be used. For example, in the context of a light bulb, this might indeed be the light bulb manufacturer. In the context of a smarter device that has a built in Linux stack, it might be an integrator of that device. The key points are that the device itself is assumed to serve a limited purpose, and that there exists an organization in the supply chain of that device that will take responsibility for informing the network about that purpose. The intent of MUD is to provide the following: o Substantially reduce the threat surface on a device to those communications intended by the manufacturer. o Provide a means to scale network policies to the ever-increasing number of types of devices in the network. o Provide a means to address at least some vulnerabilities in a way that is faster than the time it might take to update systems. This will be particularly true for systems that are no longer supported.
o Keep the cost of implementation of such a system to the bare
minimum.
o Provide a means of extensibility for manufacturers to express
other device capabilities or requirements.
MUD consists of three architectural building blocks:
o A URL that can be used to locate a description;
o The description itself, including how it is interpreted; and
o A means for local network management systems to retrieve the
description.
MUD is most effective when the network is able to identify in some
way the remote endpoints that Things will talk to.
In this specification, we describe each of these building blocks and
how they are intended to be used together. However, they may also be
used separately, independent of this specification, by local
deployments for their own purposes.
1.1. What MUD Doesn't Do
MUD is not intended to address network authorization of general
purpose computers, as their manufacturers cannot envision a specific
communication pattern to describe. In addition, even those devices
that have a single or small number of uses might have very broad
communication patterns. MUD on its own is not for them either.
Although MUD can provide network administrators with some additional
protection when device vulnerabilities exist, it will never replace
the need for manufacturers to patch vulnerabilities.
Finally, no matter what the manufacturer specifies in a MUD file,
these are not directives, but suggestions. How they are instantiated
locally will depend on many factors and will be ultimately up to the
local network administrator, who must decide what is appropriate in a
given circumstances.
1.2. A Simple Example
A light bulb is intended to light a room. It may be remotely
controlled through the network, and it may make use of a rendezvous
service (which could be accessed by an application on a smart phone).
What we can say about that light bulb, then, is that all other
network access is unwanted. It will not contact a news service, nor
speak to the refrigerator, and it has no need of a printer or other devices. It has no social networking friends. Therefore, applying an access list to it that states it will only connect to the single rendezvous service will not impede performing its function; at the same time, this will allow the network to provide the light bulb and other devices an additional layer of protection.1.3. Terminology
MUD: Manufacturer Usage Description. MUD file: a file containing YANG-based JSON that describes a Thing and associated suggested specific network behavior. MUD file server: a web server that hosts a MUD file. MUD manager: the system that requests and receives the MUD file from the MUD server. After it has processed a MUD file, it may direct changes to relevant network elements. MUD controller: a synonym that has been used in the past for MUD manager. MUD URL: a URL that can be used by the MUD manager to receive the MUD file. Thing: the device emitting a MUD URL. Manufacturer: the entity that configures the Thing to emit the MUD URL and the one who asserts a recommendation in a MUD file. The manufacturer might not always be the entity that constructs a Thing. It could, for instance, be a systems integrator, or even a component provider. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.1.4. Determining Intended Use
The notion of intended use is in itself not new. Network administrators apply access lists every day to allow for only such use. This notion of white listing was well described by Chapman and Zwicky in [FW95]. Profiling systems that make use of heuristics to identify types of systems have existed for years as well.
A Thing could just as easily tell the network what sort of access it requires without going into what sort of system it is. This would, in effect, be the converse of [RFC7488]. In seeking a general solution, however, we assume that a device will implement functionality necessary to fulfill its limited purpose. This is basic economic constraint. Unless the network would refuse access to such a device, its developers would have no reason to provide the network any information. To date, such an assertion has held true.1.5. Finding a Policy: The MUD URL
Our work begins with the device emitting a Universal Resource Locator (URL) [RFC3986]. This URL serves both to classify the device type and to provide a means to locate a policy file. MUD URLs MUST use the "https" scheme [RFC7230]. In this memo, three means are defined to emit the MUD URL, as follows: o A DHCP option [RFC2131] [RFC8415] that the DHCP client uses to inform the DHCP server. The DHCP server may take further actions, such as acting as the MUD manager or passing the MUD URL along to the MUD manager. o An X.509 constraint. The IEEE has developed IEEE 802.1AR [IEEE8021AR] to provide a certificate-based approach to communicate device characteristics, which itself relies on [RFC5280]. The MUD URL extension is non-critical, as required by IEEE 802.1AR. Various means may be used to communicate that certificate, including the Tunnel Extensible Authentication Protocol (TEAP) [RFC7170]. o Finally, a Link Layer Discovery Protocol (LLDP) frame is defined [IEEE8021AB]. It is possible that there may be other means for a MUD URL to be learned by a network. For instance, some devices may already be fielded or have very limited ability to communicate a MUD URL, and yet they can be identified through some means, such as a serial number or a public key. In these cases, manufacturers may be able to map those identifiers to particular MUD URLs (or even the files themselves). Similarly, there may be alternative resolution mechanisms available for situations where Internet connectivity is limited or does not exist. Such mechanisms are not described in this memo, but they are possible. Implementors are encouraged to allow for the flexibility of how MUD URLs may be learned.
1.6. Processing of the MUD URL
MUD managers that are able to do so SHOULD retrieve MUD URLs and signature files as per [RFC7230], using the GET method [RFC7231]. They MUST validate the certificate using the rules in [RFC2818], Section 3.1. Requests for MUD URLs SHOULD include an "Accept" header field ([RFC7231], Section 5.3.2) containing "application/mud+json", an "Accept-Language" header field ([RFC7231], Section 5.3.5), and a "User-Agent" header field ([RFC7231], Section 5.5.3). MUD managers SHOULD automatically process 3xx response status codes. If a MUD manager is not able to fetch a MUD URL, other means MAY be used to import MUD files and associated signature files. So long as the signature of the file can be validated, the file can be used. In such environments, controllers SHOULD warn administrators when cache- validity expiry is approaching so that they may check for new files. It may not be possible for a MUD manager to retrieve a MUD file at any given time. Should a MUD manager fail to retrieve a MUD file, it SHOULD consider the existing one safe to use, at least for a time. After some period, it SHOULD log that it has been unable to retrieve the file. There may be very good reasons for such failures, including the possibility that the MUD manager is in an offline environment, the local Internet connection has failed, or the remote Internet connection has failed. It is also possible that an attacker is attempting to interfere with the deployment of a device. How to handle such circumstances is a local decision.1.7. Types of Policies
When the MUD URL is resolved, the MUD manager retrieves a file that describes what sort of communications a device is designed to have. The manufacturer may specify either specific hosts for cloud-based services or certain classes for access within an operational network. An example of a class might be "devices of a specified manufacturer type", where the manufacturer type itself is indicated simply by the authority component (e.g., the domain name) of the MUD URL. Another example might be to allow or disallow local access. Just like other policies, these may be combined. For example: o Allow access to devices of the same manufacturer o Allow access to and from controllers via the Constrained Application Protocol (COAP) [RFC7252]
o Allow access to local DNS/NTP o Deny all other access A printer might have a description that states: o Allow access for port IPP or port LPD o Allow local access for port HTTP o Deny all other access In this way, anyone can print to the printer, but local access would be required for the management interface. The files that are retrieved are intended to be closely aligned to existing network architectures so that they are easy to deploy. We make use of YANG [RFC7950] because it provides accurate and adequate models for use by network devices. JSON [RFC8259] is used as a serialization format for compactness and readability, relative to XML. Other formats may be chosen with later versions of MUD. While the policy examples given here focus on access control, this is not intended to be the sole focus. By structuring the model described in this document with clear extension points, other descriptions could be included. One that often comes to mind is quality of service. The YANG modules specified here are extensions of [RFC8519]. The extensions to this model allow for a manufacturer to express classes of systems that a manufacturer would find necessary for the proper function of the device. Two modules are specified. The first module specifies a means for domain names to be used in Access Control Lists (ACLs) so that devices that have their controllers in the cloud may be appropriately authorized with domain names, where the mapping of those names to addresses may rapidly change. The other module abstracts away IP addresses into certain classes that are instantiated into actual IP addresses through local processing. Through these classes, manufacturers can specify how the device is designed to communicate, so that network elements can be configured by local systems that have local topological knowledge. That is, the deployment populates the classes that the manufacturer specifies. The abstractions below map to zero or more hosts, as follows: Manufacturer: A device made by a particular manufacturer, as identified by the authority component of its MUD URL.
same-manufacturer: Devices that have the same authority component of
their MUD URL.
controller: Devices that the local network administrator admits to
the particular class.
my-controller: Devices intended to serve as controllers for the MUD
URL that the Thing emitted.
local: The class of IP addresses that are scoped within some
administrative boundary. By default, it is suggested that this be
the local subnet.
The "manufacturer" classes can be easily specified by the
manufacturer, whereas controller classes are initially envisioned to
be specified by the administrator.
Because manufacturers do not know who will be using their devices, it
is important for functionality referenced in usage descriptions to be
relatively ubiquitous and mature. For these reasons, the YANG-based
configuration in a MUD file is limited to the modules either
specified or referenced in this document, or specified in documented
extensions.
1.8. The Manufacturer Usage Description Architecture
With these components laid out, we now have the basis for an
architecture. This leads us to ASCII art.
.......................................
. ____________ . _____________
. | | . | |
. | MUD |-->get URL-->| MUD |
. | Manager | .(https) | File Server |
. End system network |____________|<-MUD file<-<|_____________|
. . .
. . .
. _______ _________ .
.| | (DHCP et al.) | router | .
.| Thing |---->MUD URL-->| or | .
.|_______| | switch | .
. |_________| .
.......................................
Figure 1: MUD Architecture
In the above diagram, the switch or router collects MUD URLs and forwards them to the MUD manager (a network management system) for processing. This happens in different ways, depending on how the URL is communicated. For instance, in the case of DHCP, the DHCP server might receive the URL and then process it. In the case of IEEE 802.1X [IEEE8021X], the switch would carry the URL via a certificate to the authentication server via the Extensible Authentication Protocol (EAP) over Radius [RFC3748], which would then process it. One method to do this is TEAP, as described in [RFC7170]. The certificate extension is described below. The information returned by the MUD file server is valid for as long as the Thing is connected. There is no expiry. However, if the MUD manager has detected that the MUD file for a Thing has changed, it SHOULD update the policy expeditiously, taking into account whatever approval flow is required in a deployment. In this way, new recommendations from the manufacturer can be processed in a timely fashion. The information returned by the MUD file server (a web server) is valid for the duration of the Thing's connection, or as specified in the description. Thus, if the Thing is disconnected, any associated configuration in the switch can be removed. Similarly, from time to time the description may be refreshed, based on new capabilities or communication patterns or vulnerabilities. The web server is typically run by or on behalf of the manufacturer. Its domain name is that of the authority found in the MUD URL. For legacy cases where Things cannot emit a URL, if the switch is able to determine the appropriate URL, it may proxy it. In a trivial case, it may hardcode a MUD URL on a switch port or a map from some available identifier such as an L2 address or certificate hash to a MUD URL. The role of the MUD manager in this environment is to do the following: o receive MUD URLs, o fetch MUD files, o translate abstractions in the MUD files to specific network element configuration, o maintain and update any required mappings of the abstractions, and o update network elements with appropriate configuration.
A MUD manager may be a component of an Authentication, Authorization, and Accounting (AAA) system or a network management system. Communication within those systems and from those systems to network elements is beyond the scope of this memo.1.9. Order of Operations
As mentioned above, MUD contains architectural building blocks, so the order of operation may vary. However, here is one clear intended example: 1. Thing emits a URL. 2. That URL is forwarded to a MUD manager by the nearest switch (how this happens depends on the way in which the MUD URL is emitted). 3. The MUD manager retrieves the MUD file and signature from the MUD file server, assuming it doesn't already have copies. After validating the signature, it may test the URL against a web or domain reputation service, and it may test any hosts within the file against those reputation services, as it deems fit. 4. The MUD manager may query the administrator for permission to add the Thing and associated policy. If the Thing is known or the Thing type is known, it may skip this step. 5. The MUD manager instantiates local configuration based on the abstractions defined in this document. 6. The MUD manager configures the switch nearest the Thing. Other systems may be configured as well. 7. When the Thing disconnects, policy is removed.2. The MUD Model and Semantic Meaning
A MUD file consists of a YANG model instance that has been serialized in JSON [RFC7951]. For purposes of MUD, the nodes that can be modified are access lists as augmented by this model. The MUD file is limited to the serialization of only the following YANG schema: o ietf-access-control-list [RFC8519] o ietf-mud (RFC 8520) o ietf-acldns (RFC 8520)
Extensions may be used to add additional schema. This is described
further on.
To provide the widest possible deployment, publishers of MUD files
SHOULD make use of the abstractions in this memo and avoid the use of
IP addresses. A MUD manager SHOULD NOT automatically implement any
MUD file that contains IP addresses, especially those that might have
local significance. The addressing of one side of an access list is
implicit, based on whether it is applied as to-device-policy or
from-device-policy.
With the exceptions of the "name" of the ACL, "type", "name" of the
Access Control Entry (ACE), and TCP and UDP source and destination
port information, publishers of MUD files SHOULD limit the use of ACL
model leaf nodes expressed to those found in this specification.
Absent any extensions, MUD files are assumed to implement only the
following ACL model features:
o match-on-ipv4, match-on-ipv6, match-on-tcp, match-on-udp,
match-on-icmp
Furthermore, only "accept" or "drop" actions SHOULD be included. A
MUD manager MAY choose to interpret "reject" as "drop". A MUD
manager SHOULD ignore all other actions. This is because
manufacturers do not have sufficient context within a local
deployment to know whether reject is appropriate. That is a decision
that should be left to a network administrator.
Given that MUD does not deal with interfaces, the support of the
"ietf-interfaces" module [RFC8343] is not required. Specifically,
the support of interface-related features and branches (e.g.,
interface-attachment and interface-stats) of the ACL YANG module is
not required.
In fact, MUD managers MAY ignore any particular component of a
description or MAY ignore the description in its entirety, and they
SHOULD carefully inspect all MUD descriptions. Publishers of MUD
files MUST NOT include other nodes except as described in
Section 3.9. See that section for more information.
2.1. The IETF-MUD YANG Module
This module is structured into three parts: o The first component, the "mud" container, holds information that is relevant to retrieval and validity of the MUD file itself, as well as policy intended to and from the Thing. o The second component augments the matching container of the ACL model to add several nodes that are relevant to the MUD URL, or they are otherwise abstracted for use within a local environment. o The third component augments the tcp-acl container of the ACL model to add the ability to match on the direction of initiation of a TCP connection. A valid MUD file will contain two root objects: a "mud" container and an "acls" container. Extensions may add additional root objects as required. As a reminder, when parsing acls, elements within a "match" block are logically ANDed. In general, a single abstraction in a match statement should be used. For instance, it makes little sense to match both "my-controller" and "controller" with an argument, since they are highly unlikely to be the same value. A simplified graphical representation of the data models is used in this document. The meaning of the symbols in these diagrams is explained in [RFC8340].
module: ietf-mud
+--rw mud!
+--rw mud-version uint8
+--rw mud-url inet:uri
+--rw last-update yang:date-and-time
+--rw mud-signature? inet:uri
+--rw cache-validity? uint8
+--rw is-supported boolean
+--rw systeminfo? string
+--rw mfg-name? string
+--rw model-name? string
+--rw firmware-rev? string
+--rw software-rev? string
+--rw documentation? inet:uri
+--rw extensions* string
+--rw from-device-policy
| +--rw acls
| +--rw access-list* [name]
| +--rw name -> /acl:acls/acl/name
+--rw to-device-policy
+--rw acls
+--rw access-list* [name]
+--rw name -> /acl:acls/acl/name
augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches:
+--rw mud
+--rw manufacturer? inet:host
+--rw same-manufacturer? empty
+--rw model? inet:uri
+--rw local-networks? empty
+--rw controller? inet:uri
+--rw my-controller? empty
augment
/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches
/acl:l4/acl:tcp/acl:tcp:
+--rw direction-initiated? direction
(page 15 continued on part 2)
