sha512

README

sha512

A password hashing library.

The goal of sha512 is to isolate a flapping dependency and focus it on the only functionality we needed.

The test suite was copied directly over from the origin, and only the package structure has been changed to flatten it.

Note: forked from https://github.com/tredoe/osutil

Installation

go get github.com/metrumresearchgroup/sha512

License

The source files are distributed under a BSD-style license that can be found in the LICENSE file.

Documentation

Overview

Package sha512_crypt implements Ulrich Drepper's SHA512-crypt password hashing algorithm.

The specification for this algorithm can be found here: http://www.akkadia.org/drepper/SHA-crypt.txt

Index

• Constants
• Variables
• func Base64_24Bit(src []byte) []byte
• type Crypter
  • func New() Crypter
• type SHA512
  • func (c *SHA512) Cost(hashedKey string) (int, error)
  • func (c *SHA512) Generate(key, salt []byte) (string, error)
  • func (c *SHA512) SetSalt(salt Salt)
  • func (c *SHA512) Verify(hashedKey string, key []byte) error
• type Salt
  • func GetSalt() Salt
  • func (s *Salt) GenerateWRounds(length, rounds int) ([]byte, error)

Constants

const (
	MagicPrefix   = "$6$"
	SaltLenMin    = 1
	SaltLenMax    = 16
	RoundsMin     = 1000
	RoundsMax     = 999999999
	RoundsDefault = 5000
)

Variables

var (
	ErrSaltPrefix = errors.New("invalid magic prefix")
	ErrSaltFormat = errors.New("invalid salt format")
	ErrSaltRounds = errors.New("invalid rounds")
)

var ErrKeyMismatch = errors.New("hashed value is not the hash of the given password")

Functions

func Base64_24Bit

func Base64_24Bit(src []byte) []byte

Base64_24Bit is a variant of Base64 encoding, commonly used with password hashing algorithms to encode the result of their checksum output.

The algorithm operates on up to 3 bytes at a time, encoding the following 6-bit sequences into up to 4 hash64 ASCII bytes.

1. Bottom 6 bits of the first byte
2. Top 2 bits of the first byte, and bottom 4 bits of the second byte.
3. Top 4 bits of the second byte, and bottom 2 bits of the third byte.
4. Top 6 bits of the third byte.

This encoding method does not emit padding bytes as Base64 does.

Types

type Crypter

type Crypter interface {
	// Generate performs the hashing algorithm, returning a full hash suitable
	// for storage and later password verification.
	//
	// If the salt is empty, a randomly-generated salt will be generated with a
	// length of SaltLenMax and number RoundsDefault of rounds.
	//
	// Any error only can be got when the salt argument is not empty.
	Generate(key, salt []byte) (string, error)

	// Verify compares a hashed key with its possible key equivalent.
	// Returns nil on success, or an error on failure; if the hashed key is
	// diffrent, the error is "ErrKeyMismatch".
	Verify(hashedKey string, key []byte) error

	// Cost returns the hashing cost (in rounds) used to create the given hashed
	// key.
	//
	// When, in the future, the hashing cost of a key needs to be increased in
	// order to adjust for greater computational power, this function allows one
	// to establish which keys need to be updated.
	//
	// The algorithms based in MD5-crypt use a fixed value of rounds.
	Cost(hashedKey string) (int, error)

	// SetSalt sets a different salt. It is used to easily create derivated
	// algorithms, i.e. "apr1_crypt" from "md5_crypt".
	SetSalt(salt Salt)
}

Crypter is the common interface implemented by all crypt functions.

func New

func New() Crypter

New returns a new crypt.Crypter computing the SHA512-crypt password hashing.

type SHA512

type SHA512 struct{ Salt Salt }

func (*SHA512) Cost

func (c *SHA512) Cost(hashedKey string) (int, error)

func (*SHA512) Generate

func (c *SHA512) Generate(key, salt []byte) (string, error)

func (*SHA512) SetSalt

func (c *SHA512) SetSalt(salt Salt)

func (*SHA512) Verify

func (c *SHA512) Verify(hashedKey string, key []byte) error

type Salt

type Salt struct {
	MagicPrefix []byte

	SaltLenMin int
	SaltLenMax int

	RoundsMin     int
	RoundsMax     int
	RoundsDefault int
}

Salt represents a salt.

func GetSalt

func GetSalt() Salt

func (*Salt) GenerateWRounds

func (s *Salt) GenerateWRounds(length, rounds int) ([]byte, error)

GenerateWRounds creates a random salt with the random bytes being of the length provided, and the rounds parameter set as specified.

The parameters are set thus:

length > SaltLenMax: length = SaltLenMax
length < SaltLenMin: length = SaltLenMin

rounds < 0: rounds = RoundsDefault
rounds < RoundsMin: rounds = RoundsMin
rounds > RoundsMax: rounds = RoundsMax

If rounds is equal to RoundsDefault, then the "rounds=" part of the salt is removed.