argon2id

README

argon2id

This package provides a wrapper around Go's argon2 using the argon2id variant. It provides multiple helper functions to make a secure implementation easier.

Usage

package main

import (
  "log"

  "github.com/dhenkes/argon2id"
)

func main() {
  // HashPassword returns the argon2 key (hash) of a given password.
  hash, err := argon2id.HashPassword("securepassword", "randomsalt", argon2id.DefaultOptions)
  if err != nil {
    log.Fatal(err)
  }

  // VerifyPassword takes a given argon2 hash and a plaintext password and
  // compares both. It will return an error if an issue occurs or the given
  // password does not match the hash.
  err = argon2id.VerifyPassword("securepassword", hash)
  if err == argon2id.ErrHashNotEqualPassword {
    log.Printf("Hash does not match password.")
    return
  }

  if err != nil {
    log.Fatal(err)
  }

  log.Printf("Hash matches password.")
}

Documentation

Overview

Package argon2id provides a wrapper around Go's argon2 using the argon2id variant. It provides multiple helper functions to make a secure implementation easier.

Index

• Variables
• func DecodeBase64String(s string) ([]byte, error)
• func EncodeToBase64String(b []byte) string
• func HashPassword(password string, salt string, options *Options) (string, error)
• func VerifyPassword(password string, key string) error
• type Options

Variables

var (
	// ErrPasswordRequired is returned by HashPassword or VerifyPassword if no
	// password was provided.
	ErrPasswordRequired = errors.New("argon2id: password must not be empty.")

	// ErrSaltRequired is returned by HashPassword if no salt was provided.
	ErrSaltRequired = errors.New("argon2id: salt must not be empty.")

	// ErrArgon2KeyRequired is returned by VerifyPassword if no argon2 key was
	// provided.
	ErrArgon2KeyRequired = errors.New("argon2id: argon2 key must not be empty.")

	// ErrInvalidKeyLength is returned by VerifyPassword if the provided argon2
	// key is of invalid length.
	ErrInvalidKeyLength = errors.New("argon2id: argon2 key invalid length.")

	// ErrArgonVersionMismatch is returned by VerifyPassword if the provided
	// argon2 key version is different than the one used by the package.
	ErrArgonVersionMismatch = errors.New("argon2id: argon2 key version mismatch.")

	// ErrHashNotEqualPassword is returned by VerifyPassword if the provided
	// hash does not equal the password.
	ErrHashNotEqualPassword = errors.New("argon2id: hash not equal password.")
)

var DefaultOptions = &Options{
	Time:    1,
	Memory:  64 * 1024,
	Threads: 4,
	KeyLen:  32,
}

DefaultOptions contains sane defaults as of December 2021. These defaults are subject to change if new recommendations are released. These settings were chosen for usage in a web application.

Functions

func DecodeBase64String

func DecodeBase64String(s string) ([]byte, error)

DecodeBase64String is a helper function that decodes the given base64 string.

func EncodeToBase64String

func EncodeToBase64String(b []byte) string

EncodeToBase64String is a helper function that turns the given bytes into a base64 encoded string.

func HashPassword

func HashPassword(password string, salt string, options *Options) (string, error)

HashPassword takes a password and a salt and returns an argon2 key that can be saved in a database.

func VerifyPassword

func VerifyPassword(password string, key string) error

VerifyPassword takes a password and an argon2 key and compares both. It will return an error if they are not equal.

Types

type Options

type Options struct {
	Time    uint32
	Memory  uint32
	Threads uint8
	KeyLen  uint32
}

Options contain all the options that can be set using the argon2id algorithm.