objecthash

Crates.ioobjecthash
lib.rsobjecthash
version0.4.1
sourcesrc
created_at2016-08-08 08:21:00.423394
updated_at2017-01-17 02:13:07.05986
descriptionA content hashing algorithm which works across multiple encodings (JSON, Protobufs, etc)
homepagehttps://github.com/cryptosphere/rust-objecthash
repositoryhttps://github.com/cryptosphere/rust-objecthash
max_upload_size
id5921
size16,569
semver-owners (github:rust-lang-nursery:semver-owners)

documentation

README

ObjectHash for Rust Latest Version Build Status Apache 2 licensed

A content hash algorithm which works across multiple encodings (JSON, Protobufs, etc).

This crate provides a Rust implementation of an algorithm originally created by Ben Laurie.

Is it any good?

Yes.

Is it "Production Ready™"?

DANGER: EXPERIMENTAL

No! ObjectHash is an experimental algorithm, and is subject to change. Please do not depend on it yet.

Additionally, this is a project of a cryptographic nature and has not received any expert review.

Use at your own risk.

Installation

You will need to select a supported cryptography library to use as ObjectHash's backend. The following backend libraries are supported:

  • ring: A safe, fast, small Rust crypto library based on BoringSSL's cryptography primitives

Please make sure to add a crypto backend crate or the objecthash crate will not work!

Usage

ObjectHashes can be used to compute a content hash of a deeply nested structure. The intended use is to first deserialize data into a nested structure, then perform an ObjectHash digest of its contents. This way, the same content hash to be computed regardless of how the data is serialized, which allows the data to be transcoded between formats without having to recompute the content hash.

This crate defines a trait called ObjectHash:

pub trait ObjectHash {
    fn objecthash<H: ObjectHasher>(&self, hasher: &mut H);
}

There are built-in implementations of the ObjectHash trait for the following types:

  • Vec<T: ObjectHash>
  • HashMap<K: ObjectHash, V: ObjectHash>
  • str
  • String
  • Integers:
    • i8
    • i16
    • i32
    • i64
    • u8
    • u16
    • u32
    • u64
    • isize
    • usize

To calculate the ObjectHash digest of some data, call the following:

let digest: Vec<u8> = objecthash::digest(42);

This will compute a digest (using the SHA-256 algorithm) of the given value, provided the type of the value given implements the ObjectHash trait.

Macros

The objecthash_struct! macro is designed to simplify implementing the ObjectHash trait on structs, producing a dict-type hash across their keys and values:

impl ObjectHash for MyStruct {
    #[inline]
    fn objecthash<H: ObjectHasher>(&self, hasher: &mut H) {
        objecthash_struct!(
            hasher,
            "foo" => self.foo,
            "bar" => self.bar,
            "baz" => self.baz
        )
    }
}

TODO

  • More types
  • More test vectors
  • Redaction support

Contributing

  • Fork this repository on Github
  • Make your changes and send a pull request
  • If your changes look good, we'll merge them

Copyright

Copyright (c) 2016-2017 Tony Arcieri. Distributed under the Apache 2.0 License. See LICENSE file for further details.

Commit count: 58

cargo fmt