NIST SPECIAL PUBLICATION 1800-15C


Securing Small-Business and Home Internet of Things (IoT) Devices:

Mitigating Network-Based Attacks Using Manufacturer Usage Description (MUD)


Volume C:

How-to Guides



Mudumbai Ranganathan

NIST


Steve Johnson

Ashnwini Kadam

Craig Pratt

Darshak Thakore

CableLabs


Eliot Lear

Cisco


William C. Barker

Dakota Consulting


Adnan Baykal

Global Cyber Alliance


Drew Cohen

Kevin Yeich

MasterPeace Solutions


Yemi Fashina

Parisa Grayeli

Joshua Harrington

Joshua Klosterman

Blaine Mulugeta

Susan Symington

The MITRE Corporation



May 2021


FINAL


This publication is available free of charge from:

https://doi.org/10.6028/NIST.SP.1800-15


Draft versions of this publication is available free of charge from: https://www.nccoe.nist.gov/library/securing-small-business-and-home-internet-things-iot-devices-mitigating-network-based


nccoenistlogos




DISCLAIMER

Certain commercial entities, equipment, products, or materials may be identified by name or company logo or other insignia in order to acknowledge their participation in this collaboration or to describe an experimental procedure or concept adequately. Such identification is not intended to imply special status or relationship with NIST or recommendation or endorsement by NIST or NCCoE; neither is it intended to imply that the entities, equipment, products, or materials are necessarily the best available for the purpose.

National Institute of Standards and Technology Special Publication 1800-15C, Natl. Inst. Stand. Technol. Spec. Publ. 1800-15C, 243 pages, (May 2021), CODEN: NSPUE2

FEEDBACK

As a private-public partnership, we are always seeking feedback on our practice guides. We are particularly interested in seeing how businesses apply NCCoE reference designs in the real world. If you have implemented the reference design, or have questions about applying it in your environment, please email us at mitigating-iot-ddos-nccoe@nist.gov.

All comments are subject to release under the Freedom of Information Act.

National Cybersecurity Center of Excellence
National Institute of Standards and Technology
100 Bureau Drive
Mailstop 2002
Gaithersburg, MD 20899

NATIONAL CYBERSECURITY CENTER OF EXCELLENCE

The National Cybersecurity Center of Excellence (NCCoE), a part of the National Institute of Standards and Technology (NIST), is a collaborative hub where industry organizations, government agencies, and academic institutions work together to address businesses’ most pressing cybersecurity issues. This public-private partnership enables the creation of practical cybersecurity solutions for specific industries, as well as for broad, cross-sector technology challenges. Through consortia under Cooperative Research and Development Agreements (CRADAs), including technology partners—from Fortune 50 market leaders to smaller companies specializing in information technology security—the NCCoE applies standards and best practices to develop modular, easily adaptable example cybersecurity solutions using commercially available technology. The NCCoE documents these example solutions in the NIST Special Publication 1800 series, which maps capabilities to the NIST Cybersecurity Framework and details the steps needed for another entity to re-create the example solution. The NCCoE was established in 2012 by NIST in partnership with the State of Maryland and Montgomery County, Maryland.

To learn more about the NCCoE, visit https://www.nccoe.nist.gov/. To learn more about NIST, visit

NIST CYBERSECURITY PRACTICE GUIDES

NIST Cybersecurity Practice Guides (Special Publication 1800 series) target specific cybersecurity challenges in the public and private sectors. They are practical, user-friendly guides that facilitate the adoption of standards-based approaches to cybersecurity. They show members of the information security community how to implement example solutions that help them align more easily with relevant standards and best practices, and provide users with the materials lists, configuration files, and other information they need to implement a similar approach.

The documents in this series describe example implementations of cybersecurity practices that businesses and other organizations may voluntarily adopt. These documents do not describe regulations or mandatory practices, nor do they carry statutory authority.

ABSTRACT

The goal of the Internet Engineering Task Force’s Manufacturer Usage Description (MUD) architecture is for Internet of Things (IoT) devices to behave as intended by the manufacturers of the devices. This is done by providing a standard way for manufacturers to indicate the network communications that a device requires to perform its intended function. When MUD is used, the network will automatically permit the IoT device to send and receive only the traffic it requires to perform as intended, and the network will prohibit all other communication with the device, thereby increasing the device’s resilience to network-based attacks. In this project, the NCCoE has demonstrated the ability to ensure that when an IoT device connects to a home or small-business network, MUD can be used to automatically permit the device to send and receive only the traffic it requires to perform its intended function. This NIST Cybersecurity Practice Guide explains how MUD protocols and tools can reduce the vulnerability of IoT devices to botnets and other network-based threats as well as reduce the potential for harm from exploited IoT devices. It also shows IoT device developers and manufacturers, network equipment developers and manufacturers, and service providers who employ MUD-capable components how to integrate and use MUD to satisfy IoT users’ security requirements.

KEYWORDS

access control; bootstrapping; botnets; firewall rules; flow rules; Internet of Things (IoT); Manufacturer Usage Description (MUD); network segment; onboarding; router; server; threat signaling; update server; Wi-Fi Easy Connect.

DOCUMENT CONVENTIONS

The terms “shall” and “shall not” indicate requirements to be followed strictly to conform to the publication and from which no deviation is permitted.

The terms “should” and “should not” indicate that among several possibilities, one is recommended as particularly suitable without mentioning or excluding others or that a certain course of action is preferred but not necessarily required or that (in the negative form) a certain possibility or course of action is discouraged but not prohibited.

The terms “may” and “need not” indicate a course of action permissible within the limits of the publication.

The terms “can” and “cannot” indicate a possibility and capability, whether material, physical, or causal.

Acronyms used in figures can be found in the Acronyms appendix.

ACKNOWLEDGMENTS

We are grateful to the following individuals for their generous contributions of expertise and time.

Name

Organization

Allaukik Abhishek

Arm

Michael Bartling

Arm

Mark Walker

CableLabs

Tao Wan

CableLabs

Russ Gyurek

Cisco

Peter Romness

Cisco

Brian Weis

Cisco

Rob Cantu

CTIA

Dean Coclin

DigiCert

Avesta Hojjati

DigiCert

Clint Wilson

DigiCert

Katherine Gronberg

Forescout

Tim Jones

Forescout

Rae’-Mar Horne

MasterPeace Solutions, Ltd.

Nate Lesser

MasterPeace Solutions, Ltd.

Tom Martz

MasterPeace Solutions, Ltd.

Daniel Weller

MasterPeace Solutions, Ltd.

Nancy Correll

The MITRE Corporation

Sallie Edwards

The MITRE Corporation

Drew Keller

The MITRE Corporation

Sarah Kinling

The MITRE Corporation

Karri Meldorf

The MITRE Corporation

Mary Raguso

The MITRE Corporation

Allen Tan

The MITRE Corporation

Mo Alhroub

Molex

Jaideep Singh

Molex

Bill Haag

NIST

Tim Polk

NIST

Murugiah Souppaya

NIST

Paul Watrobski

NIST

Bryan Dubois

Patton Electronics

Stephen Ochs

Patton Electronics

Karen Scarfone

Scarfone Cybersecurity

Matt Boucher

Symantec A Division of Broadcom

Petros Efstathopoulos

Symantec A Division of Broadcom

Bruce McCorkendale

Symantec A Division of Broadcom

Susanta Nanda

Symantec A Division of Broadcom

Yun Shen

Symantec A Division of Broadcom

Pierre-Antoine Vervier

Symantec A Division of Broadcom

John Bambenek

ThreatSTOP

Russ Housley

Vigil Security

The Technology Partners/Collaborators who participated in this build submitted their capabilities in response to a notice in the Federal Register. Respondents with relevant capabilities or product components were invited to sign a Cooperative Research and Development Agreement (CRADA) with NIST, allowing them to participate in a consortium to build this example solution. We worked with:

Technology Partner/Collaborator

Build Involvement

Arm

Subject matter expertise

CableLabs

Micronets Gateway

Micronets cloud infrastructure

Prototype IoT devices–Raspberry Pi with Wi-Fi Easy Connect support

Micronets mobile application

Cisco

Cisco Catalyst 3850S

MUD manager

CTIA

Subject matter expertise

DigiCert

Private Transport Layer Security certificate

Premium Certificate

Forescout

Forescout appliance–VCT-R

Enterprise manager–VCEM-05

Global Cyber Alliance

Quad9 DNS service, Quad9 Threat Application Programming Interface

ThreatSTOP threat MUD file server

MasterPeace Solutions

Yikes! router

Yikes! cloud

Yikes! mobile application

Molex

Molex light-emitting diode light bar

Molex Power over Ethernet Gateway

Patton Electronics

Subject matter expertise

Symantec A Division of Broadcom

Subject matter expertise

List of Figures

Figure 1‑1 Reference Architecture

Figure 1‑2 NCCoE Physical Architecture

Figure 2‑1 Physical Architecture–Build 1

List of Tables

Table 2‑1 Cisco 3850-S Switch Running Configuration

1 Introduction

The following volumes of this guide show information technology (IT) professionals and security engineers how we implemented this example solution. We cover all of the products employed in this reference design. We do not re-create the product manufacturers’ documentation, which is presumed to be widely available. Rather, these volumes show how we incorporated the products together in our environment.

Note: These are not comprehensive tutorials. There are many possible service and security configurations for these products that are out of scope for this reference design.

1.1 How to Use this Guide

This National Institute of Standards and Technology (NIST) Cybersecurity Practice Guide demonstrates a standards-based reference design for mitigating network-based attacks by securing home and small-business Internet of Things (IoT) devices. The reference design is modular, and it can be deployed in whole or in part. This practice guide provides users with the information they need to replicate four example MUD-based implementations of this reference design. These example implementations are referred to as Builds, and this volume describes in detail how to reproduce each one.

This guide contains four volumes:

  • NIST SP 1800-15A: Executive Summary – why we wrote this guide, the challenge we address, why it could be important to your organization, and our approach to solving this challenge

  • NIST SP 1800-15B: Approach, Architecture, and Security Characteristics – what we built and why, including the risk analysis performed, and the security control map

  • NIST SP 1800-15C: How-To Guides – instructions for building the example implementations, including all the security relevant details that would allow you to replicate all or parts of this project (you are here)

  • NIST SP 1800-15D: Functional Demonstration Results describes the functional demonstration results for the four implementations of the MUD-based reference solution

Depending on your role in your organization, you might use this guide in different ways:

Business decision makers, including chief security and technology officers, will be interested in the Executive Summary, NIST SP 1800-15A, which describes the following topics:

  • challenges that enterprises face in trying to mitigate network-based attacks by securing home and small-business IoT devices

  • example solutions built at the National Cybersecurity Center of Excellence (NCCoE)

  • benefits of adopting the example solutions

Technology or security program managers who are concerned with how to identify, understand, assess, and mitigate risk will be interested in NIST SP 1800-15B, which describes what we did and why. The following sections will be of particular interest:

  • Section 3.4, Risk Assessment, describes the risk analysis we performed.

  • Section 5.2, Security Control Map, maps the security characteristics of these example solutions to cybersecurity standards and best practices.

You might share the Executive Summary, NIST SP 1800-15A, with your leadership team members to help them understand the importance of adopting a standards-based solution for mitigating network-based attacks by securing home and small-business IoT devices.

IT professionals who want to implement an approach like this will find this whole practice guide useful. You can use this How-To portion of the guide, NIST SP 1800-15C, to replicate all or parts of one or all four builds created in our lab. This How-To portion of the guide provides specific product installation, configuration, and integration instructions for implementing the example solutions. We do not re-create the product manufacturers’ documentation, which is generally widely available. Rather, we show how we incorporated the products together in our environment to create an example solution.

This guide assumes that IT professionals have experience implementing security products within the enterprise. While we have used a suite of products to address this challenge, this guide does not endorse these particular products. Your organization can adopt one of these solutions or one that adheres to these guidelines in whole, or you can use this guide as a starting point for tailoring and implementing parts of a Manufacturer Usage Description (MUD)-based solution. Your organization’s security experts should identify the products that will best integrate with your existing tools and IT system infrastructure. We hope that you will seek products that are congruent with applicable standards and best practices. NIST SP 1800-15B lists the products that we used in each build and maps them to the cybersecurity controls provided by this reference solution.

A NIST Cybersecurity Practice Guide does not describe “the” solution, but a possible solution. In the case of this guide, it describes four possible solutions. Comments, suggestions, and success stories will improve subsequent versions of this guide. Please contribute your thoughts to mitigating-iot-ddos-nccoe@nist.gov.

1.2 Build Overview

This NIST Cybersecurity Practice Guide addresses the challenge of using standards-based protocols and available technologies to mitigate network-based attacks by securing home and small-business IoT devices. It identifies three key forms of protection:

  • use of the MUD specification to automatically permit an IoT device to send and receive only the traffic it requires to perform as intended, thereby reducing the potential for the device to be the victim of a network-based attack, as well as the potential for the device, if compromised, to be used in a network-based attack

  • use of network-wide access controls based on threat intelligence to protect all devices (both MUD-capable and non-MUD-capable) from connecting to domains that are known current threats

  • automated secure software updates to all devices to ensure that operating system (OS) patches are installed promptly

Four builds that serve as example solutions of how to support the MUD specification have been implemented and demonstrated as part of this project. This practice guide provides instructions for reproducing these four builds.

1.2.1 Usage Scenarios

Each of the four builds is designed to fulfill the use case of a MUD-capable IoT device being onboarded and used on home and small-business networks, where plug-and-play deployment is required. All four builds include both MUD-capable and non-MUD-capable IoT devices. MUD-capable IoT devices include the Molex Power over Ethernet (PoE) Gateway and Light Engine as well as four development kits (devkits) that the National Cybersecurity Center of Excellence (NCCoE) configured to perform actions such as power a light-emitting diode (LED) bulb on and off, start network connections, and power a connected lighting device on and off. These MUD-capable IoT devices interact with external systems to access notional, secure updates and various cloud services, in addition to interacting with conventional personal computing devices, as permitted by their MUD files. Non-MUD-capable IoT devices deployed in the builds include three cameras, two mobile phones, two connected lighting devices, a connected assistant, a connected printer, a baby monitor with remote control and video and audio capabilities, a connected wireless access point, and a connected digital video recorder. The cameras, connected lighting devices, baby monitor, and connected digital video recorder are all controlled and managed by a mobile phone. In combination, these devices are capable of generating a wide range of network traffic that could reasonably be expected on a home or small-business network.

1.2.2 Reference Architecture Overview

Figure 1‑1 depicts a general reference design for all four builds. It consists of three main components: support for MUD, support for threat signaling, and support for periodic updates.

Figure 1‑1 Reference Architecture

The Reference Architecture for the NCCoE Lab. Explanation of components can be found below.

1.2.2.1 Support for MUD

A new functional component, the MUD manager, is introduced to augment the existing networking functionality offered by the home/small-business network router or switch. Note that the MUD manager is a logical component. Physically, the functionality it provides can and often will be combined with that of the network router or switch in a single device.

IoT devices must somehow be associated with a MUD file. The MUD specification describes three possible mechanisms through which the IoT device can provide the MUD file URL to the network: inserting the MUD URL into the Dynamic Host Configuration Protocol (DHCP) address requests that they generate when they attach to the network (e.g., when powered on), providing the MUD URL in a Link Layer Discovery Protocol (LLDP) frame, or providing the MUD URL as a field in an X.509 certificate that the device provides to the network via a protocol such as Tunnel Extensible Authentication Protocol. In addition, the MUD specification provides flexibility to enable other mechanisms by which MUD file URLs can be associated with IoT devices. One such alternative mechanism is to associate the device with its MUD file by using the device’s bootstrapping information that is conveyed as part of the Wi-Fi Easy Connect (also referred to as Device Provisioning Protocol—DPP) onboarding process. This is the mechanism implemented in Build 3.

Figure 1‑1 uses labeled arrows to depict the steps involved in supporting MUD:

  • The IoT device emits a MUD URL by using a mechanism such as DHCP, LLDP, or X.509 certificate (step 1).

  • The router extracts the MUD URL from the protocol frame of whatever mechanism was used to convey it and forwards this MUD URL to the MUD manager (step 2).

  • Once the MUD URL is received, the MUD manager uses https to request the MUD file from the MUD file server by using the MUD URL provided in the previous step (step 3a); if successful, the MUD file server at the specified location will serve the MUD file (step 3b).

  • Next, the MUD manager uses https to request the signature file associated with the MUD file (step 4a) and upon receipt (step 4b) verifies the MUD file by using its signature file.

  • The MUD file describes the communications requirements for the IoT device. Once the MUD manager has determined the MUD file to be valid, the MUD manager converts the access control rules in the MUD file into access control entries (e.g., access control lists—ACLs, firewall rules, or flow rules) and installs them on the router or switch (step 5).

Once the device’s access control rules are applied to the router or switch, the MUD-capable IoT device will be able to communicate with approved local hosts and internet hosts as defined in the MUD file, and any unapproved communication attempts will be blocked.

1.2.2.2 Support for Updates

To provide additional security, the reference architecture also supports periodic updates. All builds include a server that is meant to represent an update server to which MUD will permit devices to connect. Each IoT device on an operational network should be configured to periodically contact its update server to download and apply security patches, ensuring that it is running the most up-to-date and secure code available. To ensure that such updates are possible, the IoT device’s MUD file must explicitly permit the IoT device to receive traffic from the update server. Although regular manufacturer updates are crucial to IoT security, the builds described in this practice guide demonstrate only the ability to receive faux updates from a notional update server.

1.2.2.3 Support for Threat Signaling

To provide additional protection for both MUD-capable and non-MUD-capable devices, the reference architecture also incorporates support for threat signaling. The router or switch can receive threat feeds from a threat signaling server to use as a basis for restricting certain types of network traffic. For example, both MUD-capable and non-MUD-capable devices can be prevented from connecting to internet domains that have been identified as potentially malicious.

1.2.2.4 Build-Specific Features

The reference architecture depicted in Figure 1‑1 is intentionally general. Each build instantiates this reference architecture in a unique way, depending on the equipment used and the capabilities supported. The logical and physical architectures of each build are depicted and described in NIST SP 1800-15B: Approach, Architecture, and Security Characteristics. While all four builds support MUD and the ability to receive faux updates from a notional update server, only Build 2 currently supports threat signaling. Only Build 3 currently supports onboarding MUD-capable devices using the Wi-Fi Alliance Wi-Fi Easy Connect protocol. Build 1 and Build 2 include nonstandard device discovery technology to discover, inventory, profile, and classify attached devices. Such classification can be used to validate that the access being granted to each device is consistent with that device’s manufacturer and model. In Build 2, a device’s manufacturer and model can be used as a basis for identifying and enforcing that device’s traffic profile.

Briefly, the four builds of the reference architecture that have been completed and demonstrated are as follows:

  • Build 1 uses products from Cisco Systems, DigiCert, Forescout, and Molex. The Cisco MUD manager supports MUD, and the Forescout virtual appliances and enterprise manager perform non-MUD-related device discovery on the network. Molex PoE Gateway and Light Engine is used as a MUD-capable IoT device. Certificates from DigiCert are also used.

  • Build 2 uses products from MasterPeace Solutions Ltd., Global Cyber Alliance (GCA), ThreatSTOP, and DigiCert. The MasterPeace Solutions Yikes! router, cloud service, and mobile application support MUD as well as perform device discovery on the network and apply additional traffic rules to both MUD-capable and non-MUD-capable devices based on device manufacturer and model. The GCA threat agent, Quad9 DNS service, and ThreatSTOP threat MUD file server support threat signaling. Certificates from DigiCert are also used.

  • Build 3 uses products from CableLabs and DigiCert. CableLabs Micronets (e.g., Micronets Gateway, Micronets Manager, Micronets mobile phone application, and related service provider cloud-based infrastructure) supports MUD and implements the Wi-Fi Alliance’s Wi-Fi Easy Connect protocol to securely onboard devices to the network. It also uses software-defined networking to create separate trust zones (e.g., network segments) called micronets to which devices are assigned according to their intended network function. Certificates from DigiCert are also used.

  • Build 4 uses software developed at the NIST Advanced Networking Technologies Laboratory. This software supports MUD and is intended to serve as a working prototype of the MUD request for comments (RFC) to demonstrate feasibility and scalability. Certificates from DigiCert are also used.

The logical architectures and detailed descriptions of Builds 1, 2, 3, and 4 can be found in NIST SP 1800-15B: Approach, Architecture, and Security Characteristics.

1.2.3 Physical Architecture Overview

Figure 1‑2 depicts the high-level physical architecture of the NCCoE laboratory environment. This implementation currently supports four builds and has the flexibility to implement additional builds in the future. As depicted, the NCCoE laboratory network is connected to the internet via the NIST data center. Access to and from the NCCoE network is protected by a firewall. The NCCoE network includes a shared virtual environment that houses an update server, a MUD file server, an unapproved server (i.e., a server that is not listed as a permissible communications source or destination in any MUD file), a Message Queuing Telemetry Transport (MQTT) broker server, and a Forescout enterprise manager. These components are hosted at the NCCoE and are used across builds where applicable. The Transport Layer Security (TLS) certificate and Premium Certificate used by the MUD file server are provided by DigiCert.

The following four builds, as depicted in the diagram, are supported within the physical architecture:

  • Build 1 network components consist of a Cisco Catalyst 3850-S switch, a Cisco MUD manager, a FreeRADIUS server, and a virtualized Forescout appliance on the local network. Build 1 also requires support from all components that are in the shared virtual environment, including the Forescout enterprise manager.

  • Build 2 network components consist of a MasterPeace Solutions Ltd. Yikes! router on the local network. Build 2 requires support from the MUD file server, Yikes! cloud, and a Yikes! mobile application that are resident on the Build 2 cloud. The Yikes! router includes threat-signaling capabilities (not depicted) that have been integrated with it. Build 2 also requires support from threat-signaling cloud services that consist of the ThreatSTOP threat MUD file server, Quad9 threat application programming interface (API), and Quad9 DNS service. Build 2 uses only the update server and unapproved server components that are in the shared virtual environment.

  • Build 3 network components consist of a CableLabs Micronets Gateway/wireless access point (AP). The Gateway/wireless AP resides on the local network and operates in conjunction with various service provider components and partner/service provider offerings that reside in the Micronets virtual environment in the Build 3 cloud. The Micronets Gateway is controlled by a Micronets Manager that resides in the Build 3 cloud and that coordinates a number of cloud-based Micronets micro-services, some of which are depicted. Build 3 also includes a Micronets mobile application that provides the user and device interfaces for device onboarding.

  • Build 4 network components consist of a software-defined networking (SDN)-capable gateway/switch on the local network and an SDN controller/MUD manager and approved and unapproved servers that are located remotely from the local network. Build 4 also uses the MUD file server that is resident in the shared virtual environment.

IoT devices used in all four builds include both MUD-capable and non-MUD-capable IoT devices. The MUD-capable IoT devices used, which vary across builds, include Raspberry Pi, ARTIK, u-blox, Intel UP Squared, BeagleBone Black, NXP i.MX 8M (devkit), and the Molex Light Engine controlled by PoE Gateway. Non-MUD-capable devices used, which also vary across builds, include a wireless access point, cameras, a printer, mobile phones, lighting devices, a connected assistant device, a baby monitor, and a digital video recorder. Each of the completed builds and the roles that their components play in their architectures are explained in more detail in NIST SP 1800-15B.

The remainder of this guide describes how to implement Builds 1, 2, 3, and 4.

Figure 1‑2 NCCoE Physical Architecture

Diagram of Physical Architecture. Explanation of components can be found above.

1.3 Typographic Conventions

The following table presents typographic conventions used in this volume.

Typeface/Symbol

Meaning

Example

Italics

file names and path names; references to documents that are not hyperlinks; new terms; and placeholders

For language use and style guidance, see the NCCoE Style Guide.

Bold

names of menus, options, command buttons, and fields

Choose File > Edit.

Monospace

command-line input, onscreen computer output, sample code examples, and status codes

mkdir

Monospace (block)

multi-line input, on-screen computer output, sample code examples, status codes

% mkdir -v nccoe_projects
mkdir: created directory 'nccoe_projects'

blue text

link to other parts of the document, a web URL, or an email address

All publications from NIST’s NCCoE are available at https://www.nccoe.nist.gov.

2 Build 1 Product Installation Guides

This section of the practice guide contains detailed instructions for installing and configuring all the products used to implement Build 1. For additional details on Build 1’s logical and physical architectures, please refer to NIST SP 1800-15B.

2.1 Cisco MUD Manager

This section describes how to deploy Cisco’s MUD manager version 1.0, which uses a MUD-based authorization system in the network, using Cisco Catalyst switches, FreeRADIUS, and Cisco MUD manager.

2.1.1 Cisco MUD Manager Overview

The Cisco MUD manager is an open-source implementation that works with IoT devices that emit their MUD URLs. In this implementation we tested two MUD URL emission methods: DHCP and LLDP. The MUD manager is supported by a FreeRADIUS server that receives MUD URLs from the switch. The MUD URLs are extracted by the DHCP server and are sent to the MUD manager via Remote Authentication Dial-In User Service (RADIUS) messages. The MUD manager is responsible for retrieving the MUD file and corresponding signature file associated with the MUD URL. The MUD manager verifies the legitimacy of the file and then translates the contents to an Internet Protocol (IP) ACL-based policy that is installed on the switch.

The version of the Cisco MUD manager used in this project is a proof-of-concept implementation that is intended to introduce advanced users and engineers to the MUD concept. It is not a fully automated MUD manager implementation, and some protocol features are not present. At implementation, the “model” construct was not yet implemented. In addition, if a DNS-based system changes its address, this will not be noticed. Also, IPv6 access has not been fully supported.

2.1.2 Cisco MUD Manager Configurations

The following subsections document the software, hardware, and network configurations for the Cisco MUD manager.

2.1.2.1 Hardware Configuration

