Access Control

The netconfd-pro access control data model is defined in ietf-netconf-acm.yang (RFC 8341)

The nacm:default-deny-write and nacm:default-deny-all extensions also affect access control. If present in the YANG definition, then the default behavior (when no rule is found) is not followed. Instead, a superuser account must be used to allow default access.

There are 3 types of access control rules that can be defined:

  1. module rule

  2. RPC operation rule

  3. database rule

Rules apply to one or more groups. Each group contains zero or more user names. Database rules are applied top-down, at every level.

The user needs permission for the requested access (read or write) for all referenced nodes within the database. For example, if there was a leaf from module X that augments a container in module Y, the user would need permission to access the container from module Y, and then permission to access the leaf from module X.

The NACM data model can be used without any configuration at all. Refer to the Access Control Modes section for more details.

../_images/nacm_overview.png

Normally, some configuration is required:

  • groups: configure one or more administrative groups

  • rules: configure one or more access control rules

The entire /nacm subtree is tagged as nacm:default-deny-all. By default, only a superuser account can read or write any of its contents. It is suggested that even read access to this data structure be controlled carefully at all times.

The /nacm subtree is described in the ietf-netconf-acm.yang section and RFC 8341.

Bypassing Access Control

By default, no configuration data can be edited. Even if the NACM write-default is set to permit, the /nacm subtree cannot be edited by default.

The --superuser CLI parameter can be used to allow the specified user sessions to bypass NACM enforcement. This can be used to configure NACM groups and rule-lists, and access all API components normally protected by NACM.

Access control can also be completely disabled by setting the --access-control CLI parameter to off. This is not recommended!

Users and Groups

Access rights in NACM are given to groups.

A group entry consists of a group identifier and a list of user names that are members of the group.

By default, there are no groups created. Each /nacm/groups/group entry must be created by the client. There is no user name table either. It is assumed that the operator will know which user names are valid within each managed device.

Creating New Groups

The <edit-config> operation can be used to create new group entries.

  • A user name can appear within the same group zero or one times.

  • A user name can appear in zero or more groups.

When a user is a member of multiple groups, all these groups will be used to match against rules, in a conceptual 'OR' expression. If any of these groups matches one of the <allowed-group> leaf-list nodes within one of the 3 rule types, then that rule will be the one that is used. Rules are always searched in the order they are entered, even the system-ordered lists.

The path to the group element is /nacm:nacm/nacm:groups/nacm:group.

The following <edit-config> example shows how a group can be defined. The group name is 'admi1',and the users 'user1' and 'user2' are the initial members of this group.

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <candidate/>
    </target>
    <default-operation>merge</default-operation>
    <test-option>set</test-option>
    <config>
      <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
        <groups>
          <group xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
            nc:operation="merge">
            <name>admin1</name>
            <user-name>user1</user-name>
            <user-name>user2</user-name>
          </group>
        </groups>
      </nacm>
    </config>
  </edit-config>
</rpc>

Access Control Modes

The --access-control configuration parameter is used to globally enable or disable the access control system. It cannot be changed at run-time, or through a NETCONF session.

  • off: no access control enforcement is done at all.

  • disabled: all nacm:default-deny-write and nacm:default-deny-all tagged objects will require a superuser account to access, but no other access control enforcement will be done.

  • permissive: all nacm:default-deny-all objects will require super user account to read. No other read access enforcement will be done. Write and exec access will be checked.

  • enforcing: all access control enforcement will be checked. This is the default behavior.

Permissions

There are 3 types of access permissions defined:

  1. read: retrieval of any kind

  2. write: modification of any kind

  3. exec: right to invoke an RPC operation

The <allowed-rights> object in each of the 3 access control rule entries is a 'bits' leaf, which is allowed to contain any of these string tokens, or none of them to deny all access to a set of groups.

When a rule is found which matches the current request, the <allowed-rights> leaf will be used to grant permission or not. If the bit for the requested operation is present, then the request is permitted. If the bit is not present, then the request is denied.

