hasher

README

Adaptive Password Hasher

A simple, adaptive, password hashing module for Go!

Using the pbkdf2 key derivation algorithm, the module has functionality to hash and verify hashes, for a number of different hash algorithms, key and salt sizes. Currently, only the SHA256 and SHA512 hashing functions are supported - more are to come if needed, but feel free to open a PR for another.

Contents

• Installation
• Get Started
  • Defaults
• Advanced
  • Hash Keys
  • Setup
• Info

Installation

Installation is very simple. By using the Go CLI and go get installation can be achieved by running:

go get -u github.com/reecerussell/adaptive-password-hasher

Get Started

To get started, you must first install the package, which you can do here.

First of all, add the module import:

import (
    hasher "github.com/reecerussell/adaptive-password-hasher"
)

Then, you can use the exported functions Hash and Verify. Hashing a password can be done as follows:

pwd := []byte("MySuperSecurePassword")
hash := hasher.hash(pwd)
    
// encode & print
fmt.Printf("My Hashed Password: %s\n", base64.StdEncoding.EncodeToString(hash))

So what if you need to verify it? Easy!

ok := hasher.Verify(pwd, hash)
fmt.Printf("Verified: %v\n", ok)

And that's it!

Defaults

These exported functions all use the default hasher interface, meaning they use the default hashing values.

Default	Value	Property
Iteration Count	1000	DefaultIterationCount
Salt Size	128-bit	DefaultSaltSize
Key Size	256-bit	DefaultKeySize
Hashing Algorithm	SHA256	DefaultHashKey

Advanced

So you'd like to change the hashing algorithm or maybe even key size. It's just as simple as using the default functions. By using the New() function, you can pass in your own settings. The New() function requires 4 parameters: iteration count, salt size, key size and a hashing algorithm key.

Hash Keys

Currently, both SHA256 and SHA512 are supported, which means you can use them in your password hasher. Stored as constants, each supported algorithm has a "hash key", which make it easy to switch to different hashes and are used to distinguise what hash functions were used for a specific hash.

Constant	Algorithm	Value
HashSHA256	SHA256	1
HashSHA512	SHA512	2

Setup

Using this module with the New() function allows a lot more versability by enabling you to customise the hasher to your needs.

Here is an example on how to set it up:

myIterationCount := 15000
mySaltSize := 128
myKeySize := 256
myHashKey := hasher.HashSHA512

myHasher, err := hasher.New(myIterationCount, mySaltSize, myKeySize, myHashKey)
if err != nil {
    panic(err)
}

// hash a password
pwd := []byte("MySecurePassword")
hash := myHasher.Hash([]byte(pwd))

// encode and print
fmt.Printf("Hash: %s\n", base64.StdEncoding.EncodeToString(hash))

// verify
ok := myHasher.Verify(pwd, hash)
fmt.Printf("Verified: %v\n", ok)

Using the "advanced" method of setting up the hasher, you get the same API and functions as the default method of using it. It's worth noting you can pass in the default constants as arguments to the New() function.

Info

Updated on 11/06/2020 - Reece

Documentation

Index

• Constants
• Variables
• func Hash(pwd []byte) []byte
• func Verify(pwd, hash []byte) bool
• type Hasher
  • func New(iterCtn, saltSize, keySize, hashKey int) (Hasher, error)

Constants

const (
	// HashSHA256 is the has key used to tell a hasher
	// to use the SHA256 hashing algorithm.
	HashSHA256 = 1

	// HashSHA512 is the has key used to tell a hasher
	// to use the SHA512 hashing algorithm.
	HashSHA512 = 2

	// DefaultIterationCount is the default number of times a
	// password will be hashed.
	DefaultIterationCount = 1000

	// DefaultSaltSize is the default size of password salts.
	DefaultSaltSize = 128

	// DefaultKeySize is the default size of password sub-keys.
	DefaultKeySize = 256

	// DefaultHashKey is the default hash key.
	DefaultHashKey = HashSHA256
)

Variables

var (
	ErrInvalidIterationCount = errors.New("iteration count must be at least 1")
	ErrInvalidSaltSize       = errors.New("salt size must be positive and divisible by 8")
	ErrInvalidKeySize        = errors.New("key size must be positive and divisinle by 8")
)

Common errors.

Functions

func Hash

func Hash(pwd []byte) []byte

Hash hases the given password using the default hasher.

func Verify

func Verify(pwd, hash []byte) bool

Verify attempts to verifiy the password using the default hasher.

Types

type Hasher

type Hasher interface {
	Hash(pwd []byte) []byte
	Verify(pwd, hash []byte) bool
}

Hasher is a high-level interface used to hash and verify passwords using the pbkdf2 key derivation algorithm. Using an adaptive format, passwords can be hashed using different hash algorithms and key sizes.

func New

func New(iterCtn, saltSize, keySize, hashKey int) (Hasher, error)

New returns a new Hasher, configured with the given values.

Both saltSize and keySize are recognised as number of bits. So, the given values must be divisible by 8, for the number of bytes.

A non-nil error will be returned if any of the values are invalid.