tools/krb5-strength-wordlist.1

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