README

go-multihash

GoDoc Travis CI codecov.io

multihash implementation in Go

Table of Contents

Install

go-multihash is a standard Go module which can be installed with:

go get github.com/multiformats/go-multihash

Usage

Example

This example takes a standard hex-encoded data and uses EncodeName to calculate the SHA1 multihash value for the buffer.

The resulting hex-encoded data corresponds to: <hash function code><digest size><hash function output>, which could be re-parsed with Multihash.FromHexString().

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/multiformats/go-multihash"
)

func main() {
	// ignores errors for simplicity.
	// don't do that at home.
	// Decode a SHA1 hash to a binary buffer
	buf, _ := hex.DecodeString("0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33")

	// Create a new multihash with it.
	mHashBuf, _ := multihash.EncodeName(buf, "sha1")
	// Print the multihash as hex string
	fmt.Printf("hex: %s\n", hex.EncodeToString(mHashBuf))

	// Parse the binary multihash to a DecodedMultihash
	mHash, _ := multihash.Decode(mHashBuf)
	// Convert the sha1 value to hex string
	sha1hex := hex.EncodeToString(mHash.Digest)
	// Print all the information in the multihash
	fmt.Printf("obj: %v 0x%x %d %s\n", mHash.Name, mHash.Code, mHash.Length, sha1hex)
}

To run, copy to example/foo.go and:

> cd example/
> go build
> ./example
hex: 11140beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33
obj: sha1 0x11 20 0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33

Contribute

Contributions welcome. Please check out the issues.

Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to multiformats are subject to the IPFS Code of Conduct.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2014 Juan Batiz-Benet

Expand ▾ Collapse ▴

Documentation

