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.