Tech-invite   3GPPspecs   Glossaries   IETFRFCs   Groups   SIP   ABNFs   Ti+   Search in Tech-invite

in Index   Prev   Next
in Index   Prev   Next  Group: OPSAWG

RFC 8520

Manufacturer Usage Description Specification

Pages: 60
Proposed STD
Errata
Part 2 of 4 – Pages 15 to 29
First   Prev   Next

Top   ToC   Page 15   prevText
3.  MUD Model Definitions for the Root "mud" Container

3.1.  mud-version

   This node specifies the integer version of the MUD specification.
   This memo specifies version 1.

3.2.  MUD URL

   This URL identifies the MUD file.  This is useful when the file and
   associated signature are manually uploaded, say, in an offline mode.
Top   ToC   Page 16
3.3.  to-device-policy and from-device-policy Containers

   [RFC8519] describes access lists.  In the case of MUD, a MUD file
   must be explicit in describing the communication pattern of a Thing,
   and that includes indicating what is to be permitted or denied in
   either direction of communication.  Hence, each of these containers
   indicates the appropriate direction of a flow in association with a
   particular Thing.  They contain references to specific access lists.

3.4.  last-update

   This is a date-and-time value of when the MUD file was generated.
   This is akin to a version number.  Its form is taken from [RFC6991].

3.5.  cache-validity

   This uint8 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 it
   MUST NOT be more than 168 for any Thing that is supported.  This
   period SHOULD be no shorter than any period determined through HTTP
   caching directives (e.g., "cache-control" or "Expires").  N.B., the
   expiring of this timer does not require the MUD manager to discard
   the MUD file, nor terminate access to a Thing.  See Section 16 for
   more information.

3.6.  is-supported

   This boolean is an indication from the manufacturer to the network
   administrator as to whether or not the Thing is supported.  In this
   context, a Thing is said to not be supported if the manufacturer
   intends never to issue a firmware or software update to the Thing or
   never to update the MUD file.  A MUD manager MAY still periodically
   check for updates.

3.7.  systeminfo

   This is a textual UTF-8 description of the Thing to be connected.
   The intent is for administrators to be able to see a brief
   displayable description of the Thing.  It SHOULD NOT exceed 60
   characters worth of display space.
Top   ToC   Page 17
3.8.  mfg-name, software-rev, model-name, and firmware-rev

   These optional fields are filled in as specified by [RFC8348].  Note
   that firmware-rev and software-rev MUST NOT be populated in a MUD
   file if the device can be upgraded but the MUD URL cannot be.  This
   would be the case, for instance, with MUD URLs that are contained in
   802.1AR certificates.

3.9.  extensions

   This optional leaf-list names MUD extensions that are used in the MUD
   file.  Note that MUD extensions MUST NOT be used in a MUD file
   without the extensions being declared.  Implementations MUST ignore
   any node in this file that they do not understand.

   Note that extensions can either extend the MUD file as described in
   the previous paragraph or reference other work.  An extension example
   can be found in Appendix B.

4.  Augmentation to the ACL Model

   Note that in this section, when we use the term "match", we are
   referring to the ACL model "matches" node.

4.1.  manufacturer

   This node consists of a hostname that would be matched against the
   authority component of another Thing's MUD URL.  In its simplest
   form, "manufacturer" and "same-manufacturer" may be implemented as
   access lists.  In more complex forms, additional network capabilities
   may be used.  For example, if one saw the line "manufacturer" :
   "flobbidy.example.com", then all Things that registered with a MUD
   URL that contained flobbity.example.com in its authority section
   would match.

4.2.  same-manufacturer

   This null-valued node is an equivalent for when the manufacturer
   element is used to indicate that the authority found in another
   Thing's MUD URL matches that of the authority found in this Thing's
   MUD URL.  For example, if the Thing's MUD URL were
   "https://b1.example.com/ThingV1", then all devices that had a MUD URL
   with an authority section of b1.example.com would match.
Top   ToC   Page 18
4.3.  documentation

   This URI consists of a URL that points to documentation relating to
   the device and the MUD file.  This can prove particularly useful when
   the "controller" class is used, so that its use can be explained.

4.4.  model

   This string matches the entire MUD URL, thus covering the model that
   is unique within the context of the authority.  It may contain not
   only model information, but versioning information as well, and any
   other information that the manufacturer wishes to add.  The intended
   use is for devices of this precise class to match, to permit or deny
   communication between one another.

4.5.  local-networks

   This null-valued node expands to include local networks.  Its default
   expansion is that packets must not traverse toward a default route
   that is received from the router.  However, administrators may expand
   the expression as is appropriate in their deployments.

