Aspirational documentation for the crypt.conf feature.

Subsequent patches will actually implement all of this stuff.

Makefile.am

@@ -20,8 +20,10 @@ EXTRA_DIST = \
 
 notrans_dist_man3_MANS = \
 	crypt.3 crypt_r.3 crypt_ra.3 crypt_rn.3 \
-	crypt_gensalt.3 crypt_gensalt_ra.3 crypt_gensalt_rn.3
-notrans_dist_man5_MANS = crypt.5
+	crypt_gensalt.3 crypt_gensalt_ra.3 crypt_gensalt_rn.3 \
+	crypt_checksalt.3
+notrans_dist_man5_MANS = crypt.5 crypt.conf.5
+notrans_dist_man8_MANS = crypt-checkconf.8 crypt-tune-costs.8
 
 nodist_include_HEADERS = crypt.h
 nodist_noinst_HEADERS = crypt-hashes.h crypt-base.h

crypt-checkconf.8

@@ -0,0 +1,96 @@
+.\" Written by Zack Weinberg <zackw at panix.com> in 2018.
+.\"
+.\" To the extent possible under law, the authors have waived
+.\" all copyright and related or neighboring rights to this work.
+.\" See https://creativecommons.org/publicdomain/zero/1.0/ for further
+.\" details.
+.\"
+.Dd August 14, 2018
+.Dt CRYPT-CHECKCONF 8
+.Os "libxcrypt"
+.Sh NAME
+.Nm crypt-checkconf
+.Nd validate crypt.conf
+.Sh SYNOPSIS
+.Nm
+.Op Fl m
+.Op Ar file
+.Sh DESCRIPTION
+The
+.Nm
+utility validates a file in the format of
+.Xr crypt.conf 5 .
+If a
+.Ar file
+is given on the command line, it validates that file;
+otherwise, it validates
+.Pa /etc/crypt.conf .
+.Ar file
+may be specified as
+.Sq Li \&-
+to read standard input.
+Problems found are reported to standard error.
+.Pp
+The following problems are detected:
+.Bl -bullet
+.It
+Lines containing syntactic garbage or unprintable characters.
+Characters with the 8th bit set are allowed, but only in comments.
+.It
+Unrecognized hashing method names.
+.It
+Unrecognized values for the
+.Ar allowed use
+field.
+.It
+.Ar key Ns = Ns Ar value
+fields with an unrecognized
+.Ar key .
+.It
+Invalid values for the
+.Ar rounds
+parameter, either syntactically or because they do not meet the
+restrictions for the hashing method.
+.El
+.Sh OPTIONS
+.Bl -tag -width 2m
+.It Fl m , \-merge\-defaults
+Merge all of the valid lines in the input file
+with the compiled-in defaults,
+and write the result to standard output.
+This produces a configuration file
+with the same behavior as the original,
+but having explicit settings for each hashing method.
+Comments are preserved.
+Lines with problems are echoed as comments.
+.Pp
+To print out just the compiled-in defaults,
+ignoring whatever might be in
+.Pa /etc/crypt.conf ,
+use
+.Pp
+.Dl crypt-checkconf -m /dev/null
+.El
+.Sh EXIT STATUS
+The exit status is 0 if no problems were found, 1 if at least one problem
+was found, and 2 if a system error occurred.
+.Pp
+Note that if no
+.Ar file
+is given on the command line, and
+.Pa /etc/crypt.conf
+does not exist, that is
+.Em not
+considered to be an error, because
+.Fn crypt
+and
+.Fn crypt_gensalt
+treat a nonexistent
+.Pa /etc/crypt.conf
+the same as if it were empty.
+.Sh SEE ALSO
+.Xr crypt 3 ,
+.Xr crypt_gensalt 3 ,
+.Xr crypt 5 ,
+.Xr crypt.conf 5 ,
+.Xr crypt\-tune\-costs 8

crypt-tune-costs.8

