Data.Password.Validate

Password Validation

It is common for passwords to have a set of requirements. The most obvious requirement being a minimum length, but another common requirement is for the password to at least include a certain amount of characters of a certain category, like uppercase and lowercase alphabetic characters, numbers and/or other special characters. Though, nowadays, this last type of requirement is discouraged by security experts.

This module provides an API which enables you to set up your own PasswordPolicy to validate the format of Passwords.

Recommendations by the NIST

For policy recommendations and more, look to the following publication by the National Institute of Standards and Technology (especially the addendum): https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-63b.pdf

A short summary:

• Enforcing inclusion of specific character types (like special characters, numbers, lowercase and uppercase letters) actually makes passwords less secure.
• The length of a password is the most important factor, so let users make their passwords as lengthy as they want, within reason. (keep in mind some algorithms have length limitations, like bcrypt's 72 character limit)
• Do allow spaces so users can use sentences for passwords.
• Showing the "strength" of user's passwords is advised. A good algorithm to use is zxcvbn.
• The best way to mitigate online attacks is to limit the rate of login attempts.

Password Policies

The most important part is to have a valid and robust PasswordPolicy.

A defaultPasswordPolicy_ is provided to quickly set up a NIST recommended validation of passwords, but you can also adjust it, or just create your own.

Just remember that a PasswordPolicy must be validated first to make sure it is actually a ValidPasswordPolicy. Otherwise, you'd never be able to validate any given Passwords.

Example usage

So let's say we're fine with the default policy, which requires the password to be between 8-64 characters, and doesn't enforce any specific character category usage, then our function would look like the following:

myValidateFunc :: Password -> Bool
myValidateFunc = isValidPassword defaultPasswordPolicy_

Custom policies

But, for example, if you'd like to enforce that a Password includes at least one special character, and be at least 12 characters long, you'll have to make your own PasswordPolicy.

customPolicy :: PasswordPolicy
customPolicy =
  defaultPasswordPolicy
    { minimumLength = 12
    , specialChars = 1
    }

This custom policy will then have to be validated first, so it can be used to validate Passwords further on.

Template Haskell

The easiest way to validate a custom PasswordPolicy is by using a Template Haskell splice. Just turn on the {-# LANGUAGE TemplateHaskell #-} pragma, pass your policy to validatePasswordPolicyTH, surround it by $(...) and if it compiles it will be a ValidPasswordPolicy.

{-# LANGUAGE TemplateHaskell #-}
customValidPolicy :: ValidPasswordPolicy
customValidPolicy = $(validatePasswordPolicyTH customPolicy)

NB: any custom CharSetPredicate will be ignored by validatePasswordPolicyTH and replaced with the defaultCharSetPredicate. So if you want to use your own CharSetPredicate, you won't be able to validate your policy using validatePasswordPolicyTH. Most users, however, will find defaultCharSetPredicate to be sufficient.

At runtime

Another way of validating your custom policy is validatePasswordPolicy. In an application, this might be implemented in the following way.

main :: IO ()
main =
    case (validatePasswordPolicy customPolicy) of
      Left reasons -> error $ show reasons
      Right validPolicy -> app `runReaderT` validPolicy

customValidateFunc :: Password -> ReaderT ValidPasswordPolicy IO Bool
customValidateFunc pwd = do
    policy <- ask
    return $ isValidPassword policy pwd

Let's get dangerous

Or, if you like living on the edge, you could also just match on Right. I hope you're certain your policy is valid, though. So please have at least a unit test to verify that passing your PasswordPolicy to validatePasswordPolicy actually returns a Right.

Right validPolicy = validatePasswordPolicy customPolicy

customValidateFunc :: Password -> Bool
customValidateFunc = isValidPassword validPolicy

Validating passwords

The main function of this module is probably isValidPassword, as it is simple and straightforward.

Though if you'd want to know why a Password failed to validate, because you'd maybe like to communicate those InvalidReasons back to the user, validatePassword is here to help you out.

validatePassword :: ValidPasswordPolicy -> Password -> ValidationResult

Checks if a given Password adheres to the provided ValidPasswordPolicy.

In case of an invalid password, returns the reasons why it wasn't valid.

>>> let pass = mkPassword "This_Is_Valid_Password1234"
>>> validatePassword defaultPasswordPolicy_ pass
ValidPassword

Since: 2.1.0.0

isValidPassword :: ValidPasswordPolicy -> Password -> Bool

This function is equivalent to:

validatePassword policy password == ValidPassword

>>> let pass = mkPassword "This_Is_Valid_PassWord1234"
>>> isValidPassword defaultPasswordPolicy_ pass
True

Since: 2.1.0.0

data ValidationResult

Result of validating a Password.

Since: 2.1.0.0

Constructors

ValidPassword

InvalidPassword [InvalidReason]

Instances

Show ValidationResult

Defined in Data.Password.Validate

Methods

showsPrec :: Int -> ValidationResult -> ShowS

show :: ValidationResult -> String

showList :: [ValidationResult] -> ShowS

Eq ValidationResult

Defined in Data.Password.Validate

Methods

(==) :: ValidationResult -> ValidationResult -> Bool

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

Password Policy

A PasswordPolicy has to be validated before it can be used to validate a Password. This is done using validatePasswordPolicy or validatePasswordPolicyTH.

Next to the obvious lower and upper bounds for the length of a Password, a PasswordPolicy can dictate how many lowercase letters, uppercase letters, digits and/or special characters are minimally required to be used in the Password to be considered a valid Password.

An observant user might have also seen that a PasswordPolicy includes a CharSetPredicate. Very few users will want to change this from the defaultCharSetPredicate, since this includes all non-control ASCII characters.

If, for some reason, you'd like to accept more characters (e.g. é, ø, か, 事) or maybe you want to only allow alpha-numeric characters, charSetPredicate is the place to do so.

validatePasswordPolicy :: PasswordPolicy -> Either [InvalidPolicyReason] ValidPasswordPolicy

Verifies that a PasswordPolicy is valid and converts it into a ValidPasswordPolicy.

>>> validatePasswordPolicy defaultPasswordPolicy
Right (...)

Since: 2.1.0.0

validatePasswordPolicyTH :: PasswordPolicy -> Q Exp

Template Haskell validation function for PasswordPolicys.

{-# LANGUAGE TemplateHaskell #-}
myPolicy :: PasswordPolicy
myPolicy = defaultPasswordPolicy{ specialChars = 1 }

myValidPolicy :: ValidPasswordPolicy
myValidPolicy = $(validatePasswordPolicyTH myPolicy)

For technical reasons, the charSetPredicate field is ignored and the defaultCharSetPredicate is used. If, for any reason, you do need to use a custom CharSetPredicate, please use validatePasswordPolicy and either handle the failure case at runtime and/or use a unit test to make sure your policy is valid.

Since: 2.1.0.0

data PasswordPolicy

Set of policies used to validate a Password.

When defining your own PasswordPolicy, please keep in mind that:

• The value of maximumLength must be bigger than 0
• The value of maximumLength must be bigger than minimumLength
• If any other field has a negative value (e.g. lowercaseChars), it will be defaulted to 0
• The total sum of all character category values (i.e. all fields ending in -Chars) must not be larger than the value of maximumLength.
• The provided CharSetPredicate needs to allow at least one of the characters in the categories which require more than 0 characters. (e.g. if lowercaseChars is > 0, the charSetPredicate must allow at least one of the characters in ['a'..'z'])

or else the validation functions will return one or more InvalidPolicyReasons.

If you're unsure of what to do, please use the default: defaultPasswordPolicy_

Since: 2.1.0.0

Constructors

PasswordPolicy

Fields

• minimumLength :: !Int

  Required password minimum length

• maximumLength :: !Int

  Required password maximum length

• uppercaseChars :: !Int

  Required number of upper-case characters

• lowercaseChars :: !Int

  Required number of lower-case characters

• specialChars :: !Int

  Required number of special characters

• digitChars :: !Int

  Required number of ASCII-digit characters

• charSetPredicate :: CharSetPredicate

  Which characters are acceptable for use in passwords (cf. defaultCharSetPredicate)

Instances

Show PasswordPolicy

Defined in Data.Password.Validate

Methods

showsPrec :: Int -> PasswordPolicy -> ShowS

show :: PasswordPolicy -> String

showList :: [PasswordPolicy] -> ShowS

Eq PasswordPolicy

N.B. This will not check equality on the charSetPredicate

Defined in Data.Password.Validate

Methods

(==) :: PasswordPolicy -> PasswordPolicy -> Bool

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

Ord PasswordPolicy

N.B. This will not check order on the charSetPredicate

Defined in Data.Password.Validate

Methods

compare :: PasswordPolicy -> PasswordPolicy -> Ordering

(<) :: PasswordPolicy -> PasswordPolicy -> Bool

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

(>) :: PasswordPolicy -> PasswordPolicy -> Bool

(>=) :: PasswordPolicy -> PasswordPolicy -> Bool

max :: PasswordPolicy -> PasswordPolicy -> PasswordPolicy

min :: PasswordPolicy -> PasswordPolicy -> PasswordPolicy

data ValidPasswordPolicy

A PasswordPolicy that has been checked to be valid

Since: 2.1.0.0

Instances

Show ValidPasswordPolicy

Defined in Data.Password.Validate

Methods

showsPrec :: Int -> ValidPasswordPolicy -> ShowS

show :: ValidPasswordPolicy -> String

showList :: [ValidPasswordPolicy] -> ShowS

Eq ValidPasswordPolicy

Defined in Data.Password.Validate

Methods

(==) :: ValidPasswordPolicy -> ValidPasswordPolicy -> Bool

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

Ord ValidPasswordPolicy

Defined in Data.Password.Validate

Methods

compare :: ValidPasswordPolicy -> ValidPasswordPolicy -> Ordering

(<) :: ValidPasswordPolicy -> ValidPasswordPolicy -> Bool

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

(>) :: ValidPasswordPolicy -> ValidPasswordPolicy -> Bool

(>=) :: ValidPasswordPolicy -> ValidPasswordPolicy -> Bool

max :: ValidPasswordPolicy -> ValidPasswordPolicy -> ValidPasswordPolicy

min :: ValidPasswordPolicy -> ValidPasswordPolicy -> ValidPasswordPolicy

fromValidPasswordPolicy :: ValidPasswordPolicy -> PasswordPolicy

In case you'd want to retrieve the PasswordPolicy from the ValidPasswordPolicy

Since: 2.1.0.0

defaultPasswordPolicy :: PasswordPolicy

Default value for the PasswordPolicy.

Enforces that a password must be between 8-64 characters long, though can easily be adjusted by using record update syntax:

myPolicy = defaultPasswordPolicy{ minimumLength = 12 }

Do note that this being a default policy doesn't make it a good enough policy in every situation. The most important field, minimumLength, has 8 characters as the default, because it is the bare minimum for some sense of security. The longer the password, the more difficult it will be to guess or brute-force, so a minimum of 12 or 16 would be advised in a production setting.

This policy on it's own is guaranteed to be valid. Any changes made to it might result in validatePasswordPolicy returning one or more InvalidPolicyReasons.

>>> defaultPasswordPolicy
PasswordPolicy {minimumLength = 8, maximumLength = 64, uppercaseChars = 0, lowercaseChars = 0, specialChars = 0, digitChars = 0, charSetPredicate = <FUNCTION>}

Since: 2.1.0.0

defaultPasswordPolicy_ :: ValidPasswordPolicy

Unchangeable defaultPasswordPolicy, but guaranteed to be valid.

Since: 2.1.0.0

newtype CharSetPredicate

Predicate which defines the characters that can be used for a password.

Since: 2.1.0.0

Constructors

CharSetPredicate

Fields

• getCharSetPredicate :: Char -> Bool

defaultCharSetPredicate :: CharSetPredicate

The default character set consists of uppercase and lowercase letters, numbers, and special characters from the ASCII character set. (i.e. everything from the ASCII set except the control characters)

Since: 2.1.0.0

data InvalidReason

Possible reasons for a Password to be invalid.

Since: 2.1.0.0

Constructors

PasswordTooShort !MinimumLength !ProvidedLength

Length of Password is too short.

PasswordTooLong !MaximumLength !ProvidedLength

Length of Password is too long.

NotEnoughReqChars !CharacterCategory !MinimumAmount !ProvidedAmount

Password does not contain required number of characters.

InvalidCharacters !Text

Password contains characters that cannot be used

Instances

Show InvalidReason

Defined in Data.Password.Validate

Methods

showsPrec :: Int -> InvalidReason -> ShowS

show :: InvalidReason -> String

showList :: [InvalidReason] -> ShowS

Eq InvalidReason

Defined in Data.Password.Validate

Methods

(==) :: InvalidReason -> InvalidReason -> Bool

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

Ord InvalidReason

Defined in Data.Password.Validate

Methods

compare :: InvalidReason -> InvalidReason -> Ordering

(<) :: InvalidReason -> InvalidReason -> Bool

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

(>) :: InvalidReason -> InvalidReason -> Bool

(>=) :: InvalidReason -> InvalidReason -> Bool

max :: InvalidReason -> InvalidReason -> InvalidReason

min :: InvalidReason -> InvalidReason -> InvalidReason

data InvalidPolicyReason

Possible reasons for a PasswordPolicy to be invalid

Since: 2.1.0.0

Constructors

InvalidLength !MinimumLength !MaximumLength

Value of minimumLength is bigger than maximumLength

InvalidLength minimumLength maximumLength

MaxLengthBelowZero !MaximumLength

Value of maximumLength is zero or less

MaxLengthBelowZero maximumLength

CategoryAmountsAboveMaxLength !MaximumLength !Int

The total of the character category amount requirements are higher than the maximum length of the password. (i.e. the Int signifies the total of lowercaseChars + uppercaseChars + digitChars + specialChars)

CategoryAmountsAboveMaxLength maximumLength totalRequiredChars

InvalidCharSetPredicate !CharacterCategory !MinimumAmount

charSetPredicate does not return True for a CharacterCategory that requires at least MinimumAmount characters in the password

Instances

Show InvalidPolicyReason

Defined in Data.Password.Validate

Methods

showsPrec :: Int -> InvalidPolicyReason -> ShowS

show :: InvalidPolicyReason -> String

showList :: [InvalidPolicyReason] -> ShowS

Eq InvalidPolicyReason

Defined in Data.Password.Validate

Methods

(==) :: InvalidPolicyReason -> InvalidPolicyReason -> Bool

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

Ord InvalidPolicyReason

Defined in Data.Password.Validate

Methods

compare :: InvalidPolicyReason -> InvalidPolicyReason -> Ordering

(<) :: InvalidPolicyReason -> InvalidPolicyReason -> Bool

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

(>) :: InvalidPolicyReason -> InvalidPolicyReason -> Bool

(>=) :: InvalidPolicyReason -> InvalidPolicyReason -> Bool

max :: InvalidPolicyReason -> InvalidPolicyReason -> InvalidPolicyReason

min :: InvalidPolicyReason -> InvalidPolicyReason -> InvalidPolicyReason

data CharacterCategory

Character categories

Since: 2.1.0.0

Constructors

Uppercase

Uppercase letters

Lowercase

Lowercase letters

Special

Special characters

Digit

ASCII digits

Instances

Show CharacterCategory

Defined in Data.Password.Validate

Methods

showsPrec :: Int -> CharacterCategory -> ShowS

show :: CharacterCategory -> String

showList :: [CharacterCategory] -> ShowS

Eq CharacterCategory

Defined in Data.Password.Validate

Methods

(==) :: CharacterCategory -> CharacterCategory -> Bool

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

Ord CharacterCategory

Defined in Data.Password.Validate

Methods

compare :: CharacterCategory -> CharacterCategory -> Ordering

(<) :: CharacterCategory -> CharacterCategory -> Bool

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

(>) :: CharacterCategory -> CharacterCategory -> Bool

(>=) :: CharacterCategory -> CharacterCategory -> Bool

max :: CharacterCategory -> CharacterCategory -> CharacterCategory

min :: CharacterCategory -> CharacterCategory -> CharacterCategory

type MinimumLength = Int

type MaximumLength = Int

type ProvidedLength = Int

type MinimumAmount = Int

type ProvidedAmount = Int

For internal use

These are used in the test suite. You should not need these.

These are basically internal functions and as such have NO guarantee (NONE) to be consistent between releases.

defaultCharSet :: String

Default character set

Should be all non-control characters in the ASCII character set.

validateCharSetPredicate :: PasswordPolicy -> [InvalidPolicyReason]

Validate CharSetPredicate to return True on at least one of the characters that is required.

For instance, if PasswordPolicy states that the password requires at least one uppercase letter, then CharSetPredicate should return True on at least one uppercase letter.

categoryToPredicate :: CharacterCategory -> Char -> Bool

Convert a CharacterCategory into its associated predicate function

isSpecial :: Char -> Bool

Check if given Char is a special character. (i.e. any non-alphanumeric non-control ASCII character)

allButCSP :: PasswordPolicy -> [Int]

All Int fields of the PasswordPolicy in a row