hasher

README

Hasher

The hasher package operates on different hash algorithms through a unified interface. The interfaces it provides include "hash generation" and "comparison of hash values with files (or strings)."

The hasher is cross-platform and has been tested on Windows, macOS, and Linux.

Supported Hash Algorithms

• MD5
• CRC32
• SHA1
• SHA256
• SHA512
• 32-bit FNV-1, FNV-1a
• 64-bit FNV-1, FNV-1a
• 128-bit FNV-1, FNV-1a
• Blake3(64bit)
• MurmurHash v3
• Whirlpool
• xxHash
• Perceptual Hash (only for images)
• User-defined algorithms

Usage

Use default algorithm: MD5

package main

import (
	"fmt"
	"github.com/nao1215/hasher"
	"log"
	"os"
)

func main() {
	// Create a new Hash instance with default options.
	h := hasher.NewHash()

	// Generate a hash from a string.
	hash, err := h.Generate("example")
	if err != nil {
	    log.Fatal(err)
	}

	// Compare a hash with a string.
	err := h.Compare(hash, "example")
	if err != nil {
	    log.Fatal(err)
	}

	// Generate a hash from an io.Reader.
	file, err := os.Open("example.txt")
	if err != nil {
	    log.Fatal(err)
	}
	defer file.Close()
	hash, err = h.Generate(file)
	if err != nil {
	    log.Fatal(err)
	}

	// Compare a hash with an io.Reader.
	file, err = os.Open("example.txt")
	if err != nil {
	    log.Fatal(err)
	}
	defer file.Close()

	err = h.Compare(hash, file)
	if err != nil {
	    log.Fatal(err)
	}
}

Use another algorithm: SHA256

If you use another algorithm, you can specify algorithm option when creating a new Hash instance. If you use SHA256, you can do as follows:

    h := hasher.NewHash(hasher.WithSha256sum())

Use user-defined algorithm

If you use a user-defined algorithm, you must implement the Hasher interface.

// Hasher is an interface that contains the methods to generate and compare hashes.
type Hasher interface {
	// GenHashFromString generates a hash from a string.
	GenHashFromString(string) ([]byte, error)
	// GenHashFromIOReader generates a hash from an io.Reader.
	GenHashFromIOReader(io.Reader) ([]byte, error)
	// CmpHashAndString compares a hash and a string.
	// If the hash and the string are the same, nil is returned.
	CmpHashAndString([]byte, string) error
	// CmpHashAndIOReader compares a hash and an io.Reader.
	// If the hash and the io.Reader are the same, nil is returned.
	CmpHashAndIOReader([]byte, io.Reader) error
}

	// YourOriginalHashAlgorithm implements the Hasher interface.
	h := hasher.NewHash(hasher.WithUserDifinedAlgorithm(YourOriginalHashAlgorithm))

LICENSE

MIT License

Contribution

First off, thanks for taking the time to contribute! Contributions are not only related to development. For example, GitHub Star motivates me to develop! Please feel free to contribute to this project.

Thanks goes to these wonderful people (emoji key):

CHIKAMATSU Naohiro 💻

Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

Documentation

Overview

Package hasher provides functionality for generating and comparing hashes using various algorithms.

The Hash struct contains methods for generating and comparing hashes. By default, the MD5 algorithm is used, but the user can specify a different algorithm using options.

Example usage:

// Create a new Hash instance with default options.
h := hasher.NewHash()

// Generate a hash from a string.
hash, err := h.Generate("example")
if err != nil {
    log.Fatal(err)
}

// Compare a hash with a string.
err := h.Compare(hash, "example")
if err != nil {
    log.Fatal(err)
}

// Generate a hash from an io.Reader.
file, err := os.Open("example.txt")
if err != nil {
    log.Fatal(err)
}
defer file.Close()
hash, err = h.Generate(file)
if err != nil {
    log.Fatal(err)
}

// Compare a hash with an io.Reader.
file, err = os.Open("example.txt")
if err != nil {
    log.Fatal(err)
}
defer file.Close()
err = h.Compare(hash, file)
if err != nil {
    log.Fatal(err)
}

Supported algorithms:

• MD5
• SHA-1
• SHA-256
• SHA-512

Index

• Variables
• type Hash
  • func NewHash(opts ...Option) *Hash
  • func (h *Hash) Compare(hash []byte, input any) error
  • func (h *Hash) Generate(input any) ([]byte, error)
