unchained

package module
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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.