noble

README

Noble

Noble is a simple wrapper to make working with Go's implementation of Argon2 (specifically Argon2id) much easier. Argon2 is a modern ASIC-resistant and GPU-resistant secure key derivation function. It has better password cracking resistance (when configured correctly) than PBKDF2 , Bcrypt and Scrypt (for similar configuration parameters for CPU and RAM usage).

You would use this package when saving password hashes to a database for user authentication. While Go's bcrypt and scrypt packages are battle tested and popular, they are more vulnerable to password cracking, particularly with the advent of powerful GPU chips on modern systems.

Argon2 is a key derivation function that was selected as the winner of the 2015 Password Hashing Competition. It was designed by Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich from the University of Luxembourg. There are three different versions of the algorithm, and according to OWASP, the Argon2id variant should be used, as it provides a balanced approach to resisting both side-channel and GPU-based attacks.

Installation

Install it in the usual way:

go get -u github.com/tsawler/noble

Example

package main

import (
	"fmt"
	"github.com/tsawler/noble"
	"log"
)

func main() {
	// Create an instance of the type noble.Argon.
	n := noble.New()

	// Try creating a hash from a password. The returned value will 
	// include the hash, as well as all information need to validate a 
	// password against that hash using argon2.
	password := "verysecret"
	hash, err := n.GeneratePasswordKey(password)
	if err != nil {
		log.Println(err)
	}

	fmt.Println("hash for", password, "\n\t", hash)

	// Try comparing a valid password against this hash.
	valid, err := n.ComparePasswordAndKey(password, hash)
	fmt.Println("First password/hash compare is", valid)

	// Now compare with an invalid password.
	valid, err = n.ComparePasswordAndKey(password+"fish", hash)
	fmt.Println("Second password/hash compare is", valid)
}

The output of this program is:

(base) tcs@Grendel nobleapp % go run .
hash for verysecret 
         $argon2id$v=19$m=61440,t=1,p=4$XjQXPOyUmwUJAFPgNSMi+w$ZhBXt6gtrBnNyrFQ+i0ZlTbLS6WWrK8WKRmVQtXbY/Y
First password/hash compare is true
Second password/hash compare is false

Documentation

Overview

Package noble implements a simple wrapper which makes working with argon2 as simple as possible.

Index

• type Argon
  • func New() Argon
  • func (a *Argon) ComparePasswordAndKey(password, hash string) (bool, error)
  • func (a *Argon) GeneratePasswordKey(password string) (string, error)
• type RandomSourceReader
• type Reader

Types

type Argon

type Argon struct {
	Time              uint32 // the execution time, given in number of iterations.
	Memory            uint32 // the memory usage, given in kibibytes (1024 bytes).
	Threads           uint8  // the number of parallel threads.
	KeyLen            uint32 // the key length; for AES-256, use 32.
	MinPasswordLength uint32 // specifies a minimum length for the supplied password.
	Reader            Reader // a type that exists simply so we can swap readers for testing.
}

Argon is the main type for this module. Creating a variable of this type (typically with the New function) gives access to the two methods GeneratePasswordKey and ComparePasswordAndKey.

func New

func New() Argon

New returns an instance of the Noble type with sensible defaults.

func (*Argon) ComparePasswordAndKey

func (a *Argon) ComparePasswordAndKey(password, hash string) (bool, error)

ComparePasswordAndKey compares a plain text password with the supplied key, and returns true if the hash in the key matches the password.

func (*Argon) GeneratePasswordKey

func (a *Argon) GeneratePasswordKey(password string) (string, error)

GeneratePasswordKey takes a supplied plain text password and creates a key from it. The ID key is of type Argon2id, which is the current recommended version by OWASP.

type RandomSourceReader

type RandomSourceReader struct{}

RandomSourceReader is an empty type so that we can swap in a test reader to simulate the situation where we can't generate a salt using crypto/rand.

type Reader

type Reader interface {
	// contains filtered or unexported methods
}

Reader is an interface used for testing purposes. In order to satisfy this interface, a type must implement this function.