tools/krb5-strength-wordlist.1

   1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "KRB5-STRENGTH-WORDLIST 1"
 132 .TH KRB5-STRENGTH-WORDLIST 1 "2016-12-25" "3.1" "krb5-strength"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 krb5\-strength\-wordlist \- Create a krb5\-strength database from a word list
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 \&\fBkrb5\-strength\-wordlist\fR [\fB\-am\fR] [\fB\-c\fR \fIoutput-cdb\fR] [\fB\-l\fR \fImin-length\fR]
 142     [\fB\-L\fR \fImax-length\fR] [\fB\-o\fR \fIoutput-wordlist\fR] [\fB\-s\fR \fIoutput-sqlite\fR]
 143     [\fB\-x\fR \fIexclude\fR ...] \fIwordlist\fR
 144 .SH "DESCRIPTION"
 145 .IX Header "DESCRIPTION"
 146 \&\fBkrb5\-strength\-wordlist\fR converts a word list (a file containing one word
 147 per line) into a database that can be used by the krb5\-strength plugin or
 148 \&\fBheimdal-strength\fR command for checking passwords.  Two database formats
 149 are supported, with different features.  \s-1CDB\s0 is more space-efficient and
 150 possibly faster, but supports checking passwords only against exact
 151 matches or simple transformations (removing small numbers of leading and
 152 trailing characters).  SQLite creates a much larger database, but supports
 153 rejecting any password within edit distance one of a word in the word
 154 list.
 155 .PP
 156 \&\s-1CDB\s0 is a format invented by Dan Bernstein for fast, constant databases.
 157 The database is fixed during creation and cannot be changed without
 158 rebuilding it, and is optimized for very fast access.  For cdb, the
 159 database generated by this program will have keys for each word in the
 160 word list and the constant \f(CW1\fR as the value.
 161 .PP
 162 SQLite stores the word list in a single table containing both each word
 163 and each word reversed.  This allows the krb5\-strength plugin or
 164 \&\fBheimdal-strength\fR command to reject passwords within edit distance one
 165 of any word in the word list.  (Edit distance one means that the word list
 166 entry can be formed by changing a single character of the password, either
 167 by adding one character, removing one character, or changing one character
 168 to a different character.)  However, the SQLite database will be much
 169 larger and lookups may be somewhat slower.
 170 .PP
 171 \&\fBkrb5\-strength\-wordlist\fR takes one argument, the input word list file.
 172 Use the \fB\-c\fR option to specify an output \s-1CDB\s0 file, \fB\-s\fR to specify an
 173 output SQLite file, or \fB\-o\fR to just filter the word list against the
 174 criteria given on the command line and generate a new word list.
 175 The input word list file does not have to be sorted.  See the individual
 176 option descriptions for more information.
 177 .SH "OPTIONS"
 178 .IX Header "OPTIONS"
 179 .IP "\fB\-a\fR, \fB\-\-ascii\fR" 4
 180 .IX Item "-a, --ascii"
 181 Filter all words that contain non-ASCII characters or control characters
 182 from the resulting cdb file, leaving only words that consist solely of
 183 \&\s-1ASCII\s0 non-control characters.
 184 .IP "\fB\-c\fR \fIoutput-cdb\fR, \fB\-\-cdb\fR=\fIoutput-cdb\fR" 4
 185 .IX Item "-c output-cdb, --cdb=output-cdb"
 186 Create a \s-1CDB\s0 database in \fIoutput-cdb\fR.  A temporary file named after
 187 \&\fIoutput-cdb\fR with \f(CW\*(C`.data\*(C'\fR appended will be created in the same directory
 188 and used to stage the database contents.  The actual \s-1CDB\s0 file will be
 189 built using the \fBcdb\fR command, which must be on the user's path.  If
 190 either file already exists, \fBkrb5\-strength\-wordlist\fR will abort with an
 191 error.
 192 .Sp
 193 This option cannot be used with \fB\-o\fR or \fB\-s\fR.
 194 .IP "\fB\-L\fR \fImaximum\fR, \fB\-\-max\-length\fR=\fImaximum\fR" 4
 195 .IX Item "-L maximum, --max-length=maximum"
 196 Filter all words of length greater than \fImaximum\fR from the resulting cdb
 197 database.  The length of each line (minus the separating newline) in the
 198 input word list will be checked against \fIminimum\fR and will be filtered
 199 out of the resulting database if it is shorter.  Useful for generating
 200 password dictionaries from word lists that contain random noise that's
 201 highly unlikely to be used as a password.
 202 .Sp
 203 The default is to not filter out any words for maximum length.
 204 .IP "\fB\-l\fR \fIminimum\fR, \fB\-\-min\-length\fR=\fIminimum\fR" 4
 205 .IX Item "-l minimum, --min-length=minimum"
 206 Filter all words of length less than \fIminimum\fR from the resulting cdb
 207 database.  The length of each line (minus the separating newline) in the
 208 input word list will be checked against \fIminimum\fR and will be filtered
 209 out of the resulting database if it is shorter.  Useful for generating
 210 password dictionaries where shorter passwords will be rejected by a
 211 generic length check and no dictionary lookup will be done for a transform
 212 of the password shorter than the specified minimum.
 213 .Sp
 214 The default is not to filter out any words for minimum length.
 215 .IP "\fB\-m\fR, \fB\-\-man\fR, \fB\-\-manual\fR" 4
 216 .IX Item "-m, --man, --manual"
 217 Print out this documentation (which is done simply by feeding the script to
 218 \&\f(CW\*(C`perldoc \-t\*(C'\fR).
 219 .IP "\fB\-o\fR \fIwordlist\fR, \fB\-\-output\fR=\fIwordlist\fR" 4
 220 .IX Item "-o wordlist, --output=wordlist"
 221 Rather than creating a database, apply the filter rules given by the other
 222 command-line arguments and generate a new word list in the file name given
 223 by the \fIwordlist\fR option.  This can be used to reduce the size of a raw
 224 word list file (such as one taken from Internet sources) by removing the
 225 words that will be filtered out of the dictionary anyway, thus reducing
 226 the size of the source required to regenerate the dictionary.
 227 .Sp
 228 This option cannot be used with \fB\-c\fR or \fB\-s\fR.
 229 .IP "\fB\-s\fR \fIoutput-sqlite\fR, \fB\-\-sqlite\fR=\fIoutput-sqlite\fR" 4
 230 .IX Item "-s output-sqlite, --sqlite=output-sqlite"
 231 Create a SQLite database in \fIoutput-sqlite\fR.  If this file already
 232 exists, \fBkrb5\-strength\-wordlist\fR will abort with an error.  The resulting
 233 SQLite database will have one table, \f(CW\*(C`passwords\*(C'\fR, with two columns,
 234 \&\f(CW\*(C`password\*(C'\fR and \f(CW\*(C`drowssap\*(C'\fR.  The first holds a word from the word list,
 235 and the second holds the same word reversed.
 236 .Sp
 237 Using this option requires the \s-1DBI\s0 and DBD::SQLite Perl modules be
 238 installed.
 239 .Sp
 240 This option cannot be used with \fB\-c\fR or \fB\-o\fR.
 241 .IP "\fB\-x\fR \fIexclude\fR, \fB\-\-exclude\fR=\fIexclude\fR" 4
 242 .IX Item "-x exclude, --exclude=exclude"
 243 Filter all words matching the regular expression \fIexclude\fR from the
 244 resulting cdb database.  This regular expression will be matched against
 245 each line of the source word list after the trailing newline is removed.
 246 This option may be given repeatedly to add multiple exclusion regexes.
 247 .SH "AUTHOR"
 248 .IX Header "AUTHOR"
 249 Russ Allbery <eagle@eyrie.org>
 250 .SH "COPYRIGHT AND LICENSE"
 251 .IX Header "COPYRIGHT AND LICENSE"
 252 Copyright 2016 Russ Allbery <eagle@eyrie.org>
 253 .PP
 254 Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
 255 University
 256 .PP
 257 Permission is hereby granted, free of charge, to any person obtaining a
 258 copy of this software and associated documentation files (the \*(L"Software\*(R"),
 259 to deal in the Software without restriction, including without limitation
 260 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 261 and/or sell copies of the Software, and to permit persons to whom the
 262 Software is furnished to do so, subject to the following conditions:
 263 .PP
 264 The above copyright notice and this permission notice shall be included in
 265 all copies or substantial portions of the Software.
 266 .PP
 267 \&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 268 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 269 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 270 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 271 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 272 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 273 DEALINGS IN THE SOFTWARE.\s0
 274 .SH "SEE ALSO"
 275 .IX Header "SEE ALSO"
 276 \&\fIcdb\fR\|(1), \s-1DBI\s0, DBD::SQLite
 277 .PP
 278 The cdb file format is defined at <http://cr.yp.to/cdb.html>.
 279 .PP
 280 The current version of this program is available from its web page at
 281 <https://www.eyrie.org/~eagle/software/krb5\-strength/> as part of the
 282 krb5\-strength package.