]> CZ.NIC

Milesovska 1136/5 Praha 13000 Czechia maria.matejka@nic.cz mq@jmq.cz

Operations and Management Network Modeling next generation unicorn sparkling distributed ledger YANG (RFC 7950) is a standardized data modeling language. The data may be encoded in XML (RFC 7950), JSON (RFC 7951), plain CBOR (RFC 9254) or CBOR with standins (draft-bormann-cbor-yang-standin). This document specifies how to convert data modeled by YANG encoded in one of the formats into another format. Use cases include e.g. local transcoding between Netconf and Restconf for tool compatibility, or reverse proxying while composing multiple backends. This document also defines a data annotation for additional value type specification. That data annotation behavior updates RFC 7950, RFC 7951 and RFC 9254. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Network Modeling Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Current documents focus on encoding and specifying data for a simple round-trip between a source encoder and a destination decoder. While at least touches the topic of RESTCONF and NETCONF () coexisting at one device, there has not yet been any specification for chaining multiple encodings. At the time of this document, there are at least four kinds of data encoding (XML, JSON, plain CBOR and standin CBOR) and at least three protocol variants (NETCONF, RESTCONF and CORECONF). Implementing all of these may be too costly, and therefore users will tend to deploy convertor tools and proxies to align the otherwise incompatible data and protocols. One major usecase for this specification is a simple proxy to bridge clients and servers implementing incompatible encodings. Another example usecase is a reverse proxy used as a single endpoint for a device with multiple internal endpoint. Such a proxy may be transparent when the user knowingly deployed it, or opaque if it's a part of a third party device. The user may even be completely unaware of such a proxy existing.

Conventions and Definitions 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 when, and only when, they appear in all capitals, as shown here. TODO: define terms like Transcoder, Composer or XML Round Trip.

Transcoding Data Formats Encoding capabilities of XML, JSON or CBOR are quite different. While all values in XML are strings, JSON knows also booleans and integers, and CBOR may even use the tag features to encode various additional types, like time values or IP addresses, as specified in . This effectively means that a transcoding node either loses type information, or it must infer that information from the data representation. Generally, a transcoder MUST interpret the incoming data according to the appropriate YANG model, and choose the appropriate output representation for each value according to the model. Transcoders also SHOULD validate the data and issue appropriate error messages to the user. Otherwise, the user may get confused by an error message proxied from the endpoint, referring to a different data format than the user is using. Transcoders SHOULD quietly canonicalize value representations according to the YANG model. Since by most types have a canonical representation which MUST be used for all conceivable purposes, it's expected that no valuable information is lost by such conversion. However, transcoders MUST NOT perform any value conversion which loses data precision. Examples: For leaf item { type int32; }, it's expected that <item>+3</item> in XML gets converted to "item": 3 in JSON, and by that the value representation loses its original non-canonical string representation. For leaf item { type string; }, it's expected that <item>+3</item> in XML gets converted to "item": "+3" in JSON. Transcoders MAY choose to warn users when they are converting a non-canonical value representation. TODO: add CBOR examples

The union Built-In Type According to , it's possible to specify that a value may be of several types. Transcoders SHOULD perform a conceptual round-trip of converting such value to the XML representation and back, to check that the resulting value is indeed interpreted as the same type as in the original representation. Example: If the received JSON data is "item": "+3", the type is to be interpreted as a string, according to . Yet, after encoding to XML, the type information is lost and the value gets reinterpreted as a number. Transcoders SHOULD issue a warning every time a union-type value is reinterpreted as another member type, to avoid possible user confusion, unless the Original Type Annotation is used and known to be understood by the other party.

Netconf Reinterpretation Warning An additional error tag is specified for NETCONF, and by extension to RESTCONF and CORECONF. : identifies the elements in the data model which the proxy had to reinterpret to another type. May appear multiple times. Description: An element value has been supplied with an additional type information which could not be conveyed to the final destination, and by dropping this information, the value got reinterpreted as a different type. ]]> TODO: properly augment ietf-netconf:error-tag-type.