Cisco requires installing the MUD manager and FreeRADIUS on a single server with at least 2 gigabytes of random access memory. This server must integrate with at least one switch or router on the network. For this build we used a Catalyst 3850-S switch.

2.1.2.2 Network Configuration

The MUD manager and FreeRADIUS server instances were installed and configured on a dedicated machine leveraged for hosting virtual machines in the Build 1 lab environment. This machine was then connected to virtual local area network (VLAN) 2 on the Catalyst 3850-S and assigned a static IP address.

2.1.2.3 Software Configuration

For this build, the Cisco MUD manager was installed on an Ubuntu 18.04.01 64-bit server. However, there are many approaches for implementation. Alternatively, the MUD manager can be built via docker containers provided by Cisco.

The Cisco MUD manager can operate on Linux operating systems, such as

  • Ubuntu 18.04.01

  • Amazon Linux

The Cisco MUD manager requires the following installations and components:

  • OpenSSL

  • cJSON

  • MongoDB

  • Mongo C driver

  • Libcurl

  • FreeRADIUS server

At a high level, the following software configurations and integrations are required:

  • The Cisco MUD manager requires integration with a switch (such as a Catalyst 3850-S) that connects to an authentication, authorization, and accounting (AAA) server that communicates by using the RADIUS protocol (i.e., a RADIUS server).

  • The RADIUS server must be configured to identify a MUD URL received in an accounting request message from a device it has authenticated.

  • The MUD manager must be configured to process a MUD URL received from a RADIUS server and return access control policy to the RADIUS server, which is then forwarded to the switch.

2.1.3 Setup

2.1.3.1 Preinstallation

Cisco’s DevNet GitHub page provides documentation that we followed to complete this section: https://github.com/CiscoDevNet/MUD-Manager/tree/3.0.1#dependancies

  1. Open a terminal window, and enter the following command to log in as root:

    sudo su

    This image shows the command "sudo su" being run by iot@cisco-mud-manager.

  2. Change to the root directory:

    cd /

    This image shows the command "cd /" being run by root@cisco-mud-manager.

  3. To install OpenSSL from the terminal, enter the following command:

    apt-get install openssl

    This image shows the command "apt-get install openssl" being run on the Cisco MUD Manager.

    1. If unable to link to OpenSSL, install it by entering this command:

      apt-get install libcurl4-openssl-dev

      This image shows the command "apt-get install -y libssl-dev" being run on the Cisco MUD Manager.

  4. To install cJSON, download it from GitHub by entering the following command:

    git clone https://github.com/DaveGamble/cJSON

    This image shows the command "git clone https://github.com/DaveGamble/cJSON" being run on the Cisco MUD Manager.

    1. Change directories to the cJSON folder by entering the following command:

      cd cJSON

      This image shows the command "cd cJSON" being run on the Cisco MUD Manager.

    2. Build cJSON by entering the following commands:

      make

      This image shows the command "make" being run on the Cisco MUD Manager.

      make install

      This image shows the command "make install" being run on the Cisco MUD Manager.

  5. Change directories back a folder by entering the following command:

    cd ..

    This image shows the command "cd .." being run on the Cisco MUD Manager.

  6. To install MongoDB, enter the following commands:

    1. Import the public key:

      apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 9DA31620334BD75D9DCB49F368818C72E52529D4
      

      This image shows the command "sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 9DA31620334BD75D9DCB49F368818C72E52529D4" being run on the Cisco MUD Manager.

    2. Create a list file for MongoDB:

      echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu trusty/mongodb-org/4.0 multiverse" \| sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list
      

      This image shows the command echo being run on the Cisco MUD Manager.

    3. Reload the local package database:

      apt-get update

      This image shows the command "apt-get update" being run on the Cisco MUD Manager.

    4. Install the MongoDB packages:

      apt-get install -y mongodb

      This image shows the command "sudo apt-get install -y mongodb" being run on the Cisco MUD Manager.

  7. To install the Mongo C driver, enter the following command:

    wget https://github.com/mongodb/mongo-c-driver/releases/download/1.7.0/mongo-c-driver-1.7.0.tar.gz
    

    This image shows the command "wget https://github.com/mongodb/mongo-c-driver/releases/download/1.7.0/mongo-c-driver-1.7.0.tar.gz" being run on the Cisco MUD Manager.

    1. Untar the file by entering the following command:

      tar -xzf mongo-c-driver-1.7.0.tar.gz

      This image shows the command "tar -xzf mongo-c-driver-1.7.0.tar.gz" being run on the Cisco MUD Manager.

    2. Change into the mongo-c-driver-1.7.0 directory by entering the following command:

      cd mongo-c-driver-1.7.0/

      This image shows the command "cd mongo-c-driver-1.7.0" being run on the Cisco MUD Manager.

    3. Build the Mongo C driver by entering the following commands:

      ./configure --disable-automatic-init-and-cleanup --with-libbson=bundled

      This image shows the command "./configure --disable-automatic-init-and-cleanup --with-libbson=bundled" being run on the Cisco MUD Manager.

      make

      This image shows the command "make" being run on the Cisco MUD Manager.

      make install

      This image shows the command "make install" being run on the Cisco MUD Manager.

  8. Change directories back a folder by entering the following command:

    cd ..

    This image shows the command "cd ..." being run on the Cisco MUD Manager.

  9. To install libcurl, enter the following command:

    sudo apt-get install libcurl4-openssl-dev

    This image shows the command "sudo apt-get install libcurl4-openssl-dev" being run on the Cisco MUD Manager.

2.1.3.2 MUD Manager Installation

A portion of the steps in this section are documented on Cisco’s DevNet GitHub page: https://github.com/CiscoDevNet/MUD-Manager/tree/3.0.1#building-the-mud-manager

  1. Open a terminal window, and enter the following command to log in as root:

    sudo su

    This image shows the command "sudo su" being run by iot@cisco-mud-manager.

  2. Change to the root directory by entering the following command:

    cd /

    This image shows the command "cd /" being run on the Cisco MUD Manager.

  3. To install the MUD manager, download it from Cisco’s GitHub by entering the following command:

    git clone https://github.com/CiscoDevNet/MUD-Manager

    This image shows the command "git clone https://github.com/CiscoDevNet/MUD-Manager.git" being run on the Cisco MUD Manager.

  4. Change into the MUD manager directory:

    cd MUD-Manager

    This image shows the command "cd MUD-Manager" being run on the Cisco MUD Manager.

  5. Build the MUD manager by entering the following commands:

    ./configure

    This image shows the command "./configure" being run on the Cisco MUD Manager.

    Note: If a “pkg-config error” is thrown, run the command below to install the missing package:

    apt-get install pkg-config

    This image shows the command "apt-get install pkg-config" being run on the Cisco MUD Manager.

    make

    This image shows the command "make" being run on the Cisco MUD Manager.

    Note: If an “ac.local error” is thrown, run the command below to install the missing package:

    apt-get install automake

    This image shows the command "apt-get install automake" being run on the Cisco MUD Manager.

    make install

    This image shows the command "make install" being run on the Cisco MUD Manager.

2.1.3.3 MUD Manager Configuration

This section describes configuring the MUD manager to communicate with the NCCoE MUD file server and defining the attributes used for translating the fetched MUD files. Details about the configuration file and additional fields that can be set within this file can be accessed here: https://github.com/CiscoDevNet/MUD-Manager#editing-the-configuration-file.

  1. In the terminal, change to the MUD manager directory:

    cd /MUD-Manager

    This image shows the command "cd /MUD-Manager" being run on the Cisco MUD Manager.

  2. Copy the contents of the sample mud_manager_conf.json file to a different file:

    sudo cp examples/mud_manager_conf.json mud_manager_conf_nccoe.json

    This image shows the command "sudo cp examples/mud_manager_conf.json mud_manager_conf_nccoe.json" being run on the Cisco MUD Manager.

  3. Modify the contents of the new MUD manager configuration file:

    sudo vim mud_manager_conf_nccoe.json

    This image shows the command "sudo vim mud_manager_conf_nccoe.json " being run on the Cisco MUD Manager.

    {
    
       "MUD_Manager_Version" : 3,
    
       "MUDManagerAPIProtocol" : "http",
    
       "ACL_Prefix" : "ACS:",
    
       "ACL_Type" : "dACL-ingress-only",
    
       "COA_Password" : "cisco",
    
       "VLANs" : [
    
          { "VLAN_ID" : 3,
    
            "v4addrmask" : "192.168.13.0 0.0.0.255"
    
          },
    
          { "VLAN_ID" : 4,
    
            "v4addrmask" : "192.168.14.0 0.0.0.255"
    
          },
    
          { "VLAN_ID" : 5,
    
            "v4addrmask" : "192.168.15.0 0.0.0.255"
    
          }
    
       ],
    
       "Manufacturers" : [
    
          { "authority" : "mudfileserver",
    
            "cert" : "/home/mudtester/digicertca-chain.crt",
    
            "web_cert": "/home/mudtester/digicertchain.pem",
    
            "my_controller_v4" : "192.168.10.125",
    
            "my_controller_v6" : "2610:20:60CE:630:B000::7",
    
            "local_networks_v4" : "192.168.10.0 0.0.0.255",
    
            "local_networks_v6" : "2610:20:60CE:630:B000::",
    
            "vlan_nw_v4" : "192.168.13.0 0.0.0.255",
    
            "vlan" : 3
    
          },
    
          {
    
          "authority" : "www.gmail.com",
    
            "cert" : "/home/mudtester/digicertca-chain.crt",
    
            "web_cert": "/home/mudtester/digicertchain.pem",
    
            "vlan_nw_v4" : "192.168.14.0 0.0.0.255",
    
            "vlan" : 4
    
          }
    
       ],
    
       "DNSMapping" : {
    
          "www.osmud.org" : "198.71.233.87",
    
          "www.mqttbroker.com" : "192.168.4.6",
    
          "us.dlink.com" : "54.187.217.118",
    
          "www.nossl.net": "40.68.201.127",
    
          "www.trytechy.com" : "99.84.104.21"
    
        },
    
        "DNSMapping_v6" : {
    
          "www.mqttbroker.com" : "2610:20:60CE:630:B000::6",
    
          "www.updateserver.com" : "2610:20:60CE:630:B000::7",
    
          "www.dominiontea.com": "2a03:2880:f10c:83:face:b00c:0:25de"
    
        },
    
        "ControllerMapping" : {
    
          "https://www.google.com" : "192.168.10.104",
    
          "http://lightcontroller.example2.com": "192.168.4.77",
    
          "http://lightcontroller.example.com": "192.168.4.78"
    
        },
    
        "ControllerMapping_v6" : {
    
          "https:/www.google.com" : "ffff:2343:4444:::",
    
          "http://lightcontroller.example2.com": "ffff:2343:4444:::",
    
          "http://lightcontroller.example.com": "ffff:2343:4444:::"
    
         },
    
         "DefaultACL" : ["permit tcp any eq 22 any","permit udp any eq 68 any eq 67","permit udp any any eq 53", "deny ip any any"],
    
         "DefaultACL_v6" : ["permit udp any any eq 53", "deny ipv6 any any"]
    
      }
    

Details about the contents of the configuration file can be found at the link provided at the start of this section.

2.1.3.4 FreeRADIUS Installation

  1. Install the dependencies for FreeRADIUS:

    1. sudo apt-get install -y libtalloc-dev

      This image shows the command "sudo apt-get install -y libtalloc-dev" being run on the Cisco MUD Manager.

    2. sudo apt-get install -y libjson-c-dev

      This image shows the command "sudo apt-get install -y libjson-c-dev" being run on the Cisco MUD Manager.

    3. sudo apt-get install -y libcurl4-gnutls-dev

      This image shows the command "sudo apt-get install -y libcurl4-gnutls-dev" being run on the Cisco MUD Manager.

    4. sudo apt-get install -y libperl-dev

      This image shows the command "sudo apt-get install -y libperl-dev" being run on the Cisco MUD Manager.

    5. sudo apt-get install -y libkqueue-dev

      This image shows the command "sudo apt-get install -y libkqueue-dev" being run on the Cisco MUD Manager.

    6. sudo apt-get install -y libssl-dev

      This image shows the command "sudo apt-get install -y libssl-dev" being run on the Cisco MUD Manager.

  2. Download the source by entering the following command. (Note: Version 3.0.19 and later are recommended.)

    wget ftp://ftp.freeradius.org/pub/freeradius/freeradius-server-3.0.19.tar.gz

    This image shows the command "wget ftp://ftp.freeradius.org/pub/freeradius/freeradius-server-3.0.19.tar.gz" being run on the Cisco MUD Manager.

  3. Untar the downloaded file by entering the following command:

    tar -xf freeradius-server-3.0.19.tar.gz

    This image shows the command "tar -xf freeradius-server-3.0.19.tar.gz" being run on the Cisco MUD Manager.

  4. Move the FreeRADIUS directory to the root directory:

    sudo mv freeradius-server-3.0.19/ /

    image44

  5. Change to the FreeRADIUS directory:

    cd /freeradius-server-3.0.19/

    This image shows the command "cd /freeradius-server-3.0.19/" being run on the Cisco MUD Manager.

  6. Make and install the source by entering the following:

    1. sudo ./configure --with-rest --with-json-c --with-perl

      This image shows the command "sudo ./configure --with-rest --with-json-c --with-perl" being run on the Cisco MUD Manager.

    2. sudo make

      This image shows the command "sudo make" being run on the Cisco MUD Manager.

    3. sudo make install

      This image shows the command "sudo make install" being run on the Cisco MUD Manager.

2.1.3.5 FreeRADIUS Configuration

  1. Change to the FreeRADIUS subdirectory in the MUD manager directory:

    cd /MUD-Manager/examples/AAA-LLDP-DHCP/

    This image shows the command "cd /MUD-Manager/examples/AAA-LLDP-DHCP/" being run on the Cisco MUD Manager.

  2. Run the setup script:

    sudo ./FR-setup.sh

    This image shows the command "sudo ./FR-setup.sh" being run on the Cisco MUD Manager.

  3. Enter the following command to log in as root:

    sudo su

    This image shows the command "sudo su" being run on the Cisco MUD Manager.

  4. Change to the RADIUS directory:

    cd /usr/local/etc/raddb/

    This image shows the command "cd /usr/local/etc/raddb" being run on the Cisco MUD Manager.

  5. Open the clients.conf file:

    vim clients.conf

    This image shows the command "vim clients.conf" being run on the Cisco MUD Manager.

  6. Add the network access server (NAS) as an authorized client in the configuration file on the server by adding an entry for the NAS in the client.conf file that is opened. (Note: replace the IP address below with the IP address of the NAS, and insert the “secret” configured on the NAS to talk to the RADIUS servers.)

    client 192.168.10.2 {
       ipaddr = 192.168.10.2
       secret = cisco
    }
    

    An image of the previous configuration information on the Cisco MUD Manager

  7. Save and close the file.

2.1.3.6 Start MUD Manager and FreeRADIUS Server

  1. Start and enable the database by executing the following commands:

    sudo systemctl start mongod

    This image shows the command "sudo systemctl start mongod" being run on the Cisco MUD Manager.

    sudo systemctl enable mongod

    This image shows the command "sudo systemctl enable mongod" being run on the Cisco MUD Manager.

  2. Start the MUD manager in the foreground with logging enabled by entering the following command:

    sudo mud_manager -f /MUD-Manager/mud_manager_conf_nccoe.json -l 3

    This image shows the command "sudo mud_manager -f /MUD-Manager/mud_manager_conf_nccoe.json -l 3" being run on the Cisco MUD Manager.

    The following output should appear if the service started successfully:

    An showing the output of the Cisco MUD Manager running properly. This output shows many successes with no errors or warnings.

  3. Start the FreeRADIUS service in the foreground with logging enabled by entering the following command:

    sudo radiusd -Xxx

    This image shows the command "sudo radiusd -Xxx" being run on the Cisco MUD Manager.

At this point all the processes required to support MUD are running on the server side, and the next step is to configure the Cisco Catalyst switch. Once the switch configuration detailed in the Cisco Switch–Catalyst 3850-S setup section is completed, any DHCP activity on the network should appear in the output of the FreeRADIUS and MUD manager logs.

2.2 MUD File Server

2.2.1 MUD File Server Overview

For this build, the NCCoE built a MUD file server hosted within the lab infrastructure. This file server signs and stores the MUD files along with their corresponding signature files for the MUD-capable IoT devices used in the build. The MUD file server is also responsible for serving the MUD file and the corresponding signature file upon request from the MUD manager.

2.2.2 Configuration Overview

The following subsections document the software and network configurations for the MUD file server.

2.2.2.1 Network Configuration

This server was hosted in the NCCoE’s virtual environment, functioning as a cloud service. Its IP address was statically assigned.

2.2.2.2 Software Configuration

For this build, the server ran on the CentOS 7 operating system. The MUD files and signatures were hosted by an Apache web server and configured to use Secure Sockets Layer/Transport Layer Security (SSL/TLS) encryption.

2.2.2.3 Hardware Configuration

The MUD file server was hosted in the NCCoE’s virtual environment, functioning as a cloud service.

2.2.3 Setup

The following subsections describe the process for configuring the MUD file server.

2.2.3.1 Apache Web Server

The Apache web server was set up by using the official Apache documentation at https://httpd.apache.org/docs/current/install.html. After that, SSL/TLS encryption was set up by using the digital certificate and key obtained from DigiCert. This was set up by using the official Apache documentation, found at https://httpd.apache.org/docs/current/ssl/ssl_howto.html.

2.2.3.2 MUD File Creation and Signing

This section details creating and signing a MUD file on the MUD file server. The MUD specification does not mandate that this signing process be performed on the MUD file server itself.

2.2.3.2.1 MUD File Creation

An online tool called MUD Maker was used to build MUD files. Once the permitted communications have been defined for the IoT device, proceed to www.mudmaker.org to leverage the online tool. There is also a list of sample MUD files on the site, which can be used as a reference. Upon navigating to www.mudmaker.org, complete the following steps to create a MUD file:

  1. Specify the host that will be serving the MUD file and the model name of the device in the appropriate input fields, which are outlined in red in the screenshot below. (Note: this will result in the MUD URL for this device.)

    Sample input: mudfileserver, testmudfile

    An image of mudmaker.org with the mudurl section highlighted.

  2. Specify the Manufacturer Name of the device in the appropriate input field, which is outlined in red in the screenshot below:

    An image of mudmaker.org with the Manufacturer Name section highlighted.

  3. Include a URL to provide documentation about this device in the appropriate input field, which is outlined in red in the screenshot below:

    An image of mudmaker.org with the URL to documentation about this device section highlighted.

  4. Include a short description of the device in the appropriate input field, which is outlined in red in the screenshot below:

    An image of mudmaker.org with the short description section highlighted.

  5. Check the boxes for the types of network communication that are allowed for the device:

    An image of mudmaker.org with the internet communication checkbox highlighted.

  6. Specify the IP version that the device leverages:

    An image of mudmaker.org with the protocol version dropdown box highlighted.

  7. Specify values for the fields (Internet Hosts, Protocol, Local Port, Remote Port, and Initiated by) that describe the communications that will be permitted for the device:

    An image of mudmaker.org with the internet hosts section highlighted.

  8. Click Submit to generate the MUD file:

    An image of mudmaker.org with the submit button highlighted.

  9. Once completed, the page will redirect to the following page that outputs the MUD file on the screen. Click Download to download the MUD file, which is a .JSON file:

    An image of mudmaker.org with the Download button highlighted.

  10. Click Save to store a copy of the MUD file:

An image of the Internet Explorer download dialog with the Save button highlighted.

2.2.3.2.2 MUD File Signature Creation and Verification

In this build, OpenSSL is used to sign and verify MUD files. This example uses the MUD file created in the previous section, which is named ublox.json; the Signing Certificate; the Private Key for the Signing Certificate; the Intermediate Certificate for the Signing Certificate; and the Certificate of the Trusted Root Certificate Authority (CA) for the Signing Certificate.

  1. Sign the MUD file by using the following command:

    sudo openssl cms -sign -signer <Signing Certificate> -inkey <Private Key for Signing Certificate> -in <Name of MUD File> -binary -outform DER -binary-certfile <Intermediate Certificate for Signing Certificate> -out <Name of MUD File without the .json file extension>.p7s
    

    This image shows the previous command being run on the MUD File Server.

    This will create a signature file for the MUD file that has the same name as the MUD file but ends with the .p7s file extension, i.e., in our case ublox.p7s.

  2. Manually verify the MUD file signature by using the following command:

    sudo openssl cms -verify -in <Name of MUD File>.p7s -inform DER -content <Name of MUD File>.json -CAfile <Certificate of Trusted Root Certificate Authority for Signing Certificate>
    

    This image shows the above command being run on the MUD File Server.

If a valid file signature was created successfully, a corresponding message should appear. Both the MUD file and MUD file signature should be placed on the MUD file server in the Apache server directory.

2.3 Cisco Switch–Catalyst 3850-S

2.3.1 Cisco 3850-S Catalyst Switch Overview

The switch used in this build is an enterprise-class, layer 3 switch. It is a Cisco Catalyst 3850-S that had been modified to support MUD functionality as a proof-of-concept implementation. In addition to providing DHCP services, the switch acts as a broker for connected IoT devices for authentication, authorization, and accounting through a FreeRADIUS server. The Link Layer Discovery Protocol (LLDP) is enabled on ports that MUD-capable devices are plugged into to help facilitate recognition of connected IoT device features, capabilities, and neighbor relationships at layer 2. Additionally, an access session policy is configured on the switch to enable port control for multihost authentication and port monitoring. The combined effect of these switch configurations is a dynamic access list, which has been generated by the MUD manager, being active on the switch to permit or deny access to and from MUD-capable IoT devices.

2.3.2 Configuration Overview

The following subsections document the network, software, and hardware configurations for the Cisco Catalyst 3850-S switch.

2.3.2.1 Network Configuration

This section describes how to configure the required Cisco Catalyst 3850-S switch to support the build. A special image for the Catalyst 3850-S was provided by Cisco to support MUD-specific functionality. In our build, the switch is integrated with a DHCP server and a FreeRADIUS server, which together support delivery of the MUD URL to the MUD manager via either DHCP or LLDP. The MUD manager is also able to generate and send a dynamic access list to the switch, via the RADIUS server, to permit or deny access to and from the IoT devices. In addition to hosting directly connected IoT devices on VLANs 1, 3, and 4, the switch hosts both the MUD manager and the FreeRADIUS servers on VLAN 2. As illustrated in Figure 2‑1, each locally configured VLAN is protected by a firewall that connects the lab environment to the NIST data center, which provides internet access for all connected devices.

Figure 2‑1 Physical Architecture–Build 1

Diagram of Physical Architecture for Build 1. Explanation of components can be found above.

2.3.2.2 Software Configuration

The prototype, MUD-capable Cisco 3850-S used in this build is running internetwork operating system (IOS) version 16.09.02.

2.3.2.3 Hardware Configuration

The Catalyst 3850-S switch configured in the lab consists of 24 one-gigabit Ethernet ports with two optional 10-gigabit Ethernet uplink ports. A customized version of Cat-OS is installed on the switch. The versions of the OS are as follows:

  • Cat3k_caa-guestshell.16

  • Cat3k_caa-rpbase.16.06

  • Cat3k_caa-rpcore.16.06

  • Cat3k_caa-srdriver.16.06.0

  • Cat3k_caa-webui.16.06.0

2.3.3 Setup

Table 2‑1 lists the Cisco 3850-S switch running configuration used for the lab environment. In addition to the IOS version and a few generic configuration items, configuration items specifically relating to integration with the MUD manager and IoT devices are highlighted in bold fonts; these include DHCP, LLDP, AAA, RADIUS, and policies regarding access session. Table 2‑1 also provides a description of each configuration item for ease of understanding.

Table 2‑1 Cisco 3850-S Switch Running Configuration

Configuration Item

Description

version 16.9

no service pad

service timestamps debug datetime msec

service timestamps log datetime msec

service call-home

no platform punt-keepalive disable-kernel-core

!

hostname Build1

!

general overview of configuration information needed to configure AAA to use RADIUS and configure the RADIUS server itself. Note that the FreeRADIUS and AAA passwords must match.

aaa new-model

!

enables AAA

aaa authentication dot1x default group radius

creates an 802.1X AAA authentication method list

aaa authorization network default group radius

configures network authorization via RADIUS, including network-related services such as VLAN assignment

aaa accounting identity default start-stop group radius

enables accounting method list for session-aware networking subscriber services

aaa accounting network default start-stop group radius

!

enables accounting for all network-related service requests

aaa server radius dynamic-author
client 192.168.11.45 server-key cisco
server-key cisco
!
aaa session-id common

enables dynamic authorization local server configuration mode and specifies a RADIUS client/key from which a device accepts change of authorization (CoA) and disconnect requests

radius server AAA

address ipv4 192.168.11.45 auth-port 1812

enables AAA server from the list of multiple AAA servers configured

acct-port 1813
key cisco

uses the IP address and ports on which the FreeRADIUS server is listening

ip routing

!

ip dhcp excluded-address 192.168.10.1 192.168.10.100

!

DHCP server configuration to exclude selected addresses from pool

ip dhcp pool NCCOE-V3
network 192.168.13.0 255.255.255.0
default-router 192.168.13.1
dns-server 8.8.8.8
lease 0 12
!

DHCP server configuration to assign IP address to devices on VLAN 3

ip dhcp pool NCCOE-V4
network 192.168.14.0 255.255.255.0
default-router 192.168.14.1
dns-server 8.8.8.8
!

DHCP server configuration to assign IP address to devices on VLAN 4

ip dhcp pool NCCOE
network 192.168.10.0 255.255.255.0
default-router 192.168.10.2
dns-server 8.8.8.8
lease 0 12
!

DHCP server configuration to assign IP address to devices on VLAN 1

ip dhcp snooping

