<?xml version="1.0" encoding="US-ASCII"?>
<!-- This is built from a template for a generic Internet Draft. Suggestions for
     improvement welcome - write to Brian Carpenter, brian.e.carpenter @ gmail.com -->
<!-- This can be converted using the Web service at http://xml.resource.org/experimental.html
     (which supports the latest, sometimes undocumented and under-tested, features.) -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<!-- You want a table of contents -->
<?rfc symrefs="yes"?>
<!-- Use symbolic labels for references -->
<?rfc sortrefs="yes"?>
<!-- This sorts the references -->
<?rfc iprnotified="no" ?>
<!-- Change to "yes" if someone has disclosed IPR for the draft -->
<?rfc compact="yes"?>
<!-- This defines the specific filename and version number of your draft (and inserts the appropriate IETF boilerplate -->
<rfc category="std" docName="draft-mahesh-netconf-binary-encoding-01"
     ipr="trust200902" updates="6241">
  <front>
    <title abbrev="Binary Encoding">Binary Encoding for NETCONF</title>

    <author fullname="Mahesh Jethanandani" initials="M."
            surname="Jethanandani">
      <organization/>

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

    <author fullname="Jason Lam" initials="J." surname="Lam">
      <organization>Cisco Systems, Inc.</organization>

      <address>
        <email>lamj@cisco.com</email>
      </address>
    </author>

    <author fullname="Alfred Leung" initials="A." surname="Leung">
      <organization>Cisco Systems, Inc.</organization>

      <address>
        <email>alfleung@cisco.com</email>
      </address>
    </author>

    <author fullname="Andy Bierman" initials="A." surname="Bierman">
      <organization>YumaWorks, Inc.</organization>

      <address>
        <postal>
          <street/>

          <city/>

          <region/>

          <code/>

          <country/>
        </postal>

        <phone/>

        <facsimile/>

        <email>andy@yumaworks.com</email>

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

    <date day="30" month="June" year="2018"/>

    <area>Operations and Management Area</area>

    <workgroup>NETCONF WG</workgroup>

    <abstract>
      <t>This document describes a method by which a NETCONF [RFC6241] client
      and server can negotiate an alternate form of encoding.</t>

      <t>This document updates RFC 6241.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="intro" title="Introduction">
      <t><xref target="RFC6241">NETCONF</xref>, by default, supports XML
      encoding for its payload. However, XML can be very verbose, specially
      for operational data. This document proposes a mechanism by which
      clients and servers can negotiate an alternate form of encoding, e.g.
      binary encoding, and use that to exchange data. Binary encoding can
      reduce the physical size of the data exchanged, in some cases by as much
      as 66%, while preserving the original data.</t>

      <t>Several encoding mechanisms have been proposed, including <xref
      target="RFC7049">CBOR</xref> and <xref target="RFC8259">JSON </xref>.
      This document does not advocate any particular encoding format. Instead,
      it leaves it up to the negotiation between client and server to decide
      the form of encoding. For an example of how to encode YANG in CBOR
      format, see <xref target="I-D.ietf-core-yang-cbor">CBOR Encoding of Data
      Modeled with YANG</xref> and <xref target="RFC7951">JSON Encoding of
      Data Modeled with YANG</xref>.</t>

      <t>This document updates <xref target="RFC6241">NETCONF</xref>.</t>

      <section title="Terminology">
        <t>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
        <xref target="RFC2119">BCP 14</xref> <xref target="RFC8174"/> when,
        and only when, they appear in all capitals, as shown here.</t>
      </section>

      <!---->
    </section>

    <!---->

    <section anchor="problem" title="Protocol Negotiation">
      <t>NETCONF clients and servers exchange a hello as part of establishing
      a connection. As part of the hello exchange, the client advertises an
      ordered list of encoding it would like to use, while the server
      advertises an unordered list of encoding that it is capable of
      supporting. If no match of encoding is found, the session is dropped. If
      a match is found the client issues a request that is encoded with first
      match found. Thereafter, both the Message layer in Figure 1 of <xref
      target="RFC6241">NETCONF</xref> and the YANG data within the Message
      Layer, are in the form of new encoding. This includes RPC, Actions and
      Notifications.</t>

      <t>This draft suggests advertisement of the following additional
      capability.</t>

      <section title="Encoding">
        <section title="Overview">
          <t>The :encoding capability indicates what alternate encoding format
          each side is willing to support. The client and server send a comma
          separated list (with no white spaces) of encoding formats they are
          willing to support. The client sends a list of encoding ordered by
          preference, while the server includes an unordered list of
          encoding.</t>

          <t>Both the client and server examine each others &lt;hello&gt;
          message for this capability. If not present, the default encoding is
          used, which is XML. The client examines its list against the server
          list, checked in the order of preference it sent do the server. If a
          matching encoding format is found, the client picks that encoding
          for the remainder of the session, starting with the first
          &lt;rpc&gt; request. All &lt;rpc&gt;, &lt;rpc-reply&gt;,
          &lt;action&gt; and &lt;notification&gt; messages MUST be encoded in
          this negotiated encoding.</t>

          <t>Both the client and the server MUST support the "application/xml"
          media type to be backward compatible with <xref
          target="RFC6241">NETCONF</xref>.</t>

          <t>The base:1.1 negotiation defined in <xref
          target="RFC6241">NETCONF</xref> determines the message framing that
          is used for the entire session.</t>
        </section>

        <section title="Example">
          <t>In this example, the client supports the following encoding
          formats shown in a preferred order.</t>

          <t><list style="symbols">
              <t>Concise Binary Object Representation (CBOR) with YANG Schema
              Item iDentifier (SID) - cbor+sid</t>

              <t>Google Protocol Buffers (GPB) - gpb</t>

              <t>Thrift - thrift</t>
            </list></t>

          <t>In this example, the client advertises its (abbreviated)
          &lt;hello&gt; as follows. Some extra white spaces have been added
          for display purposes only.</t>

          <t><figure>
              <artwork><![CDATA[     <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <capabilities>
         <capability>urn:ietf:params:netconf:base:1.0</capability>
         <capability>urn:ietf:params:netconf:base:1.1</capability>
         <capability>
           urn:ietf:params:netconf:capability:encoding:1.0?format=
           application/cbor+sid,application/gpb,application/thrift
         </capability>
       </capabilities>
     </hello>]]></artwork>
            </figure></t>

          <t>The server supports the following encoding formats shown in no
          particular order of preference.</t>

          <t><list style="symbols">
              <t>cbor+sid</t>

              <t>gpb</t>
            </list></t>

          <t>In this example, the server advertises its (abbreviated)
          &lt;hello&gt; as follows. Some white spaces have been added for
          display purposes only.</t>

          <t><figure>
              <artwork><![CDATA[     <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <capabilities>
         <capability>urn:ietf:params:netconf:base:1.0</capability>
         <capability>urn:ietf:params:netconf:base:1.1</capability>
         <capability>
           urn:ietf:params:netconf:capability:encoding:1.0?
           format=application/cbor+sid,application/gpb
         </capability>
         <capability>
           urn:ietf:params:netconf:capability:config-id?id=2130
         </capability>
         <!--  rest of URIs ... -->
      </capabilities>
      <session-id>4</session-id>
     </hello>]]></artwork>
            </figure></t>

          <t>The common encoding formats in both the list are
          "application/cbor+sid", and "application/gpb", but since cbor+sid
          appear first on the client list, "application/cbor+sid" is selected
          as the form of encoding for the remainder of the session.</t>
        </section>

        <section title="Dependencies">
          <t>None.</t>
        </section>

        <section title="Capability Identifier">
          <t>The :encoding capability is identified by the following
          capability string:</t>

          <t>urn:ietf:params:netconf:capability:encoding:1.0?format={name,
          ...}</t>

          <t>The :encoding capability MUST be advertised in every server
          &lt;hello&gt; message and the URI MUST contain a "format" argument
          assigned a comma-separated list (with no white spaces) of formats
          supported by the device. For the list of supported formats, this
          document requests the creation of a new registry. See IANA
          Considerations for details.</t>

          <t>The client on the other hand SHOULD advertise this capability in
          its &lt;hello&gt; message, but it MAY omit it if XML encoding is
          desired.</t>

          <t>For example (line wrapped for display purposes only)</t>

          <t><figure>
              <artwork><![CDATA[urn:ietf:params:netconf:capability:encoding:1.0?format=
application/cbor+sid,application/gpb,application/thrift]]></artwork>
            </figure></t>
        </section>

        <section title="New Operations">
          <t>The :encoding capability does not introduce any new protocol
          operation.</t>
        </section>

        <section title="Modification to Existing Operations">
          <t>The :encoding capability does not modify any existing protocol
          operations.</t>
        </section>

        <section title="Interactions with Other Capabilities">
          <t>The :encoding capability does not interact with any other
          capabilities.</t>
        </section>
      </section>

      <section title="CBOR and SID">
        <t>One of the encoding formats that can be advertised by the client or
        the server is <xref target="RFC7049">CBOR</xref>. The payload consists
        of <xref target="RFC7950">YANG</xref> data, and YANG requires the use
        of unique identifiers, implemented in <xref
        target="RFC6241">NETCONF</xref> using names. To allow for encoding of
        YANG data models, a more compact method has been identified, called
        <xref target="I-D.ietf-core-yang-cbor">YANG Schema Item iDentifier
        (SID)</xref>. Clients and servers can advertise their capability for
        this form of encoding using "application/cbor+sid".</t>

        <t>SID does not define encoding for NETCONF operations today. It is
        expected that a new SID range would have to be identified for NETCONF
        protocol operations.</t>
      </section>
    </section>

    <!---->

    <section anchor="security" title="Security Considerations"/>

    <section anchor="iana" title="IANA Considerations">
      <t>This document registers a URI and requests the creation of a new
      registry.</t>

      <section title="NETCONF Capability URNs">
        <t>This document requests the registry of an URI in the <xref
        target="RFC3688">IETF XML registry</xref>. The IANA registry "Network
        Configuration Protocol (NETCONF) Capability URNs" needs to be updated
        to include the following capability.</t>

        <t><figure>
            <artwork><![CDATA[Index
    Capability Identifier
-------------------------
:encoding
    urn:ietf:params:netconf:capability:encoding:1.0]]></artwork>
          </figure></t>
      </section>

      <section title="New Registry">
        <t>The document also requests the creation of a new registry, called
        "Network Configuration Protocol (NETCONF) Encoding formats", that
        should be populated with the following entries.</t>

        <t><figure>
            <artwork><![CDATA[Encoding Formats
----------------
cbor+sid
gpb
thrift]]></artwork>
          </figure></t>
      </section>
    </section>

    <section anchor="ack" title="Acknowledgements">
      <t>The authors would like to thank Juergen Schoenwaeider for his
      comments on the draft.</t>
    </section>

    <!---->
  </middle>

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

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

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

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

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

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

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

      <?rfc include='reference.I-D.ietf-core-yang-cbor'?>
    </references>

    <references title="Informative References">
      <?rfc include='reference.RFC.7951'?>
    </references>
  </back>
</rfc>
