bcrypt

README

*This package uses cgo. Use golang.org/x/crypto/bcrypt instead now.*

Quick Start
===========

Example use::

  package main

  import (
        "fmt"
        "github.com/absagar/bcrypt"
  )

  var password     = "WyWihatdyd?frub1"
  var bad_password = "just a wild guess"

  func main() {
        // generate a random salt with default rounds of complexity
        salt, _ := bcrypt.Salt()

        // generate a random salt with 10 rounds of complexity
        salt, _ = bcrypt.Salt(10)

        // hash and verify a password with random salt
        hash, _ := bcrypt.Hash(password)
        if bcrypt.Match(password, hash) {
                fmt.Println("They match")
        }

        // hash and verify a password with a static salt
        hash, _ = bcrypt.Hash(password, salt)
        if bcrypt.Match(password, hash) {
                fmt.Println("They match")
        }

        // verify a random password fails to match the hashed password
        if !bcrypt.Match(bad_password, hash) {
                fmt.Println("They don't match")
        }
  }

Documentation

Overview

Package bcrypt implements Blowfish password hashing.

bcrypt is an implementation of the OpenBSD Blowfish password hashing algorithm, as described in "A Future-Adaptable Password Scheme" by Niels Provos and David Mazieres.

This system hashes passwords using a version of Bruce Schneier's Blowfish block cipher with modifications designed to raise the cost of off-line password cracking. The computation cost of the algorithm is parametised, so it can be increased as computers get faster.

// generate a reasonable hash
var password = "WyWihatdyd?frub1"
hash, _ := Hash(password)

// generate a vary expensive hash
salt, _ := Salt(MaxRounds)
hash, _ = Hash(password, salt)

if Match(password, hash)) {
    // they match!
}

Index

• Constants
• Variables
• func Hash(password string, salt ...string) (hash string, err error)
• func HashBytes(password []byte, salt ...[]byte) (hash []byte, err error)
• func Match(password, hash string) bool
• func MatchBytes(password, hash []byte) bool
• func Salt(rounds ...int) (salt string, err error)
• func SaltBytes(rounds int) (salt []byte, err error)

Constants

const (
	DefaultRounds = 12
	MaxRounds     = 31
	MinRounds     = 4
	RandomSaltLen = 16
	SaltBufferLen = 64
)

Variables

var (
	InvalidRounds = errors.New("invalid rounds")
	InvalidSalt   = errors.New("invalid salt")
)

Functions

func Hash

func Hash(password string, salt ...string) (hash string, err error)

Hash generates an encrypted hash of the unencrypted password and the random salt using the OpenBSD Blowfish password hashing algorithm. If the "salt" parameter is omitted, a random salt will be generated with a workload complexity of DefaultRounds.

Returns the Blowfish encrypted password.

func HashBytes

func HashBytes(password []byte, salt ...[]byte) (hash []byte, err error)

HashBytes provides a []byte based wrapper to Hash.

func Match

func Match(password, hash string) bool

Match determines if an unencrypted password matches a previously encrypted password. It does so by generating a Blowfish encrypted hash of the unencrypted password and the random salt from the previously encrypted password.

Returns 'true' when the encrypted passwords match, otherwise 'false'.

func MatchBytes

func MatchBytes(password, hash []byte) bool

MatchBytes provides a []byte based wrapper to Match.

func Salt

func Salt(rounds ...int) (salt string, err error)

Salt generates a random salt for use with Hash(). The "rounds" parameter defines the complexity of the hashing, increasing the cost as 2**rounds.

Returns a random salt.

func SaltBytes

func SaltBytes(rounds int) (salt []byte, err error)

SaltBytes provides a []byte based wrapper to Salt.