README
¶
pwcrypto
Go library with password cryptography routines
This library provides routines for securly storing passwords in a database and validating them.
Features:
- All passwords stored with one-way hashes
- Unique salts per user
- Upgradable cryptography algorithms and hash strengths
- Indicates when passwords should be rehashed to gradually upgrade password cryptography
- Configurable hashing routines
Usage
Create a Crypto object, which will hold the cryptography routines used. Pass
the algorithms you wish to use as arguments. The first algorithm will be used
for storing passwords, the other algorithms are accepted for existing passwords
(see Password Upgrades below).
passwords := pwcrypto.New(
NewArgon2Crypto(),
NewScryptCrypto(),
NewPBKDF2Crypto(),
NewSHA256Crypto(),
)
Use Hash() when storing a password for a user:
hash, err := passwords.Hash("mySecurePassword")
The value of hash is a string containing the hashed password and a set of
configuration parameters used for verifying the password. Store this string in
your database.
Use Check() for validating passwords:
valid, mustUpgrade, err := passwords.Check("someUserInput", hash)
In the above:
hashis the value you previously stored in your database, look it up for the user trying to authenticate"someUserInput"is the password entered during loginvalidindicates whether the input is correctmustUpgradeindicates that the password needs to be upgraded (see below).
Password Upgrades
During check, mustUpgrade will be true if the database hash uses an
outdated hash. In this case you should use Hash() again with the user input
and store the new hashed value in your database.
This allows you to to upgrade your database gradually. Suppose you previously
used SHA1, but want to upgrade to SHA256. Just configure pwcrypto with
SHA256 as the primary algorithm and SHA1 as the fallback algorithm.
passwords := pwcrypto.New(
NewSHA256Crypto(),
NewSHA1Crypto(),
)
Whenever a user logs in correctly, you'll receive mustUpgrade == true. At
this point you can use the user input to re-hash the password, which will then
use SHA256.
Configuring hashing algorithms
By default, the unparametrized algorithm constructor will return a best-practices version of the algorithm.
You can use the more verbose constructor to override specific options (if any).
PBKDF2
- Default:
NewPBKDF2Crypto() - Verbose:
NewPBKDF2CryptoWithOptions(iter, keyLen, saltLen int, hashFns []HashFunction)
Allows you to override the number of iterations, key length, salt length and hashing functions (for HMAC). Similar to crypto algorithms, the first hash function is preferred, others are for fallback compatibility.
Scrypt
- Default:
NewScryptCrypto() - Verbose:
NewScryptCryptoWithOptions(saltLen, cpuMemCost, r, p, keyLen int)
Argon2
- Default:
NewArgon2Crypto() - Verbose:
NewArgon2CryptoWithOptions(saltLen int, time, memory uint32, threads uint8, keyLen uint32)
License
This library is distributed under the MIT license.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Argon2Crypto ¶ added in v1.1.0
type Argon2Crypto struct {
// contains filtered or unexported fields
}
func NewArgon2Crypto ¶ added in v1.1.0
func NewArgon2Crypto() Argon2Crypto
Create Argon2Crypto with recommended options
func NewArgon2CryptoWithOptions ¶ added in v1.1.0
func NewArgon2CryptoWithOptions(saltLen int, time, memory uint32, threads uint8, keyLen uint32) Argon2Crypto
Create Argon2Crypto with given salt length, time, memory, threads and key length.
func (Argon2Crypto) Check ¶ added in v1.1.0
func (a Argon2Crypto) Check(input, hashed string) (bool, bool, error)
func (Argon2Crypto) ID ¶ added in v1.1.0
func (a Argon2Crypto) ID() string
type Crypto ¶
type Crypto struct {
// contains filtered or unexported fields
}
type HashFunction ¶
type HashFunction int
const ( SHA1 HashFunction = 0 //SHA224 HashFunction = 1 SHA256 HashFunction = 2 //SHA384 HashFunction = 3 SHA512 HashFunction = 4 )
func ParseHashFunction ¶
func ParseHashFunction(in string) (HashFunction, error)
func (HashFunction) Hash ¶
func (h HashFunction) Hash() func() hash.Hash
func (HashFunction) String ¶
func (h HashFunction) String() string
type PBKDF2Crypto ¶
type PBKDF2Crypto struct {
// contains filtered or unexported fields
}
func NewPBKDF2CryptoWithOptions ¶
func NewPBKDF2CryptoWithOptions(iter, keyLen, saltLen int, hashFns []HashFunction) PBKDF2Crypto
Create PBKDF2C with given number of iterations, key length, salt length and accepted hash functions.
First hash function is the preferred one which will be used for new passwords, all other ones will signal the need for an upgrade.
func (PBKDF2Crypto) ID ¶
func (a PBKDF2Crypto) ID() string
type SHA1Crypto ¶
type SHA1Crypto struct {
// contains filtered or unexported fields
}
func NewSHA1CryptoWithOptions ¶
func NewSHA1CryptoWithOptions(saltLen int) SHA1Crypto
func (SHA1Crypto) ID ¶
func (a SHA1Crypto) ID() string
type SHA256Crypto ¶
type SHA256Crypto struct {
// contains filtered or unexported fields
}
func NewSHA256CryptoWithOptions ¶
func NewSHA256CryptoWithOptions(saltLen int) SHA256Crypto
func (SHA256Crypto) ID ¶
func (a SHA256Crypto) ID() string
type ScryptCrypto ¶
type ScryptCrypto struct {
// contains filtered or unexported fields
}
func NewScryptCrypto ¶
func NewScryptCrypto() ScryptCrypto
Create ScryptCrypto with recommended options
func NewScryptCryptoWithOptions ¶
func NewScryptCryptoWithOptions(saltLen, cpuMemCost, r, p, keyLen int) ScryptCrypto
Create ScryptCrypto with given salt length, CPU/mem cost, r, p and key length.
func (ScryptCrypto) ID ¶
func (a ScryptCrypto) ID() string
Source Files