NETMOD Working Group M. Richardson
Internet-Draft Sandelman Software Works
Intended status: Standards Track 31 March 2025
Expires: 2 October 2025
Extending YANG modules at runtime
draft-richardson-netmod-atrest-extensions-01
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 2 October 2025.
Richardson Expires 2 October 2025 [Page 1]
Internet-Draft yang-extensions March 2025
Copyright Notice
Copyright (c) 2025 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 include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3
3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Extensions . . . . . . . . . . . . . . . . . . . . . . . 3
4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 4
5. Security Considerations . . . . . . . . . . . . . . . . . . . 4
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4
8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 4
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 4
9.1. Normative References . . . . . . . . . . . . . . . . . . 4
9.2. Informative References . . . . . . . . . . . . . . . . . 5
Appendix A. Appendix A: Example module and extension . . . . . . 5
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5
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].
Richardson Expires 2 October 2025 [Page 2]
Internet-Draft yang-extensions March 2025
[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 this module.
(XXX- this assumes per-module extensions, vs a global set of
extensions that could be used by many modules)
Richardson Expires 2 October 2025 [Page 3]
Internet-Draft yang-extensions March 2025
Extension documents are presented as new YANG modules. They are
_not_ defined using augment against the original module.
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.
When encoding YANG as JSON, a sub-map is also used. The key for the
sub-map is the YANG module name for the extension. Within the sub-
map, normal JSON encoding rules are used. (This is in contrast to
example in [RFC8520] in which a colon-joined key is used, and no sub-
map is used)
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, March 1997,
<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,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
Richardson Expires 2 October 2025 [Page 4]
Internet-Draft yang-extensions March 2025
[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, July 2022,
<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,
July 2024, <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-13, 18 February 2025,
<https://datatracker.ietf.org/doc/html/draft-ietf-anima-
rfc8366bis-13>.
[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-07, 21 October 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-opsawg-
ol-07>.
[RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert,
"A Voucher Artifact for Bootstrapping Protocols",
RFC 8366, DOI 10.17487/RFC8366, May 2018,
<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, March 2019,
<https://www.rfc-editor.org/info/rfc8520>.
[RFC8528] Bjorklund, M. and L. Lhotka, "YANG Schema Mount",
RFC 8528, DOI 10.17487/RFC8528, March 2019,
<https://www.rfc-editor.org/info/rfc8528>.
Appendix A. Appendix A: Example module and extension
TODO.
Author's Address
Richardson Expires 2 October 2025 [Page 5]
Internet-Draft yang-extensions March 2025
Michael Richardson
Sandelman Software Works
Email: mcr+ietf@sandelman.ca
Richardson Expires 2 October 2025 [Page 6]