6abcf20f |
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 |
f387fcb1 |
132 | Mark Wooding, <mdw@distorted.org.uk>. |