Skip to content

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

License

Notifications You must be signed in to change notification settings

iqlusioninc/veriform

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Veriform

Build Status Apache 2.0 licensed

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

Specification

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.