README
¶
go-argon2
Install
go get github.com/wranders/go-argon2
What is go-argon2 and how do I use it
This package is a interface for the argon2 key derivation function using golang.org/x/crypto/argon2, aiming to provide the simplest interface.
The Hasher is what creates password hashes and is configured directly or generated from a comma-separated key-value string (perfect for storage in configuration files).
The Matches function generates parameters from the provided hash, so the Hasher is not needed.
package main
import "github.com/wranders/go-argon2"
var hasher *argon2.Hasher
func main() {
hasherSettings := "f=argon2id,s=16,k=32,m=65536,t=3,p=2"
hasher, _ := argon2.NewHasherFromString(hasherSettings)
}
func HashPassword(password string) (string, error) {
return hasher.Create(password)
}
func PaswordMatches(password, hash string) (bool, error) {
return argon2.Matches(password, hash)
}
And that's it!
If you prefer to configure the Hasher directly:
var hasher *argon2.Hasher
import "github.com/wranders/go-argon2"
func main() {
hasher = &argon2.Hasher{
Form: argon2.FormID,
SaltLength: 16,
KeyLength: 32,
Memory: 65536,
Iterations: 3,
Parallelism: 2,
}
}
func HashPassword(password string) (string, error) {
return hasher.Create(password)
}
func PaswordMatches(password, hash string) (bool, error) {
return argon2.Matches(password, hash)
}
Interface
const (
FormI Form = iota + 1 //argon2i
FormID //argon2id
)
type Form int
type Hasher struct {
Form Form
Iterations uint32
KeyLength uint32
Memory uint32
Parallelism uint8
SaltLength uint32
}
func Matches(string, string) (bool, error) {}
func NewHasherFromString(string) (*Hasher, error) {}
func (*Hasher) Create(string) (string, error) {}
//Errors
type ErrIncompatibleVersion struct {}
type ErrInvalidForm struct{}
type ErrInvalidHash struct{}
type ErrInvalidHasherConfiguration struct{}
type ErrUnknownSetting struct {}
type ErrUnsupportedExpr struct {}
Configuration
Creating a Hasher from a settings string is simple:
| Key | Value | Meaning |
|---|---|---|
f |
string |
Form (argon2i or argon2id) (argon2d unsupported) |
s |
uint32 |
Salt Length (bytes) |
k |
uint32 |
Key Length (bytes) |
m |
uint32 or Expression |
Memory (kibibytes) |
t |
uint32 |
# Iterations over memory |
p |
uint8 |
Parallelism (number of threads) |
f=[string],s=[uint32],k=[uint32],m=[uint32|expr],t=[uint32],p=[uint8]
Note: Keys can be in any order, as long as they're all there
Memory can be any unsigned 32-bit number (0 - 4294967295), but expressions must evaluate between that range. The upper limit would use just under 550 GB of memory, to keep things in perspective.
+, -, *, /, (, ), and space are the only valid non-numeric characters in memory expressions.
f=argon2i,s=16,k=32,m=64*1024,t=3,p=2
f=argon2i,s=16,k=32,m=((64*1024) + (20-10))/2,t=3,p=2
Both are valid for use with NewHasherFromString. Expressions remove the need to pre-calculate kibibyte values.
License
Copyright © 2020 W Anders
Licensed under MIT License
Documentation
¶
Overview ¶
Package argon2 provides a simplified interface for the argon2 key derivation function using https://golang.org/x/crypto/argon2.
Configuration is handled by creating a Hasher structure with all attributes populated, or by passing a comma-delimited key-value string to the NewHasherFromString function. The Hasher structure possesses the functions to create and verify password hashes.
argon2i and argon2id are the only supported variants.
func WithString() {
settings := "f=argon2id,s=16,k=32,m=65536,t=3,p=2"
hasher, _ := argon2.NewHasherFromString(settings)
hashPass, _ := hasher.Create("mySecretPassword")
if ok, _ := hasher.Matches("mySecretPassword", hashPass); ok {
fmt.Println("Pasword matches!")
} else {
fmt.Println("Password does not match!")
}
}
func WithStruct() {
hasher := &argon2.Hasher{
Form: argon2.FormI,
SaltLength: 16,
KeyLength: 32
Memory: 65536,
Iterations: 3,
Parallelism: 2,
}
hashPass, _ := hasher.Create("mySecretPassword")
if ok, _ := hasher.Matches("mySecretPassword", hashPass); ok {
fmt.Println("Pasword matches!")
} else {
fmt.Println("Password does not match!")
}
}
When using a string to initialize the Hasher, a mathematical expression can be used to configure memory settings (ie `64*1024`) so kibibyte values do not need to be calculated beforehand.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ErrIncompatibleVersion ¶
type ErrIncompatibleVersion struct {
// contains filtered or unexported fields
}
ErrIncompatibleVersion is returned if a different version of argon2 is used in the hash
func (ErrIncompatibleVersion) Error ¶
func (e ErrIncompatibleVersion) Error() string
type ErrInvalidForm ¶
type ErrInvalidForm struct{}
ErrInvalidForm is returned if the argon2 type is unrecognized
func (ErrInvalidForm) Error ¶
func (e ErrInvalidForm) Error() string
type ErrInvalidHash ¶
type ErrInvalidHash struct{}
ErrInvalidHash is returned if the provided hash is not in the correct format.
func (ErrInvalidHash) Error ¶
func (e ErrInvalidHash) Error() string
type ErrInvalidHasherConfiguration ¶
type ErrInvalidHasherConfiguration struct{}
ErrInvalidHasherConfiguration returns if the hasher configuration contains invalid parameters
func (ErrInvalidHasherConfiguration) Error ¶
func (e ErrInvalidHasherConfiguration) Error() string
type ErrUnknownSetting ¶
type ErrUnknownSetting struct {
// contains filtered or unexported fields
}
ErrUnknownSetting returns if a setting string contains a key that is unknown
func (ErrUnknownSetting) Error ¶
func (e ErrUnknownSetting) Error() string
type ErrUnsupportedExpr ¶
type ErrUnsupportedExpr struct {
// contains filtered or unexported fields
}
ErrUnsupportedExpr returns if part of an evaluated string expression contains non-integers or unsupported modifiers.
func (ErrUnsupportedExpr) Error ¶
func (e ErrUnsupportedExpr) Error() string
type Hasher ¶
type Hasher struct {
// `argon2.FormI` or `argon2.FormID`
Form Form
// (s) Byte length of hash salt
SaltLength uint32
// (k) Byte length of hash key
KeyLength uint32
// (m) Amount of memory (in kibibytes) to use
Memory uint32
// (t) Number of iterations to perform
Iterations uint32
// (p) Degree of parallelism; number of threads
Parallelism uint8
}
Hasher contains the parameters used by the argon2
func NewHasherFromString ¶
NewHasherFromString parses a comma-delimited key-value string into a Hasher structure used to configure argon2. All fields must be present to configure argon2 as there are no default values.
Configuration string format:
"f": Form (string) : "argon2i" or "argon2id"
"s": Salt Length (int) : Byte length of hash salt
"k": Key Length (int) : Byte length of hash key
"m": Memory (int OR expression) : Memory is evaluated, so mathematical expressions can be used.
"t": Time/Iterations (int) : Number of passes over memory
"p": Parallelism (int) : Number of threads
Errors:
*ErrInvalidForm *ErrUnknownSetting scanner.ErrorList *strconv.NumError (int in expression larger than 32-bit)
Example ¶
hasherConfig := "f=argon2i,s=16,k=32,m=65536,t=3,p=2"
hasher, _ := NewHasherFromString(hasherConfig)
hash, _ := hasher.Create("mySecretPassword")
fmt.Println(hash)
// $argon2i$v=19$m=65536,t=3,p=2$oOT8PmX+YLmj8wRveAP0Cg$uIP1h5Z1DOSx9YBBSWOHE84AYGxC9/GwnB3ZFGZFh8E
Output:
Example (MemoryExpression) ¶
// Mathematical expressions for memory are parsed _ = "f=argon2i,s=16,k=32,m=64*1024,t=3,p=2" // +, -, *, /, (, ), and space (` `) // are the only valid non-numeric symbols. _ = "f=argon2i,s=16,k=32,m=((64*1024) + (20-10))/2,t=3,p=2"
Output:
Source Files