X-Git-Url: https://git.eyrie.org/?a=blobdiff_plain;f=docs%2Fdocknot.yaml;fp=docs%2Fdocknot.yaml;h=a0fdb0ba853210072416d5b9ec6e91d3cc653433;hb=5dd356e159cc54bfbbde48a0bad923fb17bda241;hp=0000000000000000000000000000000000000000;hpb=c398b3695b939612fb87802093aabe46ba3041a0;p=kerberos%2Fkrb5-strength.git diff --git a/docs/docknot.yaml b/docs/docknot.yaml new file mode 100644 index 0000000..a0fdb0b --- /dev/null +++ b/docs/docknot.yaml @@ -0,0 +1,258 @@ +# Package metadata for krb5-strength. +# +# This file contains configuration for DocKnot used to generate +# documentation files (like README.md) and web pages. Other documentation +# in this package is generated automatically from these files as part of +# the release process. For more information, see DocKnot's documentation. +# +# DocKnot is available from . +# +# Copyright 2007, 2009-2010, 2012-2014, 2016-2017, 2020, 2023 +# Russ Allbery +# +# SPDX-License-Identifier: MIT + +format: v1 + +name: krb5-strength +maintainer: Russ Allbery +version: '3.3' +synopsis: Kerberos password strength checking plugin + +license: + name: Expat + notices: | + Developed by Daria Phoebe Brashear and Ken Hornstein of Sine Nomine + Associates, on behalf of Stanford University. + + The embedded version of CrackLib (all files in the `cracklib` + subdirectory) is covered by the Artistic license. See the file + `cracklib/LICENCE` for more information. Combined derivative works that + include this code, such as binaries built with the embedded CrackLib, will + need to follow the terms of the Artistic license as well as the above + license. +copyrights: + - holder: Russ Allbery + years: 2016, 2020, 2023 + - holder: The Board of Trustees of the Leland Stanford Junior University + years: 2006-2007, 2009-2010, 2012-2014 + - holder: Alec Muffett + years: '1993' + +build: + autoconf: '2.64' + automake: '1.11' + autotools: true + kerberos: true + manpages: true + reduced_depends: true + bootstrap: | + You will also need Perl 5.010 or later and the Const::Fast, DBI, + DBD::SQLite, JSON::MaybeXS, and Perl6::Slurp modules (from CPAN) to + bootstrap the test suite data from a Git checkout. + middle: | + By default, the Heimdal external password check function is installed as + `/usr/local/bin/heimdal-strength`, and the plugin is installed as + `/usr/local/lib/krb5/plugins/pwqual/strength.so`. You can change these + paths with the `--prefix`, `--libdir`, and `--bindir` options to + `configure`. + + By default, the embedded version of CrackLib will be used. To build with + the system version of CrackLib, pass `--with-cracklib` to `configure`. + You can optionally add a directory, giving the root directory where + CrackLib was installed, or separately set the include and library path + with `--with-cracklib-include` and `--with-cracklib-lib`. You can also + build without any CrackLib support by passing `--without-cracklib` to + `configure`. + + krb5-strength will automatically build with TinyCDB if it is found. To + specify the installation path of TinyCDB, use `--with-tinycdb`. You can + also separately set the include and library path with + `--with-tinycdb-include` and `--with-tinycdb-lib`. + + Similarly, krb5-strength will automatically build with SQLite if it is + found. To specify the installation path of SQLite, use `--with-sqlite`. + You can also separately set the include and library path with + `--with-sqlite-include` and `--with-sqlite-lib`. + suffix: | + After installing this software, see the man pages for krb5-strength, + heimdal-strength, and heimdal-history for configuration information. + type: Autoconf + valgrind: true +distribution: + section: kerberos + tarname: krb5-strength + version: krb5-strength + packaging: + debian: + package: krb5-strength + summary: | + A Debian package is included in Debian 8.0 (jessie) and later + releases. +support: + email: eagle@eyrie.org + github: rra/krb5-strength + web: https://www.eyrie.org/~eagle/software/krb5-strength/ +vcs: + browse: https://git.eyrie.org/?p=kerberos/krb5-strength.git + github: rra/krb5-strength + openhub: https://www.openhub.net/p/krb5-strength + status: + workflow: build + type: Git + url: https://git.eyrie.org/git/kerberos/krb5-strength.git + +docs: + user: + - name: heimdal-history + title: heimdal-history + - name: heimdal-strength + title: heimdal-strength + - name: krb5-strength + title: krb5-strength plugin + - name: wordlist + title: krb5-strength-wordlist + developer: + - name: todo + title: To-do list + +blurb: | + krb5-strength provides a password quality plugin for the MIT Kerberos KDC + (specifically the kadmind server) and Heimdal KDC, an external password + quality program for use with Heimdal, and a per-principal password history + implementation for Heimdal. Passwords can be tested with CrackLib, + checked against a CDB or SQLite database of known weak passwords with some + transformations, checked for length, checked for non-printable or + non-ASCII characters that may be difficult to enter reproducibly, required + to contain particular character classes, or any combination of these + tests. + +description: | + Heimdal includes a capability to plug in external password quality checks + and comes with an example that checks passwords against CrackLib. + However, in testing at Stanford, we found that CrackLib with its default + transform rules does not catch passwords that can be guessed using the + same dictionary with other tools, such as Jack the Ripper. We then + discovered other issues with CrackLib with longer passwords, such as some + bad assumptions about how certain measures of complexity will scale, and + wanted to impose other limitations that it didn't support. + + This plugin provides the ability to check password quality against the + standard version of CrackLib, or against a modified version of CrackLib + that only passes passwords that resist attacks from both Crack and Jack + the Ripper using the same rule sets. It also supports doing simpler + dictionary checks against a CDB database, which is fast with very large + dictionaries, or a SQLite database, which can reject all passwords within + edit distance one of a dictionary word. It can also impose other + programmatic checks on passwords such as character class requirements. + + If you're just now starting with password checking, I recommend using the + SQLite database with a large wordlist and minimum password lengths. We + found this produced the best results with the least user frustration. + + For Heimdal, krb5-strength includes both a program usable as an external + password quality check and a plugin that implements the dynamic module + API. For MIT Kerberos (1.9 or later), it includes a plugin for the + password quality (pwqual) plugin API. + + krb5-strength can be built with either the system CrackLib or with the + modified version of CrackLib included in this package. Note, however, + that if you're building against the system CrackLib, Heimdal includes in + the distribution a strength-checking plugin and an external password check + program that use the system CrackLib. With Heimdal, it would probably be + easier to use that plugin or program than build this package unless you + want the modified CrackLib, one of the other dictionary types, or the + additional character class and length checks. + + For information about the changes to the CrackLib included in this + toolkit, see `cracklib/HISTORY`. The primary changes are tighter rules, + which are more aggressive at finding dictionary words with characters + appended and prepended, which tighten the requirements for password + entropy, and which add stricter rules for longer passwords. They are also + minor changes to fix portability issues, remove some code that doesn't + make sense in the kadmind context, and close a few security issues. The + standard CrackLib distribution on at least some Linux distributions now + supports an additional interface to configure its behavior, and + krb5-strength should change in the future to use that interface and drop + the embedded copy. + + krb5-strength also includes a password history implementation for Heimdal. + This is separate from the password strength implementation but can be + stacked with it so that both strength and history checks are performed. + This history implementation is available only via the Heimdal external + password quality interface. MIT Kerberos includes its own password + history implementation. + +requirements: | + For Heimdal, you may use either the external password quality check tool, + installed as heimdal-strength, or the plugin as you choose. It has been + tested with Heimdal 1.2.1 and later, but has not recently been tested with + versions prior to 7.0. + + For MIT Kerberos, version 1.9 or higher is required for the password + quality plugin interface. MIT Kerberos does not support an external + password quality check tool directly, so you will need to install the + plugin. + + You can optionally build against the system CrackLib library. Any version + should be supported, but note that some versions, particularly older + versions close to the original code, do things like printing diagnostics + to stderr, calling exit, and otherwise not being well-behaved for use + inside plugins or libraries. They also have known security + vulnerabilities. If using a system CrackLib library, use version 2.8.22 + or later to avoid these problems. + + You can also optionally build against the TinyCDB library, which provides + support for simpler and faster password checking against a CDB dictionary + file, and the SQLite library (a version new enough to support the + `sqlite3_open_v2` API; 3.7 should be more than sufficient), which provides + support for checking whether passwords are within edit distance one of a + dictionary word. + + For this module to be effective for either Heimdal or MIT Kerberos, you + will also need to construct a dictionary. The `mkdict` and `packer` + utilities to build a CrackLib dictionary from a word list are included in + this toolkit but not installed by default. You can run them out of the + `cracklib` directory after building. You can also use the utilities that + come with the stock CrackLib package (often already packaged in a Linux + distribution); the database format is compatible. + + For building a CDB or SQLite dictionary, use the provided + `krb5-strength-wordlist` program. For CDB dictionries, the `cdb` utility + must be on your `PATH`. For SQLite, the DBI and DBD::SQLite Perl modules + are required. `krb5-strength-wordlist` requires Perl 5.010 or later. + + For a word list to use as source for the dictionary, you can use + `/usr/share/dict/words` if it's available on your system, but it would be + better to find a more comprehensive word list. Since word lists are + bulky, often covered by murky copyrights, and easily locatable on the + Internet with a modicum of searching, none are included in this toolkit. + + The password history program, heimdal-history, requires Perl 5.010 or + later plus the following CPAN modules: + + * Const::Fast + * Crypt::PBKDF2 + * DB_File::Lock + * Getopt::Long::Descriptive + * IPC::Run + * JSON::MaybeXS + + and their dependencies. + +test: + lancaster: true + suffix: | + To run the test suite, you will need Perl 5.010 or later and the + dependencies of the `heimdal-history` program. The following additional + Perl modules will also be used by the test suite if present: + + * Perl6::Slurp + * Test::MinimumVersion + * Test::Perl::Critic + * Test::Pod + * Test::Spelling + * Test::Strict + + All are available on CPAN. Some tests will be skipped if the modules + are not available.