multihash

package module
v0.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 12, 2023 License: MIT Imports: 11 Imported by: 1,504

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

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
	BLAKE3     = 0x1E

	SHAKE_128 = 0x18
	SHAKE_256 = 0x19

	BLAKE2B_MIN = 0xb201
	BLAKE2B_MAX = 0xb240
	BLAKE2S_MIN = 0xb241
	BLAKE2S_MAX = 0xb260

	MD5 = 0xd5

	DBL_SHA2_256 = 0x56

	MURMUR3X64_64 = 0x22
	// Deprecated: use MURMUR3X64_64
	MURMUR3 = MURMUR3X64_64

	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",
	MURMUR3X64_64:             "murmur3-x64-64",
	KECCAK_224:                "keccak-224",
	KECCAK_256:                "keccak-256",
	KECCAK_384:                "keccak-384",
	KECCAK_512:                "keccak-512",
	BLAKE3:                    "blake3",
	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 = mhreg.DefaultLengths

DefaultLengths maps a multihash indicator code to the output size for that hash, in units of bytes.

View Source 
var ErrLenTooLarge = mhreg.ErrLenTooLarge
View Source 
var ErrSumNotSupported = mhreg.ErrSumNotSupported

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-x64-64":            MURMUR3X64_64,
	"keccak-224":                KECCAK_224,
	"keccak-256":                KECCAK_256,
	"keccak-384":                KECCAK_384,
	"keccak-512":                KECCAK_512,
	"blake3":                    BLAKE3,
	"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.

The error return is legacy; it is always nil.

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 GetHasher added in v0.0.15 

func GetHasher(indicator uint64) (hash.Hash, error)

Register is an alias for Register in the core package.

Consider using the core package instead of this multihash package; that package does not introduce transitive dependencies except for those you opt into, and will can result in smaller application builds.

func Register added in v0.0.15 

func Register(indicator uint64, hasherFactory func() hash.Hash)

Register is an alias for Register in the core package.

Consider using the core package instead of this multihash package; that package does not introduce transitive dependencies except for those you opt into, and will can result in smaller application builds.

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 MHFromBytes added in v0.0.9 

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. Passing a negative value uses default length values for the selected hash function.

func SumStream added in v0.0.16 

func SumStream(r io.Reader, code uint64, length int) (Multihash, error)

SumStream obtains the cryptographic sum of a given stream. The length parameter indicates the length of the resulting digest. Passing a negative value uses 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 added in v0.0.11 

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

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

func NewSet added in v0.0.11 

func NewSet() *Set

NewSet creates a new set correctly initialized.

func (*Set) Add added in v0.0.11 

func (s *Set) Add(m Multihash)

Add adds a new multihash to the set.

func (*Set) All added in v0.0.11 

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

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

func (*Set) ForEach added in v0.0.11 

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 added in v0.0.11 

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

Has returns true if the element is in the set.

func (*Set) Len added in v0.0.11 

func (s *Set) Len() int

Len returns the number of elements in the set.

func (*Set) Remove added in v0.0.11 

func (s *Set) Remove(m Multihash)

Remove removes an element from the set.

func (*Set) Visit added in v0.0.11 

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

Source Files

View all Source files

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.
register
all
This package has no purpose except to perform registration of mulithashes.
 This package has no purpose except to perform registration of mulithashes.
blake2
This package has no purpose except to perform registration of multihashes.
 This package has no purpose except to perform registration of multihashes.
blake3
This package has no purpose except to register the blake3 hash function.
 This package has no purpose except to register the blake3 hash function.
miniosha256
This package has no purpose except to perform registration of multihashes.
 This package has no purpose except to perform registration of multihashes.
murmur3
This package has no purpose except to perform registration of multihashes.
 This package has no purpose except to perform registration of multihashes.
sha256
This package has no purpose except to perform registration of multihashes.
 This package has no purpose except to perform registration of multihashes.
sha3
This package has no purpose except to perform registration of multihashes.
 This package has no purpose except to perform registration of multihashes.
test
sharness/t0030-lib
Generate hasher input that matches BLAKE3's test vectors.
 Generate hasher input that matches BLAKE3's test vectors.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.