package module
Version: v0.0.0-...-d8dc095 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2016 License: BSD-2-Clause, MIT Imports: 10 Imported by: 0


GoDoc Go Report Card


pbkdf2pass is a library written in go that provides a wrapper for encoding passwords. This is useful for storing password hashes in databases or flat files for users in a system. It is intended to be moderately more secure than simple MD5 or SHA1 hashes which can be quickly decoded using Rainbow Tables or other methods. This library is based off of the work by Defuse Security and can be found here.


To install the library you just do a go get:

go get github.com/koepkeca/pbkdf2pass

Data Format

The hashed data is stored in a string with a ':' as a separator. The order is static and is as follows:



  • hash_string is a string defining the hash type [valid types are sha1, sha224, sha256, sha384, sha512] the default type is sha256
  • iteration_length is an integer (int) that defines the number of iterations for the pbkdf2 encoding
  • salt is a base64 encoded string containing the salt
  • password is a base64 encoded string containing the password


To generate a new encoded password you will need to provide some configuration information. The default values are set as constants and may be changed at any time without corrupting existing hashes. You can also override the defaults by setting the new value in the configuration structure. For example, if you wanted to use SHA384 encoding with an iteration count of 4000 just create a Config struct as follows:

c := pbkdf2pass.Config{Algo:"sha384",IterLen:4000}

Creating a password hash

To encode a string using the parameters setup in your config you call the Encode method with the string you would like to encode, this returns a Password structure containing the encoded data.

c := pbkdf2pass.Config{}
p, e := c.Encode("Test123")
if e != nil {

p now contains a Password structure containing the relevant data.

Password implements the fmt.Stringer interface so you can use it accordingly.

To get the encoded string data you can either use:

encStr := p.String()


encStr := fmt.Sprintf("%s",encStr)

Comparing a challenge request

There are two steps you need to perform to validate a challenge. The following example illustrates validating a challenge. For the purposes of this example we will call the challenge string "challenge" and the pre-encoded password "key":

//assume key is a pre-encoded string (see above) and challenge is a 
//plain-text string entered by a user (this would be the password we are comparing against)

c := pbkdf2pass.Config{}
encKey, err := c.FromString(key)
if err != nil {
    //If there is an error decoding the key, you need to handle it here
    log.Fatal(" error decoding key from string.. failing")
//Now encKey contains the data loaded in from our string, we can just
//do a validate on the challenge
isValidPass := encKey.Validate(challenge)
//isValidPass now is true if the password matches, false if it does not

Complete coded examples are included in the example directory and include a basic encoding and decoding example.

Gotcha's and caveats

  • If any part of a Config is not explicitly set, it uses the default values.
  • The Validate method does not provide an error. There could be a base64 decoding error, however, we currently ignore it. Future versions may provide logging. It currently silently fails as a security precaution.
  • Ensure your storage method has adequate space for your hash length. Keep in mind that the salt and hash are stored as a base64 encoded value and will require more space than just the byte length.



Package pbkdf2pass is a wrapper for using pbkdf2 encoded passwords. It is based on the article "Salted Password Hashing - Doing it Right" written by Defuse Security (http://crackstation.net/hashing-security.htm) This provides functionality to store a salted keyed password.



View Source
const (
	DEFAULT_ALGO     = "sha256"

These may be changed at any time


This section is empty.


This section is empty.


type Config

type Config struct {
	Algo    string
	Salt    []byte
	IterLen int
	HashLen int
	SaltLen int

A Config contains the basic configuration for encoding The Algo must be a valid key in the hashes map Empty Salts will be generated upon Encoding

func (Config) Encode

func (c Config) Encode(s string) (p Password, e error)

Encode encodes a string using the configuration in c It returns a Password structure

type Password

type Password struct {
	HashType    string
	EncodedPass []byte
	Salt        []byte
	IterLen     int

Password contains the password data EncodedPass and Salt are the base64-Encoded values, if you intend to work with the Raw Bytes, you MUST decode the values to get the raw bytes.

func FromString

func FromString(s string) (p Password, e error)

FromString takes an encoded pasword structure and creates a Password e returns any decoding errors

func (Password) String

func (p Password) String() (s string)

String implements the fmt.Stringer interface Use this method to get a "writable" form of the password

func (Password) Validate

func (p Password) Validate(s string) (v bool)

Validate returns if String s matches the password stored in p It does this at "length-constant" time using the slowEquals method

Source Files


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL