Data.Password.Instances

This module provides the same interface as Data.Password, but it also provides additional typeclass instances for Pass and PassHash.

See the Data.Password module for more information.

Plaintext Password

data Pass

A plain-text password.

This represents a plain-text password that has NOT been hashed.

You should be careful with Pass. Make sure not to write it to logs or store it in a database.

You can construct a Pass by using the mkPass 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 Pass

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

>>> show $ mkPass "hello"
"**PASSWORD**"

Since: password-1.0.0.0

Defined in Data.Password

Methods

showsPrec :: Int -> Pass -> ShowS

show :: Pass -> String

showList :: [Pass] -> ShowS

IsString Pass

Defined in Data.Password

Methods

fromString :: String -> Pass

FromJSON Pass

This instance allows a Pass to be created from a JSON blob.

>>> let maybePass = decode "\"foobar\"" :: Maybe Pass
>>> fmap unsafeShowPassword maybePass
Just "foobar"

There is no instance for ToJSON for Pass because we don't want to accidentally encode a plain-text Pass to JSON and send it to the end-user.

Similarly, there is no ToJSON and FromJSON instance for PassHash because we don't want to accidentally send the password hash to the end user.

Defined in Data.Password.Instances

Methods

parseJSON :: Value -> Parser Pass

parseJSONList :: Value -> Parser [Pass]

FromHttpApiData Pass

This instance allows a Pass to be created with functions like parseUrlPiece or parseQueryParam.

>>> let eitherPass = parseUrlPiece "foobar"
>>> fmap unsafeShowPassword eitherPass
Right "foobar"

Defined in Data.Password.Instances

Methods

parseUrlPiece :: Text -> Either Text Pass

parseHeader :: ByteString -> Either Text Pass

parseQueryParam :: Text -> Either Text Pass

mkPass :: Text -> Pass

Construct a Pass

Since: password-1.0.0.0

Hashed Password

newtype PassHash

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

PassHash

Fields

• unPassHash :: Text

Instances

Eq PassHash

Defined in Data.Password

Methods

(==) :: PassHash -> PassHash -> Bool

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

Ord PassHash

Defined in Data.Password

Methods

compare :: PassHash -> PassHash -> Ordering

(<) :: PassHash -> PassHash -> Bool

(<=) :: PassHash -> PassHash -> Bool

(>) :: PassHash -> PassHash -> Bool

(>=) :: PassHash -> PassHash -> Bool

max :: PassHash -> PassHash -> PassHash

min :: PassHash -> PassHash -> PassHash

Read PassHash

Defined in Data.Password

Methods

readsPrec :: Int -> ReadS PassHash

readList :: ReadS [PassHash]

readPrec :: ReadPrec PassHash

readListPrec :: ReadPrec [PassHash]

Show PassHash

Defined in Data.Password

Methods

showsPrec :: Int -> PassHash -> ShowS

show :: PassHash -> String

showList :: [PassHash] -> ShowS

PersistFieldSql PassHash

This instance allows a PassHash to be stored as a field in an SQL database in Database.Persist.Sql.

Defined in Data.Password.Instances

Methods

sqlType :: Proxy PassHash -> SqlType

PersistField PassHash

This instance allows a PassHash to be stored as a field in a database using Database.Persist.

>>> let salt = Salt "abcdefghijklmnopqrstuvwxyz012345"
>>> let pass = mkPass "foobar"
>>> let hashedPassword = hashPassWithSalt salt pass
>>> toPersistValue hashedPassword
PersistText "14|8|1|YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU=|nENDaqWBmPKapAqQ3//H0iBImweGjoTqn5SvBS8Mc9FPFbzq6w65maYPZaO+SPamVZRXQjARQ8Y+5rhuDhjIhw=="

In the example above, the long PersistText will be the value you store in the database.

We don't provide an instance of PersistField for Pass, because we don't want to make it easy to store a plain-text password in the database.

Defined in Data.Password.Instances

Methods

toPersistValue :: PassHash -> PersistValue

fromPersistValue :: PersistValue -> Either Text PassHash

newtype Salt

Constructors

Salt

Fields

• getSalt :: ByteString

Instances

Eq Salt

Defined in Crypto.Scrypt

Methods

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

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

Show Salt

Defined in Crypto.Scrypt

Methods

showsPrec :: Int -> Salt -> ShowS

show :: Salt -> String

showList :: [Salt] -> ShowS

Functions for Hashing Plaintext Passwords

hashPass :: MonadIO m => Pass -> m PassHash

Just like hashPassWithSalt, but generate a new Salt everytime with a call to newSalt.

>>> hashPass $ mkPass "foobar"
PassHash {unPassHash = "14|8|1|...|..."}

hashPassWithSalt :: Salt -> Pass -> PassHash

Hash a password with the given Salt.

The resulting PassHash has the parameters used to hash it, as well as the Salt appended to it, separated by |.

The input Salt and resulting PassHash are both byte-64 encoded.

