CBOR "simple" values for CSF
draft-rundgren-cbor-simple-4-csf-02

Internet Engineering Task Force                         A. Rundgren, Ed.
Internet-Draft                                               Independent
Intended status: Informational                           29 October 2026
Expires: 2 May 2027

                      CBOR "simple" values for CSF
                  draft-rundgren-cbor-simple-4-csf-02

Abstract

   This document defines two CBOR "simple" values to be used as unique
   (reserved) labels in a CBOR map holding an embedded signature
   construct.

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 May 2027.

Copyright Notice

   Copyright (c) 2026 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.

Rundgren                   Expires 2 May 2027                   [Page 1]
Internet-Draft        CBOR "simple" values for CSF          October 2026

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Requirements Language . . . . . . . . . . . . . . . . . . . .   2
   3.  Description and Rationale . . . . . . . . . . . . . . . . . .   2
     3.1.  Initial (Now Deprecated) Solution . . . . . . . . . . . .   3
     3.2.  Enhanced (Current) Solution . . . . . . . . . . . . . . .   3
     3.3.  Unsigned Data Option  . . . . . . . . . . . . . . . . . .   4
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   4
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .   5
     6.2.  Informative References  . . . . . . . . . . . . . . . . .   5
   Appendix A.  Constrained System CSF Verifier  . . . . . . . . . .   5
   Document History  . . . . . . . . . . . . . . . . . . . . . . . .  11
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  11

