Commit | Line | Data |
---|---|---|
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 | |
352783dd | 36 | .RB [ \-Ap ] |
6abcf20f | 37 | .RB [ \-b |
38 | .IR bits ] | |
39 | .RB [ \-g | |
40 | .IR generator ] | |
41 | .br | |
e51127d5 | 42 | \h'8n' |
6abcf20f | 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; | |
352783dd MW |
59 | apostrophes are retained (unless the |
60 | .B \-A | |
61 | option is set); other funny characters are dropped. | |
6abcf20f | 62 | .PP |
63 | Options provided are: | |
64 | .TP | |
65 | .B "\-h, \-\-help" | |
66 | Write a help summary for | |
67 | .B mkphrase | |
68 | to standard output and exit. | |
69 | .TP | |
70 | .B "\-v, \-\-version" | |
45c0fd36 | 71 | Write |
6abcf20f | 72 | .BR mkphrase 's |
73 | version information to standard output and exit. | |
74 | .TP | |
75 | .B "\-u, \-\-usage" | |
76 | Write a really brief usage summary for | |
77 | .B mkphrase | |
78 | to standard output and exit. | |
79 | .TP | |
352783dd MW |
80 | .BI "\-A, \-\-no-apostrophe" |
81 | Don't treat apostrophe as a word character. | |
82 | .TP | |
6abcf20f | 83 | .BI "\-b, \-\-bits=" bits |
84 | Set the minimum entropy for acceptable phrases. The default is 128 | |
85 | bits. This might increase in future. | |
86 | .TP | |
87 | .BI "\-g, \-\-generator=" generator | |
88 | Use the given | |
89 | .I generator | |
90 | to construct passphrases. See below. The default generator is | |
91 | .BR markov . | |
92 | .TP | |
93 | .BI "\-n, \-\-count=" count | |
45c0fd36 | 94 | Produce |
6abcf20f | 95 | .I count |
96 | phrases. The default is to produce only one. | |
97 | .TP | |
98 | .B "\-p, \-\-probability" | |
99 | After each phrase, write the entropy of the passphrase, in bits. | |
100 | .TP | |
101 | .BR "\-r, \-\-range=" [\fImin - ]\fImax | |
102 | Set a range for acceptable word lengths. The default is to allow | |
103 | (almost) arbitrary length words, though these can be hard to remember. | |
104 | .PP | |
105 | The following phrase generators are implemented. | |
106 | .TP | |
107 | .B markov | |
108 | Builds a Markov model of the words in the wordlist(s). It then uses | |
109 | this to produce new `words' with similar statistical properties. | |
110 | They're usually pronounceable and often absurdly memorable. | |
111 | .IP | |
112 | Here's how it actually works. The program builds a big table which | |
113 | remembers how often each given letter occurs given the three preceding | |
114 | letters. There is a special placeholder letter for `before-the-start', | |
115 | and another for `end-of-word'. On output, we remember the last three | |
116 | letters emitted as our `state': then we choose a letter to emit at | |
117 | random, with the probability for each choice determined by how often it | |
118 | turned up following the letters in the state in the wordlists. The new | |
119 | letter is then shifted into the state and we try again, until we choose | |
120 | the end-of-word letter. The initial state is three before-the-start | |
121 | placeholder `letters'. | |
122 | .IP | |
123 | The word length limits are imposed by filtering the output of the Markov | |
124 | word generator. Strict limits make the program run slowly. The | |
125 | generator tracks the probability it had of making each choice of letter | |
126 | as it goes, and we just produce words until the phrase is sufficiently | |
127 | entropic. | |
128 | .TP | |
129 | .B wordlist | |
130 | Very simple: just choose random words from the wordlist until the phrase | |
131 | has enough entropy. Phrases are usually longer than Markov-generated | |
132 | ones. | |
133 | .SH BUGS | |
134 | Three letters work fairly well for English. However, they may not work | |
135 | so well for other languages. | |
136 | .SH AUTHOR | |
f387fcb1 | 137 | Mark Wooding, <mdw@distorted.org.uk>. |