easyhash

README

easyhash

English | 中文文档

A small Go toolkit for password hashing, hash verification, and future migration-friendly helpers.

The repository currently keeps the existing low-level algorithm-specific APIs for compatibility, and now starts exposing a higher-level library skeleton around:

• Hash
• Verify
• Identify
• NeedsRehash
• VerifyAndUpgrade

Installation

go get github.com/gofurry/easyhash

Quick Start

package main

import (
	"fmt"
	"log"

	"github.com/gofurry/easyhash"
)

func main() {
	pass := "12345678"

	hash, err := easyhash.Hash(pass)
	if err != nil {
		log.Fatal(err)
	}

	ok, err := easyhash.Verify(pass, hash)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("verified:", ok)
}

High-Level API

• Hash(password, opts...) defaults to PBKDF2-SHA256.
• Verify(password, encodedHash) accepts the new easyhash format and legacy stored hashes.
• Identify(encodedHash) helps with migration and diagnostics.
• NeedsRehash(encodedHash, policy) reports whether a hash should be upgraded.
• VerifyAndUpgrade(password, encodedHash, policy) verifies and returns a replacement hash when policy requires it.

Compatibility API

The existing low-level APIs remain available:

• CreateArgon2 / VerifyArgon2
• CreatePBKDF2 / VerifyPBKDF2
• CreateScrypt / VerifyScrypt
• CreateBcrypt / VerifyBcrypt
• CreateMD5

Package Layout

easyhash/
  crypto.go
  errors.go
  format.go
  hash.go
  options.go
  policy.go
  types.go
  docs/usage.md
  docs/zh/README_zh.md
  docs/roadmap.md
  examples/README.md
  examples/password/main.go

Security Notes

• Hashing is not encryption.
• PBKDF2-SHA256 is the default high-level algorithm in Hash.
• Use WithArgon2id() or WithBcrypt() when you want a different tradeoff.
• MD5 is legacy-only and should not be used for new password storage.
• DefaultSalt exists for backwards compatibility and behaves closer to a global pepper-like suffix than to a per-hash salt.
• File and token helpers are planned, but the current package is still primarily a password hashing library.

Examples

• Example index: examples/README.md
• Password example: examples/password/main.go

Usage Guide

See docs/usage.md for a focused walkthrough of the high-level API and migration flow.

Roadmap

See docs/roadmap.md for the current Chinese roadmap used to track repository evolution.

Documentation

Index

• Constants
• Variables
• func CreateArgon2(cfg Argon2, password string) (string, error)
• func CreateBcrypt(cost int, password string) (string, error)
• func CreateMD5(str string) string
• func CreatePBKDF2(cfg PBKDF2, password string) (string, error)
• func CreateScrypt(cfg Scrypt, password string) (string, error)
• func Hash(password string, opts ...Option) (string, error)
• func NeedsRehash(encodedHash string, policy Policy) (bool, error)
• func Verify(password, encodedHash string) (bool, error)
• func VerifyAndUpgrade(password, encodedHash string, policy Policy) (ok bool, newHash string, upgraded bool, err error)
• func VerifyArgon2(password, storedHash string) (bool, error)
• func VerifyBcrypt(password, storedHash string) bool
• func VerifyPBKDF2(password string, storedStr string) (bool, error)
• func VerifyScrypt(password, storedHash string) (bool, error)
• type Algorithm
  • func Identify(encodedHash string) (Algorithm, error)
• type Argon2
  • func DefaultArgon2() Argon2
• type Option
  • func WithArgon2id() Option
  • func WithArgon2idConfig(cfg Argon2) Option
  • func WithBcrypt() Option
  • func WithBcryptCost(cost int) Option
  • func WithPBKDF2() Option
  • func WithPBKDF2Config(cfg PBKDF2) Option
  • func WithScrypt() Option
  • func WithScryptConfig(cfg Scrypt) Option
• type Options
  • func DefaultOptions() Options
