One document matched: draft-lear-ietf-netmod-mud-01.xml

<?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.0.28 -->

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>

<?rfc toc="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>

<rfc ipr="trust200902" docName="draft-lear-ietf-netmod-mud-01" category="std">

  <front>
    <title abbrev="MUD YANG Model">Manufacturer Usage Description YANG Model</title>

    <author initials="E." surname="Lear" fullname="Eliot Lear">
      <organization>Cisco Systems</organization>
      <address>
        <postal>
          <street>Richtistrasse 7</street>
          <city>Wallisellen</city>
          <code>CH-8304</code>
          <country>Switzerland</country>
        </postal>
        <phone>+41 44 878 9200</phone>
        <email>lear@cisco.com</email>
      </address>
    </author>

    <date year="2016" month="March" day="04"/>

    
    
    <keyword>Internet-Draft</keyword>

    <abstract>


<t>This memo specifies a YANG model to be used to generate and parse
manufacturer usage descriptions.  These descriptions are retrieved by
network management systems in order to instantiate policies associated
with those devices.  This memo also specifies a well known URI suffix
to indicate that a file contains XML derived from this model.</t>



    </abstract>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>Manufacturer Usage Descriptions (MUDs) provide advice to end networks
on how to treat specific classes of devices.  The MUD architecture is
explained in <xref target="I-D.lear-mud-framework"/>.  The files that are retrieved
are intended to be closely aligned to existing network architectures
so that they are easy to deploy.  We make use of YANG <xref target="RFC6020"/> and
XML because many network vendors have focused their network management
efforts through this interface.</t>

<t>The YANG model specified here is an extension of
<xref target="I-D.ietf-netmod-acl-model"/>.  The extensions in this model allow for
a manufacturer to express classes of systems that a manufacturer would
find necessary for the proper function of the device.  These classes
are then instantiated into actual IP addresses through local
processing.</t>

<t>Because manufacturers do not know who will be using their devices, it
is important for functionality referenced in usage descriptions to be
relatively ubiquitous, and therefore, mature.  Therefore, only a
limited subset of NETCONF-like content is permitted.</t>

<t>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”,  “MAY”, and
“OPTIONAL” in this document are to be interpreted as described in
<xref target="RFC2119"/>.</t>

</section>
<section anchor="the-mud-model-and-semantic-meaning" title="The MUD Model and Semantic Meaning">
<t>A MUD file consists of XML based on a YANG model.  For purposes of
MUD, the elements that can be modified are access lists as augmented
by this model.  Publishers of MUD files MUST NOT include elements that
are not stated in either this memo or by <xref target="I-D.ietf-netmod-acl-model"/>.</t>

<t>This module is structured into four parts.  The first container holds
information that is relevant to retrieval and validity of the MUD file
itself.   The second container augments the matching container of the
ACL model to add several elements that are relevant to the MUD URI, or
other otherwise abstracted for use within a local environment.  The
third container augments actions to add quality of service treatment.
Finally, an additional container provides for some meta-information
relating to why a rule might be in place.</t>

<figure><artwork><![CDATA[
  module: ietf-mud
   +--rw support-information
      +--rw last-update?      yang:date-and-time
      +--rw cache-validity?   uint32
      +--rw masa-server?      inet:uri
      +--rw is-supported?     boolean
  augment /acl:access-lists/acl:acl/acl:access-list-entries
          /acl:ace/acl:matches:
   +--rw manufacturer?        inet:host
   +--rw same-manufacturer?   boolean
   +--rw model?               string
   +--rw local-networks?      empty
   +--rw controller?          inet:uri
]]></artwork></figure>

</section>
<section anchor="element-definitions" title="Element Definitions">

<t>The following elements are defined.</t>

<section anchor="last-update" title="last-update">
<t>This is a date-and-time value of the last time the XML file was
updated.  This is akin to a version number.</t>

</section>
<section anchor="cache-validity" title="cache-validity">
<t>This uint32 is the period of time in hours that a network management
station MUST wait since its last retrieval before checking for an
update.  It is RECOMMENDED that this value be no less than 24 and no
more than 144 for any device that is supported.</t>

</section>
<section anchor="masa-server" title="masa-server">
<t>This optional element refers to the URI that should be used to
resolve the location any MASA service, as specified in
<xref target="I-D.ietf-anima-bootstrapping-keyinfra"/>.</t>

