Initial import of KTH eBones. This has been cleaned up to only include

the "core" Kerberos functionality. The rest of the userland will get their
own changes later.

1 files changed, 368 insertions, 0 deletions

diff --git a/crypto/kerberosIV/doc/install.texi b/crypto/kerberosIV/doc/install.texi
new file mode 100644
index 0000000..240c04e
--- /dev/null
+++ b/crypto/kerberosIV/doc/install.texi
@@ -0,0 +1,368 @@
+@node Installing programs, How to set up a realm, What is Kerberos?, Top
+@chapter Installing programs
+
+You have a choise to either build the distribution from source code or
+to install binaries, if they are available for your machine.
+
+@c XXX
+
+We recommend building from sources, but using pre-compiled binaries
+might be easier.  If there are no binaries available for your machine or
+you want to do some specific configuration, you will have to compile
+from source.
+
+@menu
+* Installing from source::      
+* Installing a binary distribution::  
+* Finishing the installation::  
+* Authentication modules::      
+@end menu
+
+@node Installing from source, Installing a binary distribution, Installing programs, Installing programs
+@comment  node-name,  next,  previous,  up
+@section Installing from source
+
+To build this software un-tar the distribution and run the
+@code{configure} script.
+
+To compile successfully, you will need an ANSI C compiler, such as
+@code{gcc}. Other compilers might also work, but setting the ``ANSI
+compliance'' too high, might break in parts of the code, not to mention
+the standard include files.
+
+To build in a separate build tree, run @code{configure} in the directory
+where the tree should reside.  You will need a Make that understands
+VPATH correctly.  GNU Make works fine.
+
+After building everything (which will take anywhere from a few minutes
+to a long time), you can install everything in @file{/usr/athena} with
+@kbd{make install} (running as root). It is possible to install in some
+other place, but it isn't recommended. To do this you will have to run
+@code{configure} with @samp{--prefix=/my/path}.
+
+If you need to change the default behavior, configure understands the
+following options:
+
+@table @asis
+@item @kbd{--with-shared}
+Create shared versions of the Kerberos libraries. Not really
+recommended and might not work on all systems.
+
+@item @kbd{--with-cracklib=}@var{dir}
+Use cracklib for password quality control in 
+@pindex kadmind
+@code{kadmind}. This option requires 
+@cindex cracklib
+cracklib with the patch from
+@code{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}.
+
+@item @kbd{--with-dictpath=}@var{dictpath}
+This is the dictionary that cracklib should use.
+
+@item @kbd{--with-socks=}@var{dir}
+@cindex firewall
+@cindex socks
+If you have to traverse a firewall and it uses the SocksV5 protocol
+(@cite{RFC 1928}), you can build with socks-support.  Point @var{dir} to
+the directory where you have socks5 installed.  For more information
+about socks see @kbd{http://www.socks.nec.com/}.
+
+@item @kbd{--with-readline=}@var{dir}
+@cindex readline
+To enable history/line editing in @code{ftp} and @code{kadmin}, any
+present version of readline will be used.  If you have readline
+installed but in a place where configure does not managed to find it,
+you can use this option.  The code also looks for @code{libedit}.  If
+there is no library at all, the bundled version of @code{editline} will
+be used.
+
+@item @kbd{--with-mailspool=}@var{dir}
+The configuration process tries to determine where your machine stores
+its incoming mail.  This is typically @file{/usr/spool/mail} or
+@file{/var/mail}.  If it does not work or you store your mail in some
+unusual directory, this option can be used to specify where the mail
+spool directory is located.  This directory is only accessed by
+@pindex popper
+@code{popper}, and the mail check in
+@pindex login
+@code{login}.
+
+@c @item @kbd{--enable-random-mkey}
+@c Do not use this option unless you think you know what you are doing.
+
+@item @kbd{--with-mkey=}@var{file}
+Put the master key here, the default is @file{/.k}.
+
+@item @kbd{--without-berkeley-db}
+If you have
+@cindex Berkeley DB
+Berkeley DB installed, it is preferred over
+@c XXX
+dbm. If you already are running Kerberos this option might be useful,
+since there currently isn't an easy way to convert a dbm database to a
+db one (you have to dump the old database and then load it with the new
+binaries).
+@end table
+
+@node Installing a binary distribution, Finishing the installation, Installing from source, Installing programs
+@comment  node-name,  next,  previous,  up
+@section Installing a binary distribution
+
+The binary distribution is supposed to be installed in
+@file{/usr/athena}, installing in some other place may work but is not
+recommended.  A symlink from @file{/usr/athena} to the install directory
+should be fine.
+
+@node Finishing the installation, Authentication modules, Installing a binary distribution, Installing programs
+@section Finishing the installation
+
+@pindex su
+The only program that needs to be installed setuid to root is @code{su}.
+
+If 
+@pindex rlogin
+@pindex rsh
+@code{rlogin} and @code{rsh} are setuid to root they will fall back to
+non-kerberised protocols if the kerberised ones fail for some
+reason. The old protocols use reserved ports as security, and therefore
+the programs have to be setuid to root. If you don't need this
+functionality consider turning off the setuid bit.
+
+@pindex login
+@code{login} does not have to be setuid, as it is always run by root
+(users should use @code{su} rather than @code{login}).  It will print a
+helpful message when not setuid to root and run by a user.
+
+The programs intended to be run by users are located in
+@file{/usr/athena/bin}.  Inform your users to include
+@file{/usr/athena/bin} in their paths, or copy or symlink the binaries
+to some good place.  The programs that you will want to use are:
+@code{kauth}/@code{kinit},
+@pindex kauth
+@pindex kinit
+@code{klist}, @code{kdestroy}, @code{kpasswd}, @code{ftp},
+@pindex klist
+@pindex kdestroy
+@pindex kpasswd
+@pindex ftp
+@code{telnet}, @code{rcp}, @code{rsh}, @code{rlogin}, @code{su},
+@pindex telnet
+@pindex rcp
+@pindex rsh
+@pindex rlogin
+@pindex su
+@pindex xnlock
+@pindex afslog
+@pindex pagsh
+@pindex rxtelnet
+@pindex tenletxr
+@pindex rxterm
+@code{rxtelnet}, @code{tenletxr}, @code{rxterm}, and
+@code{xnlock}. If you are using AFS, @code{afslog} and @code{pagsh}
+might also be useful.  Administrators will want to use @code{kadmin} and
+@code{ksrvutil}, which are located in @file{/usr/athena/sbin}.
+@pindex kadmin
+@pindex ksrvutil
+
+@code{telnetd} and @code{rlogind} assume that @code{login} is located in
+@file{/usr/athena/bin} (or whatever path you used as
+@samp{--prefix}). If for some reason you want to move @code{login}, you
+will have to specify the new location with the @samp{-L} switch when
+configuring
+@pindex telnetd
+telnetd
+and
+@pindex rlogind
+rlogind
+in @file{inetd.conf}.
+
+It should be possible to replace the system's default @code{login} with
+the kerberised @code{login}.  However some systems assume that login
+performs some serious amount of magic that our login might not do (although
+we've tried to do our best). So before replacing it on every machine,
+try and see what happens.  Another thing to try is to use one of the
+authentication modules (@xref{Authentication modules}) supplied.
+
+The @code{login} program that we use was in an earlier life the standard
+login program from NetBSD. In order to use it with a lot of weird
+systems, it has been ``enhanced'' with features from many other logins
+(Solaris, SunOS, IRIX, AIX, and others).  Some of these features are
+actually useful and you might want to use them even on other systems.
+
+@table @file
+@item /etc/fbtab
+@pindex fbtab
+@itemx /etc/logindevperm
+@pindex logindevperm
+Allows you to chown some devices when a user logs in on a certain
+terminal.  Commonly used to change the ownership of @file{/dev/mouse},
+@file{/dev/kbd}, and other devices when someone logs in on
+@file{/dev/console}.
+
+@file{/etc/fbtab} is the SunOS file name and it is tried first.  If
+there is no such file then the Solaris file name
+@file{/etc/logindevperm} is tried.
+@item /etc/environment
+@pindex environment
+This file specifies what environment variables should be set when a user
+logs in. (AIX-style)
+@item /etc/default/login
+@pindex default/login
+Almost the same as @file{/etc/environment}, but the System V style.
+@item /etc/login.access
+@pindex login.access
+Can be used to control who is allowed to login from where and on what
+ttys. (From Wietse Venema)
+@end table
+
+@menu
+* Authentication modules::      
+@end menu
+
+@node  Authentication modules,  , Finishing the installation, Installing programs
+@comment  node-name,  next,  previous,  up
+@section Authentication modules
+The problem of having different authentication mechanisms has been
+recognised by several vendors, and several solutions has appeared. In
+most cases these solutions involve some kind of shared modules that are
+loaded at run-time.  Modules for some of these systems can be found in
+@file{lib/auth}.  Presently there are modules for Digital's SIA, Linux'
+PAM (might also work on Solaris, when PAM gets supported), and IRIX'
+@code{login} and @code{xdm} (in @file{lib/auth/afskauthlib}).
+
+@menu
+* Digital SIA::                 
+* IRIX::                        
+* PAM::                         
+@end menu
+
+@node Digital SIA, IRIX, Authentication modules, Authentication modules
+@subsection Digital SIA
+
+To install the SIA module you will have to do the following:
+
+@itemize @bullet
+
+@item
+Make sure @file{libsia_krb4.so} is available in
+@file{/usr/athena/lib}. If @file{/usr/athena} is not on local disk, you
+might want to put it in @file{/usr/shlib} or someplace else. If you do,
+you'll have to edit @file{krb4_matrix.conf} to reflect the new location
+(you will also have to do this if you installed in some other directory
+than @file{/usr/athena}).
+@item
+Copy (your possibly edited) @file{krb4_matrix.conf} to @file{/etc/sia}.
+@item
+Apply @file{security.patch} to @file{/sbin/init.d/security}.
+@item
+Turn on KRB4 security by issuing @kbd{rcmgr set SECURITY KRB4} and
+@kbd{rcmgr set KRB4_MATRIX_CONF krb4_matrix.conf}.
+@item
+Digital thinks you should reboot your machine, but that really shouldn't
+be necessary.  It's usually sufficient just to run
+@kbd{/sbin/init.d/security start}.
+@end itemize
+
+Users with local passwords (like @samp{root}) should be able to login
+safely.
+
+When using Digital's xdm the @samp{KRBTKFILE} environment variable isn't
+passed along as it should (since xdm zaps the environment). Instead you
+have to set @samp{KRBTKFILE} to the correct value in
+@file{/usr/lib/X11/xdm/Xsession}. Add a line similar to
+@example
+KRBTKFILE=/tmp/tkt`id -u`_`ps -o ppid= -p $$`; export KRBTKFILE
+@end example
+
+There is currently no support for changing passwords. Use @file{kpasswd}
+instead.
+
+@subsubheading Notes to users with Enhanced security
+
+Digital's @samp{ENHANCED} (C2) security, and Kerberos solves two
+different problems. C2 deals with local security, adds better control of
+who can do what, auditing, and similar things. Kerberos deals with
+network security.
+
+To make C2 security work with Kerberos you will have to do the
+following.
+
+@itemize @bullet
+@item
+Replace all occurencies of @file{krb4_matrix.conf} with
+@file{krb4+c2_matrix.conf} in the directions above.
+@item
+You must enable ``vouching'' in the @samp{default} database.  This will
+make the OSFC2 module trust other SIA modules, so you can login without
+giving your C2 password. To do this use @samp{edauth} to edit the
+default entry @kbd{/usr/tcb/bin/edauth -dd default}, and add a
+@samp{d_accept_alternate_vouching} capability, if not already present.
+@item
+For each user that does @emph{not} have a local C2 password, you should
+set the password expiration field to zero. You can do this for each
+user, or in the @samp{default} table. To to this use @samp{edauth} to
+set (or change) the @samp{u_exp} capability to @samp{u_exp#0}.
+@item
+You should make sure that you use Digital's login rather than the one
+distributed by us. The easiest way to do this is to replace
+@file{/usr/athena/bin/login} with @file{/bin/login}.
+@end itemize
+
+At present @samp{su} does not accept the vouching flag, so it will not
+work as expected. 
+
+Also, kerberised ftp will not work with C2 passwords. You can solve this
+by using both Digital's ftpd and our on different ports.
+
+@strong{Remember}, if you do these changes you will get a system that
+most certainly does @emph{not} fulfill the requirements of a C2
+system. If C2 is what you want, for instance if someone else is forcing
+you to use it, you're out of luck.  If you use enhanced security because
+you want a system that is more secure than it would otherwise be, you
+probably got an even more secure system. Passwords will not be sent in
+the clear, for instance.
+
+@node IRIX, PAM, Digital SIA, Authentication modules
+@subsection IRIX
+
+The IRIX support is a module that is compatible with Transarc's
+@file{afskauthlib.so}.  It should work with all programs that use this
+library, this should include @file{login} and @file{xdm}.
+
+The interface is not very documented but it seems that you have to copy
+@file{libkafs.so}, @file{libkrb.so}, and @file{libdes.so} to
+@file{/usr/lib}, or build your @file{afskauthlib.so} statically.
+
+The @file{afskauthlib.so} itself is able to reside in
+@file{/usr/vice/etc}, @file{/usr/afsws/lib}, or the current directory
+(wherever that is).
+
+Appart from this it should ``just work'', there are no configuration
+files.
+
+@node PAM,  , IRIX, Authentication modules
+@subsection PAM
+
+The PAM module was written more out of curiosity that anything else. It
+has not been updated for quite a while, since none of us are using
+Linux, and Solaris does not support PAM yet.  We've had positive reports
+from at least one person using the module, though.
+
+To use this module you should:
+
+@itemize @bullet
+@item
+Make sure @file{pam_krb4.so} is available in @file{/usr/athena/lib}. You
+might actually want it on local disk, so @file{/lib/security} might be a
+better place if @file{/usr/athena} is not local.
+@item
+Look at @file{pam.conf.add} for examples of what to add to
+@file{/etc/pam.conf}.
+@end itemize
+
+There is currently no support for changing kerberos passwords. Use
+kpasswd instead.
+
+See also Derrick J Brashear's @code{<shadow@@dementia.org>} Kerberos PAM
+module at @kbd{ftp://ftp.dementia.org/pub/pam}. It has a lot more
+features, and it is also more in line with other PAM modules.