acrypt

README

Acrypt

Overview

Secure password hashing using the Argon2id hashing algorithm.

import (
    // ...
    "github.com/bitdabbler/acrypt"
)

Usage

Simple API

The simplest API accepts password inputs directly as strings.

Hashing a password

pwd := "secret"
hash, err := acrypt.Hash(pwd)
if err != nil {
    log.Print(err)
}
fmt.Println(hash)

Verifying a password

pwd := "secret"
hash, err := acrypt.Hash(pwd)
if err != nil {
    log.Print(err)
}
if acrypt.Verify(hash, pwd) {
    log.Println("the password is good")
}

(Also simple) Bcrypt-like API

The other API expects passwords to be passed as byte slices, and uses naming similar that used in the Go Bcrypt package.

ref: https://pkg.go.dev/golang.org/x/crypto/bcrypt

Hashing a password

pwd := []byte("secret")
hash, err := acrypt.GenerateFromPassword(pwd, DefaultConfig)
if err != nil {
    log.Print(err)
}
fmt.Println(hash)

Verifying a password

pwd := []byte("secret")
hash, err := acrypt.GenerateFromPassword(pwd, DefaultConfig)
if err != nil {
    log.Print(err)
}
if acrypt.CompareHashAndPassword(hash, pwd) == nil {
    log.Println("the password is good")
}

Documentation

Overview

Package acrypt provides an interface similar to the bcrypt library interface, but uses the Argon2id hashing algorithm for improved security. It also provides a slightly simpler interface, convenient for implementations that do not need to use the Bcrypt one.

Index

• Constants
• Variables
• func CompareHashAndPassword(hashedPassword, password []byte) error
• func GenerateFromPassword(password []byte, cfg *Config) ([]byte, error)
• func Hash(password string) ([]byte, error)
• func Verify(hashedPassword []byte, password string) bool
• type Config

Examples

• CompareHashAndPassword
• GenerateFromPassword
• Hash
• Verify

Constants

const HashID = "$argon2id"

HashID exposes a constant identifier that can be used to refer to hashes generated by this library. Every hash will also be prefixed with this value, allowing clients to quickly test hashes for type.

Variables

var DefaultConfig = &Config{
	MemoryKB:    1 << 16,
	Times:       3,
	Parallelism: 2,
	SaltLength:  16,
	KeyLength:   32,
}

DefaultConfig defines the Argon2 hashing parameters used by default. Values for several of the parameters are recommended in the RFC draft: https://tools.ietf.org/html/draft-irtf-cfrg-argon2-04#section-3.1

The default configuration is exposed, so the values can be updated at the package level, allowing developers to customize the configuration while still leveraging the simpler API.

Functions

func CompareHashAndPassword

func CompareHashAndPassword(hashedPassword, password []byte) error

CompareHashAndPassword compares an acrypt hashed password with its possible plaintext equivalent. It returns nil upon success.

Example

pwd := []byte("secret")
hash, err := GenerateFromPassword(pwd, DefaultConfig)
if err != nil {
	fmt.Print(err)
}
if CompareHashAndPassword(hash, pwd) == nil {
	fmt.Println("the password is good")
}

Output:

the password is good

func GenerateFromPassword

func GenerateFromPassword(password []byte, cfg *Config) ([]byte, error)

GenerateFromPassword returns a hash generated using the configuration parameters provided for the Argon2id hashing algorithm. If the config param is nil, then the default config values will be used.

Example

pwd := []byte("secret")
hash, err := GenerateFromPassword(pwd, DefaultConfig)
if err != nil {
	fmt.Print(err)
}
fmt.Println(string(hash))

func Hash

func Hash(password string) ([]byte, error)

Hash a password string using the package level `DefaultConfig`.

Example

pwd := "secret"
hash, err := Hash(pwd)
if err != nil {
	fmt.Print(err)
}
fmt.Println(hash)

func Verify

func Verify(hashedPassword []byte, password string) bool

Verify compares an Acrypt hashed password with its possible plaintext string equivalent.

Example

pwd := "secret"
hash, err := Hash(pwd)
if err != nil {
	fmt.Print(err)
}
if Verify(hash, pwd) {
	fmt.Println("the password is good")
}

Types

type Config

type Config struct {
	MemoryKB    uint32
	Times       uint32 // iterations
	Parallelism uint8
	SaltLength  uint32
	KeyLength   uint32
}

Config contains the configuration parameters used for the Argon2id algorithm.