More Control Operators for CDDL
draft-ietf-cbor-cddl-more-control-01
The information below is for an old version of the document.
Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
---|---|---|---|
Author | Carsten Bormann | ||
Last updated | 2023-12-07 (Latest revision 2023-06-14) | ||
Replaces | draft-bormann-cbor-cddl-more-control | ||
RFC stream | Internet Engineering Task Force (IETF) | ||
Formats | |||
Reviews |
ARTART Last Call Review due 2024-11-20
Incomplete
|
||
Additional resources | Mailing list discussion | ||
Stream | WG state | WG Document | |
Document shepherd | (None) | ||
IESG | IESG state | I-D Exists | |
Consensus boilerplate | Unknown | ||
Telechat date | (None) | ||
Responsible AD | (None) | ||
Send notices to | (None) |
draft-ietf-cbor-cddl-more-control-01
Network Working Group C. Bormann Internet-Draft Universität Bremen TZI Intended status: Standards Track 7 December 2023 Expires: 9 June 2024 More Control Operators for CDDL draft-ietf-cbor-cddl-more-control-01 Abstract The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. RFCs have added to this extension point both in an application-specific and a more general way. The present document defines a number of additional generally applicable control operators for text conversion (Bytes, Integers, JSON, Printf-style formatting), operations on text, and deterministic encoding. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://cbor- wg.github.io/cddl-more-control/. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf- cbor-cddl-more-control/. Discussion of this document takes place on the Concise Binary Object Representation (CBOR) Maintenance and Extensions 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/cbor-wg/cddl-more-control. 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/. Bormann Expires 9 June 2024 [Page 1] Internet-Draft CDDL control operators December 2023 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 9 June 2024. Copyright Notice Copyright (c) 2023 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 2. Text Conversion . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Byte Strings: Base16 (Hex), Base32, Base64 . . . . . . . 4 2.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3. Printf-style Formatting . . . . . . . . . . . . . . . . . 6 2.4. JSON Values . . . . . . . . . . . . . . . . . . . . . . . 7 3. Text Processing . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Join . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. Deterministic Encoding . . . . . . . . . . . . . . . . . . . 8 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 10 7. Security considerations . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 8.2. Informative References . . . . . . . . . . . . . . . . . 12 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 Bormann Expires 9 June 2024 [Page 2] Internet-Draft CDDL control operators December 2023 1. Introduction The Concise Data Definition Language (CDDL), standardized in [RFC8610], provides "control operators" as its main language extension point (Section 3.8 of [RFC8610]). RFCs have added to this extension point both in an application-specific [RFC9090] and a more general [RFC9165] way. The present document defines a number of additional generally applicable control operators: +===============+=======================================+ | Name | Purpose | +===============+=======================================+ | .b64u, .b64c | Base64 representation of byte strings | +---------------+---------------------------------------+ | .b64u-sloppy, | (sloppy-tolerant variants of the | | .b64c-sloppy | above) | +---------------+---------------------------------------+ | .hex, .hexlc, | Base16 representation of byte strings | | .hexuc | | +---------------+---------------------------------------+ | .b32, .h32 | Base32 representation of byte strings | +---------------+---------------------------------------+ | .b45 | Base45 representation of byte strings | +---------------+---------------------------------------+ | .decimal | Text representation of integer | | | numbers | +---------------+---------------------------------------+ | .printf | Printf-formatted text representation | | | of data items | +---------------+---------------------------------------+ | .json | Text representation of JSON values | +---------------+---------------------------------------+ | .join | Building text from array of | | | components | +---------------+---------------------------------------+ | .cbordet, | deterministically encoded CBOR data | | .cborseqdet | items, CBOR sequences | +---------------+---------------------------------------+ Table 1: New control operators in this document Bormann Expires 9 June 2024 [Page 3] Internet-Draft CDDL control operators December 2023 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. This specification uses terminology from [RFC8610]. In particular, with respect to control operators, "target" refers to the left-hand side operand, and "controller" to the right-hand side operand. "Tool" refers to tools along the lines of that described in Appendix F of [RFC8610]. Note also that the data model underlying CDDL provides for text strings as well as byte strings as two separate types, which are then collectively referred to as "strings". 2. Text Conversion 2.1. Byte Strings: Base16 (Hex), Base32, Base64 A CDDL model often defines data that are byte strings in essence but need to be transported in various encoded forms, such as base64 or hex. This section defines a number of control operators to model these conversions. The control operators generally are of a form that could be used like this: signature-for-json = text .b64u signature signature = bytes .cbor COSE_Sign1 The specification of these control operators is complicated by the large number of transformations in use. Inspired by Section 8 of [STD94], we use representations defined in [RFC4648] with the following names: Bormann Expires 9 June 2024 [Page 4] Internet-Draft CDDL control operators December 2023 +==============+=======================+========================+ | name | meaning | reference | +==============+=======================+========================+ | .b64u | Base64URL, no padding | Section 5 of [RFC4648] | +--------------+-----------------------+------------------------+ | .b64u-sloppy | Base64URL, no | Section 5 of [RFC4648] | | | padding, sloppy | | +--------------+-----------------------+------------------------+ | .b64c | Base64 classic, | Section 4 of [RFC4648] | | | padding | | +--------------+-----------------------+------------------------+ | .b64c-sloppy | Base64 classic, | Section 4 of [RFC4648] | | | padding, sloppy | | +--------------+-----------------------+------------------------+ | .b32 | Base32, no padding | Section 6 of [RFC4648] | +--------------+-----------------------+------------------------+ | .h32 | Base32/hex alphabet, | Section 7 of [RFC4648] | | | no padding | | +--------------+-----------------------+------------------------+ | .hex | Base16 (hex), either | Section 8 of [RFC4648] | | | case | | +--------------+-----------------------+------------------------+ | .hexlc | Base16 (hex), lower | Section 8 of [RFC4648] | | | case | | +--------------+-----------------------+------------------------+ | .hexuc | Base16 (hex), upper | Section 8 of [RFC4648] | | | case | | +--------------+-----------------------+------------------------+ | .b45 | Base45 | [RFC9285] | +--------------+-----------------------+------------------------+ Table 2: Control Operators for Text Conversion of byte strings Note that this specification is somewhat opinionated here: It does not provide base64url, base32 or base32hex encoding with padding, or base64 classic without padding. Experience indicates that these combinations only ever occur in error, so the usability of CDDL is increased by not providing them in the first place. Also, adding "c" makes sure that any decision for classic base64 is actively taken. The additional designation "sloppy" indicates that the text string is not validated for any additional bits being zero, in variance to what is specified in the paragraph behind table 1 in Section 4 of [RFC4648]. Note that the present specification is opinionated again in not specifying a sloppy variant of base32 or base32/hex, as no legacy use of sloppy base32(/hex) was known at the time of writing. Base45 is known to be suboptimal for use in environments with limited data transparency (such as URLs), but is included because of its Bormann Expires 9 June 2024 [Page 5] Internet-Draft CDDL control operators December 2023 close relationship to QR codes and its wide use in health informatics (note that base45 is at least strongly specified not to allow sloppy forms of encoding). 2.2. Numbers +==========+=================+===========+ | name | meaning | reference | +==========+=================+===========+ | .decimal | Decimal Integer | --- | +----------+-----------------+-----------+ Table 3: Control Operator for Text Conversion of Integers The control operator .decimal allows the modeling of text strings that carry numeric information in decimal form, such as in the uint64/int64 formats of YANG-JSON [RFC7951]. yang-json-sid = text .decimal (0..9223372036854775807) Again, the specification is opinionated by only providing integer numbers without leading zeros, i.e., the decimal numbers match the regular expression 0|-?[1-9][0-9]* (of course, further restricted by the control type). See the next section for more flexibility, and for octal, hexadecimal, or binary conversions. 2.3. Printf-style Formatting +=========+===================================+===========+ | name | meaning | reference | +=========+===================================+===========+ | .printf | Printf-formatting of data item(s) | --- | +---------+-----------------------------------+-----------+ Table 4: Control Operator for Printf-formatting of data item(s) The control operator .printf allows the modeling of text strings that carry various formatted information, as long as the format can be represented in Printf-style formatting strings as they are used in the C language (see Section 7.21.6.1 of [C]). my_alg_19 = hexlabel<19> hexlabel<K> = text .printf (["0x%04x", K]) Bormann Expires 9 June 2024 [Page 6] Internet-Draft CDDL control operators December 2023 The controller (right-hand side) of the .printf control is an array of one Printf-style format string and zero or more data items that fit the individual conversion specifications in the format string. The construct matches a text string representing the textual output of an equivalent C-language printf function call that is given the format string and the data items following it in the array. In the example given, my_alg_19 matches the text string "0x0013". The data items in the controller array do not need to be literals, as for example in: any_alg = hexlabel<1..20> hexlabel<K> = text .printf (["0x%04x", K]) Here, any_alg matches the text strings "0x0013" or "0x0001" but not "0x1234". 2.4. JSON Values Some applications store complete JSON texts into text strings, the JSON value for which can easily be defined in CDDL. This is supported by a control operator similar to .cbor in Section 3.8.4 of [RFC8610]. +=======+=========+===========+ | name | meaning | reference | +=======+=========+===========+ | .json | JSON | [STD90] | +-------+---------+-----------+ Table 5: Control Operator for Text Conversion of JSON values embedded-claims = text .json claims claims = {iss: issuer, exp: expiry} Note that a .jsonseq is not provided, as no use case is known yet. There is no way to constrain the use of blank space in data items to be validated; variants (e.g, not providing for any blank space) could be defined. 3. Text Processing Bormann Expires 9 June 2024 [Page 7] Internet-Draft CDDL control operators December 2023 3.1. Join Often, text strings need to be constructed out of parts that can best be modeled as an array. +=======+==================================+===========+ | name | meaning | reference | +=======+==================================+===========+ | .join | concatenate elements of an array | --- | +-------+----------------------------------+-----------+ Table 6: Control Operator for Text Generation from Arrays In general, this control operator is hard to validate as it would require full parser functionality. It is therefore recommended to only use it in simple cases, and leave full parsing to ABNF Section 3 of [RFC9165] or similar. legacy-ip-address = text .join [digits<1>, ".", digits<2>, ".", digits<3>, ".", digits<4>] digits<N> = text .decimal byte<n> 4. Deterministic Encoding [RFC8610] and [RFC8742] specify the control operators .cbor and .cborseq to indicate that the value of a byte string should be an encoded CBOR data item or a CBOR sequence. This specification provides complementary control operators .cbordet and .cborseqdet that indicate that these data items/sequences need to be encoded in accordance to Sections 4.2.1 and 4.2.2 of [STD94]. +=============+=========================+===========+ | name | meaning | reference | +=============+=========================+===========+ | .cbordet | deterministically | [RFC8610] | | | encoded CBOR data item | | +-------------+-------------------------+-----------+ | .cborseqdet | CBOR sequence made from | [RFC8742] | | | deterministically | | | | encoded CBOR data items | | +-------------+-------------------------+-----------+ Table 7: Control Operator for Deterministically Encoded Data Items and Sequences Bormann Expires 9 June 2024 [Page 8] Internet-Draft CDDL control operators December 2023 Note that considerations of deterministic representation at the application level can often be expressed in the CDDL definition of the right-hand side and then do not need additional control operators. 5. IANA Considerations // RFC Editor: please replace RFC-XXXX with the RFC number of this // RFC and remove this note. This document requests IANA to register the contents of Table 8 into the registry "CDDL Control Operators" of [IANA.cddl]: Bormann Expires 9 June 2024 [Page 9] Internet-Draft CDDL control operators December 2023 +==============+============+ | Name | Reference | +==============+============+ | .b64u | [RFC-XXXX] | +--------------+------------+ | .b64u-sloppy | [RFC-XXXX] | +--------------+------------+ | .b64c | [RFC-XXXX] | +--------------+------------+ | .b64c-sloppy | [RFC-XXXX] | +--------------+------------+ | .b45 | [RFC-XXXX] | +--------------+------------+ | .b32 | [RFC-XXXX] | +--------------+------------+ | .h32 | [RFC-XXXX] | +--------------+------------+ | .hex | [RFC-XXXX] | +--------------+------------+ | .hexlc | [RFC-XXXX] | +--------------+------------+ | .hexuc | [RFC-XXXX] | +--------------+------------+ | .decimal | [RFC-XXXX] | +--------------+------------+ | .printf | [RFC-XXXX] | +--------------+------------+ | .json | [RFC-XXXX] | +--------------+------------+ | .join | [RFC-XXXX] | +--------------+------------+ | .cbordet | [RFC-XXXX] | +--------------+------------+ | .cborseqdet | [RFC-XXXX] | +--------------+------------+ Table 8: New control operators to be registered 6. Implementation Status This section is to be removed before publishing as an RFC. In the CDDL tool described in Appendix F of [RFC8610], the control operators defined in the present revision of this specification are implemented as of version 0.10.4. Bormann Expires 9 June 2024 [Page 10] Internet-Draft CDDL control operators December 2023 7. Security considerations The security considerations of [RFC8610] apply. 8. References 8.1. Normative References [C] International Organization for Standardization, "Information technology — Programming languages — C", Fourth Edition, ISO/IEC 9899:2018, June 2018, <https://www.iso.org/standard/74528.html>. Technically equivalent specification text is available at https://web.archive.org/web/20181230041359if_/ http://www.open-std.org/jtc1/sc22/wg14/www/abq/ c17_updated_proposed_fdis.pdf (https://web.archive.org/web/20181230041359if_/ http://www.open-std.org/jtc1/sc22/wg14/www/abq/ c17_updated_proposed_fdis.pdf) [IANA.cddl] IANA, "Concise Data Definition Language (CDDL)", <https://www.iana.org/assignments/cddl>. [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/rfc/rfc2119>. [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, <https://www.rfc-editor.org/rfc/rfc4648>. [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/rfc/rfc8174>. [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019, <https://www.rfc-editor.org/rfc/rfc8610>. [RFC8742] Bormann, C., "Concise Binary Object Representation (CBOR) Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020, <https://www.rfc-editor.org/rfc/rfc8742>. Bormann Expires 9 June 2024 [Page 11] Internet-Draft CDDL control operators December 2023 [RFC9165] Bormann, C., "Additional Control Operators for the Concise Data Definition Language (CDDL)", RFC 9165, DOI 10.17487/RFC9165, December 2021, <https://www.rfc-editor.org/rfc/rfc9165>. [RFC9285] Fältström, P., Ljunggren, F., and D.W. van Gulik, "The Base45 Data Encoding", RFC 9285, DOI 10.17487/RFC9285, August 2022, <https://www.rfc-editor.org/rfc/rfc9285>. [STD90] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>. [STD94] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, December 2020, <https://www.rfc-editor.org/rfc/rfc8949>. 8.2. Informative References [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/rfc/rfc7951>. [RFC9090] Bormann, C., "Concise Binary Object Representation (CBOR) Tags for Object Identifiers", RFC 9090, DOI 10.17487/RFC9090, July 2021, <https://www.rfc-editor.org/rfc/rfc9090>. Acknowledgements Henk Birkholz suggested the need for many of the control operators defined here. Author's Address Carsten Bormann Universität Bremen TZI Postfach 330440 D-28359 Bremen Germany Phone: +49-421-218-63921 Email: cabo@tzi.org Bormann Expires 9 June 2024 [Page 12]