Internet-Draft CBOR "simple" values for CSF October 2026
Rundgren Expires 2 May 2027 [Page]
Workgroup:
Internet Engineering Task Force
Internet-Draft:
draft-rundgren-cbor-simple-4-csf-02
Published:
Intended Status:
Informational
Expires:
Author:
A. Rundgren, Ed.
Independent

CBOR "simple" values for CSF

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.

▲

Table of Contents

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

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).
  • 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.

Table 1: Simple Values
Value Semantics Reference
99 Unique (reserved) label draft-rundgren-cbor-simple-4-csf-XX
100 Unique (reserved) label draft-rundgren-cbor-simple-4-csf-XX

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

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

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");
                }
                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");
    }
    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.
            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.

Document History

Author's Address

Anders Rundgren (editor)
Independent
Montpellier
France