scryptauth

README

scryptauth

scryptauth is a GO library for secure password handling using scrypt

It uses sha256_hmac(scrypt(user_password, salt), server_key) to protect against both dictionary attacks and DB leaks.

scryptauth additionally provides encode/decode routines using base64 to create strings for storing into a DB.

Usage

Choose your scrypt pw_cost factor (make bench helps you on this). Typical values used in production are between 11 and 14 which means a login will take at least 15 to 130ms, and your service will be able to handle only 66 and 8 logins per second with 100% load on a single CPU (keep that in mind!).

Documentation

http://godoc.org/github.com/gebi/scryptauth

Author

Michael Gebetsroither (michael \x40 mgeb \x2e org)

License

BSD 2 clause

Documentation

Overview

scryptauth is a GO library for secure password handling using scrypt

It uses sha256_hmac(scrypt(user_password, salt), server_key) to protect against both dictionary attacks and DB leaks.

scryptauth additionally provides encode/decode routines using base64 to create strings for storing into a DB.

Copyright: Michael Gebetsroither 2012 (michael \x40 mgeb \x2e org)

License: BSD 2 clause

Index

• Constants
• func DecodeBase64(str string) (ctxID uint, hash, salt []byte, err error)
• func EncodeBase64(ctxID uint, hash, salt []byte) (str string)
• type Context
  • func New(pwCost uint, hmacKey []byte) (*Context, error)
  • func (c *Context) Check(hash, password, salt []byte) (chk bool, err error)
  • func (c *Context) Gen(password []byte) (hash, salt []byte, err error)
  • func (c *Context) Hash(password, salt []byte) (hash []byte, err error)

Examples

• DecodeBase64
• EncodeBase64

Constants

const (
	// Key length and salt length are 32 bytes (256 bits)
	KeyLength = 32

	// scrypt default parameters as used by New()
	DefaultR = 8
	DefaultP = 1
)

Functions

func DecodeBase64

func DecodeBase64(str string) (ctxID uint, hash, salt []byte, err error)

DecodeBase64 parses "ctxID:base64(hash):base64(salt)"

Example

Sample function to verify stored hash from DB

db_string := "17:3Tnrsg5-QaM7OsyRvqcBv9qS-jqGxzRIXQqvbTUf894=:HrHzQ4S016BffZ2TmwLRYYiIggfSmkwKdEtd1Pk_b-I="
contexts := make(map[uint]*Context)
ctx, err := New(12, []byte("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA")) // PLEASE CHANGE THIS KEY FOR PRODUCTION USE
if err != nil {
	fmt.Print(err)
	return
}
contexts[17] = ctx
user_password := []byte("bar")

ctxID, hash, salt, err := DecodeBase64(db_string)
if err != nil {
	fmt.Print(err)
	return
}

ok, err := contexts[ctxID].Check(hash, user_password, salt)
if !ok {
	fmt.Printf("Error wrong password for user (%s)", err)
	return
}
fmt.Print("ok")

Output:

ok

func EncodeBase64

func EncodeBase64(ctxID uint, hash, salt []byte) (str string)

EncodeBase64 encodes into "ctxID:base64(hash):base64(salt)"

Example

Sample Function to generate new password hash for storing in DB

hmac_key := []byte("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA") // PLEASE CHANGE THIS KEY FOR PRODUCTION USE
pw_cost := uint(12)
ctxID := uint(17)
user_password := []byte("test123")

ctx, err := New(pw_cost, hmac_key)
if err != nil {
	fmt.Print(err)
	return
}
hash, salt, err := ctx.Gen(user_password)
if err != nil {
	fmt.Print(err)
	return
}
str := EncodeBase64(ctxID, hash, salt)
fmt.Print(str)

Types

type Context

type Context struct {
	HmacKey []byte // HMAC key used to secure scrypt hash
	PwCost  uint   // PwCost parameter used to calculate N parameter of scrypt (1<<PwCost == N)
	R       int    // r parameter of scrypt
	P       int    // p parameter of scrypt
}

func New

func New(pwCost uint, hmacKey []byte) (*Context, error)

New creates a new Context struct. This is a convenience function to produce a context. You might as well produce the Context struct yourself.

func (*Context) Check

func (c *Context) Check(hash, password, salt []byte) (chk bool, err error)

Check verifies password against hash/salt

func (*Context) Gen

func (c *Context) Gen(password []byte) (hash, salt []byte, err error)

Gen generates hash for password using a new salt from crypto.rand

func (*Context) Hash

func (c *Context) Hash(password, salt []byte) (hash []byte, err error)

Hash produces the hash using password and salt. This is used by Gen() and Check() to generate/check password hashes.