Special YANG Extensions For Access Control

There are 3 YANG language extensions defined that can be used to force access control behavior for specific data nodes in the configuration database.

  1. nacm:default-deny-write (no parameter) If present in a data node statement, this extension will cause the write default to be ignored, and any write access to instances of this object will be rejected with an 'access-denied' error unless there is an explicit NACM rule allowing write access to the user session. If present in an 'rpc' statement, then exec access will be denied unless there is an explicit NACM rule granting exec access.

  2. nacm:default-deny-all (no parameter) If present in a data node statement, this extension will cause the read and write defaults to be ignored, and any write access to instances of this object will be rejected with an 'access-denied' error unless there is an explicit NACM rule allowing write access to the user session. Read access will be denied, which causes that data to be removed from the <rpc-reply>. If present in an 'rpc' statement, then exec access will be denied unless there is an explicit NACM rule granting exec access.

  3. ncx:user-write (parameter: permitted, type: bits: create, update, delete) Used within database configuration data definition statements to control user write access to the database object containing this statement. The 'permitted' argument is a list of operations that users are permitted to invoke for the specified node. These permissions will over-ride all NACM access control rules, even if NACM is disabled. To dis-allow all user access, provide an empty string for the 'permitted' parameter.

    To allow only create and delete user access, provide the string 'create delete' for the parameter. Use this for YANG database objects that cannot be changed once they are set.

Default Enforcement Behavior

Each access type has a default behavior if no rule is found and no special YANG extensions apply:

  • read default: permit

  • write default: deny

  • exec default: permit

These defaults can be changed by the server developer, by modifying the YANG definitions in ietf-netconf-acm.yang. If the data node object definition contains the special YANG extensions described in the previous section, then the extension will define default access and the NACM default access rule will not be used.

Access Control Algorithm

The access control enforcement procedures are defined in RFC 6536, section 3.4

YANG Extensions Affecting Access Control

The YANG extension ncx:password can be used in a YANG module (leaf definition) to identify password fields.

The "obj_is_password" function will be true for these objects, and any object that uses the “crypt-hash” typedef from the iana-crypt-hash.yang module.

Note

The "ncx:password" extension is deprecated and should not be used. It does not prevent disclosure of passwords in all cases. Use the "crypt-hash" data type instead.

The OpenConfig YANG extension oc-ext:openconfig-hashed-value can be used in a YANG module (leaf definition) to identify a password field with strict requirements for non-disclosure.

The initial cleartext password string is converted to a hash right away and only the hash is stored or displayed after that.

This extension should be used instead of "ncx:password" if the "crypt-hash" data type cannot be used.

Passwords and crypt-hash

Objects that are type “crypt-hash” will be processed by the server according to the following typedef from iana-crypt-hash.yang:

typedef crypt-hash {
  type string {
    pattern
      '$0$.*'
    + '|$1$[a-zA-Z0-9./]{1,8}$[a-zA-Z0-9./]{22}'
    + '|$5$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{43}'
    + '|$6$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{86}';
  }
  description
    "The crypt-hash type is used to store passwords using
     a hash function.  The algorithms for applying the hash
     function and encoding the result are implemented in
     various UNIX systems as the function crypt(3).

     A value of this type matches one of the forms:

       $0$<clear text password>
       $<id>$<salt>$<password hash>
       $<id>$<parameter>$<salt>$<password hash>

     The '$0$' prefix signals that the value is clear text.  When
     such a value is received by the server, a hash value is
     calculated, and the string '$<id>$<salt>$' or
     $<id>$<parameter>$<salt>$ is prepended to the result.  This
     value is stored in the configuration data store.
     If a value starting with '$<id>$', where <id> is not '0', is
     received, the server knows that the value already represents a
     hashed value and stores it 'as is' in the data store.

     When a server needs to verify a password given by a user, it
     finds the stored password hash string for that user, extracts
     the salt, and calculates the hash with the salt and given
     password as input.  If the calculated hash value is the same
     as the stored value, the password given by the client is
     accepted.

     This type defines the following hash functions:

       id | hash function | feature
       ---+---------------+-------------------
        1 | MD5           | crypt-hash-md5
        5 | SHA-256       | crypt-hash-sha-256
        6 | SHA-512       | crypt-hash-sha-512

     The server indicates support for the different hash functions
     by advertising the corresponding feature.";
  reference
    "IEEE Std 1003.1-2008 - crypt() function
     RFC 1321: The MD5 Message-Digest Algorithm
     FIPS.180-4.2012: Secure Hash Standard (SHS)";
}

Values of this datatype that match the “$0$” format will be converted and stored as a hash, according to the typedef specification.

  • The agt_profile field "agt_min_password_len" field will be used to enforce a minimum password length for the crypt-hash data type. The default value is 8.

  • The agt_profile field "agt_crypt_hash_prefix" field will be used to select the hash function that will be used for the conversion of $0$ format strings. The default value is SHA-512 ($6$).

  • The obj_is_password() function will be true for any crypt-hash data node

Password Storage

  • The "crypt-hash" data type must be used (with mode 5 or 6) to avoid exposure of a cleartext password by the client in the initial password configuration edit request.

  • Otherwise, the "crypt-hash" data type (mode 0) or the "openconfig-hashed-value" extension should be used if

There are more details about password storage and password exposure during logging in the KnowledgeBase article Passwords Stored in YANG Data

Using Module Tags with NACM

There is a "module-tag" extension to NACM defined in yumaworks-system.yang

augment /nacm:nacm/nacm:rule-list/nacm:rule/nacm:rule-type {
  case module-tags {
    uses ywapp:ModuleTagParm;
  }
}

This extension adds a new rule-type called module-tags.

A list of module-tag strings can be used to select the modules that are mapped to the NACM rule.

It is similar to a data-rule which selects a path, except it selects all objects from the specified module(s) for RPC, notification, and data node access control.

Module-tags are more flexible than the module-name leaf provided in the NACM rule entry.

It is recommended that this field be set to the default ‘*’ if the module-tag parameter is used.

Example:

The following module-tag is used:

module-tagmap [email protected]

The module ietf-restconf-monitoring is mapped to the module-tag “restconf”.

The following NACM configuration contains a module-tags rule:

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
  <read-default>deny</read-default>
    <groups>
      <group>
        <name>g1</name>
        <user-name>netconf1</user-name>
      </group>
    </groups>
  <rule-list>
    <name>rl1</name>
    <group>g1</group>
    <rule>
      <name>r1</name>
      <module-name>*</module-name>
      <access-operations>*</access-operations>
      <action>permit</action>
      <comment/>
      <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">restconf</module-tag>
    </rule>
  </rule-list>
</nacm>

This rule allows group “g1” all access to the modules tagged with the module-tag “restconf”.

An example <get> request returns only the data from the ietf-restconf-monitoring.yang module.

[email protected]> get

RPC Data Reply 3 for session 4 [default]:

rpc-reply {
  data {
    restconf-state {
      capabilities {
        capability urn:ietf:params:restconf:capability:depth:1.0
        capability urn:ietf:params:restconf:capability:with-defaults:1.0
        capability urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=report-all
        capability urn:ietf:params:restconf:capability:fields:1.0
        capability urn:ietf:params:restconf:capability:replay:1.0
        capability urn:ietf:params:restconf:capability:filter:1.0
        capability urn:ietf:params:restconf:capability:yang-patch:1.0
      }
      streams {
        stream RESTCONF {
          name RESTCONF
          description 'default RESTCONF event stream'
          replay-support true
          replay-log-creation-time 2018-04-27T21:45:56Z
          access xml {
            encoding xml
            location http://localhost/restconf/stream
          }
        }
      }
    }
  }
}