~eau/passwd

1c2f9c6650007bad95f4de47159500498a910ff0 — eau 4 years ago c3871ec
README update
1 files changed, 18 insertions(+), 12 deletions(-)

M README.md
M README.md => README.md +18 -12
@@ 41,20 41,23 @@ It is an attempt to dimension crypto parameters to common use cases (interactive
- Default  : ~interactive.
- Paranoid : file storage.

Custom profiles allow a user to define its own hashing parameters if those default don't fit.
Custom profiles allow a user to define its own hashing parameters if those default don't fit.  


## Public vs Masked parameters

Commonly password hashing includes hashing parameters in order to provide interoperability.

if no interoperability is needed (outside your authentication needs) and to make things slightly more annoying for a regular 
attacker, you might "mask" your parameters (instead of embedding them in the resulting hash).
attacker, you might "mask" your parameters (instead of embedding them in the resulting hash).  


### Public parameters (common practice)

Public parameters will embbed the derivation parameters in the resulting hash.
This allows you to simply use the **`passwd.Compare()`** function against a hash without
the need of a profile object.
the need of a profile object.  


### Masked parameters



@@ 65,7 68,8 @@ method.
An attacker would have to not only grab the stored password, but also to guess the parameters you use
with your key derivation in order to attack it offline.

**!!! IMPORTANT !!! This is NOT what makes your hash safe, it just makes it slightly harder to attack offline.**
**!!! IMPORTANT !!! This is NOT what makes your hash safe, it just makes it slightly harder to attack offline.**  


### Key'ed Hash 



@@ 75,8 79,7 @@ key'd hashes try to guarantee that leaked password cannot be attacked offline.

We used the method described [here](https://bristolcrypto.blogspot.com/2015/01/password-hashing-according-to-facebook.html).

This requires you to **`<profile>.SetSecret()`** before call the **`Hash()`** or **`Compare()`** function.

This requires you to **`<profile>.SetSecret()`** before call the **`Hash()`** or **`Compare()`** function.  





@@ 95,8 98,7 @@ Hash your password:

done, that's it, now **`hashed`** contain the hashed password:   

**`$2id$GlQX3F.KSYw1JLVv.LKDT.$1$65536$8$32$97DO7W9m/I8CTEQFKDa.VvEBTX1WepVv4qaWlt0OqH6`**

**`$2id$GlQX3F.KSYw1JLVv.LKDT.$1$65536$8$32$97DO7W9m/I8CTEQFKDa.VvEBTX1WepVv4qaWlt0OqH6`**  





@@ 106,7 108,8 @@ check a hash against a password:

**`err := passwd.Compare(hashed, []byte("password"))`**  

done, `err` will be nil if the password matches the hash.
done, `err` will be nil if the password matches the hash.  






@@ 115,7 118,8 @@ done, `err` will be nil if the password matches the hash.

create a password hashing profile:   

**`p, err := passwd.NewMasked(passwd.Argon2idDefault)`**
**`p, err := passwd.NewMasked(passwd.Argon2idDefault)`**  



Hash your password:   


@@ 125,7 129,8 @@ Hash your password:
done, that's it, now **`hashed`** contain the hashed password and parameters are
masked.  

**`$2id$ihFFCGUfBHTqUfvUIos6X.$AmClxc.3uj6LsxjVGqpOZggyqIL.wQJ9zjY23ztsETK`**
**`$2id$ihFFCGUfBHTqUfvUIos6X.$AmClxc.3uj6LsxjVGqpOZggyqIL.wQJ9zjY23ztsETK`**  


### Password Compare (**masked parameters**) :



@@ 133,7 138,8 @@ check a hash against a password:

**`err := p.Compare(hashed, []byte("password"))`**

done.
done.  


Status
------