+++ /dev/null
-.\" -*-nroff-*-
-.ie t \{\
-. if \n(.g \{\
-. fam P
-. \}
-. ds ss \s8\u
-. ds se \d\s0
-. ds us \s8\d
-. ds ue \u\s0
-. ds *b \(*b
-.\}
-.el \{\
-. ds ss ^
-. ds se
-. ds us _
-. ds ue
-. ds *b \fIbeta\fP
-.\}
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.TH mkphrase 1 "9 June 2005" "Straylight/Edgeware" "Catacomb cryptographic library"
-.SH NAME
-mkphrase \- generate passphrases with guaranteed minimum entropy
-.SH SYNOPSIS
-.B mkphrase
-.RB [ \-p ]
-.RB [ \-b
-.IR bits ]
-.RB [ \-g
-.IR generator ]
-.br
-
-.RB [ \-n
-.IR count ]
-.RB [ \-r
-.RI [ min\fB\- ] max ]
-.IR wordlist ...
-.SH DESCRIPTION
-The
-.B mkphrase
-program generates pronounceable but random passphrases in such a way
-that they're guaranteed to have at least a given level of entropy.
-.PP
-The program generates phrases using a wordlist. Usually this will be
-something like
-.BR /usr/share/dict/words ,
-though you can use anything you want. Wordlist files are expected to
-contain whitespace-separated words. Letters are smashed to lowercase;
-apostrophes are retained; other funny characters are ignored.
-.PP
-Options provided are:
-.TP
-.B "\-h, \-\-help"
-Write a help summary for
-.B mkphrase
-to standard output and exit.
-.TP
-.B "\-v, \-\-version"
-Write
-.BR mkphrase 's
-version information to standard output and exit.
-.TP
-.B "\-u, \-\-usage"
-Write a really brief usage summary for
-.B mkphrase
-to standard output and exit.
-.TP
-.BI "\-b, \-\-bits=" bits
-Set the minimum entropy for acceptable phrases. The default is 128
-bits. This might increase in future.
-.TP
-.BI "\-g, \-\-generator=" generator
-Use the given
-.I generator
-to construct passphrases. See below. The default generator is
-.BR markov .
-.TP
-.BI "\-n, \-\-count=" count
-Produce
-.I count
-phrases. The default is to produce only one.
-.TP
-.B "\-p, \-\-probability"
-After each phrase, write the entropy of the passphrase, in bits.
-.TP
-.BR "\-r, \-\-range=" [\fImin - ]\fImax
-Set a range for acceptable word lengths. The default is to allow
-(almost) arbitrary length words, though these can be hard to remember.
-.PP
-The following phrase generators are implemented.
-.TP
-.B markov
-Builds a Markov model of the words in the wordlist(s). It then uses
-this to produce new `words' with similar statistical properties.
-They're usually pronounceable and often absurdly memorable.
-.IP
-Here's how it actually works. The program builds a big table which
-remembers how often each given letter occurs given the three preceding
-letters. There is a special placeholder letter for `before-the-start',
-and another for `end-of-word'. On output, we remember the last three
-letters emitted as our `state': then we choose a letter to emit at
-random, with the probability for each choice determined by how often it
-turned up following the letters in the state in the wordlists. The new
-letter is then shifted into the state and we try again, until we choose
-the end-of-word letter. The initial state is three before-the-start
-placeholder `letters'.
-.IP
-The word length limits are imposed by filtering the output of the Markov
-word generator. Strict limits make the program run slowly. The
-generator tracks the probability it had of making each choice of letter
-as it goes, and we just produce words until the phrase is sufficiently
-entropic.
-.TP
-.B wordlist
-Very simple: just choose random words from the wordlist until the phrase
-has enough entropy. Phrases are usually longer than Markov-generated
-ones.
-.SH BUGS
-Three letters work fairly well for English. However, they may not work
-so well for other languages.
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>.