progs/perftest.c: Use from Glibc syscall numbers.

[catacomb] / progs / mkphrase.1

.\" -*-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 [ \-Ap ]
.RB [ \-b
.IR bits ]
.RB [ \-g
.IR generator ]
.br
\h'8n'
.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 (unless the
.B \-A
option is set); other funny characters are dropped.
.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 "\-A, \-\-no-apostrophe"
Don't treat apostrophe as a word character.
.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>.