git.distorted.org.uk Git - u/mdw/catacomb/blob - mkphrase.1

   1 .\" -*-nroff-*-
   2 .ie t \{\
   3 .  if \n(.g \{\
   4 .    fam P
   5 .  \}
   6 .  ds ss \s8\u
   7 .  ds se \d\s0
   8 .  ds us \s8\d
   9 .  ds ue \u\s0
  10 .  ds *b \(*b
  11 .\}
  12 .el \{\
  13 .  ds ss ^
  14 .  ds se
  15 .  ds us _
  16 .  ds ue
  17 .  ds *b \fIbeta\fP
  18 .\}
  19 .de VS
  20 .sp 1
  21 .RS
  22 .nf
  23 .ft B
  24 ..
  25 .de VE
  26 .ft R
  27 .fi
  28 .RE
  29 .sp 1
  30 ..
  31 .TH mkphrase 1 "9 June 2005" "Straylight/Edgeware" "Catacomb cryptographic library"
  32 .SH NAME
  33 mkphrase \- generate passphrases with guaranteed minimum entropy
  34 .SH SYNOPSIS
  35 .B mkphrase
  36 .RB [ \-p ]
  37 .RB [ \-b
  38 .IR bits ]
  39 .RB [ \-g
  40 .IR generator ]
  41 .br
  42
  43 .RB [ \-n
  44 .IR count ]
  45 .RB [ \-r
  46 .RI [ min\fB\- ] max ]
  47 .IR wordlist ...
  48 .SH DESCRIPTION
  49 The
  50 .B mkphrase
  51 program generates pronounceable but random passphrases in such a way
  52 that they're guaranteed to have at least a given level of entropy.
  53 .PP
  54 The program generates phrases using a wordlist.  Usually this will be
  55 something like
  56 .BR /usr/share/dict/words ,
  57 though you can use anything you want.  Wordlist files are expected to
  58 contain whitespace-separated words.  Letters are smashed to lowercase;
  59 apostrophes are retained; other funny characters are ignored.
  60 .PP
  61 Options provided are:
  62 .TP
  63 .B "\-h, \-\-help"
  64 Write a help summary for
  65 .B mkphrase
  66 to standard output and exit.
  67 .TP
  68 .B "\-v, \-\-version"
  69 Write
  70 .BR mkphrase 's
  71 version information to standard output and exit.
  72 .TP
  73 .B "\-u, \-\-usage"
  74 Write a really brief usage summary for
  75 .B mkphrase
  76 to standard output and exit.
  77 .TP
  78 .BI "\-b, \-\-bits=" bits
  79 Set the minimum entropy for acceptable phrases.  The default is 128
  80 bits.  This might increase in future.
  81 .TP
  82 .BI "\-g, \-\-generator=" generator
  83 Use the given
  84 .I generator
  85 to construct passphrases.  See below.  The default generator is
  86 .BR markov .
  87 .TP
  88 .BI "\-n, \-\-count=" count
  89 Produce
  90 .I count
  91 phrases.  The default is to produce only one.
  92 .TP
  93 .B "\-p, \-\-probability"
  94 After each phrase, write the entropy of the passphrase, in bits.
  95 .TP
  96 .BR "\-r, \-\-range=" [\fImin - ]\fImax
  97 Set a range for acceptable word lengths.  The default is to allow
  98 (almost) arbitrary length words, though these can be hard to remember.
  99 .PP
 100 The following phrase generators are implemented.
 101 .TP
 102 .B markov
 103 Builds a Markov model of the words in the wordlist(s).  It then uses
 104 this to produce new `words' with similar statistical properties.
 105 They're usually pronounceable and often absurdly memorable.
 106 .IP
 107 Here's how it actually works.  The program builds a big table which
 108 remembers how often each given letter occurs given the three preceding
 109 letters.  There is a special placeholder letter for `before-the-start',
 110 and another for `end-of-word'.  On output, we remember the last three
 111 letters emitted as our `state': then we choose a letter to emit at
 112 random, with the probability for each choice determined by how often it
 113 turned up following the letters in the state in the wordlists.  The new
 114 letter is then shifted into the state and we try again, until we choose
 115 the end-of-word letter.  The initial state is three before-the-start
 116 placeholder `letters'.
 117 .IP
 118 The word length limits are imposed by filtering the output of the Markov
 119 word generator.  Strict limits make the program run slowly.  The
 120 generator tracks the probability it had of making each choice of letter
 121 as it goes, and we just produce words until the phrase is sufficiently
 122 entropic.
 123 .TP
 124 .B wordlist
 125 Very simple: just choose random words from the wordlist until the phrase
 126 has enough entropy.  Phrases are usually longer than Markov-generated
 127 ones.
 128 .SH BUGS
 129 Three letters work fairly well for English.  However, they may not work
 130 so well for other languages.
 131 .SH AUTHOR
 132 Mark Wooding, <mdw@distorted.org.uk>.