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:
module rule
RPC operation rule
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.
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:
read: retrieval of any kind
write: modification of any kind
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.
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.
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.
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