Overview

    Package multihash is the Go implementation of https://github.com/multiformats/multihash, or self-describing hashes.

    Index

    Examples

    Constants

    View Source
    const (
    	IDENTITY = 0x00
    	// Deprecated: use IDENTITY
    	ID         = IDENTITY
    	SHA1       = 0x11
    	SHA2_256   = 0x12
    	SHA2_512   = 0x13
    	SHA3_224   = 0x17
    	SHA3_256   = 0x16
    	SHA3_384   = 0x15
    	SHA3_512   = 0x14
    	SHA3       = SHA3_512
    	KECCAK_224 = 0x1A
    	KECCAK_256 = 0x1B
    	KECCAK_384 = 0x1C
    	KECCAK_512 = 0x1D
    
    	SHAKE_128 = 0x18
    	SHAKE_256 = 0x19
    
    	BLAKE2B_MIN = 0xb201
    	BLAKE2B_MAX = 0xb240
    	BLAKE2S_MIN = 0xb241
    	BLAKE2S_MAX = 0xb260
    
    	MD5 = 0xd5
    
    	DBL_SHA2_256 = 0x56
    
    	MURMUR3_128 = 0x22
    	// Deprecated: use MURMUR3_128
    	MURMUR3 = MURMUR3_128
    
    	SHA2_256_TRUNC254_PADDED  = 0x1012
    	X11                       = 0x1100
    	POSEIDON_BLS12_381_A1_FC1 = 0xb401
    )

      constants

      Variables

      View Source
      var (
      	ErrUnknownCode      = errors.New("unknown multihash code")
      	ErrTooShort         = errors.New("multihash too short. must be >= 2 bytes")
      	ErrTooLong          = errors.New("multihash too long. must be < 129 bytes")
      	ErrLenNotSupported  = errors.New("multihash does not yet support digests longer than 127 bytes")
      	ErrInvalidMultihash = errors.New("input isn't valid multihash")
      
      	ErrVarintBufferShort = errors.New("uvarint: buffer too small")
      	ErrVarintTooLong     = errors.New("uvarint: varint too big (max 64bit)")
      )

        errors

        View Source
        var Codes = map[uint64]string{
        	IDENTITY:                  "identity",
        	SHA1:                      "sha1",
        	SHA2_256:                  "sha2-256",
        	SHA2_512:                  "sha2-512",
        	SHA3_224:                  "sha3-224",
        	SHA3_256:                  "sha3-256",
        	SHA3_384:                  "sha3-384",
        	SHA3_512:                  "sha3-512",
        	DBL_SHA2_256:              "dbl-sha2-256",
        	MURMUR3_128:               "murmur3-128",
        	KECCAK_224:                "keccak-224",
        	KECCAK_256:                "keccak-256",
        	KECCAK_384:                "keccak-384",
        	KECCAK_512:                "keccak-512",
        	SHAKE_128:                 "shake-128",
        	SHAKE_256:                 "shake-256",
        	SHA2_256_TRUNC254_PADDED:  "sha2-256-trunc254-padded",
        	X11:                       "x11",
        	POSEIDON_BLS12_381_A1_FC1: "poseidon-bls12_381-a2-fc1",
        	MD5:                       "md5",
        }

          Codes maps a hash code to it's name

          View Source
          var DefaultLengths = map[uint64]int{
          	IDENTITY:     -1,
          	SHA1:         20,
          	SHA2_256:     32,
          	SHA2_512:     64,
          	SHA3_224:     28,
          	SHA3_256:     32,
          	SHA3_384:     48,
          	SHA3_512:     64,
          	DBL_SHA2_256: 32,
          	KECCAK_224:   28,
          	KECCAK_256:   32,
          	MURMUR3_128:  4,
          	KECCAK_384:   48,
          	KECCAK_512:   64,
          	SHAKE_128:    32,
          	SHAKE_256:    64,
          	X11:          64,
          	MD5:          16,
          }

            DefaultLengths maps a hash code to it's default length

            View Source
            var ErrLenTooLarge = errors.New("requested length was too large for digest")
            View Source
            var ErrSumNotSupported = errors.New("Function not implemented. Complain to lib maintainer.")

              ErrSumNotSupported is returned when the Sum function code is not implemented

              View Source
              var Names = map[string]uint64{
              	"identity":                  IDENTITY,
              	"sha1":                      SHA1,
              	"sha2-256":                  SHA2_256,
              	"sha2-512":                  SHA2_512,
              	"sha3":                      SHA3_512,
              	"sha3-224":                  SHA3_224,
              	"sha3-256":                  SHA3_256,
              	"sha3-384":                  SHA3_384,
              	"sha3-512":                  SHA3_512,
              	"dbl-sha2-256":              DBL_SHA2_256,
              	"murmur3-128":               MURMUR3_128,
              	"keccak-224":                KECCAK_224,
              	"keccak-256":                KECCAK_256,
              	"keccak-384":                KECCAK_384,
              	"keccak-512":                KECCAK_512,
              	"shake-128":                 SHAKE_128,
              	"shake-256":                 SHAKE_256,
              	"sha2-256-trunc254-padded":  SHA2_256_TRUNC254_PADDED,
              	"x11":                       X11,
              	"md5":                       MD5,
              	"poseidon-bls12_381-a2-fc1": POSEIDON_BLS12_381_A1_FC1,
              }

                Names maps the name of a hash to the code

                Functions

                func Encode

                func Encode(buf []byte, code uint64) ([]byte, error)

                  Encode a hash digest along with the specified function code. Note: the length is derived from the length of the digest itself.

                  func EncodeName

                  func EncodeName(buf []byte, name string) ([]byte, error)

                    EncodeName is like Encode() but providing a string name instead of a numeric code. See Names for allowed values.

                    Example

                    Code:

                    // ignores errors for simplicity - don't do that at home.
                    buf, _ := hex.DecodeString("0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33")
                    mhbuf, _ := EncodeName(buf, "sha1")
                    mhhex := hex.EncodeToString(mhbuf)
                    fmt.Printf("hex: %v\n", mhhex)
                    
                    hex: 11140beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33
                    

                    func RegisterHashFunc

                    func RegisterHashFunc(code uint64, hashFunc HashFunc) error

                      RegisterHashFunc adds an entry to the package-level code -> hash func map. The hash function must return at least the requested number of bytes. If it returns more, the hash will be truncated.

                      func ValidCode

                      func ValidCode(code uint64) bool

                        ValidCode checks whether a multihash code is valid.

                        Types

                        type DecodedMultihash

                        type DecodedMultihash struct {
                        	Code   uint64
                        	Name   string
                        	Length int    // Length is just int as it is type of len() opearator
                        	Digest []byte // Digest holds the raw multihash bytes
                        }

                          DecodedMultihash represents a parsed multihash and allows easy access to the different parts of a multihash.

                          func Decode

                          func Decode(buf []byte) (*DecodedMultihash, error)

                            Decode parses multihash bytes into a DecodedMultihash.

                            Example

                            Code:

                            // ignores errors for simplicity - don't do that at home.
                            buf, _ := hex.DecodeString("0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33")
                            mhbuf, _ := EncodeName(buf, "sha1")
                            o, _ := Decode(mhbuf)
                            mhhex := hex.EncodeToString(o.Digest)
                            fmt.Printf("obj: %v 0x%x %d %s\n", o.Name, o.Code, o.Length, mhhex)
                            
                            obj: sha1 0x11 20 0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33
                            

                            type ErrInconsistentLen

                            type ErrInconsistentLen struct {
                            	// contains filtered or unexported fields
                            }

                              ErrInconsistentLen is returned when a decoded multihash has an inconsistent length

                              func (ErrInconsistentLen) Error

                              func (e ErrInconsistentLen) Error() string

                              type HashFunc

                              type HashFunc func(data []byte, length int) (digest []byte, err error)

                                HashFunc is a hash function that hashes data into digest.

                                The length is the size the digest will be truncated to. While the hash function isn't responsible for truncating the digest, it may want to error if the length is invalid for the hash function (e.g., truncation would make the hash useless).

                                type Multihash

                                type Multihash []byte

                                  Multihash is byte slice with the following form: <hash function code><digest size><hash function output>. See the spec for more information.

                                  func Cast

                                  func Cast(buf []byte) (Multihash, error)

                                    Cast casts a buffer onto a multihash, and returns an error if it does not work.

                                    func FromB58String

                                    func FromB58String(s string) (m Multihash, err error)

                                      FromB58String parses a B58-encoded multihash.

                                      func FromHexString

                                      func FromHexString(s string) (Multihash, error)

                                        FromHexString parses a hex-encoded multihash.

                                        func MHFromBytes

                                        func MHFromBytes(buf []byte) (int, Multihash, error)

                                          MHFromBytes reads a multihash from the given byte buffer, returning the number of bytes read as well as the multihash

                                          func Sum

                                          func Sum(data []byte, code uint64, length int) (Multihash, error)

                                            Sum obtains the cryptographic sum of a given buffer. The length parameter indicates the length of the resulting digest and passing a negative value use default length values for the selected hash function.

                                            func (Multihash) B58String

                                            func (m Multihash) B58String() string

                                              B58String returns the B58-encoded representation of a multihash.

                                              func (*Multihash) HexString

                                              func (m *Multihash) HexString() string

                                                HexString returns the hex-encoded representation of a multihash.

                                                func (*Multihash) String

                                                func (m *Multihash) String() string

                                                  String is an alias to HexString().

                                                  type Reader

                                                  type Reader interface {
                                                  	io.Reader
                                                  
                                                  	ReadMultihash() (Multihash, error)
                                                  }

                                                    Reader is an io.Reader wrapper that exposes a function to read a whole multihash, parse it, and return it.

                                                    func NewReader

                                                    func NewReader(r io.Reader) Reader

                                                      NewReader wraps an io.Reader with a multihash.Reader

                                                      type Set

                                                      type Set struct {
                                                      	// contains filtered or unexported fields
                                                      }

                                                        Set is a set of Multihashes, holding one copy per Multihash.

                                                        func NewSet

                                                        func NewSet() *Set

                                                          NewSet creates a new set correctly initialized.

                                                          func (*Set) Add

                                                          func (s *Set) Add(m Multihash)

                                                            Add adds a new multihash to the set.

                                                            func (*Set) All

                                                            func (s *Set) All() []Multihash

                                                              All returns a slice with all the elements in the set.

                                                              func (*Set) ForEach

                                                              func (s *Set) ForEach(f func(m Multihash) error) error

                                                                ForEach runs f(m) with each multihash in the set. If returns immediately if f(m) returns an error.

                                                                func (*Set) Has

                                                                func (s *Set) Has(m Multihash) bool

                                                                  Has returns true if the element is in the set.

                                                                  func (*Set) Len

                                                                  func (s *Set) Len() int

                                                                    Len returns the number of elements in the set.

                                                                    func (*Set) Remove

                                                                    func (s *Set) Remove(m Multihash)

                                                                      Remove removes an element from the set.

                                                                      func (*Set) Visit

                                                                      func (s *Set) Visit(m Multihash) bool

                                                                        Visit adds a multihash only if it is not in the set already. Returns true if the multihash was added (was not in the set before).

                                                                        type Writer

                                                                        type Writer interface {
                                                                        	io.Writer
                                                                        
                                                                        	WriteMultihash(Multihash) error
                                                                        }

                                                                          Writer is an io.Writer wrapper that exposes a function to write a whole multihash.

                                                                          func NewWriter

                                                                          func NewWriter(w io.Writer) Writer

                                                                            NewWriter wraps an io.Writer with a multihash.Writer

                                                                            Directories

                                                                            Path Synopsis
                                                                            Package opts helps to write commands which may take multihash options.
                                                                            Package opts helps to write commands which may take multihash options.