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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 (*Argon) ComparePasswordAndKey ¶
ComparePasswordAndKey compares a plain text password with the supplied key, and returns true if the hash in the key matches the password.
type RandomSourceReader ¶ added in v1.0.1
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.
Source Files