x/crypto/scrypt,x/crypto/argon2: add high-level APIs

[elithrar]

Summary: The x/crypto/scrypt package has a very simple API that puts the onus of figuring out salt generation and sensible N/r/p values on the package user. We should attempt to mirror the bcrypt packages' API and provide sensible defaults.

Details:

• Add a GenerateFromPassword function that generates output in the form N$r$p$salt$dk (noting that there is no 'standard' for scrypt here)
• Add a CompareHashAndPassword function
• Add a Cost function that can return the cost of a given output (i.e. for determining whether to upgrade or not)
• Provide sensible default params that provide reasonable values of N, r, p and document why/when you may wish to change them.
• Potentially provide a way to automatically determine values of N, r, p given memory (MB) and time (ms) constraints.

Note that I've done most of this work in https://godoc.org/github.com/elithrar/simple-scrypt and would seek to bring most of this in.

[adg]

Seems reasonable to me, but @agl should take a look.

[bradfitz]

Ping @agl.

[kevinburke]

puts the onus of figuring out salt generation and sensible N/r/p values on the package user.
Provide sensible default params that provide reasonable values of N, r, p and document why/when you may wish to change them.

I just added some better documentation here, so hopefully this is better now.

Add a GenerateFromPassword function that generates output in the form N$r$p$salt$dk (noting that there is no 'standard' for scrypt here)

I'd feel uncomfortable publishing this without having some sort of standard present on the scrypt website. You could ask Colin Percival if he is interested in it.

Add a CompareHashAndPassword function

This would be reasonable but we'd need to figure out what the hash input should be.

Add a Cost function that can return the cost of a given output (i.e. for determining whether to upgrade or not)

The API for bcrypt takes a []byte but []byte is also the output from scrypt.Key. You'd have to know to use the GenerateFromPassword output instead.

[elithrar]

Thanks for taking a look at this @kevinburke (I'd forgotten myself)

I'd feel uncomfortable publishing this without having some sort of standard present on the scrypt website. You could ask Colin Percival if he is interested in it.

Noted. I pinged Colin on Twitter, and as there isn't a specified output format (there isn't in the paper), have asked if there's any intent to specify. Unlikely, but doesn't hurt to ask.

The other two points are somewhat held up on a standard format. The alternative would be to return a struct of the params for the caller to then stringify as needed.

PS: I did note the improved params "for 2017" CL the other day, which is a good start.

[ianlancetaylor]

Ping @agl @FiloSottile

[FiloSottile]

Here's a proposal for a high-level password API for scrypt.

const RecommendedCost = 15
func NewHash(password string, cost int) (string, error)
func Cost(hash string) (int, error)
func Check(hash, password string) error
func Calibrate(t time.Duration, memoryMiB int) (cost int, err error)

We should just fix r = 8 and p = 1, as there is no reason to change those, and users can still use the low-level Key interface. We can support different values in Check.

For the $ identifier, we should probably just copy libsodium, but I'll put together a wider survey.

We should probably not have minimum and maximum costs, but the Check docs should recommend checking with Cost if the hash is not trusted. Cost needs to take r and p into account, by scaling the returned cost relatively to them.

While at it, let's also do argon2.

const RecommendedTime = 1
const RecommendedMemory = 32 * 1024
func NewHash(password string, time, memoryKiB uint32) (string, error)
func Cost(hash string) (time, memoryKiB uint32, threads uint8, err error)
func Check(hash, password string) error
func Calibrate(t time.Duration) (time uint32, err error)

We've left out threads because it doesn't seem to be widely used (is that true?) and one can still use Key, but had to return it from Cost because it affects the performance in a way that is not as easily aggregated as scrypt.Cost.

RecommendedMemory matches the memory of scrypt.RecommendedCost.

-- @FiloSottile and @katiehockman

[Jacalz]

I have been quite interested in cryptography recently and I am currently using bcrypt because of the super easy high level API that can be used. I would have preferred to use scrypt or argon2 due to them generally being advertised as more secure from what I can tell. That is precisely why I think this is a great idea and I think more users in Go would adopt usage of scrypt and argon2if they were easier to use.

Regarding the proposals, I really like the idea from @FiloSottile with the recommended values. That makes life a lot easier and it could enforce strong security because recommendations could ideally be bumped in future releases in case such a need should emerge. It looks like the recommendation is to have parallelism that corresponds to the amount of cores (or perhaps threads) on the computer system. Might be good to do this automatically in this high level API.

However, I would like that the names match those in bcrypt and I think that it makes a lot of sense to be concise. Thus I would appreciate if the NewHash() was GenerateFromPassword() and Check() wasCompareHashAndPassword(). It might also, as mentioned above, make sense to check the number of cores using runtime.NumCPU() for setting the parallelism. It might not be needed to be passed in as a function parameter, but it might make sense to check it based on cpu cores.

Might also make sense if the Argon2 implementation used Argon2ID because it seems to be recommended if the user doesn't know what to use.

[rsc]

Using very long names because they already exist is not typically a good pattern. Cleaning up the API is almost certainly worth doing.

[rsc]

@FiloSottile posted a new API 19 days ago and there have not been many comments. Does anyone object to accepting this new API?