password

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 23, 2026 License: MIT Imports: 7 Imported by: 0

README

password

Secure password hashing and verification using bcrypt and Argon2id, the two algorithms recommended by OWASP for password storage.

Both algorithms produce self-describing hash strings that encode the algorithm, parameters, salt, and digest, so a stored hash carries everything needed to verify it. Argon2id is the primary recommendation (memory-hard, GPU-resistant); bcrypt is provided as a widely-compatible alternative.

Key functions

  • Hash(plain string, opts *Options) (string, error) — produce a self-describing hash
  • Verify(plain, stored string) bool — verify a password against a stored hash
  • NeedsRehash(stored string, opts *Options) bool — detect outdated parameters for transparent upgrades
  • MustHash — panic-on-error variant for tests/init

Key types

  • Options — algorithm selection and tuning (cost, memory, threads, key/salt length)
  • Algorithm — AlgorithmArgon2id (default) or AlgorithmBcrypt

Quick start

import "github.com/LingByte/ling-base/common/password"

hashed, err := password.Hash("my-secret-password", nil)

if password.Verify("my-secret-password", hashed) {
    // access granted
}

if password.NeedsRehash(hashed, nil) {
    newHash, _ := password.Hash("my-secret-password", nil)
    // persist newHash
}

Documentation

Overview

Package password provides secure password hashing and verification using bcrypt and Argon2id, the two algorithms recommended by OWASP for password storage.

Algorithm selection

Argon2id is the primary recommendation (memory-hard, GPU-resistant). Bcrypt is provided as a widely-compatible alternative. Both produce self-describing hash strings that encode the algorithm, parameters, salt, and digest, so a stored hash carries everything needed to verify it.

Quick start

// Hash a password with Argon2id (recommended).
hashed, err := password.Hash("my-secret-password", nil)
if err != nil { return err }

// Verify.
if password.Verify("my-secret-password", hashed) {
    // access granted
}

// Check if a hash needs rehashing (e.g. params are outdated).
if password.NeedsRehash(hashed, nil) {
    newHash, _ := password.Hash("my-secret-password", nil)
    // persist newHash
}

Migrating from bcrypt to Argon2id

// On next login:
if password.Verify(plain, stored) {
    if password.NeedsRehash(stored, nil) {
        newHash, _ := password.Hash(plain, nil)
        // save newHash
    }
}

Index

Constants

View Source
const (
	// DefaultBcryptCost is the default bcrypt cost factor.
	// OWASP recommends a minimum of 10; 12 provides ~250ms per hash on
	// modern hardware. Adjust based on your hardware and latency budget.
	DefaultBcryptCost = 12

	// DefaultArgon2Time is the default Argon2id time cost (iterations).
	DefaultArgon2Time = 3
	// DefaultArgon2Memory is the default Argon2id memory cost in KiB.
	// 64 * 1024 = 64 MB. OWASP recommends a minimum of 19 MiB; 64 MiB
	// provides strong resistance. Adjust based on your hardware.
	DefaultArgon2Memory = 64 * 1024
	// DefaultArgon2Threads is the default Argon2id parallelism (threads).
	DefaultArgon2Threads = 2
	// DefaultArgon2KeyLen is the default Argon2id output key length in bytes.
	DefaultArgon2KeyLen = 32
	// DefaultArgon2SaltLen is the default Argon2id salt length in bytes.
	DefaultArgon2SaltLen = 16
)

Variables

View Source
var (
	// ErrEmptyPassword is returned when hashing an empty password.
	ErrEmptyPassword = errors.New("password: password must not be empty")
	// ErrInvalidHash is returned when a stored hash is malformed or uses an
	// unknown algorithm.
	ErrInvalidHash = errors.New("password: invalid hash format")
	// ErrPasswordTooLong is returned when the password exceeds 72 bytes
	// (bcrypt limitation).
	ErrPasswordTooLong = errors.New("password: password exceeds 72 bytes for bcrypt")
)

Functions

func Hash

func Hash(plain string, opts *Options) (string, error)

Hash produces a self-describing password hash string.

By default, Argon2id is used. The returned string encodes the algorithm and all parameters so that Verify can reconstruct the computation without external configuration:

"$argon2id$v=19$m=65536,t=3,p=2$<base64-salt>$<base64-key>"
"$bcrypt$<bcrypt-hash>"

Pass nil for opts to use secure defaults.

func MustHash

func MustHash(plain string, opts *Options) string

MustHash is like Hash but panics on error. Use only in tests or initialization where a hash failure is unrecoverable.

func NeedsRehash

func NeedsRehash(stored string, opts *Options) bool

NeedsRehash reports whether a stored hash should be recomputed with current parameters. This is true when:

  • The algorithm differs from the target (default: Argon2id).
  • The bcrypt cost is lower than the target.
  • The Argon2id time/memory/threads are lower than the target.

Use this on login to transparently upgrade hashes to stronger params. Pass nil for opts to compare against defaults.

func Verify

func Verify(plain, stored string) bool

Verify checks whether plain matches the given stored hash. The hash format determines the algorithm used; no external config is needed. Returns false (not an error) if the password doesn't match.

Types

type Algorithm

type Algorithm string

Algorithm identifies a password hashing algorithm.

const (
	// AlgorithmArgon2id is the Argon2id algorithm (recommended).
	AlgorithmArgon2id Algorithm = "argon2id"
	// AlgorithmBcrypt is the bcrypt algorithm.
	AlgorithmBcrypt Algorithm = "bcrypt"
)

func AlgorithmOf

func AlgorithmOf(stored string) Algorithm

AlgorithmOf returns the algorithm used by a stored hash, or Algorithm("") if the hash is unrecognized.

type Options

type Options struct {
	// Algorithm selects the hashing algorithm. Defaults to AlgorithmArgon2id.
	Algorithm Algorithm

	// BcryptCost is the bcrypt cost factor (4-31). Defaults to 12.
	// Only used when Algorithm == AlgorithmBcrypt.
	BcryptCost int

	// Argon2Time is the Argon2id time cost (iterations). Defaults to 3.
	// Only used when Algorithm == AlgorithmArgon2id.
	Argon2Time uint32
	// Argon2Memory is the Argon2id memory cost in KiB. Defaults to 65536 (64MB).
	// Only used when Algorithm == AlgorithmArgon2id.
	Argon2Memory uint32
	// Argon2Threads is the Argon2id parallelism. Defaults to 2.
	// Only used when Algorithm == AlgorithmArgon2id.
	Argon2Threads uint8
	// Argon2KeyLen is the output key length in bytes. Defaults to 32.
	// Only used when Algorithm == AlgorithmArgon2id.
	Argon2KeyLen uint32
	// Argon2SaltLen is the salt length in bytes. Defaults to 16.
	// Only used when Algorithm == AlgorithmArgon2id.
	Argon2SaltLen uint32
}

Options configures password hashing. Zero values use safe defaults.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL