shadow/doc/README

[ $Id: README,v 1.3 1998/12/28 20:34:27 marekm Exp $ ]

This is the explanatory document for Julianne Frances Haugh's login
replacement, release 3.  This document was last updated 16 Feb 1997.

This software is copyright 1988 - 1997, Julianne F. Haugh.  All rights
reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of Julianne F. Haugh nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY JULIE HAUGH AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL JULIE HAUGH OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

This source code is currently archived on ftp.uu.net in the
comp.sources.misc portion of the USENET archives.  You may also contact
the author, Julianne F. Haugh, at jfh@bga.com if you have any questions
regarding this package.

THIS SOFTWARE IS BEING DISTRIBUTED AS-IS.  THE AUTHORS DISCLAIM ALL
LIABILITY FOR ANY CONSEQUENCES OF USE.  THE USER IS SOLELY RESPONSIBLE
FOR THE MAINTENANCE OF THIS SOFTWARE PACKAGE.  THE AUTHORS ARE UNDER NO
OBLIGATION TO PROVIDE MODIFICATIONS OR IMPROVEMENTS.  THE USER IS
ENCOURAGED TO TAKE ANY AND ALL STEPS NEEDED TO PROTECT AGAINST ACCIDENTAL
LOSS OF INFORMATION OR MACHINE RESOURCES.

Special thanks are due to Chip Rosenthal for his fine testing efforts;
to Steve Simmons for his work in porting this code to BSD; and to Bill
Kennedy for his contributions of LaserJet printer time and energies.
Also, thanks for Dennis L. Mumaugh for the initial shadow password
information and to Tony Walton (olapw@olgb1.oliv.co.uk) for the System
V Release 4 changes.  Effort in porting to SunOS has been contributed
by Dr. Michael Newberry (miken@cs.adfa.oz.au) and Micheal J. Miller, Jr.
(mke@kaberd.rain.com).  Effort in porting to AT&T UNIX System V Release
4 has been provided by Andrew Herbert (andrew@werple.pub.uu.oz.au).
Special thanks to Marek Michalkiewicz (marekm@i17linuxb.ists.pwr.wroc.pl)
for taking over the Linux port of this software.

New for Release 3.3:
	User-defined authentication has been added.  This allows you to
	write programs to replace the password authentication method
	which uses the crypt() function.

	The CrackLib password checking library is supported as of release
	3.3.0.  It allows you to perform pro-active password checking as
	each password is changed.

Warning:
	The newuser command will be removed in a later release.
	The libsec.a library will be removed at some point after
	  version 3.3.3.

This software is described in the 3rd USENIX Security Symposium
proceedings.  These proceedings are available from

	USENIX Association
	2560 Ninth Street, Suite 215
	Berkeley, CA 94710

The current price is $30 for USENIX members and $39 for non-members.

Begin by reading and editing the config.h file.  All options are selected
by using #define's.  A brief description for each available option appears
below.  You may want to print this file out as it is LONG and you will
need to refer to it while editting config.h.  You will also have to edit
the Makefile.  The possible differences are documented there.  Pay close
attention to the install: rule.  Login now runs on about 30 different
varieties of UNIX that I have been made aware of.  If you have any qualms,
you should run "make save" before running "make install".  If something
breaks you can use "make restore" to put things back.  In any case, you
should have a recent system backup as the potential for serious damage
exists.

There are special Makefile and config.h files for SVR4, SunOS 4.1, and
Linux systems.  If there is a major UNIX variant that you would like to
see supported, please send working Makefile and config.h files and I will
try to include then in the base distribution.

Note that there are MANY options.  As distributed most options are turned
on, which produces a really nice package.  This is the system as used on
some of the authors' machines.  There are many options which may be
selected at run time.  You should refer to the login.5 manual page for
more information regarding these options.

There are several files which you may have to replace.  If your system has
a lastlog.h file, you should replace the one which I provide with your
system version.  The pwd.h file that is produced by "make" must agree
exactly with the system supplied version.  You should re-arrange the
fields or #define's until they match.  The same is true for "shadow.h",
if you system provides one.  You may want to replace large portions of
that file (or the entire file) with your system version.  It is provided
for those systems which do NOT provide /usr/include/shadow.h.  If you
do not have a the crypt() function in your library (perhaps because you
are located outside the United States), you may wish to look into the
UFC-crypt package which was posted to comp.sources.misc in volume 23,
issues 97 and 98.

Login Defaults File -
	This option selects the name of the file to read for the
	run-time configurable options.  The default value for
	LOGINDEFS is "/etc/login.defs".

