Document error kinds and remove dead BcryptError::Io branch

[goto-bus-stop]

Hi! I was looking into how I should best handle the errors returned by bcrypt in my web service. I especially wasn't sure what conditions some errors could be raised under.

This PR documents whether errors can happen during hashing or verification, so users can more easily decide what they want to do with the different error cases.

Additionally, the BcryptError::Io branch appears to be unused, so I suggest removing it outright 😇

[goto-bus-stop]

I pointed out where the cost value comes from because if this error is raised from bcrypt::hash(), it was actually a programmer error, and if you have a hardcoded cost you can just handle that branch with unreachable!(). But during verification it means the hash was malformed which is something you have to deal with always.

[Keats]

All those different errors mapping to the same thing makes me thing it should probably a single error with details in the string

[goto-bus-stop]

Sorta thought the same while doing it, I think as a user you wouldn't do different things for these different branches. I didn't change it already because they have different data inside the branch (like the length of the salt for InvalidSaltLen, but that might also not be that useful. I'll change it to a single branch later today so you can see if you like it :)

[goto-bus-stop]

In the latest commit I've changed the errors that can occur when parsing a hash for verification to be &'static strs. This does mean they have less information than before, but I think in most cases that information was not really actionable for a user to begin with; they just need to know "the hash is malformed", it's not something that you would recover from differently depending on if it's the salt length or the hash base64 that's incorrect.

[tarcieri]

FWIW I recently revamped the error type in the password-hash crate, and also added a variant with &'static str for tracking which field in the params was invalid: https://docs.rs/password-hash/0.6.0-rc.4/password_hash/enum.Error.html

That's trying to be a sort of universal error type for this case, so I'd be curious how well it lines up with yours and what features anyone things are missing.

Also, with the latest prereleases of password-hash and mcf it should now be possible to (optionally) impl the password-hash traits for bcrypt, if that's something you're interested in.

[Keats]

I think one variant makes sense.

I'm not familiar with password-hash but i guess once there is a new release we can look at maybe implementing the trait behind a feature