mirror of
https://github.com/restic/restic.git
synced 2024-12-23 08:16:36 +00:00
41c35b2218
The master branch includes a fix for i386, otherwise the calibration panics. See https://github.com/restic/restic/issues/676 for details.
155 lines
5.1 KiB
Markdown
155 lines
5.1 KiB
Markdown
# simple-scrypt
|
|
[![GoDoc](https://godoc.org/github.com/elithrar/simple-scrypt?status.svg)](https://godoc.org/github.com/elithrar/simple-scrypt) [![Build Status](https://travis-ci.org/elithrar/simple-scrypt.svg?branch=master)](https://travis-ci.org/elithrar/simple-scrypt)
|
|
|
|
simple-scrypt provides a convenience wrapper around Go's existing
|
|
[scrypt](http://golang.org/x/crypto/scrypt) package that makes it easier to
|
|
securely derive strong keys ("hash user passwords"). This library allows you to:
|
|
|
|
* Generate a scrypt derived key with a crytographically secure salt and sane
|
|
default parameters for N, r and p.
|
|
* Upgrade the parameters used to generate keys as hardware improves by storing
|
|
them with the derived key (the scrypt spec. doesn't allow for this by
|
|
default).
|
|
* Provide your own parameters (if you wish to).
|
|
|
|
The API closely mirrors Go's [bcrypt](https://golang.org/x/crypto/bcrypt)
|
|
library in an effort to make it easy to migrate—and because it's an easy to grok
|
|
API.
|
|
|
|
## Installation
|
|
|
|
With a [working Go toolchain](https://golang.org/doc/code.html):
|
|
|
|
```sh
|
|
go get -u github.com/elithrar/simple-scrypt
|
|
```
|
|
|
|
## Example
|
|
|
|
simple-scrypt doesn't try to re-invent the wheel or do anything "special". It
|
|
wraps the `scrypt.Key` function as thinly as possible, generates a
|
|
crytographically secure salt for you using Go's `crypto/rand` package, and
|
|
returns the derived key with the parameters prepended:
|
|
|
|
```go
|
|
package main
|
|
|
|
import(
|
|
"fmt"
|
|
"log"
|
|
|
|
"github.com/elithrar/simple-scrypt"
|
|
)
|
|
|
|
func main() {
|
|
// e.g. r.PostFormValue("password")
|
|
passwordFromForm := "prew8fid9hick6c"
|
|
|
|
// Generates a derived key of the form "N$r$p$salt$dk" where N, r and p are defined as per
|
|
// Colin Percival's scrypt paper: http://www.tarsnap.com/scrypt/scrypt.pdf
|
|
// scrypt.Defaults (N=16384, r=8, p=1) makes it easy to provide these parameters, and
|
|
// (should you wish) provide your own values via the scrypt.Params type.
|
|
hash, err := scrypt.GenerateFromPassword([]byte(passwordFromForm), scrypt.DefaultParams)
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
// Print the derived key with its parameters prepended.
|
|
fmt.Printf("%s\n", hash)
|
|
|
|
// Uses the parameters from the existing derived key. Return an error if they don't match.
|
|
err := scrypt.CompareHashAndPassword(hash, []byte(passwordFromForm))
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
}
|
|
```
|
|
|
|
## Upgrading Parameters
|
|
|
|
Upgrading derived keys from a set of parameters to a "stronger" set of parameters
|
|
as hardware improves, or as you scale (and move your auth process to separate
|
|
hardware), can be pretty useful. Here's how to do it with simple-scrypt:
|
|
|
|
```go
|
|
func main() {
|
|
// SCENE: We've successfully authenticated a user, compared their submitted
|
|
// (cleartext) password against the derived key stored in our database, and
|
|
// now want to upgrade the parameters (more rounds, more parallelism) to
|
|
// reflect some shiny new hardware we just purchased. As the user is logging
|
|
// in, we can retrieve the parameters used to generate their key, and if
|
|
// they don't match our "new" parameters, we can re-generate the key while
|
|
// we still have the cleartext password in memory
|
|
// (e.g. before the HTTP request ends).
|
|
current, err := scrypt.Cost(hash)
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
// Now to check them against our own Params struct (e.g. using reflect.DeepEquals)
|
|
// and determine whether we want to generate a new key with our "upgraded" parameters.
|
|
slower := scrypt.Params{
|
|
N: 32768,
|
|
R: 8,
|
|
P: 2,
|
|
SaltLen: 16,
|
|
DKLen: 32,
|
|
}
|
|
|
|
if !reflect.DeepEqual(current, slower) {
|
|
// Re-generate the key with the slower parameters
|
|
// here using scrypt.GenerateFromPassword
|
|
}
|
|
}
|
|
```
|
|
|
|
## Automatically Determining Parameters
|
|
|
|
Thanks to the work by [tgulacsi](https://github.com/tgulacsi), you can have simple-scrypt
|
|
automatically determine the optimal parameters for you (time vs. memory). You should run this once
|
|
on program startup, as calibrating parameters can be an expensive operation.
|
|
|
|
```go
|
|
var params scrypt.Params
|
|
|
|
func main() {
|
|
var err error
|
|
// 500ms, 64MB of RAM per hash.
|
|
params, err = scrypt.Calibrate(500*time.Millisecond, 64, Params{})
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
...
|
|
}
|
|
|
|
func RegisterUserHandler(w http.ResponseWriter, r *http.Request) {
|
|
err := r.ParseForm()
|
|
if err != nil {
|
|
http.Error(w, err.Error(), http.StatusBadRequest)
|
|
return
|
|
}
|
|
|
|
// Make sure you validate: not empty, not too long, etc.
|
|
email := r.PostFormValue("email")
|
|
pass := r.PostFormValue("password")
|
|
|
|
// Use our calibrated parameters
|
|
hash, err := scrypt.GenerateFromPassword([]byte(pass), params)
|
|
if err != nil {
|
|
http.Error(w, err.Error(), http.StatusBadRequest)
|
|
return
|
|
}
|
|
|
|
// Save to DB, etc.
|
|
}
|
|
```
|
|
|
|
Be aware that increasing these, whilst making it harder to brute-force the resulting hash, also
|
|
increases the risk of a denial-of-service attack against your server. A surge in authenticate
|
|
attempts (even if legitimate!) could consume all available resources.
|
|
|
|
## License
|
|
|
|
MIT Licensed. See LICENSE file for details.
|
|
|