</section>
<section anchor="is-supported" title="is-supported">
<t>This boolean is an indication from the manufacturer to the network
administrator as to whether or not the device is supported.  In this
context a device is said to be supported if the manufacturer might
issue an update to the device or if the manufacturer might update the
MUD file.</t>

</section>
<section anchor="manufacturer" title="manufacturer">
<t>This element consists of a hostname that would be matched against the
authority section of another device’s MUD URI.</t>

</section>
<section anchor="same-manufacturer" title="same-manufacturer">
<t>This is a boolean equivalent for when the manufacturer element is used
to indicate the authority that is found in another device’s MUD URI
matches that of the authority found in this device’s MUD URI.</t>

</section>
<section anchor="model" title="model">
<t>This string matches the one and only segment following the
authority section of the MUD URI.  It refers to a model that is unique
within the context of the authority.  It may also include product
version information.  Thus how this field is constructed is entirely a
local matter for the manufacturer.</t>

</section>
<section anchor="local-networks" title="local-networks">
<t>This null-valued element expands to include local networks.  Its
default expansion is that packets must not traverse toward a default
route that is received from the router.</t>

</section>
<section anchor="controller" title="controller">
<t>This URI specifies a value that a controller will register with the
network management station.  The element then is expanded to the set
of hosts that are so registered.</t>

<t>In addition, some meta information is defined in order to determine
when a usage description should be refreshed.  Finally, the class of a
device may be specified, such that a generic policy for a given class
may be applied.</t>

<t>An example of an intended MUD policy for a lightbulb might be as follows:</t>

<figure><artwork><![CDATA[
   Allow access to controller "https://mfg.example.com/example-printers"
   Allow access to local DNS/DHCP
   Deny all other access
]]></artwork></figure>

</section>
</section>
<section anchor="what-does-a-mud-uri-look-like" title="What does a MUD URI look like?">

<t>To begin with, MUD takes full advantage of both the https: scheme and
the use of .well-known.  HTTPS is important in this case because men
in the middle could otherwise harm the operation of a class of
devices.  .well-known is used because we wish to add additional
structure to the URI.  And so the URI appears as follows:</t>

<figure><artwork><![CDATA[
   mud-uri   = "https://" authority  "/.well-known/mud/" mud-rev
               "/" model "/" dev-rev *( "?" extras )
	       ; authority is from RFC3986
   mud-rev   = "v1"
   model     = segment  ; from RFC3986
   dev-rev   = segment  ; from RFC3986
   extras    = query    ; from RFC3986
   
]]></artwork></figure>

<t>mud-rev signifies the version of the manufacturer usage description
file.  This memo specifies “v1” of that file.  It should be pointout
that later versions may not use XML at all.</t>

<t>“model” represents a device model as the manufacturer wishes to
represent it.  It could be a brand name or something more specific.
“dev-rev” provides a means to indicate what version the product is.
Specifically if it has been updated in the field, this is the place
where evidence of that update would appear.  Once again, the field is
opaque.  From a controller standpoint, therefore, only comparison and
matching operations are safe.  Processing of this URI occurs as
specified in <xref target="RFC2818"/> and <xref target="RFC3986"/>.</t>

</section>
<section anchor="the-mud-yang-model" title="The MUD YANG Model">

<figure><artwork><![CDATA[
<CODE BEGINS>file "ietf-mud.yang";

module ietf-mud {
  yang-version 1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-mud";
  prefix "ietf-mud";
  
  
  import ietf-access-control-list {
    prefix "acl";
  }

  import ietf-yang-types 
  {
    prefix "yang";
  }
  
  import ietf-inet-types
  {
    prefix "inet";
  }
  
  organization
    "Cisco Systems, Inc.";

  contact
    "Eliot Lear
     lear@cisco.com
    ";

  description
    "This YANG module defines a component that augments the
     IETF description of an access list.  This specific module
     focuses on additional filters that include local, model,
     and same-manufacturer.
    Copyright (c) 2015 IETF Trust and the persons identified as
    the document authors.  All rights reserved.
    Redistribution and use in source and binary forms, with or
    without modification, is permitted pursuant to, and subject
    to the license terms contained in, the Simplified BSD
    License set forth in Section 4.c of the IETF Trust's Legal
    Provisions Relating to IETF Documents
    (http://trustee.ietf.org/license-info).
    This version of this YANG module is part of RFC XXXX; see
    the RFC itself for full legal notices.";

  revision "2015-12-15"  {
    description "A policy container for manufacturer-driven policy";
    reference "RFC XXXX";
  }


  container support-information 
  {
    
    description "Information about when support end(ed), and
                 when to refresh";
    
    leaf last-update 
    {
      type yang:date-and-time;
      description "This is intended to be the time and date that
                   the MUD file was generated.";
    }

    leaf cache-validity
    {
      type uint32;
      description "The information retrieved from the MUD server is
                 valid for these many hours, after which it should
                 be refreshed.";
    }

    leaf masa-server {
      type inet:uri;
      description "The URI of the MASA server that network
      elements should forward requests to for this device.";
    }      

    leaf is-supported 
    {
      type boolean;
      description "The element is currently supported
                   by the manufacturer.";
    }
  }
  

  augment "/acl:access-lists/acl:acl/" +
     "acl:access-list-entries/acl:ace/" +
     "acl:matches" {
    description "adding manufacturer-driven policy";

    leaf manufacturer 
    {
      type inet:host;
      description "authority component of the manufacturer URI";
    }

    leaf same-manufacturer 
    {
      type boolean;
      description "expand to ACEs for each device
      		   with the same origin";
    }

    leaf model 
      {
	type string;
	description "specific model for a given manufacturer";
      }

    leaf local-networks {
      type empty;
      description "this string is used to indicate networks
                   considered local in a given environment.";
    }
    leaf controller {
      type inet:uri;
      description "expands to one or more controllers for a
                   given service that is codified by inet:uri.";
    }              
  }
} 

<CODE ENDS>
]]></artwork></figure>

</section>
<section anchor="example" title="Example">
<t>The example below permits access to devices that are registered with
the MUD system of type “http://mfg.example.com/printers”.  It denies
all other access.</t>

<figure><artwork><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
  <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <access-lists
   xmlns="urn:ietf:params:xml:ns:yang:ietf-access-control-list"
   xmlns:ietf-acl-dnsname="urn:ietf:params:xml:ns:yang:ietf-mud">
       <acl>
        <access-list-entries>
          <ace>
            <matches>
	      <controller>
	         http://mfg.example.com/printers
	      </controller>
            </matches>
            <actions>
              <permit />
            </actions>
            <rule-name>rule1<rule-name/>
          </ace>
        </access-list-entries>
        <acl-name>sample-mud-acl<acl-name/>
        <acl-type>ipv4-acl<acl-type/>
      </acl>
    </access-lists>
  </data>
]]></artwork></figure>

</section>
<section anchor="security-considerations" title="Security Considerations">
<t>Based on the means a URI is procurred, a device may be able to lie
about what it is, thus gaining additional network access.  This will
occur when it makes use of primitives such as “manufacturer” for the
purpose of accessing devices of a particular type.  Depending on the
sophistication of the attack it will be easier or harder to detect.
Network management systems SHOULD NOT deploy a usage description for a
a device with the same MAC address that has indicated a change of
authority without some additional validation (such as review of the
class).  New devices that present some form of unauthenticated MUD URI
SHOULD be validated by some external means when they would be
otherwise be given increased network access.</t>

<t>It may be possible for a rogue manufacturer to inappropriately
exercise the MUD file parser, in order to exploit a vulnerability.
There are two recommended approaches to address this threat.  The
first is to have a system do a primary scan of the file to ensure that
it is both parseable and believable at some level.  MUD files will
likely be relatively small, to start with.  The number of ACEs used by
any given device should be relatively small as well.  Second, it may
be useful to limit retrieval of MUD URIs to only those sites that are
known to have decent web reputations.</t>

</section>
<section anchor="iana-considerations" title="IANA Considerations">

<t>This memo will make a request of IANA for the URI suffix of “.mud”.
Specification to follow.</t>

</section>
<section anchor="acknowledgments" title="Acknowledgments">
<t>The author would like to thank Einar Nilsen-Nygaard for his valuable
advice.  The numerous remaining errors in this work are entirely the
responsibility of the author.</t>

</section>


  </middle>

  <back>

    <references title='Normative References'>





<reference  anchor='RFC2119' target='http://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>



<reference  anchor='RFC3986' target='http://www.rfc-editor.org/info/rfc3986'>
<front>
<title>Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials='T.' surname='Berners-Lee' fullname='T. Berners-Lee'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<author initials='L.' surname='Masinter' fullname='L. Masinter'><organization /></author>
<date year='2005' month='January' />
<abstract><t>A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.  This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet.  The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier.  This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='STD' value='66'/>
<seriesInfo name='RFC' value='3986'/>
<seriesInfo name='DOI' value='10.17487/RFC3986'/>
</reference>



