multihash

README

go-multihash

multihash implementation in Go

Table of Contents

• Install
• Usage
• Maintainers
• Contribute
• License

Install

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

go get github.com/multiformats/go-multihash

Note that go-multihash is packaged with Gx, so it is recommended to use Gx to install and use it (see Usage section).

Usage

Using Gx and Gx-go

This module is packaged with Gx. In order to use it in your own project it is recommended that you:

go get -u github.com/whyrusleeping/gx
go get -u github.com/whyrusleeping/gx-go
cd <your-project-repository>
gx init
gx import github.com/multiformats/go-multihash
gx install --global
gx-go --rewrite

Please check Gx and Gx-go documentation for more information.

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

Maintainers

Captain: @Kubuxu.

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

Documentation

Overview

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

Index

• Constants
• Variables
• func AppCode(code uint64) bool
• func Encode(buf []byte, code uint64) ([]byte, error)
• func EncodeName(buf []byte, name string) ([]byte, error)
• func ValidCode(code uint64) bool
• type DecodedMultihash
  • func Decode(buf []byte) (*DecodedMultihash, error)
• type ErrInconsistentLen
  • func (e ErrInconsistentLen) Error() string
• type Multihash
  • func Cast(buf []byte) (Multihash, error)
  • func FromB58String(s string) (m Multihash, err error)
  • func FromHexString(s string) (Multihash, error)
  • func Sum(data []byte, code uint64, length int) (Multihash, error)
  • func (m Multihash) B58String() string
  • func (m *Multihash) HexString() string
  • func (m *Multihash) String() string
• type Reader
  • func NewReader(r io.Reader) Reader
• type Writer
  • func NewWriter(w io.Writer) Writer

Examples

• Decode
• EncodeName

Constants

const (
	ID         = 0x00
	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

	DBL_SHA2_256 = 0x56

	MURMUR3 = 0x22
)

constants

Variables

var (
	ErrUnknownCode      = errors.New("unknown multihash code")
	ErrTooShort         = errors.New("multihash too short. must be > 3 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

var Codes = map[uint64]string{
	ID:           "id",
	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:      "murmur3",
	KECCAK_224:   "keccak-224",
	KECCAK_256:   "keccak-256",
	KECCAK_384:   "keccak-384",
	KECCAK_512:   "keccak-512",
	SHAKE_128:    "shake-128",
	SHAKE_256:    "shake-256",
}

Codes maps a hash code to it's name

var DefaultLengths = map[uint64]int{
	ID:           -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:      4,
	KECCAK_384:   48,
	KECCAK_512:   64,
	SHAKE_128:    32,
	SHAKE_256:    64,
}

DefaultLengths maps a hash code to it's default length

var ErrSumNotSupported = errors.New("Function not implemented. Complain to lib maintainer.")

ErrSumNotSupported is returned when the Sum function code is not implemented

var Names = map[string]uint64{
	"id":           ID,
	"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":      MURMUR3,
	"keccak-224":   KECCAK_224,
	"keccak-256":   KECCAK_256,
	"keccak-384":   KECCAK_384,
	"keccak-512":   KECCAK_512,
	"shake-128":    SHAKE_128,
	"shake-256":    SHAKE_256,
}

Names maps the name of a hash to the code

Functions

func AppCode

func AppCode(code uint64) bool

AppCode checks whether a multihash code is part of the App range.

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

// 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)

Output:

hex: 11140beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33

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

// 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)

Output:

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 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 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 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