>>> let salt = Salt "abcdefghijklmnopqrstuvwxyz012345"
>>> hashPassWithSalt salt (mkPass "foobar")
PassHash {unPassHash = "14|8|1|YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU=|nENDaqWBmPKapAqQ3//H0iBImweGjoTqn5SvBS8Mc9FPFbzq6w65maYPZaO+SPamVZRXQjARQ8Y+5rhuDhjIhw=="}

(Note that we use an explicit Salt in the example above. This is so that the example is reproducible, but in general you should use hashPass. hashPass generates a new Salt everytime it is called.)

This function uses the hash function from the scrypt package: encryptPass.

newSalt :: MonadIO m => m Salt

Generate a random 32-byte salt.

Functions for Checking Plaintext Passwords Against Hashed Passwords

checkPass :: Pass -> PassHash -> PassCheck

Check a Pass against a PassHash.

Returns PassCheckSuccess on success.

>>> let salt = Salt "abcdefghijklmnopqrstuvwxyz012345"
>>> let pass = mkPass "foobar"
>>> let passHash = hashPassWithSalt salt pass
>>> checkPass pass passHash
PassCheckSuccess

Returns PassCheckFail If an incorrect Pass or PassHash is used.

>>> let badpass = mkPass "incorrect-password"
>>> checkPass badpass passHash
PassCheckFail

This should always fail if an incorrect password is given.

\(Blind badpass) -> let correctPassHash = hashPassWithSalt salt "foobar" in checkPass badpass correctPassHash == PassCheckFail

data PassCheck

The result of a checking a password against a hashed version. This is returned by checkPass.

Constructors

PassCheckSuccess

The password check was successful. The plain-text password matches the hashed password.

PassCheckFail

The password check failed. The plain-text password does not match the hashed password.

Instances

Eq PassCheck

Defined in Data.Password

Methods

(==) :: PassCheck -> PassCheck -> Bool

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

Read PassCheck

Defined in Data.Password

Methods

readsPrec :: Int -> ReadS PassCheck

readList :: ReadS [PassCheck]

readPrec :: ReadPrec PassCheck

readListPrec :: ReadPrec [PassCheck]

Show PassCheck

Defined in Data.Password

Methods

showsPrec :: Int -> PassCheck -> ShowS

show :: PassCheck -> String

showList :: [PassCheck] -> ShowS

Unsafe Debugging Functions for Showing a Password

unsafeShowPassword :: Pass -> String

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

>>> unsafeShowPasswordText $ mkPass "foobar"
"foobar"

You should generally not use this function.

unsafeShowPasswordText :: Pass -> Text

This is like unsafeShowPassword but produces a Text instead of a String.

Setup for doctests.

>>> :set -XOverloadedStrings

Import needed functions.

>>> import Data.Aeson (decode)
>>> import Database.Persist.Class (PersistField(toPersistValue))
>>> import Web.HttpApiData (parseUrlPiece)

Orphan instances

FromJSON Pass

This instance allows a Pass to be created from a JSON blob.

>>> let maybePass = decode "\"foobar\"" :: Maybe Pass
>>> fmap unsafeShowPassword maybePass
Just "foobar"

There is no instance for ToJSON for Pass because we don't want to accidentally encode a plain-text Pass to JSON and send it to the end-user.

Similarly, there is no ToJSON and FromJSON instance for PassHash because we don't want to accidentally send the password hash to the end user.

Methods

parseJSON :: Value -> Parser Pass

parseJSONList :: Value -> Parser [Pass]

FromHttpApiData Pass

This instance allows a Pass to be created with functions like parseUrlPiece or parseQueryParam.

>>> let eitherPass = parseUrlPiece "foobar"
>>> fmap unsafeShowPassword eitherPass
Right "foobar"

Methods

parseUrlPiece :: Text -> Either Text Pass

parseHeader :: ByteString -> Either Text Pass

parseQueryParam :: Text -> Either Text Pass

PersistFieldSql PassHash

This instance allows a PassHash to be stored as a field in an SQL database in Database.Persist.Sql.

Methods

sqlType :: Proxy PassHash -> SqlType

PersistField PassHash

This instance allows a PassHash to be stored as a field in a database using Database.Persist.

>>> let salt = Salt "abcdefghijklmnopqrstuvwxyz012345"
>>> let pass = mkPass "foobar"
>>> let hashedPassword = hashPassWithSalt salt pass
>>> toPersistValue hashedPassword
PersistText "14|8|1|YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU=|nENDaqWBmPKapAqQ3//H0iBImweGjoTqn5SvBS8Mc9FPFbzq6w65maYPZaO+SPamVZRXQjARQ8Y+5rhuDhjIhw=="

In the example above, the long PersistText will be the value you store in the database.

We don't provide an instance of PersistField for Pass, because we don't want to make it easy to store a plain-text password in the database.

Methods

toPersistValue :: PassHash -> PersistValue

fromPersistValue :: PersistValue -> Either Text PassHash