4.6.  controller

   This URI specifies a value that a controller will register with the
   MUD manager.  The node then is expanded to the set of hosts that are
   so registered.  This node may also be a URN.  In this case, the URN
   describes a well-known service, such as DNS or NTP, that has been
   standardized.  Both of those URNs may be found in Section 17.7.

   When "my-controller" is used, it is possible that the administrator
   will be prompted to populate that class for each and every model.
   Use of "controller" with a named class allows the user to populate
   that class only once for many different models that a manufacturer
   may produce.

   Controller URIs MAY take the form of a URL (e.g., "http[s]://").
   However, MUD managers MUST NOT resolve and retrieve such files, and
   it is RECOMMENDED that there be no such file at this time, as their
   form and function may be defined at a point in the future.  For now,
   URLs should serve simply as class names and may be populated by the
   local deployment administrator.

   Great care should be taken by MUD managers when invoking the
   controller class in the form of URLs.  For one thing, it requires
   some understanding by the administrator as to when it is appropriate.
Top   ToC   Page 19
   Pre-registration in such classes by controllers with the MUD server
   is encouraged.  The mechanism to do that is beyond the scope of this
   work.

4.7.  my-controller

   This null-valued node signals to the MUD manager to use whatever
   mapping it has for this MUD URL to a particular group of hosts.  This
   may require prompting the administrator for class members.  Future
   work should seek to automate membership management.

4.8.  direction-initiated

   This MUST only be applied to TCP.  This matches the direction in
   which a TCP connection is initiated.  When the direction initiated is
   "from-device", packets that are transmitted in the direction of a
   Thing MUST be dropped unless the Thing has first initiated a TCP
   connection.  By way of example, this node may be implemented in its
   simplest form by looking at naked SYN bits, but it may also be
   implemented through more stateful mechanisms.

   When applied, this matches packets when the flow was initiated in the
   corresponding direction.  [RFC6092] specifies IPv6 guidance best
   practices.  While that document is scoped specifically to IPv6, its
   contents are applicable for IPv4 as well.

5.  Processing of the MUD File

   To keep things relatively simple in addition to whatever definitions
   exist, we also apply two additional default behaviors:

   o  Anything not explicitly permitted is denied.

   o  Local DNS and NTP are, by default, permitted to and from the
      Thing.

   An explicit description of the defaults can be found in Appendix A.
   These are applied AFTER all other explicit rules.  Thus, a default
   behavior can be changed with a "drop" action.

6.  What Does a MUD URL Look Like?

   MUD URLs are required to use the "https" scheme, in order to
   establish the MUD file server's identity and assure integrity of the
   MUD file.
Top   ToC   Page 20
   Any "https://" URL can be a MUD URL.  For example:

     https://things.example.org/product_abc123/v5
     https://www.example.net/mudfiles/temperature_sensor/
     https://example.com/lightbulbs/colour/v1

   A manufacturer may construct a MUD URL in any way, so long as it
   makes use of the "https" scheme.

7.  The MUD YANG Model

   <CODE BEGINS>file "ietf-mud@2019-01-28.yang"
   module ietf-mud {
     yang-version 1.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
       "IETF OPSAWG (Operations and Management Area Working Group)";
     contact
       "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
        WG List: opsawg@ietf.org

        Author: Eliot Lear
                lear@cisco.com

        Author: Ralph Droms
                rdroms@gmail.com

        Author: Dan Romascanu
                dromasca@gmail.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.
Top   ToC   Page 21
        This module is intended to be serialized via JSON and stored
        as a file, as described in RFC 8520.

        The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
        NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
        'MAY', and 'OPTIONAL' in this document are to be interpreted as
        described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
        they appear in all capitals, as shown here.

        Copyright (c) 2019 IETF Trust and the persons identified as
        authors of the code.  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 8520; see
        the RFC itself for full legal notices.";

     revision 2019-01-28 {
       description
         "Initial proposed standard.";
       reference
         "RFC 8520: Manufacturer Usage Description
          Specification";
     }

     typedef direction {
       type enumeration {
         enum to-device {
           description
             "packets or flows destined to the target
              Thing.";
         }
         enum from-device {
           description
             "packets or flows destined from
              the target Thing.";
         }
       }
       description
         "Which way are we talking about?";
     }

     container mud {
Top   ToC   Page 22
       presence "Enabled for this particular MUD URL";
       description
         "MUD-related information, as specified
          by RFC 8520.";
       uses mud-grouping;
     }

     grouping mud-grouping {
       description
         "Information about when support ends (or ended)
          and when to refresh.";
       leaf mud-version {
         type uint8;
         mandatory true;
         description
           "This is the version of the MUD
            specification.  This memo specifies version 1.";
       }
       leaf mud-url {
         type inet:uri;
         mandatory true;
         description
           "This is the MUD URL associated with the entry found
            in a MUD file.";
       }
       leaf last-update {
         type yang:date-and-time;
         mandatory true;
         description
           "This is intended to be when the current MUD file
            was generated.  MUD managers SHOULD NOT check
            for updates between this time plus cache validity.";
       }
       leaf mud-signature {
         type inet:uri;
         description
           "A URI that resolves to a signature as
            described in this specification.";
       }
       leaf cache-validity {
         type uint8 {
           range "1..168";
         }
         units "hours";
         default "48";
         description
           "The information retrieved from the MUD server is
            valid for these many hours, after which it should
Top   ToC   Page 23
            be refreshed.  N.B., MUD manager implementations
            need not discard MUD files beyond this period.";
       }
       leaf is-supported {
         type boolean;
         mandatory true;
         description
           "This boolean indicates whether or not the Thing is
            currently supported by the manufacturer.";
       }
       leaf systeminfo {
         type string;
         description
           "A UTF-8 description of this Thing.  This
            should be a brief description that may be
            displayed to the user to determine whether
            to allow the Thing on the
            network.";
       }
       leaf mfg-name {
         type string;
         description
           "Manufacturer name, as described in
            the ietf-hardware YANG module.";
       }
       leaf model-name {
         type string;
         description
           "Model name, as described in the
            ietf-hardware YANG module.";
       }
       leaf firmware-rev {
         type string;
         description
           "firmware-rev, as described in the
            ietf-hardware YANG module.  Note that this field
            MUST NOT be included when the device can be
            updated but the MUD URL cannot.";
       }
       leaf software-rev {
         type string;
         description
           "software-rev, as described in the
            ietf-hardware YANG module.  Note that this field
            MUST NOT be included when the device can be
            updated but the MUD URL cannot.";
       }
       leaf documentation {
Top   ToC   Page 24
         type inet:uri;
         description
           "This URL points to documentation that
            relates to this device and any classes that it uses
            in its MUD file.  A caution: MUD managers need
            not resolve this URL on their own but rather simply
            provide it to the administrator.  Parsing HTML is
            not an intended function of a MUD manager.";
       }
       leaf-list extensions {
         type string {
           length "1..40";
         }
         description
           "A list of extension names that are used in this MUD
            file.  Each name is registered with the IANA and
            described in an RFC.";
       }
       container from-device-policy {
         description
           "The policies that should be enforced on traffic
            coming from the device.  These policies are not
            necessarily intended to be enforced at a single
            point but may be rendered by the controller to any
            relevant enforcement points in the network or
            elsewhere.";
         uses access-lists;
       }
       container to-device-policy {
         description
           "The policies that should be enforced on traffic
            going to the device.  These policies are not
            necessarily intended to be enforced at a single
            point but may be rendered by the controller to any
            relevant enforcement points in the network or
            elsewhere.";
         uses access-lists;
       }
     }

     grouping access-lists {
       description
         "A grouping for access lists in the context of device
          policy.";
       container access-lists {
         description
           "The access lists that should be applied to traffic
            to or from the device.";
Top   ToC   Page 25
         list access-list {
           key "name";
           description
             "Each entry on this list refers to an ACL that
              should be present in the overall access list
              data model.  Each ACL is identified by name and
              type.";
           leaf name {
             type leafref {
               path "/acl:acls/acl:acl/acl:name";
             }
             description
               "The name of the ACL for this entry.";
           }
         }
       }
     }

     augment "/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches" {
       description
         "adding abstractions to avoid the need of IP addresses.";
       container mud {
         description
           "MUD-specific matches.";
         leaf manufacturer {
           type inet:host;
           description
             "A domain that is intended to match the authority
              section of the MUD URL.  This node is used to specify
              one or more manufacturers a device should
              be authorized to access.";
         }
         leaf same-manufacturer {
           type empty;
           description
             "This node matches the authority section of the MUD URL
              of a Thing.  It is intended to grant access to all
              devices with the same authority section.";
         }
         leaf model {
           type inet:uri;
           description
             "Devices of the specified model type will match if
              they have an identical MUD URL.";
         }
         leaf local-networks {
           type empty;
           description
Top   ToC   Page 26
             "IP addresses will match this node if they are
              considered local addresses.  A local address may be
              a list of locally defined prefixes and masks
              that indicate a particular administrative scope.";
         }
         leaf controller {
           type inet:uri;
           description
             "This node names a class that has associated with it
              zero or more IP addresses to match against.  These
              may be scoped to a manufacturer or via a standard
              URN.";
         }
         leaf my-controller {
           type empty;
           description
             "This node matches one or more network elements that
              have been configured to be the controller for this
              Thing, based on its MUD URL.";
         }
       }
     }
     augment "/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches"
           + "/acl:l4/acl:tcp/acl:tcp" {
       description
         "add direction-initiated";
       leaf direction-initiated {
         type direction;
         description
           "This node matches based on which direction a
            connection was initiated.  The means by which that
            is determined is discussed in this document.";
       }
     }
   }
   <CODE ENDS>

