gzxcvbn

gzxcvbn - Password strength estimation for Gleam.

A Gleam port of zxcvbn, the password strength estimator developed by Dropbox.

Example

import gzxcvbn
import gzxcvbn/common
import gzxcvbn/en

let opts =
  gzxcvbn.options()
  |> gzxcvbn.with_dictionaries(common.dictionaries())
  |> gzxcvbn.with_dictionaries(en.dictionaries())
  |> gzxcvbn.with_graphs(common.graphs())
  |> gzxcvbn.build()

let result = gzxcvbn.check("correcthorsebatterystaple", opts)
// result.score == VeryUnguessable

Types

CheckResult

</>

Result of password strength estimation.

pub type CheckResult {
  CheckResult(
    password: String,
    score: Score,
    guesses: Int,
    guesses_log10: Float,
    feedback: Feedback,
    crack_times: CrackTimes,
    sequence: List(MatchWithGuesses),
  )
}

Constructors

```
CheckResult(
  password: String,
  score: Score,
  guesses: Int,
  guesses_log10: Float,
  feedback: Feedback,
  crack_times: CrackTimes,
  sequence: List(MatchWithGuesses),
)
```
Arguments

password

The analysed password

score

Overall strength score (0-4)

guesses

Estimated number of guesses needed

guesses_log10

Log base 10 of guesses

feedback

User-facing feedback for improvement

crack_times

Crack time estimates for different attack scenarios

sequence

The optimal match sequence found

CrackTimes

</>

Crack time estimates for different attack scenarios.

pub type CrackTimes {
  CrackTimes(
    online_throttled_seconds: Float,
    online_unthrottled_seconds: Float,
    offline_slow_seconds: Float,
    offline_fast_seconds: Float,
    online_throttled_display: String,
    online_unthrottled_display: String,
    offline_slow_display: String,
    offline_fast_display: String,
  )
}

Constructors

```
CrackTimes(
  online_throttled_seconds: Float,
  online_unthrottled_seconds: Float,
  offline_slow_seconds: Float,
  offline_fast_seconds: Float,
  online_throttled_display: String,
  online_unthrottled_display: String,
  offline_slow_display: String,
  offline_fast_display: String,
)
```
Arguments

online_throttled_seconds

Seconds to crack with online throttled attack (100/hour).

online_unthrottled_seconds

Seconds to crack with online unthrottled attack (10/second).

offline_slow_seconds

Seconds to crack with offline slow attack (10k/second).

offline_fast_seconds

Seconds to crack with offline fast attack (10B/second).

online_throttled_display

Human-readable time for online throttled attack.

online_unthrottled_display

Human-readable time for online unthrottled attack.

offline_slow_display

Human-readable time for offline slow attack.

offline_fast_display

Human-readable time for offline fast attack.

DictionaryKind

</>

What kind of data a dictionary contains.

pub type DictionaryKind {
  Passwords
  Names
  Words
  UserInput(UserInputKind)
}

Constructors

```
Passwords
```
Common passwords (triggers password-specific warnings)
```
Names
```
Personal names (first or last)
```
Words
```
Common words (generic dictionary)
```
UserInput(UserInputKind)
```
User-provided inputs with category

Feedback

</>

Feedback to help users create stronger passwords.

pub type Feedback {
  Feedback(warning: String, suggestions: List(String))
}

Constructors

Feedback(warning: String, suggestions: List(String))

L33tSubstitution

</>

A leetspeak character substitution.

pub type L33tSubstitution {
  L33tSubstitution(from: String, to: String)
}

Constructors

```
L33tSubstitution(from: String, to: String)
```
Arguments

from

The original character in the password (e.g. “@”)

to

The letter it represents (e.g. “a”)

Match

</>

A pattern match found in the password.

All variants have start and end fields representing 0-indexed, inclusive positions in the password string.

pub type Match {
  DictionaryMatch(
    start: Int,
    end: Int,
    token: String,
    rank: Int,
    dictionary_name: String,
    dictionary_kind: DictionaryKind,
    reversed: Bool,
    l33t: Bool,
    l33t_subs: List(L33tSubstitution),
  )
  SpatialMatch(
    start: Int,
    end: Int,
    token: String,
    graph: String,
    turns: Int,
    shifted_count: Int,
  )
  SequenceMatch(
    start: Int,
    end: Int,
    token: String,
    sequence_name: String,
    ascending: Bool,
  )
  RepeatMatch(
    start: Int,
    end: Int,
    token: String,
    base_token: String,
    repeat_count: Int,
    base_guesses: Int,
  )
  DateMatch(
    start: Int,
    end: Int,
    token: String,
    year: Int,
    month: Int,
    day: Int,
    has_separator: Bool,
  )
  BruteforceMatch(start: Int, end: Int, token: String)
}

Constructors

DictionaryMatch(
  start: Int,
  end: Int,
  token: String,
  rank: Int,
  dictionary_name: String,
  dictionary_kind: DictionaryKind,
  reversed: Bool,
  l33t: Bool,
  l33t_subs: List(L33tSubstitution),
)

Word from a ranked dictionary

SpatialMatch(
  start: Int,
  end: Int,
  token: String,
  graph: String,
  turns: Int,
  shifted_count: Int,
)

Keyboard pattern (qwerty, etc.)

SequenceMatch(
  start: Int,
  end: Int,
  token: String,
  sequence_name: String,
  ascending: Bool,
)

Sequential characters (abc, 123, zyx)

RepeatMatch(
  start: Int,
  end: Int,
  token: String,
  base_token: String,
  repeat_count: Int,
  base_guesses: Int,
)

Repeated characters or patterns (aaa, abcabc)

DateMatch(
  start: Int,
  end: Int,
  token: String,
  year: Int,
  month: Int,
  day: Int,
  has_separator: Bool,
)

Date pattern

BruteforceMatch(start: Int, end: Int, token: String)

Fallback for unmatched characters

MatchWithGuesses

</>

A match with its estimated guesses.

pub type MatchWithGuesses {
  MatchWithGuesses(
    match: Match,
    guesses: Int,
    guesses_log10: Float,
  )
}

Constructors

MatchWithGuesses(
  match: Match,
  guesses: Int,
  guesses_log10: Float,
)

NamedDictionary

</>

Named dictionary with its name and ranked words. The dictionary maps words to their frequency rank (1 = most common).

pub type NamedDictionary {
  NamedDictionary(
    name: String,
    kind: DictionaryKind,
    dictionary: dict.Dict(String, Int),
  )
}

Constructors

NamedDictionary(
  name: String,
  kind: DictionaryKind,
  dictionary: dict.Dict(String, Int),
)

NamedGraph

</>

Named adjacency graph with its name and graph data.

pub type NamedGraph {
  NamedGraph(
    name: String,
    graph: dict.Dict(String, List(option.Option(String))),
  )
}

Constructors

NamedGraph(
  name: String,
  graph: dict.Dict(String, List(option.Option(String))),
)

Options

opaque </>

Configuration options for the password checker.

pub opaque type Options

OptionsBuilder

opaque </>

Builder for constructing Options.

pub opaque type OptionsBuilder

Score

</>

Password strength score on a 0-4 scale.

pub type Score {
  TooGuessable
  VeryGuessable
  SomewhatGuessable
  SafelyUnguessable
  VeryUnguessable
}

Constructors

```
TooGuessable
```
Too guessable: risky password (guesses < 10^3)
```
VeryGuessable
```
Very guessable: protection from throttled online attacks (guesses < 10^6)
```
SomewhatGuessable
```
Somewhat guessable: protection from unthrottled online attacks (guesses < 10^8)
```
SafelyUnguessable
```
Safely unguessable: moderate protection from offline slow-hash scenarios (guesses < 10^10)
```
VeryUnguessable
```
Very unguessable: strong protection from offline slow-hash scenarios (guesses >= 10^10)

Suggestion

</>

Suggestion message keys for translation.

pub type Suggestion {
  UseMoreWords
  NoNeedForSymbolsOrDigits
  AddAnotherWord
  CapitalisationDoesntHelp
  AllUppercaseDoesntHelp
  ReversedDoesntHelp
  PredictableSubstitutions
  UseKeyboardPatternLonger
  AvoidRepeatedWords
  AvoidSequences
  AvoidRecentYears
  AvoidDates
  AvoidAssociatedYears
}

Constructors

