<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-mahesh-netconf-accounting-03"
     ipr="trust200902">
  <front>
    <title abbrev="NETCONF and RESTCONF Accounting">Accounting in NETCONF and
    RESTCONF</title>

    <author fullname="Mahesh Jethanandani" initials="M" surname="Jethanandani">
      <organization>Cisco Systems, Inc</organization>

      <address>
        <postal>
          <street>170 West Tasman Drive</street>

          <city>San Jose</city>

          <region>CA</region>

          <code>95070</code>

          <country>USA</country>
        </postal>

        <phone/>

        <facsimile/>

        <email>mjethanandani@gmail.com</email>

        <uri/>
      </address>
    </author>

    <date day="17" month="July" year="2017"/>

    <abstract>
      <t>This document defines an accounting record for NETCONF and
      RESTCONF.</t>
    </abstract>

    <note title="Requirements Language">
      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
      "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
      document are to be interpreted as described in <xref
      target="RFC2119">RFC 2119</xref>.</t>
    </note>
  </front>

  <middle>
    <section title="Introduction">
      <t><xref target="RFC6241">NETCONF</xref> and <xref
      target="RFC8040">RESTCONF</xref> protocol operations are authenticated
      and authorized as part of the Authentication, Authorization and
      Accounting (AAA) framework. An accounting record is generated as part of
      the same framework for each of these operations to satisfy the
      accounting part of AAA, but there has been no effort to define such a
      record. Having an accounting record that is consistent across vendors
      allows for the operator to compare operations across devices from
      different vendors. This document defines such a record and a
      corresponding YANG data model (ietf-netconf-am.yang).</t>

      <t>The rest of this document will use NETCONF to imply both NETCONF and
      RESTCONF, but where applicable will call out each protocol
      specifically.</t>

      <section title="Compatability with remote AAA servers">
        <t>This document does not cover how the server interacts with remote
        AAA servers and any interaction is out of scope of this document. A
        particular implementation can make the records available as part of
        &lt;get&gt; request, send a notification every time a accounting
        record is generated or use any existing protocol to update the remote
        AAA server.</t>
      </section>

      <section title="Terminology">
        <t>The following terms are defined in <xref
        target="RFC6241">NETCONF</xref> and are not redefined here:</t>

        <t><list style="symbols">
            <t>client</t>

            <t>&lt;get&gt;</t>

            <t>notification</t>

            <t>server</t>

            <t>session</t>

            <t>user</t>
          </list></t>

        <t>And the following terms are defined in <xref
        target="RFC6536">NACM</xref> and are not redefined here.</t>

        <t><list style="symbols">
            <t>data-node</t>

            <t>action</t>

            <t>rule</t>
          </list></t>
      </section>
    </section>

    <section title="Accounting Record">
      <t>An accounting record for NETCONF consists of the following fields.
      Note, there is no accounting record for reading or notification of an
      accounting record.</t>

      <texttable title="">
        <ttcol>message-id</ttcol>

        <ttcol>session-id</ttcol>

        <ttcol>src-ip</ttcol>

        <ttcol>date-time</ttcol>

        <ttcol>user</ttcol>

        <ttcol>groups</ttcol>

        <ttcol>rule</ttcol>

        <ttcol>data-node</ttcol>

        <ttcol>value</ttcol>

        <ttcol>action</ttcol>

        <ttcol>status</ttcol>
      </texttable>

      <t>where:</t>

      <t>message-id: This is the id within a given NETCONF session assigned to
      each RPC. RESTCONF has no concept of a session, so this field would be
      left blank.</t>

      <t>session-id: The session-id in case of NETCONF and would be blank in
      case of RESTCONF. If the accounting record needs to be fragmented for
      any reason, it is suggested that this field not be repeated in
      subsequent packets. Instead a combination of start and end record
      marker, and the message-id should be used to reassemble fragmented
      records.</t>

      <t>src-ip: The source IP address that was used to request the operation.
      If the accounting record needs to be fragmented for any reason, it is
      suggested that this field not be repeated in subsequent packets. Instead
      a combination of start and end record marker, and the message-id should
      be used to reassemble fragmented records.</t>

      <t>date-time: The date and time when the operation was performed (UTC
      Timezone). If the accounting record needs to be fragmented for any
      reason, it is suggested that this field not be repeated in subsequent
      packets. Instead a combination of start and end record marker, and the
      message-id should be used to reassemble fragmented records.</t>

      <t>user: The NETCONF user that requesed this operation. If the
      accounting record needs to be fragmented for any reason, it is suggested
      that this field not be repeated in subsequent packets. Instead a
      combination of start and end record marker, and the message-id should be
      used to reassemble fragmented records.</t>

      <t>groups: The group the user belongs to. If the accounting record needs
      to be fragmented for any reason, it is suggested that this field not be
      repeated in subsequent packets. Instead a combination of start and end
      record marker, and the message-id should be used to reassemble
      fragmented records.</t>

      <t>data-node: The data-node in the <xref target="RFC6536">NACM</xref>
      rule on which the operations is being performed</t>

      <t>value: The value that was set for any of the attributes in the
      request</t>

      <t>action: The action in the <xref target="RFC6536">NACM</xref> rule</t>

      <t>rule: The rule in the <xref target="RFC6536">NACM</xref> that was
      matched to authorize the action.</t>

      <t>status: Whether the operations was permitted or denied.</t>
    </section>

    <section title="Data Model Definitions">
      <t>The model uses the NACM extension statement of default-deny-all to
      protect accounting records. Explicit rules have to be defined to be
      enable access to the accounting records.</t>

      <section title="Data Organization">
        <t>The following diagram highlights the contents and structure of the
        Accounting YANG module. For information on annotations, please refer
        to <xref target="I-D.ietf-netmod-yang-tree-diagrams">YANG Tree
        Diagrams</xref>.</t>

        <t><figure>
            <artwork><![CDATA[
module: ietf-netconf-am
    +--rw nam
       +--rw enable-nam?          boolean
       +--ro accounting-record* [session-id message-id]
          +--ro session-id    nc:session-id-type
          +--ro message-id    uint32
          +--ro date-time     yang:date-and-time
          +--ro src-ip        inet:ip-address
          +--ro group         nacm:group-name-type
          +--ro user?         nacm:user-name-type
          +--ro rule?         string
          +--ro data-node     nacm:node-instance-identifier
          +--ro value?
          +--ro action        nacm:access-operations-type
          +--ro status?       nacm:action-type
   ]]></artwork>
          </figure></t>
      </section>

      <section title="YANG Module">
        <t>The following YANG module specifies the normative NETCONF content
        that MUST be supported by the server.</t>

        <t>The "ietf-netconf-am" YANG module imports typedefs from <xref
        target="RFC6991">YANG-TYPES</xref>, from <xref
        target="RFC6241">NETCONF</xref> and from <xref
        target="RFC6536">NACM</xref>.</t>

        <figure>
          <artwork><![CDATA[<CODE BEGINS> file "ietf-netconf-am@2017-07-16.yang"

module ietf-netconf-am {
    yang-version 1.1;
    namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-am";
    prefix "nam";

    import ietf-inet-types {
        prefix inet;
    }
    
    import ietf-yang-types {
        prefix yang;
    }
  
    import ietf-netconf {
        prefix nc;
    }

    import ietf-netconf-acm {
        prefix nacm;
    }

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

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

         WG Chair: Mehmet Ersue
               	   <mailto:mehmet.ersue@nsn.com>

         WG Chair: Mahesh Jethanandani
                   <mailto:mjethanandani@gmail.com>

         Editor:   Mahesh Jethanandani
                   <mailto:mjethanandani@gmail.com>";


    description
        "This module defines an accounting record for NETCONF operations
         performed on the server. If these operations are authorized 
         using rules defined by NACM [RFC6536], then that information is 
         also captured by this module.

         Copyright (c) 2014 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 XXXX; see
         the RFC itself for full legal notices.";

    revision "2017-07-16" {
         description
             "Initial version";
         reference
             "RFC XXXX: NETCONF and RESTCONF Accounting";
    }

    /*
     * Data definition statements.
     */

    container nam {
    	nacm:default-deny-all;
     
        description
            "Parameters for NETCONF Accounting Model.";
         
        leaf enable-nam {
        	type boolean;
            default true;
            description
                "Enable or disable generation of NETCONF
                 accounting records. If 'true', accounting
                 records will be generated. If set to 'false'
                 no accounting records will be generated.";
        }

        list accounting-record {
            key "session-id message-id";
            config false;
            description
                "A list of accounting records generated by the server";
             
            leaf session-id {
                type nc:session-id-type;
                description
                    "If this operation happened over NETCONF, this 
                     field captures the NETCONF session-id. In case 
                     of RESTCONF this field can be left blank.";
            }
            
            leaf message-id {
                type uint32;
                description
                    "Id that is assigned to each RPC within a given
                     NETCONF session. Should be blank in case of 
                     RESTCONF.";
            }

            leaf date-time {
                type yang:date-and-time;
                mandatory true;
                description
                    "The date and time when the operation was 
                     requested.";
            }

            leaf src-ip {
                type inet:ip-address;
                mandatory true;
                description
                    "The source IP address where the request was made 
                     from.";
            }

            leaf group {
                type nacm:group-name-type;
                mandatory true;
                description
                    "The name of the group that the user who requested 
                     the operation belongs to.";
            }
      
            leaf user {
                type nacm:user-name-type;
                description
                    "The user within the group that is requesting this 
                     operation.";
            }
            
            leaf rule {
                type string {
                    length "1..max";
                }
                description
                    "The name assigned to the rule that was used to
                     authorize the action, if authorization was 
                     enabled.";
            }
            
            leaf data-node {
                type nacm:node-instance-identifier;
                mandatory true;
                description
                    "Data Node Instance Identifier associated with the
                     data node that the request is being made on.
 
                     Instance identifiers start with the top-level
                     data node, and a complete identifier is required 
                     for this value.";
            }

            anydata value {
                description
                    "An optional field, it contains the value of any
                     of the attribute that form the record.

                     It could be as simple as the filter value 
                     'http' specified that the user requested as part
                     of the authorization request such as in this 
                     example:

                     <filter>
                         <name>http</name>
                     </filter>

                     or it could be value being set for a ssh port
                     in this example:

                     <ssh>
                         <port>2022</port>
                     </ssh>";
            }
            
            leaf action {
                type nacm:access-operations-type;
                mandatory true;
                description
                    "The type of NETCONF operation being requested.";
            }
            
            leaf status {
                type nacm:action-type;
                description
                    "Action taken by the server when the above 
                     mentioned rule matched, if authorization was 
                     enable.";
            }
        }
    }
}


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

        <t/>
      </section>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This document makes two requests of IANA.</t>

      <t>The first request is to register one URI in "The IETF XML Registry".
      Following the format in <xref target="RFC3688">The IETF XML
      Registry</xref>, the following needs to be registered.</t>

      <t>URI: urn:ietf:params:xml:ns:yang:ietf-netconf-am</t>

      <t>Registrant Contact: The IESG</t>

      <t>XML: N/A, the requested URI is an XML namespace</t>

      <t>The second request is to register one module in the "YANG Module
      Names" registry. Following the format in <xref
      target="RFC7950">YANG</xref>, the following needs to be registered.</t>

      <t>Name: ietf-netconf-am</t>

      <t>Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-am</t>

      <t>Prefix: nam</t>

      <t>Reference: RFC XXXX</t>

      <t>Note to RFC Editor - Please replace XXXX here and in the rest of the
      draft with the RFC id assigned to this draft.</t>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>The YANG module defined in this document is designed to be accessed
      via network management protocol such as <xref
      target="RFC6241">NETCONF</xref> or <xref
      target="RFC8040">RESTCONF</xref>. The lowest NETCONF layer is the secure
      transport layer, and the mandatory-to-implement secure transport is
      <xref target="RFC6242">Secure Shell (SSH)</xref>. The lowest RESTCONF
      layers is HTTPS, and the mandatory-to-implement secure transport is
      <xref target="RFC5246">TLS</xref>.</t>

      <t>The NETCONF Access Control Model <xref target="RFC6536">(NACM)</xref>
      provides the means to restrict access for particular NETCONF or RESTCONF
      users to a pre-configured subset of all available NETCONF or RESTCONF
      protocol operations and content.</t>

      <t>Most of the data nodes defined in this YANG module are readonly, i.e.
      config false, and are therefore not vulnerable to manipulation in
      network environments. However, they might contain data that might be
      sensitive and should be protected with the right <xref
      target="RFC6536">NACM</xref> rules.</t>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t/>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>

      <?rfc include='reference.RFC.3688'?>

      <?rfc include='reference.RFC.5246'?>

      <?rfc include='reference.RFC.6241'?>

      <?rfc include='reference.RFC.6242'?>

      <?rfc include='reference.RFC.6536'?>

      <?rfc include='reference.RFC.6991'?>

      <?rfc include='reference.RFC.7950'?>

      <?rfc include='reference.RFC.8040'?>
    </references>

    <references title="Informative References">
      <?rfc include='reference.I-D.ietf-netmod-yang-tree-diagrams'?>
    </references>

    <section title="Accounting model examples">
      <section title="&lt;edit-config&gt; Example for Accounting">
        <t>This example demonstrates how the configuration could be updated to
        enable accounting. The attribute in the model that enables accounting
        is enable-nam. </t>

        <figure>
          <artwork><![CDATA[
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
     message-id="4">
  <edit-config xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
    <target>
      <candidate/>
    </target>
    <test-option>test-then-set</test-option>
    <error-option>rollback-on-error</error-option>
    <config>
      <nam xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-am">
        <enable-nam>true</enable-nam>
      </nam>
    </config>
  </edit-config>
</rpc>

]]></artwork>
        </figure>
      </section>

      <section title="&lt;get&gt; Example for Accounting">
        <t>This example demonsrates what a &lt;get&gt; request and response
        might look like.</t>

        <t><figure>
            <artwork><![CDATA[
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
     message-id="1">
  <get>
    <filter>
      <nam xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-am">
        <accounting-record/>
      </nam>
    </filter>
  </get>
</rpc>

<rpc-reply message-id="1"
           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <data>
    <nam xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-am">
      <accounting-record>
        <session-id>101</session-id>
        <message-id>100</message-id>
        <date-time>2017-06-19T16:39:57-08:00</date-time>
        <src-ip>172.20.39.46</src-ip>
        <group>netconf-group</group>
        <user>netconf</user>
        <path xmlns:acme="http://example.com/ns/itf">
          /acme:interfaces/acme:interface
        </path>
        <value>
          <name>GigabitEthernet0/0/0/0</name>
          <admin-state>UP</admin-state>
        </value>
        <action>read</action>
        <rule>51</rule>
        <status>permit</status>
      </accounting-record>
    </nam>
  </data>
</rpc-reply>

]]></artwork>
          </figure></t>
      </section>

      <section title="NACM rule for Accounting">
        <t>This example demonstrates how NACM could be configured to permit
        access to accounting records. Note, the model has default-deny-all set
        to prevent access to accounting records by default, and expects
        explicit rules to be configured to permit access.</t>

        <t><figure>
            <artwork><![CDATA[
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
  <rule-list>
    <name>root</name>
    <group>root</group>

    <rule>
      <name>allow-nam</name>
      <path xmlns:n="urn:ietf:params:xml:ns:yang:ietf-netconf-am">
        /n:nam
      </path>
      <access-operations>read</access-operations>
      <action>permit</action>
      <comment>
        Allow the root group read access to the /nam data.
      </comment>
    </rule>
  </rule-list>
</nacm>
]]></artwork>
          </figure></t>
      </section>
    </section>
  </back>
</rfc>
