pwhash

README

Opinionated password hashing library

This library implements password hashing functions for Go web applications. It is intentionally not configurable to avoid security mistakes.

Using it is very simple. There are only two methods: Hash and Verify:

// When storing a password in the database:
password := "correct horse battery staple"
hash := pwhash.Hash(password)

// When checking a password for validity:
if !pwhash.Verify(password, hash) {
	// Oh no, the user entered the wrong password!
	showLoginPage()
	return
}
// User is logged in. Set up a session etc.

In the current configuration, it hashes passwords using argon2id, with 64MB memory, a time parameter of 1, and uses 4 threads. Passwords hashed this way should take under 50ms to verify on most systems.

Some other password formats are supported for backwards compatibility. This includes the PBKDF2-SHA256 hash in the Python hashlib and the Django format. More formats can be added if the need arises. Remember that this is only for legacy purposes, newly stored passwords will be in the argon2 format and thus better protected against cracking.

License

This library has been put into the public domain. For details, see LICENSE.txt or unlicense.org.

Documentation

Overview

Package pwhash is a simple to use password hashing library. The defaults are set to be good for most purposes and it is backwards compatible with older password hashing schemes.

Index

• func Hash(password string) string
• func Verify(password, hash string) bool

Examples

• Hash

Functions

func Hash

func Hash(password string) string

Hash returns a hashed version of the given password. Use this when the user enters a new password and store it as an opaque string in a database.

You don't need to salt or do this operation multiple times, this is all handled for you.

Example

hash := Hash("correct horse battery staple")
fmt.Println("hash:", hash)

fmt.Println("verify:", Verify("correct horse battery staple", hash))
fmt.Println("verify:", Verify("Tr0ub4dor&3", hash))

func Verify

func Verify(password, hash string) bool

Verify check whether a given password matches the hash. Use it for example this way:

hash := loadUser(username).hash
if !pwhash.Verify(password, hash) {
    // login unsuccessful
    return ...
}
// continue with logged in user

This function accepts multiple hash formats for backwards compatibility.