ip dhcp snooping vlan 1,3

!

enables DHCP snooping globally

specifically enables DHCP snooping on VLANs 1 and 3

access-session attributes filter-list list mudtest
lldp
dhcp
access-session accounting attributes filter-spec include list mudtest
access-session monitor
!

configures access-session attributes to cause LLDP Time Length Values (including the MUD URL) to be forwarded in an accounting message to the AAA server

dot1x logging verbose

global configuration command to filter 802.1x authentication verbose messages

ldp run

!

enables LLDP, a discovery protocol that runs over layer 2 (the data link layer) to gather information on non-Cisco-manufactured devices

policy-map type control subscriber mud-mab-test
event session-started match-all
10 class always do-until-failure
10 authenticate using mab
!

configures identity control policies that define the actions that session-aware networking takes in response to specified conditions and subscriber events

template mud-mab-test
switchport mode access
mab
access-session port-control auto
service-policy type control subscriber mud-mab-test
!

enables policy-map (mud-mab-test) and template to cause media access control (MAC) authentication bypass (MAB) to happen

dynamically applies an interface template to a target

sets the authorization state of a port. The default value is force-authorized.

applies the above previously configured control policy called mud-mab-test

interface GigabitEthernet1/0/13
source template mud-mab-test
!

statically applies an interface template to a target, i.e., an IoT device

interface GigabitEthernet1/0/14
source template mud-mab-test
!

statically applies an interface template to a target, i.e., an IoT device

interface GigabitEthernet1/0/15
source template mud-mab-test
!

statically applies an interface template to a target, i.e., an IoT device

interface GigabitEthernet1/0/16
source template mud-mab-test
!

statically applies an interface template to a target, i.e., an IoT device

interface GigabitEthernet1/0/17
source template mud-mab-test
!

statically applies an interface template to a target, i.e., an IoT device

interface GigabitEthernet1/0/18
source template mud-mab-test
!

statically applies an interface template to a target, i.e., an IoT device

interface GigabitEthernet1/0/19
source template mud-mab-test
!

statically applies an interface template to a target, i.e., an IoT device

interface GigabitEthernet1/0/20
source template mud-mab-test

statically applies an interface template to a target, i.e., an IoT device

interface Vlan1
ip address 192.168.10.2 255.255.255.0
!

configure and address VLAN1 interface for inter-VLAN routing

interface Vlan2
ip address 192.168.11.1 255.255.255.0
!

configure and address VLAN2 interface for inter-VLAN routing

interface Vlan3
ip address 192.168.13.1 255.255.255.0
!

configure and address VLAN3 interface for inter-VLAN routing

interface Vlan4
ip address 192.168.14.1 255.255.255.0
!

configure and address VLAN4 interface for inter-VLAN routing

interface Vlan5
ip address 192.168.15.1 255.255.255.0
!

configure and address VLAN5 interface for inter-VLAN routing

!

ip default-gateway 192.168.10.1

ip forward-protocol nd

ip http server

ip http authentication local

ip http secure-server

ip route 0.0.0.0 0.0.0.0 192.168.10.1

ip route 192.168.12.0 255.255.255.0 192.168.5.1

!

2.4 DigiCert Certificates

2.4.1 DigiCert CertCentral® Overview

DigiCert’s CertCentral® web-based platform allows provisioning and management of publicly trusted X.509 certificates for a variety of purposes. After establishing an account, clients can log in, request, renew, and revoke certificates by using only a browser. For this build, two certificates were provisioned: a private TLS certificate for the MUD file server to support the https connection from the MUD manager to the MUD file server, and a Premium Certificate for signing the MUD files.

2.4.2 Configuration Overview

This section typically documents the network, software, and hardware configurations, but that is not necessary for this component.

2.4.3 Setup

DigiCert allows certificates to be requested through its web-based platform, CertCentral. A user account is needed to access CertCentral. For details on creating a user account and setting up an account, follow the steps described here: https://docs.digicert.com/get-started/.

2.4.3.1 TLS Certificate

For this build, we leveraged DigiCert’s private TLS certificate because the MUD file server is hosted internally. This certificate supports https connections to the MUD file server, which are required by the MUD manager. Additional information about the TLS certificates offered by DigiCert can be found at https://www.digicert.com/security-certificate-support/.

For instructions on how to order a TLS certificate, proceed to the DigiCert documentation found here, and follow the process for the specific TLS certificate being requested: https://docs.digicert.com/manage-certificates/order-your-ssltls-certificates/.

Once requested, integrate the certificate onto the MUD file server as described in Section 2.2.3.1.

2.4.3.2 Premium Certificate

To sign MUD files according to the MUD specification, a client certificate is required. For this implementation, we leveraged DigiCert’s Premium Certificate to sign MUD files. This certificate supports signing or encrypting Secure/Multipurpose Internet Mail Extensions messages, which is required by the specification.

For detailed instructions on how to request and implement a Premium Certificate, proceed to the DigiCert documentation found here: https://docs.digicert.com/manage-certificates/client-certificates-guide/.

Once requested, sign MUD files as described in Section 2.2.3.2.2.

2.5 IoT Devices

2.5.1 Molex PoE Gateway and Light Engine

This section provides configuration details of the MUD-capable Molex PoE Gateway and Light Engine used in the build. This component emits a MUD URL that uses LLDP.

2.5.1.1 Configuration Overview

The Molex PoE Gateway runs firmware created and provided by Molex. This firmware was modified by Molex to emit a MUD URL that uses an LLDP message.

2.5.1.1.1 Network Configuration

The Molex PoE Gateway is connected to the network over a wired Ethernet connection. The IP address is assigned dynamically by using DHCP.

2.5.1.1.2 Software Configuration

For this build, the Molex PoE Gateway is configured with Molex’s PoE Gateway firmware, version 1.6.1.8.4.

2.5.1.1.3 Hardware Configuration

The Molex PoE Gateway used in this build is model number 180993-0001, dated March 2017.

2.5.1.2 Setup

The Molex PoE Gateway is controlled via the Constrained Application Protocol (CoAP), and CoAP commands were used to ensure that device functionality was maintained during the MUD process.

2.5.1.2.1 DHCP Client Configuration

The device uses the default DHCP client included in the Molex PoE Gateway firmware.

2.5.2 IoT Development Kits–Linux Based

This section provides configuration details for the Linux-based IoT development kits used in the build, which emit MUD URLs by using DHCP. It also provides information regarding a basic IoT application used to test the MUD process.

2.5.2.1 Configuration Overview

The devkits run various flavors of Linux-based operating systems and are configured to emit a MUD URL during a typical DHCP transaction. They also run a Python script that allows the devkits to receive and process commands by using the MQTT protocol, which can be sent to peripherals connected to the devkits.

2.5.2.1.1 Network Configuration

The devkits are connected to the network over a wired Ethernet connection. The IP address is assigned dynamically by using DHCP.

2.5.2.1.2 Software Configuration

For this build, the Raspberry Pi is configured on Raspbian 9, the Samsung ARTIK 520 is configured on Fedora 24, and the Intel UP Squared Grove is configured on Ubuntu 16.04 LTS. The devkits also utilized dhclient as the default DHCP client. This DHCP client is provided with many Linux distributions and can be installed using a preferred package manager if not currently present.

2.5.2.1.3 Hardware Configuration

The hardware used for these devkits included the Raspberry Pi 3 Model B, Samsung ARTIK 520, and Intel UP Squared Grove.

2.5.2.2 Setup

The following subsection describes setting up the devkits to send a MUD URL during the DHCP transaction and to act as a connected device by leveraging an MQTT broker server (we describe setting up the MQTT broker server in Section 2.8).

2.5.2.2.1 DHCP Client Configuration

We leveraged dhclient as the default DHCP client for these devices due to the availability of the DHCP client on different Linux platforms and the ease of emitting MUD URLs via DHCP.

To set up the dhclient configuration:

  1. Open a terminal on the device.

  2. Ensure that any other conflicting DHCP clients are disabled or removed.

  3. Install the dhclient package (if needed).

  4. Edit the dhclient.conf file by entering the following command:

    sudo nano /etc/dhcp/dhclient.conf

    This image shows the command "sudo nano /etc/dhcp/dhclient.conf" being run on the Raspberry Pi Devkit.

  5. Add the following lines:

    option mud-url code 161 = text;
    
    send mud-url = "<insert URL for MUD File here>";
    

    This image shows the following lines being added to the /etc/dhcp/dhclient.conf file on the Raspberry Pi Devkit: option mud-url code 161 = text; send mud-url = "https://mudfileserver/pi4";

  6. Save and close the file.

  7. Reboot the device:

    reboot

    This image shows the command "reboot" being run on the Raspberry Pi Devkit.

  8. Open a terminal.

  9. Execute the dhclient:

    sudo dhclient -v

    This image shows the command "sudo dhclient -v" being run on the Raspberry Pi Devkit.

2.5.2.2.2 IoT Application for Testing

The following Python application was created by the NCCoE to enable the devkits to act as basic IoT devices:

#Program: IoTapp.
#Version: 1.0
#Purpose: Provide IoT capabilities to devkit.
#Protocols: MQTT.

#Functionality: Allow remote control of LEDs on connected breadboard.

#Libraries
import paho.mqtt.client as mqttClient
import time
import RPi.GPIO as GPIO

#Global Variables
BrokerAddress = "192.168.1.87" #IP address of Broker(Server), change as needed. Best practice would be a registered domain name that can be queried for appropriate server address.

BrokerPort = "1883" #Default port used by most MQTT Brokers. Would be 1883 if using Transport Encryption with TLS.
ConnectionStatus = "Disconnected" #Status of connection to Broker. Should be either "Connected" or "Disconnected".
LED = 26

#Supporting Functions
def on_connect(client, userdata, flags, rc): #Function for connection status to Broker.
   if rc == 0:

      ConnectionStatus = "Connected to Broker!"
      print(ConnectionStatus)

   else:
      ConnectionStatus = "Connection Failed!"
      print(ConnectionStatus)

def on_message(client, userdata, msg): #Function for parsing message data.
   if "ON" in msg.payload:
      print("ON!")
      GPIO.output(LED, 1)

   if "OFF" in msg.payload:
      print("OFF!")
      GPIO.output(LED, 0)

def MQTTapp():
   client = mqttClient.Client() #New instance.
   client.on_connect = on_connect
   client.on_message = on_message
   client.connect(BrokerAddress, BrokerPort)
   client.loop_start()
   client.subscribe("test")
   try:
      while True:
         me.sleep(1)

   except KeyboardInterrupt:
      print("8")
      client.disconnect()
      client.loop_stop()

#Main Function

def main():

   GPIO.setmode(GPIO.BCM)
   GPIO.setup(LED, GPIO.OUT)

   print("Main function has been executed!")
   MQTTapp()

if \__name_\_ == "__main__":
   main()

2.5.3 IoT Development Kit–u-blox C027-G35

This section details configuration of a u-blox C027-G35, which emits a MUD URL by using DHCP, and a basic IoT application used to test MUD rules.

2.5.3.1 Configuration Overview

This devkit runs the Arm Mbed-OS and is configured to emit a MUD URL during a typical DHCP transaction. It also runs a basic IoT application to test MUD rules.

2.5.3.1.1 Network Configuration

The u-blox C027-G35 is connected to the network over a wired Ethernet connection. The IP address is assigned dynamically by using DHCP.

2.5.3.1.2 Software Configuration

For this build, the u-blox C027-G35 was configured on the Mbed-OS 5.10.4 operating system.

2.5.3.1.3 Hardware Configuration

The hardware used for this devkit is the u-blox C027-G35.

2.5.3.2 Setup

The following subsection describes setting up the u-blox C027-G35 to send a MUD URL in the DHCP transaction and to act as a connected device by establishing network connections to the update server and other destinations.

2.5.3.2.1 DHCP Client Configuration

To add MUD functionality to the Mbed-OS DHCP client, the following two files inside Mbed-OS require modification:

  • mbed-os/features/lwipstack/lwip/src/include/lwip/prot/dhcp.h

    • NOT mbed-os/features/lwipstack/lwip/src/include/lwip/dhcp.h

  • mbed-os/features/lwipstack/lwip/src/core/ipv4/lwip_dhcp.c

Changes to include/lwip/prot/dhcp.h:

  1. Add the following line below the greatest DCHP option number (67) on line 170:

    #define DHCP_OPTION_MUD_URL_V4 161 /*MUD: RFC-ietf-opsawg-mud-25 draft-ietf-opsawg-mud-08, Manufacturer Usage Description*/

Changes to core/ipv4/lwip_dhcp.c:

  1. Change within container around line 141:

    To enum dhcp_option_idx (at line 141) before the first #if, add

    DHCP_OPTION_IDX_MUD_URL_V4, /*MUD: DHCP MUD URL Option*/

    It should now look like the screenshot below:

    A screenshot of the file, now including the added lines.

  2. Change within the function around line 975:

    1. To the list of local variables for static err_t dhcp_discover(struct netif *netif), add the desired MUD URL (www.example.com used here):

      mud_url

      Note: The MUD URL must be less than 255 octets/bytes/characters long.

    2. Within if (result == ERR_OK) after

      dhcp_option(dhcp, DHCP_OPTION_PARAMETER_REQUEST_LIST, LWIP_ARRAYSIZE(dhcp_discover_request_options)); for (i = 0; i < LWIP_ARRAYSIZE(dhcp_discover_request_options); i++) { dhcp_option_byte(dhcp, dhcp_discover_request_options[i]); }

      and before:

      image82

      add:

      image83

  3. Change within the function around line 1486:

    Within the following function:

    image84

    Within switch(op) before default, add the following case (around line 1606):

    image85

  4. Compile by using the following command:

    image82

2.5.3.2.2 IoT Application for Testing

The following application was created by the NCCoE to enable the devkit to test the build as a MUD-capable device:

#include "mbed.h"
#include "EthernetInterface.h"

//DigitalOut led1(LED1);
PwmOut led2(LED2);
Serial pc(USBTX, USBRX);

float brightness = 0.0;

// Network interface
EthernetInterface net;

// Socket demo
int main() {
   int led1 = true;

   for (int i = 0; i < 4; i++) {

      led2 = (led1)? 0.5 : 0.0;

      led1 = !led1;
      wait(0.5);
   }

   for (int i = 0; i < 8; i++) {

      led2 = (led1)? 0.5 : 0.0;

      led1 = !led1;
      wait(0.25);
   }

   for (int i = 0; i < 8; i++) {

      led2 = (led1)? 0.5 : 0.0;

      led1 = !led1;
      wait(0.125);
   }

   TCPSocket socket;
   char sbuffer[] = "GET / HTTP/1.1\r\nHost: www.updateserver.com\r\n\r\n";
   char bbuffer[] = "GET / HTTP/1.1\r\nHost: www.unapprovedserver.com\r\n\r\n";
   int scount, bcount;
   char rbuffer[64];
   char brbuffer[64];
   int rcount, brcount;

   /* By default grab an IP address */
   // Bring up the ethernet interface
   pc.printf("Ethernet socket example\r\n");
   net.connect();
   // Show the network address
   const char *ip = net.get_ip_address();
   pc.printf("IP address is: %s\r\n", ip ? ip : "No IP");
   socket.open(&net);
   /* End of default IP address */

   pc.printf("Press U to turn LED1 brightness up, D to turn it down, G to get IP, R to release IP, H for HTTP request, B for blocked HTTP request\r\n");

   while(1) {

      char c = pc.getc();

      if((c == 'u') && (brightness < 0.5)) {
         brightness += 0.01;
         led2 = brightness;
      }

      if((c == 'd') && (brightness > 0.0)) {
         brightness -= 0.01;
         led2 = brightness;
      }

      if(c == 'g'){
         // Bring up the ethernet interface
         pc.printf("Sending DHCP Request...\r\n");
         net.connect();
         // Show the network address
         const char *ip = net.get_ip_address();
         pc.printf("IP address is: %s\r\n", ip ? ip : "No IP");
      }

      if(c == 'r'){
         socket.close();
         net.disconnect();
         pc.printf("IP Address Released\r\n");
      }

      if(c == 'h'){
         pc.printf("Sending HTTP Request...\r\n");
         // Open a socket on the network interface, and create a TCP connection
         socket.open(&net);
         socket.connect("*www.updateserver.com*", 80);
         // Send a simple http request
         scount = socket.send(sbuffer, sizeof sbuffer);
         pc.printf("sent %d [%.*s]\r\n", scount, strstr(sbuffer, "\r\n")-sbuffer, sbuffer);
         // Receive a simple http response and print out the response line
         rcount = socket.recv(rbuffer, sizeof rbuffer);
         pc.printf("recv %d [%.*s]\r\n", rcount, strstr(rbuffer, "\r\n")-rbuffer, rbuffer);
         socket.close();
      }

      if(c == 'b'){
         pc.printf("Sending Blocked HTTP Request...\r\n");
         // Open a socket on the network interface, and create a TCP connection
         socket.open(&net);
         socket.connect("www.unapprovedserver.com", 80);
         // Send a simple http request
         bcount = socket.send(bbuffer, sizeof bbuffer);
         pc.printf("sent %d [%.*s]\r\n", bcount, strstr(bbuffer, "\r\n")-bbuffer, bbuffer);
         // Receive a simple http response and print out the response line
         brcount = socket.recv(brbuffer, sizeof brbuffer);
         pc.printf("recv %d [%.*s]\r\n", brcount, strstr(brbuffer, "\r\n")-brbuffer, brbuffer);
         socket.close();
      }

   }

}

2.5.4 IoT Devices–Non-MUD-Capable

This section details configuration of non-MUD-capable IoT devices attached to the implementation network. These include several types of devices, such as cameras, mobile phones, lighting, a connected assistant, a printer, a baby monitor, a wireless access point, and a digital video recorder. These devices did not emit a MUD URL or have MUD capabilities of any kind.

2.5.4.1 Configuration Overview

These non-MUD-capable IoT devices are unmodified and still retain the default manufacturer configurations.

2.5.4.1.1 Network Configuration

These IoT devices are configured to obtain an IP address via DHCP.

2.5.4.1.2 Software Configuration

The software on these devices is configured according to standard manufacturer instructions.

2.5.4.1.3 Hardware Configuration

The hardware used in these devices is unmodified from manufacturer specifications.

2.5.4.2 Setup

These devices were set up according to the manufacturer instructions and connected to the Cisco switch via Ethernet cable or connected wirelessly through the wireless access point.

2.5.4.2.1 DHCP Client Configuration

These IoT devices used the default DHCP clients provided by the original manufacturer and were not modified in any way.

2.6 Update Server

This section describes how to implement a server that will act as an update server. It will attempt to access and be accessed by the IoT device, in this case one of the development kits we built in the lab.

2.6.1 Update Server Overview

The update server is an Apache web server that hosts mock software update files to be served as software updates to our IoT device devkits. When the server receives an http request, it sends the corresponding update file.

2.6.2 Configuration Overview

The following subsections document the software, hardware, and network requirements for the update server.

2.6.2.1 Network Configuration

The IP address was statically assigned.

2.6.2.2 Software Configuration

For this build, the update server was configured on the Ubuntu 18.04 LTS operating system.

2.6.2.3 Hardware Configuration

The update server was hosted in the NCCoE’s virtual environment, functioning as a cloud service.

2.6.3 Setup

The Apache web server was set up by using the official Apache documentation at https://httpd.apache.org/docs/current/install.html. After completing the process, the SSL/TLS encryption was set up by using the digital certificate and key obtained from DigiCert. This was set up by using the official Apache documentation, found at https://httpd.apache.org/docs/current/ssl/ssl_howto.html.

The following configurations were made to the server to host the update file:

  1. Open a terminal.

  2. Change directories to the Hypertext Markup Language (HTML) folder:

    cd /var/www/html/

    This image shows the command "cd /var/www/html" being run on the Update Server.

  3. Create the update file. (Note: this is a mock update file.)

    touch IoTsoftwareV2.tar.gz

    This image shows the command "touch IoTsoftwareV2.tar.gz" being run on the Update Server.

2.7 Unapproved Server

This section describes how to implement a server that will act as an unapproved server. It will attempt to access and to be accessed by an IoT device, in this case one of the MUD-capable devices on the implementation network.

2.7.1 Unapproved Server Overview

The unapproved server is an internet host that is not explicitly authorized in the MUD file to communicate with the IoT device. When the IoT device attempts to connect to this server, the router or switch should not allow this traffic because it is not an approved internet service as defined by the corresponding MUD file. Likewise, when the server attempts to connect to the IoT device, this traffic should be denied at the router or switch.

2.7.2 Configuration Overview

The following subsections document the software, hardware, and network configurations for the unapproved server.

2.7.2.1 Network Configuration

The unapproved server hosts a web server that is accessed via Transmission Control Protocol (TCP) port 80. Any applications that request access to this server need to be able to connect on this port. Use firewall-cmd, iptables, or any other system utility for manipulating the firewall to open this port.

2.7.2.2 Software Configuration

For this build, the CentOS 7 OS was leveraged with an Apache web server.

2.7.2.3 Hardware Configuration

The unapproved server was hosted in the NCCoE’s virtual environment, functioning as a cloud service. The IP address was statically assigned.

2.7.3 Setup

The following subsection describes the setup process for configuring the unapproved server.

2.7.3.1 Apache Web Server

The Apache web server was set up by using the official Apache documentation at https://httpd.apache.org/docs/current/install.html. SSL/TLS encryption was not used for this server.

2.8 MQTT Broker Server

2.8.1 MQTT Broker Server Overview

For this build, the open-source tool Mosquitto was used as the MQTT broker server. The server communicates publish and subscribe messages among multiple clients. For our implementation, this server allows mobile devices set up with the appropriate application to communicate with the MQTT-enabled IoT devices in the build. The messages exchanged by the devices are on and off messages, which allow the mobile device to control the LED light on the MQTT-enabled IoT device.

2.8.2 Configuration Overview

The following subsections document the software, hardware, and network requirements for the MQTT broker server.

2.8.2.1 Network Configuration

The MQTT broker server was hosted in the NCCoE’s virtual environment, functioning as a cloud service. The IP address was statically assigned.

The server is accessed via TCP port 1883. Any clients that require access to this server need to be able to connect on this port. Use firewall-cmd, iptables, or any other system utility for manipulating the firewall to open this port.

2.8.2.2 Software Configuration

For this build, the MQTT broker server was configured on an Ubuntu 18.04 LTS operating system.

2.8.2.3 Hardware Configuration

This server was hosted in the NCCoE’s virtual environment, functioning as a cloud service. The IP address was statically assigned.

2.8.3 Setup

In this section we describe setting up the MQTT broker server to communicate messages to and from the controlling application and the IoT device.

2.8.3.1 Mosquitto Setup

  1. Install the open-source MQTT broker server, Mosquitto, by entering the following command:

    sudo apt-get update && sudo apt-get install mosquitto

    This image shows the command "sudo apt-get update && sudo apt-get install mosquitto" being run on the MQTT Broker.

    Following the installation, this implementation leveraged the default configuration of the Mosquitto server. The MQTT broker server was set up by using the official Mosquitto documentation at https://mosquitto.org/man/.

2.9 Forescout–IoT Device Discovery

This section describes how to implement Forescout’s appliance and enterprise manager to provide device discovery on the network.

2.9.1 Forescout Overview

The Forescout appliance discovers, catalogs, profiles, and classifies the devices that are connected to the demonstration network. When a device is added to or removed from the network, the Forescout appliance is updated and actively monitors these devices on the network. The administrator will be able to manage multiple Forescout appliances from a central point by integrating the appliance with the enterprise manager.

2.9.2 Configuration Overview

The following subsections document the software, hardware, and network requirements for the Forescout appliance and enterprise manager.

2.9.2.1 Network Configuration

The virtual Forescout appliance was hosted on VLAN 2 of the Cisco switch. It was set up with just the monitor interface. The network configuration for the Forescout appliance was completed by using the official Forescout documentation at https://docs.forescout.com/bundle/Installation_Guide_8.0.1/resource/Installation_Guide_8.0.1.pdf (see Chapters 2 and 8).

The virtual enterprise manager was hosted in the virtual environment that is shared across each build.

2.9.2.2 Software Configuration

The build leveraged a virtual Forescout appliance VCT-R version 8.0.1 along with a virtual enterprise manager VCEM-05 version 8.0.1. Both virtual appliances were built on a Linux OS supported by Forescout.

Forescout provides software for managing the appliances on the network. The Forescout console is software that allows management of the Forescout appliance/enterprise manager and visualization of the data gathered by the appliances.

2.9.2.3 Hardware Configuration

The build leveraged a virtual Forescout appliance, which was set up in the lab environment on a dedicated machine hosting the local virtual machines in Build 1.

The virtual enterprise manager was hosted in the NCCoE’s virtual environment with a static IP assignment.

2.9.3 Setup

In this section we describe setting up the virtual Forescout appliance and the virtual enterprise manager.

2.9.3.1 Forescout Appliance Setup

The virtual Forescout appliance was set up by using the official Forescout documentation at https://docs.forescout.com/bundle/Installation_Guide_8.0.1/resource/Installation_Guide_8.0.1.pdf (see Chapters 3 and 8).

3 Build 2 Product Installation Guides

This section of the practice guide contains detailed instructions for installing and configuring the products used to implement Build 2. For additional details on Build 2’s logical and physical architectures, please refer to NIST SP 1800-15B.

3.1 Yikes! MUD Manager

This section describes the Yikes! MUD manager version v1.1.3, which is a software package deployed on the Yikes! router. It should not require configuration as it should be fully functioning upon connecting the Yikes! router to the network.

3.1.1 Yikes! MUD Manager Overview

The Yikes! MUD manager is a software package supported by MasterPeace within the Yikes! physical router. The version of the Yikes! router used in this implementation supports IoT devices that leverage DHCP as their default MUD emission method.

3.1.2 Configuration Overview

At this implementation, no additional network, software, or hardware configuration was required to enable the Yikes! MUD manager capability on the Yikes! router.

