Registry of Uniform Resource (UR) Types

April 28, 2025 · View on GitHub

BCR-2020-006

© 2020 Blockchain Commons

Authors: Wolf McNally, Christopher Allen
Date: May 12, 2020
Revised: April 26, 2025

Introduction

A limited, base-32 character set is required by Uniform Resources (UR) [BCR5] in order to be compatible with both URI syntax [RFC3986] and QR Code alphanumeric mode [QRCodeAlphaNum]. In addition, [BCR5] specifies:

Each UR encoded object includes a type component as the first path component after the UR scheme. Types MUST consist only of characters from the English letters (ignoring case), Arabic numerals, and the hyphen -.

Because this namespace intersects with but does not enclose existing type namespace definitions such as [MIME] and because defined types like MIME do not uniformly specify CBOR encoding (required by [BCR5]) a new namespace is necessary to easily identify the type of data encoded in a UR.

This document is a registry of UR types and CBOR tags maintained by Blockchain Commons. Each entry in the registry records the type string, its associated CBOR tag, a brief description of the type, and either a link to the type definition or a reference to the type definition within this document. Additional types may be added by contacting this document's maintainers.

Types specified within this document are specified in [CDDL], the Concise Data Definition Language used as a human-readable notation for CBOR structures.

User-Defined Types x-*

All types with the prefix x- are reserved for user-defined UR types.

CBOR-Wrapped Types cbor-*

All types with the prefix cbor- are reserved for existing non-CBOR media types wrapped in a CBOR byte string. The only types currently specified in this registry are cbor-png for [PNG] images and cbor-svg for [SVG] images.

Tags for Embedding

Each UR type defines a CBOR encoding. When a UR type is suitable for embedding within another CBOR structure, it MUST be tagged with a CBOR tag defined for this purpose. When a UR type is used as the top-level CBOR object encoded into a UR, the object MUST NOT be tagged, as this information is provided by the UR type component.

This document also lists the tag, if any, defined for the particular CBOR structure contained in the UR encoding. The tags listed here may or may not currently be listed in IANA's registry of CBOR tags [CBOR-TAGS] but the intent is that they will be registered as they come into us.

Some of the UR types and their corresponding CBOR tags below have been deprecated. There may be existing software that still uses these "version 1" types and tags however, so it is RECOMMENDED that such software only read the deprecated types and tags and not write them, preferring the version 2 types and tags instead. Deprecated types and tags below are denoted using strikethrough.

Registry