1.  Introduction

   This document defines two CBOR [RFC8949] "simple" values to be used
   as unique (reserved) labels in conjunction with an embedded signature
   scheme described in Appendix E (https://www.ietf.org/archive/id/
   draft-rundgren-cbor-core-25.html#appendix-E) of CBOR::Core
   [I-D.rundgren-cbor-core], from now on referred to as CSF (CBOR
   Signature Format).

   The purpose of the unique labels is to securely decouple application-
   specific labels from the CSF signature container, respectively hold
   data that should be excluded from the signature.

   In addition to eliminating the need for application-specific labels
   for embedded signature constructs, the net result includes simplified
   signature APIs as well.

2.  Requirements Language

   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.

3.  Description and Rationale

   This section describes the problem and its solution.

   The CBOR examples are provided in "Extended Diagnostic Notation
   (EDN)" [I-D.ietf-cbor-edn-literals].

Rundgren                   Expires 2 May 2027                   [Page 2]
Internet-Draft        CBOR "simple" values for CSF          October 2026

3.1.  Initial (Now Deprecated) Solution

   In the original take on the CSF embedded signature scheme, an
   application-specific label held the embedded signature container.

   The following CBOR code shows a very simple example using an HMAC
   signature:

   {
     1: "data",         # Application data
     2: "more data",    # Application data
     -1: {              # Embedded signature (CSF container)
       1: 5,
       6: h'4853d7730cc1340682b1748dc346cf627a5e91ce62c67fff15c40257ed2a37a1'
     }
   }

   Having to define an application-specific ("custom") label for the
   embedded signature container is certainly not a showstopper, but it
   lacks "finesse".  In addition, signature APIs need to deal with such
   labels like the following:

     sign(_signatureLabel_, _applicationMap_).

3.2.  Enhanced (Current) Solution

   In the following sample (copied from [I-D.rundgren-cbor-core]), a
   CBOR simple(99) value is used as a reserved label for the embedded
   signature container:

   {
     1: "data",         # Application data
     2: "more data",    # Application data
     simple(99): {      # Embedded signature (CSF container)
       1: 5,
       6: h'237e674c7be1818ddd7eaacf40ca80415b9ad816880751d2136c45385207420c'
     }
   }

   The advantages with using simple(99) include:

   *  Eliminates the need for application-specific labels for signature
      containers.

   *  Simplifies signature APIs: sign(_applicationMap_).

Rundgren                   Expires 2 May 2027                   [Page 3]
Internet-Draft        CBOR "simple" values for CSF          October 2026

   *  Using deterministic encoding (a CSF prerequisite), CBOR simple
      types lexicographically follow after other CBOR elements (of the
      kind normally used as labels).  This makes sense for embedded
      signatures, since they usually "attest" the application data that
      is (list-wise), situated above the signature container, like in
      the example.

   *  Appendix A shows an additional feature accomplished by this
      arrangement.

3.3.  Unsigned Data Option

   In use-cases like when issuing selectable disclosures (e.g. as in
   https://cyberphone.github.io/sd-experimental/doc/#issued-sd-cwt), it
   may be advantageous being able to carry unsigned data together with
   signed data, as an alternative to a more elaborate construct.  For
   this purpose, the reserved CBOR simple(100) label was introduced:

   {
     1: "data",         # Application data
     2: "more data",    # Application data
     simple(99): {      # Embedded signature (CSF container)
       1: 5,
       6: h'237e674c7be1818ddd7eaacf40ca80415b9ad816880751d2136c45385207420c'
     },
     simple(100): "just passing through..."
   }

4.  IANA Considerations

   In the registry [IANA.cbor-simple-values], IANA is requested to
   allocate the simple value defined in Table 1.

    +=======+==================+=====================================+
    | Value |    Semantics     |              Reference              |
    +=======+==================+=====================================+
    |   99  | Unique           | draft-rundgren-cbor-simple-4-csf-XX |
    |       | (reserved) label |                                     |
    +-------+------------------+-------------------------------------+
    |  100  | Unique           | draft-rundgren-cbor-simple-4-csf-XX |
    |       | (reserved) label |                                     |
    +-------+------------------+-------------------------------------+

                          Table 1: Simple Values

Rundgren                   Expires 2 May 2027                   [Page 4]
Internet-Draft        CBOR "simple" values for CSF          October 2026

5.  Security Considerations

   An "alternative" use of the "simple" values defined herein, could in
   a marginal implementation introduce security issues.

6.  References

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

   [RFC8949]  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/info/rfc8949>.

   [IANA.cbor-simple-values]
              IANA, "Concise Binary Object Representation (CBOR) Simple
              Values",
              <https://www.iana.org/assignments/cbor-simple-values>.

6.2.  Informative References

   [I-D.ietf-cbor-edn-literals]
              Bormann, C., "CBOR Extended Diagnostic Notation (EDN)",
              Work in Progress, Internet-Draft, draft-ietf-cbor-edn-
              literals-28, <https://datatracker.ietf.org/doc/html/draft-
              ietf-cbor-edn-literals-18>.

   [I-D.rundgren-cbor-core]
              Rundgren, A., "CBOR::Core - CBOR Cross Platform Profile",
              <https://www.ietf.org/archive/id/draft-rundgren-cbor-core-
              25.html>.

Appendix A.  Constrained System CSF Verifier

   The following C sample code shows how the use of simple(99), due to
   the deterministic coding rules, makes the actual signature value
   appear as the last item in a CSF-signed object.

Rundgren                   Expires 2 May 2027                   [Page 5]
Internet-Draft        CBOR "simple" values for CSF          October 2026

   This arrangement enables embedded signatures based on the CSF scheme,
   to be applied to quite primitive systems, with moderate additional
   resource requirements.

   Note: this is a low-level solution, relying on the assumption that
   floating-point numbers are not used as labels, since such labels
   would appear _after_ the simple(99) label.

   #include <stdio.h>
   #include <stdlib.h>
   #include <string.h>
   #include <stdbool.h>
   #include <stdint.h>
   #include <stdarg.h>
   #include "../lib/hmac_sha256.h"

   /*
       Decode and verify the integrity of this minimal sample using
       CBOR Signature Format (CSF).

       Sample expressed in diagnostic notation:

           {
             1: "data",
             2: "more data",
             simple(99): {
               1: 5,
               6: h'237e674c7be1818ddd7eaacf40ca80415b9ad816880751d2136c45385207420c'
             }
           }

   */

   uint8_t buffer[] = {  // Corresponding CBOR binary
       0xa3, 0x01, 0x64, 0x64, 0x61, 0x74, 0x61, 0x02, 0x69, 0x6d, 0x6f, 0x72,
       0x65, 0x20, 0x64, 0x61, 0x74, 0x61, 0xf8, 0x63, 0xa2, 0x01, 0x05, 0x06,
       0x58, 0x20, 0x23, 0x7e, 0x67, 0x4c, 0x7b, 0xe1, 0x81, 0x8d, 0xdd, 0x7e,
       0xaa, 0xcf, 0x40, 0xca, 0x80, 0x41, 0x5b, 0x9a, 0xd8, 0x16, 0x88, 0x07,
       0x51, 0xd2, 0x13, 0x6c, 0x45, 0x38, 0x52, 0x07, 0x42, 0x0c };

   const uint8_t HMAC_KEY[] = {
       0x7f, 0xdd, 0x85, 0x1a, 0x3b, 0x9d, 0x2d, 0xaf, 0xc5, 0xf0, 0xd0, 0x00,
       0x30, 0xe2, 0x2b, 0x93, 0x43, 0x90, 0x0c, 0xd4, 0x2e, 0xde, 0x49, 0x48,
       0x56, 0x8a, 0x4a, 0x2e, 0xe6, 0x55, 0x29, 0x1a };

   #define COSE_HS256_ALG 5
   #define COSE_HS256_LEN 32

Rundgren                   Expires 2 May 2027                   [Page 6]
Internet-Draft        CBOR "simple" values for CSF          October 2026

   int bufferPosition;

   void failedOperation(char *message, ...) {
       va_list args;
       printf("\n*** ");
       va_start(args, message);
       vprintf(message, args);
       va_end(args);
       printf(" (bufferPosition = %d)\n\n", bufferPosition);
       exit(1);
   }

   void initiate() {
       bufferPosition = 0;
   }

   void terminate() {
       if (bufferPosition < sizeof(buffer)) {
           failedOperation("Unread buffer data");
       }
   }

   uint8_t _getByte() {
       if (bufferPosition >= sizeof(buffer)) {
           failedOperation("Buffer overflow");
       }
       return buffer[bufferPosition++];
   }

   int32_t _getLength(uint8_t header) {
       int32_t length = header & 0x1f;
       if (length >= 24) switch (length) {
           default:
               failedOperation("Unsupported or invalid length: 0x%02x", length);
           case 24:
           case 25:
           case 26:
               {
                   int32_t q = 1 << (length - 24);
                   int32_t leadingZeroMask = 0xffff << (q * 4);
                   length = 0;
                   while (q--) {
                       length <<= 8;
                       length += _getByte();
                   }
                   if (length & 0x80000000) {
                       failedOperation("Int32 value out of range");
                   }

Rundgren                   Expires 2 May 2027                   [Page 7]
Internet-Draft        CBOR "simple" values for CSF          October 2026

                   if (!(length & leadingZeroMask) || length < 24) {
                       failedOperation("Non-deterministically encoded integer");
                   }
               }
       }
       return length;
   }

   int32_t getInt32() {
       uint8_t header = _getByte();
       if (header & 0xc0) {
           failedOperation("Expected integer");
       }
       int32_t value = _getLength(header);
       return header < 0x20 ? value : ~value;
   }

   void getSimple(uint8_t value) {
       if (_getByte() != 0xf8 || _getByte() != value) {
           failedOperation("Expected simple(%d)", value);
       }
   }

   void getKey(int32_t key) {
       if (key != getInt32()) {
           failedOperation("Expected key: %d", key);
       }
   }

   int32_t getMap(int32_t elements) {
       int32_t savePos = bufferPosition;
       uint8_t header = _getByte();
       if ((header & 0xe0) != 0xa0 || elements != _getLength(header)) {
           failedOperation("Expected map with %d elements", elements);
       }
       return savePos;
   }

   typedef struct {
       int length;
       uint8_t* bytes;
   } STRING;

   void _getString(uint8_t majorType, STRING* string) {
       uint8_t header = _getByte();
       if ((header & 0xe0) != majorType) {
           failedOperation("Expected string type");
       }

Rundgren                   Expires 2 May 2027                   [Page 8]
Internet-Draft        CBOR "simple" values for CSF          October 2026

       int32_t length = _getLength(header);
       string->length = length;
       string->bytes = &buffer[bufferPosition];
       while (length--) {
           _getByte();  // Scan away, but check for overrun!
       }
   }

   void getTstr(STRING* string) {
       _getString(0x60, string);
   }

   void getBstr(STRING* string) {
       _getString(0x40, string);
   }

   void debugPrint(STRING* data, bool hex, char* description) {
       printf("%s: ", description);
       for (int i = 0; i < data->length; ) {
           printf(hex ? "%02x" : "%c", data->bytes[i++]);
       }
       printf("\n");
   }

   int main(int argc, char **args) {
       initiate();

       getMap(3);  // Top-level map

           getKey(1);
           STRING firstArgument;
           getTstr(&firstArgument);

           getKey(2);
           STRING secondArgument;
           getTstr(&secondArgument);

           getSimple(99);  // CSF object label

               // Read and verify the size of the CSF map.
               //
               // Then decrement CSF map size by one since
               // signatureValue is not a part of signedData.
               //
               // This is the opposite to what happens during signature
               // creation, where signatureValue is the final element
               // added and thus increases the CSF map size with one
               // in order to maintain a valid CSF container.

Rundgren                   Expires 2 May 2027                   [Page 9]
Internet-Draft        CBOR "simple" values for CSF          October 2026

               buffer[getMap(2)]--;

                   getKey(1);  // CSF algorithm label
                   int32_t algorithm = getInt32();

                   // signedData constitutes of the following CBOR data:
                   //
                   //  {
                   //    1: "data",
                   //    2: "more data",
                   //    simple(99): {
                   //      1: 5
                   //    }
                   //  }
                   //
                   STRING signedData;
                   signedData.length = bufferPosition;
                   signedData.bytes = buffer;

                   getKey(6); // CSF signatureValue label
                   STRING signatureValue;
                   getBstr(&signatureValue);

       terminate();

       // Sample passed format verification. Print read data.
       debugPrint(&firstArgument, false, "First argument");
       debugPrint(&secondArgument, false, "Second argument");
       debugPrint(&signedData, true, "Signed data");
       printf("Algorithm: %d (COSE HS256)\n", algorithm);
       debugPrint(&signatureValue, true, "Signature value");

       // Finally, signature validation.
       if (algorithm != COSE_HS256_ALG || signatureValue.length != COSE_HS256_LEN) {
           failedOperation("Error in algorithm or signatureValue.length");
       }
       uint8_t out[COSE_HS256_LEN];
       size_t hmac = hmac_sha256(HMAC_KEY, sizeof(HMAC_KEY),
                                 signedData.bytes, signedData.length,
                                 out, COSE_HS256_LEN);
       if (hmac != COSE_HS256_LEN || memcmp(out, signatureValue.bytes, COSE_HS256_LEN)) {
           failedOperation("Signature validation failed");
       }
       printf("\nSample validated!!!\n");
   }

   Complete source code and documention is available at
   https://github.com/cyberphone/ultra-simple-csf-sample.

Rundgren                   Expires 2 May 2027                  [Page 10]
Internet-Draft        CBOR "simple" values for CSF          October 2026

Document History

   *  00.  First cut.

   *  01.  Added simple(100).

   *  02.  Referenced CBOR::Core rather than the Java CSF
      implementation.

Author's Address

   Anders Rundgren (editor)
   Independent
   Montpellier
   France
   Email: anders.rundgren.net@gmail.com
   URI:   https://www.linkedin.com/in/andersrundgren/

Rundgren                   Expires 2 May 2027                  [Page 11]