Internet DRAFT - draft-mahesh-netconf-binary-encoding

draft-mahesh-netconf-binary-encoding







NETCONF WG                                               M. Jethanandani
Internet-Draft
Updates: 6241 (if approved)                                       J. Lam
Intended status: Standards Track                                A. Leung
Expires: January 1, 2019                             Cisco Systems, Inc.
                                                              A. Bierman
                                                         YumaWorks, Inc.
                                                           June 30, 2018


                      Binary Encoding for NETCONF
                draft-mahesh-netconf-binary-encoding-01

Abstract

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

   This document updates RFC 6241.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on January 1, 2019.

Copyright Notice

   Copyright (c) 2018 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must



Jethanandani, et al.     Expires January 1, 2019                [Page 1]

Internet-Draft               Binary Encoding                   June 2018


   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Protocol Negotiation  . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Encoding  . . . . . . . . . . . . . . . . . . . . . . . .   3
       2.1.1.  Overview  . . . . . . . . . . . . . . . . . . . . . .   3
       2.1.2.  Example . . . . . . . . . . . . . . . . . . . . . . .   4
       2.1.3.  Dependencies  . . . . . . . . . . . . . . . . . . . .   5
       2.1.4.  Capability Identifier . . . . . . . . . . . . . . . .   5
       2.1.5.  New Operations  . . . . . . . . . . . . . . . . . . .   6
       2.1.6.  Modification to Existing Operations . . . . . . . . .   6
       2.1.7.  Interactions with Other Capabilities  . . . . . . . .   6
     2.2.  CBOR and SID  . . . . . . . . . . . . . . . . . . . . . .   6
   3.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
     4.1.  NETCONF Capability URNs . . . . . . . . . . . . . . . . .   6
     4.2.  New Registry  . . . . . . . . . . . . . . . . . . . . . .   7
   5.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   7
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     6.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   NETCONF [RFC6241], 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.

   Several encoding mechanisms have been proposed, including CBOR
   [RFC7049] and JSON [RFC8259].  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 CBOR
   Encoding of Data Modeled with YANG [I-D.ietf-core-yang-cbor] and JSON
   Encoding of Data Modeled with YANG [RFC7951].

   This document updates NETCONF [RFC6241].




Jethanandani, et al.     Expires January 1, 2019                [Page 2]

Internet-Draft               Binary Encoding                   June 2018


1.1.  Terminology

   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 BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Protocol Negotiation

   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 NETCONF [RFC6241] and the YANG data within the Message
   Layer, are in the form of new encoding.  This includes RPC, Actions
   and Notifications.

   This draft suggests advertisement of the following additional
   capability.

2.1.  Encoding

2.1.1.  Overview

   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.

   Both the client and server examine each others <hello> 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 <rpc> request.
   All <rpc>, <rpc-reply>, <action> and <notification> messages MUST be
   encoded in this negotiated encoding.

   Both the client and the server MUST support the "application/xml"
   media type to be backward compatible with NETCONF [RFC6241].

   The base:1.1 negotiation defined in NETCONF [RFC6241] determines the
   message framing that is used for the entire session.



Jethanandani, et al.     Expires January 1, 2019                [Page 3]

Internet-Draft               Binary Encoding                   June 2018


2.1.2.  Example

   In this example, the client supports the following encoding formats
   shown in a preferred order.

   o  Concise Binary Object Representation (CBOR) with YANG Schema Item
      iDentifier (SID) - cbor+sid

   o  Google Protocol Buffers (GPB) - gpb

   o  Thrift - thrift

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

        <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>

   The server supports the following encoding formats shown in no
   particular order of preference.

   o  cbor+sid

   o  gpb

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














Jethanandani, et al.     Expires January 1, 2019                [Page 4]

Internet-Draft               Binary Encoding                   June 2018


        <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>

   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.

2.1.3.  Dependencies

   None.

2.1.4.  Capability Identifier

   The :encoding capability is identified by the following capability
   string:

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

   The :encoding capability MUST be advertised in every server <hello>
   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.

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

   For example (line wrapped for display purposes only)

   urn:ietf:params:netconf:capability:encoding:1.0?format=
   application/cbor+sid,application/gpb,application/thrift





Jethanandani, et al.     Expires January 1, 2019                [Page 5]

Internet-Draft               Binary Encoding                   June 2018


2.1.5.  New Operations

   The :encoding capability does not introduce any new protocol
   operation.

2.1.6.  Modification to Existing Operations

   The :encoding capability does not modify any existing protocol
   operations.

2.1.7.  Interactions with Other Capabilities

   The :encoding capability does not interact with any other
   capabilities.

2.2.  CBOR and SID

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

   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.

3.  Security Considerations

4.  IANA Considerations

   This document registers a URI and requests the creation of a new
   registry.

4.1.  NETCONF Capability URNs

   This document requests the registry of an URI in the IETF XML
   registry [RFC3688].  The IANA registry "Network Configuration
   Protocol (NETCONF) Capability URNs" needs to be updated to include
   the following capability.








Jethanandani, et al.     Expires January 1, 2019                [Page 6]

Internet-Draft               Binary Encoding                   June 2018


   Index
       Capability Identifier
   -------------------------
   :encoding
       urn:ietf:params:netconf:capability:encoding:1.0

4.2.  New Registry

   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.

   Encoding Formats
   ----------------
   cbor+sid
   gpb
   thrift

5.  Acknowledgements

   The authors would like to thank Juergen Schoenwaeider for his
   comments on the draft.

6.  References

6.1.  Normative References

   [I-D.ietf-core-yang-cbor]
              Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A.
              Minaburo, "CBOR Encoding of Data Modeled with YANG",
              draft-ietf-core-yang-cbor-06 (work in progress), February
              2018.

   [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>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [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>.





Jethanandani, et al.     Expires January 1, 2019                [Page 7]

Internet-Draft               Binary Encoding                   June 2018


   [RFC7049]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
              October 2013, <https://www.rfc-editor.org/info/rfc7049>.

   [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>.

   [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>.

   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

6.2.  Informative References

   [RFC7951]  Lhotka, L., "JSON Encoding of Data Modeled with YANG",
              RFC 7951, DOI 10.17487/RFC7951, August 2016,
              <https://www.rfc-editor.org/info/rfc7951>.

Authors' Addresses

   Mahesh Jethanandani

   Email: mjethanandani@gmail.com


   Jason Lam
   Cisco Systems, Inc.

   Email: lamj@cisco.com


   Alfred Leung
   Cisco Systems, Inc.

   Email: alfleung@cisco.com


   Andy Bierman
   YumaWorks, Inc.

   Email: andy@yumaworks.com





Jethanandani, et al.     Expires January 1, 2019                [Page 8]