8.  The Domain Name Extension to the ACL Model

   This module specifies an extension to the IETF-ACL model such that
   domain names may be referenced by augmenting the "matches" node.
   Different implementations may deploy differing methods to maintain
   the mapping between the IP address and domain name, if indeed any are
   needed.  However, the intent is that resources that are referred to
   using a name should be authorized (or not) within an access list.
Top   ToC   Page 27
   The structure of the change is as follows:

   module: ietf-acldns
     augment /acl:acls/acl:acl/acl:aces/acl:ace/
       acl:matches/acl:l3/acl:ipv4/acl:ipv4:
       +--rw src-dnsname?   inet:host
       +--rw dst-dnsname?   inet:host
     augment /acl:acls/acl:acl/acl:aces/acl:ace/
       acl:matches/acl:l3/acl:ipv6/acl:ipv6:
       +--rw src-dnsname?   inet:host
       +--rw dst-dnsname?   inet:host

   The choice of these particular points in the access control list
   model is based on the assumption that we are in some way referring to
   IP-related resources, as that is what the DNS returns.  A domain name
   in our context is defined in [RFC6991].  The augmentations are
   replicated across IPv4 and IPv6 to allow MUD file authors the ability
   to control the IP version that the Thing may utilize.

   The following nodes are defined.

8.1.  src-dnsname

   The argument corresponds to a domain name of a source as specified by
   inet:host.  A number of means may be used to resolve hosts.  What is
   important is that such resolutions be consistent with ACLs that are
   required by Things to properly operate.

8.2.  dst-dnsname

   The argument corresponds to a domain name of a destination as
   specified by inet:host.  See the previous section (Section 8.1)
   relating to resolution.

   Note that when using either of these with a MUD file, because access
   is associated with a particular Thing, MUD files MUST NOT contain
   either a src-dnsname in an ACL associated with from-device-policy or
   a dst-dnsname associated with to-device-policy.
Top   ToC   Page 28
8.3.  The ietf-acldns Model

   <CODE BEGINS>file "ietf-acldns@2019-01-28.yang"
   module ietf-acldns {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-acldns";
     prefix ietf-acldns;

     import ietf-access-control-list {
       prefix acl;
     }
     import ietf-inet-types {
       prefix inet;
     }

     organization
       "IETF OPSAWG (Operations and Management Area Working Group)";
     contact
       "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
        WG List: opsawg@ietf.org

        Author: Eliot Lear
                lear@cisco.com

        Author: Ralph Droms
                rdroms@gmail.com

        Author: Dan Romascanu
                dromasca@gmail.com
       ";
     description
       "This YANG module defines a component that augments the
        IETF description of an access list to allow DNS names
        as matching criteria.

        Copyright (c) 2019 IETF Trust and the persons identified as
        authors of the code.  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).";

     revision 2019-01-28 {
       description
         "Base version of dnsname extension of the ACL model.";
Top   ToC   Page 29
       reference
         "RFC 8520: Manufacturer Usage Description
          Specification";
     }

     grouping dns-matches {
       description
         "Domain names for matching.";
       leaf src-dnsname {
         type inet:host;
         description
           "domain name to be matched against.";
       }
       leaf dst-dnsname {
         type inet:host;
         description
           "domain name to be matched against.";
       }
     }

     augment "/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches"
           + "/acl:l3/acl:ipv4/acl:ipv4" {
       description
         "Adding domain names to matching.";
       uses dns-matches;
     }
     augment "/acl:acls/acl:acl/acl:aces/acl:ace/acl:matches"
           + "/acl:l3/acl:ipv6/acl:ipv6" {
       description
         "Adding domain names to matching.";
       uses dns-matches;
     }
   }
   <CODE ENDS>


Next Section