doc/pod/ckpasswd.pod

   1 =head1 NAME
   2
   3 ckpasswd - nnrpd password authenticator
   4
   5 =head1 SYNOPSIS
   6
   7 B<ckpasswd> [B<-gs>] [B<-d> I<database>] [B<-f> I<filename>]
   8 [B<-u> I<username> B<-p> I<password>]
   9
  10 =head1 DESCRIPTION
  11
  12 B<ckpasswd> is the basic password authenticator for nnrpd, suitable for
  13 being run from an auth stanza in I<readers.conf>.  See readers.conf(5) for
  14 more information on how to configure an nnrpd authenticator.
  15
  16 B<ckpasswd> accepts a username and password from nnrpd and tells nnrpd(8)
  17 whether that's the correct password for that username.  By default, when
  18 given no arguments, it tries to check the password using PAM if support
  19 for PAM was found when INN was built.  Failing that, it tries to check the
  20 password against the password field returned by getpwnam(3).  Note that
  21 these days most systems no longer make real passwords available via
  22 getpwnam(3) (some still do if and only if the program calling getpwnam(3)
  23 is running as root).
  24
  25 When using PAM, B<ckpasswd> identifies itself as C<nnrpd>, not as
  26 C<ckpasswd>, and the PAM configuration must be set up accordingly.  The
  27 details of PAM configuration are different on different operating systems
  28 (and even different Linux distributions); see L<EXAMPLES> below for help
  29 getting started, and look for a pam(7) or pam.conf(4) manual page on your
  30 system.
  31
  32 When using any method other than PAM, B<ckpasswd> expects all passwords to
  33 be stored encrypted by the system crypt(3) function and calls crypt(3) on
  34 the supplied password before comparing it to the expected password.  IF
  35 you're using a different password hash scheme (like MD5), you must use
  36 PAM.
  37
  38 =head1 OPTIONS
  39
  40 =over 4
  41
  42 =item B<-d> I<database>
  43
  44 Read passwords from a database (ndbm or dbm format depending on what your
  45 system has) rather than by using getpwnam(3).  B<ckpasswd> expects
  46 I<database>.dir and I<database>.pag to exist and to be a database keyed by
  47 username with the encrypted passwords as the values.
  48
  49 While INN doesn't come with a program intended specifically to create such
  50 databases, on most systems it's fairly easy to write a Perl script to do
  51 so.  Something like:
  52
  53     #!/usr/bin/perl
  54     use NDBM_File;
  55     use Fcntl;
  56     tie (%db, 'NDBM_File', '/path/to/database', O_RDWR|O_CREAT, 0640)
  57         or die "Cannot open /path/to/database: $!\n";
  58     $| = 1;
  59     print "Username: ";
  60     my $user = <STDIN>;
  61     chomp $user;
  62     print "Password: ";
  63     my $passwd = <STDIN>;
  64     chomp $passwd;
  65     my @alphabet = ('.', '/', 0..9, 'A'..'Z', 'a'..'z');
  66     my $salt = join '', @alphabet[rand 64, rand 64];
  67     $db{$user} = crypt ($passwd, $salt);
  68     untie %db;
  69
  70 Note that this will echo back the password when typed; there are obvious
  71 improvements that could be made to this, but it should be a reasonable
  72 start.  Sometimes a program like this will be available with the name
  73 B<dbmpasswd>.
  74
  75 This option will not be available on systems without dbm or ndbm
  76 libraries.
  77
  78 =item B<-f> I<filename>
  79
  80 Read passwords from the given file rather than using getpwnam(3).  The
  81 file is expected to be formatted like a system password file, at least
  82 vaguely.  That means each line should look something like:
  83
  84     username:pdIh9NCNslkq6
  85
  86 (and each line may have an additional colon after the encrypted password
  87 and additional data; that data will be ignored by B<ckpasswd>).  Lines
  88 starting with a number sign (`#') are ignored.  INN does not come with a
  89 utility to create the encrypted passwords, but B<htpasswd> (which comes
  90 with Apache) can do so and it's a quick job with Perl (see the example
  91 script under B<-d>).  If using Apache's B<htpasswd> program, be sure to
  92 give it the B<-d> option so that it will use crypt(3).
  93
  94 =item B<-g>
  95
  96 Attempt to look up system group corresponding to username and return a
  97 string like "user@group" to be matched against in F<readers.conf>.  This
  98 option is incompatible with the B<-d> and B<-f> options.
  99
 100 =item B<-p> I<password>
 101
 102 Use I<password> as the password for authentication rather than reading a
 103 password using the nnrpd authenticator protocol.  This option is useful
 104 only for testing your authentication system (particularly since it
 105 involves putting a password on the command line), and does not work when
 106 B<ckpasswd> is run by B<nnrpd>.  If this option is given, B<-u> must also
 107 be given.
 108
 109 =item B<-s>
 110
 111 Check passwords against the result of getspnam(3) instead of getpwnam(3).
 112 This function, on those systems that supports it, reads from /etc/shadow
 113 or similar more restricted files.  If you want to check passwords supplied
 114 to nnrpd(8) against system account passwords, you will probably have to
 115 use this option on most systems.
 116
 117 Most systems require special privileges to call getspnam(3), so in order
 118 to use this option you may need to make B<ckpasswd> setgid to some group
 119 (like group "shadow") or even setuid root.  B<ckpasswd> has not been
 120 specifically audited for such uses!  It is, however, a very small program
 121 that you should be able to check by hand for security.
 122
 123 This configuration is not recommended if it can be avoided, for serious
 124 security reasons.  See L<readers.confZ<>(5)/SECURITY CONSIDERATIONS> for
 125 discussion.
 126
 127 =item B<-u> I<username>
 128
 129 Authenticate as I<username>.  This option is useful only for testing (so
 130 that you can test your authentication system easily) and does not work
 131 when B<ckpasswd> is run by B<nnrpd>.  If this option is given, B<-p> must
 132 also be given.
 133
 134 =back
 135
 136 =head1 EXAMPLES
 137
 138 See readers.conf(5) for examples of nnrpd(8) authentication configuration
 139 that uses B<ckpasswd> to check passwords.
 140
 141 An example PAM configuration for F</etc/pam.conf> that tells B<ckpasswd>
 142 to check usernames and passwords against system accounts is:
 143
 144     nnrpd auth    required pam_unix.so
 145     nnrpd account required pam_unix.so
 146
 147 Your system may want you to instead create a file named F<nnrpd> in
 148 F</etc/pam.d> with lines like:
 149
 150     auth    required pam_unix.so
 151     account required pam_unix.so
 152
 153 This is only the simplest configuration.  You may be able to include
 154 common shared files, and you may want to stack other modules, either to
 155 allow different authentication methods or to apply restrictions like lists
 156 of users who can't authenticate using B<ckpasswd>.  The best guide is the
 157 documentation for your system and the other PAM configurations you're
 158 already using.
 159
 160 To test to make sure that B<ckpasswd> is working correctly, you can run it
 161 manually and then give it the username (prefixed with C<ClientAuthname:>)
 162 and password (prefixed with C<ClientPassword:>) on standard input.  For
 163 example:
 164
 165     (echo 'ClientAuthname: test' ; echo 'ClientPassword: testing') \
 166         | ckpasswd -f /path/to/passwd/file
 167
 168 will check a username of C<test> and a password of C<testing> against the
 169 username and passwords stored in F</path/to/passwd/file>.  On success,
 170 B<ckpasswd> will print C<User:test> and exit with status 0.  On failure,
 171 it will print some sort of error message and exit a non-zero status.
 172
 173 =head1 HISTORY
 174
 175 Written by Russ Allbery <rra@stanford.edu> for InterNetNews.
 176
 177 $Id: ckpasswd.pod 7526 2006-08-12 22:31:11Z eagle $
 178
 179 =head1 SEE ALSO
 180
 181 readers.conf(5), nnrpd(8)
 182
 183 Linux users who want to use PAM should read the Linux-PAM System
 184 Administrator's Guide at
 185 L<http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/Linux-PAM_SAG.html>.
 186
 187 =cut