README
¶
argon2
Easy to use Argon2 password hashing for Go.
Provides an interface around golang.org/x/crypto/argon2 similar to the interface of the golang.org/x/crypto/bcrypt package.
Examples
Create Password Hash
package main
import (
"fmt"
"log"
"github.com/judwhite/argon2"
)
func main() {
// user input
password := []byte("some password")
str, err := argon2.GenerateFromPassword(password, argon2.Options{})
if err != nil {
log.Fatal(err)
}
fmt.Println(str) // store this output in a database
}
Validate Password Hash
package main
import (
"fmt"
"log"
"github.com/judwhite/argon2"
)
func main() {
// retrieved from a database
const hash = "$argon2id$v=19$m=98304,t=5,p=2$AAECAwQFBgcICQoLDA0ODw$Ezmo1ZvImYjNdSrjbN33VEd5aUBeSmP3YZAojYw467I"
// user input
password := []byte("some password")
// validate passwords match
if err := argon2.CompareHashAndPassword(hash, password); err != nil {
log.Fatal(err)
}
fmt.Println("passwords match")
}
Similar Projects
- https://godoc.org/golang.org/x/crypto/argon2
- https://github.com/p-h-c/phc-winner-argon2
- https://github.com/alexedwards/argon2id
License
argon2 is under the MIT license. See the LICENSE file for details.
Documentation
¶
Overview ¶
Package argon2 provides an interface around golang.org/x/crypto/argon2 similar to the interface of the bcrypt package.
This package is intended for password hashing, particularly for user databases. GenerateFromPassword returns a formatted string suitable for database storage. This value can be used by CompareHashAndPassword to check if a plaintext password matches the hash.
For more information about Argon2 visit https://github.com/p-h-c/phc-winner-argon2 and https://godoc.org/golang.org/x/crypto/argon2.
Index ¶
- func CompareHashAndPassword(hashedPassword string, password []byte) error
- func GenerateFromPassword(password []byte, opts Options) (string, error)
- func GenerateHashBytes(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) ([]byte, error)
- func IsPasswordMismatch(err error) bool
- type HashParameters
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompareHashAndPassword ¶
CompareHashAndPassword compares an Argon2 hashed password, as returned from GenerateFromPassword, with a plaintext password. Returns nil if the passwords match, otherwise returns an error.
func GenerateFromPassword ¶
GenerateFromPassword returns the Argon2 hashed password using the provided options. The options are similar to how Cost works in bcrypt and allow you to tune the memory and CPU usage for your environment. If you pass an empty Options struct defaults will be chosen, though you should test these parameters under your expected load. It's safe to reuse a single Options instance from multiple goroutines, provided it's not modified while calling the function.
Use CompareHashAndPassword to compare the returned hashed password with its plaintext version.
A 16-byte salt is created using crypto/rand. The salt is not provided as a parameter or in the options to discourage reusing salt values. The output of the hash, also referred to as the key length, is set to the recommended 32 bytes.
The hash is returned formatted, as in the reference implementation: "$argon2id$v=19$m=<num>,t=<num>,p=<num>$<salt-base64>$<hash-base64>".
func GenerateHashBytes ¶
func GenerateHashBytes(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) ([]byte, error)
GenerateHashBytes calls the underlying Argon2id implementation in crypto/argon2. It returns only the hash without option information or formatting.
func IsPasswordMismatch ¶
IsPasswordMismatch reports whether an error returned by CompareHashAndPassword is the result of a password mismatch, opposed to another type of error such as an invalid format.
Types ¶
type HashParameters ¶
type HashParameters struct {
// Function is the name of the hash function used, such as "argon2id".
Function string
// Version is the version of Argon2 used to create the hash.
Version int
// Time is the number of iterations, affecting the time cost.
Time uint32
// Memory is the size of the memory used in KiB, affecting the memory cost.
Memory uint32
// Threads is the number of threads, affecting the degree of parallelism.
Threads uint8
// SaltLen is the length of the salt value.
SaltLen uint32
// KeyLen is the length of the output hash value.
KeyLen uint32
}
HashParameters contains parameters used to create an Argon2 hash. It's returned by the Parameters function.
func Parameters ¶
func Parameters(hashedPassword string) (HashParameters, error)
Parameters returns the hashing parameters used to create the given hashed password. When, in the future, the hashing cost of a password system needs to be changed in order to adjust for greater computational power, this function allows one to establish which passwords need to be updated.
type Options ¶
type Options struct {
// Time is the number of iterations, affecting the time cost.
// If unset, the default value is 5.
Time uint32
// Memory is the size of the memory used in KiB, affecting the memory cost.
// If unset, the default value is 65536 (64 MiB).
Memory uint32
// Threads is the number of threads, affecting the degree of parallelism.
// If unset the default value is 2.
Threads uint8
}
Options for affecting the computational cost.
Source Files