NAME

       ckpasswd - nnrpd password authenticator

SYNOPSIS

       ckpasswd [-gs] [-d database] [-f filename] [-u username -p password]

DESCRIPTION

       ckpasswd is the basic password authenticator for nnrpd, suitable for being run from an
       auth stanza in readers.conf.  See readers.conf(5) for more information on how to configure
       an nnrpd authenticator.

       ckpasswd accepts a username and password from nnrpd and tells nnrpd(8) whether that's the
       correct password for that username.  By default, when given no arguments, it tries to
       check the password using PAM if support for PAM was found when INN was built.  Failing
       that, it tries to check the password against the password field returned by getpwnam(3).
       Note that these days most systems no longer make real passwords available via getpwnam(3)
       (some still do if and only if the program calling getpwnam(3) is running as root).

       When using PAM, ckpasswd identifies itself as "nnrpd", not as "ckpasswd", and the PAM
       configuration must be set up accordingly.  The details of PAM configuration are different
       on different operating systems (and even different Linux distributions); see EXAMPLES
       below for help getting started, and look for a pam(7) or pam.conf(4) manual page on your
       system.

       When using any method other than PAM, ckpasswd expects all passwords to be stored
       encrypted by the system crypt(3) function and calls crypt(3) on the supplied password
       before comparing it to the expected password.  If you're using a different password hash
       scheme (like MD5), you must use PAM.

OPTIONS

       -d database
           Read passwords from a database (ndbm or dbm format depending on what your system has)
           rather than by using getpwnam(3).  ckpasswd expects database.dir and database.pag to
           exist and to be a database keyed by username with the encrypted passwords as the
           values.

           While INN doesn't come with a program intended specifically to create such databases,
           on most systems it's fairly easy to write a Perl script to do so.  Something like:

               #!/usr/bin/perl
               use NDBM_File;
               use Fcntl;
               tie (%db, 'NDBM_File', '/path/to/database', O_RDWR|O_CREAT, 0640)
                   or die "Cannot open /path/to/database: $!\n";
               $| = 1;
               print "Username: ";
               my $user = <STDIN>;
               chomp $user;
               print "Password: ";
               my $passwd = <STDIN>;
               chomp $passwd;
               my @alphabet = ('.', '/', 0..9, 'A'..'Z', 'a'..'z');
               my $salt = join '', @alphabet[rand 64, rand 64];
               $db{$user} = crypt ($passwd, $salt);
               untie %db;

           Note that this will echo back the password when typed; there are obvious improvements
           that could be made to this, but it should be a reasonable start.  Sometimes a program
           like this will be available with the name dbmpasswd.

           This option will not be available on systems without dbm or ndbm libraries.

       -f filename
           Read passwords from the given file rather than using getpwnam(3).  The file is
           expected to be formatted like a system password file, at least vaguely.  That means
           each line should look something like:

               username:pdIh9NCNslkq6

           (and each line may have an additional colon after the encrypted password and
           additional data; that data will be ignored by ckpasswd).  Lines starting with a number
           sign ("#") are ignored.  INN does not come with a utility to create the encrypted
           passwords, but htpasswd (which comes with Apache) can do so and it's a quick job with
           Perl (see the example script under -d).  If using Apache's htpasswd program, be sure
           to give it the -d option so that it will use crypt(3).

       -g  Attempt to look up system group corresponding to username and return a string like
           "user@group" to be matched against in readers.conf.  This option is incompatible with
           the -d and -f options.

       -p password
           Use password as the password for authentication rather than reading a password using
           the nnrpd authenticator protocol.  This option is useful only for testing your
           authentication system (particularly since it involves putting a password on the
           command line), and does not work when ckpasswd is run by nnrpd.  If this option is
           given, -u must also be given.

       -s  Check passwords against the result of getspnam(3) instead of getpwnam(3).  This
           function, on those systems that supports it, reads from /etc/shadow or similar more
           restricted files.  If you want to check passwords supplied to nnrpd(8) against system
           account passwords, you will probably have to use this option on most systems.

           Most systems require special privileges to call getspnam(3), so in order to use this
           option you may need to make ckpasswd setgid to some group (like group "shadow") or
           even setuid root.  ckpasswd has not been specifically audited for such uses!  It is,
           however, a very small program that you should be able to check by hand for security.

           This configuration is not recommended if it can be avoided, for serious security
           reasons.  See "SECURITY CONSIDERATIONS" in readers.conf(5) for discussion.

       -u username
           Authenticate as username.  This option is useful only for testing (so that you can
           test your authentication system easily) and does not work when ckpasswd is run by
           nnrpd.  If this option is given, -p must also be given.

EXAMPLES

       See readers.conf(5) for examples of nnrpd(8) authentication configuration that uses
       ckpasswd to check passwords.

       An example PAM configuration for /etc/pam.conf that tells ckpasswd to check usernames and
       passwords against system accounts is:

           nnrpd auth    required pam_unix.so
           nnrpd account required pam_unix.so

       Your system may want you to instead create a file named nnrpd in /etc/pam.d with lines
       like:

           auth    required pam_unix.so
           account required pam_unix.so

       This is only the simplest configuration.  You may be able to include common shared files,
       and you may want to stack other modules, either to allow different authentication methods
       or to apply restrictions like lists of users who can't authenticate using ckpasswd.  The
       best guide is the documentation for your system and the other PAM configurations you're
       already using.

       To test to make sure that ckpasswd is working correctly, you can run it manually and then
       give it the username (prefixed with "ClientAuthname:") and password (prefixed with
       "ClientPassword:") on standard input.  For example:

           (echo 'ClientAuthname: test' ; echo 'ClientPassword: testing') \
               | ckpasswd -f /path/to/passwd/file

       will check a username of "test" and a password of "testing" against the username and
       passwords stored in /path/to/passwd/file.  On success, ckpasswd will print "User:test" and
       exit with status 0.  On failure, it will print some sort of error message and exit a non-
       zero status.

HISTORY

       Written by Russ Allbery <rra@stanford.edu> for InterNetNews.

       $Id: ckpasswd.pod 9387 2011-12-26 05:42:18Z eagle $

SEE ALSO

       crypt(3), nnrpd(8), pam(7), readers.conf(5).