README
¶
simple-argon2
simple-argon2 provides a convenience wrapper around Go's existing argon2 (formaly argon2id) package that makes it easier to securely derive strong keys ("hash user passwords").
Based on article How to Hash and Verify Passwords With Argon2 in Go and strongly inspired of github.com/elithrar/simple-scrypt package (source code, comments & readme).
The API closely mirrors Go's bcrypt library in an effort to make it easy to migrate—and because it's an easy to grok API.
Usage
go get github.com/mdouchement/simple-argon2
package main
import (
"fmt"
"log"
argon2 "github.com/mdouchement/simple-argon2"
)
func main() {
hashed, err := argon2.GenerateFromPasswordString("42password42", argon2.Default)
if err != nil {
log.Fatal(err)
}
fmt.Println(hashed)
// $argon2id$v=19$m=65536,t=3,p=2$/lASHr1GVXVkV/628wFUVGqINrLbWo7v86TjaooJmUY$igyAvrODju4SsBSefcYOzMaLl9xGjSkjsY1tnaKaTxk
err = argon2.CompareHashAndPasswordString(hashed, "42password42")
if err != nil {
// Invalid password
log.Fatal(err)
}
// Valid password
}
License
MIT
Contributing
All PRs are welcome.
- Fork it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request
As possible, run the following commands to format and lint the code:
# Format
find . -name '*.go' -exec gofmt -s -w {} \;
# Lint
golangci-lint run -c .golangci.yml
Documentation
¶
Overview ¶
Package argon2 provides a convenience wrapper around Go's existing argon2 package that makes it easier to securely derive strong keys from weak inputs (i.e. user passwords). The package provides password generation and comparison for argon2 derived keys.
Index ¶
- Constants
- Variables
- func CompareHashAndPassword(hashedPassword, password []byte) error
- func CompareHashAndPasswordString(hashedPassword, password string) error
- func GenerateFromPassword(password []byte, p Params) ([]byte, error)
- func GenerateFromPasswordString(password string, p Params) (string, error)
- func GenerateRandomBytes(n uint32) ([]byte, error)
- type Params
Constants ¶
const ( // MinIterations is the minimum iterations (or passes) over the memory. MinIterations = 1 // MinParallelism is the minimum of threads (or lanes) used by the algorithm. MinParallelism = 1 // MinSaltLength is the minimum length of the random salt. MinSaltLength = 16 // MinKeyLength is the minimum length of the generated key (or password hash). MinKeyLength = 16 )
Variables ¶
var ( // Default provides sensible default inputs into the argon2 function. Default = Params{ Memory: 64 * 1024, Iterations: 3, Parallelism: 2, SaltLength: 16, KeyLength: 32, } // ErrInvalidHash is returned when failing to parse a provided argon2 // hash and/or parameters. ErrInvalidHash = errors.New("argon2: the encoded hash is not in the correct format") // ErrIncompatibleVersion is returned when the provided hashed password is incompatible with this lib. ErrIncompatibleVersion = errors.New("argon2: incompatible version") // ErrMismatchedHashAndPassword is returned when a password (hashed) and // given hash do not match. ErrMismatchedHashAndPassword = errors.New("argon2: the hashed password does not match the hash of the given password") )
Functions ¶
func CompareHashAndPassword ¶
CompareHashAndPassword compares a derived key with the possible cleartext equivalent. The parameters used in the provided derived key are used. It returns nil on success, and an error if the derived keys do not match.
func CompareHashAndPasswordString ¶
CompareHashAndPasswordString compares a derived key with the possible cleartext equivalent. The parameters used in the provided derived key are used. It returns nil on success, and an error if the derived keys do not match.
func GenerateFromPassword ¶
GenerateFromPassword returns the derived key of the password using the parameters provided. The parameters are prepended to the derived key and separated by the "$" character (0x24). If the parameters provided are less than the minimum acceptable values, the values are setted to the default.
func GenerateFromPasswordString ¶
GenerateFromPasswordString returns the derived key of the password using the parameters provided. The parameters are prepended to the derived key and separated by the "$" character (0x24). If the parameters provided are less than the minimum acceptable values, the values are setted to the default.
func GenerateRandomBytes ¶
GenerateRandomBytes returns securely generated random bytes. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller should not continue.
Types ¶
type Params ¶
type Params struct {
// Memory is the amount of memory used by the algorithm (in kibibytes).
Memory uint32
// Iterations is the number of iterations (or passes) over the memory.
Iterations uint32
// Parallelism is the number of threads (or lanes) used by the algorithm.
Parallelism uint8
// SaltLength is the length of the random salt
SaltLength uint32
// KeyLength is the length of the generated key (or password hash).
KeyLength uint32
}
Params describes the input parameters to the argon2 key derivation function. https://tools.ietf.org/html/draft-irtf-cfrg-argon2-04 https://github.com/P-H-C/phc-winner-argon2
Source Files