scrypt: update recommended parameters for 2017

Previously we documented recommended parameters for scrypt from 2009,
which was eight years ago. Update those parameters and also provide
some guidance to users for configuring those settings in 2017. On my
late 2015 Macbook Pro, the scrypt benchmark with N=1<<15, r=8, p=1
completes in 91 milliseconds.

Add an Example with a salt.

Fixes golang/go#22082.

Change-Id: I23e3920db67583c9fce093768a32e67ab9c979f5
Reviewed-on: https://go-review.googlesource.com/67070
Reviewed-by: Adam Langley <agl@golang.org>

scrypt/example_test.go

@@ -0,0 +1,22 @@
+package scrypt_test
+
+import (
+	"encoding/base64"
+	"fmt"
+	"log"
+
+	"golang.org/x/crypto/scrypt"
+)
+
+func Example() {
+	// DO NOT use this salt value; generate your own random salt. 8 bytes is
+	// a good length.
+	salt := []byte{0xc8, 0x28, 0xf2, 0x58, 0xa7, 0x6a, 0xad, 0x7b}
+
+	dk, err := scrypt.Key([]byte("some password"), salt, 1<<15, 8, 1, 32)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(base64.StdEncoding.EncodeToString(dk))
+	// Output: lGnMz8io0AUkfzn6Pls1qX20Vs7PGN6sbYQ2TQgY12M=
+}