[u/mdw/catacomb] / 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 [ \-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, <mdw@distorted.org.uk>.
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
	36	.RB [ \-p ]
	37	.RB [ \-b
	38	.IR bits ]
	39	.RB [ \-g
	40	.IR generator ]
	41	.br
45c0fd36	42
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;
	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"
45c0fd36	69	Write
6abcf20f	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
45c0fd36	89	Produce
6abcf20f	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>.