• type Hasher
• type Option
  • func WithAdler32() Option
  • func WithBlake3() Option
  • func WithCRC32() Option
  • func WithFnv128() Option
  • func WithFnv128a() Option
  • func WithFnv32() Option
  • func WithFnv32a() Option
  • func WithFnv64() Option
  • func WithFnv64a() Option
  • func WithMd5() Option
  • func WithMmh3() Option
  • func WithPhash() Option
  • func WithSha1() Option
  • func WithSha256() Option
  • func WithSha512() Option
  • func WithUserDifinedAlgorithm(hasher Hasher) Option
  • func WithWhirlpool() Option
  • func WithXXHash() Option

Variables

var (
	// ErrUnsupportedInputType is an error that is returned when the input type is not supported.
	ErrUnsupportedInputType = errors.New("unsupported input type")
	// ErrHashMismatch is an error that is returned when the hash and the input do not match.
	ErrHashMismatch = errors.New("hash mismatch")
	// ErrPhashNotSupportedString is an error that is returned when phash does not support string input.
	ErrPhashNotSupportedString = errors.New("phash does not support string input")
)

Types

type Hash

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

Hash is a struct that contains the methods to generate and compare hashes.

func NewHash

func NewHash(opts ...Option) *Hash

NewHash returns a new Hasher struct. Default hash algorithm is MD5SUM. The user can specify a different algorithm using options. e.g. NewHash(WithSha1Algorithm())

func (*Hash) Compare

func (h *Hash) Compare(hash []byte, input any) error

Compare compares hash and input. The input can be a string or an io.Reader. If the input is not a string or an io.Reader, ErrUnsupportedInputType is returned. If the hash and the input are the same, nil is returned. If the hash and the input are different with hasher support algorithm, an ErrHashMismatch is returned.

func (*Hash) Generate

func (h *Hash) Generate(input any) ([]byte, error)

Generate generates a hash from the input. The input can be a string or an io.Reader. If the input is not a string or an io.Reader, ErrUnsupportedInputType is returned.

type Hasher

type Hasher interface {
	// GenHashFromString generates a hash from a string.
	GenHashFromString(string) ([]byte, error)
	// GenHashFromIOReader generates a hash from an io.Reader.
	GenHashFromIOReader(io.Reader) ([]byte, error)
	// CmpHashAndString compares a hash and a string.
	// If the hash and the string are the same, nil is returned.
	CmpHashAndString([]byte, string) error
	// CmpHashAndIOReader compares a hash and an io.Reader.
	// If the hash and the io.Reader are the same, nil is returned.
	CmpHashAndIOReader([]byte, io.Reader) error
}

Hasher is an interface that contains the methods to generate and compare hashes.

type Option

type Option func(*Hash)

Option sets the options for the Hasher struct.

func WithAdler32

func WithAdler32() Option

WithAdler32 is an option that sets the hash algorithm to Adler-32.

func WithBlake3

func WithBlake3() Option

WithBlake3 is an option that sets the hash algorithm to Blake3.

func WithCRC32

func WithCRC32() Option

WithCRC32 is an option that sets the hash algorithm to CRC-32.

func WithFnv128

func WithFnv128() Option

WithFnv128 is an option that sets the hash algorithm to FNV-128.

func WithFnv128a

func WithFnv128a() Option

WithFnv128a is an option that sets the hash algorithm to FNV-128a.

func WithFnv32

func WithFnv32() Option

WithFnv32 is an option that sets the hash algorithm to FNV-32.

func WithFnv32a

func WithFnv32a() Option

WithFnv32a is an option that sets the hash algorithm to FNV-32a.

func WithFnv64

func WithFnv64() Option

WithFnv64 is an option that sets the hash algorithm to FNV-64.

func WithFnv64a

func WithFnv64a() Option

WithFnv64a is an option that sets the hash algorithm to FNV-64a.

func WithMd5

func WithMd5() Option

WithMd5 is an option that sets the hash algorithm to MD5SUM.

func WithMmh3

func WithMmh3() Option

WithMmh3 is an option that sets the hash algorithm to Murmur3.

func WithPhash

func WithPhash() Option

WithPhash is an option that sets the hash algorithm to Perceptual Hash.

func WithSha1

func WithSha1() Option

WithSha1 is an option that sets the hash algorithm to SHA-1.

func WithSha256

func WithSha256() Option

WithSha256 is an option that sets the hash algorithm to SHA-256.

func WithSha512

func WithSha512() Option

WithSha512 is an option that sets the hash algorithm to SHA-512.

func WithUserDifinedAlgorithm

func WithUserDifinedAlgorithm(hasher Hasher) Option

WithUserDifinedAlgorithm is an option that sets the hash algorithm to a user-defined algorithm.

func WithWhirlpool

func WithWhirlpool() Option

WithWhirlpool is an option that sets the hash algorithm to Whirlpool.

func WithXXHash

func WithXXHash() Option

WithXXHash is an option that sets the hash algorithm to XXHash.