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 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 request. All , , and 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) as follows. Some extra white spaces have been added for display purposes only. urn:ietf:params:netconf:base:1.0 urn:ietf:params:netconf:base:1.1 urn:ietf:params:netconf:capability:encoding:1.0?format= application/cbor+sid,application/gpb,application/thrift 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) 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 urn:ietf:params:netconf:base:1.0 urn:ietf:params:netconf:base:1.1 urn:ietf:params:netconf:capability:encoding:1.0? format=application/cbor+sid,application/gpb urn:ietf:params:netconf:capability:config-id?id=2130 4 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 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 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, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . [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, . 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, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . 6.2. Informative References [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, . 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]