X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ba6e6b64033b1f9de49feccb5c9cd438354481f7..0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a:/progs/mkphrase.1

diff --git a/progs/mkphrase.1 b/progs/mkphrase.1
new file mode 100644
index 0000000..dd4fd56
--- /dev/null
+++ b/progs/mkphrase.1
@@ -0,0 +1,132 @@
+.\" -*-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>.