pass
2015-12-14
Parent:b394d1d58b85
pass/README.md
Update to new crypto import path. Our the Go crypto library is now located at golang.org/x/crypto, so we need to update to use that instead of Google Code.
| paddy@0 | 1 # Pass |
| paddy@0 | 2 |
| paddy@0 | 3 Pass is a library of convenience functions for securely handling passphrases. |
| paddy@0 | 4 |
| paddy@0 | 5 ## On Startup |
| paddy@0 | 6 |
| paddy@0 | 7 When your server first starts up, you should run the `CalculateIterations` function, passing the `hash.Hash` you intend to use in hashing passphrases. I recommend SHA-256. This iteration count will be used later, so hold on to it. |
| paddy@0 | 8 |
| paddy@0 | 9 ## To Hash a Passphrase |
| paddy@0 | 10 |
| paddy@0 | 11 When a user first signs up, you need to hash their passphrase and store it in your database. _Never store their unencrypted passphrase **anywhere**_. |
| paddy@0 | 12 |
| paddy@0 | 13 To do this, run the `Create` function, passing the `hash.Hash` you intend to use in hashing their passphrase (I recommend SHA-256), the number of iterations to use in hashing their passphrase (this should come from `CalculateIterations` and the hash being used to create the passphrase should be the hash used to calculate the number of iterations), and the passphrase the user entered as a slice of bytes. |
| paddy@0 | 14 |
| paddy@0 | 15 The resulting hash and a salt will be returned. You should store the salt, the hash, and the number of iterations in your database--this will allow you to set those variables on a per-passphrase basis. |
| paddy@0 | 16 |
| paddy@0 | 17 ## To Check a Passphrase |
| paddy@0 | 18 |
| paddy@0 | 19 Retrieve the passphrase you wish to check against (probably keyed by ID or username) from your database. You'll need the salt, the hash, the hashing algorithm, and the number of iterations to run. |
| paddy@0 | 20 |
| paddy@0 | 21 Run `Check`, passing it the hashing algorithm--which should match the hashing algorithm run against the passphrase originally--, the number of iterations, the passphrase the user just entered you want to compare to the stored passphrase, and the salt. The output will be a candidate hash. |
| paddy@0 | 22 |
| paddy@0 | 23 Finally, run `Compare`, passing it the candidate hash and the hash from your database. This is a constant time function, and will compare the two based on the length of the candidate. |
| paddy@0 | 24 |
| paddy@0 | 25 If `Compare` returns true, the passphrases match. |