Internet-Draft yang-extensions September 2024
Richardson Expires 31 March 2025 [Page]
Workgroup:
NETMOD Working Group
Internet-Draft:
draft-richardson-netmod-atrest-extensions-00
Published:
Intended Status:
Standards Track
Expires:
Author:
M. Richardson
Sandelman Software Works

Extending YANG modules at runtime

Abstract

This document describes a mechanism of signaling extensions to YANG modules that can be used when YANG is not used in an online fashion.

About This Document

This note is to be removed before publishing as an RFC.

Status information for this document may be found at https://datatracker.ietf.org/doc/draft-richardson-netmod-atrest-extensions/.

Discussion of this document takes place on the cbor Working Group mailing list (mailto:cbor@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/cbor/. Subscribe at https://www.ietf.org/mailman/listinfo/cbor/.

Source for this draft and an issue tracker can be found at https://github.com/mcr/yang-extensions-at-reset.

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 31 March 2025.

Table of Contents

1. Introduction

In the process of revising [RFC8366] to accomodate needed extensions an effort was initially made to do this using augment (cite) and later augment-structure. [RFC8366] is a digitally signed voucher format used in onboarding of new devices. It is a file format that may be transmitted over CoAP, HTTP or via USB key, but it does not use RESTCONF. The contents of the file are not subject to negotiation as might be done with [RFC8528].

Rather than have each topic document define the relevant extensions needed, it turned out to be necessary to collect all the extensions necessary into a single revision to the YANG module, which is being produced as [I-D.ietf-anima-rfc8366bis].

[RFC8520] is like [RFC8366]: it is a file format. When [RFC8520] was defined, it anticipated that there would be future extensions, and defined a YANG leaf called "extensions" which is a list of subsequent YANG modules which are included. This is being used to define, for instance, [I-D.ietf-opsawg-ol].

When YANG is serialized to XML or JSON, the keys used in the attribute map are strings, and so it seems relatively straightforward for a human programmer to understand how to insert these new keys into the same attribute map. YANG however, is intended to be machine parseable, and [RFC9254] provides a way to serialize YANG to CBOR. While strings can be used if necessary, the preferred method is via YANG-SID values, allocated for instance, via [RFC9595]. It is not obvious how an extension mechanism as described by [RFC8520] can be efficiently encoded to CBOR, nor how YANG tooling should react to these ad-hoc extensions.

This document makes the [RFC8520] extension mechanism a generic mechanism that can be used by any YANG module, and explains how to efficiently encode this to CBOR using YANG-SID.

2. 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.1. Motivation

XXX - Do we need more details about the motivation?

3. Protocol

3.1. Extensions

A YANG module that expects to have extensions establishes an attribute called "extensions" This attribute value is a list of extensions that are included in this object. This set of available values is established as an IANA registry by the document defining the module.

(XXX- this assumes per-module extensions, vs a global set of extensions that could be used by many modules)

When encoding YANG as CBOR, in order to encode the additional attributes defined by that extension, a new sub-map is created. The key for this sub-map, in the parent map, consists of the YANG module SID, encoded using the CBOR Tag 47, the tag for an absolute SID. Within the sub-map, the normal delta-encoding is used, using the SID values allocated for that module.

(XXX- the submap should allow to XML and JSON too?)

4. Privacy Considerations

YYY

5. Security Considerations

ZZZ

6. IANA Considerations

7. Acknowledgements

Hello.

8. Changelog

9. References

9.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC9254]
Veillette, M., Ed., Petrov, I., Ed., Pelov, A., Bormann, C., and M. Richardson, "Encoding of Data Modeled with YANG in the Concise Binary Object Representation (CBOR)", RFC 9254, DOI 10.17487/RFC9254, , <https://www.rfc-editor.org/info/rfc9254>.
[RFC9595]
Veillette, M., Ed., Pelov, A., Ed., Petrov, I., Ed., Bormann, C., and M. Richardson, "YANG Schema Item iDentifier (YANG SID)", RFC 9595, DOI 10.17487/RFC9595, , <https://www.rfc-editor.org/info/rfc9595>.

9.2. Informative References

[I-D.ietf-anima-rfc8366bis]
Watsen, K., Richardson, M., Pritikin, M., Eckert, T. T., and Q. Ma, "A Voucher Artifact for Bootstrapping Protocols", Work in Progress, Internet-Draft, draft-ietf-anima-rfc8366bis-12, , <https://datatracker.ietf.org/doc/html/draft-ietf-anima-rfc8366bis-12>.
[I-D.ietf-opsawg-ol]
Lear, E. and C. Bormann, "Ownership and licensing statements in YANG", Work in Progress, Internet-Draft, draft-ietf-opsawg-ol-06, , <https://datatracker.ietf.org/doc/html/draft-ietf-opsawg-ol-06>.
[RFC8366]
Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, "A Voucher Artifact for Bootstrapping Protocols", RFC 8366, DOI 10.17487/RFC8366, , <https://www.rfc-editor.org/info/rfc8366>.
[RFC8520]
Lear, E., Droms, R., and D. Romascanu, "Manufacturer Usage Description Specification", RFC 8520, DOI 10.17487/RFC8520, , <https://www.rfc-editor.org/info/rfc8520>.
[RFC8528]
Bjorklund, M. and L. Lhotka, "YANG Schema Mount", RFC 8528, DOI 10.17487/RFC8528, , <https://www.rfc-editor.org/info/rfc8528>.

Author's Address

Michael Richardson
Sandelman Software Works