Data.Password

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.

Plain-text Password

data 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.

Instances

Show Password

CAREFUL: Show-ing a Password will always print "**PASSWORD**"

>>> show ("hello" :: Password)
"**PASSWORD**"

Since: 1.0.0.0

Defined in Data.Password.Internal

Methods

showsPrec :: Int -> Password -> ShowS

show :: Password -> String

showList :: [Password] -> ShowS

IsString Password

Defined in Data.Password.Internal

Methods

fromString :: String -> Password

mkPassword :: Text -> Password

Construct a Password

Since: 1.0.0.0

Password Hashing

newtype PasswordHash a

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

• unPasswordHash :: Text

Instances

Eq (PasswordHash a)

Defined in Data.Password.Internal

Methods

(==) :: PasswordHash a -> PasswordHash a -> Bool

(/=) :: PasswordHash a -> PasswordHash a -> Bool

Ord (PasswordHash a)

Defined in Data.Password.Internal

Methods

compare :: PasswordHash a -> PasswordHash a -> Ordering

(<) :: PasswordHash a -> PasswordHash a -> Bool

(<=) :: PasswordHash a -> PasswordHash a -> Bool

(>) :: PasswordHash a -> PasswordHash a -> Bool

(>=) :: PasswordHash a -> PasswordHash a -> Bool

max :: PasswordHash a -> PasswordHash a -> PasswordHash a

min :: PasswordHash a -> PasswordHash a -> PasswordHash a

Read (PasswordHash a)

Defined in Data.Password.Internal

Methods

readsPrec :: Int -> ReadS (PasswordHash a)

readList :: ReadS [PasswordHash a]

readPrec :: ReadPrec (PasswordHash a)

readListPrec :: ReadPrec [PasswordHash a]

Show (PasswordHash a)

Defined in Data.Password.Internal

Methods

showsPrec :: Int -> PasswordHash a -> ShowS

show :: PasswordHash a -> String

showList :: [PasswordHash a] -> ShowS

data PasswordCheck

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

Defined in Data.Password.Internal

Methods

(==) :: PasswordCheck -> PasswordCheck -> Bool

(/=) :: PasswordCheck -> PasswordCheck -> Bool

Read PasswordCheck

Defined in Data.Password.Internal

Methods

readsPrec :: Int -> ReadS PasswordCheck

readList :: ReadS [PasswordCheck]

readPrec :: ReadPrec PasswordCheck

readListPrec :: ReadPrec [PasswordCheck]

Show PasswordCheck

Defined in Data.Password.Internal

Methods

showsPrec :: Int -> PasswordCheck -> ShowS

show :: PasswordCheck -> String

showList :: [PasswordCheck] -> ShowS

newtype Salt a

A salt used by a hashing algorithm.

Since: 2.0.0.0

Constructors

Salt ByteString

Instances

Eq (Salt a)

Defined in Data.Password.Internal

Methods

(==) :: Salt a -> Salt a -> Bool

(/=) :: Salt a -> Salt a -> Bool

Show (Salt a)

Defined in Data.Password.Internal

Methods

showsPrec :: Int -> Salt a -> ShowS

show :: Salt a -> String

showList :: [Salt a] -> ShowS

newSalt :: MonadIO m => Int -> m (Salt a)

Generate a random x-byte-long salt.

Since: 2.0.0.0

Unsafe debugging function to show a Password

unsafeShowPassword :: Password -> Text

This is an unsafe function that shows a password in plain-text.

>>> unsafeShowPassword ("foobar" :: Password)
"foobar"

You should generally not use this function.