unchained

package module
Version: v0.0.0-...-57de6aa Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2019 License: BSD-3-Clause Imports: 8 Imported by: 0

README

Unchained

Build Status GoDoc Go Report Card

Django Password Hashers library in Go to perform user validation against legacy databases. You can also use it as a standard password hasher for newer Go applications.

Unchained works with Go 1.9 and higher.

Install

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

Documentation

Overview

Package unchained provides Django password hashers in Go.

These hashers can be used to perform validation against legacy databases. It can also be used as a standard for newer applications.

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

The default password used in Django is a string in this format:

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

Currently this library supports Argon2, BCrypt, and PBKDF2 algorithms.

Index

Examples

Constants

View Source
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.

View Source
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

View Source
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 validate 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/dimiro1/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)
		}
	}
}
Output:

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/dimiro1/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)
	}
}
Output:

Types

This section is empty.

Directories

Path Synopsis
Package argon2 implements a Django compatible Argon2 algorithm.
Package argon2 implements a Django compatible Argon2 algorithm.
Package bcrypt implements a Django compatible bcrypt algorithm.
Package bcrypt implements a Django compatible bcrypt algorithm.
Package md5 implements a Django compatible MD5 algorithm.
Package md5 implements a Django compatible MD5 algorithm.
Package pbkdf2 implements a Django compatible PBKDF2 algorithm.
Package pbkdf2 implements a Django compatible PBKDF2 algorithm.
Package sha1 implements a Django compatible SHA1 algorithm.
Package sha1 implements a Django compatible SHA1 algorithm.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL