jamesmunns / veriform

Security-oriented protobuf-like serialization format with "Merkleized" content hashing support

Veriform is a cryptographically verifiable data serialization format inspired by Protocol Buffers, useful for things like credentials, transparency logs, and "blockchain" applications.

Specification

Rationale (a.k.a. "Oh no! Not another serialization format!")

If you look at another engineer's work and think, "That's dumb. Why don't you just..." Take a breath. Find out why the problem is hard. —Adrienne Porter Felt

Obligatory xkcd

Veriform is similar in design to Protocol Buffers, which is at its core a schema-driven format. It also includes a small amount of information which makes it partly self-describing, "wire types", however they are too limited to comprehend serialized messages in absence of a schema.

Without a fully self-describing wire format, it isn't possible to implement Veriform's primary distinguishing feature: "Merkleized" content hashing which functions even if some of the fields in a message aren't known by the schema. This means that the sender and receiver of a message don't need to be working with the same version of a schema to agree on a message hash, which enables schema evolution.

Veriform is not intended to be a general purpose serialization format: for that we recommend something like Protocol Buffers or Cap'n Proto. While it's fine to use Veriform for general purpose serialization if it fits your needs, it's lacking many features such as an associated RPC protocol. Instead, Veriform is the sort of thing you might use for the credentials passed as part of an RPC protocol.

Another interesting use case for Veriform is Certificate Transparency or otherwise "blockchain"-like systems that heavily rely on cryptographic integrity and Merkle proofs.

Veriform's data model is isomorphic with a subset of TJSON, a microformat which extends JSON with richer types. All Veriform documents can be bidirectionally transcoded to/from TJSON with no data loss. Furthermore, TJSON documents can be authenticated with the same Merkleized hashing scheme as Veriform, meaning signatures for one encoding will validate in the other.

Comparison with other serialization formats

The table below compares Veriform to the other formats:

Name	Schemas	Self-Describing	Integers	Authentication	Standardization
Veriform	💚†	💚	vint64	Structured Hashing	None
ASN.1 DER	💔	💛	Fixed-Width	Canonicalization	ITU/IETF
Cap'n Proto	💚	💚	Fixed-Width	Canonicalization	None
CBOR	💔	💚	Fixed-Width	Canonicalization	IETF
csexp	💔	💚	Fixed-Width	Canonicalization	IETF
MessagePack	💔	💚	Fixed-Width	None	None
Protobuf	💚	💔	LEB128	Canonicalization	None
XDR	💚	💔	Fixed-Width	None	IETF

†NOTE: Coming soon!

Status

Veriform does not yet provide the minimum viable functionality it needs to be useful. The table below covers the current implementation state:

Status	Feature	Notes
🚧	Message Decoding	In progress
⛔	Message Encoding	Not started
🚧	Structured Hashing	In progress
⛔	Schemas	Not started
🚧	TJSON Transcoding	In progress

NOTE: Veriform is a multi-language monorepo: all implementations in all languages within the repo are intended to implement the spec in its current state and share a consistent feature set. The progress above applies equally to all language implementations currently within the repo.

Copyright

Copyright © 2017-2020 Tony Arcieri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed as above, without any additional terms or conditions.