@@ -0,0 +1,149 @@
+.\" Written by Zack Weinberg <zackw at panix.com> in 2018.
+.\"
+.\" To the extent possible under law, the authors have waived
+.\" all copyright and related or neighboring rights to this work.
+.\" See https://creativecommons.org/publicdomain/zero/1.0/ for further
+.\" details.
+.\"
+.Dd August 14, 2018
+.Dt CRYPT-TUNE-COSTS 8
+.Os "libxcrypt"
+.Sh NAME
+.Nm crypt-tune-costs
+.Nd choose cost parameters for passphrase hashing
+.Sh SYNOPSIS
+.Nm
+.Op Fl sv
+.Op Fl t Ar milliseconds
+.Op Fl p Ar method
+.Op Fl e Ar method , Ns Ar method , Ns .\|.\|.
+.Op Fl l Ar method , Ns Ar method , Ns .\|.\|.
+.Op Fl d Ar method , Ns Ar method , Ns .\|.\|.
+.Sh DESCRIPTION
+The
+.Nm
+utility measures the speed of all the hashing methods supported by
+.Xr crypt 3 ,
+and selects cost parameters that will make each of them
+take a specified amount of time on the current hardware.
+By default, this is 250 milliseconds,
+which is long enough to impose significant costs on brute-force attackers,
+while not annoying legitimate users.
+Hashing methods that cannot be made to take this long
+will be marked as
+.Em legacy ,
+to be used only for authentication against existing hashes.
+.Pp
+.Nm
+writes a configuration file suitable for use as
+.Pa /etc/security/crypt.conf
+(see
+.Xr crypt.conf 5 )
+to its standard output.
+.Sh OPTIONS
+.Bl -tag -width 2m
+.It Fl s , \-strict
+Disable hashing methods that cannot be made to take the
+specified amount of time, instead of marking them as legacy.
+.It Fl v , \-verbose
+Write detailed information about the process of searching for
+appropriate cost parameters to standard error.
+.It Fl t Ar milliseconds ; Fl \-time Ns = Ns Ar milliseconds
+Try to make each hashing method take
+.Ar milliseconds
+milliseconds.
+The number supplied must be positive, and may be either an integer or
+a decimal fraction.
+.It Fl p Ar method ; Fl \-preferred Ns = Ns Ar method
+Use
+.Ar method
+as the preferred hashing method for new passphrases; that is,
+.Nm crypt_gensalt
+will generate a setting string for this method when its
+.Ar prefix
+argument is NULL.
+.Fl p Ar method
+implies
+.Fl e Ar method .
+.It Fl e Ar method , Ns Ar method , Ns .\|.\|. ; Fl \-enabled Ns = Ns Ar method , Ns Ar method , Ns .\|.\|.
+Use each
+.Ar method
+for authentication against existing hashes,
+and allow them to be used in new hashes.
+.Pp
+.Fl e Ar all
+means to enable all known hashing methods.
+.It Fl l Ar method , Ns Ar method , Ns .\|.\|. ; Fl \-legacy Ns = Ns Ar method , Ns Ar method , Ns .\|.\|.
+Use each
+.Ar method
+only for authentication against existing passphrase hashes;
+.Nm crypt_gensalt
+will refuse to generate new setting strings for them.
+.Nm
+will not bother selecting cost parameters for these hashes.
+.Pp
+.Fl l Ar all
+means to mark all known hashing methods as legacy.
+.It Fl d Ar method , Ns Ar method , Ns .\|.\|. ; Fl \-disabled Ns = Ns Ar method , Ns Ar method , Ns .\|.\|.
+Do not allow any of the
+.Ar method Ns s
+to be used at all; both
+.Nm crypt_gensalt
+and
+.Nm crypt
+will fail if directed to use them.
+.Nm
+will not bother selecting cost parameters for these hashes.
+.Pp
+.Fl d Ar all
+means to disable all known hashing methods.
+.Pp
+.Em Caution:
+Users whose passphrases were hashed using a disabled method
+will not be able to log in with a passphrase.
+If they log in some other way
+(e.g.\& an SSH key)
+they will not be able to
+.Em change
+their passphrase, because
+.Xr passwd 1
+will not be able to validate their old passphrase.
+.El
+.Pp
+The
+.Fl p ,
+.Fl e ,
+.Fl l ,
+and
+.Fl d
+options may be given any number of times and in any order.
+If more than one of these options is given for the same
+.Ar method ,
+the last one on the command line wins.
+.Sh EXIT STATUS
+The exit status is 0 if the generated
+.Pa crypt.conf
+has at least one hashing method enabled for new passphrases.
+It is 1 if it does not, or if a system error occurred.
+.Sh EXAMPLES
+Select costs parameters for all hashes that are enabled by default:
+.Pp
+.Dl # crypt-tune-costs > /etc/crypt.conf
+.Pp
+Select a cost parameter for yescrypt, which will be used as the
+default hash; mark all other hashes as disabled:
+.Pp
+.Dl # crypt-tune-costs -d all -p yescrypt > /etc/crypt.conf
+.Pp
+Find cost parameters that will make all hashes take approximately 2 seconds.
+Disable all hashes that cannot be made to take this long.
+Display detailed progress information, and dump the generated
+.Pa crypt.conf
+to the terminal:
+.Pp
+.Dl $ crypt-tune-costs -e all -m 2000 -vs
+.Sh SEE ALSO
+.Xr crypt 3 ,
+.Xr crypt_gensalt 3 ,
+.Xr crypt 5 ,
+.Xr crypt.conf 5

crypt.3

@@ -282,7 +282,10 @@ when they fail.
 .Bl -tag -width Er
 .It Er EINVAL
 .Fa setting
-is invalid, or requests a hashing method that is not supported.
+is invalid,
+or requests a hashing method that is not supported
+or has been disabled in
+.Xr crypt.conf 5 .
 .It Er ERANGE
 .Nm crypt_rn
 only:
@@ -463,6 +466,7 @@ originate with the Openwall project.
 .Xr login 1 ,
 .Xr passwd 1 ,
 .Xr crypt 5 ,
+.Xr crypt.conf 5 ,
 .Xr passwd 5 ,
 .Xr shadow 5 ,
 .Xr pam 8