.\" -*-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, .