CBOR TagUR TypeDescriptionDefinition
200envelopeGordian Envelope[Envelope]
201envelope leafEncapsulated dCBOR[Envelope]
40000known-valueEnvelope known value[BCR-2023-002]
40001digestCryptographic digest[BCR-2021-002]
40002encryptedEncrypted message[BCR-2022-001]
40003compressedCompressed message[BCR-2023-001]
40004requestGSTP request[BCR-2023-014]
40005responseGSTP response[BCR-2023-014]
40006functionFunction identifier[BCR-2023-012]
40007parameterParameter identifier[BCR-2023-012]
40008placeholderFunction placeholder[BCR-2023-012]
40009replacementFunction replacement[BCR-2023-012]
40010agreement-private-keyAgreement private key[BCR-2023-011]
40011agreement-public-keyAgreement public key[BCR-2023-011]
40012aridApparently Random Identifier[BCR-2022-002]
40013crypto-prvkeysPrivate keys[BCR-2023-011]
40014nonceCryptographic nonce[BCR-2023-015]
40015passwordHashed password (e.g., Scrypt)[BCR-2023-016]
40016crypto-prvkey-basePrivate key base[BCR-2023-011]
40017crypto-pubkeysPublicKeys[BCR-2023-011]
40018saltSalt[BCR-2023-017]
40019crypto-sealedSealed message[BCR-2023-011]
40020signatureSignature[BCR-2023-011]
40021signing-private-keySigning private key[BCR-2023-011]
40022signing-public-keySigning public key[BCR-2023-011]
40023crypto-keySymmetric Key[BCR-2022-001]
40024xidXID or XID Document[BCR-2024-010]
40025referenceCryptographically secure reference[BCR-2024-011]
40026eventEvent identifier[BCR-2023-014]
40027encrypted-keyEncrypted key[BCR-2022-001]
40100mlkem-private-keyMLKEM Private Key[BCR-2025-003]
40101mlkem-public-keyMLKEM Public Key[BCR-2025-003]
40102mlkem-ciphertextMLKEM Ciphertext[BCR-2025-003]
40103mldsa-private-keyMLDSA Private Key[BCR-2025-003]
40104mldsa-public-keyMLDSA Private Key[BCR-2025-003]
40105mldsa-signatureMLDSA Signature[BCR-2025-003]
40300 300seed crypto-seedCryptographic seedThis document
40303 303hdkey crypto-hdkeyHierarchical Deterministic (HD) key[BCR-2020-007]
40304 304keypath crypto-keypathKey Derivation Path[BCR-2020-007]
40305 305coin-info crypto-coin-infoCryptocurrency Coin Use[BCR-2020-007]
40306 306eckey crypto-eckeyElliptic Curve (EC) key[BCR-2020-008]
40307 307address crypto-addressCryptocurrency Address[BCR-2020-009]
40308 308output-descriptor crypto-outputBitcoin Output Descriptor[BCR-2020-010]
40309 309sskr crypto-sskrSSKR (Sharded Secret Key Reconstruction) shard[BCR-2020-011]
40310 310psbt crypto-psbtPartially Signed Bitcoin Transaction (PSBT)This document
40311 311account-descriptor crypto-accountBIP44 Account[BCR-2023-019]
40800ssh-privateText format SSH private key[BCR-2024-005]
40801ssh-publicText format SSH public key[BCR-2024-005]
40802ssh-signatureText format SSH signature[BCR-2024-005]
40803ssh-certificateText format SSH certificate[BCR-2024-005]
1347571542 ('PROV')provenanceProvenance Mark[BCR-2024-001]

Notable Tags

CBOR TagUR TypeDescriptionDefinition
16cose-encrypt0COSE_Encrypt0: Encrypted message (implied recipient)[COSE]
17cose-mac0COSE_Mac0: Authenticated message (implied recipient)[COSE]
18cose-sign1COSE_Sign1: Signed message (single recipient)[COSE]
24cborWrapped cbor[CBOR]
96cose-encryptCOSE_Encrypt: Encrypted message (multiple recipients)[COSE]
97cose-macCOSE_Mac: Authenticated message (multiple recipients)[COSE]
98cose-signCOSE_Sign: Signed message (multiple recipients)[COSE]
cose-keyCOSE_Key: An encryption key[COSE]
cose-keysetCOSE_KeySet: A set of encryption keys[COSE]
cbor-pngPNG image[PNG]
cbor-svgSVG image[SVG]

UR Types and CBOR Tags

This document defines the following UR types along with their corresponding CBOR tags:

UR typeCBOR Tag
ur:seed#6.40300

These tags have been registered in the IANA Registry of CBOR Tags.

Cryptographic Seed seed

The type seed contains a single, byte string having a length from 1 to 64 bytes. Semantically, this byte string SHOULD be a random or pseudorandom sequence generated by a cryptographically-strong algorithm.

The type may also include a creation-date attribute which is the number of days since the Unix epoch upon which this seed was generated. See BCR-2023-008 for more information.

The type may also include name, which SHOULD be a short name for the seed, and note, which is an arbitrary amount of text describing the seed.

CDDL

tagged-seed = #6.40300(seed)

seed = {
	payload: bytes,
	? creation-date: tagged-date,
	? name: text,
	? note: text
}
payload = 1
creation-date = 2
name = 3
note = 4

Example/Test Vector

  • For a 16 byte (128-bit) seed generated on May 11, 2020, in the CBOR diagnostic notation:
{
  1: h'c7098580125e2ab0981253468b2dbc52',
  2: 100(18394)
}
  • Encoded as binary using [CBOR-PLAYGROUND]:
A2                                     # map(2)
   01                                  # unsigned(1) payload:
   50                                  # bytes(16)
      C7098580125E2AB0981253468B2DBC52 # payload
   02                                  # unsigned(2) creation-date:
   D8 64                               # tag(100)
      19 47DA                          # unsigned(18394)
  • As a hex string:
A20150C7098580125E2AB0981253468B2DBC5202D8641947DA
  • As a UR:
