Multiformats
draft-snell-multihash-00

Abstract

Defines Multiformats, a collection of data formats that aim to future-proof systems by adding self-description to format values; and defines the Multihash and Multibase Multiformat data formats.

Status of This Memo

This Internet-Draft is submitted to IETF 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 August 27, 2020.

Copyright Notice

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

Table of Contents

• 1. Introduction
• 2. Unsigned Variable Length Integer
• 2.1. ABNF Definition
• 3. Multibase
• 3.1. Examples
• 3.2. Multibase ABNF
• 4. Multihash
• 4.1. Example Multihashes
• 4.2. Multihash ABNF
• 5. Security Considerations
• 6. IANA Considerations
• 6.1. The Codec Registry
• 6.1.1. Codec Registration
• 6.1.2. Initial Contents
• 6.2. The Multibase Registry
• 6.2.1. Base-Encoding Registration
• 6.2.2. Initial Contents
• 7. Normative References
• Authors' Addresses

1. Introduction

Multiformats are a collection of data formats that aim to future-proof systems by adding self-description to format values; allowing interoperability and protocol agility while avoiding lock in.

The self-describing aspects of the Multiformat values have a few stipulations:

• They MUST be in-band (encoded within and carried with the value).
• They MUST avoid lock-in and promote extensibility.
• They MUST be compact and have a binary-packed representation.
• They MUST have a human-readable representation.

This specification defines the Multihash and Multibase formats.

This specification also defines extensible registries for codec and base-encoding identifiers.

New Multiformat data formats SHOULD be registered within the Codec Registry using the "multiformat" type identifier.

In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119].

This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234]

2. Unsigned Variable Length Integer

The various Multiformats defined in this specification make use of the Unsigned Variable Length Integer encoding defined in Appendix C of the [LEB128] standard.

As suggested by the name, this variable length encoding is only capable of representing unsigned integers. Further, while there is no theoretical maximum integer value that can be represented by the format, implementations MUST NOT encode more than nine (9) bytes giving a practical limit of integers in a range between 0 and 2^63 - 1.

Specific Multiformats using the Unsigned Variable Length Integer encoding MAY explicitly declare a more restricted range of encoded values but MUST NOT require values greater than 2^63 - 1.

All integer values between 0 and 127 are encoded as a single byte that is identical to the input. That is, the value 1 is encoded as 00000001, and the value 127 is encoded as 01111111.

Values greater than 127 require two or more bytes as illustrated in the examples below.

Numbers MUST be encoded using the least number of bytes possible.

2.1. ABNF Definition

Specifications signal use of the Unsigned Variable Length Encoded Integer format by referencing the unsigned-varint ABNF grammar rule defined below.

varint-terminator = %x00-7f
varint-continuation = %x80-ff
unsigned-varint = *8varint-continuation varint-terminator

3. Multibase

Multibase is a format for differentiating outputs from various well-established text base-encoding algorithms.

A Multibase consists simply of a single prefix character that identifies the base-encoding of the remaining characters. All valid Multibase prefix characters are registered in The Multibase Registry.

The prefix character for each base are selected such that they are included in the alphabets of the base they represent. For example, "f" is the base code for base16 (hex) because "f" is in hex's 16 character alphabet.

3.1. Examples

Given the sample text, "Multibase is awesome! \o/", the following example Multibase encodings may be generated.

3.2. Multibase ABNF

ABNF

base-identifier = <ascii character>
multibase = base-identifier {base-encoded-data}

4. Multihash

Multihash is a format for differentiating outputs from various well-established cryptographic hash functions while adressing output length and encoding considerations.

Multihash values encode the hash function output prefixed by an id identifying the hash function encoded as an unsigned variable length integer, and the length of the hash function output encoded as an unsigned variable length integer. All valid Multihash function identifiers are registered in the Codec Registry.

Multihash values are byte sequences that MAY be encoded in multiple base-encodings including hex, base64, base32, or others. When representing a Multihash using a base-encoding, the Multibase format SHOULD be used.

4.1. Example Multihashes

Given the sample text "multihash", the following example Multihash values may be generated:

4.2. Multihash ABNF

Multihash

hash-function-code = unsigned-varint
hash-digest-size = unsigned-varint
hash = {hash function output}

multihash = hash-function-code hash-digest-size hash

5. Security Considerations

There are no additional security considerations introduced by the use of Multiformat data formats. Note, however, that various hash functions that may be used with multiformats may be vulnerable to various known security issues and limitations (e.g. sha1) and thus SHOULD be avoided.

