Manufacturer Usage Description

Setting Up MUD on Devices

  1. Identify the network access needed by the device.
  2. Generate a MUD file.
  3. Make a MUD file available on the Internet.
  4. Program a MUD URL into devices that point to that MUD file.

Identify the Network Access for the Device

Network access for a device refers to the types of communications the device needs to perform its normal functions. Types of statements might include, but are not limited to:

  • “it communicates with a building controller using COAP”
  • “it periodically contacts updatemgr.example.com using TLS on port 443 to check for firmware updates”
  • “it communicates with peer addresses broadcasting packets on UDP port 4341”

Generate a MUD File

You will need the communication patterns you established in the Identify the Network Access for the Device section before you can create a MUD file. There are two ways in which you can make a MUD file.

  1. You can create your own MUD file and put it on your own MUD File Server. To do so, you will need to take the following steps:

    a. Choose the web server on which you will place the MUD file, and determine the HTTPS URL that will become the URL. For example, if your company name is "Widgetmaker", you might choose a MUD URL of https://mudfiles.widgetmaker.com/widgetmaker/luminaire/model1/1.0/ReallyBright100.

    b. Create a MUD file following the MUD Specification at https://tools.ietf.org/html/draft-ietf-opsawg-mud.

  2. Alternatively, Cisco DevNet has staged a Beta application for authoring a MUD file https://mudmaker.testing.devnetcloud.com/login. Create a login and follow the instructions for creating a MUD file for your device. At this point, we allow you to download this file for hosting on your private server. Coming soon, we will allow you to host and serve the file for a nominal fee.

Once you have created a MUD file, you will need to create a signature file that verifies that you, the manufacturer, are responsible for the device's development and actually created the file.

The MUD file signature is created as a Cryptographic Message Syntax (CMS) object and stored in the distinguished encoding rules (DER) format. Section 13.1 of the MUD specification shows how this can be done using OpenSSL:

Code Snippet
Copy%openssl cms -sign -signer widgetmaker_certfile -inkey widgetmaker_key \
                 -in ReallyBright100.json -binary -outform DER -binary \
            -certfile intermediatecert -out ReallyBright100.p7s

For testing purposes, follow the directions in the Creating a Testing Web Server section to create a special purpose CA. Create a signing key and certificate, and sign the MUD file.

Make a MUD File Available on the Internet

A MUD file and its signature file must be published on a web server to be available to MUD Controllers used by Network Administrators.

If you made your own MUD file in Step 1 under Generate a MUD File and plan to place it on your own web server, then a web server answering the DNS address matching the MUD URL needs to be available.

Install both the MUD file and its signature file on the web server specified in the MUD URL. Ensure that it is in the correct location. The web server needs to support TLS and run on port 443.

If you chose to use https://mudmaker.testing.devnetcloud.com/login instead, then your MUD file is already available!

Creating a Testing Web Server

Use the following procedure if you need to create a web server for testing your MUD file.

Caution: DO NOT USE THIS TEST WEB SERVER IN PRODUCTION ON THE INTERNET AS IT HAS NOT BEEN VETTED AS BEING SECURE.

  1. Choose a directory to be the beginning of the URL. In this procedure, the directory will be called “mudfs-dir”. Change directory into the mudfs-dir.
  2. Create the directories under mudfs-dir that match the components of the URL. For example, if the URL is https://mudfiles.widgetmaker.com/widgetmaker/luminaire/model1/1.0/ReallyBright100, create the directory structure of "widgetmaker/luminaire/model1/1.0".
  3. Place the MUD file you created and its signature file in last directory created. For example, the files “ReallyBright100.json” and “ReallyBright100.p7s” would be placed in the “1.0” directory.
  4. Start a web server that advertises the files. Make sure that it is serving files only in the mudfs-dir. If you need a web server, you can use a simple Python web server that is generally available on Linux. This is an HTTPS server and can be on any machine where the TLS port 443 is not already in use.

Program IoT Devices to Support MUD

LLDP

