Tech-invite   3GPPspecs   RFCs   SIP   Search in Tech-invite

in Index   Prev   Next
in Index   Prev   Next  Group: NETCONF

RFC 8341

Network Configuration Access Control Model

Pages: 58
STD 91
Obsoletes:  6536
Part 3 of 3 – Pages 31 to 58
First   Prev   None

Top   ToC   RFC8341 - Page 31   prevText
3.5.  Data Model Definitions

3.5.1.  Data Organization

   The following diagram highlights the contents and structure of the
   NACM YANG module.

   module: ietf-netconf-acm
     +--rw nacm
        +--rw enable-nacm?              boolean
        +--rw read-default?             action-type
        +--rw write-default?            action-type
        +--rw exec-default?             action-type
        +--rw enable-external-groups?   boolean
        +--ro denied-operations         yang:zero-based-counter32
        +--ro denied-data-writes        yang:zero-based-counter32
        +--ro denied-notifications      yang:zero-based-counter32
        +--rw groups
        |  +--rw group* [name]
        |     +--rw name         group-name-type
        |     +--rw user-name*   user-name-type
        +--rw rule-list* [name]
           +--rw name     string
           +--rw group*   union
           +--rw rule* [name]
              +--rw name                 string
              +--rw module-name?         union
              +--rw (rule-type)?
              |  +--:(protocol-operation)
              |  |  +--rw rpc-name?            union
              |  +--:(notification)
              |  |  +--rw notification-name?   union
              |  +--:(data-node)
              |     +--rw path                 node-instance-identifier
              +--rw access-operations?   union
              +--rw action               action-type
              +--rw comment?             string