6. IANA Considerations

6.1. The Codec Registry

6.1.1. Codec Registration

Codec identifiers can be registered using the procedure described herein.

Codecs are registered using the Expert Review policy (see Section 4.5 of [RFC8126]). The goal of the registry is to reflect common use of codecs on the Internet. Therefore, the expert(s) should be strongly biased towards approving registrations, unless they are abusive, frivolous, not likely to be used on the Internet, or actively harmful to the Internet and/or the Web (not merely aesthetically displeasing or architecturally dubious). Expert(s) can withhold registration of codecs that are too general for the proposal application.

Expert(s) will clearly identify any issues that cause a registration to be refused. Advice about the semantics of a proposed codec can be given, but if it does not block registration, this should be explicitly stated.

When a request if approved, the expert(s) shall inform IANA, and the regstration will be processed. The IESG is the final arbiter of any objection.

The Codec Registry is located at https://www.iana.org/assignments/multiformat-codecs. Registration requests can be made by following instructions located there or by sending an email to the multiformat-codecs@ietf.org mailing list.

Registration requests consist of at least the following information:

• *Codec Name*: The name of codec
• *Type*: The type of applicable multiformat
• *Code*: The requested identity code
• *Description*: An optional short text description of the codec.
• *Reference*: A reference to the document that specifies the codec, preferably including a URI that can be used to retrieve a copy of the document. An indication of the relevant section(s) can also be included but is not required.

Multiformat data formats themselves MAY be registered within The Codec Registry using a Type field value of "multiformat". For all other registrations, the Type field MUST refer to an entry in The Codec Registry whose Type is "multiformat".

The expert(s) can define additional fields to be collected in the registry.

Registrations SHOULD reference a freely available, stable specification.

Note that codecs can be registere by third parties (including the expert(s)), if the expert(s) determine that an unregistered codec is widely deployed and not likely to be registered in a timely manner otherwise. Such registrations still are subject to the requirements defined.

6.1.2. Initial Contents

The initial contents of the Codec Registry include:

For each of the above entries, this document serves as the reference.

6.2. The Multibase Registry

6.2.1. Base-Encoding Registration

Base-encoding identifiers can be registered using the procedure described herein.

Base-encodings are registered using the Expert Review policy (see Section 4.5 of [RFC8126]). The goal of the registry is to reflect common use of codecs on the Internet. Therefore, the expert(s) should be strongly biased towards approving registrations, unless they are abusive, frivolous, not likely to be used on the Internet, or actively harmful to the Internet and/or the Web (not merely aesthetically displeasing or architecturally dubious). Expert(s) can withhold registration of codecs that are too general for the proposal application.

Expert(s) will clearly identify any issues that cause a registration to be refused. Advice about the semantics of a proposed codec can be given, but if it does not block registration, this should be explicitly stated.

When a request if approved, the expert(s) shall inform IANA, and the regstration will be processed. The IESG is the final arbiter of any objection.

The Multibase Registry is located at https://www.iana.org/assignments/multiformat-base. Registration requests can be made by following instructions located there or by sending an email to the multiformat-codecs@ietf.org mailing list.

Registration requests consist of at least the following information:

• *Name*: The name of base-encoding
• *Prefix*: The requested prefix identifier
• *Description*: An optional short text description of the base encoding.
• *Status*: An indicator of the current implementation status of the encoding and prefix. MUST be one of "draft", "candidate", or "default".
• *Reference*: A reference to the document that specifies the base encoding, preferably including a URI that can be used to retrieve a copy of the document. An indication of the relevant section(s) can also be included but is not required.

Each of the Status field values indicates the following meanings:

• *draft*: The encoding has been proposed but is not widely implemented and may be removed in the future.
• *candidate*: The encoding is mature and widely implemented by many but not all implementations.
• *default*: The encoding SHOULD be implemented by all implementations and are widely used.

The expert(s) can change the Status of a registration at any time.

The expert(s) can define additional fields to be collected in the registry.

Registrations SHOULD reference a freely available, stable specification.

Note that base encoding can be registered by third parties (including the expert(s)), if the expert(s) determine that an unregistered base encoding is widely deployed and not likely to be registered in a timely manner otherwise. Such registrations still are subject to the requirements defined.

6.2.2. Initial Contents

The initial contents of the Multibase Registry are as follows:

For each of the above entries, this document serves as the reference.

7. Normative References

Authors' Addresses