The IEEE802.1AB Link Layer Discovery Protocol (LLDP) is used by network devices to advertise information about themselves to other devices attached to the same local area network (LAN). LLDP is also used to negotiate Power over Ethernet (PoE) parameters.

A MUD URL can be emitted via LLDP, as defined by the MUD Specification. The LLDP TLV includes several fixed fields that define it as a MUD URL, and is followed by a field that contains the MUD URL itself. The following figure shows the format of the TLV:

LLDP

DHCP

The Dynamic Host Configuration Protocol (DHCP) is used by network devices to request IP addresses and also to announce some attributes about themselves to DHCP servers, known as "Options". A device can announce a MUD URL using the Option defined in the MUD Specification. The following figure shows the format of the Option:

DHCP

Creating a DHCP MUD Option on Linux

There are two popular Linux packages that a device can use as a DHCP client: dhcpcd and dhclient.

DHCPCD

The MUD URL supports the dhcpcd package as of DHCP Version 7. If your version is too old, you can download the most recent version here: https://roy.marples.name/projects/dhcpcd

Update dhcpcd.conf as follows:

Code Snippet
Copy mudurl url
         Specifies the URL for a manufacturer usage description (MUD).
         The description is used by upstream network devices to instanti‐
         ate any desired access lists.  See draft-ietf-opsawg-mud for more
         information.

DHCLIENT

Adding a MUD URI to dhclient is supported as of DHCP Version 4. If you need to download a more current version, you can do so here: https://www.isc.org/downloads/dhcp/

Update the dhclient.conf file as follows for IPv4, assuming your MUD URL is https://mudfiles.widgetmaker.com/widgetmaker/luminaire/model1/1.0/ReallyBright100.json

option mud code 161 = text; send mud "https://mudfiles.widgetmaker.com/widgetmaker/luminaire/model1/1.0/ReallyBright100.json";

Creating an LLDP MUD TLV on Linux

An IoT device using Linux needs to support an LLDP daemon and be configured to emit the LLDP MUD URL TLV. This section describes how to do this using a common Linux daemon, lldpd.

  1. Check if you have lldpd running on your Linux system by using the lldp CLI command. If it is not there, you will need to download it. On some distributions this is done using apt.

    sudo apt install lldpd

    Or, you can download the code from https://github.com/vincentbernat/lldpd

  2. Check if the lldpd version supports the configure custom-tlv command. Become root, run the lldpcli command, and enter configure custom-tlv ?

If the response is “unknown”, download a newer version.

Creating the Configuration File With the MUD URL

The lldpd package allows custom TLVs to be installed by inserting a “.conf” file in the appropriate location (typically either /etc/lldpd or /usr/local/etc/lldpd).

For example, if your MUD URL is the following:

https://mudfiles.widgetmaker.com/widgetmaker/luminaire/model1/1.0/ReallyBright100

you would need to create a file with the following format, where each number is the value of a character (e.g., "68,74,74,70,73" represents "https").

The contents of the file should be two lines (which are line wrapped below):

Code Snippet
Copyconfigure lldp custom-tlv oui 00,00,5e subtype 01 oui-info 68,74,74,70,73,3a,2f,2f,6d,75,64,66,69,6c,65,
73,2e,77,69,64,67,65,74,6d,61,6b,65,72,2e,63,6f,6d,2f,77,69,64,67,65,74,6d,61,6b,65,72,2f,6c,75,6d,69,6e,
61,69,72,65,2f,6d,6f,64,65,6c,31,2f,31,2e,30,2f,52,65,61,6c,6c,79,42,72,69,67,68,74,31,30,30

# MUD URL: https[]()://mudfiles.widgetmaker.com/widgetmaker/luminaire/model1/1.0/ReallyBright100

Installing the MUD URL Configuration File

  1. Install the configuration file in /etc/lldpd.d.

    Note: If you installed a new package, the file name might be /usr/local/etc/lldpd.d.

  2. Run lldpd.

    The service should be run as a daemon. For a quick test, it can be invoked in the foreground as follows:

    sudo lldpd -d

Note: If you have installed a package in /usr/local/bin, you may need to set LD_LIBRARY_PATH=/usr/local/lib for the command to run properly.

Next