# pwcrypto

**Repository Path**: mirrors_rubenv/pwcrypto

## Basic Information

- **Project Name**: pwcrypto
- **Description**: Go library with password cryptography routines
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-18
- **Last Updated**: 2026-01-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pwcrypto

> Go library with password cryptography routines

[![test](https://github.com/rubenv/pwcrypto/actions/workflows/test.yml/badge.svg)](https://github.com/rubenv/pwcrypto/actions/workflows/test.yml) [![GoDoc](https://godoc.org/github.com/rubenv/pwcrypto?status.png)](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.