https://github.com/rubenv/pwcrypto
Go library with password cryptography routines
https://github.com/rubenv/pwcrypto
Last synced: 12 months ago
JSON representation
Go library with password cryptography routines
- Host: GitHub
- URL: https://github.com/rubenv/pwcrypto
- Owner: rubenv
- License: mit
- Created: 2019-06-13T07:05:04.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-08-30T19:37:16.000Z (almost 3 years ago)
- Last Synced: 2025-02-24T08:27:08.029Z (over 1 year ago)
- Language: Go
- Size: 24.4 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pwcrypto
> Go library with password cryptography routines
[](https://github.com/rubenv/pwcrypto/actions/workflows/test.yml) [](https://godoc.org/github.com/rubenv/pwcrypto)
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:
- `hash` is the value you previously stored in your database, look it up for the user trying to authenticate
- `"someUserInput"` is the password entered during login
- `valid` indicates whether the input is correct
- `mustUpgrade` indicates 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) license.