• type PBKDF2
  • func DefaultPBKDF2() PBKDF2
• type Policy
  • func DefaultPolicy() Policy
  • func LowMemoryPolicy() Policy
  • func StrongPolicy() Policy
• type Scrypt
  • func DefaultScrypt() Scrypt

Examples

• Hash
• VerifyAndUpgrade

Constants

const DefaultBcryptCost = 12

const DefaultSalt = "AwesomeGolangCrypto"

DefaultSalt is a package-wide password suffix retained for backwards compatibility. It behaves closer to a global pepper than to a per-hash random salt.

Variables

var (
	ErrInvalidHashFormat    = errors.New("easyhash: invalid hash format")
	ErrUnsupportedAlgorithm = errors.New("easyhash: unsupported algorithm")
)

Functions

func CreateArgon2

func CreateArgon2(cfg Argon2, password string) (string, error)

CreateArgon2 generates an Argon2id hash for the given password using the provided configuration. Returns a base64-encoded string in format: salt:time:memory:threads:hash

func CreateBcrypt

func CreateBcrypt(cost int, password string) (string, error)

CreateBcrypt generates a bcrypt hash for the given password with the specified cost. Cost should be between 4 and 31, with 12-14 being recommended for most applications.

func CreateMD5

func CreateMD5(str string) string

CreateMD5 creates an MD5 hash of the input string. WARNING: MD5 is cryptographically broken and should not be used for password hashing. This function is provided for legacy compatibility only.

func CreatePBKDF2

func CreatePBKDF2(cfg PBKDF2, password string) (string, error)

CreatePBKDF2 generates a PBKDF2 hash for the given password using the provided configuration. Returns a base64-encoded string in format: salt:iterations:hash

func CreateScrypt

func CreateScrypt(cfg Scrypt, password string) (string, error)

CreateScrypt generates a scrypt hash for the given password using the provided configuration. Returns a base64-encoded string in format: salt:N:r:p:hash

func Hash

func Hash(password string, opts ...Option) (string, error)

Hash hashes a password using the selected high-level algorithm. The default algorithm is PBKDF2-SHA256.

Example

package main

import (
	"fmt"

	"github.com/gofurry/easyhash"
)

func main() {
	hash, err := easyhash.Hash("12345678")
	if err != nil {
		fmt.Println("error")
		return
	}

	algorithm, err := easyhash.Identify(hash)
	if err != nil {
		fmt.Println("error")
		return
	}

	fmt.Println(algorithm)
}

Output:
pbkdf2-sha256

func NeedsRehash

func NeedsRehash(encodedHash string, policy Policy) (bool, error)

NeedsRehash reports whether a stored hash should be upgraded to match the policy.

func Verify

func Verify(password, encodedHash string) (bool, error)

Verify verifies a password against either the new easyhash format or legacy hashes.

func VerifyAndUpgrade

func VerifyAndUpgrade(password, encodedHash string, policy Policy) (ok bool, newHash string, upgraded bool, err error)

VerifyAndUpgrade verifies a password and returns a replacement hash when policy requires it.

Example

package main

import (
	"fmt"

	"github.com/gofurry/easyhash"
)

func main() {
	legacy, err := easyhash.CreateArgon2(easyhash.DefaultArgon2(), "12345678")
	if err != nil {
		fmt.Println("error")
		return
	}

	ok, newHash, upgraded, err := easyhash.VerifyAndUpgrade("12345678", legacy, easyhash.DefaultPolicy())
	if err != nil {
		fmt.Println("error")
		return
	}

	algorithm, err := easyhash.Identify(newHash)
	if err != nil {
		fmt.Println("error")
		return
	}

	fmt.Println(ok, upgraded, algorithm)
}

Output:
true true pbkdf2-sha256

func VerifyArgon2

func VerifyArgon2(password, storedHash string) (bool, error)

VerifyArgon2 verifies a password against a stored Argon2 hash

func VerifyBcrypt

