Struct chbs::word::WordList

pub struct WordList { /* private fields */ }

A wordlist.

To load a built-in wordlist, checkout the methods on this struct prefixed with builtin_.
The default wordlist loaded when using default() uses builtin_eff_large().

A loaded fixed wordlist which may be used as word provider for passphrase generation by constructing a sampler using sampler.

It is highly recommended that the worlist contains at least 7776 (6⁵) words to provide enough entropy when uniformly sampling words from it.

Implementations

impl WordList

pub fn new(words: Vec<String>) -> Self

Construct a new word list with the given words.

To load a wordlist from a file, use load instead.
To load a built-in wordlist, use the methods on this struct prefixed with builtin_.

Panics

This panics if the given set of words is empty.

pub fn load<P>(path: P) -> Result<Self, WordListError> where
    P: AsRef<Path>, 

Load a wordlist from a file.

This loads a wordlist from a file at the given path, and constructs a WordList.

• Words are splitted by any whitespace (including newlines), see char::is_whitespace
• It assumes any non-whitespace character is part of a word
• Whitespaces are omitted the final wordlist
• Emtpy items are omitted
• The file must not include dice numbers

For wordlists that include dice numbers, the load_diced method may be used instead.
If words are separated in a different manner, manually load each word and use the new constructor instead.

An error is returned if loading the wordlist failed, or if the loaded file didn’t contain any words.

File examples

abacus abdomen abdominal abide abiding

or

abacus
abdomen

pub fn load_diced<P>(path: P) -> Result<Self, WordListError> where
    P: AsRef<Path>, 

Load a diced wordlist from a file.

This loads a diced wordlist from a file at the given path, and constructs a WordList. Many diceware wordlists include dice numbers for each word, these should be omitted when using this crate. This method helps with that.

• Words are splitted by the newline character (\n).
• Only the last word on each line is kept, terminated by any whitespace, see char::is_whitespace
• It assumes any non-whitespace character is part of a word
• Prefixed words do not have to be dice numbers
• Lines having a single word with no dice number prefix are included
• Emtpy lines are omitted

For wordlists that do not include dice numbers, the the regular load method instead.
If words are separated in a different manner, manually load each word and use the new constructor instead.

An error is returned if loading the wordlist failed, or if the loaded file didn’t contain any words.

File examples

11111 abacus
11112 abdomen
11113 abdominal

or

#1 (1,1,1,1,2)    abacus
#2 (1,1,1,1,2)    abdomen

pub fn builtin_eff_large() -> Self

Construct wordlist from built-in EFF large.

Use the built-in EFF large list of words, and construct a wordlist from it. This is based on BUILTIN_EFF_LARGE.

pub fn builtin_eff_short() -> Self

Construct wordlist from built-in EFF short.

Use the built-in EFF short list of words, and construct a wordlist from it. This is based on BUILTIN_EFF_SHORT.

Note: this wordlist is considered short, as it only contains 1296 (6⁴) words. The list has an entropy of about 10.3 bits when uniformly sampling words from it.
It is recommended to use a larger wordlist such as builtin_eff_large.

pub fn builtin_eff_general_short() -> Self

Construct wordlist from built-in EFF general short.

Use the built-in EFF general short list of words, and construct a wordlist from it. This is based on BUILTIN_EFF_GENERAL_SHORT.

Note: this wordlist is considered short, as it only contains 1296 (6⁴) words. The list has an entropy of about 10.3 bits when uniformly sampling words from it.
It is recommended to use a larger wordlist such as builtin_eff_large.

pub fn sampler(&self) -> WordSampler

Build a sampler for this wordlist.

The word sampler may be used to pull any number of random words from the wordlist for passphrase generation.

Trait Implementations

impl Clone for WordList

fn clone(&self) -> WordList

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WordList

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for WordList

fn default() -> WordList

Construct a default wordlist.

This uses the built-in EFF large wordlist, which can be constructed with WordList::builtin_eff_large().