chiark / gitweb /
debugging for thing that crashed
[innduct.git] / 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