More Control Operators for CDDL
draft-bormann-cbor-cddl-more-control-00

Network Working Group                                         C. Bormann
Internet-Draft                                    Universität Bremen TZI
Intended status: Standards Track                        25 February 2023
Expires: 29 August 2023

                    More Control Operators for CDDL
                draft-bormann-cbor-cddl-more-control-00

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
   application control operators for text conversion (Bytes, Integers,
   JSON) and operations on text.

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 29 August 2023.

Copyright Notice

   Copyright (c) 2023 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

Bormann                  Expires 29 August 2023                 [Page 1]
Internet-Draft           CDDL control operators            February 2023

   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
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Text Conversion . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Byte Strings: Base16 (Hex), Base32, Base64  . . . . . . .   3
     2.2.  Numbers . . . . . . . . . . . . . . . . . . . . . . . . .   4
     2.3.  JSON Values . . . . . . . . . . . . . . . . . . . . . . .   5
   3.  Text Processing . . . . . . . . . . . . . . . . . . . . . . .   5
     3.1.  Join  . . . . . . . . . . . . . . . . . . . . . . . . . .   5
     3.2.  Intersperse . . . . . . . . . . . . . . . . . . . . . . .   6
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   5.  Implementation Status . . . . . . . . . . . . . . . . . . . .   7
   6.  Security considerations . . . . . . . . . . . . . . . . . . .   7
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

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:

Bormann                  Expires 29 August 2023                 [Page 2]
Internet-Draft           CDDL control operators            February 2023

     +======================+========================================+
     | Name                 | Purpose                                |
     +======================+========================================+
     | .b64u, .b64c         | Base64 representation of byte strings  |
     +----------------------+----------------------------------------+
     | .hex, .hexlc, .hexuc | Base16 representation of byte strings  |
     +----------------------+----------------------------------------+
     | .b32, .h32           | Base32 representation of byte strings  |
     +----------------------+----------------------------------------+
     | .decimal             | Text representation of integer numbers |
     +----------------------+----------------------------------------+
     | .json                | Text representation of JSON values     |
     +----------------------+----------------------------------------+
     | .join                | Building text from array of components |
     +----------------------+----------------------------------------+

              Table 1: New control operators in this document

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

Bormann                  Expires 29 August 2023                 [Page 3]
Internet-Draft           CDDL control operators            February 2023

   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:

   +========+=================================+========================+
   | name   | meaning                         | reference              |
   +========+=================================+========================+
   | .b64u  | Base64URL, no padding           | Section 5 of [RFC4648] |
   +--------+---------------------------------+------------------------+
   | .b64c  | Base64 classic, padding         | Section 4 of [RFC4648] |
   +--------+---------------------------------+------------------------+
   | .b32   | Base32, no padding              | Section 6 of [RFC4648] |
   +--------+---------------------------------+------------------------+
   | .h32   | Base32/hex alphabet, no         | Section 7 of [RFC4648] |
   |        | 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                            |                        |
   +--------+---------------------------------+------------------------+

       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.

2.2.  Numbers

                +==========+=================+===========+
                | name     | meaning         | reference |
                +==========+=================+===========+
                | .decimal | Decimal Integer | ---       |
                +----------+-----------------+-----------+

                    Table 3: Control Operator for Text
                          Conversion of Integers

Bormann                  Expires 29 August 2023                 [Page 4]
Internet-Draft           CDDL control operators            February 2023

   This allows the modeling of text strings that carry numeric
   information, 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 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).  Future specifications can provide octal, hexadecimal,
   or binary conversions.

2.3.  JSON Values

   Some applications store complete JSON texts into text strings, the
   JSON value for 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 4: 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

3.1.  Join

   Often, text strings need to be constructed out of parts that can best
   be modeled as an array.

Bormann                  Expires 29 August 2023                 [Page 5]
Internet-Draft           CDDL control operators            February 2023

         +=======+==================================+===========+
         | name  | meaning                          | reference |
         +=======+==================================+===========+
         | .join | concatenate elements of an array | ---       |
         +-------+----------------------------------+-----------+

            Table 5: 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>

3.2.  Intersperse

   (This section requires some additional design effort before it can be
   implemented and registered.)

   The previous example is somewhat unwieldy as the dots are just
   syntactic noise.

   The .intersperse control is modeled after Haskell's function of the
   same name [INTERSPERSE].  It takes the elements of an array and
   intersperses a given additional elements between each to elements of
   the additional array.

   legacy-ip-address = text .join ("." .intersperse digits)
   digits = [4*4 digit]
   digit = text .decimal (uint .size 1)

   .intersperse is actually not limited to text strings; it can be used
   for any juggling of arrays.

   We want to stop here, as there is a danger of generating a functional
   programming language in an ad-hoc fashion.

4.  IANA Considerations

   This document requests IANA to register the contents of Table 6 into
   the registry "CDDL Control Operators" of [IANA.cddl]:

Bormann                  Expires 29 August 2023                 [Page 6]
Internet-Draft           CDDL control operators            February 2023

                          +==========+===========+
                          | Name     | Reference |
                          +==========+===========+
                          | .b64u    | [RFCthis] |
                          +----------+-----------+
                          | .b64c    | [RFCthis] |
                          +----------+-----------+
                          | .b32     | [RFCthis] |
                          +----------+-----------+
                          | .h32     | [RFCthis] |
                          +----------+-----------+
                          | .hex     | [RFCthis] |
                          +----------+-----------+
                          | .hexlc   | [RFCthis] |
                          +----------+-----------+
                          | .hexuc   | [RFCthis] |
                          +----------+-----------+
                          | .decimal | [RFCthis] |
                          +----------+-----------+
                          | .json    | [RFCthis] |
                          +----------+-----------+
                          | .join    | [RFCthis] |
                          +----------+-----------+

                            Table 6: New control
                              operators to be
                                 registered

5.  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 this specification are implemented as of version
   0.10.2.

6.  Security considerations

   The security considerations of [RFC8610] apply.

7.  References

7.1.  Normative References

   [IANA.cddl]
              IANA, "Concise Data Definition Language (CDDL)",
              <https://www.iana.org/assignments/cddl>.

Bormann                  Expires 29 August 2023                 [Page 7]
Internet-Draft           CDDL control operators            February 2023

   [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>.

   [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>.

   [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>.

7.2.  Informative References

   [INTERSPERSE]
              "intersperse", Haskell Documentation,
              <https://hoogle.haskell.org/?hoogle=intersperse>.

   [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>.

Bormann                  Expires 29 August 2023                 [Page 8]
Internet-Draft           CDDL control operators            February 2023

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 29 August 2023                 [Page 9]