zxcvbn-hs: Password strength estimation based on zxcvbn.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

Please see the README below.


[Skip to Readme]

Properties

Versions 0.2.0.0, 0.2.0.0, 0.2.1.0, 0.3.0.0, 0.3.1, 0.3.2, 0.3.3, 0.3.4, 0.3.5, 0.3.6
Change log CHANGELOG.md
Dependencies attoparsec (>=0.13 && <0.14), base (>=4.9 && <5.0), base64-bytestring (>=1.0 && <1.1), binary (>=0.8 && <0.11), binary-instances (>=0.1 && <1.0), containers (>=0.6 && <0.7), fgl (>=5.7 && <5.8), filepath (>=1.4 && <1.5), lens (>=4.17 && <4.18), math-functions (>=0.3 && <0.4), mtl (>=2.2 && <2.3), optparse-applicative (>=0.14 && <0.15), pipes (>=4.3 && <4.4), pipes-safe (>=2.3 && <2.4), pipes-text (>=0.0 && <0.1), text (>=1.2 && <1.3), time (>=1.8 && <2.0), unordered-containers (>=0.2 && <0.3), vector (>=0.12 && <0.13), zlib (>=0.6 && <0.7), zxcvbn-hs [details]
License MIT
Copyright Copyright (c) 2019 Peter Jones
Author Peter Jones <pjones@devalot.com>
Maintainer Peter Jones <pjones@devalot.com>
Category System
Home page https://code.devalot.com/sthenauth/zxcvbn-hs
Bug tracker https://github.com/sthenauth/zxcvbn-hs/issues
Source repo head: git clone https://code.devalot.com/sthenauth/zxcvbn-hs.git
Uploaded by PeterJones at 2019-09-12T18:50:48Z

Modules

[Index] [Quick Jump]

Flags

Manual Flags

NameDescriptionDefault
tools

Build the data processing tools (i.e. dictionary compilers)

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for zxcvbn-hs-0.2.0.0

[back to package description]

What?

This is a native Haskell implementation of the zxcvbn password strength estimation algorithm as it appears in the 2016 USENIX Security paper and presentation (with some small modifications).

Why?

The zxcvbn algorithm is a major improvement over traditional password strength estimators. Instead of counting the occurrence of special characters, mixed case characters, numeric digits, etc., zxcvbn analyzes a plain text password and estimates the number of guesses that an attacker would need to make in order to crack it.

How?

A plain text password is broken into a list of substrings called tokens and each token is analyzed as follows:

Each possible interpretation of a token is given an estimated number of guesses and then the entire password is scored based on the weakest path.

Usage

A complete example can be found in the example/Main.hs file. That said, it's pretty easy to use:

import Text.Password.Strength (score, strength, en_US)
import Data.Time.Clock (getCurrentTime, utctDay)

main = do
  -- The date matcher needs to know the current year.
  refDay <- utctDay <$> getCurrentTime

  let password = "password1234567"
      guesses  = score en_US refDay password

  print guesses -- Number of estimated guesses (18)
  print (strength guesses) -- Sum type describing the password strength (Risky)

Demo App

If you want to play with an interactive demo take a look at the zxcvbn-ws repository.

Customization

You'll most likely want to add custom words to the frequency dictionaries. For example, the name of your application, your domain name, and any personal information you have on the customer. Doing so will penalize the score of a password using such information.

The Text.Password.Strength.Config module defines the addCustomFrequencyList function which can be used to easily add words to the frequency dictionary.

Localization

Unlike other implementations of the zxcvbn algorithm, this version fully supports localization. It's easy to augment or completely replace the frequency dictionaries and keyboard layouts. Tools are provided to compile simple text files into the data types required by this library.

However, like the other implementations, the default configuration is heavily biased towards United States English, hence its name: en_US.

Included in the default configuration are:

Existing Localization Packages

Performance

It takes approximately 1.5 ms to process a 30-character password. Performance degrades as the length of the password increases (e.g., a 60-character password clocks in at 13.54 ms).

You probably want to limit the number of characters you send through the score function using something like Text.take 100 in order to prevent a malicious user from slowing down your application.

Most of the time is currently spent in decoding and testing l33t speak. If you want to work on improving the performance I suggestion you generate a profile using the benchmark tool.