func VerifyBcrypt(password, storedHash string) bool

VerifyBcrypt verifies a password against a stored bcrypt hash

func VerifyPBKDF2

func VerifyPBKDF2(password string, storedStr string) (bool, error)

VerifyPBKDF2 verifies a password against a stored PBKDF2 hash

func VerifyScrypt

func VerifyScrypt(password, storedHash string) (bool, error)

VerifyScrypt verifies a password against a stored scrypt hash

Types

type Algorithm

type Algorithm string

Algorithm identifies the password hashing algorithm used by a stored hash.

const (
	AlgorithmArgon2id Algorithm = "argon2id"
	AlgorithmBcrypt   Algorithm = "bcrypt"
	AlgorithmPBKDF2   Algorithm = "pbkdf2-sha256"
	AlgorithmScrypt   Algorithm = "scrypt"
	AlgorithmMD5      Algorithm = "md5"
)

func Identify

func Identify(encodedHash string) (Algorithm, error)

Identify returns the hashing algorithm used by an encoded hash.

type Argon2

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

Argon2 configuration struct for Argon2id password hashing

func DefaultArgon2

func DefaultArgon2() Argon2

DefaultArgon2 returns an Argon2 configuration with secure default values

type Option

type Option func(*Options)

Option mutates high-level hash options.

func WithArgon2id

func WithArgon2id() Option

WithArgon2id selects Argon2id for Hash.

func WithArgon2idConfig

func WithArgon2idConfig(cfg Argon2) Option

WithArgon2idConfig overrides the Argon2id configuration for Hash.

func WithBcrypt

func WithBcrypt() Option

WithBcrypt selects bcrypt for Hash.

func WithBcryptCost

func WithBcryptCost(cost int) Option

WithBcryptCost overrides the bcrypt cost for Hash.

func WithPBKDF2

func WithPBKDF2() Option

WithPBKDF2 selects PBKDF2-SHA256 for Hash.

func WithPBKDF2Config

func WithPBKDF2Config(cfg PBKDF2) Option

WithPBKDF2Config overrides the PBKDF2 configuration for Hash.

func WithScrypt

func WithScrypt() Option

WithScrypt selects scrypt for Hash.

func WithScryptConfig

func WithScryptConfig(cfg Scrypt) Option

WithScryptConfig overrides the scrypt configuration for Hash.

type Options

type Options struct {
	Algorithm  Algorithm
	Argon2id   Argon2
	PBKDF2     PBKDF2
	Scrypt     Scrypt
	BcryptCost int
}

Options configures the high-level Hash API.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default high-level hashing configuration.

type PBKDF2

type PBKDF2 struct {
	PBKDF2Iterations int // Number of iterations for key derivation
	PBKDF2KeyLength  int // Length of the derived key in bytes
	SaltLength       int // Length of the random salt in bytes
}

PBKDF2 configuration struct for PBKDF2 password hashing

func DefaultPBKDF2

func DefaultPBKDF2() PBKDF2

DefaultPBKDF2 returns a PBKDF2 configuration with secure default values

type Policy

type Policy struct {
	PreferredAlgorithm Algorithm
	Argon2id           Argon2
	PBKDF2             PBKDF2
	Scrypt             Scrypt
	BcryptCost         int
	AllowLegacyMD5     bool
}

Policy describes when a stored hash should be upgraded.

func DefaultPolicy

func DefaultPolicy() Policy

DefaultPolicy returns the default migration target for the high-level API.

func LowMemoryPolicy

func LowMemoryPolicy() Policy

LowMemoryPolicy keeps Argon2id resource usage lower for constrained environments.

func StrongPolicy

func StrongPolicy() Policy

StrongPolicy uses more conservative defaults for new password hashes.

type Scrypt

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

Scrypt configuration struct for scrypt password hashing

func DefaultScrypt

func DefaultScrypt() Scrypt

DefaultScrypt returns a Scrypt configuration with secure default values