Original type annotation In order to keep the type information with the value even through conversion, transcoders (and generally encoders) MAY attach a type annotation to such a value. The following module defines the "original-type" annotation. Example: <item ot:original-type="string">+3</item> If the Original Type Annotation is used and understood, contrary to what is specified in , the received value MUST be validated first against the specified original type, and SHOULD NOT be accepted as any other member type, even if a match is found. By the same logic, this extends , so that not only the implicit encoding of the value is taken into account, but also the Original Type Annotation if present. TODO: make an annotation draft for CBOR by tagging keys. When encoding and decoding in and from CBOR with Standins (), a standin SHOULD be used whenever possible. Specifying the Original Type Annotation also resolves possible problems with unions containing leafref as a member type. The example in becomes much simpler by explicitly indicating whether the value is intended to be interpreted as a leafref or something else. Most notably, the original specification requires revalidation every time the target instance may have been added or deleted, which may be error-prone for development and costly for operations.

Proxying NETCONF, RESTCONF and CORECONF protocols If the node behaves as a proxy between different protocols, it should translate as wide range of requests as realistically possible. When the request is impossible to be fulfilled because the underlying protocol lacks the needed capabilities, the proxy MUST indicate this failure by a rpc-error response with the error-tag set to operation-not-supported. For example, the NETCONF operations <lock> and <unlock> are not defined for RESTCONF, and therefore the implementation needs to decide whether to plainly refuse them, or to somehow emulate the overall effect. When a single request can't be translated to a single underlying request, the proxy may instead perform multiple consecutive requests. If any of these requests fails, the proxy MUST issue appropriate rollback requests, and properly relay all errors, so that the original request's semantics is kept intact. For example, if a complex RESTCONF PATCH operation can't be translated to one NETCONF request, the proxy may choose to issue <lock>, perform multiple edits and finalize by <unlock>. If such an edit fails half-way, the proxy must revert it before unlocking and failing, so that the RESTCONF operation fails cleanly. Detailed specification of request and response translation is out of scope of this document, and may depend on exact context and even be specific for the YANG models supported.

Operational Considerations Running proxies always adds inherent complexity into the network, and it may be better to look for tools natively supporting the required protocol, instead of deploying a proxy. For device vendors, running a proxy may be an only solution. If a device exposes a summary endpoint by a proxy over several sub-endpoints, it is recommended to not expose the sub-endpoints even just for debug purposes, as accessing a sub-endpoint directly may break some consistency expectations on the proxy.

Security Considerations It's required by that all NETCONF connections provide authentication, data integrity, confidentiality and replay protection. While different proxies may handle these aspects differently, it MUST be documented how these are handled. Specifically if authentication is terminated at a proxy, the underlying endpoints MUST be isolated in such a way that they are only accessible through the proxy.

IANA Considerations TODO: Do we need to require registration of the YANG module for the Original Type Annotation? Otherwise: This document has no IANA actions.

Normative References The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK] YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF). This document defines encoding rules for representing configuration data, state data, parameters of Remote Procedure Call (RPC) operations or actions, and notifications defined using YANG as JavaScript Object Notation (JSON) text. This document defines a YANG extension that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes. This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). YANG (RFC 7950) is a data modeling language used to model configuration data, state data, parameters and results of Remote Procedure Call (RPC) operations or actions, and notifications. This document defines encoding rules for YANG in the Concise Binary Object Representation (CBOR) (RFC 8949). Universität Bremen TZI CZ.NIC YANG (RFC 7950) is a data modeling language used to model configuration data, state data, parameters and results of Remote Procedure Call (RPC) operations or actions, and notifications. YANG-CBOR (RFC 9254) defines encoding rules for YANG in the Concise Binary Object Representation (CBOR) (RFC 8949). While the overall structure of YANG-CBOR is encoded in an efficient, binary format, YANG itself has its roots in XML and therefore traditionally encodes some information such as date/times and IP addresses/prefixes in a verbose text form. This document defines how to use existing CBOR tags for this kind of information in YANG-CBOR as a "stand-in" for the text-based information that would be found in the original form of YANG-CBOR. Trilliant Networks Inc. consultant IMT Atlantique YumaWorks Universität Bremen TZI This document describes a network management interface for constrained devices and networks, called CoAP Management Interface (CORECONF). The Constrained Application Protocol (CoAP) is used to access datastore and data node resources specified in YANG, or SMIv2 converted to YANG. CORECONF uses the YANG to CBOR mapping and converts YANG identifier strings to numeric identifiers for payload size reduction. CORECONF extends the set of YANG based protocols, NETCONF and RESTCONF, with the capability to manage constrained devices and networks. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Acknowledgments This document is a result of prior work of Maria Matějka and Carsten Bormann on , and design discussions with Vojtěch Vilímek over a NETCONF-RESTCONF-CORECONF proxy.