docs/docknot.yaml

   1 # Package metadata for krb5-strength.
   2 #
   3 # This file contains configuration for DocKnot used to generate
   4 # documentation files (like README.md) and web pages.  Other documentation
   5 # in this package is generated automatically from these files as part of
   6 # the release process.  For more information, see DocKnot's documentation.
   7 #
   8 # DocKnot is available from <https://www.eyrie.org/~eagle/software/docknot/>.
   9 #
  10 # Copyright 2007, 2009-2010, 2012-2014, 2016-2017, 2020, 2023
  11 #     Russ Allbery <eagle@eyrie.org>
  12 #
  13 # SPDX-License-Identifier: MIT
  14
  15 format: v1
  16
  17 name: krb5-strength
  18 maintainer: Russ Allbery <eagle@eyrie.org>
  19 version: '3.3'
  20 synopsis: Kerberos password strength checking plugin
  21
  22 license:
  23   name: Expat
  24   notices: |
  25     Developed by Daria Phoebe Brashear and Ken Hornstein of Sine Nomine
  26     Associates, on behalf of Stanford University.
  27
  28     The embedded version of CrackLib (all files in the `cracklib`
  29     subdirectory) is covered by the Artistic license.  See the file
  30     `cracklib/LICENCE` for more information.  Combined derivative works that
  31     include this code, such as binaries built with the embedded CrackLib, will
  32     need to follow the terms of the Artistic license as well as the above
  33     license.
  34 copyrights:
  35   - holder: Russ Allbery <eagle@eyrie.org>
  36     years: 2016, 2020, 2023
  37   - holder: The Board of Trustees of the Leland Stanford Junior University
  38     years: 2006-2007, 2009-2010, 2012-2014
  39   - holder: Alec Muffett
  40     years: '1993'
  41
  42 build:
  43   autoconf: '2.64'
  44   automake: '1.11'
  45   autotools: true
  46   kerberos: true
  47   manpages: true
  48   reduced_depends: true
  49   bootstrap: |
  50     You will also need Perl 5.010 or later and the Const::Fast, DBI,
  51     DBD::SQLite, JSON::MaybeXS, and Perl6::Slurp modules (from CPAN) to
  52     bootstrap the test suite data from a Git checkout.
  53   middle: |
  54     By default, the Heimdal external password check function is installed as
  55     `/usr/local/bin/heimdal-strength`, and the plugin is installed as
  56     `/usr/local/lib/krb5/plugins/pwqual/strength.so`.  You can change these
  57     paths with the `--prefix`, `--libdir`, and `--bindir` options to
  58     `configure`.
  59
  60     By default, the embedded version of CrackLib will be used.  To build with
  61     the system version of CrackLib, pass `--with-cracklib` to `configure`.
  62     You can optionally add a directory, giving the root directory where
  63     CrackLib was installed, or separately set the include and library path
  64     with `--with-cracklib-include` and `--with-cracklib-lib`.  You can also
  65     build without any CrackLib support by passing `--without-cracklib` to
  66     `configure`.
  67
  68     krb5-strength will automatically build with TinyCDB if it is found.  To
  69     specify the installation path of TinyCDB, use `--with-tinycdb`.  You can
  70     also separately set the include and library path with
  71     `--with-tinycdb-include` and `--with-tinycdb-lib`.
  72
  73     Similarly, krb5-strength will automatically build with SQLite if it is
  74     found.  To specify the installation path of SQLite, use `--with-sqlite`.
  75     You can also separately set the include and library path with
  76     `--with-sqlite-include` and `--with-sqlite-lib`.
  77   suffix: |
  78     After installing this software, see the man pages for krb5-strength,
  79     heimdal-strength, and heimdal-history for configuration information.
  80   type: Autoconf
  81   valgrind: true
  82 distribution:
  83   section: kerberos
  84   tarname: krb5-strength
  85   version: krb5-strength
  86   packaging:
  87     debian:
  88       package: krb5-strength
  89       summary: |
  90         A Debian package is included in Debian 8.0 (jessie) and later
  91         releases.
  92 support:
  93   email: eagle@eyrie.org
  94   github: rra/krb5-strength
  95   web: https://www.eyrie.org/~eagle/software/krb5-strength/
  96 vcs:
  97   browse: https://git.eyrie.org/?p=kerberos/krb5-strength.git
  98   github: rra/krb5-strength
  99   openhub: https://www.openhub.net/p/krb5-strength
 100   status:
 101     workflow: build
 102   type: Git
 103   url: https://git.eyrie.org/git/kerberos/krb5-strength.git
 104
 105 docs:
 106   user:
 107     - name: heimdal-history
 108       title: heimdal-history
 109     - name: heimdal-strength
 110       title: heimdal-strength
 111     - name: krb5-strength
 112       title: krb5-strength plugin
 113     - name: wordlist
 114       title: krb5-strength-wordlist
 115   developer:
 116     - name: todo
 117       title: To-do list
 118
 119 blurb: |
 120   krb5-strength provides a password quality plugin for the MIT Kerberos KDC
 121   (specifically the kadmind server) and Heimdal KDC, an external password
 122   quality program for use with Heimdal, and a per-principal password history
 123   implementation for Heimdal.  Passwords can be tested with CrackLib,
 124   checked against a CDB or SQLite database of known weak passwords with some
 125   transformations, checked for length, checked for non-printable or
 126   non-ASCII characters that may be difficult to enter reproducibly, required
 127   to contain particular character classes, or any combination of these
 128   tests.
 129
 130 description: |
 131   Heimdal includes a capability to plug in external password quality checks
 132   and comes with an example that checks passwords against CrackLib.
 133   However, in testing at Stanford, we found that CrackLib with its default
 134   transform rules does not catch passwords that can be guessed using the
 135   same dictionary with other tools, such as Jack the Ripper.  We then
 136   discovered other issues with CrackLib with longer passwords, such as some
 137   bad assumptions about how certain measures of complexity will scale, and
 138   wanted to impose other limitations that it didn't support.
 139
 140   This plugin provides the ability to check password quality against the
 141   standard version of CrackLib, or against a modified version of CrackLib
 142   that only passes passwords that resist attacks from both Crack and Jack
 143   the Ripper using the same rule sets.  It also supports doing simpler
 144   dictionary checks against a CDB database, which is fast with very large
 145   dictionaries, or a SQLite database, which can reject all passwords within
 146   edit distance one of a dictionary word.  It can also impose other
 147   programmatic checks on passwords such as character class requirements.
 148
 149   If you're just now starting with password checking, I recommend using the
 150   SQLite database with a large wordlist and minimum password lengths.  We
 151   found this produced the best results with the least user frustration.
 152
 153   For Heimdal, krb5-strength includes both a program usable as an external
 154   password quality check and a plugin that implements the dynamic module
 155   API.  For MIT Kerberos (1.9 or later), it includes a plugin for the
 156   password quality (pwqual) plugin API.
 157
 158   krb5-strength can be built with either the system CrackLib or with the
 159   modified version of CrackLib included in this package.  Note, however,
 160   that if you're building against the system CrackLib, Heimdal includes in
 161   the distribution a strength-checking plugin and an external password check
 162   program that use the system CrackLib.  With Heimdal, it would probably be
 163   easier to use that plugin or program than build this package unless you
 164   want the modified CrackLib, one of the other dictionary types, or the
 165   additional character class and length checks.
 166
 167   For information about the changes to the CrackLib included in this
 168   toolkit, see `cracklib/HISTORY`.  The primary changes are tighter rules,
 169   which are more aggressive at finding dictionary words with characters
 170   appended and prepended, which tighten the requirements for password
 171   entropy, and which add stricter rules for longer passwords.  They are also
 172   minor changes to fix portability issues, remove some code that doesn't
 173   make sense in the kadmind context, and close a few security issues.  The
 174   standard CrackLib distribution on at least some Linux distributions now
 175   supports an additional interface to configure its behavior, and
 176   krb5-strength should change in the future to use that interface and drop
 177   the embedded copy.
 178
 179   krb5-strength also includes a password history implementation for Heimdal.
 180   This is separate from the password strength implementation but can be
 181   stacked with it so that both strength and history checks are performed.
 182   This history implementation is available only via the Heimdal external
 183   password quality interface.  MIT Kerberos includes its own password
 184   history implementation.
 185
 186 requirements: |
 187   For Heimdal, you may use either the external password quality check tool,
 188   installed as heimdal-strength, or the plugin as you choose.  It has been
 189   tested with Heimdal 1.2.1 and later, but has not recently been tested with
 190   versions prior to 7.0.
 191
 192   For MIT Kerberos, version 1.9 or higher is required for the password
 193   quality plugin interface.  MIT Kerberos does not support an external
 194   password quality check tool directly, so you will need to install the
 195   plugin.
 196
 197   You can optionally build against the system CrackLib library.  Any version
 198   should be supported, but note that some versions, particularly older
 199   versions close to the original code, do things like printing diagnostics
 200   to stderr, calling exit, and otherwise not being well-behaved for use
 201   inside plugins or libraries.  They also have known security
 202   vulnerabilities.  If using a system CrackLib library, use version 2.8.22
 203   or later to avoid these problems.
 204
 205   You can also optionally build against the TinyCDB library, which provides
 206   support for simpler and faster password checking against a CDB dictionary
 207   file, and the SQLite library (a version new enough to support the
 208   `sqlite3_open_v2` API; 3.7 should be more than sufficient), which provides
 209   support for checking whether passwords are within edit distance one of a
 210   dictionary word.
 211
 212   For this module to be effective for either Heimdal or MIT Kerberos, you
 213   will also need to construct a dictionary.  The `mkdict` and `packer`
 214   utilities to build a CrackLib dictionary from a word list are included in
 215   this toolkit but not installed by default.  You can run them out of the
 216   `cracklib` directory after building.  You can also use the utilities that
 217   come with the stock CrackLib package (often already packaged in a Linux
 218   distribution); the database format is compatible.
 219
 220   For building a CDB or SQLite dictionary, use the provided
 221   `krb5-strength-wordlist` program.  For CDB dictionries, the `cdb` utility
 222   must be on your `PATH`.  For SQLite, the DBI and DBD::SQLite Perl modules
 223   are required.  `krb5-strength-wordlist` requires Perl 5.010 or later.
 224
 225   For a word list to use as source for the dictionary, you can use
 226   `/usr/share/dict/words` if it's available on your system, but it would be
 227   better to find a more comprehensive word list.  Since word lists are
 228   bulky, often covered by murky copyrights, and easily locatable on the
 229   Internet with a modicum of searching, none are included in this toolkit.
 230
 231   The password history program, heimdal-history, requires Perl 5.010 or
 232   later plus the following CPAN modules:
 233
 234   * Const::Fast
 235   * Crypt::PBKDF2
 236   * DB_File::Lock
 237   * Getopt::Long::Descriptive
 238   * IPC::Run
 239   * JSON::MaybeXS
 240
 241   and their dependencies.
 242
 243 test:
 244   lancaster: true
 245   suffix: |
 246     To run the test suite, you will need Perl 5.010 or later and the
 247     dependencies of the `heimdal-history` program.  The following additional
 248     Perl modules will also be used by the test suite if present:
 249
 250     * Perl6::Slurp
 251     * Test::MinimumVersion
 252     * Test::Perl::Critic
 253     * Test::Pod
 254     * Test::Spelling
 255     * Test::Strict
 256
 257     All are available on CPAN.  Some tests will be skipped if the modules
 258     are not available.