3.1.3 Setup

At this implementation, no setup was required to enable the Yikes! MUD manager capability on the Yikes! router. See the Yikes! Router section for details on the router setup.

3.2 MUD File Server

3.2.1 MUD File Server Overview

For this build, the NCCoE leveraged a MUD file server hosted by MasterPeace. This file server hosts MUD files along with their corresponding signature files for the MUD-capable IoT devices used in Build 2. The MUD file server is responsible for serving the MUD file and the corresponding signature file upon request from the MUD manager. These files were created by the NCCoE and provided to MasterPeace to host due to the Yikes! cloud component requirement that the MUD file server be internet accessible to display the contents of the MUD file in the Yikes! user interface (UI).

To build an on-premises MUD file server and to create MUD files for MUD-capable IoT devices, please follow the instructions in Build 1’s MUD File Server section.

3.3 Yikes! DHCP Server

This section describes the Yikes! DHCP server, which should also be fully functional out of the box and should not require any modification upon receipt.

3.3.1 Yikes! DHCP Server Overview

The Yikes! DHCP server is MUD capable and, like the Yikes! MUD manager and Yikes! threat-signaling agent, is a logical component within the Yikes! router. In addition to dynamically assigning IP addresses, it recognizes the DHCP option (161) and logs DHCP events that include this option to a log file. This log file is monitored by the Yikes! MUD manager, which is responsible for handling the MUD requests.

3.3.2 Configuration Overview

At this implementation, no additional network, software, or hardware configuration was required to enable the Yikes! DHCP server capability on the Yikes! router.

3.3.3 Setup

At this implementation, no additional setup was required.

3.4 Yikes! Router

This section describes how to implement and configure the Yikes! router, which requires minimal configuration from a user standpoint.

3.4.1 Yikes! Router Overview

The Yikes! router is a customized original equipment manufacturer product, which at implementation was a preproduction product. It is a self-contained router, Wi-Fi access point, and firewall that communicates locally with Wi-Fi devices and wired devices. The Yikes! router leveraged in this implementation was developed on an OpenWRT base router with the Yikes! capabilities added on. The Yikes! router hosts all the software necessary to enable a MUD infrastructure on premise. It also communicates with the Yikes! cloud and threat-signaling services to support additional capabilities in the network.

At this implementation, the Yikes! MUD manager, DHCP server, and GCA threat-signaling components all reside on the Yikes! router and are configured to function without any additional configuration.

3.4.2 Configuration Overview

3.4.2.1 Network Configuration

Implementation of a Yikes! router requires an internet source such as a Digital Subscriber Line (DSL) or cable modem.

3.4.2.2 Software Configuration

At this implementation, no additional software configuration was required to set up the Yikes! router.

3.4.2.3 Hardware Configuration

At this implementation, no additional hardware configuration was required to set up the Yikes! router.

3.4.3 Setup

As stated earlier, the version of the Yikes! router used in Build 2 was preproduction, so MasterPeace may have performed some setup and configuration steps that are not documented here. Those additional steps, however, are not expected to be required to set up the production version of the router. The following setup steps were performed:

  1. Unbox the Yikes! router and provided accessories.

  2. Connect the Yikes! router’s wide area network port to an internet source (e.g., cable modem or DSL).

  3. Plug the power supply into the Yikes! router.

  4. Power on the Yikes! router.

After powering on the router, the network password must be provided so the router can authenticate itself to the network. In addition, best security practices (not documented here), such as changing the router’s administrative password, should be followed in accordance with the security policies of the user.

3.5 DigiCert Certificates

DigiCert’s CertCentral web-based platform allows provisioning and management of publicly trusted X.509 certificates for a variety of purposes. After establishing an account, clients can log in, request, renew, and revoke certificates by using only a browser. For Build 2, the Premium Certificate created in Build 1 was leveraged for signing the MUD files. To request and implement DigiCert certificates, follow the documentation in Build 1’s DigiCert Certificates section and subsequent sections.

3.6 IoT Devices

3.6.1 IoT Development Kits—Linux Based

3.6.1.1 Configuration Overview

This section provides configuration details for the Linux-based IoT development kits used in the build, which emit MUD URLs by using DHCP. It also provides information regarding a basic IoT application used to test the MUD process.

3.6.1.1.1 Network Configuration

The devkits are connected to the network over both a wired Ethernet connection and wirelessly. The IP address is assigned dynamically by using DHCP.

3.6.1.1.2 Software Configuration

For this build, Raspberry Pi is configured on Raspbian 9, the Samsung ARTIK 520 is configured on Fedora 24, the NXP i.MX 8m is configured on Yocto Linux, and the BeagleBone Black is configured on Debian 9.5. The devkits also utilized a variety of DHCP clients, including dhcpcd and dhclient (see Build 1’s IoT Development Kits–Linux Based section for dhclient configurations). This build introduced dhcpcd as a method for emitting a MUD URL for all devkits in this build, apart from the NXP i.MX 8m, which leveraged dhclient. Dhcpcd is provided with many Linux distributions and can be installed using a preferred package manager if not currently present.

3.6.1.1.3 Hardware Configuration

The hardware used for these devkits included the Raspberry Pi 3 Model B, Samsung ARTIK 520, NXP i.MX 8m, and BeagleBone Black.

3.6.1.2 Setup

The following subsection describes setting up the devkits to send a MUD URL during the DHCP transaction using dhcpcd as the DHCP client on the Raspberry Pi. For dhclient instructions, see Build 1’s Setup and DHCP Client Configuration sections.

3.6.1.2.1 DHCP Client Configuration

These devkits utilized dhcpcd version 7.2.3. Configuration consisted of adding the following line to the file located at /etc/dhcpcd.conf:

mudurl https://<example-url>

A screenshot of the /etch/dhcpcd.conf file with the MUD URL configured per the instructions above.

3.7 Update Server

Build 2 leveraged the preexisting update server that is described in Build 1’s Update Server section. To implement a server that will act as an update server, see the documentation in Build 1’s Update Server section. The update server will attempt to access and be accessed by the IoT device, which, in this case, is one of the development kits we built in the lab.

3.8 Unapproved Server

Build 2 leverages the preexisting unapproved server that is described in Build 1’s Unapproved Server section. To implement a server that will act as an unapproved server, see the documentation in Build 1’s Unapproved Server section. The unapproved server will attempt to access and to be accessed by an IoT device, which, in this case, is one of the MUD-capable devices on the implementation network.

3.9 Yikes! IoT Device Discovery, Categorization, and Traffic Policy Enforcement (Yikes! Cloud and Yikes! Mobile Application)

This section describes how to implement and configure Yikes! IoT device discovery, categorization, and traffic policy enforcement, which is a capability supported by the Yikes! router, Yikes! cloud, and Yikes! mobile application.

3.9.1 Yikes! IoT Device Discovery, Categorization, and Traffic Policy Enforcement Overview

The Yikes! router provides an IoT device discovery service for Build 2. Yikes! discovers, inventories, profiles, and classifies devices connected to the local network consistent with each device’s type and allows traffic enforcement policies to be configured by the user through the Yikes! mobile application.

Yikes! isolates every device on the network so that, by default, no device is permitted to communicate with any other device. Devices added to the network are automatically identified and categorized based on information such as DHCP header, MAC address, operating system, manufacturer, and model.

Using the Yikes! mobile application, users can define fine-grained device filtering. The enforcement can be set to enable specific internet access (north/south) and internal network access to specific devices (east/west) as determined by category-specific rules.

3.9.2 Configuration Overview

3.9.2.1 Network Configuration

No network configurations outside Yikes! router network configurations are required to enable this capability.

3.9.2.2 Software Configuration

MasterPeace performed some software configuration on the Yikes! router after it was deployed as part of Build 2. Aside from this, no additional software configuration was required to support device discovery. When the production version of the Yikes! router is available, it is not expected to require configuration. The Yikes! mobile application was still in development during deployment. The build used the web-based Yikes! mobile application from a laptop in the lab environment to display and configure device information and traffic policies.

3.9.2.3 Hardware Configuration

At this implementation, the Yikes! mobile application was not published in an application store. For this reason, a desktop was leveraged to load the web page hosting the “mobile application.”

3.9.3 Setup

Once devices have been added to the network on the Yikes! router, they will appear in the Yikes! cloud inventory, which is accessible via the Yikes! mobile application. At this implementation, the Yikes! mobile application and the processes associated with the Yikes! cloud service were under development. It is possible that the design of the UI and the workflow will change for the final implementation of the mobile application.

3.9.3.1 Yikes! Router and Account Cloud Registration

At this implementation, the Yikes! router and cloud account registration processes were under development. As a result, this section will not describe how to associate a Yikes! router with a Yikes! cloud instance. The steps below show the process for account registration at this implementation.

  1. Open a browser and access the Yikes! UI. (Note: in the preproduction version of the router, accessing the UI required inputting a URL provided by MasterPeace.)

    Screenshot of the Yikes! app login page

  2. Click on the Register button to sign up for an account:

    Screenshot of the Yikes! app login page with the Register button highlighted

  3. Populate the requested information for the account: First Name, Last Name, Email, and Password. Click Sign Up:

    Screenshot of the Yikes! app account registration populated as described in instructions above with sign up button highlighted.

    Note: There will be additional steps related to associating the Yikes! router with the Yikes! account being created. However, at this implementation, this process was still under development.

  4. Once the account is approved and linked to the Yikes! router, Log in with the credentials created in step 3:

    Screenshot of the Yikes! app login page with username and password populated and login button highlighted.

  5. The home screen will show the network overview:

    Screenshot of the Yikes! Network page

3.9.3.2 Yikes! MUD-Capable IoT Device Discovery

This section details the Yikes! MUD-capable IoT device discovery capability. This feature is accessible through the Yikes! mobile application and identifies all MUD-capable IoT devices that are connected to the network.

  1. Open the menu pane in the UI:

    Screenshot of the Yikes! app Network page with the menu bar highlighted.

  2. Click the Devices button to open the devices menu:

    Screenshot of the Yikes! app Menu, with the "Devices" option highlighted

  3. Click the MUD tab to switch from the ALL device view to review the MUD-capable IoT devices connected to the network:

    Screenshot of the Yikes! app devices page, with the "MUD" tab at the top highlighted

  4. All MUD-capable devices on the network will have the MUD label as seen below:

    Screenshot of the Yikes! app devices page, with the MUD designation highlighted

3.9.3.3 Yikes! Alerts

This section details the Yikes! alerting capability. This feature is accessible through the Yikes! mobile application and notifies users when new devices have been connected to the network. Additionally, this feature alerts the user when new devices are not recognized as known devices and are placed in the uncategorized device category by the Yikes! cloud.

From the Yikes! mobile application, the user can edit the information about the device (e.g., name, make, and model) and modify the device’s category or can choose to ignore the alert by removing the notification.

  1. Open the menu pane in the UI:

    Screenshot of the Yikes! Network page with the menu bar highlighted

  2. Click Alerts to open the Alerts menu:

    Screenshot of the Yikes! app Menu, with the Alerts option highlighted

  3. Select a device to edit the device information and category by clicking Edit Device:

    Screenshot of the Yikes! app Alerts page, with the Edit Device button highlighted on an uncategorized device alert

  4. Modify the Category of the device by clicking the device’s current category:

    Screenshot of the Yikes! app new device window, with the Category option highlighted

  5. Select the desired category, in this case Smart Appliances, and click OK:

    Screenshot of the Yikes! app new device window, with the category set to Smart Appliances

  6. The device Category will update to reflect the new selection. Click Add Device to complete the process:

    Screenshot of the Yikes! app New Device window with the "Add Device" button highlighted

  7. The alerts menu will update and no longer include the device that was just modified and added:

    Screenshot of the Yikes! app Alerts page showing the device which was just configured has been removed from the Alerts page.

3.9.3.4 Yikes! Device Categories and Setting Rules

The Yikes! mobile application provides the capability to view predefined device categories and set rules for local communication between categories of devices on the local network and internet rules for all devices in a selected category.

  1. Click the menu bar to open the menu pane:

    Screenshot of the Yikes! app Network page with the menu bar highlighted.

  2. Click the Device Categories option to view all device categories:

    Screenshot of the Yikes! app Menu, with the Device Categories option highlighted

  3. Select the category of device to view and configure rules:

    Screenshot of the Yikes! App categories page showing the "Smart Appliances" category

  4. Modify local rules by clicking on the category of devices with which the selected category is permitted to communicate:

    Screenshot of the Yikes! app Smart Appliances category page, with the Cell Phones category pre-set to deny traffic

    Screenshot of the Yikes! app Smart Appliances category page, with the Cell Phones category changed to allow traffic once the button has been clicked.

  5. Scroll to the bottom of the page to view the current Internet Rules for this category, and change the permissions by clicking on IoT Specific Sites:

    Screenshot of the Yikes! app Smart Appliances category page, with the IoT Specific Sites button pre-set to deny specific traffic and allow all internet traffic for devices in this category.

    Screenshot of the Yikes! app Smart Appliances category page, with the IoT Specific Sites category set to allow only IoT specific traffic once the button is clicked.

Smart appliances should now be permitted to communicate locally to Smart Appliances, Home Assistants, Tablets, Cell Phones, and, externally, to IoT Specific Sites.

3.9.3.5 Yikes! Network Rules

  1. The Yikes! mobile application allows reviewing the rules that have been implemented on the network. These rules are divided into two main sections: Local Rules and Internet Rules. Local rules display the local communications permitted for each category of devices. Internet rules display the internet communications permitted for each category of devices. This section reviews the rules defined for Smart Appliances in Yikes! Device Categories and Setting Rules UI:

    Screenshot of the Yikes! app Network page with the menu bar highlighted.

  2. Click Network Rules to navigate to the rules menu:

    Screenshot of the Yikes! app menu, with the Network Rules section highlighted

  3. Click Local Rules to view the permitted local communications for each device category:

    Screenshot of the Yikes! app Network Rules page, with the Local Rules section highlighted

  4. Scroll down to view the local rules for the Smart Appliances category:

    Screenshot of the Yikes! app Network Rules page, with the Local Rules section expanded and the "Smart Appliances" category highlighted. Showing this category is allowed to communicate laterally with tablets, home assistants, smart appliances and cell phones.

  5. Minimize the rules by clicking the Local Rules button:

    Screenshot of the Yikes! app Network Rules page, with the Local Rules section expanded and highlighted

  6. Expand the rules that show internet rules for device categories by clicking Internet Rules:

    Screenshot of the Yikes! app Network Rules page, with the Internet Rules section highlighted and selected.

  7. Scroll down to view the internet rules for the Smart Appliances category:

    Screenshot of the Yikes! app Network Rules page, with the Internet Rules section expanded and the "Smart Appliances" category highlighted showing this category can only communicate with Manufacturer Specified Sites Only.

  8. Minimize the rules by clicking the Internet Rules button:

    Screenshot of the Yikes! app Network Rules page, with the Internet Rules section expanded and highlighted

3.10 GCA Quad9 Threat Signaling in Yikes! Router

This section describes the threat-signaling service provided by GCA in the Yikes! router. This capability should not require configuration because the Quad9 Active Threat Response (Q9Thrt) open-source software should be fully functional when the Yikes! router to connects to the network. Please see the Q9Thrt GitHub page for details on this software: https://github.com/osmud/q9thrt#q9thrt.

3.10.1 GCA Quad9 Threat Signaling in Yikes! Router Overview

The GCA Q9Thrt leverages DNS traffic by using Quad9 DNS services and threat intelligence from ThreatSTOP. As detailed in NIST SP 1800-15B, Q9Thrt is integrated into the Yikes! router and relies on the availability of three third-party services in the cloud: Quad9 DNS service, Quad9 threat API, and ThreatSTOP threat MUD file server. The Yikes! router is integrated with GCA Q9Thrt capabilities implemented, configured, and enabled out of the box.

3.10.2 Configuration Overview

At this implementation, no additional network, software, or hardware configuration was required to enable GCA Q9Thrt on the Yikes! router.

3.10.3 Setup

At this implementation, no additional setup was required to enable GCA Q9Thrt on the Yikes! router. See the Yikes! Router section for details on the router setup.

To take advantage of threat signaling, the Yikes! router uses the Quad9 DNS services for domain name resolution. GCA Quad threat signaling depends upon the Quad9 DNS services to be up and running. The Quad9 threat API must also be available to provide the Yikes! router with information regarding specific threats. In addition, for any given threat that is found, the MUD file server provided by the threat intelligence service that has flagged that threat as potentially dangerous must also be available. These are third-party services that GCA Q9Thrt relies upon to be set up, configured, and available.

It is possible to implement the Q9Thrt feature onto a non-Yikes! router. To integrate the Q9Thrt feature onto an existing router, see the open-source software on GitHub: https://github.com/osmud/q9thrt.

This software was designed for and has been integrated successfully using the OpenWRT platform but has the potential to be integrated into various networking environments. Instructions on how to deploy Q9thrt onto an existing router can be found on https://github.com/osmud/q9thrt#q9thrt.

4 Build 3 Product Installation Guides

This section of the practice guide contains detailed instructions for installing, configuring, and integrating the products used to implement Build 3. For additional details on Build 3’s logical and physical architectures, please refer to NIST SP 1800-15B.

4.1 Product Installation

4.1.1 DigiCert Certificates

DigiCert’s CertCentral web-based platform allows provisioning and management of publicly trusted X.509 certificates for a variety of purposes. After establishing an account, clients can log in, request, renew, and revoke certificates by using only a browser. For Build 3, the Premium Certificate created in Build 1 was leveraged for signing the MUD files. Additionally, this implementation leveraged a standard SSL certificate to secure the cloud servers. You will need to request standard SSL certificates for each of the servers in your implementation. For this build we requested standard SSL certificates for two servers—the MUD file server and the Micronets service provider cloud server. To request and implement DigiCert certificates, follow the documentation in Build 1’s DigiCert Certificates section and subsequent sections.

Once you have received the requested certificates, you can store these on the respective servers in your desired location. For this demonstration, we simply stored them in the workspace directory on the appropriate servers, but it is likely these would be stored in the /usr/lib or /etc/lib directories.

4.1.2 MUD Manager

This section describes the CableLabs MUD manager, which, for this implementation, is a cloud-provided service. This implementation leveraged the nccoe-build-3 branch of CableLabs MUD manager Git release. This service can be hosted by the implementer or another party. This documentation describes setting up your own MUD manager.

4.1.2.1 MUD Manager Overview

The CableLabs MUD manager is used by the Micronets Manager as a utility service to retrieve MUD files from a passed URL, parse the MUD file, and produce device communication restriction declarations that can be passed to the associated Micronets Gateway Service.

This Micronets MUD manager is hosted in the service provider cloud and for this implementation is on the same server as the other Micronets services. The MUD manager is responsible for retrieving MUD files and their associated signature files and executing verification as outlined in the MUD specification. It generates the ACLs for the device based on the MUD file and provides this information to the Micronets Manager.

4.1.2.2 Configuration Overview

The following subsections document the software and network configurations for the MUD manager. Please note that the MUD manager, Micronets Manager, Websocket Proxy, MUD registry, and MSO portal are all implemented on the same server, nccoe-server1.micronets.net.

4.1.2.2.1 Network Configuration

The nccoe-server1.micronets.net server was hosted outside the lab environment on a Linode cloud-hosted Linux server. Its IP address was statically assigned.

4.1.2.2.2 Software Configuration

For this build, the server ran on an Ubuntu 18.04 LTS operating system. The MUD manager runs in its own docker container and is configured to use SSL/TLS encryption.

The following software is required to install, configure, and operate the MUD manager:

  • an Ubuntu 18.04 LTS server reachable by the server hosting the Micronets Manager instances and any Micronets gateways

  • docker (v18.06 or higher)

  • curl

  • NGINX

4.1.2.2.3 Hardware Configuration

The following hardware is required to install, configure, and operate the MUD manager:

  • 4 gigabyte (GB) of RAM

  • 50 GB of free disk space

4.1.2.3 Setup

The subsequent sections describe installing, configuring, and confirming general operation for the MUD manager.

4.1.2.3.1 Install and Set Up Dependencies
  1. Make directory for downloading micronets-related scripts and packages:

    mkdir Projects/micronets/

  2. Install docker, curl, and NGINX by entering the following command:

    sudo apt install docker curl nginx

  3. Create an NGINX config file for this server. (Note: If you are following the architecture for this implementation, all Micronets cloud components will be hosted on this server, and this will be the same config file that will be modified to add routes to the different Micronets services.)

    sudo vim /etc/nginx/sites-available/<ServerURL>

    sudo vim /etc/nginx/sites-available/nccoe-server1.micronets.net

  4. Add the following configuration block to the file and add the path to the certificate and key file received from your DigiCert standard SSL. (Note: additional locations will be added to this configuration block as you continue to set up the different Micronets services.)

    server {
    
       listen 443 ssl;
       listen [::]:443 ssl;
    
       root /var/www/html;
    
       index index.html index.htm index.nginx-debian.html;
    
       server_name nccoe-server1.micronets.net;
    
       location / {
    
          try_files $uri $uri/ =404;
    
       }
    
       ssl_certificate /home/micronets-dev/Projects/micronets/cert/nccoe-server1_micronets_net.crt;
    
       ssl_certificate_key /home/micronets-dev/Projects/micronets/cert/nccoe-server1_micronets_net.key;
    
    }
    
  5. Enable the file by creating a link from it to the sites-enabled directory, which NGINX reads from during start-up:

    sudo ln -s /etc/nginx/sites-available/nccoe-server1.micronets.net /etc/nginx/sites-enabled/nccoe-server1.micronets.net
    
  6. Next, test to make sure that there are no syntax errors in the NGINX files:

    sudo nginx -t

    You should see output similar to the following:

    This image shows the expected output for the command "sudo nginx -t" being run on the MUD Manager.

  7. If there are no problems, restart NGINX to enable your changes:

    sudo systemctl restart nginx

4.1.2.3.2 Installing MUD Manager
  1. Change directory to the Projects/micronets/ folder:

    cd Projects/micronets/

  2. Download the management script by executing the following command:

    curl -O https://raw.githubusercontent.com/cablelabs/micronets-mud-tools/nccoe-build-3/bin/micronets-mud-manager
    
  3. Install and execute the management script:

    sudo install -v -o root -m 755 -D -t /etc/micronets/micronets-mud-manager.d/ micronets-mud-manager
    

    You should see output similar to the following:

    This image shows the expected output of the command "sudo install -v -o root -m 755 -D -t /etc/micronets/micronets-mud-manager.d/ mi-cronets-mud-manager" being run on the MUD Manager.

  4. Open the management script to configure it for your implementation by entering the following command:

    sudo vim /etc/micronets/micronets-mud-manager.d/micronets-mud-manager

  5. Once the file is opened, modify the default variables in the management script to point to the server hosting our Micronets manager by changing the DEF_CONTROLLER_ADDRESS variable:

    DEF_CONTROLLER_ADDRESS=nccoe-server1.micronets.net

    This image shows the contents of the file "/etc/micronets/micronets-mud-manager.d/micronets-mud-manager" on the MUD Manager, after the DEF_CONTROLLER_ADDRESS value has been changed.

  6. Download the docker image by entering the following command:

    /etc/micronets/micronets-mud-manager.d/micronets-mud-manager docker-pull

    You should see output similar to the following:

    This image shows the expected output for the command "/etc/micronets/micronets-mud-manager.d/micronets-mud-manager docker-pull" being run on the MUD Manager.

  7. Next, set up the MUD cache directory by using the management script and entering the following command:

    sudo /etc/micronets/micronets-mud-manager.d/micronets-mud-manager setup-cache-dir

  8. Last, start the MUD manager by entering the following command to run the docker container:

    /etc/micronets/micronets-mud-manager.d/micronets-mud-manager docker-run

    You should see output similar to the following:

    This image shows the expected output for the command "/etc/micronets/micronets-mud-manager.d/micronets-mud-manager docker-run" being run on the MUD Manager.

  9. Verify that the MUD manager is running by using the following command and reviewing the logs:

    /etc/micronets/micronets-mud-manager.d/micronets-mud-manager docker-logs

    You should see output similar to the following:

    This image shows the expected output for the command "/etc/micronets/micronets-mud-manager.d/micronets-mud-manager docker-logs" being run on the MUD Manager.

  10. Set up a proxy pass to the MUD manager by adding the following entry to the NGINX server block:

    1. Open the NGINX sites-available file for the server:

      sudo vim /etc/nginx/sites-available/nccoe-server1.micronets.net

    2. Add the following location to the server block:

      location /micronets/mud-manager/ {
      
         proxy_pass http://localhost:8888/;
      
      }
      

      This image shows the file "/etc/nginx/sites-available/nccoe-server1.micronets.net" on the MUD Manager after the location listed above has been added.

  11. Reload the NGINX server by executing the following command:

    sudo nginx -s reload

4.1.2.3.3 Operation

In this section, we test general operation of the MUD manager.

  1. Test the MUD manager by retrieving a MUD file and using the following command (replace the MUD manager URL with the URL you created in Section 4.1.2.3.1):

    curl -q -X POST -H "Content-Type: application/json" \
    https://nccoe-server1.micronets.net/micronets/mud-manager/getMudFile \
    -d '{"url": "https://alpineseniorcare.com/micronets-mud/ciscopi.json"}'
    

    You should see the MUD file requested printed in the terminal:

    image125

  2. Check the MUD file cache directory to confirm that the MUD file requested is stored in the cache:

    ls -1 /var/cache/micronets-mud/

    You should see the MUD file you just requested stored in the cache directory:

    This image shows the expected output for the command "ls -1 /var/cache/micronets-mud/" being run on the MUD Manager.

  3. Now that the MUD manager has successfully retrieved its first MUD file, you can clear the cache by entering the following command:

    /etc/micronets/micronets-mud-manager.d/micronets-mud-manager clear-cache-dir

    You should see the following output once the command above has been executed:

    This image shows the expected output of the command "/etc/micronets/micronets-mud-manager.d/micronets-mud-manager clear-cache-dir" being run on the MUD Manager.

  4. To output a list of additional docker commands supported by the management script, you can execute the following command:

    /etc/micronets/micronets-mud-manager.d/micronets-mud-manager ––

    You should see output similar to the following:

    This image shows the expected output of the command "/etc/micronets/micronets-mud-manager.d/micronets-mud-manager –" being run on the MUD Manager.

