| Copyright | (c) Dennis Gosnell 2019; Felix Paulusma 2020 |
|---|---|
| License | BSD-style (see LICENSE file) |
| Maintainer | cdep.illabout@gmail.com |
| Stability | experimental |
| Portability | POSIX |
| Safe Haskell | None |
| Language | Haskell2010 |
Data.Password
Description
This library provides an easy way for interacting with passwords from Haskell.
It provides the types Password and PasswordHash, which correspond to plain-text and
hashed passwords.
API
Every supported hashing algorithm has its own module (e.g. Data.Password.Bcrypt)
which exports its own hashPassword and checkPassword functions, as well as all the
types and functions in this module. If you are not sure about the specifics of an
algorithm you want to use, you can rest assured that by using the hashPassword function
of the respective algorithm you are not making any big mistakes, security-wise.
Of course, if you know what you're doing and you want more fine-grained control
over the hashing function, you can adjust it using the hashPasswordWithParams
function of the respective algorithm.
Algorithms
Generally, the most "secure" algorithm is believed to be Argon2,
then Scrypt, then Bcrypt, and lastly PBKDF2. Bcrypt and PBKDF2
are the most established algorithms, so they have been tried and tested, though
they both lack a memory cost, and therefore have a greater vulnerability to
specialized hardware attacks.
When choosing an algorithm, and you have no idea which to pick, just go for
Bcrypt if your password does not need the highest security possible.
It's still a fine way for hashing passwords, and the cost is easily adjustable if needed.
If your needs do require stronger protection, you should find someone who can advise you
on this topic. (And if you're already knowledgeable enough, you know what to do)
Special instances
The real benefit of this module is that there is an accompanying
password-instances
package that provides canonical typeclass instances for
Password and PasswordHash for many common typeclasses, like
FromJSON from
aeson,
PersistField
from
persistent, etc.
See the password-instances package for more information.
Synopsis
- data Password
- mkPassword :: Text -> Password
- newtype PasswordHash a = PasswordHash {}
- data PasswordCheck
- newtype Salt a = Salt ByteString
- newSalt :: MonadIO m => Int -> m (Salt a)
- unsafeShowPassword :: Password -> Text
Plain-text Password
A plain-text password.
This represents a plain-text password that has NOT been hashed.
You should be careful with Password. Make sure not to write it to logs or
store it in a database.
You can construct a Password by using the mkPassword function or as literal
strings together with the OverloadedStrings pragma (or manually, by using
fromString on a String). Alternatively, you could also use some of the
instances in the password-instances
library.
Password Hashing
newtype PasswordHash a Source #
A hashed password.
This represents a password that has been put through a hashing function. The hashed password can be stored in a database.
Constructors
| PasswordHash | |
Fields | |
Instances
data PasswordCheck Source #
The result of checking a password against a hashed version. This is
returned by the checkPassword functions.
Constructors
| PasswordCheckSuccess | The password check was successful. The plain-text password matches the hashed password. |
| PasswordCheckFail | The password check failed. The plain-text password does not match the hashed password. |
Instances
| Eq PasswordCheck Source # | |
Defined in Data.Password.Internal Methods (==) :: PasswordCheck -> PasswordCheck -> Bool # (/=) :: PasswordCheck -> PasswordCheck -> Bool # | |
| Read PasswordCheck Source # | |
Defined in Data.Password.Internal Methods readsPrec :: Int -> ReadS PasswordCheck # readList :: ReadS [PasswordCheck] # | |
| Show PasswordCheck Source # | |
Defined in Data.Password.Internal Methods showsPrec :: Int -> PasswordCheck -> ShowS # show :: PasswordCheck -> String # showList :: [PasswordCheck] -> ShowS # | |
A salt used by a hashing algorithm.
Since: 2.0.0.0
Constructors
| Salt ByteString |
Unsafe debugging function to show a Password
unsafeShowPassword :: Password -> Text Source #
This is an unsafe function that shows a password in plain-text.
>>>unsafeShowPassword ("foobar" :: Password)"foobar"
You should generally not use this function.