Universal CBOR (U-CBOR)

2.1. Supported CBOR Objects

The following table shows the CBOR subset supported by U-CBOR:¶

Conforming implementations (of course) only have to implement the U-CBOR types required by the targeted application(s).¶

Although extensions are imaginable (like supporting all "simple" types), extensions will most likely cause interoperability issues and are thus NOT RECOMMENDED. In addition, the mandated CBOR subset is compatible with most computer languages and platforms. Compared to the current state-of-the-art, JSON [RFC8259], the availability of bigint, bstr, and "tagged data" represent major improvements.¶

However, nothing prevents developers from at the application (API) level, through mapping concepts, support additional, "virtual" data types, analogous to how you map an application's data model to the set of data types available, be it a data interchange format, a database, or a programming language.¶

2.2. Deterministic Encoding Scheme

The U-CBOR encoding scheme adheres to section 4.2 of [RFC8949], but adds a few constraints (denoted by RFC+), where the RFC offers choices. The deterministic encoding rules are as follows:¶

• RFC+: Floating point and integer objects MUST be treated as distinct types regardless of their numeric value. This is compliant with Rule 2 in section 4.2.2 of [RFC8949].¶

• RFC: Integers, represented by the int and bigint types, MUST use the int type if the value is between -264 and 264-1, otherwise the bigint type MUST be used. Appendix A.1 features a list of compliant integer sample values.¶

• RFC+: Floating point numbers MUST always use the shortest [IEEE754] variant that preserves the precision of the original value. Appendix A.2 features a list of compliant floating point sample values.¶

  Note that NaN "signaling" (like f97e01), MUST be rejected.¶

• RFC: Map keys MUST be sorted in the bytewise lexicographic order of their deterministic encoding. Duplicate keys MUST be rejected. Somewhat surprisingly the following represents a properly sorted map:¶

  {
    "a": ... ,
    "b": ... ,
    "aa": ...
  }

  ¶
• RFC+: Since CBOR encoding according to this specification maintains type and data uniqueness, there are no specific restrictions or tests needed in order to determine map key equivalence. As an example, the floating-point numbers 0.0 and -0.0, and the integer number 0 represent the distinct keys f90000, f98000, and 00 respectively.¶
• RFC+: Indefinite length objects MUST be rejected.¶

2.3. CBOR Tool Requirements

The primary feature that deterministic encoding brings to the table is that wrapping CBOR data to be signed in bstr objects, like specified by COSE [RFC9052] (Section 2), no longer is a prerequisite. That is, cryptographic operations can optionally be performed on "raw" CBOR data. Turn to Appendix B for an example of an application depending on such features.¶

However, to make this a reality, the following functionality MUST be provided by CBOR tools compliant with this specification:¶

• It MUST be possible to add, delete, and update the contents of CBOR map and array objects, of received and decoded CBOR data. Note: CBOR primitives MUST remain immutable.¶
• It MUST be possible to reserialize received CBOR data, be it updated or not.¶
• Irrespective of if CBOR data was received, updated, or created programmatically, deterministic encoding MUST be maintained.¶
• Invalid or unsupported CBOR constructs, as well as CBOR data not adhering to the deterministic encoding scheme MUST be rejected. See also Appendix C and Appendix A.3.¶

It is RECOMMENDED separating CBOR data and application / platform-level data, since the latter may not always reserialize as expected, like in this Chrome browser console example:¶

> let date = new Date('2025-03-02T13:08:55.0001Z');
> date.toISOString()
'2025-03-02T13:08:55.000Z'

How this separation actually is accomplished is out of scope for this specification. However, encapsulation of CBOR data in high-level, and self-rendering objects, represents a usable method. Similar approaches are used by most ASN.1 tools. The code in Appendix B.5 shows an example that updates and reserializes decoded CBOR data.¶

A.1. Integers

This normative section holds a selection of CBOR integer values, with an emphasize on edge cases.¶

A.2. Floating Point Numbers

This normative section holds a selection of [IEEE754] 16, 32, and 64-bit values, with an emphasize on edge cases.¶

The textual representation of the values is based on the serialization method for the Number data type, defined by [ECMASCRIPT] with one change: to comply with diagnostic notation (section 8 of [RFC8949]), all values are expressed as floating point numbers. The rationale for using [ECMASCRIPT] serialization is because it supposed to generate the shortest and most correct representation of [IEEE754] numbers.¶

A.3. Invalid Encodings

The following table holds a selection of valid CBOR objects, not permitted by U-CBOR.¶

1. See also Appendix C.¶

B.1. Unsigned Data

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

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

Then continue to the next section (Appendix B.2)...¶

B.2. Signature Process

This section describes the steps required for adding an enveloped signature to the CBOR map object in Appendix B.1.¶

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.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.3. Validation Process

In order to validate the enveloped signature created in the Appendix B.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.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.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.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

B.5. Code Example

Using the JavaScript implementation mentioned in Appendix E, basic signature validation of the signed CBOR object created in Appendix B.2, could be performed by the following code:¶

// The variable cborBinary is supposed to contain CBOR
let object = CBOR.decode(cborBinary);             // Decode
let csf = object.get(CBOR.Int(-1));               // Get CSF container
let alg = csf.get(CBOR.Int(1)).getInt();          // Read algorithm
let sig = csf.remove(CBOR.Int(6)).getBytes();     // Read and remove signature value
let key = CBOR.fromHex('7fdd851a3b9d2dafc5f0d00030e22b9343900cd42ede4948568a4a2ee655291a');

// Hypothetical HMAC validation method:
hmacValidate(alg, sig, key, object.encode());     // Note that object.encode()
                                                  // reserializes all but sig.
// Validated object, access the "payload":
let param = object.get(CBOR.Int(1)).getString();  // param should now contain "data"

Note that this code depends heavily on the CBOR tool features outlined in Section 2.3.¶