.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CKPASSWD 8" .TH CKPASSWD 8 2024-04-01 "INN 2.7.2" "InterNetNews Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME ckpasswd \- nnrpd password authenticator .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fBckpasswd\fR [\fB\-gs\fR] [\fB\-d\fR \fIdatabase\fR] [\fB\-f\fR \fIfilename\fR] [\fB\-u\fR \fIusername\fR \fB\-p\fR \fIpassword\fR] .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBckpasswd\fR is the basic password authenticator for \fBnnrpd\fR, suitable for being run from an auth stanza in \fIreaders.conf\fR. See readers.conf(5) for more information on how to configure an \fBnnrpd\fR authenticator. .PP \&\fBckpasswd\fR accepts a username and password from \fBnnrpd\fR 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). .PP When using PAM, \fBckpasswd\fR identifies itself as \f(CW\*(C`nnrpd\*(C'\fR, not as \&\f(CW\*(C`ckpasswd\*(C'\fR, 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. .PP When using any method other than PAM, \fBckpasswd\fR 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. Any password hashing algorithm supported by your libc or libcrypt can be used. .SH OPTIONS .IX Header "OPTIONS" .IP "\fB\-d\fR \fIdatabase\fR" 4 .IX Item "-d database" Read passwords from a database (ndbm, gdbm or dbm format depending on what your system has) rather than by using getpwnam(3). \fBckpasswd\fR expects \fIdatabase\fR.dir and \fIdatabase\fR.pag to exist and to be a database keyed by username with the encrypted passwords as the values. .Sp 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: .Sp .Vb 10 \& #!/usr/bin/perl \& use NDBM_File; \& use Fcntl; \& tie (%db, \*(AqNDBM_File\*(Aq, \*(Aq/path/to/database\*(Aq, O_RDWR|O_CREAT, 0640) \& or die "Cannot open /path/to/database: $!\en"; \& $| = 1; \& print "Username: "; \& my $user = ; \& chomp $user; \& print "Password: "; \& my $passwd = ; \& chomp $passwd; \& my @alphabet = (\*(Aq.\*(Aq, \*(Aq/\*(Aq, 0..9, \*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq); \& my $salt = join \*(Aq\*(Aq, @alphabet[rand 64, rand 64]; \& $db{$user} = crypt ($passwd, $salt); \& untie %db; .Ve .Sp 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 \&\fBdbmpasswd\fR. .Sp This option will not be available on systems without ndbm, gdbm or dbm libraries. .IP "\fB\-f\fR \fIfilename\fR" 4 .IX Item "-f filename" Read passwords from the given file rather than using getpwnam(3). Each line of the file should look something like: .Sp .Vb 2 \& username:$5$Hlb2yXPd$2nOO/QR9P1mnRFr/i6L9ybxbgSDXd4UlatKqbcY4eoB \& joe:FCjOJnpOo50IE:Old weak hash algorithm used for Joe .Ve .Sp Each line has at least two fields separated by a colon. The first field contains the username; the second field contains a password hashed with the crypt(3) function. Additional colons and data may appear after the encrypted password; that data will be ignored by \fBckpasswd\fR. Lines starting with a number sign (\f(CW\*(C`#\*(C'\fR) are ignored. .Sp INN does not come with a utility to create the encrypted passwords, but OpenSSL can do so and it's also a quick job with Perl (see the one-line example script below). .Sp A line in \fIfilename\fR for the user \f(CW\*(C`user\*(C'\fR with the password \f(CW\*(C`pass\*(C'\fR would be \&\f(CW\*(C`user:\*(C'\fR followed with the output of the following command using SHA\-256 as hashing scheme: .Sp .Vb 2 \& % openssl passwd \-5 pass \& $5$UIhtJSBOaC0Ap3Vk$nbKgmykshoQ2HmvA3s/nI.X4uhhNHBKTYhBS3pYLjJ6 .Ve .Sp See the openssl\-passwd(1) man page for the list of hashing schemes it can generate. You must take one that your system crypt(3) function handles (type \&\f(CW\*(C`man 3 crypt\*(C'\fR or \f(CW\*(C`man 5 crypt\*(C'\fR to find the supported hashing schemes). .Sp In case OpenSSL is not installed on your server, you can also use the following Perl command which does the same job with SHA\-256 (see details below to set \f(CW\*(C`YourSalt\*(C'\fR to an appropriate value; \f(CW\*(C`5\*(C'\fR is the prefix for SHA\-256, which does not expect any parameters): .Sp .Vb 2 \& % perl \-le \*(Aqprint crypt("pass", q{$5$YourSalt$})\*(Aq \& $5$YourSalt$V5hqwFg1nhKb5as6md9KTe5b2NyavsMS6dBYVKfp5W7 .Ve .Sp As Perl makes use of crypt(3), you have access to all available hashing schemes on your systems. For instance, if yescript is supported, you can generate an encrypted password with an argument like \f(CW\*(C`$y$j9T$YourSalt$\*(C'\fR to Perl crypt function, where \f(CW\*(C`y\*(C'\fR is the prefix for yescript, \f(CW\*(C`j9T\*(C'\fR the parameters passed to crypt_gensalt(3) to generate the hashed password (these parameters control the yescript configuration, and correspond in this example to the \f(CW\*(C`YESCRYPT_DEFAULTS\*(C'\fR flag, the recommended flavor which has \f(CW\*(C`j\*(C'\fR value in 2023, with cost factor of 4096 as block count and 32 as block size) and \&\f(CW\*(C`YourSalt\*(C'\fR a string which should be chosen at random and different for each user. The syntax and optimal length of the salt depend on the hashing scheme (e.g. a length multiple of 4 for yescript) and cryptographic recommendations (e.g. at least 32 random bits in length, following NIST SP\ 800\-63B recommendations in 2023). .Sp To put it in a nutshell, in the following command, you only have to change the password \f(CW\*(C`pass\*(C'\fR and the \f(CW\*(C`YourSalt\*(C'\fR random string, different for \fBeach\fR user, and leave the rest of the command as-is: .Sp .Vb 2 \& % perl \-le \*(Aqprint crypt("pass", q{$y$j9T$YourSalt$})\*(Aq \& $y$j9T$YourSalt$X4tB48vKNDT6mK0vNOc7ppKPWvEsyMg5LwoQfO50r2A .Ve .Sp A random salt of 12 characters can be obtained with the following command (the result corresponds to 72 random bits as each character is selected in a 6\-bit range of 64 possible characters): .Sp .Vb 3 \& % perl \-le \*(Aqprint join("", \& (".", "/", 0..9, A..Z, a..z)[map {rand 64} (1..12)])\*(Aq \& k2W/17eJu58r .Ve .IP \fB\-g\fR 4 .IX Item "-g" Attempt to look up system group corresponding to username and return a string like \f(CW\*(C`user@group\*(C'\fR to be matched against in \fIreaders.conf\fR. This option is incompatible with the \fB\-d\fR and \fB\-f\fR options. .IP "\fB\-p\fR \fIpassword\fR" 4 .IX Item "-p password" Use \fIpassword\fR as the password for authentication rather than reading a password using the \fBnnrpd\fR 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 \&\fBckpasswd\fR is run by \fBnnrpd\fR. If this option is given, \fB\-u\fR must also be given. .IP \fB\-s\fR 4 .IX Item "-s" Check passwords against the result of getspnam(3) instead of getpwnam(3). This function, on those systems that supports it, reads from \fI/etc/shadow\fR 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. .Sp Most systems require special privileges to call getspnam(3), so in order to use this option you may need to make \fBckpasswd\fR setgid to some group (like group \f(CW\*(C`shadow\*(C'\fR) or even setuid root. \fBckpasswd\fR 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. .Sp This configuration is not recommended if it can be avoided, for serious security reasons. See "SECURITY CONSIDERATIONS" in readers.conf(5) for discussion. .IP "\fB\-u\fR \fIusername\fR" 4 .IX Item "-u username" Authenticate as \fIusername\fR. This option is useful only for testing (so that you can test your authentication system easily) and does not work when \fBckpasswd\fR is run by \fBnnrpd\fR. If this option is given, \fB\-p\fR must also be given. .SH EXAMPLES .IX Header "EXAMPLES" See readers.conf(5) for examples of nnrpd(8) authentication configuration that uses \fBckpasswd\fR to check passwords. .PP An example PAM configuration for \fI/etc/pam.conf\fR that tells \fBckpasswd\fR to check usernames and passwords against system accounts is: .PP .Vb 2 \& nnrpd auth required pam_unix.so \& nnrpd account required pam_unix.so .Ve .PP Your system may want you to instead create a file named \fInnrpd\fR in \&\fI/etc/pam.d\fR with lines like: .PP .Vb 2 \& auth required pam_unix.so \& account required pam_unix.so .Ve .PP 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 \fBckpasswd\fR. The best guide is the documentation for your system and the other PAM configurations you're already using. .PP To test to make sure that \fBckpasswd\fR is working correctly, you can run it manually and then give it the username (prefixed with \f(CW\*(C`ClientAuthname:\*(C'\fR) and password (prefixed with \f(CW\*(C`ClientPassword:\*(C'\fR) on standard input. For example: .PP .Vb 2 \& (echo \*(AqClientAuthname: test\*(Aq ; echo \*(AqClientPassword: testing\*(Aq) \e \& | ckpasswd \-f /path/to/passwd/file .Ve .PP will check a username of \f(CW\*(C`test\*(C'\fR and a password of \f(CW\*(C`testing\*(C'\fR against the username and passwords stored in \fI/path/to/passwd/file\fR. On success, \&\fBckpasswd\fR will print \f(CW\*(C`User:test\*(C'\fR and exit with status \f(CW\*(C`0\*(C'\fR. On failure, it will print some sort of error message and exit a non-zero status. .SH HISTORY .IX Header "HISTORY" Written by Russ Allbery for InterNetNews. .SH "SEE ALSO" .IX Header "SEE ALSO" crypt(3), nnrpd(8), pam(7), readers.conf(5).