doc/man/ckpasswd.8

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "CKPASSWD 8"
 132 .TH CKPASSWD 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
 133 .SH "NAME"
 134 ckpasswd \- nnrpd password authenticator
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBckpasswd\fR [\fB\-gs\fR] [\fB\-d\fR \fIdatabase\fR] [\fB\-f\fR \fIfilename\fR]
 138 [\fB\-u\fR \fIusername\fR \fB\-p\fR \fIpassword\fR]
 139 .SH "DESCRIPTION"
 140 .IX Header "DESCRIPTION"
 141 \&\fBckpasswd\fR is the basic password authenticator for nnrpd, suitable for
 142 being run from an auth stanza in \fIreaders.conf\fR.  See \fIreaders.conf\fR\|(5) for
 143 more information on how to configure an nnrpd authenticator.
 144 .PP
 145 \&\fBckpasswd\fR accepts a username and password from nnrpd and tells \fInnrpd\fR\|(8)
 146 whether that's the correct password for that username.  By default, when
 147 given no arguments, it tries to check the password using \s-1PAM\s0 if support
 148 for \s-1PAM\s0 was found when \s-1INN\s0 was built.  Failing that, it tries to check the
 149 password against the password field returned by \fIgetpwnam\fR\|(3).  Note that
 150 these days most systems no longer make real passwords available via
 151 \&\fIgetpwnam\fR\|(3) (some still do if and only if the program calling \fIgetpwnam\fR\|(3)
 152 is running as root).
 153 .PP
 154 When using \s-1PAM\s0, \fBckpasswd\fR identifies itself as \f(CW\*(C`nnrpd\*(C'\fR, not as
 155 \&\f(CW\*(C`ckpasswd\*(C'\fR, and the \s-1PAM\s0 configuration must be set up accordingly.  The
 156 details of \s-1PAM\s0 configuration are different on different operating systems
 157 (and even different Linux distributions); see \s-1EXAMPLES\s0 below for help
 158 getting started, and look for a \fIpam\fR\|(7) or \fIpam.conf\fR\|(4) manual page on your
 159 system.
 160 .PP
 161 When using any method other than \s-1PAM\s0, \fBckpasswd\fR expects all passwords to
 162 be stored encrypted by the system \fIcrypt\fR\|(3) function and calls \fIcrypt\fR\|(3) on
 163 the supplied password before comparing it to the expected password.  \s-1IF\s0
 164 you're using a different password hash scheme (like \s-1MD5\s0), you must use
 165 \&\s-1PAM\s0.
 166 .SH "OPTIONS"
 167 .IX Header "OPTIONS"
 168 .IP "\fB\-d\fR \fIdatabase\fR" 4
 169 .IX Item "-d database"
 170 Read passwords from a database (ndbm or dbm format depending on what your
 171 system has) rather than by using \fIgetpwnam\fR\|(3).  \fBckpasswd\fR expects
 172 \&\fIdatabase\fR.dir and \fIdatabase\fR.pag to exist and to be a database keyed by
 173 username with the encrypted passwords as the values.
 174 .Sp
 175 While \s-1INN\s0 doesn't come with a program intended specifically to create such
 176 databases, on most systems it's fairly easy to write a Perl script to do
 177 so.  Something like:
 178 .Sp
 179 .Vb 16
 180 \&    #!/usr/bin/perl
 181 \&    use NDBM_File;
 182 \&    use Fcntl;
 183 \&    tie (%db, 'NDBM_File', '/path/to/database', O_RDWR|O_CREAT, 0640)
 184 \&        or die "Cannot open /path/to/database: $!\en";
 185 \&    $| = 1;
 186 \&    print "Username: ";
 187 \&    my $user = <STDIN>;
 188 \&    chomp $user;
 189 \&    print "Password: ";
 190 \&    my $passwd = <STDIN>;
 191 \&    chomp $passwd;
 192 \&    my @alphabet = ('.', '/', 0..9, 'A'..'Z', 'a'..'z');
 193 \&    my $salt = join '', @alphabet[rand 64, rand 64];
 194 \&    $db{$user} = crypt ($passwd, $salt);
 195 \&    untie %db;
 196 .Ve
 197 .Sp
 198 Note that this will echo back the password when typed; there are obvious
 199 improvements that could be made to this, but it should be a reasonable
 200 start.  Sometimes a program like this will be available with the name
 201 \&\fBdbmpasswd\fR.
 202 .Sp
 203 This option will not be available on systems without dbm or ndbm
 204 libraries.
 205 .IP "\fB\-f\fR \fIfilename\fR" 4
 206 .IX Item "-f filename"
 207 Read passwords from the given file rather than using \fIgetpwnam\fR\|(3).  The
 208 file is expected to be formatted like a system password file, at least
 209 vaguely.  That means each line should look something like:
 210 .Sp
 211 .Vb 1
 212 \&    username:pdIh9NCNslkq6
 213 .Ve
 214 .Sp
 215 (and each line may have an additional colon after the encrypted password
 216 and additional data; that data will be ignored by \fBckpasswd\fR).  Lines
 217 starting with a number sign (`#') are ignored.  \s-1INN\s0 does not come with a
 218 utility to create the encrypted passwords, but \fBhtpasswd\fR (which comes
 219 with Apache) can do so and it's a quick job with Perl (see the example
 220 script under \fB\-d\fR).  If using Apache's \fBhtpasswd\fR program, be sure to
 221 give it the \fB\-d\fR option so that it will use \fIcrypt\fR\|(3).
 222 .IP "\fB\-g\fR" 4
 223 .IX Item "-g"
 224 Attempt to look up system group corresponding to username and return a
 225 string like \*(L"user@group\*(R" to be matched against in \fIreaders.conf\fR.  This
 226 option is incompatible with the \fB\-d\fR and \fB\-f\fR options.
 227 .IP "\fB\-p\fR \fIpassword\fR" 4
 228 .IX Item "-p password"
 229 Use \fIpassword\fR as the password for authentication rather than reading a
 230 password using the nnrpd authenticator protocol.  This option is useful
 231 only for testing your authentication system (particularly since it
 232 involves putting a password on the command line), and does not work when
 233 \&\fBckpasswd\fR is run by \fBnnrpd\fR.  If this option is given, \fB\-u\fR must also
 234 be given.
 235 .IP "\fB\-s\fR" 4
 236 .IX Item "-s"
 237 Check passwords against the result of \fIgetspnam\fR\|(3) instead of \fIgetpwnam\fR\|(3).
 238 This function, on those systems that supports it, reads from /etc/shadow
 239 or similar more restricted files.  If you want to check passwords supplied
 240 to \fInnrpd\fR\|(8) against system account passwords, you will probably have to
 241 use this option on most systems.
 242 .Sp
 243 Most systems require special privileges to call \fIgetspnam\fR\|(3), so in order
 244 to use this option you may need to make \fBckpasswd\fR setgid to some group
 245 (like group \*(L"shadow\*(R") or even setuid root.  \fBckpasswd\fR has not been
 246 specifically audited for such uses!  It is, however, a very small program
 247 that you should be able to check by hand for security.
 248 .Sp
 249 This configuration is not recommended if it can be avoided, for serious
 250 security reasons.  See \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in readers.conf\&(5) for
 251 discussion.
 252 .IP "\fB\-u\fR \fIusername\fR" 4
 253 .IX Item "-u username"
 254 Authenticate as \fIusername\fR.  This option is useful only for testing (so
 255 that you can test your authentication system easily) and does not work
 256 when \fBckpasswd\fR is run by \fBnnrpd\fR.  If this option is given, \fB\-p\fR must
 257 also be given.
 258 .SH "EXAMPLES"
 259 .IX Header "EXAMPLES"
 260 See \fIreaders.conf\fR\|(5) for examples of \fInnrpd\fR\|(8) authentication configuration
 261 that uses \fBckpasswd\fR to check passwords.
 262 .PP
 263 An example \s-1PAM\s0 configuration for \fI/etc/pam.conf\fR that tells \fBckpasswd\fR
 264 to check usernames and passwords against system accounts is:
 265 .PP
 266 .Vb 2
 267 \&    nnrpd auth    required pam_unix.so
 268 \&    nnrpd account required pam_unix.so
 269 .Ve
 270 .PP
 271 Your system may want you to instead create a file named \fInnrpd\fR in
 272 \&\fI/etc/pam.d\fR with lines like:
 273 .PP
 274 .Vb 2
 275 \&    auth    required pam_unix.so
 276 \&    account required pam_unix.so
 277 .Ve
 278 .PP
 279 This is only the simplest configuration.  You may be able to include
 280 common shared files, and you may want to stack other modules, either to
 281 allow different authentication methods or to apply restrictions like lists
 282 of users who can't authenticate using \fBckpasswd\fR.  The best guide is the
 283 documentation for your system and the other \s-1PAM\s0 configurations you're
 284 already using.
 285 .PP
 286 To test to make sure that \fBckpasswd\fR is working correctly, you can run it
 287 manually and then give it the username (prefixed with \f(CW\*(C`ClientAuthname:\*(C'\fR)
 288 and password (prefixed with \f(CW\*(C`ClientPassword:\*(C'\fR) on standard input.  For
 289 example:
 290 .PP
 291 .Vb 2
 292 \&    (echo 'ClientAuthname: test' ; echo 'ClientPassword: testing') \e
 293 \&        | ckpasswd \-f /path/to/passwd/file
 294 .Ve
 295 .PP
 296 will check a username of \f(CW\*(C`test\*(C'\fR and a password of \f(CW\*(C`testing\*(C'\fR against the
 297 username and passwords stored in \fI/path/to/passwd/file\fR.  On success,
 298 \&\fBckpasswd\fR will print \f(CW\*(C`User:test\*(C'\fR and exit with status 0.  On failure,
 299 it will print some sort of error message and exit a non-zero status.
 300 .SH "HISTORY"
 301 .IX Header "HISTORY"
 302 Written by Russ Allbery <rra@stanford.edu> for InterNetNews.
 303 .PP
 304 $Id: ckpasswd.8 7880 2008-06-16 20:37:13Z iulius $
 305 .SH "SEE ALSO"
 306 .IX Header "SEE ALSO"
 307 \&\fIreaders.conf\fR\|(5), \fInnrpd\fR\|(8)
 308 .PP
 309 Linux users who want to use \s-1PAM\s0 should read the Linux-PAM System
 310 Administrator's Guide at
 311 <http://www.kernel.org/pub/linux/libs/pam/Linux\-PAM\-html/Linux\-PAM_SAG.html>.