crypt

README

.. image:: https://travis-ci.org/GehirnInc/crypt.svg?branch=master
    :target: https://travis-ci.org/GehirnInc/crypt

crypt - A password hashing library for Go
=========================================
crypt provides pure golang implementations of UNIX's crypt(3).

The goal of crypt is to bring a library of many common and popular password
hashing algorithms to Go and to provide a simple and consistent interface to
each of them. As every hashing method is implemented in pure Go, this library
should be as portable as Go itself.

All hashing methods come with a test suite which verifies their operation
against itself as well as the output of other password hashing implementations
to ensure compatibility with them.

I hope you find this library to be useful and easy to use!

Install
-------

To install crypt, use the *go get* command.

.. code-block:: sh

   go get github.com/GehirnInc/crypt


Usage
-----

.. code-block:: go

    package main

    import (
    	"fmt"

    	"github.com/GehirnInc/crypt"
    	_ "github.com/GehirnInc/crypt/sha256_crypt"
    )

    func main() {
    	crypt := crypt.SHA256.New()
    	ret, _ := crypt.Generate([]byte("secret"), []byte("$5$salt"))
    	fmt.Println(ret)

    	err := crypt.Verify(ret, []byte("secret"))
    	fmt.Println(err)

    	// Output:
    	// $5$salt$kpa26zwgX83BPSR8d7w93OIXbFt/d3UOTZaAu5vsTM6
    	// <nil>
    }

Documentation
-------------

The documentation is available on GoDoc_.

.. _GoDoc: https://godoc.org/github.com/GehirnInc/crypt

Documentation

Overview

Package crypt provides interface for password crypt functions and collects common constants.

Index

• Variables
• func IsHashSupported(hashedKey string) bool
• func RegisterCrypt(c Crypt, f func() Crypter, prefix string)
• type Crypt
  • func (c Crypt) Available() bool
  • func (c Crypt) New() Crypter
• type Crypter
  • func New(c Crypt) Crypter
  • func NewFromHash(hashedKey string) Crypter

Variables

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

Functions

func IsHashSupported

func IsHashSupported(hashedKey string) bool

IsHashSupported returns true if hashedKey has a supported prefix. NewFromHash will not panic for this hashedKey

func RegisterCrypt

func RegisterCrypt(c Crypt, f func() Crypter, prefix string)

RegisterCrypt registers a function that returns a new instance of the given crypt function. This is intended to be called from the init function in packages that implement crypt functions.

Types

type Crypt

type Crypt uint

Crypt identifies a crypt function that is implemented in another package.

const (
	APR1   Crypt = 1 + iota // import github.com/GehirnInc/crypt/apr1_crypt
	MD5                     // import github.com/GehirnInc/crypt/md5_crypt
	SHA256                  // import github.com/GehirnInc/crypt/sha256_crypt
	SHA512                  // import github.com/GehirnInc/crypt/sha512_crypt

)

func (Crypt) Available

func (c Crypt) Available() bool

Available reports whether the Crypt c is available.

func (Crypt) New

func (c Crypt) New() Crypter

New returns new Crypter making the Crypt c. New panics if the Crypt c is unavailable.

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 common.Salt)
}

Crypter is the common interface implemented by all crypt functions.

func New

func New(c Crypt) Crypter

New returns a new crypter.

func NewFromHash

func NewFromHash(hashedKey string) Crypter

NewFromHash returns a new Crypter using the prefix in the given hashed key.