Top   ToC   RFC8341 - Page 32
3.5.2.  YANG Module

   The following YANG module specifies the normative NETCONF content
   that MUST be supported by the server.

   The "ietf-netconf-acm" YANG module imports typedefs from [RFC6991].

   <CODE BEGINS> file "ietf-netconf-acm@2018-02-14.yang"
   module ietf-netconf-acm {

     namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-acm";

     prefix nacm;

     import ietf-yang-types {
       prefix yang;
     }

     organization
       "IETF NETCONF (Network Configuration) Working Group";

     contact
       "WG Web:   <https://datatracker.ietf.org/wg/netconf/>
        WG List:  <mailto:netconf@ietf.org>

        Author:   Andy Bierman
                  <mailto:andy@yumaworks.com>

        Author:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>";

     description
       "Network Configuration Access Control Model.

        Copyright (c) 2012 - 2018 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
        (https://trustee.ietf.org/license-info).

        This version of this YANG module is part of RFC 8341; see
        the RFC itself for full legal notices.";
Top   ToC   RFC8341 - Page 33
     revision "2018-02-14" {
       description
         "Added support for YANG 1.1 actions and notifications tied to
          data nodes.  Clarified how NACM extensions can be used by
          other data models.";
       reference
         "RFC 8341: Network Configuration Access Control Model";
     }

     revision "2012-02-22" {
       description
         "Initial version.";
       reference
         "RFC 6536: Network Configuration Protocol (NETCONF)
                    Access Control Model";
     }

     /*
      * Extension statements
      */

     extension default-deny-write {
       description
         "Used to indicate that the data model node
          represents a sensitive security system parameter.

          If present, the NETCONF server will only allow the designated
          'recovery session' to have write access to the node.  An
          explicit access control rule is required for all other users.

          If the NACM module is used, then it must be enabled (i.e.,
          /nacm/enable-nacm object equals 'true'), or this extension
          is ignored.

          The 'default-deny-write' extension MAY appear within a data
          definition statement.  It is ignored otherwise.";
     }

     extension default-deny-all {
       description
         "Used to indicate that the data model node
          controls a very sensitive security system parameter.

          If present, the NETCONF server will only allow the designated
          'recovery session' to have read, write, or execute access to
          the node.  An explicit access control rule is required for all
          other users.
Top   ToC   RFC8341 - Page 34
          If the NACM module is used, then it must be enabled (i.e.,
          /nacm/enable-nacm object equals 'true'), or this extension
          is ignored.

          The 'default-deny-all' extension MAY appear within a data
          definition statement, 'rpc' statement, or 'notification'
          statement.  It is ignored otherwise.";
     }

     /*
      * Derived types
      */

     typedef user-name-type {
       type string {
         length "1..max";
       }
       description
         "General-purpose username string.";
     }

     typedef matchall-string-type {
       type string {
         pattern '\*';
       }
       description
         "The string containing a single asterisk '*' is used
          to conceptually represent all possible values
          for the particular leaf using this data type.";
     }

     typedef access-operations-type {
       type bits {
         bit create {
           description
             "Any protocol operation that creates a
              new data node.";
         }
         bit read {
           description
             "Any protocol operation or notification that
              returns the value of a data node.";
         }
         bit update {
           description
             "Any protocol operation that alters an existing
              data node.";
         }
Top   ToC   RFC8341 - Page 35
         bit delete {
           description
             "Any protocol operation that removes a data node.";
         }
         bit exec {
           description
             "Execution access to the specified protocol operation.";
         }
       }
       description
         "Access operation.";
     }

     typedef group-name-type {
       type string {
         length "1..max";
         pattern '[^\*].*';
       }
       description
         "Name of administrative group to which
          users can be assigned.";
     }

     typedef action-type {
       type enumeration {
         enum permit {
           description
             "Requested action is permitted.";
         }
         enum deny {
           description
             "Requested action is denied.";
         }
       }
       description
         "Action taken by the server when a particular
          rule matches.";
     }

     typedef node-instance-identifier {
       type yang:xpath1.0;
       description
         "Path expression used to represent a special
          data node, action, or notification instance-identifier
          string.

          A node-instance-identifier value is an
          unrestricted YANG instance-identifier expression.
Top   ToC   RFC8341 - Page 36
          All the same rules as an instance-identifier apply,
          except that predicates for keys are optional.  If a key
          predicate is missing, then the node-instance-identifier
          represents all possible server instances for that key.

          This XML Path Language (XPath) expression is evaluated in the
          following context:

             o  The set of namespace declarations are those in scope on
                the leaf element where this type is used.

             o  The set of variable bindings contains one variable,
                'USER', which contains the name of the user of the
                current session.

             o  The function library is the core function library, but
                note that due to the syntax restrictions of an
                instance-identifier, no functions are allowed.

             o  The context node is the root node in the data tree.

          The accessible tree includes actions and notifications tied
          to data nodes.";
     }

     /*
      * Data definition statements
      */

     container nacm {
       nacm:default-deny-all;

       description
         "Parameters for NETCONF access control model.";

       leaf enable-nacm {
         type boolean;
         default "true";
         description
           "Enables or disables all NETCONF access control
            enforcement.  If 'true', then enforcement
            is enabled.  If 'false', then enforcement
            is disabled.";
       }
Top   ToC   RFC8341 - Page 37
       leaf read-default {
         type action-type;
         default "permit";
         description
           "Controls whether read access is granted if
            no appropriate rule is found for a
            particular read request.";
       }

       leaf write-default {
         type action-type;
         default "deny";
         description
           "Controls whether create, update, or delete access
            is granted if no appropriate rule is found for a
            particular write request.";
       }

       leaf exec-default {
         type action-type;
         default "permit";
         description
           "Controls whether exec access is granted if no appropriate
            rule is found for a particular protocol operation request.";
       }

       leaf enable-external-groups {
         type boolean;
         default "true";
         description
           "Controls whether the server uses the groups reported by the
            NETCONF transport layer when it assigns the user to a set of
            NACM groups.  If this leaf has the value 'false', any group
            names reported by the transport layer are ignored by the
            server.";
       }

       leaf denied-operations {
         type yang:zero-based-counter32;
         config false;
         mandatory true;
         description
           "Number of times since the server last restarted that a
            protocol operation request was denied.";
       }
Top   ToC   RFC8341 - Page 38
       leaf denied-data-writes {
         type yang:zero-based-counter32;
         config false;
         mandatory true;
         description
           "Number of times since the server last restarted that a
            protocol operation request to alter
            a configuration datastore was denied.";
       }

       leaf denied-notifications {
         type yang:zero-based-counter32;
         config false;
         mandatory true;
         description
           "Number of times since the server last restarted that
            a notification was dropped for a subscription because
            access to the event type was denied.";
       }

       container groups {
         description
           "NETCONF access control groups.";

         list group {
           key name;

           description
             "One NACM group entry.  This list will only contain
              configured entries, not any entries learned from
              any transport protocols.";

           leaf name {
             type group-name-type;
             description
               "Group name associated with this entry.";
           }

           leaf-list user-name {
             type user-name-type;
             description
               "Each entry identifies the username of
                a member of the group associated with
                this entry.";
           }
         }
       }
Top   ToC   RFC8341 - Page 39
       list rule-list {
         key name;
         ordered-by user;
         description
           "An ordered collection of access control rules.";

         leaf name {
           type string {
             length "1..max";
           }
           description
             "Arbitrary name assigned to the rule-list.";
         }
         leaf-list group {
           type union {
             type matchall-string-type;
             type group-name-type;
           }
           description
             "List of administrative groups that will be
              assigned the associated access rights
              defined by the 'rule' list.

              The string '*' indicates that all groups apply to the
              entry.";
         }

         list rule {
           key name;
           ordered-by user;
           description
             "One access control rule.

              Rules are processed in user-defined order until a match is
              found.  A rule matches if 'module-name', 'rule-type', and
              'access-operations' match the request.  If a rule
              matches, the 'action' leaf determines whether or not
              access is granted.";

           leaf name {
             type string {
               length "1..max";
             }
             description
               "Arbitrary name assigned to the rule.";
           }
Top   ToC   RFC8341 - Page 40
           leaf module-name {
             type union {
               type matchall-string-type;
               type string;
             }
             default "*";
             description
               "Name of the module associated with this rule.

                This leaf matches if it has the value '*' or if the
                object being accessed is defined in the module with the
                specified module name.";
           }
           choice rule-type {
             description
               "This choice matches if all leafs present in the rule
                match the request.  If no leafs are present, the
                choice matches all requests.";
             case protocol-operation {
               leaf rpc-name {
                 type union {
                   type matchall-string-type;
                   type string;
                 }
                 description
                   "This leaf matches if it has the value '*' or if
                    its value equals the requested protocol operation
                    name.";
               }
             }
             case notification {
               leaf notification-name {
                 type union {
                   type matchall-string-type;
                   type string;
                 }
                 description
                   "This leaf matches if it has the value '*' or if its
                    value equals the requested notification name.";
               }
             }
Top   ToC   RFC8341 - Page 41
             case data-node {
               leaf path {
                 type node-instance-identifier;
                 mandatory true;
                 description
                   "Data node instance-identifier associated with the
                    data node, action, or notification controlled by
                    this rule.

                    Configuration data or state data
                    instance-identifiers start with a top-level
                    data node.  A complete instance-identifier is
                    required for this type of path value.

                    The special value '/' refers to all possible
                    datastore contents.";
               }
             }
           }

           leaf access-operations {
             type union {
               type matchall-string-type;
               type access-operations-type;
             }
             default "*";
             description
               "Access operations associated with this rule.

                This leaf matches if it has the value '*' or if the
                bit corresponding to the requested operation is set.";
           }

           leaf action {
             type action-type;
             mandatory true;
             description
               "The access control action associated with the
                rule.  If a rule has been determined to match a
                particular request, then this object is used
                to determine whether to permit or deny the
                request.";
           }
Top   ToC   RFC8341 - Page 42
           leaf comment {
             type string;
             description
               "A textual description of the access rule.";
           }
         }
       }
     }
   }

   <CODE ENDS>

4.  IANA Considerations

   This document reuses the URI for "ietf-netconf-acm" in the "IETF XML
   Registry".

   This document updates the module registration in the "YANG Module
   Names" registry to reference this RFC instead of RFC 6536 for
   "ietf-netconf-acm".  Following the format in [RFC6020], the following
   has been registered.

        Name: ietf-netconf-acm
        Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-acm
        Prefix: nacm
        Reference: RFC 8341

5.  Security Considerations

   The YANG module specified in this document defines a schema for data
   that is designed to be accessed via network management protocols such
   as NETCONF [RFC6241] or RESTCONF [RFC8040].  The lowest NETCONF layer
   is the secure transport layer, and the mandatory-to-implement secure
   transport is Secure Shell (SSH) [RFC6242].  The lowest RESTCONF layer
   is HTTPS, and the mandatory-to-implement secure transport is TLS
   [RFC5246].

   The NETCONF access control model [RFC8341] provides the means to
   restrict access for particular NETCONF or RESTCONF users to a
   preconfigured subset of all available NETCONF or RESTCONF protocol
   operations and content.

   There is a risk related to the lack of access control enforcement for
   the RESTCONF OPTIONS and PATCH methods.  The risk here is that the
   response to OPTIONS and PATCH may vary based on the presence or
   absence of a resource corresponding to the URL's path.  If this is
   the case, then it can be used to trivially probe for the presence or
   absence of values within a tree.  Therefore, a server MUST NOT vary
Top   ToC   RFC8341 - Page 43
   its responses based on the existence of the underlying resource,
   which would indicate the presence or absence of resource instances.
   In particular, servers should not expose any instance information
   before ensuring that the client has the necessary access permissions
   to obtain that information.  In such cases, servers are expected to
   always return the "access-denied" error response.

   There are a number of data nodes defined in this YANG module that are
   writable/creatable/deletable (i.e., config true, which is the
   default).  These data nodes may be considered sensitive or vulnerable
   in some network environments.  Write operations (e.g., edit-config)
   to these data nodes without proper protection can have a negative
   effect on network operations.  These are the subtrees and data nodes
   and their sensitivity/vulnerability:

   o  /nacm: The entire /nacm subtree is related to security.  Refer to
      the following sections for more details.

   This section highlights the issues for an administrator to consider
   when configuring a NETCONF server with the NACM.

5.1.  NACM Configuration and Monitoring Considerations

   Configuration of the access control system is highly sensitive to
   system security.  A server may choose not to allow any user
   configuration to some portions of it, such as the global security
   level or the groups that allowed access to system resources.

   By default, NACM enforcement is enabled.  By default, "read" access
   to all datastore contents is enabled (unless "nacm:default-deny-all"
   is specified for the data definition), and "exec" access is enabled
   for safe protocol operations.  An administrator needs to ensure that
   the NACM is enabled and also decide if the default access parameters
   are set appropriately.  Make sure that the following data nodes are
   properly configured:

   o  /nacm/enable-nacm (default "true")

   o  /nacm/read-default (default "permit")

   o  /nacm/write-default (default "deny")

   o  /nacm/exec-default (default "permit")

   An administrator needs to restrict write access to all configurable
   objects within this data model.
Top   ToC   RFC8341 - Page 44
   If write access is allowed for configuration of access control rules,
   then care needs to be taken not to disrupt the access control
   enforcement.  For example, if the NACM access control rules are
   edited directly within the running configuration datastore (i.e.,
   :writable-running capability is supported and used), then care needs
   to be taken not to allow unintended access while the edits are being
   done.

   An administrator needs to make sure that the translation from a
   transport- or implementation-dependent user identity to a NACM
   username is unique and correct.  This requirement is specified in
   detail in Section 2.2 of [RFC6241].

   An administrator needs to be aware that the YANG data structures
   representing access control rules (/nacm/rule-list and
   /nacm/rule-list/rule) are ordered by the client.  The server will
   evaluate the access control rules according to their relative
   conceptual order within the running configuration datastore.

   Note that the /nacm/groups data structure contains the administrative
   group names used by the server.  These group names may be configured
   locally and/or provided through an external protocol, such as RADIUS
   [RFC2865] [RFC5607].

   An administrator needs to be aware of the security properties of any
   external protocol used by the transport layer to determine group
   names.  For example, if this protocol does not protect against
   man-in-the-middle attacks, an attacker might be able to inject group
   names that are configured in the NACM so that a user gets more
   permissions than it should.  In such cases, the administrator may
   wish to disable the usage of such group names by setting
   /nacm/enable-external-groups to "false".

   Some of the readable data nodes in this YANG module may be considered
   sensitive or vulnerable in some network environments.  It is thus
   important to control read access (e.g., via get, get-config, or
   notification) to these data nodes.  These are the subtrees and data
   nodes and their sensitivity/vulnerability:

   o  /nacm/enable-nacm

   o  /nacm/read-default

   o  /nacm/write-default

   o  /nacm/exec-default

   o  /nacm/enable-external-groups
Top   ToC   RFC8341 - Page 45
   o  /nacm/groups

   o  /nacm/rule-list

   An administrator needs to restrict read access to the above-listed
   objects within this data model, as they reveal access control
   configuration that could be considered sensitive.

5.2.  General Configuration Issues

   There is a risk that invocation of non-standard protocol operations
   will have undocumented side effects.  An administrator needs to
   construct access control rules such that the configuration datastore
   is protected from such side effects.

   It is possible for a session with some write access (e.g., allowed to
   invoke <edit-config>), but without any access to a particular
   datastore subtree containing sensitive data, to determine the
   presence or non-presence of that data.  This can be done by
   repeatedly issuing some sort of edit request (create, update, or
   delete) and possibly receiving "access-denied" errors in response.
   These "fishing" attacks can identify the presence or non-presence of
   specific sensitive data even without the "error-path" field being
   present within the <rpc-error> response.

   It may be possible for the set of NETCONF capabilities on the server
   to change over time.  If so, then there is a risk that new protocol
   operations, notifications, and/or datastore content have been added
   to the device.  An administrator needs to be sure that the access
   control rules are correct for the new content in this case.
   Mechanisms to detect NETCONF capability changes on a specific device
   are outside the scope of this document.

   It is possible that the data model definition itself (e.g., a YANG
   when-stmt) will help an unauthorized session determine the presence
   or even value of sensitive data nodes by examining the presence and
   values of different data nodes.

   It is possible that the data model definition itself (e.g., a YANG
   when-stmt or choice-stmt) will allow a session to implicitly create
   or delete nodes that the session does not have write access to as an
   implicit side effect from the processing of an allowed <edit-config>
   operation.
Top   ToC   RFC8341 - Page 46
   There is a risk that non-standard protocol operations, or even the
   standard <get> protocol operation, may return data that "aliases" or
   "copies" sensitive data from a different data object.  There may
   simply be multiple data model definitions that expose or even
   configure the same underlying system instrumentation.

   A data model may contain external keys (e.g., YANG leafref), which
   expose values from a different data structure.  An administrator
   needs to be aware of sensitive data models that contain leafref
   nodes.  This entails finding all the leafref objects that "point" at
   the sensitive data (i.e., "path-stmt" values) that implicitly or
   explicitly includes the sensitive data node.

   It is beyond the scope of this document to define access control
   enforcement procedures for underlying device instrumentation that may
   exist to support the NETCONF server operation.  An administrator can
   identify each protocol operation that the server provides and decide
   if it needs any access control applied to it.

   This document incorporates the optional use of a recovery session
   mechanism, which can be used to bypass access control enforcement in
   emergencies such as NACM configuration errors that disable all access
   to the server.  The configuration and identification of such a
   recovery session mechanism are implementation specific and are
   outside the scope of this document.  An administrator needs to be
   aware of any recovery session mechanisms available on the device and
   make sure that they are used appropriately.

   It is possible for a session to disrupt configuration management,
   even without any write access to the configuration, by locking the
   datastore.  This may be done to ensure that all or part of the
   configuration remains stable while it is being retrieved, or it may
   be done as a "denial-of-service" attack.  There is no way for the
   server to know the difference.  An administrator may wish to restrict
   "exec" access to the following protocol operations:

   o  <lock>

   o  <unlock>

   o  <partial-lock>

   o  <partial-unlock>
Top   ToC   RFC8341 - Page 47
5.3.  Data Model Design Considerations

   Designers need to clearly identify any sensitive data, notifications,
   or protocol operations defined within a YANG module.  For such
   definitions, a "nacm:default-deny-write" or "nacm:default-deny-all"
   statement ought to be present, in addition to a clear description of
   the security risks.

   Protocol operations need to be properly documented by the data model
   designer so that it is clear to administrators what data nodes (if
   any) are affected by the protocol operation and what information (if
   any) is returned in the <rpc-reply> message.

   Data models ought to be designed so that different access levels for
   input parameters to protocol operations are not required.  The use of
   generic protocol operations should be avoided, and if different
   access levels are needed, separate protocol operations should be
   defined instead.

6.  References

6.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246,
              DOI 10.17487/RFC5246, August 2008,
              <https://www.rfc-editor.org/info/rfc5246>.

   [RFC5277]  Chisholm, S. and H. Trevino, "NETCONF Event
              Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
              <https://www.rfc-editor.org/info/rfc5277>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <https://www.rfc-editor.org/info/rfc6020>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/info/rfc6241>.
Top   ToC   RFC8341 - Page 48
   [RFC6242]  Wasserman, M., "Using the NETCONF Protocol over Secure
              Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
              <https://www.rfc-editor.org/info/rfc6242>.

   [RFC6991]  Schoenwaelder, J., Ed., "Common YANG Data Types",
              RFC 6991, DOI 10.17487/RFC6991, July 2013,
              <https://www.rfc-editor.org/info/rfc6991>.

   [RFC7230]  Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
              Transfer Protocol (HTTP/1.1): Message Syntax and Routing",
              RFC 7230, DOI 10.17487/RFC7230, June 2014,
              <https://www.rfc-editor.org/info/rfc7230>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <https://www.rfc-editor.org/info/rfc8040>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in
              RFC 2119 Key Words", BCP 14, RFC 8174,
              DOI 10.17487/RFC8174, May 2017,
              <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8342]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "Network Management Datastore Architecture
              (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
              <https://www.rfc-editor.org/info/rfc8342>.

   [W3C.REC-xml-20081126]
              Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
              F. Yergeau, "Extensible Markup Language (XML) 1.0
              (Fifth Edition)", World Wide Web Consortium Recommendation
              REC-xml-20081126, November 2008,
              <https://www.w3.org/TR/2008/REC-xml-20081126>.
Top   ToC   RFC8341 - Page 49
6.2.  Informative References

   [RFC2865]  Rigney, C., Willens, S., Rubens, A., and W. Simpson,
              "Remote Authentication Dial In User Service (RADIUS)",
              RFC 2865, DOI 10.17487/RFC2865, June 2000,
              <https://www.rfc-editor.org/info/rfc2865>.

   [RFC5607]  Nelson, D. and G. Weber, "Remote Authentication Dial-In
              User Service (RADIUS) Authorization for Network Access
              Server (NAS) Management", RFC 5607, DOI 10.17487/RFC5607,
              July 2009, <https://www.rfc-editor.org/info/rfc5607>.

   [YANG-SEC] IETF, "YANG Security Guidelines", <https://trac.ietf.org/
              trac/ops/wiki/yang-security-guidelines>.
Top   ToC   RFC8341 - Page 50
Appendix A.  Usage Examples

   The following XML [W3C.REC-xml-20081126] snippets are provided as
   examples only, to demonstrate how the NACM can be configured to
   perform some access control tasks.

A.1.  <groups> Example

   There needs to be at least one <group> entry in order for any of the
   access control rules to be useful.

   The following XML shows arbitrary groups and is not intended to
   represent any particular use case.

   <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
     <groups>
       <group>
         <name>admin</name>
         <user-name>admin</user-name>
         <user-name>andy</user-name>
       </group>

       <group>
         <name>limited</name>
         <user-name>wilma</user-name>
         <user-name>bam-bam</user-name>
       </group>

       <group>
         <name>guest</name>
         <user-name>guest</user-name>
         <user-name>guest@example.com</user-name>
       </group>
     </groups>
   </nacm>

   This example shows three groups:

   admin:  The "admin" group contains two users named "admin" and
      "andy".

   limited:  The "limited" group contains two users named "wilma" and
      "bam-bam".

   guest:  The "guest" group contains two users named "guest" and
      "guest@example.com".
Top   ToC   RFC8341 - Page 51
A.2.  Module Rule Example

   Module rules are used to control access to all the content defined in
   a specific module.  A module rule has the "module-name" leaf set but
   no nodes from the "rule-type" choice set.

   <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
     <rule-list>
       <name>guest-acl</name>
       <group>guest</group>

       <rule>
         <name>deny-ncm</name>
         <module-name>ietf-netconf-monitoring</module-name>
         <access-operations>*</access-operations>
         <action>deny</action>
         <comment>
             Do not allow guests any access to the NETCONF
             monitoring information.
         </comment>
       </rule>
     </rule-list>

     <rule-list>
       <name>limited-acl</name>
       <group>limited</group>

       <rule>
         <name>permit-ncm</name>
         <module-name>ietf-netconf-monitoring</module-name>
         <access-operations>read</access-operations>
         <action>permit</action>
         <comment>
             Allow read access to the NETCONF
             monitoring information.
         </comment>
       </rule>
       <rule>
         <name>permit-exec</name>
         <module-name>*</module-name>
         <access-operations>exec</access-operations>
         <action>permit</action>
         <comment>
             Allow invocation of the
             supported server operations.
         </comment>
       </rule>
     </rule-list>
Top   ToC   RFC8341 - Page 52
     <rule-list>
       <name>admin-acl</name>
       <group>admin</group>

       <rule>
         <name>permit-all</name>
         <module-name>*</module-name>
         <access-operations>*</access-operations>
         <action>permit</action>
         <comment>
             Allow the 'admin' group complete access to all
             operations and data.
         </comment>
       </rule>
     </rule-list>
   </nacm>

   This example shows four module rules:

   deny-ncm:  This rule prevents the "guest" group from reading any
      monitoring information in the "ietf-netconf-monitoring" YANG
      module.

   permit-ncm:  This rule allows the "limited" group to read the
      "ietf-netconf-monitoring" YANG module.

   permit-exec:  This rule allows the "limited" group to invoke any
      protocol operation supported by the server.

   permit-all:  This rule allows the "admin" group complete access to
      all content in the server.  No subsequent rule will match for the
      "admin" group because of this module rule.
Top   ToC   RFC8341 - Page 53
A.3.  Protocol Operation Rule Example

   Protocol operation rules are used to control access to a specific
   protocol operation.

   <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
     <rule-list>
       <name>guest-limited-acl</name>
       <group>limited</group>
       <group>guest</group>

       <rule>
         <name>deny-kill-session</name>
         <module-name>ietf-netconf</module-name>
         <rpc-name>kill-session</rpc-name>
         <access-operations>exec</access-operations>
         <action>deny</action>
         <comment>
           Do not allow the 'limited' group or the 'guest' group
           to kill another session.
         </comment>
       </rule>
       <rule>
         <name>deny-delete-config</name>
         <module-name>ietf-netconf</module-name>
         <rpc-name>delete-config</rpc-name>
         <access-operations>exec</access-operations>
         <action>deny</action>
         <comment>
           Do not allow the 'limited' group or the 'guest' group
           to delete any configurations.
         </comment>
       </rule>
     </rule-list>
Top   ToC   RFC8341 - Page 54
     <rule-list>
       <name>limited-acl</name>
       <group>limited</group>

       <rule>
         <name>permit-edit-config</name>
         <module-name>ietf-netconf</module-name>
         <rpc-name>edit-config</rpc-name>
         <access-operations>exec</access-operations>
         <action>permit</action>
         <comment>
           Allow the 'limited' group to edit the configuration.
         </comment>
       </rule>
     </rule-list>
   </nacm>

   This example shows three protocol operation rules:

   deny-kill-session:  This rule prevents the "limited" group or the
      "guest" group from invoking the NETCONF <kill-session> protocol
      operation.

   deny-delete-config:  This rule prevents the "limited" group or the
      "guest" group from invoking the NETCONF <delete-config> protocol
      operation.

   permit-edit-config:  This rule allows the "limited" group to invoke
      the NETCONF <edit-config> protocol operation.  This rule will have
      no real effect unless the "exec-default" leaf is set to "deny".
Top   ToC   RFC8341 - Page 55
A.4.  Data Node Rule Example

   Data node rules are used to control access to specific (config and
   non-config) data nodes within the NETCONF content provided by the
   server.

   <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
     <rule-list>
       <name>guest-acl</name>
       <group>guest</group>

       <rule>
         <name>deny-nacm</name>
         <path xmlns:n="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
           /n:nacm
         </path>
         <access-operations>*</access-operations>
         <action>deny</action>
         <comment>
           Deny the 'guest' group any access to the /nacm data.
         </comment>
       </rule>
     </rule-list>

     <rule-list>
       <name>limited-acl</name>
       <group>limited</group>

       <rule>
         <name>permit-acme-config</name>
         <path xmlns:acme="http://example.com/ns/netconf">
           /acme:acme-netconf/acme:config-parameters
         </path>
         <access-operations>
           read create update delete
         </access-operations>
         <action>permit</action>
         <comment>
           Allow the 'limited' group complete access to the acme
           NETCONF configuration parameters.  Showing long form
           of 'access-operations' instead of shorthand.
         </comment>
       </rule>
     </rule-list>
Top   ToC   RFC8341 - Page 56
     <rule-list>
       <name>guest-limited-acl</name>
       <group>guest</group>
       <group>limited</group>

       <rule>
         <name>permit-dummy-interface</name>
         <path xmlns:acme="http://example.com/ns/itf">
           /acme:interfaces/acme:interface[acme:name='dummy']
         </path>
         <access-operations>read update</access-operations>
         <action>permit</action>
         <comment>
           Allow the 'limited' and 'guest' groups read
           and update access to the dummy interface.
         </comment>
       </rule>
     </rule-list>

     <rule-list>
       <name>admin-acl</name>
       <group>admin</group>
       <rule>
         <name>permit-interface</name>
         <path xmlns:acme="http://example.com/ns/itf">
           /acme:interfaces/acme:interface
         </path>
         <access-operations>*</access-operations>
         <action>permit</action>
         <comment>
           Allow the 'admin' group full access to all acme interfaces.
         </comment>
       </rule>
     </rule-list>
   </nacm>
Top   ToC   RFC8341 - Page 57
   This example shows four data node rules:

   deny-nacm:  This rule denies the "guest" group any access to the
      /nacm subtree.

   permit-acme-config:  This rule gives the "limited" group read-write
      access to the acme <config-parameters>.

   permit-dummy-interface:  This rule gives the "limited" and "guest"
      groups read-update access to the acme <interface> entry named
      "dummy".  This entry cannot be created or deleted by these groups;
      it can only be altered.

   permit-interface:  This rule gives the "admin" group read-write
      access to all acme <interface> entries.

A.5.  Notification Rule Example

   Notification rules are used to control access to a specific
   notification event type.

   <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
     <rule-list>
       <name>sys-acl</name>
       <group>limited</group>
       <group>guest</group>

       <rule>
         <name>deny-config-change</name>
         <module-name>acme-system</module-name>
         <notification-name>sys-config-change</notification-name>
         <access-operations>read</access-operations>
         <action>deny</action>
         <comment>
           Do not allow the 'guest' group or the 'limited' group
           to receive config change events.
         </comment>
       </rule>
     </rule-list>
   </nacm>

   This example shows one notification rule:

   deny-config-change:  This rule prevents the "limited" group or the
      "guest" group from receiving the acme <sys-config-change>
      event type.
Top   ToC   RFC8341 - Page 58
Authors' Addresses

   Andy Bierman
   YumaWorks
   685 Cochran St.
   Suite #160
   Simi Valley, CA  93065
   United States of America

   Email: andy@yumaworks.com


   Martin Bjorklund
   Tail-f Systems

   Email: mbj@tail-f.com