Shadow [ unreadable ] Password Files -
	This option utilizes an alternate, non-readable file to
	contain the actual encrypted passwords.  This is presumed
	to increase system security by increasing the difficulty
	with which system crackers obtain encrypted passwords.

	Select this option by defining the SHADOWPWD macro.

	This feature is optional, but only certain commands may
	be compiled with this option disabled.

Shadow Group Files -
	This option utilizes an alternate, non-readable file to
	contain encrypted group passwords and group administrator
	information.

	This feature allows one or more users to be defined as
	the administrators of a group for the purpose of adding
	or deleting members and changing the group password.

	Select this option by defining the SHADOWGRP macro.  You
	must also create an emptry /etc/gshadow file.  You must
	select the SHADOWPWD option if you select SHADOWGRP.

DBM Password Files -
	This option utilizes the DBM database access routines to
	increase the performance of user name and ID lookups in the
	password file.  You may select the NDBM database instead
	and have DBM-style access to all user information files.

	Select this option by defining both the DBM and GETPWENT
	macros.  The FGETPWENT macro must also be defined or the
	fgetpwent() library routine must be present.

Double Length Passwords -
	This option extends the maximum length of a user password
	to 16 characters from eight.

	Select this option by defining the DOUBLESIZE macro.
	Credit for this option is due Jonathan Bayer.

Password Aging -
	This option includes code to perform password aging.
	Password aging is presumed to increase system security
	by forcing users to change passwords on a regular
	basis.  The resolution on password age is in weeks for
	non-shadow password systems and in days otherwise.

	Select this option by defining the AGING macro.

Syslog -
	This option causes the code to log various errors or
	special conditions to the syslog daemon.  The types of
	information that are logged security violations, changes
	to the user database, and program errors.

	Select syslog processing by defining the USE_SYSLOG
	macro.

Remote Login -
	This option causes certain network login code to be
	inserted to enable the "rlogin" and "telnet" commands to
	work.  To enable network logins, define the RLOGIN macro.
	If your <utmp.h> file includes a ut_host member, you must
	also define the UT_HOST macro.  Note that SVR4 has a
	"utmpx" file to hold the ut_host member, so UT_HOST is
	not required.

Directory Reading Routines -
	Three different macros are defined for opening and reading
	directories.  They are DIR_XENIX, DIR_BSD, and DIR_SYSV.
	Refer to config.h for more details.

Library Configuration Macros -
	The following macros define the functions which are present
	in your system library:

	HAVE_ULIMIT	- Define if your UNIX supports ulimit()
	GETPWENT	- Define if you want my GETPWENT(3) routines
	GETGRENT	- Define if you want my GETGRENT(3) routines
	NEED_AL64	- Define if library does not include a64l()
	NEED_MKDIR	- Define if system does not have mkdir()
	NEED_RMDIR	- Define if system does not have rmdir()
	NEED_RENAME	- Define if system does not have rename()
	NEED_STRSTR	- Define if library does not include strstr()

Password File Information -
	The following macros define the fields which are present in
	your system password file.  Because the system was compiled
	to use the password file in its original form, these macros
	must agree with the actual contents of the file.

	BSD_QUOTA	- the pw_quota field exists
	ATT_AGE		- the pw_age field exists
	ATT_COMMENT	- the pw_comment field exists

Signal Return Type -
	Because different systems return different data types for
	the signal() system call, you must define SIGTYPE to be
	the data type your system uses.  The default is "int", but
	"void" is another popular value.

SunOS 4.1.1 Notes: (mke@kaberd.rain.com) Michael J. Miller Jr.

[ These notes were edited from the original.  The standard Makefile
  and config.h have notes indicating the changes required for SunOS.
  Steve Allen at Lick has been working on cleaning up this platform. ]

You'll need to do the following to get the shadow password dist to
compile on a sun 4.1.1 system.

If using csh, then type 'rehash'.  cd to the /etc directory and type
'pwconv'.  This will create two files,  nshadow and npasswd.
now type 'mkpasswd -f nshadow' and 'mkpasswd -f npasswd'.  This will
create the shadow password file.

Note: ftp will still use the old password file.  Modified versions of
      ftpd are available, or you may modify the version of ftpd from
      any of the freely redistributable ftpd clones.

Note: If you run suns pcnfs, be aware that it will still be looking at the
      old password file as well.  I may work out a patch for this, as I am
      fairly certain the stuff on the sun side comes with source.

Note: I have compiled this package with the standard c compiler and
      suns unbundled c compiler at an optomization level of 2 in
      both casses.  Haven't tried gcc yet, so I don't know wether it
      works.  Same goes for suns C++ compiler.

Note: Has been compiled on a sun 3/75 running sunos 4.1.1.  Should compile
      fine on sun 4's running 4.1.1, and may compile on suns running
      4.1.  Have no idea what sort of success people will have that
      are running 4.03 and older versions.