<reference  anchor='RFC6020' target='http://www.rfc-editor.org/info/rfc6020'>
<front>
<title>YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)</title>
<author initials='M.' surname='Bjorklund' fullname='M. Bjorklund' role='editor'><organization /></author>
<date year='2010' month='October' />
<abstract><t>YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='6020'/>
<seriesInfo name='DOI' value='10.17487/RFC6020'/>
</reference>



<reference anchor='I-D.ietf-netmod-acl-model'>
<front>
<title>Network Access Control List (ACL) YANG Data Model</title>

<author initials='D' surname='Bogdanovic' fullname='Dean Bogdanovic'>
    <organization />
</author>

<author initials='K' surname='Koushik' fullname='Kiran Koushik'>
    <organization />
</author>

<author initials='L' surname='Huang' fullname='Lisa Huang'>
    <organization />
</author>

<author initials='D' surname='Blair' fullname='Dana Blair'>
    <organization />
</author>

<date month='December' day='9' year='2015' />

<abstract><t>This document describes a data model of Access Control List (ACL) basic building blocks.</t></abstract>

</front>

<seriesInfo name='Internet-Draft' value='draft-ietf-netmod-acl-model-06' />
<format type='TXT'
        target='http://www.ietf.org/internet-drafts/draft-ietf-netmod-acl-model-06.txt' />
</reference>



<reference anchor='I-D.ietf-anima-bootstrapping-keyinfra'>
<front>
<title>Bootstrapping Key Infrastructures</title>

<author initials='M' surname='Pritikin' fullname='Max Pritikin'>
    <organization />
</author>

<author initials='M' surname='Richardson' fullname='Michael Richardson'>
    <organization />
</author>

<author initials='M' surname='Behringer' fullname='Michael Behringer'>
    <organization />
</author>

<author initials='S' surname='Bjarnason' fullname='Steinthor Bjarnason'>
    <organization />
</author>

<date month='October' day='19' year='2015' />

<abstract><t>This document specifies automated bootstrapping of an key infrastructure using vendor installed IEEE 802.1AR manufacturing installed certificates, in combination with a vendor based service on the Internet.  Before being authenticated, a new device has only link-local connectivity, and does not require a routable address. When a vendor provides an Internet based service, devices can be forced to join only specific domains but in limited/disconnected networks or legacy environments we describe a variety of options that allow bootstrapping to proceed.</t></abstract>

</front>

<seriesInfo name='Internet-Draft' value='draft-ietf-anima-bootstrapping-keyinfra-01' />
<format type='TXT'
        target='http://www.ietf.org/internet-drafts/draft-ietf-anima-bootstrapping-keyinfra-01.txt' />
</reference>



<reference  anchor='RFC2818' target='http://www.rfc-editor.org/info/rfc2818'>
<front>
<title>HTTP Over TLS</title>
<author initials='E.' surname='Rescorla' fullname='E. Rescorla'><organization /></author>
<date year='2000' month='May' />
<abstract><t>This memo describes how to use Transport Layer Security (TLS) to secure Hypertext Transfer Protocol (HTTP) connections over the Internet.  This memo provides information for the Internet community.</t></abstract>
</front>
<seriesInfo name='RFC' value='2818'/>
<seriesInfo name='DOI' value='10.17487/RFC2818'/>
</reference>




    </references>

    <references title='Informative References'>





<reference anchor='I-D.lear-mud-framework'>
<front>
<title>Manufacturer Usage Description Framework</title>

<author initials='E' surname='Lear' fullname='Eliot Lear'>
    <organization />
</author>

<date month='January' day='21' year='2016' />

<abstract><t>A key presumption of the Internet architecture has been that devices are general purpose computers.  By constraining the set of devices that connect to the Internet to non-general purpose devices, we can introduce a set of network capabilities that provides an additional layer of protection to those devices.  One such capability is the Manufacturer Usage Description (MUD).  This work builds on many existing network capabilities so as to be easily deployable by all involved.  The focus of this work is primarily, but not exclusively, in the realm of security; and again primarily, but not exclusively, relating to smart objects.</t></abstract>

</front>

<seriesInfo name='Internet-Draft' value='draft-lear-mud-framework-00' />
<format type='TXT'
        target='http://www.ietf.org/internet-drafts/draft-lear-mud-framework-00.txt' />
</reference>




    </references>



  </back>
</rfc>