```
UseMoreWords
```
```
NoNeedForSymbolsOrDigits
```
```
AddAnotherWord
```
```
CapitalisationDoesntHelp
```
```
AllUppercaseDoesntHelp
```
```
ReversedDoesntHelp
```
```
PredictableSubstitutions
```
```
UseKeyboardPatternLonger
```
```
AvoidRepeatedWords
```
```
AvoidSequences
```
```
AvoidRecentYears
```
```
AvoidDates
```
```
AvoidAssociatedYears
```
For user-provided years

Translations

</>

Translation functions for internationalising feedback messages.

pub type Translations {
  Translations(
    warning: fn(Warning) -> String,
    suggestion: fn(Suggestion) -> String,
  )
}

Constructors

Translations(
  warning: fn(Warning) -> String,
  suggestion: fn(Suggestion) -> String,
)

UserInputKind

</>

Category of user-provided input.

pub type UserInputKind {
  UserNames
  UserYears
  UserOther
}

Constructors

```
UserNames
```
User-related names (triggers name warnings)
```
UserYears
```
User-related years like birth year (triggers year warnings)
```
UserOther
```
Other user inputs (generic warning)

Warning

</>

Warning message keys for translation.

pub type Warning {
  NoWarning
  StraightRowOfKeys
  ShortKeyboardPatterns
  RepeatedCharacters
  RepeatedCharacterPatterns
  SequenceAbcEtc
  RecentYears
  Dates
  TopTenPassword
  TopHundredPassword
  CommonPassword
  SimilarToCommonPassword
  WordByItself
  CommonNamesByThemselves
  NamesByThemselves
  AssociatedYears
}

Constructors

```
NoWarning
```
```
StraightRowOfKeys
```
```
ShortKeyboardPatterns
```
```
RepeatedCharacters
```
```
RepeatedCharacterPatterns
```
```
SequenceAbcEtc
```
```
RecentYears
```
```
Dates
```
```
TopTenPassword
```
```
TopHundredPassword
```
```
CommonPassword
```
```
SimilarToCommonPassword
```
```
WordByItself
```
```
CommonNamesByThemselves
```
Names from a dictionary (e.g. first_names, last_names)
```
NamesByThemselves
```
User-provided names via with_user_names
```
AssociatedYears
```
User-provided years that are associated with the user

Values

build

</>

pub fn build(builder: OptionsBuilder) -> Options

Build the final Options from the builder.

check

</>

pub fn check(password: String, opts: Options) -> CheckResult

Check a password’s strength.

check_with_translations

</>

pub fn check_with_translations(
  password: String,
  opts: Options,
  translations: Translations,
) -> CheckResult

Check a password’s strength with custom translations.

default_translations

</>

pub fn default_translations() -> Translations

Default English translations.

match_length

</>

pub fn match_length(m: Match) -> Int

Get the length of a match.

options

</>

pub fn options() -> OptionsBuilder

Create a new options builder with default settings.

score_to_int

</>

pub fn score_to_int(score: Score) -> Int

Convert a score to its numeric value (0-4).

with_dictionaries

</>

pub fn with_dictionaries(
  builder: OptionsBuilder,
  dictionaries: List(NamedDictionary),
) -> OptionsBuilder

Add dictionaries to the options.

with_graphs

</>

pub fn with_graphs(
  builder: OptionsBuilder,
  graphs: List(NamedGraph),
) -> OptionsBuilder

Add keyboard graphs for spatial matching.

with_user_inputs

</>

pub fn with_user_inputs(
  builder: OptionsBuilder,
  inputs: List(String),
) -> OptionsBuilder

Add other user inputs to treat as dictionary words.

with_user_names

</>

pub fn with_user_names(
  builder: OptionsBuilder,
  names: List(String),
) -> OptionsBuilder

Add user-provided names (usernames, family names, etc.). Triggers name-specific warnings when matched.

with_user_years

</>

pub fn with_user_years(
  builder: OptionsBuilder,
  years: List(Int),
) -> OptionsBuilder

Add user-related years (birth year, anniversary, etc.). Triggers year-specific warnings when matched.

Example

Constructors

Arguments

Constructors

Arguments

Constructors

Constructors

Constructors

Arguments

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors