unchained

README

Unchained

Secure password hashers for Go compatible with Django Password Hashers.

Unchained can also be used to perform password validation against legacy or shared Django databases.

Install

Requires Go 1.9 or higher.

go get github.com/alexandrevicenzi/unchained

Supported Hashers

Hasher	Encode	Decode	Dependencies
Argon2	✔	✔	golang.org/x/crypto/argon2
BCrypt	✔	✔	golang.org/x/crypto/bcrypt
BCrypt SHA256	✔	✔	golang.org/x/crypto/bcrypt
Crypt	✘	✘
MD5	✔	✔
PBKDF2 SHA1	✔	✔	golang.org/x/crypto/pbkdf2
PBKDF2 SHA256	✔	✔	golang.org/x/crypto/pbkdf2
SHA1	✔	✔
Unsalted MD5	✔	✔
Unsalted SHA1	✔	✔

Notes

Crypt support is not planned because it's UNIX only.

BCrypt hasher does not allow to set custom salt as in Django. If you encode the same password multiple times you will get different hashes. This limitation comes from golang.org/x/crypto/bcrypt library.

Examples

Encode password

package main

import "github.com/alexandrevicenzi/unchained"

func main() {
    hash, err := unchained.MakePassword("my-password", unchained.GetRandomString(12), "default")

    if err == nil {
        fmt.Println(hash)
    } else {
        fmt.Printf("Error encoding password: %s\n", err)
    }
}

Validate password

package main

import "github.com/alexandrevicenzi/unchained"

func main() {
    valid, err := unchained.CheckPassword("admin", "pbkdf2_sha256$24000$JMO9TJawIXB1$5iz40fwwc+QW6lZY+TuNciua3YVMV3GXdgkhXrcvWag=")

    if valid {
        fmt.Println("Password is valid.")
    } else {
        if err == nil {
            fmt.Println("Password is invalid.")
        } else {
            fmt.Printf("Error decoding password: %s\n", err)
        }
    }
}

License

BSD

Reference

• Password management in Django
• Django Unchained :trollface:

Related Links

• Django compatible signing for Go (django.core.signing)

Documentation

Overview

Package unchained provides password hashers that are compatible with Django.

These hashers can be also used to perform validation against legacy and shared Django databases.

Django provides a flexible password storage system and uses PBKDF2 by default.

The password format/representation is the same as the one used in Django:

<algorithm>$<iterations>$<salt>$<hash>

This library supports Argon2, BCrypt, PBKDF2, MD5 and SHA1 algorithms.

Index

• Constants
• Variables
• func CheckPassword(password, encoded string) (bool, error)
• func GetRandomString(length int) string
• func IdentifyHasher(encoded string) string
• func IsHasherImplemented(hasher string) bool
• func IsPasswordUsable(encoded string) bool
• func IsValidHasher(hasher string) bool
• func IsWeakHasher(hasher string) bool
• func MakePassword(password, salt, hasher string) (string, error)

Examples

• CheckPassword
• MakePassword

Constants

const (
	Argon2Hasher       = "argon2"
	BCryptHasher       = "bcrypt"
	BCryptSHA256Hasher = "bcrypt_sha256"
	CryptHasher        = "crypt"
	MD5Hasher          = "md5"
	PBKDF2SHA1Hasher   = "pbkdf2_sha1"
	PBKDF2SHA256Hasher = "pbkdf2_sha256"
	SHA1Hasher         = "sha1"
	UnsaltedMD5Hasher  = "unsalted_md5"
	UnsaltedSHA1Hasher = "unsalted_sha1"
)

Django hasher identifiers.

const (
	// The prefix used in unusable passwords.
	UnusablePasswordPrefix = "!"
	// The length of unusable passwords after the prefix.
	UnusablePasswordSuffixLength = 40
	// The default hasher used in Django.
	DefaultHasher = PBKDF2SHA256Hasher
	// The default salt size used in Django.
	DefaultSaltSize = 12
)

Variables

var (
	// ErrInvalidHasher is returned if the hasher is invalid or unknown.
	ErrInvalidHasher = errors.New("unchained: invalid hasher")
	// ErrHasherNotImplemented is returned if the hasher is not implemented.
	ErrHasherNotImplemented = errors.New("unchained: hasher not implemented")
)

Functions

func CheckPassword

func CheckPassword(password, encoded string) (bool, error)

CheckPassword validates if the raw password matches the encoded digest.

This is a shortcut that discovers the hasher used in the encoded digest to perform the correct validation.

Example

package main

import (
	"fmt"

	"github.com/alexandrevicenzi/unchained"
)

func main() {
	valid, err := unchained.CheckPassword("admin", "pbkdf2_sha256$24000$JMO9TJawIXB1$5iz40fwwc+QW6lZY+TuNciua3YVMV3GXdgkhXrcvWag=")

	if valid {
		fmt.Println("Password is valid.")
	} else {
		if err == nil {
			fmt.Println("Password is valid.")
		} else {
			fmt.Printf("Error decoding password: %s\n", err)
		}
	}
}

func GetRandomString

func GetRandomString(length int) string

GetRandomString returns a securely generated random string.

func IdentifyHasher

func IdentifyHasher(encoded string) string

IdentifyHasher returns the hasher used in the encoded password.

func IsHasherImplemented

func IsHasherImplemented(hasher string) bool

IsHasherImplemented returns true if the hasher is implemented in this library, or false otherwise.

func IsPasswordUsable

func IsPasswordUsable(encoded string) bool

IsPasswordUsable returns true if encoded password is usable, or false otherwise.

func IsValidHasher

func IsValidHasher(hasher string) bool

IsValidHasher returns true if the hasher is supported by Django, or false otherwise.

func IsWeakHasher

func IsWeakHasher(hasher string) bool

IsWeakHasher returns true if the hasher is not recommend by Django, or false otherwise.

func MakePassword

func MakePassword(password, salt, hasher string) (string, error)

MakePassword turns a plain-text password into a hash.

If password is empty then return a concatenation of UnusablePasswordPrefix and a random string. If salt is empty then a randon string is generated. BCrypt algorithm ignores salt parameter. If hasher is "default", encode using default hasher.

Example

package main

import (
	"fmt"

	"github.com/alexandrevicenzi/unchained"
)

func main() {
	hash, err := unchained.MakePassword("my-password", unchained.GetRandomString(12), "default")

	if err == nil {
		fmt.Println(hash)
	} else {
		fmt.Printf("Error encoding password: %s\n", err)
	}
}