Universal CBOR (U-CBOR)

2.3.1. Protocol Primitives Support

To facilitate cross-platform protocol interoperability, implementers of U-CBOR compatible tools SHOULD include decoder API support for the following primitives:¶

1. Range testing MUST be performed using the traditional ranges for unsigned respectively two-complement numbers. That is, a hypothetical getUint8() MUST reject numbers outside of 0 to 255, whereas a hypothetical getInt8(), MUST reject numbers outside of -128 to 127.¶

2. Note that a hypothetical getBigInt() MUST also accept CBOR int objects since int is used for integers that fit in CBOR major type 0 and 1 objects. See also Appendix A.1 and Appendix C.¶

3. Some platforms do not natively support float32 and/or float16. In this case a hypothetical getFloat16() would need to use a bigger floating-point type for the return value.¶

   Note that a hypothetical getFloat16() MUST reject encountered Float32 and Float64 objects. See also Appendix C.¶

4. Since a CBOR null typically represents the absence of a value, a decoder MUST provide a test-function, like isNull().¶

5. Since CBOR does not feature a native-level time-object, Section 3.4 of [RFC8949] introduces two variants of time-objects using the CBOR tags 0 and 1. The time-objects SHOULD also be supported without the tag construct.¶

If a call does not match the underlying CDDL type, the call MUST be rejected,¶

Due to considerable variations between platforms, corresponding encoder API support does not appear to be meaningful to specify in detail: Java doesn't have built-in support for unsigned integers, whereas JavaScript requires the use of the JavaScript BigInt type for dealing with 64-bit integers.¶

2.3.2. Media Type

Protocols building on U-CBOR, are RECOMMENDED using the media type: application/cbor.¶

2.3.3. Diagnostic Notation Support

Compliant U-CBOR implementations SHOULD include support for bi-directional diagnostic notation, to facilitate:¶

• Human-centric debugging and logging¶
• Easy creation of test and configuration data¶

The supported notation is compliant with a subset of Section 8 of [RFC8949] (b32' and encoding indicators were left out), but adds a few items to make diagnostic notation slightly more adapted for parsing, like single-line comments:¶

1. The letter n in the Syntax column denotes one or more digits.¶
2. The optional {sign} must be a single hyphen ('-') character.¶
3. Input only: between the quotes, the whitespace characters (' ', '\t', '\r', '\n') are ignored.¶
4. Input only: the control characters ('\t' and '\n') inside of string quotes become a part of the text. For normalizing line terminators, a single '\r' or the combination '\r\n' are rewritten as '\n'. To avoid getting newline characters ('\n') included in multi-line text strings, a line continuation marker consisting of a backslash ('\') immediately preceding the newline may be used.¶
5. Text strings may also include JavaScript compatible escape sequences ('\'', '\"', '\\', '\b', '\f', '\n', '\r', '\t', '\uhhhh').¶
6. Input only.¶

B.1.1. Unsigned Data

Imagine you have a CBOR map object like the following that you want to sign:¶

{
  1: "data",
  2: "more data"
}

B.1.2. Signature Process

This section describes the steps required for adding an enveloped signature to the CBOR map object in Appendix B.1.1. To avoid confusing CBOR map keys with cryptographic keys, the former are referred to as "labels".¶

1. Add an empty CSF container (a CBOR map) to the unsigned CBOR map using an application-defined label (-1).¶
2. Add the designated signature algorithm to the CSF container using the CSF algorithm label (1).¶
3. Optional. Add other signature meta data to the CSF container. Not used in the example.¶

4. Generate a signature by invoking a (hypothetical) signature method with the following arguments:¶

   • the designated signature key.¶
   • the designated signature algorithm.¶
   • the deterministic encoding of the current CBOR object in its entirety. In the example that would be a301646461746102696d6f7265206461746120a10105, if expressed in hex code.¶
5. Add the returned signature value to the CSF container using the CSF signature label (6).¶

The result after the final step (using the parameters from Appendix B.1.4), should match the following CBOR object:¶

{
  1: "data",
  2: "more data",
  -1: {
    1: 5,
    6: h'4853d7730cc1340682b1748dc346cf627a5e91ce62c67fff15c40257ed2a37a1'
  }
}

Note that the signature covers the entire CBOR object except for the CSF signature value and label (6).¶

B.1.3. Validation Process

In order to validate the enveloped signature created in the Appendix B.1.2, the following steps are performed:¶

1. Fetch a reference to the CSF container using the application-defined label (-1). Next perform the following operations using the reference:¶

   1. Retrieve the signature algorithm using the CSF algorithm label (1).¶
   2. Retrieve the signature value using the CSF algorithm label (6).¶
   3. Remove the CSF algorithm label (6) and its associated value.¶

   Now we should have exactly the same CBOR object as we had before step #4 in Appendix B.1.2. That is:¶

   {
     1: "data",
     2: "more data",
     -1: {
       1: 5
     }
   }

   ¶

2. Validate the signature data by invoking a (hypothetical) signature validation method with the following arguments:¶

   • the designated signature key (in the example taken from Appendix B.1.4).¶
   • the signature algorithm retrieved in step #1.¶
   • the signature value retrieved in step #1.¶
   • the deterministic encoding of the current CBOR object in its entirety.¶

Note: this is a "bare-bones" validation process, lacking the ruggedness of a real-world implementation.¶

B.1.4. Example Parameters

The signature and validation processes depend on the COSE [RFC9053] algorithm "HMAC 256/256" and an associated 256-bit key, here provided in hex code:¶

7fdd851a3b9d2dafc5f0d00030e22b9343900cd42ede4948568a4a2ee655291a