argon2

README

Argon2

This package add functionality to golang.org/x/crypto/argon2, for generating argon2 hashes and verify it.

Installation

$ go get github.com/marlonmp/argon2

Usage

Generate Hash

If you want to generate a hash, just hash the password, GenerateHash function create a random salt and have a default argon2 parameters.

password := "some password"

hash := argon2.GenerateHash(password)

If you want to generate your own salt, no biggie, you can pass it in GenerateHashNSalt function.

salt := "some salt"

password := "some password"

hash, err := argon2.GenerateHashNSalt(password, salt)

if err == argon2.InvalidSalt { ... }

Or if you want to create your custom options, check this out.

// default options in argon2
var defaultOptions = &Options{
	Algorithm:   &Argon2ID{},
	Version:     argon2.Version,
	Memory:      64,
	Iterations:  3,
	Parallelism: 3,

	HashLength: 32,
	SaltLength: 16,
}

// You can create your custom options, and modify whatever you want.

myOptions := &argon2.Options{
	Algorithm:   &argon2.Argon2I{},
	Iterations:  4,
}

password := "some password"

hash := argon2.GenerateHash(password, myOptions)

Verification

To verify if the password is equal to a encoded hash, call the VerifyHash function.

password := "some password"
encodedHash := "some encoded hash"


isEqual, err := argon2.VerifyHash(password, encodedHash)

if err == argon2.InvalidHash { ... }

if err == argon2.InvalidSalt { ... }

// base64 error
if err != nil { ... }

if isEqual {
    println(password, "is equal to:", encodedHash)

} else {
    println(password, "is not equal to:", encodedHash)

}

Documentation

Index

• Constants
• Variables
• func GenerateHash(password string, customOptions ...Options) string
• func GenerateHashNSalt(password, salt string, customOptions ...Options) (string, error)
• func VerifyHash(password, encodedHash string) (bool, error)
• type Argon2I
  • func (Ai *Argon2I) GetAlgorithm() string
  • func (Ai *Argon2I) Hash(salt, password []byte, options *Options) []byte
• type Argon2ID
  • func (Aid *Argon2ID) GetAlgorithm() string
  • func (Aid *Argon2ID) Hash(salt, password []byte, options *Options) []byte
• type Options

Constants

const (
	// D  = "argon2d"
	I  = "argon2i"
	ID = "argon2id"
)

algorithms

Variables

var (
	AlgorithmNotSupported = errors.New("argon2: algorithm not supported")
	InvalidSalt           = errors.New("argon2: invalid salt")
	InvalidHash           = errors.New("argon2: invalid hash")
	InvalidHashParameters = errors.New("argon2: invalid hash parameters")
)

Functions

func GenerateHash

func GenerateHash(password string, customOptions ...Options) string

GenerateHash: Gets a password with optional hash options and returns the password hashed in argon2 with a random salt.

func GenerateHashNSalt

func GenerateHashNSalt(password, salt string, customOptions ...Options) (string, error)

GenerateHashNSalt: Gets password and salt in string and optional options and return the password hashed in argon2.

Return the error InvalidSalt if the salt is invalid

func VerifyHash

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

VerifyHash: Gets password and encodedHash in string and compare if the password is equal to the encoded hash.

Return the InvalidHash error if the hash is not valid, or return a error from base64.RawStdEncoding.Strict().DecodeString.

Types

type Argon2I

type Argon2I struct{}

func (*Argon2I) GetAlgorithm

func (Ai *Argon2I) GetAlgorithm() string

func (*Argon2I) Hash

func (Ai *Argon2I) Hash(salt, password []byte, options *Options) []byte

type Argon2ID

type Argon2ID struct{}

func (*Argon2ID) GetAlgorithm

func (Aid *Argon2ID) GetAlgorithm() string

func (*Argon2ID) Hash

func (Aid *Argon2ID) Hash(salt, password []byte, options *Options) []byte

type Options

type Options struct {

	// Argon2 information
	Algorithm   algorithm
	Version     int
	Memory      uint32
	Iterations  uint32
	Parallelism uint8

	// Hash information
	HashLength uint32
	SaltLength uint8
}