| Internet-Draft | MUD and CoAP | February 2024 |
| Romann & Damer | Expires 28 August 2024 | [Page] |
This document specifies additional ways for discovering and emitting Manufacturer Usage Descriptions (MUD), especially in constrained environments, utilizing the Constrained Application Protocol (CoAP), CoRE Resource Discovery, and CBOR Web Tokens.¶
This note is to be removed before publishing as an RFC.¶
Status information for this document may be found at https://datatracker.ietf.org/doc/draft-romann-mud-constrained/.¶
Source for this draft and an issue tracker can be found at https://github.com/namib-project/draft-coap-mud.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 28 August 2024.¶
Copyright (c) 2024 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.¶
Manufacturer Usage Descriptions (MUDs), which have been specified in [RFC8520], provide a means for end devices to indicate to the network what sort of access and network functionality they require to properly function. This information enables automatic configuration of firewall appliances to limit device network access to the specified network resources only, which in turn reduces the attack surface for MUD-capable devices.¶
While [RFC8520] contemplates the use of CoAP-related [RFC7252] policies, the MUD URL discovery methods it specifies (DHCP/DHCPv6, LLDP, and X.509 certificates) are not well-suited for constrained environments (e.g., 802.15.4 networks using 6LoWPAN and SLAAC).¶
Therefore, this document introduces a number of additional ways for distributing MUD URLs using CoAP -- such as well-known URIs and parameters for the CoRE Link-Format -- which are better suited for constrained devices. Furthermore, this document specifies a method of encoding MUD URLs in (signed) CBOR Web Tokens (CWTs) [RFC8392], which allows MUD managers to better validate the authenticity of both the URL itself and the associated MUD file.¶
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.¶
This specification re-uses the terminology defined in [RFC8520].¶
Building upon the MUD architecture specified in [RFC8520], there are two main network components relevant for this document: The Thing that wants to obtain network access via a Router or Switch, and the MUD Manager that processes MUD URLs, retrieves MUD files from the MUD file server, and configures other network components accordingly. For the purposes of this document, we extend the MUD architecture with another component: The MUD Receiver. The MUD Receiver is the device responsible for providing and/or performing CoAP requests to resources intended for MUD URL delivery. While this component can also be a part of the same physical device as the MUD Manager or the router/switch, this is not required. Both the Thing and the MUD Receiver can play active roles when using CoAP [RFC7252] for exposing and discovering MUD URLs.¶
A general overview of the MUD architecture adjusted for using CoAP in a constrained environment can be seen in Figure 1. Here, we can see that both the Thing and the MUD Receiver (as the recipient of the MUD URLs) may initiate the MUD discovery process: The Thing can contact and register with MUD URL recipients, e.g. by sending a CoAP POST request via Multicast, addressing a well-known registration endpoint. Conversely, MUD recipients can initiate the discovery process, e.g. by sending a COAP GET request to a well-known URI via multicast.¶
Note that the protocol used for communication between the MUD Receiver and MUD Manager is not specified in this document and implementation-specific.¶
................................................... . __________ Forward valid ____________ . . + + MUD URLs + + . . | MUD +------------>+ MUD | . . | Receiver | | Manager | . . +__________+ +____________+ . . ^ . . . | . . . Provide MUD | End system network . . . URL (CoAP) | . . . __+____ _________ . . + + (DHCP et al.) + router + . . +--- | Thing +---->MUD URL+->+ or | . . |MUD +_______+ | switch | . . |File | +_________+ . . +------+ . ...................................................
Optionally, Things may also provide additional means for proving the authenticity of the MUD URL associated with them. For this purpose, this document specifies how to use CBOR Web Tokens [RFC8392] to include MUD URLs as part of a signed and therefore authenticable token.¶
For this document, we focus on two mechanisms for exposing MUD URLs in a constrained network: On the one hand, Things can expose MUD URLs as a dedicated CoAP resource. This allows them to further secure the payload and provide additional authentication, e.g., by embedding the URL in a CBOR Web Token. On the other hand, Things can include a MUD URL in a list of links, using, for example, the CoRE Link-Format. This Web Linking approach also allows Things to submit MUD URLs to a Directory Service.¶
The first part of this section describes the mechanisms that use a dedicated MUD URL CoAP resource. In the later parts of this section, discovery methods for this MUD URL resource are specified. As part of the discovery method description, a method of providing MUD URLs directly using the CoRE link format is also described.¶
In general, this specification provides two ways by which a MUD URL transmission can be performed using an explicit MUD URL resource.¶
In environments where many Things need to be managed over several subnets and where multicast usage is not desirable, it can be advantageous if the MUD Receiver provides a CoAP resource to perform submissions to and the Things initiate the MUD URL submission. This will be referred to as the "Thing-initiated" submission flow for the remainder of this specification.¶
Conversely, in environments where multicast is not an issue and things might be limited in their capabilities, it can be advantageous if MUD Receivers retrieve the MUD URL from a CoAP resource provided by the Things. In this specification, this will be referred to as the "Receiver-initiated" submission flow.¶
In the Receiver-initiated flow, Things provide a CoAP resource discoverable by the means provided in Section 3.4, which is then requested by MUD Receivers to retrieve the MUD URL.¶
In general, the Receiver-initiated MUD URL flow can be divided into these steps:¶
After joining the network, the Thing starts providing a CoAP resource to retrieve the MUD URL. This resource should provide the MUD URL in one of the formats specified in Section 3.2. It also makes this resource discoverable for MUD Receivers using the methods specified in Section 3.4.¶
The MUD Receiver discovers the resource using the aforementioned methods. Depending on the method of discovery, this could for example happen using a periodic scan for devices, e.g., by periodically requesting a well-known URI using multicast.¶
The MUD Receiver retrieves the discovered resource for devices for which the MUD Controller does not have a current MUD URL. To do so, it performs a CoAP request for the discovered MUD URL resource URI using the GET method, which is responded to with the appropriate payload. Receivers MUST specify their desired payload format using the Accept option Section 5.10.4 of [RFC7252]. During content negotiation, Receivers MUST start with requesting the Content-Format that provides the greatest degree of authenticity protection (i.e., prefer CWTs over plaintext transmission).¶
In the Thing-initiated flow, Things discovery a submission resource provided by the MUD Receiver and submit their MUD URLs to this resource.¶
This flow can be divided into these general steps:¶
The MUD Receiver provides a CoAP resource that Things can submit their MUD URLs to. It also makes itself discoverable for Things using the methods specified in Section 3.4.¶
The Thing connects to the network. After connecting, it discovers the MUD URL submission resource using the aforementioned methods.¶
The Thing submits the MUD URL to the previously discovered URI. To do so, it performs a CoAP request to the discovered URI with the POST method. The MUD URL is contained as the message payload in this request using one of the content formats defined in Section 3.2. Receivers MAY be configured to limit the accepted Content-Formats to ones that provide some level of authenticity for the MUD URL based on policy. However, receiver implementations MUST also support unauthenticated MUD URL transmissions if no policy forbids it.¶
For the purposes of this specification, we will define two formats for transmitting MUD URLs, which are suitable for different environments. MUD Receivers that conform to this specification MUST support both formats.¶
The easiest method of transmitting MUD URLs is using a plain text payload containing only the MUD URL. While this method has the advantage of simplicity, it does not contain any additional information that could be used by a MUD Receiver to authenticate the supplied MUD URL.¶
CoAP requests and responses that use this format MUST use the Content-Format option with the value corresponding to the "application/mud-url+plain" media type.¶
Previous methods of transmitting MUD URLs do not allow for authentication of supplied MUD URLs. To accomodate for environments where authentication of MUD URLs is desired, it is also possible to include the MUD URL as a claim inside of a CBOR Web Token [RFC8392]. This allows for MUD Receivers or MUD Controllers to verify the authenticity of the provided MUD URL.¶
CBOR Web Tokens that contain MUD URL information have the following properties:¶
The MUD URL is contained as an ASCII-encoded string in the "mud-url" claim.¶
The Token MAY contain proof-of-possession claims [RFC8747]. If it does, the MUD Receiver MUST verify that the device is in possession of the key specified in the cnf claim. Proof-of-Possession claims that are transmitted over CoAP without DTLS/TLS MUST represent public keys, Receivers MUST treat any symmetric keys sent over insecure channels as invalid/compromised.¶
The Token MAY contain an expiry time. If an expiry time is specified, the MUD URL should be resubmitted or requested again shortly before the original CWT expires. Note that using an expiry time could cause problems if the device is unable to perform a refresh, e.g., due to a power outage.¶
CoAP requests and responses that use this format MUST use the Content-Format option with the value corresponding to the "application/mud-url+cwt" media type.¶
If the MUD URL is transmitted as a CBOR Web Token that includes proof-of-possession claims, the proof-of-possession claim SHOULD be verified. To do so, the following procedures SHOULD be used. Both of the following procedures use the establishment of a DTLS session using the PoP key in order to prove the possession of the key, similarly to the procedures defined in [RFC9202].¶
After submitting the MUD URL, the MUD Receiver parses the token. If it detects proof-of-possession claims, the receiver MUST reply with a 4.01 (Unauthorized) CoAP response code and reject the token for now. If the original submission request was not performed using CoAPS, the Receiver MUST also return a set of key information that can be used to establish a CoAP+DTLS session with it, as well as a CoAPS URI indicating the location of the secured submission resource.¶
The Thing then repeats the submission request using its own key information, the Receiver's key information, and the provided URI.¶
During the DTLS handshake, the Receiver MUST require the Thing to use the proof-of-possession key included in the originally submitted token in order to successfully establish a DTLS session.¶
After the DTLS handshake, the Thing has proven possession of the key included in the CWT to the MUD Receiver, which can then treat the CWT as valid.¶
After receiving the MUD URL from a request (e.g., a multicast request), the MUD Receiver parses the token. If it detects proof-of-possession claims, the receiver MUST continue with the following procedure before treating the CWT as valid.¶
The receiver repeats the MUD URL request, this time using DTLS. During the DTLS handshake, the Receiver must require the Thing to use the proof-of-possession key included in the originally received token in order to successfully establish the DTLS session.¶
After the DTLS handshake, the Thing has proven possession of the key included in the CWT to the MUD Receiver, which can then treat the CWT as valid.¶
In this section, additional methods for resource discovery in constrained environments are defined.¶
This document introduces a new well-known URI for discovering MUD URLs directly: /.well-known/mud-url.¶
/.well-known/mud-url MAY be used to expose a URL pointing to a MUD file hosted by an external MUD file server.
This MUD file MUST describe the device the URL was retrieved from or is referring to within a list of CoRE links.¶
[RFC7252] registers one IPv4 and one IPv6 address each for the purpose of CoAP multicast. In addition to these already existing "All CoAP Nodes" multicast addresses, this document defines an additional "All MUD CoAP Nodes" IPv6 multicast addresses that can be used to address only the subset of CoAP Nodes that support MUD. If a device exposes a MUD URL via CoAP, it SHOULD join the respective multicast groups for the IP versions it supports. Lastly, this document also defines an additional "All MUD Receivers" IPv6 multicast address that can be used by Things to interact with MUD Receivers in their vicinity.¶
Resources which either host MUD URLs or MUD files MAY be indicated using the CoRE Link Format [RFC6690].
For this purpose, additional link parameters are defined:
With the resource-types mud-file and mud-url, a link MAY be annotated as pointing to a MUD file or a MUD URL, respectively.
If a MUD URL is included as a resource in a list of CoRE web links, the supported Content-Formats MUST be indicated using the ct parameter.¶
MUD Receivers or other devices can send a GET requests to a CoAP server for /.well-known/core and get in return a list of hypermedia links to other resources hosted in that server, encoded using the CoRE Link-Format [RFC6690].
Among those, it will get the path to the resource exposing the MUD URL, for example /.well-known/mud-url and resource-types like rt=mud-url.¶
Things SHOULD only provide at most one link of resource type mud-url and mud-file each, unless they use MUD URLs encoded as CWTs with expiry times and provide an additional, basic MUD URL to enable token refresh.
However, if a CoRE Link Format description contains multiple mud-url or mud-file entries of the same type, MUD Receivers MUST choose the MUD URL that provides the highest degree of authenticity protection (where CWTs with expiry time take precedence over CWTs without expiry time).
If multiple MUD URLs with the same level of authenticity protection exist, the MUD Receiver SHOULD try them in an arbitrary order until one is successfully validated.¶
By using CoRE Resource Directories [RFC9176], devices can register a MUD file or MUD URL and use the directory as a MUD repository, making it discoverable with the usual RD Lookup steps. A MUD manager itself MAY also act as a Resource Directory, directly applying the policies from registered MUD files to the network. In addition to the registration endpoint defined in [RFC9176], MUD managers MAY define a separate registration interface when acting as a CoRE RD.¶
With the additional mechanisms for finding MUD URLs introduced in this document, MUD managers can be configured to play a more active role in discovering MUD-enabled devices. Furthermore, IoT devices could identify their peers based on a MUD URL associated with these devices or perform a configuration process based on the linked MUD file's contents. However, the IoT devices themselves also have more options for exposing their MUD URLs more actively, using, for instance, a MUD manager's registration interface.¶
In the remainder of this section, we will outline potential use-cases and procedures for obtaining a MUD URL with the additional mechanisms defined above.¶
This section outlines specifics of this specification regarding the behavior of Things.¶
Things MAY expose their MUD URL using a dedicated resource hosted under
/.well-known/mud-url.
If a MUD URL is exposed this way, the resource MUST offer at least one of the
specified serialization methods and MUST allow clients to choose between them
using the Accept option, if provided.
If the Thing supports resource discovery using a /.well-known/core resource,
MUD URL resources SHOULD be advertised there using the CoRE Link-Format
[RFC6690], indicating the available Content-Formats using the ct parameter.¶
Things MAY actively register their MUD URLs with MUD Receivers offering a registration interface. To perform the registration process, Things can perform a discovery process using the CoRE Link Format or directly include their MUD URL as a payload of a CoAP POST request. If Things are actively registering their MUD URLs with MUD managers, they SHOULD regularly repeat the process to keep interested parties informed about their presence and their associated MUD URL.¶
Using the CoRE Link Format, Things MAY send a GET request to the All CoAP Nodes
(IPv4) or the All MUD Receivers (IPv6) multicast address, requesting the /.well-known/core
resources and including an (optional) query parameter rt=mud.url-register.
After filtering the obtained links for the Resource Type mud.url-register to
identify available submission interfaces, the Thing MAY then send a unicast
POST request to the discovered MUD manager, containing the MUD URL as a payload
and a corresponding Content-Format option.
Alternatively, a Thing MAY also use a CoRE Resource Directory [RFC9176] to
perform the discovery process.¶
Things MAY also directly send a POST request containing the MUD URL as
a payload and a corresponding Content-Format option via unicast or to the All
CoAP Nodes (IPv4) or the All MUD Receivers (IPv6) multicast address, using the well-known URI
/.well-known/mud-submission.¶
If a Thing should be interested in the MUD URLs of one or more of its peers, it MAY use the same mechanisms specified for MUD Receivers described in the following section.¶
MUD Receivers are assumed to be mostly non-constrained devices. Accordingly, this specification puts most of the implementation burden regarding support for flows and formats on the receivers, while keeping the requirements for Things as small as possible. In general, it is recommended that MUD Receivers support as much of the specification as possible in order to support as many different Things as possible.¶
For the discovery process described in Section 3.4, the following considerations apply to MUD Receivers:¶
MUD Receivers that support IPv6 SHOULD regularly perform a CoAP request to the "All MUD CoAP Nodes" multicast address for the /.well-known/mud-url URI.¶
MUD Receivers that support IPv4 SHOULD regularly perform a CoAP request to the "All CoAP Nodes" multicast address for the /.well-known/mud-url URI.¶
MUD Receivers that support IPv6 devices MUST join the "All MUD Receivers" IPv6 multicast group.¶
MUD Receivers that support IPv4 devices MUST join the "All CoAP Nodes" IPv4 multicast group.¶
MUD Receivers SHOULD regularly query any CoRE Resource Directories relevant for the subnet they are responsible for.¶
MUD Receivers SHOULD register their submission resource to any CoRE Resource Directories relevant for the subnet they are responsible for.¶
This section describes the behavior for MUD Receivers regarding the Thing-initiated submission flow:¶
MUD Receivers MUST provide a submission resource under the /.well-known/mud-submission well-known URI.¶
MUD Receivers SHOULD include their submission resource in any CoRE Link Format descriptions of their resources (both in /.well-known/core and in CoRE RD registrations, if applicable).¶
MUD Receivers MAY indicate failure of MUD URL submission using a CoAP Error Code. If the submitted MUD URL is encoded in a CBOR Web Token including proof-of-possession claims, MUD Receivers MUST return the appropriate error code to initiate the proof of possession flow as described in Section 3.3.¶
This section describes considerations for MUD Receivers regarding the Receiver-initiated submission flow:¶
Regarding the actual MUD URL payload transmitted using CoAP, the following considerations apply:¶
MUD Receivers SHOULD treat devices for which MUD URL retrieval failed as devices the same way as devices that do not provide a MUD URL at all, unless an explicit differing policy is defined.¶
MUD Receiver implementations MUST support the plain MUD URL payload, although support for these MAY be disabled by policy.¶
MUD Receivers MUST support the CWT MUD URL claim.¶
MUD Receivers SHOULD be configured with a policy as to which signers are authorized to sign tokens.¶
MUD Receivers SHOULD support proof-of-possession semantics in CBOR Web Tokens and validate them before treating submitted MUD URLs using this format as valid.¶
(Very WIP for now)¶
The security considerations from [RFC8520] also apply to this document. Regarding CoAP specifics, [I-D.irtf-t2trg-amplification-attacks] provides information on possible attack scenarios. Additionally, the following considerations should be taken into account.¶
For Thing manufacturers that intend to implement this specification:¶
It is recommended to use CBOR Web Token-encoded MUD URLs whereever possible to allow for better integrity checking¶
Using expiry times for CWTs containing MUD URLs can be advantageous, but also has its shortcomings. Most notably, expiry times are not recommended if it is possible for Things to reach a state where they have neither the means to update their CWT nor a non-expired token in their persistent storage As devices may be out of service for longer periods of time, preventing them from refreshing CWTs, this state is unavoidable for the vast majority of devices.¶
In order to use expiry times anyways, manufacturers could use two different CWTs: A backup CWT without an expiry time with a MUD URL pointing to a very restricted MUD file that only allows updating the main CWT, and a main CWT that has an expiry time but has a more broad MUD file referenced in it.¶
For network operators: Network operators SHOULD specify a policy that describes:¶
We would like to thank Jaime Jiménez for allowing us to build upon his draft
draft-jimenez-t2trg-mud-coap-00 for creating an initial version of this
document.¶