hasher

README

Go Hasher

A wrapper around some common hashing functions with customizable encoding

If any issues/bugs are found please raise an issue on github here: Issue Tracker

---

• Docs
• Getting Started
  • Basic Usage
  • Hmac Usage
  • Custom Encoder Usage
• Functions
  • Hash Functions
  • Hmac Functions
  • Encoding Functions

Docs

Online: https://pkg.go.dev/github.com/gymshark/go-hasher

Local: godoc -http=:6060

Getting started

import "github.com/gymshark/go-hasher"

Basic usage

import "github.com/gymshark/go-hasher"

func main() {
    h := hasher.Sha256([]byte("hello world.")).Base64()
    fmt.Println(h) //base64 encoded hash
}

Hmac usage

import "github.com/gymshark/go-hasher"

func main() {
    secretKey := "secretKey"
    hmac := hasher.HmacSha512([]byte("hello world."), secretKey).Base64()
    fmt.Println(hmac) //base64 encoded hmac
    
    //securely check for equality
    eq := hasher.Equal([]byte(hmac), []byte("random-invalid-hmac"))

    //Output: false
    fmt.Println(eq)
}

Custom Encoder

This allows you to pass a func with the signature of func ([]byte) string to the encoder when the lib may not supply a helper function for your needs

import "github.com/gymshark/go-hasher"

func main() {
	encodingFn := func(b []byte) string {
        //encode the bytes however you want
        encodedstring := string(b)
        return encodedstring
    }
	
    h := hasher.Sha1([]byte("hello world.")).Encode(encodingFn)
    fmt.Println(h) //encoded hash result of custom function
}

Functions

Hash functions

Md5([]byte)
Sha1([]byte)
Sha256([]byte)
Sha512([]byte)
Sha3([]byte)

Hmac functions

HmacMd5([]byte, string)
HmacSha1([]byte, string)
HmacSha256([]byte, string)
HmacSha512([]byte)

There is no Sha3 hmac function due to Sha3 being resistant to length extension attacks, you can append your secret key to your data then use Sha3([]byte) to generate your hash data.

𝑚𝑎𝑐=SHA3(𝑘||𝑚) is a secure MAC if 𝑘 is a fixed-length key. This is an explicit design goal of SHA3.

Encoding functions

Hex() // base16
Base32()
Base64()
Base64UrlSafe()
Encode(func([]byte) string) //allows custom encoding

Documentation

Overview

Package hasher is a utility wrapper around some common hashing functions with customizable encoding

Supported encodings

Base64, Base64UrlSafe, Base32, Hex, Custom Encoding Function

If an encoding is supplied that is not recognised an "unsupported encoding" error will be returned with an empty string in the hash value, so it is recommended to use the constants supplied with this package

Index

• func Equal(h1, h2 []byte) bool
• type Hash
  • func HmacMd5(data []byte, secret string) Hash
  • func HmacSha1(data []byte, secret string) Hash
  • func HmacSha256(data []byte, secret string) Hash
  • func HmacSha512(data []byte, secret string) Hash
  • func Md5(data []byte) Hash
  • func Sha1(data []byte) Hash
  • func Sha256(data []byte) Hash
  • func Sha3(data []byte) Hash
  • func Sha512(data []byte) Hash
  • func (h Hash) Base32() string
  • func (h Hash) Base64() string
  • func (h Hash) Base64UrlSafe() string
  • func (h Hash) Encode(fn func(src []byte) string) string
  • func (h Hash) Hex() string

Examples

• Equal
• Hash.Base32
• Hash.Base64
• Hash.Base64UrlSafe
• Hash.Encode
• Hash.Hex
• HmacMd5
• HmacSha1
• HmacSha256
• HmacSha512
• Md5
• Sha1
• Sha256
• Sha3
• Sha512

Functions

func Equal

func Equal(h1, h2 []byte) bool

Equal compares two hashes for equality without leaking timing information.

Example

d := []byte("hello")
h1 := Sha256(d).Hex()
h2 := Sha512(d).Hex()

eq := Equal([]byte(h1), []byte(h2))
fmt.Println(eq)

Output:

false

Types

type Hash

type Hash []byte

Hash allows the addition of encoding functions to the hashed data

func HmacMd5

func HmacMd5(data []byte, secret string) Hash

HmacMd5 returns a new HMAC hash using md5.

Example

h := HmacMd5([]byte("hello"), "secretKey").Base64()
fmt.Println(h)

func HmacSha1

func HmacSha1(data []byte, secret string) Hash

HmacSha1 returns a new HMAC hash using sha1.

Example

h := HmacSha1([]byte("hello"), "secretKey").Base64()
fmt.Println(h)

func HmacSha256

func HmacSha256(data []byte, secret string) Hash

HmacSha256 returns a new HMAC hash using sha256.

Example

h := HmacSha256([]byte("hello"), "secretKey").Base64()
fmt.Println(h)

func HmacSha512

func HmacSha512(data []byte, secret string) Hash

HmacSha512 returns a new HMAC hash using sha512.

Example

h := HmacSha512([]byte("hello"), "secretKey").Base64()
fmt.Println(h)

func Md5

func Md5(data []byte) Hash

Md5 returns a md5 checksum

Example

h := Md5([]byte("hello")).Hex()
fmt.Println(h)

func Sha1

func Sha1(data []byte) Hash

Sha1 returns a sha1 checksum

Example

h := Sha1([]byte("hello")).Hex()
fmt.Println(h)

func Sha256

func Sha256(data []byte) Hash

Sha256 returns a sha2-256 checksum

Example

h := Sha256([]byte("hello")).Hex()
fmt.Println(h)

func Sha3

func Sha3(data []byte) Hash

Sha3 returns a sha3-256 checksum using the ShakeSum256 function

Example

h := Sha3([]byte("hello")).Hex()
fmt.Println(h)

func Sha512

func Sha512(data []byte) Hash

Sha512 returns a sha2-512 checksum

Example

h := Sha512([]byte("hello")).Hex()
fmt.Println(h)

func (Hash) Base32

func (h Hash) Base32() string

Base32 returns a string representation of the hash in base32 encoding

Example

h := Sha1([]byte("hello")).Base32()
fmt.Println(h)

func (Hash) Base64

func (h Hash) Base64() string

Base64 returns a string representation of the hash in base64 encoding

Example

h := Sha512([]byte("hello")).Base64()
fmt.Println(h)

func (Hash) Base64UrlSafe

func (h Hash) Base64UrlSafe() string

Base64UrlSafe returns a string representation of the hash in Base64UrlSafe encoding

Example

h := Sha512([]byte("hello")).Base64UrlSafe()
fmt.Println(h)

func (Hash) Encode

func (h Hash) Encode(fn func(src []byte) string) string

Encode allows users to pass their own custom stringer func

Example

binaryFunc := func(b []byte) string {
	return fmt.Sprintf("%08b", b)
}

h := Sha512([]byte("hello")).Encode(binaryFunc)
fmt.Println(h)

func (Hash) Hex

func (h Hash) Hex() string

Hex returns a string representation of the hash in Hex (base16) encoding

Example

h := Sha512([]byte("hello")).Hex()
fmt.Println(h)