ur:seed/oeadgdstaslplabghydrpfmkbggufgludprfgmaotpiecffltnlpqdenos
  • UR as QR Code:

Seed Digest Source Specification

When a unique identifier to a seed is needed, an extract of its fields, called the digest source is created and then used as input to the SHA-256 hashing algorithm. The resulting digest can be compared to digests produced the same way to determine whether a seed has a particular identity. See BCR-2021-002: Digests for Digital Objects for more information.

The digest source of a seed is just the payload byte string. All other fields are ignored. For the example test vector above, the payload is:

c7098580125e2ab0981253468b2dbc52

So the digest would be the SHA-256 hash of those bytes:

e824467caffeaf3bbc3e0ca095e660a9bad80ddb6a919433a37161908b9a3986

When encoded as CBOR (diagnostic notation):

seed-digest = #6.40600(h'e824467caffeaf3bbc3e0ca095e660a9bad80ddb6a919433a37161908b9a3986')

Encoded as binary:

D9 0258                                 # tag(600)
   58 20                                # bytes(32)
      E824467CAFFEAF3BBC3E0CA095E660A9BAD80DDB6A919433A37161908B9A3986

Partially Signed Bitcoin Transaction (PSBT) psbt

The type psbt contains a single, deterministic length byte string of variable length up to 2322^{32}-1 bytes. Semantically, this byte string MUST be a valid Partially Signed Bitcoin Transaction encoded in the binary format specified by [BIP174].

CDDL

bytes

Example/Test Vector

  • CBOR diagnostic notation:
h'70736274ff01009a020000000258e87a21b56daf0c23be8e7070456c336f7cbaa5c8757924f545887bb2abdd750000000000ffffffff838d0427d0ec650a68aa46bb0b098aea4422c071b2ca78352a077959d07cea1d0100000000ffffffff0270aaf00800000000160014d85c2b71d0060b09c9886aeb815e50991dda124d00e1f5050000000016001400aea9a2e5f0f876a588df5546e8742d1d87008f000000000000000000'
  • Encoded as binary using [CBOR-PLAYGROUND]:
58 A7                                   # bytes(167)
70736274FF01009A020000000258E87A21B56DAF0C23BE8E7070456C336F7CBAA5C8757924F545887BB2ABDD750000000000FFFFFFFF838D0427D0EC650A68AA46BB0B098AEA4422C071B2CA78352A077959D07CEA1D0100000000FFFFFFFF0270AAF00800000000160014D85C2B71D0060B09C9886AEB815E50991DDA124D00E1F5050000000016001400AEA9A2E5F0F876A588DF5546E8742D1D87008F000000000000000000
  • As a hex string:
58A770736274FF01009A020000000258E87A21B56DAF0C23BE8E7070456C336F7CBAA5C8757924F545887BB2ABDD750000000000FFFFFFFF838D0427D0EC650A68AA46BB0B098AEA4422C071B2CA78352A077959D07CEA1D0100000000FFFFFFFF0270AAF00800000000160014D85C2B71D0060B09C9886AEB815E50991DDA124D00E1F5050000000016001400AEA9A2E5F0F876A588DF5546E8742D1D87008F000000000000000000
  • As a UR:
ur:psbt/hdosjojkidjyzmadaenyaoaeaeaeaohdvsknclrejnpebncnrnmnjojofejzeojlkerdonspkpkkdkykfelokgprpyutkpaeaeaeaeaezmzmzmzmlslgaaditiwpihbkispkfgrkbdaslewdfycprtjsprsgksecdratkkhktikewdcaadaeaeaeaezmzmzmzmaojopkwtayaeaeaeaecmaebbtphhdnjstiambdassoloimwmlyhygdnlcatnbggtaevyykahaeaeaeaecmaebbaeplptoevwwtyakoonlourgofgvsjydpcaltaemyaeaeaeaeaeaeaeaeaebkgdcarh
  • UR as QR Code:

COSE Structures cose-*

[COSE] specifies CBOR-encoded structures for transmitting signed and/or encrypted objects. This document specifies UR types starting with cose- for the various COSE messages in their untagged form.

Implementations

Typescript/Javascript Implementation: ur-registry

Java Implementation: hummingbird

Normative References

Informative References