4.1.3 MUD File Server

This section describes the CableLabs MUD file server, which is a cloud-hosted service. The Build 3 implementation is designed a bit differently from the other three builds insofar as it requires a MUD registry to be incorporated in the solution as described in Volume B. We describe the MUD registry in this section of the documentation.

4.1.3.1 MUD File Server Overview

In the absence of a commercial MUD file server for use in this project, the NCCoE leveraged a Linode cloud-hosted Linux server to create the MUD file server that is accessible via the internet. This file server stores the MUD files along with their corresponding signature files for the IoT devices used in the project. Upon receiving a GET request for the MUD files and signatures, it serves the request to the MUD manager by using https.

4.1.3.2 Configuration Overview

The following subsections document the software and network configurations for the MUD file server.

4.1.3.2.1 Network Configuration

This server was hosted outside the lab environment on a Linode cloud-hosted Linux server. Its IP address was statically assigned.

4.1.3.2.2 Software Configuration

For this build, the server ran on an Ubuntu 18.04 LTS operating system. The MUD files and signatures were hosted by an NGINX web server and configured to use SSL/TLS encryption.

4.1.3.2.3 Hardware Configuration

The following hardware is required to install, configure, and operate the MUD file server:

  • 4 GB of RAM

  • 50 GB of free disk space

4.1.3.3 Setup

