idnits 2.17.00 (12 Aug 2021) /tmp/idnits31474/draft-mahesh-netconf-binary-encoding-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC6241]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 30, 2018) is 1414 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-06 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF WG M. Jethanandani 3 Internet-Draft 4 Updates: 6241 (if approved) J. Lam 5 Intended status: Standards Track A. Leung 6 Expires: January 1, 2019 Cisco Systems, Inc. 7 A. Bierman 8 YumaWorks, Inc. 9 June 30, 2018 11 Binary Encoding for NETCONF 12 draft-mahesh-netconf-binary-encoding-01 14 Abstract 16 This document describes a method by which a NETCONF [RFC6241] client 17 and server can negotiate an alternate form of encoding. 19 This document updates RFC 6241. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 1, 2019. 38 Copyright Notice 40 Copyright (c) 2018 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Protocol Negotiation . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 3 60 2.1.2. Example . . . . . . . . . . . . . . . . . . . . . . . 4 61 2.1.3. Dependencies . . . . . . . . . . . . . . . . . . . . 5 62 2.1.4. Capability Identifier . . . . . . . . . . . . . . . . 5 63 2.1.5. New Operations . . . . . . . . . . . . . . . . . . . 6 64 2.1.6. Modification to Existing Operations . . . . . . . . . 6 65 2.1.7. Interactions with Other Capabilities . . . . . . . . 6 66 2.2. CBOR and SID . . . . . . . . . . . . . . . . . . . . . . 6 67 3. Security Considerations . . . . . . . . . . . . . . . . . . . 6 68 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 69 4.1. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 6 70 4.2. New Registry . . . . . . . . . . . . . . . . . . . . . . 7 71 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 72 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 74 6.2. Informative References . . . . . . . . . . . . . . . . . 8 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 77 1. Introduction 79 NETCONF [RFC6241], by default, supports XML encoding for its payload. 80 However, XML can be very verbose, specially for operational data. 81 This document proposes a mechanism by which clients and servers can 82 negotiate an alternate form of encoding, e.g. binary encoding, and 83 use that to exchange data. Binary encoding can reduce the physical 84 size of the data exchanged, in some cases by as much as 66%, while 85 preserving the original data. 87 Several encoding mechanisms have been proposed, including CBOR 88 [RFC7049] and JSON [RFC8259]. This document does not advocate any 89 particular encoding format. Instead, it leaves it up to the 90 negotiation between client and server to decide the form of encoding. 91 For an example of how to encode YANG in CBOR format, see CBOR 92 Encoding of Data Modeled with YANG [I-D.ietf-core-yang-cbor] and JSON 93 Encoding of Data Modeled with YANG [RFC7951]. 95 This document updates NETCONF [RFC6241]. 97 1.1. Terminology 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 101 "OPTIONAL" in this document are to be interpreted as described in BCP 102 14 [RFC2119] [RFC8174] when, and only when, they appear in all 103 capitals, as shown here. 105 2. Protocol Negotiation 107 NETCONF clients and servers exchange a hello as part of establishing 108 a connection. As part of the hello exchange, the client advertises 109 an ordered list of encoding it would like to use, while the server 110 advertises an unordered list of encoding that it is capable of 111 supporting. If no match of encoding is found, the session is 112 dropped. If a match is found the client issues a request that is 113 encoded with first match found. Thereafter, both the Message layer 114 in Figure 1 of NETCONF [RFC6241] and the YANG data within the Message 115 Layer, are in the form of new encoding. This includes RPC, Actions 116 and Notifications. 118 This draft suggests advertisement of the following additional 119 capability. 121 2.1. Encoding 123 2.1.1. Overview 125 The :encoding capability indicates what alternate encoding format 126 each side is willing to support. The client and server send a comma 127 separated list (with no white spaces) of encoding formats they are 128 willing to support. The client sends a list of encoding ordered by 129 preference, while the server includes an unordered list of encoding. 131 Both the client and server examine each others message for 132 this capability. If not present, the default encoding is used, which 133 is XML. The client examines its list against the server list, 134 checked in the order of preference it sent do the server. If a 135 matching encoding format is found, the client picks that encoding for 136 the remainder of the session, starting with the first request. 137 All , , and messages MUST be 138 encoded in this negotiated encoding. 140 Both the client and the server MUST support the "application/xml" 141 media type to be backward compatible with NETCONF [RFC6241]. 143 The base:1.1 negotiation defined in NETCONF [RFC6241] determines the 144 message framing that is used for the entire session. 146 2.1.2. Example 148 In this example, the client supports the following encoding formats 149 shown in a preferred order. 151 o Concise Binary Object Representation (CBOR) with YANG Schema Item 152 iDentifier (SID) - cbor+sid 154 o Google Protocol Buffers (GPB) - gpb 156 o Thrift - thrift 158 In this example, the client advertises its (abbreviated) as 159 follows. Some extra white spaces have been added for display 160 purposes only. 162 163 164 urn:ietf:params:netconf:base:1.0 165 urn:ietf:params:netconf:base:1.1 166 167 urn:ietf:params:netconf:capability:encoding:1.0?format= 168 application/cbor+sid,application/gpb,application/thrift 169 170 171 173 The server supports the following encoding formats shown in no 174 particular order of preference. 176 o cbor+sid 178 o gpb 180 In this example, the server advertises its (abbreviated) as 181 follows. Some white spaces have been added for display purposes 182 only. 184 185 186 urn:ietf:params:netconf:base:1.0 187 urn:ietf:params:netconf:base:1.1 188 189 urn:ietf:params:netconf:capability:encoding:1.0? 190 format=application/cbor+sid,application/gpb 191 192 193 urn:ietf:params:netconf:capability:config-id?id=2130 194 195 196 197 4 198 200 The common encoding formats in both the list are "application/ 201 cbor+sid", and "application/gpb", but since cbor+sid appear first on 202 the client list, "application/cbor+sid" is selected as the form of 203 encoding for the remainder of the session. 205 2.1.3. Dependencies 207 None. 209 2.1.4. Capability Identifier 211 The :encoding capability is identified by the following capability 212 string: 214 urn:ietf:params:netconf:capability:encoding:1.0?format={name, ...} 216 The :encoding capability MUST be advertised in every server 217 message and the URI MUST contain a "format" argument assigned a 218 comma-separated list (with no white spaces) of formats supported by 219 the device. For the list of supported formats, this document 220 requests the creation of a new registry. See IANA Considerations for 221 details. 223 The client on the other hand SHOULD advertise this capability in its 224 message, but it MAY omit it if XML encoding is desired. 226 For example (line wrapped for display purposes only) 228 urn:ietf:params:netconf:capability:encoding:1.0?format= 229 application/cbor+sid,application/gpb,application/thrift 231 2.1.5. New Operations 233 The :encoding capability does not introduce any new protocol 234 operation. 236 2.1.6. Modification to Existing Operations 238 The :encoding capability does not modify any existing protocol 239 operations. 241 2.1.7. Interactions with Other Capabilities 243 The :encoding capability does not interact with any other 244 capabilities. 246 2.2. CBOR and SID 248 One of the encoding formats that can be advertised by the client or 249 the server is CBOR [RFC7049]. The payload consists of YANG [RFC7950] 250 data, and YANG requires the use of unique identifiers, implemented in 251 NETCONF [RFC6241] using names. To allow for encoding of YANG data 252 models, a more compact method has been identified, called YANG Schema 253 Item iDentifier (SID) [I-D.ietf-core-yang-cbor]. Clients and servers 254 can advertise their capability for this form of encoding using 255 "application/cbor+sid". 257 SID does not define encoding for NETCONF operations today. It is 258 expected that a new SID range would have to be identified for NETCONF 259 protocol operations. 261 3. Security Considerations 263 4. IANA Considerations 265 This document registers a URI and requests the creation of a new 266 registry. 268 4.1. NETCONF Capability URNs 270 This document requests the registry of an URI in the IETF XML 271 registry [RFC3688]. The IANA registry "Network Configuration 272 Protocol (NETCONF) Capability URNs" needs to be updated to include 273 the following capability. 275 Index 276 Capability Identifier 277 ------------------------- 278 :encoding 279 urn:ietf:params:netconf:capability:encoding:1.0 281 4.2. New Registry 283 The document also requests the creation of a new registry, called 284 "Network Configuration Protocol (NETCONF) Encoding formats", that 285 should be populated with the following entries. 287 Encoding Formats 288 ---------------- 289 cbor+sid 290 gpb 291 thrift 293 5. Acknowledgements 295 The authors would like to thank Juergen Schoenwaeider for his 296 comments on the draft. 298 6. References 300 6.1. Normative References 302 [I-D.ietf-core-yang-cbor] 303 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 304 Minaburo, "CBOR Encoding of Data Modeled with YANG", 305 draft-ietf-core-yang-cbor-06 (work in progress), February 306 2018. 308 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 309 Requirement Levels", BCP 14, RFC 2119, 310 DOI 10.17487/RFC2119, March 1997, 311 . 313 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 314 DOI 10.17487/RFC3688, January 2004, 315 . 317 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 318 and A. Bierman, Ed., "Network Configuration Protocol 319 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 320 . 322 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 323 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 324 October 2013, . 326 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 327 RFC 7950, DOI 10.17487/RFC7950, August 2016, 328 . 330 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 331 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 332 May 2017, . 334 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 335 Interchange Format", STD 90, RFC 8259, 336 DOI 10.17487/RFC8259, December 2017, 337 . 339 6.2. Informative References 341 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 342 RFC 7951, DOI 10.17487/RFC7951, August 2016, 343 . 345 Authors' Addresses 347 Mahesh Jethanandani 349 Email: mjethanandani@gmail.com 351 Jason Lam 352 Cisco Systems, Inc. 354 Email: lamj@cisco.com 356 Alfred Leung 357 Cisco Systems, Inc. 359 Email: alfleung@cisco.com 361 Andy Bierman 362 YumaWorks, Inc. 364 Email: andy@yumaworks.com