CBOR Tx Envelope specification

Standard for serialising a CBOR payload, ensuring consistency when signing the payload.

BRFCTitleAuthor(s)Version
5b82a2ed7b16CBOR Tx EnvelopeLibs1

Overview

When sharing data objects, inconsistencies between implementations can cause changes to the data object (for example, key order) which would cause signature verification to fail.

The JSON Envelope BRFC described a technique to ensure consitency of the data being signed by encoding the JSON payload inside a parent JSON object (the envelope). This specification proposes using the same technique applied to CBOR (Concise Binary Object Representation) encoded payloads.

As CBOR is a concise binary-friendly format, it offers a highly efficient way of encapsulating public keys, signatures and other binary values. CBOR can also be used in streaming applications.

Envelope data definition

The following CBOR structure is described using CDDL (Concise Data Definition Language).

Envelope = {
  payload: bytes,
  ? pubkey: bytes,
  ? signature: bytes
}

The Envelope type is a map which must contain a payload field, and may contain pubkey and signature fields. The value of the payload field must be a CBOR-encoded binary. If present, the pubkey field must be a Bitcoin public key binary, and the signature field must be an ECDSA signature.

Signing algorithm

An ECDSA signature is created by calculating the sha256 hash of the payload binary, and signing the hash with a Bitcoin private key. The resulting signature and the private key's corresponding public key are included in the Envelope data item.

The recieving end can verify the signature by calculating the sha256 hash of the payload binary, and verifying the signature against the hash, using the pubkey.

CBOR data format

There are several alternative binary data serialisation formats, such as Protobuf, MessagePack and BSON.

CBOR was chosen because it has a well defined specification with implementations in many languages, and strikes the right balance of simplicity and flexibility. CBOR is largely isomorphic to JSON, plus supports byte arrays. Which is exactly what is needed.

HTTP requests

A valid HTTP request or response must contain the following:

  • Headers:
    • Content-Type: Must be "application/cbor" or can be any media type with the +suffix "+cbor", for example: "xxx/yyy+cbor".
  • Body: The Envelope data must be CBOR-encoded.

Streaming applications

In a streaming application, a data stream may be composed of a sequence of CBOR-encoded Envelope data items concatenated back-to-back. The receiving end will buffer data until one or more complete Envelope data items can be decoded. Any remaining data is buffered until it too can be decoded.

Implementations

The following implementations of this BRFC are available:

  • Txpost - Elixir
  • Coming soon - JavaScript

Comments

This spec is released as an RFC (request for comment) as part of the public review process. Any comments, criticisms or suggestions should be directed toward the Txpost repository issues page.