4.1.3.3.1 NGINX Web Server
  1. Update your local package index by entering the following command:

    sudo apt update

  2. Install NGINX by entering the following command:

    sudo apt install nginx

  3. Create the directory where the MUD files will be stored on the MUD file server as follows:

    sudo mkdir -p /var/www/nccoe-server2.micronets.net/html/micronets-mud/

  4. Create an NGINX config file for this server. (Note: If you are following the architecture for this implementation, all Micronets cloud components will be hosted on this server, and this will be the same config file that will be modified to add routes to the different Micronets services.)

    sudo vim /etc/nginx/sites-available/<ServerURL>

    Below is an example of this command:

    sudo vim /etc/nginx/sites-available/nccoe-server2.micronets.net

  5. Add the following configuration block to the file. (Note: additional locations will be added to this configuration block as you continue to set up the different Micronets services.)

    server {
        listen 443 ssl;
        listen [::]:443 ssl;
        root /var/www/nccoe-server2.micronets.net/html;
        index index.html index.htm index.nginx-debian.html;
        server_name nccoe-serve2.micronets.net;
        location / {
            # First attempt to serve request as file, then
            # as directory, then fall back to displaying a 404.
            try_files $uri $uri/ =404;
        }
        if ($scheme != "https") {
            return 301 https://$host$request_uri;
        }
        ssl_certificate /home/micronets-dev/Projects/micronets/cert/nccoe-server2_micronets_net.crt;
        ssl_certificate_key /home/micronets-dev/Projects/micronets/cert/nccoe-server2_micronets_net.key;
        include /etc/nginx/micronets-subscriber-forwards/*.conf;
    }
    
  6. Enable the file by creating a link from it to the sites-enabled directory, which NGINX reads from during startup:

    sudo ln -s /etc/nginx/sites-available/nccoe-server2.micronets.net \
    /etc/nginx/sites-enabled/nccoe-server2.micronets.net
    
  7. Next, test to make sure that there are no syntax errors in any of your NGINX files:

    sudo nginx -t

    You should see output similar to the following:

    This image shows the expected output of the command "sudo nginx -t" being run on the MUD File Server.

  8. If there are no problems, restart NGINX to enable your changes:

    sudo systemctl restart nginx

4.1.3.3.2 MUD File Creation and Signing

To create MUD files for MUD-capable IoT devices, please follow the instructions in Build 1’s MUD File Serversection. Once MUD files and signature files are created, they can be stored in the web server directory created on the MUD file server in the previous section.

4.1.4 Micronets Gateway

This section describes the CableLabs Micronets Gateway, which, for this implementation, is an on-premises component. This implementation leveraged the nccoe-build-3 tagged version of CableLabs Micronets Gateway Git release. This documentation describes setting up your own Micronets gateway.

4.1.4.1 Micronets Gateway Overview

The Micronets Gateway establishes a connection to the Micronets Manager through the Websocket Proxy and receives traffic flow rules and other configuration information that it applies and enforces. Additionally, the Micronets Gateway supports wired and wireless connections, MUD-defined ACLs, and DPP onboarding.

4.1.4.2 Configuration Overview

The following subsections document the software and network configurations for the Micronets Gateway.

4.1.4.2.1 Network Configuration

Implementation of a Micronets gateway requires an internet source such as a digital subscriber line (DSL) or cable modem.

4.1.4.2.2 Software Configuration

The Micronets Gateway runs an Ubuntu 16.04 LTS server, which can support all the software dependencies and packages that will be installed during setup.

4.1.4.2.3 Hardware Configuration

For this implementation, we leveraged a Shuttle XPC slim DH170 with the following specs:

  • x86_64 processor (Intel or AMD)

  • at least two Ethernet ports

  • wireless adapter with a QUALCOMM Atheros AR9271 chipset

  • 2 GB or higher of RAM

4.1.4.3 Setup

4.1.4.3.1 Install Dependencies
  1. If Micronets is already installed and running, you should stop the services first by executing the following commands:

    sudo systemctl stop micronets-gw.service
    
    sudo systemctl stop micronets-hostapd.service
    
  2. Update your local package index by entering the following command:

    sudo apt-get update

    You should see the following output from this command:

    This image shows the expected output from the command "sudo apt-get update" being run on the Micronets Gateway.

  3. Install the python-pip, virtualenv, dnsmasq, python-six, and libnl-route-3-200 packages by executing the following command:

    sudo apt-get -y install python-pip virtualenv dnsmasq python-six libnl-route-3-200

    If the packages are not already installed, you should see the following output from this command:

    This image shows the expected output from the command "sudo apt-get -y install python-pip virtualenv dnsmasq python-six libnl-route-3-200" being run on the Micronets Gateway.

  4. Install openvswitch version 2.9.2 and its dependencies from the CableLabs micronets-gw github repository by executing the following for loop:

    for package in libopenvswitch_2.9.2-1_amd64.deb \
    
          openvswitch-common_2.9.2-1_amd64.deb \
    
          openvswitch-switch_2.9.2-1_amd64.deb ;
    
    do curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.55/${package};
    
    sudo dpkg -i ${package};
    
    done
    

    You should see the following output from this command:

    This image shows the expected output of the above command being run on the Micronets Gateway.

  5. Install Python version 3.6 and its dependencies from the CableLabs micronets-gw github repository by executing the following for loop:

    for package in libpython3.6-minimal_3.6.5-5.16.04.york1_amd64.deb \
    
          libpython3.6-stdlib_3.6.5-5.16.04.york1_amd64.deb \
    
          python3.6-minimal_3.6.5-5.16.04.york1_amd64.deb \
    
          python3.6_3.6.5-5.16.04.york1_amd64.deb ;
    
    do curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.55/${package};
    

    You should see the following output from this command:

    This image shows the expected output of the above command being run on the Micronets Gateway.

4.1.4.3.2 Install Micronets Packages
  1. Enter the following command to download the Micronets hostapd package:

    curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.55/micronets-hostapd-1.0.21.deb
    

    You should see output similar to the following:

    This image shows the output of the command "curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.55/micronets-hostapd-1.0.21.deb" being run on the Micronets Gateway.

  2. Enter the following command to de-package the Micronets hostapd package:

    sudo dpkg -i micronets-hostapd-1.0.21.deb

    You should see output similar to the following:

    This image shows the expected output of the command "sudo dpkg -i micronets-hostapd-1.0.21.deb " being run on the Micronets Gateway.

  3. Enter the following command to download the Micronets Gateway package:

    curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.55/micronets-gw-1.0.55.deb
    

    You should see output similar to the following:

    This image shows the expected output of the command "curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.55/micronets-gw-1.0.55.deb" being run on the Micronets Gateway.

  4. Enter the following command to install the Micronets hostapd package:

    sudo dpkg -i micronets-gw-1.0.55.deb

    After a bit of a delay, you should see output similar to the following:

    This image shows the expected output of the command "sudo dpkg -i micronets-gw-1.0.55.deb" being run on the Micronets Gateway.

  5. Enable autostart for the Micronets hostapd service by entering the following command:

    sudo systemctl enable micronets-hostapd.service

  6. Enable autostart for the Micronets Gateway Service by entering the following command:

    sudo systemctl enable micronets-gw.service

  7. Start the Micronets hostapd service by entering the following command:

    sudo systemctl start micronets-hostapd.service

  8. Start the Micronets Gateway Service by entering the following command:

    sudo systemctl start micronets-gw.service

  9. Verify that the gateway service started successfully by running the following command:

    sudo systemctl status micronets-gw.service

  10. Verify that the Micronets hostapd service started successfully by running the following command:

    sudo systemctl status micronets-hostapd.service

CableLabs documentation notes that installing the micronets-gw package should produce the following results:

  • installation of the Micronets Gateway Service in the /opt/micronets-gw directory

  • installation of the ifup/down and dnsmasq extension scripts for configuration of openvswitch and the micronets-gw service via /etc/network/interfaces

  • installation of a sample/etc/network/interfaces file in /opt/micronets-gw/doc/interfaces.sample

  • installation and start of the micronets-gw-service systemd service

4.1.5 IoT Devices

This section provides configuration details for the Linux-based IoT development kits used in the build, which can be onboarded via DPP. It also provides information regarding a basic IoT application used to test the MUD process.

4.1.5.1 IoT Devices Overview

Build 3, like the other builds in this project, leverages the Raspberry Pi devkit with capabilities developed to make these devices both MUD- and DPP-capable. The Raspberry Pi runs the Raspbian 9 OS and is provisioned with one bootstrapping public/private key pair during device setup. The Micronets Proto-Pi software developed by CableLabs in combination with the added hardware outlined in the configuration section adds DPP capability to these devices. There are two onboarding mechanisms called modes supported by the Micronets Proto-Pi software: DPP mode and clinic mode. The clinic mode provides an onboarding mechanism via automated installation of Wi-Fi security certificates, and the DPP mode provides QR code–based device onboarding. For this implementation, we only describe setting up and leveraging the Micronets Proto-Pi software in DPP mode. If you would like to leverage the clinic mode of this software, follow the documentation provided by CableLabs: https://github.com/cablelabs/micronets-pi3/blob/nccoe-build-3/README.md#Installation.

4.1.5.2 Configuration Overview

The following subsections document the software and network configurations for the Micronets Proto-Pi device.

4.1.5.2.1 Network Configuration

The following network configurations are required to install, configure, and operate the Micronets Proto-Pi device:

  • wired network connection to a separate access point that provides both initial internet access to self-register the device and remote management access to the device during setup

4.1.5.2.2 Software Configuration

The following software is required to install, configure, and operate the Micronets Proto-Pi device:

4.1.5.2.3 Hardware Configuration

The following hardware is required to install, configure, and operate the Micronets Proto-Pi device:

  • Raspberry Pi (version 3B+)

  • SD card

  • Alfa adapter

  • Ethernet cable

4.1.5.3 Setup

4.1.5.3.1 Install Dependencies
  1. Connect the SD card to your computer.

  2. Open balenaEtcher (or whatever tool you have downloaded for flashing SD cards).

  3. Click Select image, and select the Raspbian image you downloaded:

    This image shows the "Select image" button in BalenaEtcher.

    This image shows a .ZIP file being selected.

  4. Click Select target, and select the SD card you connected to the computer (the software may automatically recognize the target):

    This image shows the "Select target" button in BalenaEtcher.

    You should see something similar to the following:

    This image shows BalenaEtcher after a target has been selected.

  5. Click Flash! to start the flashing process:

    This image shows the "Flash!" button in BalenaEtcher.

    You may be prompted to enter your password, as seen below:

    This image shows an example of a password prompt in BalenaEtcher.

    When the flashing has completed, you should see output similar to the following:

    This image shows the "Flash Complete!" screen in BalenaEtcher.

4.1.5.3.2 Install Micronets Proto-Pi
  1. Insert the SD card to the Raspberry Pi, and connect power using a micro–Universal Serial Bus (USB) cable.

  2. Connect to the Raspberry Pi from a remote machine by using SSH:

    Note: You will need to figure out the Ethernet IP address of the Raspberry Pi, which can be done by looking at the DHCP assignments on the gateway to which you connected the Raspberry Pi.

    1. Enter the following command once you have identified the device’s IP address:

      ssh pi@[ipaddress]

      image144

    2. You will be prompted to continue connecting, as this is the first time connecting to the device:

      image145

    3. Enter the password for the Raspberry Pi:

      Note: The password is “micronets” if you are leveraging the CableLabs Raspberry Pi image:

      image146

    4. You will now have access to a terminal on the Raspberry Pi:

      This image shows the expected result after the command "ssh pi@[ipaddress]" has been used to connect to the Raspberry Pi.

  3. Ensure that you are in the home directory by entering the following command:

    cd ~

  4. Download the Micronets Proto-Pi software from GitHub by entering the following command:

    git clone https://git@github.com/cablelabs/micronets-pi3.git

    You should see output similar to the following:

    This image shows the expected output of the command "git clone https://git@github.com/cablelabs/micronets-pi3.git" being run on the Raspberry Pi.

  5. Change into the micronets-pi3 directory by entering the following command:

    cd micronets-pi3/

  6. Check out the nccoe-build-3 branch by entering the following branch:

    git checkout nccoe-build-3

    You should see output similar to the following:

    This image shows the expected output of the command "git checkout nccoe-build-3" being run on the Raspberry Pi.

  7. Change into the deploy directory by entering the following command:

    cd deploy/

  8. Install the Micronets Proto-Pi software by entering the following command:

    ./install

    When prompted to accept disk space required, input Y as seen below:

    image150

    image151image152image153

4.1.5.3.3 Operation

Four buttons are used for general operation in the Micronets Proto-Pi application. These buttons are on the right side of the application and will be described in the upcoming sections.

  1. Accessing Raspberry Pi Using Virtual Network Computing (VNC )Viewer:

    1. Access the Raspberry Pi using the VNC Viewer, enter the IP address of the Raspberry Pi, and click Connect:

      image154

      You will be prompted to accept and store the signature for this device as it is the first time connecting to it. Click OK:

      image155

      Once accepted, proceed to log in with the username and password, as seen below:

      image156

    2. You should see the Micronets Proto-Pi application on the screen as seen below:

      This image shows the Micronets Proto-Pi app being used on the Raspberry Pi.

  2. The onboard button described in the following steps allows the user to initiate the onboard operation:

    1. Click the green button to initiate the onboard process:

      This image shows the Micronets Proto-Pi app being used on the Raspberry Pi. The green button with a plus sign is highlighted to initiate the onboarding process.

      A QR code will appear as seen below. The mobile application will be used to scan this QR code for onboarding:

      This image shows the QR code in the Micronets Proto-Pi app being used on the Raspberry Pi.

  3. The cycle button described in the following steps turns the Wi-Fi off/on to reconnect to the configured service set identifier (SSID).

    1. Click the orange cycle button:

      This image shows the orange cycle button in the Micronets Proto-Pi app being used on the Raspberry Pi.

      You should see output similar to the following:

      This image shows the expected output after pressing the orange cycle button in the Micronets Proto-Pi app being used on the Raspberry Pi.

  4. The settings button described in the following steps will open the settings menu, which has four different operations/buttons:

    1. Click the gear button:

      This image shows the settings button in the Micronets Proto-Pi app being used on the Raspberry Pi.

      The following menu will appear:

      This image shows the expected output after pressing the settings button in the Micronets Proto-Pi app being used on the Raspberry Pi.

    2. Click the Mode button to change the onboarding mode from DPP to clinic, and vice versa:

      This image shows the mode button from the Settings menu in the Micronets Proto-Pi app being used on the Raspberry Pi.

      The following screen displays:

      This image shows the expected output from the mode button from the Settings menu in the Micronets Proto-Pi app being used on the Raspberry Pi.

    3. Click the Mode button again to return to DPP mode:

      This image shows the mode button from the Settings menu in the Micronets Proto-Pi app being used on the Raspberry Pi.

      You will see the following change to your screen:

      This image shows the result of clicking the mode button again. The device is now in DPP mode.

    4. Click the Reset button to clear Wi-Fi credentials. (Note: If the device is in clinic mode, it will restore the credentials for the clinic Wi-Fi.)

      This image shows the reset button from the Settings menu in the Micronets Proto-Pi app being used on the Raspberry Pi.

      You should see output similar to the following:

      This image shows the result of clicking the reset button. The device outputs "Clearing Wifi Credentials..."

    5. Click the Reboot button to reboot the Pi:

      This image shows the reboot button from the Settings menu in the Micronets Proto-Pi app being used on the Raspberry Pi.

      You should see output similar to the following:

      This image shows the result of clicking the reboot button. The main screen shows "Rebooting Device...".

    6. Click the Done button to exit the settings screen:

      This image shows the done button from the Settings menu in the Micronets Proto-Pi app being used on the Raspberry Pi.

      You should see output similar to the following:

      This image shows the result of the done button being clicked. The screen has returned to the main application screen.

  5. The power button described in the following steps appears on the main screen of the Micronets Proto-Pi application and is used to restart the application as well as shut down the Pi entirely:

    1. Tap the power button to restart the application:

      This image shows the power button from the main screen on the Micronets Proto-Pi app being used on the Raspberry Pi.

      You should see output similar to the following:

      This image shows the result of the power button being clicked. The main screen outputs "Restarting Appliction...".

      Next, the following screen should appear:

      This image shows the next screen displayed after restarting the application. The screen shows the micronets icon and the IP address of the device.

      Finally, the main screen appears as seen below:

      This image shows the final step in the appliction restart. The main screen of the application is now showing.

    2. Hold the power button to shut down the Pi:

      This image shows the power button which is to be held down to shutdown the Pi.

      You should see output similar to the following:

      This image shows the result of holding down the power button. The screen displays "Shutting Down.."

4.1.6 Update Server

Build 3 leverages the preexisting update server that is described in Build 1’s Update Server section. To implement a server that will act as an update server, see the documentation in Build 1’s Update Server section. The update server will attempt to access and be accessed by the IoT device, which, in this case, is one of the development kits we built in the lab.

4.1.7 Unapproved Server

Build 3 leverages the preexisting unapproved server that is described in Build 1’s Unapproved Server section. To implement a server that will act as an unapproved server, see the documentation in Build 1’s Unapproved Server section. The unapproved server will attempt to access and be accessed by an IoT device, which, in this case, is one of the MUD-capable devices on the implementation network.

4.1.8 CableLabs MUD Registry

This section describes the CableLabs MUD registry, which, for this implementation, is a cloud-provided service. This implementation leveraged the nccoe-build-3 branch of CableLabs MUD registry Git release. This service can be hosted by the implementer or another party. This documentation describes setting up your own MUD registry.

4.1.8.1 CableLabs MUD Registry Overview

The Micronets MUD registry provides the capability to look up the MUD URL that is associated with a particular device. This registration and MUD URL association can be done manually or by the device using self-registration.

4.1.8.2 Configuration Overview

The following subsections document the software and network configurations for the MUD registry. Please note that the MUD manager, Micronets Manager, Websocket Proxy, MUD registry, and MSO portal are all implemented on the same server, nccoe-server1.micronets.net. Many of these configurations have already been covered in previous sections of this document but are repeated here for consistency.

4.1.8.2.1 Network Configuration

This server was hosted outside the lab environment on a Linode cloud-hosted Linux server. Its IP address was statically assigned.

4.1.8.2.2 Software Configuration

For this build, the server ran on an Ubuntu 18.04 LTS operating system. The MUD registry runs in its own docker container and is configured to use SSL/TLS encryption.

The following software is required to install, configure, and operate the MUD registry:

  • an Ubuntu 18.04 LTS server reachable by the server hosting the Micronets Manager instances and any Micronets gateways

  • docker (v18.06 or higher)

  • curl

  • NGINX

4.1.8.2.3 Hardware Configuration

The following hardware is required to install, configure, and operate the MUD registry:

  • 4 GB of RAM

  • 50 GB of free disk space

4.1.8.3 Setup

4.1.8.3.1 Install and Configure MUD Registry
  1. Log in to docker by using the following command:

    docker login

    You should see output similar to the following:

    This image shows the expected output of the above command being run on the MUD Registry.

  2. Retrieve the nccoe-build-3 tagged image by entering the following command:

    docker pull community.cablelabs.com:4567/micronets-docker/micronets-mud-registry:nccoe-build-3
    
  3. Execute the following command to run the image that was just retrieved:

    The command will follow the syntax below. Replace <MUDFILESERVER_URL> with your MUD file server URL:

    docker run -d -p 127.0.0.1:3082:3082 –env mud_base_uri=https:// <MUDFILESERVER_URL> -v /etc/micronets/micronets-mud-registry.d/:/etc/micronets/config–name=micronets-mud-registry community.cablelabs.com:4567/micronets-docker/micronets-mud-registry:nccoe-build-3

    docker run -d -p 127.0.0.1:3082:3082 --env mud_base_uri=https://nccoe-server2.micronets.net/micronets-mud -v
    /etc/micronets/micronets-mud-registry.d/:/etc/micronets/config --name=micronets-mud-registry
    community.cablelabs.com:4567/micronets-docker/micronets-mud-registry:nccoe-build-3
    
  4. Configure your own vendor code for your implementation by completing the following steps:

    1. Create and modify the mud-registry.conf file by executing the following command. (Note: The configuration file must be named “mud-registry.conf” and must reside in a host folder that is passed to the docker instance in the docker run command executed in the previous step.)

      sudo vim /etc/micronets/micronets-mud-registry.d/mud-registry.conf

    2. Replace <VENDOR-CODE> with your choice of vendor name, <MUDREGISTRY_URL> with the MUD registry URL, and <MUDFILESERVER_URL> with the MUD file server URL:

      {
      “vendors” : {
      <VENDOR-CODE> “: “https:// <MUDREGISTRY_URL> /registry/devices”, “ABCD”: “https://abcd-domain.com:3082/vendors”
      }, “mud_base_uri”: “https:// <MUDFILESERVER_URL> /micronets-mud”, “device_db_file”: “/etc/micronets/config/device-registration.nedb”
      }

      For this implementation, we added the following:

      {
         "vendors" : {
            "TEST": "https://nccoe-server1.micronets.net/registry/devices",
           "ABCD": "https://abcd-domain.com:3082/vendors"
         },
         "mud_base_uri": "https://nccoe-server2.micronets.net/micronets-mud",
         "device_db_file": "/etc/micronets/config/device-registration.nedb"
      }
      

      This image shows the contents of the "/etc/micronets/micronets-mud-registry.d/mud-registry.conf" on the MUD Registry.

    3. Modify the sites-available file for the NGINX server to route appropriate traffic to the docker container by executing the following commands:

      1. Open the sites-available file for the NGINX server by entering the following command:

        sudo vim /etc/nginx/sites-available/nccoe-server1.micronets.net

      2. Map the location for the /registry/devices so it is routed to vendors/ in the docker instance running on port 3082 and for the /mud/ to be passed to the global registry by adding the following to the server block:

        location /registry/devices {
            proxy_pass http://localhost:3082/vendors/;
        }
        location /mud/{
            proxy_pass http://localhost:3082/registry/;
        }
        

        This image shows the contents of the "/etc/nginx/sites-available/nccoe-server1.micronets.net" on the MUD Registry.

4.1.9 CableLabs Micronets Manager for SDN Control

This section describes the CableLabs Micronets Manager, which, for this implementation, is a cloud-provided service. This implementation leveraged the nccoe-build-3 branch of CableLabs Micronets Manager Git release. This service can be hosted by the implementer or another party. This documentation describes setting up your own Micronets Manager.

4.1.9.1 CableLabs Micronets Manager Overview

The Micronets Manager provides micro-services to the implementation. It receives onboarding requests, bootstrapping information, and more for a particular subscriber and is a core component for handing off requests among different components in the architecture.

4.1.9.2 Configuration Overview

The following subsections document the software and network configurations for the Micronets Manager. Please note that these instructions have the MUD manager, Micronets Manager, Websocket Proxy, MUD registry, and MSO portal all deployed onto the same server, nccoe-server1.micronets.net. Many of these configurations are already covered in previous sections of this document but are repeated here for consistency.

4.1.9.2.1 Network Configuration

This server was hosted outside the lab environment on a Linode cloud-hosted Linux server. Its IP address was statically assigned.

4.1.9.2.2 Software Configuration

For this build, the server ran on an Ubuntu 18.04 LTS operating system. The Micronets Manager runs in its own docker container and is configured to use SSL/TLS encryption.

The following software is required to install, configure, and operate the Micronets Manager:

  • an Ubuntu 18.04 LTS server reachable by any Micronets gateways

  • docker (v18.06 or higher)

  • docker-compose (v1.23.1 or higher)

  • OpenSSL (1.0.2g or higher)

  • curl

  • NGINX (1.14.0 or higher)

4.1.9.2.3 Hardware Configuration

The following hardware is required to install, configure, and operate the Micronets Manager:

  • 4 GB of RAM

  • 50 GB of free disk space

4.1.9.3 Setup

4.1.9.3.1 Install Dependencies
  1. Install docker, docker-compose, openssl, curl, and NGINX by entering the following command:

    sudo apt-get install docker docker-compose openssl curl nginx

4.1.9.3.2 Install and Configure the Micronets Manager
  1. Ensure the version of docker-compose is correct and upgrade if needed:

    1. Check the current version by entering the following command:

      docker-compose ––version

      You should see the version output as seen below:

      image41932-1

    2. If the version is earlier than v1.23.1, run the following command to install a new version in /usr/local/bin directory:

      1. Download the docker-compose utility:

        curl -s -L -O https://github.com/docker/compose/releases/download/1.24.1/docker-compose-Linux-`uname -m\`
        
      2. Install the docker-compose utility to the appropriate directory:

        sudo install -v -o root -m 755 docker-compose-Linux-`uname -m\` /usr/local/bin/docker-compose
        

        You should see output similar to the following:

        image41932-2

  2. Download the Micronets Manager management script, and install it by entering the following commands:

    1. Download the Micronets Manager management script:

      curl -s -O https://raw.githubusercontent.com/cablelabs/micronets-manager/nccoe-build-3/scripts/mm-container
      
    2. Download the docker-compose utility:

      curl -s -O https://raw.githubusercontent.com/cablelabs/micronets-manager/nccoe-build-3/scripts/docker-compose.yml
      
    3. Install the management script to the appropriate location:

      sudo install -v -o root -m 755 -D -t /etc/micronets/micronets-manager.d mm-container
      

      You should see output similar to the following:

      image182

    4. Install the docker-compose utility to the appropriate location:

      sudo install -v -o root -m 644 -D -t /etc/micronets/micronets-manager.d docker-compose.yml
      

      You should see output similar to the following:

      image183

  3. Copy the Micronets Manager server cert/key and the Websocket Proxy root CA cert created in earlier steps for use by the Micronets Manager docker container(s):

    1. Install the certificates and keys by entering the following command:

      sudo install -v -o root -m 600 -D -t /etc/micronets/micronets-manager.d/lib micronets-manager.{cert,key}.pem micronets-ws-root.cert.pem
      

      You should see output similar to the following:

      image184

    2. Create a placeholder micronets-ws-proxy.pkeycert.pem file. This file is not used, but the Micronets Manager currently checks for it:

      sudo touch /etc/micronets/micronets-manager.d/lib/micronets-ws-proxy.pkeycert.pem

  4. Copy the shared secret value generated during the MSO portal installation:

    sudo install -v -o root -g docker -m 660 -D -t /etc/micronets/micronets-manager.d/lib mso-auth-secret
    

    You should see output similar to the following:

    image185

  5. Execute the following command to download the Micronets Manager docker image. (Note: If you cannot connect to the docker service, use sudo usermod -aG docker to add the user account to the docker group.)

    /etc/micronets/micronets-manager.d/mm-container pull

    You should see output similar to the following:

    image186

  6. Complete the following step to configure NGINX for the Micronets Manager:

    1. The Micronets Manager management script creates NGINX forward entries that provide a unique URI for each Micronets Manager docker image. To create the infrastructure for these entries, run:

      sudo /etc/micronets/micronets-manager.d/mm-container setup-web-proxy

      You should see output similar to the following:

      image187

  7. This sets up the folder to dynamically create forwarding entries for Micronets Manager instances as they are created/removed. But the site files in /etc/nginx/sites-available/ need the following added to the server blocks to enable forwarding subscriber operations to the correct docker container.

    1. Open the NGINX sites-available file created in:

      sudo vim /etc/nginx/sites-available/nccoe-server1.micronets.net

    2. Add the following entry to the file:

      include /etc/nginx/micronets-subscriber-forwards/*.conf;

      For example:

      server {
         server_name nccoe-server1.micronets.net;
         {…]
         include /etc/nginx/micronets-subscriber-forwards/*.conf;
      }
      

      This image shows the contents of the "/etc/nginx/sites-available/nccoe-server1.micronets.net" file on the Micronets manager.

  8. Complete the following steps to configure the Micronets Manager to communicate with other Micronets services on the server:

    1. Open the docker-compose.yml file by entering the following command:

      sudo vim /etc/micronets/micronets-manager.d/docker-compose.yml

    2. Modify the following environmental variables in the docker-compose.yml file. Replace <ServerURL> with your server URL:

      MM_API_PUBLIC_BASE_URL: https://\ **<ServerURL>**/sub/${MM_SUBSCRIBER_ID}/api
      
      MM_APP_PUBLIC_BASE_URL: https:// **<ServerURL>**/sub/${MM_SUBSCRIBER_ID}/app
      
      MM_IDENTITY_SERVER_BASE_URL: https://\ **<ServerURL>**:8888/
      
      MM_MSO_PORTAL_BASE_URL: https:// **<ServerURL>**/micronets/mso-portal
      
      MM_MUD_MANAGER_BASE_URL: https:// **<ServerURL>**/micronets/mud-manager
      
      MM_MUD_REGISTRY_BASE_URL: https:// **<ServerURL>**/micronets/mud/v1
      
      MM_GATEWAY_WEBSOCKET_BASE_URL: wss://\ **<ServerURL>**:5050/micronets/v1/ws-proxy/gw
      

      This image shows the contents of the "/etc/micronets/micronets-manager.d/docker-compose.yml" file on the Micronets manager.

4.1.10 Micronets Websocket Proxy

This section describes the CableLabs Micronets Websocket Proxy, which, for this implementation, is a cloud-provided service. This implementation leverages the nccoe-build-3 branch of CableLabs Micronets Websocket Proxy Git release. This service can be hosted by the implementer or another party. This documentation describes setting up your own Micronets Manager.

4.1.10.1 Micronets Websocket Proxy Overview

The Micronets Websocket Proxy is a service for establishing a Websocket connection between a subscriberʼs gateway and Micronets Manager. This connection is leveraged to issue representational state transfer (REST) commands to the gateway and to receive event notifications from the gateway.

4.1.10.2 Configuration Overview

The following subsections document the software and network configurations for the Websocket Proxy. Please note that the MUD manager, Micronets Manager, Websocket Proxy, MUD registry, and MSO portal are all implemented on the same server, nccoe-server1.micronets.net. Many of these configurations are already covered in previous sections of this document but are repeated here for consistency.

4.1.10.2.1 Network Configuration

This server was hosted outside the lab environment on a Linode cloud-hosted Linux server. Its IP address was statically assigned.

4.1.10.2.2 Software Configuration

For this build, the server ran on an Ubuntu 18.04 LTS operating system. The Websocket Proxy runs in its own docker container and is configured to use SSL/TLS encryption.

The following software is required to install, configure, and operate the Websocket Proxy:

  • an Ubuntu 18.04 LTS server reachable by the Micronets Manager and any Micronets gateways

  • docker (v18.06 or higher)

  • docker-compose (v1.23.1 or higher)

  • curl

  • Python 3.6+

  • Python virtualenv package

4.1.10.2.3 Hardware Configuration

The following hardware is required to install, configure, and operate the Websocket Proxy:

  • 4 GB of RAM

  • 50 GB of free disk space

4.1.10.3 Setup

  1. Change to the working directory by entering the following command:

    cd Projects/micronets/

    If you have not already created this directory:

    1. Execute the following command:

      mkdir Projects/micronets/

    2. Next, change directories by entering the following command:

      cd Projects/micronets/

  2. Download and install the cert generation scripts by executing the following commands:

    1. Download the script to generate the root certificates:

      curl -s -O https://raw.githubusercontent.com/cablelabs/micronets-ws-proxy/nccoe-build-3/bin/gen-root-cert

    2. Download the script to generate leaf certificates:

      curl -s -O https://raw.githubusercontent.com/cablelabs/micronets-ws-proxy/nccoe-build-3/bin/gen-leaf-cert

    3. Install both scripts by executing the following command:

      sudo install -v -o root -m 755 -D -t /etc/micronets/micronets-ws-proxy.d/ gen-*-cert
      

      You should see output similar to the following:

      image190

  3. Create the root certificate for the Websocket Proxy:

    /etc/micronets/micronets-ws-proxy.d/gen-root-cert --cert-basename micronets-ws-root \
      --subject-org-name "Micronets Websocket Root Cert" \
      --expiration-in-days 3650
    

    You should see output similar to the following:

    image191

  4. Create the Websocket Proxyʼs server certificate and private key by entering the following command. (Note: This certificate and key host the Websocket Proxy server.)

    /etc/micronets/micronets-ws-proxy.d/gen-leaf-cert --cert-basename micronets-ws-proxy \
       --subject-org-name "Micronets Websocket Proxy Cert" \
       --expiration-in-days 3650 \
       --ca-certfile micronets-ws-root.cert.pem \
       --ca-keyfile micronets-ws-root.key.pem
    

    You should see output similar to the following:

    image192

  5. Combine the private key and certificate into one file by entering the following command:

    cat micronets-ws-proxy.cert.pem micronets-ws-proxy.key.pem \
       > micronets-ws-proxy.pkeycert.pem
    
  6. Generate the client certificate and key to be used by the Micronets Manager to connect to the Websocket Proxy. (Note: these files will enable the Micronets Manager to connect to the proxy.)

    /etc/micronets/micronets-ws-proxy.d/gen-leaf-cert --cert-basename micronets-manager \
       --subject-org-name "Micronets Manager Websocket Client Cert" \
       --expiration-in-days 3650 \
       --ca-certfile micronets-ws-root.cert.pem \
       --ca-keyfile micronets-ws-root.key.pem
    

    You should see output similar to the following:

    image193

  7. Combine the private key and certificate into one file by entering the following command:

    cat micronets-manager.cert.pem micronets-manager.key.pem \
       > micronets-manager.pkeycert.pem
    
  8. Generate the certificate and key to be used by the Micronets Gateway to connect to the Websocket Proxy. (Note: these files will enable the Micronets Gateway to connect to the proxy.)

    /etc/micronets/micronets-ws-proxy.d/gen-leaf-cert --cert-basename micronets-gw-service \
       --subject-org-name "Micronets Gateway Service Websocket Client Cert" \
       --expiration-in-days 3650 \
       --ca-certfile micronets-ws-root.cert.pem \
       --ca-keyfile micronets-ws-root.key.pem
    

    You should see output similar to the following:

    image194

  9. Combine the private key and certificate into one file by entering the following command:

    cat micronets-gw-service.cert.pem micronets-gw-service.key.pem \
       > micronets-gw-service.pkeycert.pem
    
  10. Download and install the management script by entering the following commands:

    1. Download the micronets-ws-proxy script:

      curl -s -O https://raw.githubusercontent.com/cablelabs/micronets-ws-proxy/nccoe-build-3/bin/micronets-ws-proxy

    2. Install the script to the appropriate directory:

      sudo install -v -o root -m 755 -D -t /etc/micronets/micronets-ws-proxy.d/ micronets-ws-proxy
      

      You should see output similar to the following:

      image195

  11. Copy the Websocket Proxy server cert and key for use by the Websocket Proxy docker container:

    sudo install -v -o root -m 600 -D -t /etc/micronets/micronets-ws-proxy.d/lib \
    micronets-ws-proxy.pkeycert.pem micronets-ws-root.cert.pem
    

    You should see output similar to the following:

    image196

  12. Download the Micronets Websocket Proxy docker image. (Note: if you cannot connect to the docker service, use sudo usermod -aG docker to add the user account to the docker group.)

    /etc/micronets/micronets-ws-proxy.d/micronets-ws-proxy docker-pull

    You should see output similar to the following:

    image197

  13. Start the Websocket Proxy:

    /etc/micronets/micronets-ws-proxy.d/micronets-ws-proxy docker-run

    You should see output similar to the following:

    image198

  14. Verify that the Websocket Proxy is running:

    /etc/micronets/micronets-ws-proxy.d/micronets-ws-proxy docker-logs

    You should see output similar to the following:

    image199

  15. Verify the Websocket Proxy credentials by executing the following steps:

    1. Download the Websocket test client script:

      curl -O https://raw.githubusercontent.com/cablelabs/micronets-ws-proxy/nccoe-build-3/bin/websocket-test-client.py

    2. Download the requirements text file:

      curl -O https://raw.githubusercontent.com/cablelabs/micronets-ws-proxy/nccoe-build-3/requirements.txt

    3. Clear out the nonroot installation of virtualenv, and set the Python interpreter to use Python 3.6 for the script installation:

      virtualenv --clear -p $(which python3.6) $PWD/virtualenv

      You should see output similar to the following:

      image200

    4. Install virtualenv and pass the requirements text file:

      ./virtualenv/bin/pip install -r requirements.txt

      You should see output similar to the following:

      image201

    5. Run the Websocket test client script:

      ./virtualenv/bin/python websocket-test-client.py \
         --client-cert micronets-manager.pkeycert.pem \
         --ca-cert micronets-ws-root.cert.pem \
         wss://localhost:5050/micronets/v1/ws-proxy/test/mm
      

      You should see output similar to the following:

      image202

    6. Verify communication from the test client to the Websocket Proxy by checking the logs:

      /etc/micronets/micronets-ws-proxy.d/micronets-ws-proxy docker-logs

      You should see output similar to the following:

      image203

  16. Save the micronets-manager.pkeycert.pem, micronets-gw-service.pkeycert.pem, and micronets-ws-root.cert.pem files for configuring the Micronets Manager and Micronets Gateway components.

4.1.11 Micronets iPhone Application for Device Onboarding

This section describes the CableLabs Micronets iPhone application, which is a mobile application used for onboarding DPP-capable devices. This implementation leverages the latest CableLabs Micronets iPhone application Git release. This documentation describes setting up your own Micronets iPhone application.

4.1.11.1 Micronets iPhone Application Overview

The Micronets iPhone application is responsible for sending onboarding requests and related elements to the MSO portal when the user initiates the onboarding process on the Micronets Proto-Pi device and scans the QR code. If building with an Android phone, follow the documentation provided here: https://github.com/cablelabs/micronets-mobile/blob/nccoe-build-3/README.md#android

4.1.11.2 Configuration Overview

The following subsections document the software and network configurations for the Micronets iPhone application.

4.1.11.2.1 Network Configuration

The mobile phone on which the Micronets application is being installed should have internet access via either the cellular network or Wi-Fi.

4.1.11.2.2 Software Configuration

The following software is required to install, configure, and operate the Micronets iPhone application:

  • macOS (minimum version 10.13; High Sierra)

  • Apple iOS Developer license

  • Node (minimum version 8)

  • Cordova (version 8.0.0; problems with version 9)

  • Xcode (minimum version 9.2)

  • ImageMagick

  • Brew

4.1.11.2.3 Hardware Configuration

The following hardware is required to install, configure, and operate the Micronets iPhone application:

  • Apple computing system (laptop or desktop)

  • Apple iPhone (any model compatible with iOS 10.3 and above)

4.1.11.3 Setup

4.1.11.3.1 Install Dependencies
  1. Install Node by entering the following command in the terminal:

    brew install node

  2. Install ImageMagick by entering the following command in the terminal:

    brew install imagemagick

  3. Install Cordova version 8.0.0 by entering the following command:

    sudo npm install -g cordova@8.0.0

  4. Install ios-deploy, which Cordova uses to cable-load the application, by entering the following command:

    sudo npm install -g --unsafe-perm=true ios-deploy

    Note: The unsafe-perm flag is required on macOS versions El Capitan and higher.

    If you run into an EACCES: permission denied error, attempt the following fixes:

    sudo chown -R $USER:$GROUP ~/.npm

    sudo chown -R $USER:$GROUP ~/.config

  5. Open Xcode, and add Xcode to your command-line tools:

    Preferences > Location > Command Line Tools

    Select your Xcode version as seen in screenshot below:

    This image shows the expected location to add XCode.

4.1.11.3.2 Build Micronets iPhone Application
  1. Check out the repo that contains the Micronets mobile application build by entering the following command:

    git clone https://www.github.com/cablelabs/micronets-mobile.git

    image205

  2. Enter the Micronets mobile directory by entering the following command:

    cd micronets-mobile

  3. Add the target platform by entering the following command:

    cordova platform add ios

    image206

  4. Generate iOS icon set by entering the following command:

    npx app-icon generate

    You should see the following output:

    image207

  5. Plug your iPhone into your computer, unlock your phone, and open to home screen. (You will need to allow developer use of the phone. You will be prompted.)

  6. Run the following command to build the mobile application:

    cordova run ios --device --buildFlag='-UseModernBuildSystem=0'

    You should see output similar to the following:

    image208

    Note: This initial attempt to build is expected to fail. It is necessary to open the project in Xcode and change some settings.

  7. Open the project file platforms/ios/Micronets.xcodeproj in Xcode.

  8. Click the Micronets icon in the navigator pane on the left. The properties pane should now be visible on the right:

    This image shows the Micronets icon in the navigator pane.

  9. Select Micronets under TARGETS:

    This image shows the Micronets option in the Targets section.

  10. Select the Signing & Capabilities tab in the heading:

    This image shows the Signing & Capabilities tab in the heading.

  11. Ensure Automatically manage signing is checked:

    This image shows the Automatically manage signing checkbox.

    You will see the following notification. Select Enable Automatic:

    This image shows the automatically manage signing notification.

    The Automatically manage signing setting should now be selected as seen below:

    This image shows the Automatically manage signing checkbox.

  12. Ensure that your team is selected under the Team drop-down:

    This image shows the Team dropdown.

    Note: If you encounter the following error to register the bundle identifier, proceed to step a: This image shows the "Failed to register bundle identifier" error.

    1. Change the Bundle Identifier to your own unique identifier:

      This image shows the Bundle Identifier box.

    2. Navigate to the config.xml file by selecting as shown below:

      This image shows the config.xml file in the navigation menu.

    3. Modify the widget id from com.cablelabs.micronets.mobile to the build identifier created in step a as seen below:

      This image shows the contents of the config.xml file.

      This image shows the contents of the config.xml file.

  13. Select the General tab in the heading:

    This image shows the General tab in the heading.

  14. Under Deployment Info, make the following modifications:

    1. Select the deployment Target (suggested 10.3)

      image222

      image223c

    2. Select Device type iPhone and iPad, Device Orientation Portrait and Upside Down, Status Bar style Hide status bar:

      image224

  15. Select the Info tab, and make the following modifications:

    This image shows the Info tab in the heading.

    1. On the last entry in Custom iOS Target Properties, hover over the down arrow.

    2. A plus sign appears. Click it to create a new property.

      image226

    3. In the combo box drop-down, start typing View controller, and choose the auto-fill suggestion View controller-based status bar appearance:

      image227

    4. Click enter to add this entry. Ensure this entry is set to NO.

      image228

  16. Return to the terminal, and run the following command (ensure the iPhone is unlocked first):

    cordova run ios --device --buildFlag='-UseModernBuildSystem=0'

    Note: You may see an UnhandledPromiseRejectionWarning as seen below, but the application should still have been loaded onto your iPhone:

    image229

4.1.12 MSO Portal Bootstrapping Interface to the Onboarding Manager

This section describes the CableLabs Micronets MSO portal, which, for this implementation, is a cloud-provided service. This implementation leverages the nccoe-build-3 branch of CableLabs Micronets MSO portal Git release. This service can be hosted by the implementer or another party. This documentation describes setting up your own MSO portal.

4.1.12.1 MSO Portal Overview

The MSO portal is the interface between the Micronets iPhone application and the Micronets Manager. It is responsible for passing onboarding requests and respective onboarding information to the Micronets Manager to complete the request.

4.1.12.2 Configuration Overview

The following subsections document the software and network configurations for the MSO portal. Please note that the MUD manager, Micronets Manager, Websocket Proxy, MUD registry, and MSO portal are all implemented on the same server, nccoe-server1.micronets.net. Many of these configurations are already covered in previous sections of this document but are repeated here for consistency.

4.1.12.2.1 Network Configuration

This server was hosted outside the lab environment on a Linode cloud-hosted Linux server. Its IP address was statically assigned.

4.1.12.2.2 Software Configuration

The following software is required to install, configure, and operate the MSO portal:

  • docker (v18.06 or higher)

  • docker-compose (v1.23.1 or higher)

  • OpenSSL (1.0.2g or higher)

  • NGINX and requisite certificates if https is to be supported

4.1.12.2.3 Hardware Configuration

The following hardware is required to install, configure, and operate the MSO portal:

  • 4 GB of RAM

  • 50 GB of free disk space

4.1.12.3 Setup

4.1.12.3.1 Install Dependencies
  1. Install docker, docker-compose, openssl, and NGINX by entering the following command:

    sudo apt-get install docker docker-compose openssl nginx

4.1.12.3.2 Install and Configure MSO Portal
  1. Install a newer version of docker-compose, if necessary. (Ubuntu 18.04 comes with an older version.)

    1. Check the current version by entering the following command:

      docker-compose --version

      The result should be similar to the following:

      image41932-1

    2. If the version is earlier than v1.23.1, run the following commands to install a new version in /usr/local/bin:

      1. Download the docker compose utility:

        curl -L -O https://github.com/docker/compose/releases/download/1.24.1/docker-compose-Linux-`uname -m’
        
      2. Install the docker compose utility into the appropriate directory:

        sudo install -v -o root -m 755 docker-compose-Linux-`uname -m\` /usr/local/bin/docker-compose
        

        The result should be similar to the following:

        image41932-2

  2. Download and install the MSO portal management script by entering the following commands:

    1. Download the MSO portal management script by executing the following command:

      curl -O https://raw.githubusercontent.com/cablelabs/micronets-mso-portal/nccoe-build-3/scripts/mso-portal

    2. Download the docker-compose.yml file by executing the following command:

      curl -O https://raw.githubusercontent.com/cablelabs/micronets-mso-portal/nccoe-build-3/scripts/docker-compose.yml

    3. Install the MSO portal management script to the appropriate directory by executing the following command:

      sudo install -v -o root -m 755 -D -t /etc/micronets/mso-portal.d mso-portal

      The result should be similar to the following:

      image230

    4. Install the docker-compose.yml management script to the appropriate directory by executing the following command:

      sudo install -v -o root -m 644 -D -t /etc/micronets/mso-portal.d docker-compose.yml
      

      The result should be similar to the following:

      image231

    Note: The MSO portal management script contains default values that can be modified directly in your copy of the management script or overridden via command-line parameters. Run /etc/micronets/mso-portal.d –help to see the options.

  3. Download the MSO portal docker image by executing the following command. (Note: If you cannot connect to the docker service, you can use sudo usermod -aG docker <username> to add the user account to the docker group.)

    /etc/micronets/mso-portal.d/mso-portal docker-pull

    The result should be similar to the following:

    image232

  4. Generate a shared secret for enabling communication between the Micronets Manager instances and the MSO portal:

    sudo /etc/micronets/mso-portal.d/mso-portal create-mso-secret

    The result should be similar to the following:

    image233

    Note: This value will need to be copied to the Micronets Manager host server to allow Micronets Manager instances to access the MSO portal APIs.

  5. Configure MSO portal URLs:

    1. Open the mso-portal file by entering the following command:

      sudo vim /etc/micronets/mso-portal.d/mso-portal

    2. Modify the parameters of the MSO portal management script to reflect the public end points of the MSO portal service. For example:

      1. The DEF_MSO_API_BASE_URL path variable can be set to:

        DEF_MSO_API_BASE_URL="https://nccoe-server1.micronets.net/micronets/mso-portal/"
        
      2. The DEF_WS_PROXY_BASE_URL path variable can be set to:

        DEF_WS_PROXY_BASE_URL="wss://nccoe-server1.micronets.net:5050/micronets/v1/ws-proxy/gw"
        

        This image shows the contents of the "/etc/micronets/mso-portal.d/mso-portal" file on the MSO portal.

  6. Start the MSO portal docker image by executing the following command:

    sudo /etc/micronets/mso-portal.d/mso-portal docker-run

    The result should be similar to the following:

    image235

  7. Verify that the MSO portal started successfully by executing the following command:

    /etc/micronets/mso-portal.d/mso-portal docker-logs

    You should see output like the following at the end of the log:

    Feathers application started on “http://0.0.0.0:3210”

    Feathers webSocketBaseUrl “wss://<ServerURL>:5050/micronets/v1/ws-proxy/gw”

    Feathers publicApiBaseUrl “https://< ServerURL>/micronets/mso-portal/”

    image236

  8. To securely expose the MSO API, configure your NGINX server block to allow the https proxy to redirect to localhost port 3210:

    1. Open the NGINX sites-available file for the server:

      sudo vim /etc/nginx/sites-available/nccoe-server1.micronets.net

    2. Add the following location to the server block:

      server {
            […]
         location /micronets/mso-portal/ {
            proxy_pass http://127.0.0.1:3210/;
         }
            […]
      }
      

      This image shows the contents of the "/etc/nginx/sites-available/nccoe-server1.micronets.net" file on the MSO portal.

4.2 Product Integration and Operation

This section details integration and operation of the Micronets components that were previously installed in the product installation section. Please ensure that the components from that section are installed as described before proceeding to the following sections.

4.2.1 Adding an MSO Subscriber

This section describes adding an MSO portal subscriber. This subscriber account will allow a valid connection and association among the Micronets mobile application, Micronets Gateway, and Micronets services.

4.2.1.1 Prerequisites

To successfully complete this section, complete the product installation section.

4.2.1.2 Instructions

  1. Add a subscriber and associated user account and password to the MSO portal by entering the following command. (Note: be sure to use the server URL that reflects the location of your MSO portal.)

    curl -s -X POST https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/subscriber \
       -H "Content-Type: application/json" \
       -d '{
          "id" : "subscriber-001",
          "ssid" : "micronets-gw",
          "name" : "Subscriber 001",
          "gatewayId":"micronets-gw",
          "username":"micronets",
          "password":"micronets"
       }' \
    | json_pp
    

    You should see output similar to the following:

    A screenshot of output of the command executed to add a subscriber account the mso-portal. The screenshot outputs a confirmation of the information sent in the command.

  2. Start the Micronets Manager for the subscriber by executing the following command:

    sudo /etc/micronets/micronets-manager.d/mm-container start subscriber-001

    You should see output similar to the following:

    image239

  3. Check the logs to confirm that the Micronets Manager for the new subscriber started successfully by executing the following command:

    /etc/micronets/micronets-manager.d/mm-container logs subscriber-001

    You should see output similar to the following:

    image240

  4. Verify that the Micronets Manager for the subscriber has registered with the MSO portal by executing the following command:

    curl -s https://my-server.org/micronets/mso-portal/portal/v1/subscriber/subscriber-001 | json_pp
    

    You should see output similar to the following:

    image241

4.2.2 Associating the Micronets Gateway with a Subscriber

This section describes associating an MSO portal subscriber with the Micronets Gateway. For additional instructions not detailed in this documentation, please follow the link to the CableLabs documentation: https://github.com/cablelabs/micronets-gw/releases/tag/1.0.62-u18.04 (for Micronets Gateway configuration) and https://github.com/cablelabs/micronets/blob/nccoe-build-3/docs/operation/gateway-4subscriber.md (for operations documentation).

4.2.2.1 Prerequisites

To successfully complete this section, complete the product installation section and complete Section 4.2.1. Ensure that all steps have been successfully completed before proceeding to the instructions.

4.2.2.2 Instructions

  1. Create the /etc/network/interfaces file on the Micronets Gateway:

    1. Open a terminal on the Micronets Gateway. If this is the first installation of the Micronets Gateway, copy the sample interfaces file to your /etc/network/interfaces file by entering the following command:

      sudo cp /opt/micronets-gw/doc/interfaces.sample /etc/network/interfaces

    2. Modify the /etc/network/interfaces file:

      1. Retrieve the desired interface names on the gateway by running the following command in a terminal on the gateway:

        ifconfig

      2. Configure your wireless and wired interface by renaming the corresponding portion of the file to reference the respective interface name, as seen in the config below:

        #
        # A wired interface managed by the Micronets gateway
        #
        allow-brmn001 enp1s0
        iface enp1s0 manual
          ovs_type OVSPort
          ovs_bridge brmn001
          ovs_port_req 4
          ovs_port_initial_state blocked
        #
        # A wireless interface managed by the Micronets gateway
        #
        allow-brmn001 wlp2s0
        iface wlp2s0inet manual
          ovs_type OVSPort
          ovs_bridge brmn001
          ovs_port_req 3
          ovs_port_initial_state blocked
        
      3. Confirm that the bridge entry contains an ovs_ports line referring to the micronet interfaces (enp1s0 and wlp2s0) as seen in the config below:

        auto brmn001
        allow-ovs brmn001
        iface brmn001 inet manual
          ovs_type OVSBridge
          ...
        # the ovs_ports should list all wired and wireless interfaces under Micronets management
          ovs_ports diagout1 enp1s0 wlp2s0
          ...
        
      4. Confirm that the entry in the interfaces file for the wired interface is set up correctly for the network to supply the uplink (the uplink interface is enp1s0) and get its address via DHCP so the configuration is similar to the following:

        #
        # The uplink port
        #
        auto eth enp1s0
        iface eth0inet dhcp
        
      5. Confirm that the bridge entry contains an ovs_bridge_uplink_port line referring to the uplink interface as seen in the config below:

        auto brmn001
        allow-ovs brmn001
        iface brmn001 inet manual
          ovs_type OVSBridge
          ...
          # This is the port that's connected to the Internet
          ovs_bridge_uplink_port enp1s0
          ...
        
      6. Reboot the gateway to apply the changes to the /etc/network/interfaces file by executing the following command:

        sudo reboot

  2. Create a gateway configuration file for the Micronets Gateway to register for the subscriber:

    1. Copy and save the MAC addresses and corresponding interface names output by executing the following command:

      ifconfig

    2. Navigate to the /etc/network/interfaces file on the gateway, and copy the subnets configurations, which will be used for the gateway configuration file in the following steps:

      sudo vim /etc/network/interfaces

      Copy and save the subnet and ranges associated with the interfaces identified in the previous step from this file. (Note: these are at the bottom of the file.)

      image242

      image243

    3. Create the gateway config file by entering the following command:

      sudo vim gateway-config-001.json

    4. Modify the following configuration to include your gateway’s MAC address and subnets as seen below, and copy them into the gateway-config-001.json file.

      Be sure to modify the ipv4SubnetRanges definition to match the bridge subnet range—e.g., the file above defines five different subnets ranging from 10.135.1.1/24– 10.135.5.1/24, so we set octetC to have a minimum of 1 and a maximum of 5, and octetD to have a minimum of 2 and a maximum of 254, as seen in the config below:

      {
          "version": "1.0",
          "gatewayId": "micronets-gw",
          "gatewayModel": "proto-gateway",
          "gatewayVersion": {"major":1, "minor":0, "micro":0},
          "configRevision": 1,
          "vlanRanges": [
              {"min":1000, "max":4095}
          ],
          "micronetInterfaces": [
              {
                  "medium": "wifi",
                  "name": "wlp2s0",
                  "macAddress": "20:16:d8:2b:4b:41",
                  "ssid": "micronets-gw",
                  "dpp": {
                      "supportedAkms": ["psk"]
                  },
                  "ipv4SubnetRanges": [
                      {
                          "id": "range001",
                          "subnetRange": {"octetA": 10,
                              "octetB": 135,
                              "octetC": {"min":1, "max":5}
                          },
                          "subnetGateway": {"octetD": 1},
                          "deviceRange": {"octetD": {"min":2, "max":254}}
                      }
                  ]
              },
              {
                  "medium": "ethernet",
                  "name": "enp1s0",
                  "macAddress": "80:ee:73:dc:64:1d",
                  "ipv4Subnets": [
                      {
                          "id": "range001",
                          "subnetRange": {"octetA": 10,
                              "octetB": 135,
                              "octetC": 250
                          },
                          "subnetGateway": {"octetD": 1},
                          "deviceRange": {"octetD": {"min":2, "max":254}}
                      }
                  ]
              }
          ]
      }
      
  3. Register a gateway configuration for a subscriber with the subscriber’s Micronets Manager instance by entering the following command (with the subscriber being subscriber-001 in this case):

    curl -s -X POST https://nccoe-server1.micronets.net/sub/subscriber-001/api/mm/v1/micronets/odl \
    
    -H "Content-Type: application/json" -d @./gateway-config-001.json | json_pp
    

    You should see output similar to the following:

    image244

    image245

  4. Confirm that the gateway ID is updated in the MSO portal by executing the following command:

    curl -s https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/subscriber/subscriber-001 | json_pp
    

    You should see output similar to the following:

    image246

  5. Configure the Micronets Gateway with the Websocket Proxy keys provisioned for the gateway:

    1. Copy the client cert and key as well as the Websocket root certificate, created in the product installation section, from the cloud server into the gateway by executing the following commands from the gateway:

      1. Copy the micronets-gw-service.pkeycert.pem to the gateway:

        scp micronets-dev@nccoe-server1.micronets.net:Projects/micronets/micronets-gw-service.pkeycert.pem .
        

        You should see the following output:

        image247

      2. Copy the micronets-ws-root.cert.pem to the gateway:

        scp micronets-dev@nccoe-server1.micronets.net:Projects/micronets/micronets-ws-root.cert.pem .
        

        You should see the following output:

        image248

    2. Copy them into the gateway service library to be loaded when the gateway is restarted:

      sudo cp -v micronets-gw-service.pkeycert.pem micronets-ws-root.cert.pem /opt/micronets-gw/lib/
      
  6. Change the Websocket lookup URL to use the MSO portal service on your server by completing the following commands:

    1. Open the Micronets Gateway config file by executing the following command:

      sudo vim /opt/micronets-gw/config.py

    2. Modify the WEBSOCKET_LOOKUP_URL and GATEWAY_ID to match the MSO portal Websocket lookup end point created in the product installation section and the Micronets Gateway ID:

      WEBSOCKET_LOOKUP_URL = 'https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/socket?gatewayId={gateway_id}'
      
      GATEWAY_ID = 'micronets-gw'
      

      A screenshot of the micronets gateway config with the websocket lookup url and the gateway ID modified to reflect the specified endpoint and ID.

  7. Restart the Micronets Gateway Service by executing the following command:

    sudo systemctl restart micronets-gw.service

  8. Check the Micronets Gateway Service log (/opt/micronets-gw/micronets-gw.log ) to verify that the gatewayʼs Websocket registration status was successful:

    cat /opt/micronets-gw/micronets-gw.log

    You should see output similar to the following:

    A screenshot of the logs for the micronet3s gateway showing the successful connection to the websocket proxy.

  9. Confirm the establishment of the gateway-manager control connection by examining the Websocket Proxy connection reports in the Websocket Proxy log:

    /etc/micronets/micronets-ws-proxy docker-logs | less

    Look for the following in the log (with the MEETUP ID matching the subscriber name in question):

    A screenshot of the docker-logs for the websocket proxy showing the meetup table and the successful connection of the client.

    This indicates that the Micronets Gateway Service and the Micronets Manager for the subscriber connected and can exchange provisioning commands and event indications.

4.2.3 Integrating Micronets Proto-Pi Device

This section describes associating an MSO portal subscriber with the Micronets Gateway. For additional instructions not detailed in this documentation, please follow the link to the CableLabs documentation: https://github.com/cablelabs/micronets-pi3/blob/nccoe-build-3/README.md#Operation.

4.2.3.1 Prerequisites

To successfully complete this section, be sure to have completed the product installation section associated with the Micronets Proto-Pi device. Ensure all steps have been successfully completed before proceeding to the instructions.

4.2.3.2 Instructions

  1. Connect to the Raspberry Pi via SSH by entering the following command:

    ssh pi@192.168.30.191

    You will be prompted to enter the device password; the password will remain the same.

  2. Change to the keys directory by entering the following command:

    cd micronets-pi3/keys/

  3. Output the content of the proto-pi.dpp.pub file to copy the public key for this device. (Note: you will need to store this device key for registering the device with the MUD registry if doing so manually.)

    cat proto-pi.dpp.pub

    Highlight and copy the key that was output by the previous command:

    This image shows the expected output of the above command being used on the Raspberry Pi.

  4. Modify the config.json file to include the key that was copied in the previous step, and modify the parameters of the file to match your setup:

    sudo vim ~/micronets-pi3/config/config.json

    The original file before editing should be similar to the following screenshot:

    This image shows the content of the file "~/micronets-pi3/config/config.json" on the Raspberry Pi.

    If doing manual device registration, edit the file to reflect the correct DeviceModelUID (should be the same name as the MUD file associated with this device), dppMUDUrl, msoPortalUrl, registrationServer, vendorCode as seen below:

    {
        "channel": 1,
        "channelClass": 81,
        "comcast": false,
        "demo": true,
        "deviceModelUID": "nist-model-fe_northsouth.json",
        "deviceProfile": "device-0",
        "disableMUD": false,
        "dppMUDUrl": "https://nccoe-server1.microents.net/mud/v1/mud-url/TEST/MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgACxjMF8Ucp6d3gRBImv78eGEMwB5igS2Kt5bnXI7VeBrc=",
        "dppName": "myDevice",
        "dppProxy": {
            "msoPortalUrl": "https://nccoe-server1.micronets.net/micronets/mso-portal/",
            "password": "grandma",
            "username": "grandma"
        },
        "messageTimeoutSeconds": 45,
        "mode": "dpp",
        "onboardAnimationSeconds": 5,
        "qrcodeCountdown": 30,
        "registrationServer": "https://nccoe-server1.micronets.net/registry/devices",
        "splashAnimationSeconds": 10,
        "vendorCode": "TEST"
    }
    

    If enabling self-registry, follow the steps described in this documentation: https://github.com/cablelabs/micronets-pi3/blob/nccoe-build-3/README.md#dpp-mode-mud-registry

  5. Reboot the device for the new config file to take effect:

    sudo reboot

4.2.4 Updating MUD Registry

This section describes the HTTP API operations for interacting with the MUD registry. The instructions detail how to register a MUD-capable device and its MUD URL with a vendor. For additional API operations not documented here, follow the link to the CableLabs MUD registry operation documentation: https://github.com/cablelabs/micronets-mud-registry/blob/nccoe-build-3/README.md#Operation.

4.2.4.1 Prerequisites

To successfully complete this section, be sure to have completed the product installation section.

4.2.4.2 Instructions

  1. Retrieve the device registry URL for a vendor by entering the following curl command:

    /mud/v1/device-registry/:vendor-code

    curl -L https://nccoe-server1.micronets.net/mud/v1/device-registry/TEST

    You should see output similar to the following:

    image254

  2. Register a device with a vendor’s registry. This requires the device model UID and the public key, which can be modified and retrieved through the Micronets Proto-Pi:

    /registry/devices/register-device/:device-model-UID64/:public-key

    curl -X POST https://nccoe-server1.micronets.net/registry/devices/register-device/nist-model-fe_northsouth.json/MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADSOi8J6JCJJ0h4+NmPtARUgfMrQ2mcCazdJNfNdgTkZM=
    

    You should see output similar to the following:

    image255

  3. Retrieve the MUD registry URL for a vendor:

    /mud/v1/mud-registry/:vendor-code

    curl https://nccoe-server1.micronets.net/mud/v1/mud-registry/TEST

    You should see output similar to the following:

    image256

  4. Lookup a MUD URL from the vendor MUD registry:

    /registry/devices/mud-registry/:public-key

    curl https://nccoe-server1.micronets.net/registry/devices/mud-registry/MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADSOi8J6JCJJ0h4+NmPtARUgfMrQ2mcCazdJNfNdgTkZM=
    

    You should see output similar to the following:

    image257

  5. Delete a device from the MUD registry. (Note: if you do this step, the device will no longer be associated with a MUD file. Therefore, you should execute this command only if you do not intend to onboard the device with MUD capabilities.)

    /registry/devices/remove-device/:public-key

    curl -L -X POST https://nccoe-server1.micronets.net/registry/devices/remove-device/MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADSOi8J6JCJJ0h4+NmPtARUgfMrQ2mcCazdJNfNdgTkZM=
    

    You should see output similar to the following:

    image258

4.2.5 Integrating the Micronets iPhone App with MSO Portal

This section describes integrating the Micronets iPhone application with the MSO portal. For additional instructions not detailed in this documentation, please follow the link to the CableLabs documentation: https://github.com/cablelabs/micronets-mobile/blob/nccoe-build-3/README.md#Operation.

4.2.5.1 Prerequisites

A valid network connection on the iPhone is required as well as the completion of the product installation section related to the Micronets iPhone application.

4.2.5.2 Instructions

  1. Open the Micronets mobile application:

    This image shows the iOS home screen with the Micronets mobile app icon.

  2. From the splash screen, click the gear button in the upper right corner to open the settings page:

    This image shows Micronets Mobile App initial screen with the gear button enclosed with a red box, which is to be clicked.

  3. Modify the following fields in the general settings:

    Mode - DPP or Clinic: We select DPP; if you are selecting the Clinic mode, please follow the documentation for details related to the Clinic mode.

    Debug - Leave this off, as CableLabs will be deprecating this in the future.

    Enable MUD – If enabled, it will try to fetch the MUD file for the scanned device and prepopulate the Submit form prior to onboarding.

    A screenshot of the settings menu for the general settings associated with the micronets moblie application modified to reflect the correct modes enabled.

  4. Modify the servers for the Micronets application:

    DPP – MSO portal server URL for submitting onboard requests

    IdOra – Server for user authentication. (Note: this is only required if utilizing the Clinic Mode.)

    MUD – MUD registry server for looking up MUD files using the vendor code and public key in the QRCode. (Note: this only needs to be changed if you are deploying your own MUD registry.)

    A screenshot of the settings menu for the servers associated with the micronets moblie application modified to reflect the correct servers.

  5. Back on the Micronets mobile application, enter your subscriber credentials and click SIGN IN:

    A screenshot of the micronets mobile application with the subscirber credentials input and the sign in button enclosed with a red box which is to be clicked.

  6. Click the READY TO SCAN button to open the camera for onboarding:

    A screenshot of the micronets mobile application with the ready to scan button enclosed in a red box, which is to be clicked.

  7. If prompted, allow the Micronets application camera access by clicking OK:

    A screenshot of the micronets mobile application with a prompt for the user to allow Micronets to use access the camera. The OK button is enclosed with a red box, which is to be clicked.

4.2.6 Onboarding Micronets Proto-Pi to a Micronet

This section describes how to onboard a configured Micronets Proto-Pi device to a micronet using the Micronet iPhone app. For additional instructions not detailed in this documentation, please follow the link to the CableLabs documentation: https://github.com/cablelabs/micronets-pi3/blob/nccoe-build-3/README.md#Operation.

4.2.6.1 Prerequisites

To successfully complete this section, the following is required:

  • a Raspberry Pi with the Micronets Proto-Pi software installed and configured

  • an iOS or Android phone with the Micronets application installed and configured

  • a Micronets subscriber account configured in Section 4.2.1

  • a gateway device associated with the Micronets subscriber configured in Section 4.2.2

4.2.6.2 Instructions

  1. If leveraging the self-registration feature for MUD onboarding, ensure that an ethernet cable is connected to the Raspberry Pi running the Micronets Proto-Pi software.

  2. Power on the Pi device. If leveraging the self-registration feature, the device will automatically be registered on first run.

  3. On the mobile device, open the Micronets mobile application and log in with your subscriber credentials.

    A screenshot of the micronets mobile application with the subscriber credentials input and the sign in button enclosed with a red box which is to be clicked.

  4. On the Mobile device, tap the Ready to Scan button:

    A screenshot of the micronets mobile application with the ready to scan button enclosed in a red box, which is to be clicked.

  5. On the Pi, click the Onboard icon:

    A screenshot with the proto-pi device on the main page with the onboard button enclosed in a red box, which is to be clicked.

    You should see a QR code appear on the screen:

    A screenshot of the QR code that has appeared on the proto-pi device once the onboard button has clicked

  6. Scan the QRCode with the Micronet mobile application:

    A screenshot of the micronets mobile application scanning the QR Code that has appeared on the proto-pi device.

  7. On the next screen that appears on the Micronets mobile application, input the following information in a timely fashion. (Note: these steps must be completed while the device is still in onboard mode.)

    1. If a MUD file was found, the device CLASS and NAME will be pre-populated; modify as needed. In the case that a MUD file was not found, populate the CLASS and NAME manually.

    2. Set the MODE to STA. (Note: the Mode should always be STA as of the time of this implementation.)

    3. Tap the ONBOARD button to send the onboarding request to the MSO portal.

      A screenshot of the Micronets mobile application in the onboarding page. The class and name are specified and the onboard button is enclosed in a red box, which is to be clicked.

  8. On the Pi, you will see the device has been onboarded to the Micronets Gateway and has received an IP address:

    A screenshot of the proto-pi device onboarded to the gateway and assigned an IP address of "10.135.1.2".

4.2.7 Interacting with Micronets Manager

The Micronets Manager, which is hosted in the cloud, has API endpoints exposed in order to allow implementers to manage the Micronets Gateway through the Micronets Manager service. This section describes how to set up postman and execute different functions.

4.2.7.1 Prerequisites

In order to successfully complete this section of the documentation, be sure to have completed the product installation section above and downloaded the Postman application onto a laptop that has

4.2.7.2 Instructions

  1. Once Postman is installed and set up on the laptop, proceed to the following site to download the Micronets Manager Linode postman collections:

    Follow the links:


  2. Open the Postman application and sign in.

  3. Click the import button to import the collections downloaded in step 1:

    A screenshot of the postman application open and the import button in the top left hand corner of the application enclosed in a red box, which is to be clicked.

  4. Next, click upload files:

    A screenshot of the import menu opened with the upload files button enclosed with a red box, which is to be clicked.

  5. Select the Postman and global environmental variables collections downloaded in step 1:

    This image shows the File Select menu, with two files selected.

  6. Confirm your import and click Import:

    A screenshot of the two files selected to be opened and imported to the postman application. The open button is enclosed in a red box which is to be clicked.

  7. You will need to set the Globals for the micronets-manager-linode-ip, subscriberId, and mso-portal-linode-ip:

    1. Click the gear button in the top right-hand corner of the application to Manage Environments:

      A screenshot of main page of the postman application with the gear button enclosed with a red box which is to be clicked.

    2. Click Globals:

      A screenshot of the manage environements menu opened with the Globals button enclosed in a red box which is to be clicked.

    3. Modify the current values for the micronets-manager-linode-ip, subscriberId, and mso-portal-linode-ip variables as follows and click Save:

      micronets-manager-linode-ip: nccoe-server1.micronets.net

      subscriberId: subscriber-001

      mso-portal-linode-ip: nccoe-server1.micronets.net

      A screenshot of the manage environements menu opened with the current value of the Variables modified to reflect the correct servers.

    4. Exit out of the menu:

      A screenshot of the manage environements menu opened with the "X" buttone enclose in a red box to exit out of the menu.

  8. Next, open the Postman collection and review and modify the URLs for the calls to ensure the API endpoint paths match your implementation:

    1. Modify the GET MM Gateway Config command to reflect the following. Executing this command will pull the current Gateway config from the Micronets Manager:

      http://{{micronets-manager-linode-ip}}/mm/v1/micronets/odl

      A screenshot showing the postman collection and the "GET MM Gateway Config" request modified to include the URL: http://{{micronets-manager-linode-ip}}/mm/v1/micronets/odl

    2. Modify the GET MM Registry command to reflect the following. Executing this command will pull the current registry from the Micronets Manager:

      https://{{micronets-manager-linode-ip}}/mm/v1/micronets/registry

      A screenshot showing the postman collection and the "GET MM Registry" request modified to include the URL: https://{{micronets-manager-linode-ip}}/mm/v1/micronets/registry

    3. Modify the GET Micronets command to reflect the following. Executing this command will pull a list of the current micronets on the Gateway from the Micronets Manager:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}
      

      A screenshot showing the postman collection and the "GET Micronets" request modified to include the URL: https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}

    4. Modify the GET Gateway Subnets command to reflect the following. Executing this command will pull a list of the current subnets on the Gateway from the Micronets Manager:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/dhcp/subnets
      

      A screenshot showing the postman collection and the "GET Gateway Subnets" request modified to include the URL: https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/dhcp/subnets

    5. Modify the GET Gateway Devices in a subnet command to reflect the following. Executing this command will pull a list of the current devices in a subnet on the Gateway from the Micronets Manager:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/dhcp/subnets/subnetId/devices
      

      A screenshot showing the postman collection and the "GET Gateway Devices in a subnet" request modified to include the URL: https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/dhcp/subnets/subnetId/devices

    6. Modify the GET MM Users command to reflect the following. Executing this command will pull a list of the users associated with the subscriber ID from the Micronets Manager:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/micronets/users
      

      A screenshot showing the postman collection and the "GET MM Users" request modified to include the URL: https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/micronets/users

    7. Modify the DELETE All Micronets command to reflect the following. Executing this command will delete all of the current micronets on the Gateway via the Micronets Manager:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}/micronets
      

      A screenshot showing the postman collection and the "DELETE All Micronets " request modified to include the URL: https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}/micronets

    8. Modify the DELETE Single Micronets command to reflect the following. Executing this command will delete a specific micronet on the Gateway via the Micronets Manager. This command is to be modified before executing to specify the <micronetID>, which can be retrieved by executing the GET Micronets command:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}/micronets/<micronetID>

      Below is an example of this command:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}/micronets/2453819029
      

      A screenshot showing the postman collection and the "DELETE Single Micronets " request modified to include the URL: https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}/micronets/2136369149/devices/da34c7219c2c97f0e2c2838e66c725d137f3c097

    9. Modify the DELETE Device from Micronet command to reflect the following. Executing this command will delete a specific device from a particular micronet on the Gateway via the Micronets Manager. This command is to be modified before executing to specify the <micronetID> and <deviceID>, which can be retrieved by executing the GET Micronets command:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}/micronets/<micronetID> /devices/<deviceID>

      Below is an example of this command:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}/micronets/2136369149/devices/da34c7219c2c97f0e2c2838e66c725d137f3c097
      

      A screenshot showing the postman collection and the "DELETE Device from Micronet" request modified to include the URL: https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/subscriber/{{subscriberId}}/micronets/2136369149/devices/da34c7219c2c97f0e2c2838e66c725d137f3c097

    10. Modify the DELETE Gateway Subnets command to reflect the following. Executing this command will delete all subnets on the Gateway via the Micronets Manager:

      https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/dhcp/subnets
      

      A screenshot showing the postman collection and the "Delete Gateway Subnets" request modified to include the URL: https://{{micronets-manager-linode-ip}}/sub/{{subscriberId}}/api/mm/v1/dhcp/subnets

4.2.8 Removing Micronets Proto-Pi from a Micronet

Removing a Micronets Proto-Pi from a micronet will remove the network credentials from the device. For additional instructions not detailed in this documentation, please follow the link to the CableLabs documentation: https://github.com/cablelabs/micronets/blob/nccoe-build-3/docs/operation/pi-offboarding.md.

4.2.8.1 Prerequisites

To successfully complete this section, the following are required:

  • a Raspberry Pi with the Micronets Proto-Pi software installed and configured

  • a device that is currently onboarded to the Micronets Gateway

4.2.8.2 Instructions

  1. Power on the Micronets Proto-Pi device.

  2. Tap Settings:

    This image shows the settings button in the Micronets Proto-Pi app being used on the Raspberry Pi.

  3. Tap Reset:

    This image shows the reset button from the Settings menu in the Micronets Proto-Pi app being used on the Raspberry Pi.

    You should see output similar to the following:

    This image shows the result of clicking the reset button. The device outputs "Clearing Wifi Credentials..."

4.2.9 Removing an MSO Subscriber

Removing a subscriber involves removing the subscriber from the MSO portal database, removing the subscriber’s micronets, and removing the subscriberʼs Micronets Manager. For additional instructions not detailed in this documentation, please follow the link to the CableLabs documentation: https://github.com/cablelabs/micronets/blob/nccoe-build-3/docs/operation/pi-offboarding.md.

4.2.9.1 Prerequisites

To successfully complete this section, be sure to have first completed both the product installation section and the section that details adding the MSO portal.

4.2.9.2 Instructions

  1. Remove the subscriber from the MSO portal:

    curl -s -X DELETE https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/subscriber/subscriber-001 | json_pp
    
  2. Verify that the subscriber is removed from the MSO portal by executing the following commands:

    1. Check if the subscriber ID is present in the subscriber list:

      curl -s https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/subscriber/subscriber-001 | json_pp
      

      You should see output similar to the following:

      image288

    2. Next, check if the user is present in the list of users in the MSO portal:

      curl -s https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/users | json_pp
      

      You should see output similar to the following:

      image289

    3. Finally, check to see if there is a socket present for the subscriber ID:

      curl -s https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/socket/subscriber-001 | json_pp
      

      You should see output similar to the following:

      image290

Note: There could be scenarios where the commands above do not show empty lists. If that is the case, the subscriber has not been deleted properly. You can delete the subscriber entries in the MSO portal subtables by executing the following commands:

  1. Delete the subscriber ID from the user list manually:

    curl -s -X DELETE https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/users/subscriber-001 | json_pp
    
  2. Delete the subscriber ID from the socket list manually:

    curl -s -X DELETE https://nccoe-server1.micronets.net/micronets/mso-portal/portal/v1/socket/subscriber-001
    
  1. Remove all the micronets for the subscriber using:

    curl -s -X DELETE https://nccoe-server1.micronets.net/sub/subscriber-001/api/mm/v1/subscriber/subscriber-001/micronets
    

    You should see output similar to the following:

    image291

    This will remove the micronets on the connected Micronets Gateway. If the gateway is not connected to its peer Micronets Manager, the micronets can be deleted directly on the gateway using:

    curl -s -X DELETE http://localhost:5000/micronets/v1/gateway/micronets

  2. You can verify that the micronets have been deleted by running:

    curl -s https://nccoe-server1.micronets.net/sub/subscriber-001/api/mm/v1/subscriber/subscriber-001/micronets
    

    This should return an empty micronets list.

  3. Remove the Micronets Manager docker container for a subscriber by running:

    /etc/micronets/micronets-manager.d/mm-container delete subscriber-001

    You will be prompted to remove the config file:

    The result of running the '/etc/micronets/micronets-manager.d/mm-container delete subscriber-001' command. The terminal shows the user being prompted to remove the config file.

    Lastly, you will be prompted to provide sudo privileges:

    The result of running the '/etc/micronets/micronets-manager.d/mm-container delete subscriber-001' command. The terminal shows the user being prompted enter their password.

  4. Confirm the Micronets Manager for the subscriber is removed by executing the following command:

    curl -s https://nccoe-server1.micronets.net/sub/subscriber-001/api/mm/v1/subscriber/subscriber-001
    

5 Build 4 Product Installation Guides

This section of the practice guide contains detailed instructions for installing and configuring the products used to implement Build 4. For additional details on Build 4’s logical and physical architectures, please refer to NIST SP 1800-15B.

5.1 NIST SDN Controller/MUD Manager

5.1.1 NIST SDN Controller/MUD Manager Overview

This is a limited implementation that is intended to introduce a MUD manager build on top of an SDN controller. Build 4 implements all the abstractions in the MUD specification. At testing, this build uses strictly IPv4, and DHCP is the only standardized mechanism that it supports to associate MUD URLs with devices.

Build 4 uses a MUD manager built on the OpenDaylight SDN controller. This build works with IoT devices that emit their MUD URLs through DHCP. The MUD manager works by snooping the traffic passing through the controller to detect the emission of a MUD URL. The MUD URL extracted by the MUD manager is then used to retrieve the MUD file and corresponding signature file associated with the MUD URL. The signature file is used to verify the legitimacy of the MUD file. The MUD manager then translates the access control entries in the MUD file into flow rules that are pushed to the switch.

5.1.2 Configuration Overview

The following subsections document the software, hardware, and network configurations for the Build 4 SDN controller/MUD manager.

5.1.2.1 Hardware Configuration

This build requires installing the SDN controller/MUD manager on a server with at least two gigabytes of random access memory. This server must connect to at least one SDN-capable switch or router on the network, which is the MUD policy enforcement point. The MUD manager works with any OpenFlow 1.3-enabled SDN switch. For this implementation, a Northbound Networks Zodiac WX wireless SDN access point was used as the SDN switch.

5.1.2.2 Network Configuration

The SDN controller/MUD manager instance was installed and configured on a dedicated machine leveraged for hosting virtual machines in the Build 4 lab environment. The SDN controller/MUD manager listens on port 6653 for Open vSwitch (OVS) inbound connections, which are initiated by the OVS instance running on the Northbound Networks access point.

5.1.2.3 Software Configuration

For this build, the SDN controller/MUD manager was installed on an Ubuntu 18.04.01 64-bit server.

The SDN controller/MUD manager requires the following installations and components:

  • Java SE Development Kit 8

  • Apache Maven 3.5 or higher

5.1.3 Preinstallation

Build 4’s GitHub page provides documentation that was followed to complete this section: https://github.com/usnistgov/nist-mud.

5.1.4 Setup

  1. Execute the following command to clone the Git project:

    git clone https://github.com/usnistgov/nist-mud.git

    This image shows the command "git clone https://github.com/usnistgov/nist-mud.git" being run on the MUD Manager.

  2. Copy the contents of nist-mud/maven/settings.xml to ~/.m2 by executing the commands below:

    cd nist-mud/maven/
    
    mkdir ~/.m2
    
    cp settings.xml ~/.m2
    

    This image shows the commands "cd nist-mud/maven/", "mkdir ~/.m2", and "cp settings.xml ~/.m2" being run on the MUD Manager.

  3. In the nist-mud directory, run the commands below:

    cd
    
    cd nist-mud/
    
    mvn -e clean install -nsu -Dcheckstyle.skip -DskipTests -Dmaven.javadoc.skip=true
    

    This image shows the command "mvn -e clean install -nsu -Dcheckstyle.skip -DskipTests -Dmaven.javadoc.skip=true" being run on the MUD Manager.

  4. Open port 6653 on the controller stack for TCP access so the switches can connect by executing the command below:

    sudo ufw allow 6653/tcp

    This image shows the command "sudo ufw allow 6653/tcp" being run on the MUD Manager.

  5. OpenDaylight uses port 8181 for the REST API. That port should be opened if access to the REST API is desired from outside the controller machine. Open port 8181 by executing the command below:

    sudo ufw allow 8181

    This image shows the command "sudo ufw allow 8181" being run on the MUD Manager.

  6. Change to the bin directory by executing the command below:

    ~/nist-mud/sdnmud-aggregator/karaf/target/assembly/bin

  7. Run the command below:

    ./karaf clean

    This image shows the commands "~/nist-mud/sdnmud-aggregator/karaf/target/assembly/bin" and "./karaf clean" being run on the MUD Manager.

  8. At the Karaf prompt, install MUD capabilities using:

    feature:install features-sdnmud

    This image shows the command "feature:install features-sdnmud" being run at the Karaf prompt on the MUD Manager.

  9. Check if the feature is running by using the command feature:list | grep sdnmud in Karaf.

    image301

  10. On the SDN controller/MUD manager host, run a script to configure the SDN controller and add bindings for the controller abstractions defined in the test MUD files. This script pushes configuration information for the MUD manager application (sdnmud-config.json) as well as network configuration information for the managed local area network (LAN) (controllerclass-mapping.json). The latter file specifies bindings for the controller classes that are used in the MUD file as well as subnet information for classification of local addresses. These are scoped to a single policy enforcement point, which is identified by a switch-id. By default, the switch ID is openflow:MAC-address where MAC-address is the MAC address of the switch interface that connects to the SDN controller (in decimal). This must be unique per switch. Note too, that we identify whether a switch is wireless.

    This image shows the command "python configure.py" being run on the MUD Manager.

Example Python script (configure.py):

import requests
import json
import argparse
import os

if \__name__=="__main__":
    if os.environ.get("CONTROLLER_ADDR") is None:
        print "Please set environment variable CONTROLLER_ADDR to the address of the opendaylight controller"

    controller_addr = os.environ.get("CONTROLLER_ADDR")

    headers= {"Content-Type":"application/json"}
    for (configfile,suffix) in {
        ("sdnmud-config.json", "sdnmud:sdnmud-config"),
        ("controllerclass-mapping.json","nist-mud-controllerclass-mapping:controllerclass-mapping")
    }:
        data = json.load(open(configfile))
        print "configfile", configfile
        print "suffix ", suffix
        url = "http://" + controller_addr + ":8181/restconf/config/" + suffix
        print "url ", url
        r = requests.put(url, data=json.dumps(data), headers=headers , auth=('admin', 'admin'))
        print "response ", r

Example controller class mapping (controllerclass-mapping.json):

{
    "controllerclass-mapping" : {
        "switch-id" : "openflow:123917682138002",
        "controller" : [
            {
                "uri" : "urn:ietf:params:mud:dns",
                "address-list" : [ "10.0.41.1" ]
            },
            {
                "uri" : "urn:ietf:params:mud:dhcp",
                "address-list" : [ "10.0.41.1" ]
            },
            {
                "uri" : "*https://controller.nist.local*",
                "address-list" : [ "10.0.41.225" ]
            },
            {
                "uri" : "*https://sensor.nist.local/nistmud1*",
                "address-list" : [ "10.0.41.225" ]
           }
        ],
        "local-networks": [ "10.0.41.0/24" ],
        "wireless" : true
    }
}

Example SDN MUD configuration (sdnmud-config.json):

{
    "sdnmud-config" : {
        "ca-certs": "lib/security/cacerts",
        "key-pass" : "changeit",
        "trust-self-signed-cert" : true,
        "mfg-id-rule-cache-timeout": 120,
        "relaxed-acl" : false
    }
}

5.2 MUD File Server

5.2.1 MUD File Sever Overview

The MUD file server is responsible for serving the MUD file and the corresponding signature file upon request from the MUD manager. For testing purposes, the MUD file server is run on 127.0.0.1 on the same machine as the MUD manager. This allows us to examine the logs to check if the MUD file has been retrieved. For testing purposes, host name verification for the TLS connection to the MUD file server is disabled in the configuration of the MUD manager.

5.2.2 Configuration Overview

The following subsections document the software, hardware, and network configurations for the MUD file server.

5.2.2.1 Hardware Configuration

The MUD file server was hosted on the same machine as the SDN controller.

5.2.2.2 Network Configuration

The MUD file server was hosted on the same machine as the SDN controller. To direct the MUD manager to retrieve the MUD files from the MUD file server, the host name of the two manufacturers that are present in the MUD URLs used for testing are both mapped to 127.0.0.1 in the /etc/hosts file of the Java Virtual Machine in which the MUD manager is running. This static configuration is read by the MUD manager when it starts. The name resolution information in the /etc/hosts file directs the MUD manager to retrieve the test MUD files from the MUD file server.

5.2.2.3 Software Configuration

In this build, serving MUD files requires Python 2.7 and the Python requests package. These may be installed using apt and pip. After creation of the MUD files by using mudmaker.org, the MUD files were signed, and the certificates used for signing were imported into the trust store of the Java Virtual Machine in which the MUD manager is running.

5.2.3 Setup

5.2.3.1 MUD File Creation

This build also leveraged the MUD Maker online tool found at www.mudmaker.org. For detailed instructions on creating a MUD file using this online tool, please refer to Build 1’s MUD File Creation section.

5.2.3.2 MUD File Signing

  1. Sign and import the desired MUD files. An example script (sign-and-import1.sh) can be found below.

    This image shows the command "sh sign-and-import1.sh" being run on the MUD Manager.

    The shell script that was used in this build is shown below. This script generates a signature based on the private key of a DigiCert-issued certificate and imports the certificate into the trust store of the Java Virtual Machine. This is done for both MUD files.

    CACERT=DigiCertCA.crt
    MANUFACTURER_CRT=nccoe_mud_file_signing.crt
    MANUFACTURER_KEY=mudsign.key.pem
    MANUFACTURER_ALIAS=sensor.nist.local
    MANUFACTURER_SIGNATURE=mudfile-sensor.p7s
    MUDFILE=mudfile-sensor.json
    openssl cms -sign -signer $MANUFACTURER_CRT -inkey $MANUFACTURER_KEY -in $MUDFILE -binary -noattr -outform DER -certfile $CACERT -out $MANUFACTURER_SIGNATURE
    openssl cms -verify -binary -in $MANUFACTURER_SIGNATURE -signer $MANUFACTURER_CRT -inform DER -content $MUDFILE
    MANUFACTURER_ALIAS=otherman.nist.local
    MUDFILE=mudfile-otherman.json
    MANUFACTURER_SIGNATURE=mudfile-otherman.p7s
    openssl cms -sign -signer $MANUFACTURER_CRT -inkey $MANUFACTURER_KEY -in $MUDFILE -binary -noattr -outform DER -certfile $CACERT -out $MANUFACTURER_SIGNATURE
    openssl cms -verify -binary -in $MANUFACTURER_SIGNATURE -signer $MANUFACTURER_CRT -inform DER -content $MUDFILE
    sudo -E $JAVA_HOME/bin/keytool -delete -alias digicert -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit
    sudo -E $JAVA_HOME/bin/keytool -importcert -file $CACERT -alias digicert -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit
    

5.2.3.3 MUD File Serving

Run a script that serves desired MUD files and signatures. An example Python script (mudfile-server.py) can be found below.

  1. Save a copy of the mudfile-server.py Python script onto the NIST SDN controller/MUD manager configured in Section 5.1:

    import BaseHTTPServer, SimpleHTTPServer
    import ssl
    import urlparse
    
    # Dummy manufacturer server for testing
    class MyHTTPRequestHandler(SimpleHTTPServer.SimpleHTTPRequestHandler):
    
        def do_GET(self):
            print ("DoGET " + self.path)
            self.send_response(200)
            if self.path == "/nistmud1" :
                with open("mudfile-sensor.json", mode="r") as f:
                    data = f.read()
                print("Read " + str(len(data)) + " chars ")
                self.send_header("Content-Length", len(data))
                self.end_headers()
                self.wfile.write(data)
            elif self.path == "/nistmud2" :
                with open("mudfile-otherman.json", mode="r") as f:
                    data = f.read()
                print("Read " + str(len(data)) + " chars ")
                self.send_header("Content-Length", len(data))
                self.end_headers()
                self.wfile.write(data)
            elif self.path == "/nistmud1/mudfile-sensor.p7s":
                with open("mudfile-sensor.p7s",mode="r") as f:
                    data = f.read()
                print("Read " + str(len(data)) + " chars ")
                self.send_header("Content-Length", len(data))
                self.end_headers()
                self.wfile.write(data)
            elif self.path == "/nistmud2/mudfile-otherman.p7s":
                with open("mudfile-otherman.p7s",mode="r") as f:
                    data = f.read()
                print("Read " + str(len(data)) + " chars ")
                self.send_header("Content-Length", len(data))
                self.end_headers()
                self.wfile.write(data)
            else:
                print("UNKNOWN URL!!")
                self.wfile.write(b'Hello, world!')
    
    httpd = BaseHTTPServer.HTTPServer(('0.0.0.0', 443), MyHTTPRequestHandler)
    httpd.socket = ssl.wrap_socket (httpd.socket, keyfile='./mudsigner.key', certfile='./mudsigner.crt', server_side=True)
    httpd.serve_forever()
    
  2. From the same directory as the previous step, execute the command below to start the MUD file server:

    sudo -E python mudfile-server.py

    This image shows the command "sudo -E python mudfile-server.py" being run on the MUD Manager.

5.3 Northbound Networks Zodiac WX Access Point

5.3.1 Northbound Networks Zodiac WX Access Point Overview

The Zodiac WX, in addition to being a wireless access point, includes the following logical components: an SDN switch, a NAT router, a DHCP server, and a DNS server. The Zodiac WX is powered by OpenWRT and Open vSwitch. Open vSwitch directly integrates into the wireless configuration. The Zodiac WX works with any standard OpenFlow-compatible controllers and requires no modifications because it appears to the controller as a standard OpenFlow switch.

5.3.2 Configuration Overview

The following subsections document the network, software, and hardware configurations for the SDN-capable Northbound Networks Zodiac WX.

5.3.2.1 Network Configuration

The access point is configured to have a static public address on the public side of the NAT. For purposes of testing, we use 203.0.113.x addresses on the public network. The public side of the NAT is given the address of 203.0.113.1. The DHCP server is set up to allocate addresses to wireless devices on the LAN. The SDN controller/MUD manager is connected to the public side of the NAT. The Open vSwitch configuration for the access point is given the address of the SDN controller, which is shown in the setup below.

5.3.2.2 Software Configuration

At this implementation, no additional software configuration was required.

5.3.2.3 Hardware Configuration

At this implementation, no additional hardware configuration was required.

5.3.3 Setup

On the Zodiac WX, DNSmasq supports both DHCP and DNS. For testing purposes, it will be necessary to access several web servers (two update servers called www.nist.local and an unapproved server called www.antd.local). The following commands enable the Zodiac WX to resolve the web server host names to their IP addresses.

  1. Set up the access point to resolve the addresses for the web server host names by opening the file /etc/dnsmasq.conf on the access point.

  2. Add the following line to the dnsmasq.conf file:

    addn-hosts=/etc/hosts.nist.local

    This image shows the contents of the /etc/dnsmasq.conf with "addn-hosts=/etch/hosts.nist.local" added to the file.

  3. The file /etc/hosts.nist.local has the host name to address mapping. The mapping used for our tests is shown below (Note that the host www.nist.local maps to two addresses on the public side).

    This image shows the contents of the /etc/hosts.nist.local file.

  4. On the Zodiac WX configuration web page in the System->Startup tab, indicate where (IP address and port) the Open vSwitch Daemon connects to the controller.

    This image shows a screenshot of the Northbound Networks Zodiac configuration webpage, in the Startup tab.

5.4 DigiCert Certificates

DigiCert’s CertCentral web-based platform allows provisioning and management of publicly trusted X.509 certificates for a variety of purposes. After establishing an account, clients can log in, request, renew, and revoke certificates by using only a browser. For Build 4, the Premium Certificate created in Build 1 was leveraged for signing the MUD files. To request and implement DigiCert certificates, follow the documentation in Build 1’s DigiCert Certificates section and subsequent sections.

5.5 IoT Devices

5.5.1 IoT Devices Overview

This section provides configuration details for the Linux-based Raspberry Pis used in the build, which emit MUD URLs by using DHCP.

5.5.2 Configuration Overview

The devices used in this build were multiple Raspberry Pi development kits that were configured to act as IoT devices. The devices run Raspbian 9, a Linux-based operating system, and are configured to emit a MUD URL during a typical DHCP transaction. These devices were used to test interactions related to MUD capabilities.

5.5.2.1 Network Configuration

The kits are connected to the network over a wireless connection. Their IP addresses are assigned dynamically by the DHCP server on the Zodiac WX access point.

5.5.2.2 Software Configuration

The Raspberry Pis are configured on Raspbian. They also utilized dhclient as their default DHCP clients to manually initiate a DHCP interaction. This DHCP client is provided with many Linux distributions and can be installed using a preferred package manager if not currently present. Dhclient uses a configuration file: /etc/dhclient.conf. This needs to be modified to include the MUD URL that the device will emit in its DHCP requests. (The modification details are provided in the setup information below.)

5.5.2.3 Hardware Configuration

Multiple Raspberry Pi 3 Model B devices were used.

5.5.3 Setup

Each Raspberry Pi used in this build was intended to represent a different class of device (manufacturer, other manufacturer, local networks, controller classes). The type of device was determined by the MUD URL being emitted by the device. If no MUD URL is emitted, the device is an unclassified local network device.

  1. On each Pi, changes were made to /etc/network/interfaces to add a line that allows the Pi to authenticate to the access point. The following line is added to the network interface as shown below:

    wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf.northbound

    This image shows the line "wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf.northbound" being added to the /etc/network/interfaces file.

    The file (/etc/wpa_supplicant/wpa_supplicant.conf.northbound) is shown below:

    This image shows the contents of the /etc/wpa_supplicant/wpa_supplicant.conf.northbound file.

  2. A dhclient configuration file can be altered (by adding information) to allow for emission of a MUD URL in the DHCP transaction. Modify the dhclient.conf file with the command:

    vi /etc/dhcp/dhclient.conf

  3. A send MUD URL line must be added as well as a mud-url in the request line. In this build, multiple MUD URLs were transmitted, depending on the type of the device. Example alterations made to dhclient configuration files can be seen below:

    send mud-url = "https://sensor.nist.local/nistmud1";
    
    send mud-url = "https://otherman.nist.local/nistmud2";
    

    This image shows the contents of the /etc/dhcp/dhclient.conf file.

  4. To control the time at which the MUD URL is emitted, we manually reacquire the DHCP address rather than have the device acquire the MUD URL on boot. Emit the MUD URL and attain an IP address by sending the altered dhclient configuration file manually with the following commands:

    sudo rm /var/lib/dhcp/dhclient.leases
    
    sudo ifconfig wlan0 0.0.0.0
    
    sudo dhclient -v wlan0 -cf /etc/dhcp/dhclient.conf.toaster
    

    This image shows the output of the "sudo dhclient -v wlan0 -cf /etc/dhcp/dhclient.conf.toaster" command.

5.6 Update Server

5.6.1 Update Server Overview

This section provides configuration details for the Linux-based IoT development kit used in the build, which acts as an update server. This update server will attempt to access and be accessed by the IoT device, which, in this case, is one of the development kits built in the lab. The update server is a web server that hosts mock software update files to be served as software updates to our IoT device devkits. When the server receives an http request, it sends the corresponding update file.

5.6.2 Configuration Overview

The devkit runs Raspbian 9, a Linux-based operating system, and is configured to act as an update server. This host was used to test approved internet interactions related to MUD capabilities.

5.6.2.1 Network Configuration

The web server host has a static public IP address configuration and is connected to the access point on the wired interface. It is given an address on the 203.0.113 network.

5.6.2.2 Software Configuration

The Raspberry Pi is configured on Raspbian. The devkit also utilized a simple Python script to run an http server to test MUD capabilities.

5.6.2.3 Hardware Configuration

The hardware used for this devkit includes a Raspberry Pi 3 Model B.

5.6.3 Setup

The primary configuration needed for the web server device is done with the DNS mapping on the Zodiac WX access point to be discussed in the section related to setup of the Northbound Networks Zodiac WX Access Point The Raspberry Pi is required to run a simple http server.

  1. Copy the example Python script below onto the Raspberry Pi:

    Example Python script (httpserver.py):

    import SimpleHTTPServer
    import SocketServer
    import argparse
    if __name__ == "__main__":
        parser = argparse.ArgumentParser()
        parser.add_argument("-H", help="Host address", default="0.0.0.0")
        parser.add_argument("-P", help="Port ", default="80")
        args = parser.parse_args()
        hostAddr = args.H
        PORT = int(args.P)
        Handler = SimpleHTTPServer.SimpleHTTPRequestHandler
        httpd = SocketServer.TCPServer((hostAddr, PORT), Handler)
        print "serving at port", PORT
        httpd.serve_forever()
    
  2. From the same directory as the script copied in the previous step, execute the command below to start the http server:

    sudo python httpserver.py -P 443

    This image shows the httpserver.py script being run on a Raspberry Pi by executing "sudo python httpserver.py -P 443"

5.7 Unapproved Server

5.7.1 Unapproved Server Overview

This section provides configuration details for the Linux-based IoT development kit used in the build, which acts as an unapproved internet host. This host will attempt to access and to be accessed by an IoT device, which, in this case, is one of the MUD-capable devices on the network.

The unapproved server is an internet host that is not explicitly authorized in the MUD file to communicate with the IoT device. When the IoT device attempts to connect to this server, the switch should not allow this traffic because it is not an approved internet service per the corresponding MUD file. Likewise, when the server attempts to connect to the IoT device, this traffic should be denied at the switch.

5.7.2 Configuration Overview

The devkit runs Raspbian 9, a Linux-based operating system, and is configured to act as an unapproved internet host. This host was used to test unapproved internet interactions related to MUD capabilities.

5.7.2.1 Network Configuration

The web host has a static public IP address configuration and is connected to the access point on the wired interface. It is given an address on the 203.0.113 network.

5.7.2.2 Software Configuration

The Raspberry Pi is configured on Raspbian. The devkit also utilized a simple Python script to run an http server to test MUD capabilities.

5.7.2.3 Hardware Configuration

The hardware used for this devkit includes a Raspberry Pi 3 Model B.

5.7.3 Setup

The primary configuration needed for the web server device is accomplished by the DNS mapping on the Zodiac WX access point to be discussed in the section related to setup of the Northbound Networks Zodiac WX Access Point. The Raspberry Pi is required to run a simple http server.

  1. Copy the example Python script below onto the Raspberry Pi:

    Example Python script (httpserver.py):

    import SimpleHTTPServer
    import SocketServer
    import argparse
        if __name__ == "__main__":
        parser = argparse.ArgumentParser()
        parser.add_argument("-H", help="Host address", default="0.0.0.0")
        parser.add_argument("-P", help="Port ", default="80")
        args = parser.parse_args()
        hostAddr = args.H
        PORT = int(args.P)
        Handler = SimpleHTTPServer.SimpleHTTPRequestHandler
        httpd = SocketServer.TCPServer((hostAddr, PORT), Handler)
        print "serving at port", PORT
        httpd.serve_forever()
    
  2. From the same directory as the script copied in the previous step, execute the command below to start the http server:

    sudo python httpserver.py -P 443

    This image shows the httpserver.py script being run on a Raspberry Pi by executing "sudo python httpserver.py -P 443"