source: trunk/third/cns/doc/kerbman.texinfo @ 8789

\input texinfo  

@finalout
@setfilename kerb-man

@ifinfo

@emph{Cygnus Network Security
---User and Administrator Documentation for CNS Version 1,}
by Cygnus Support.

CNS includes man pages and software developed at the Massachusetts
Institute of Technology, which includes this copyright information:

Copyright @copyright{} 1989 by the Massachusetts Institute of Technology
 
@quotation
Export of software employing encryption from the United States of
America is assumed to require a specific license from the United
States Government.  It is the responsibility of any person or
organization contemplating export to obtain such a license before
exporting.
@end quotation
 
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright
notice appear in all copies and that both that copyright notice and
this permission notice appear in supporting documentation, and that
the name of M.I.T. not be used in advertising or publicity pertaining
to distribution of the software without specific, written prior
permission.  M.I.T. makes no representations about the suitability of
this software for any purpose.  It is provided ``as is'' without express
or implied warranty.

Copyright @copyright{} 1991, 1992, 1994, 1995 Cygnus Support

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission 
notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore


Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@setchapternewpage odd
@settitle Cygnus Network Security
@titlepage
@finalout
@title Cygnus Network Security
@subtitle User and Administrator Documentation for CNS Version 1
@sp 2
@subtitle January 1995
@vfill
@author Mark Eichin
@author Pat McGregor
@author Cygnus Support

@page

@vskip 0pt plus 1filll

@emph{Cygnus Network Security
---User and Administrator Documentation for CNS Version 1,}
by Cygnus Support.

CNS includes man pages and software developed at the Massachusetts
Institute of Technology, which includes this copyright information:

Copyright @copyright{} 1989 by the Massachusetts Institute of Technology

@quotation
Export of software employing encryption from the United States of
America is assumed to require a specific license from the United
States Government.  It is the responsibility of any person or
organization contemplating export to obtain such a license before
exporting.
@end quotation

WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright
notice appear in all copies and that both that copyright notice and
this permission notice appear in supporting documentation, and that
the name of M.I.T. not be used in advertising or publicity pertaining
to distribution of the software without specific, written prior
permission.  M.I.T. makes no representations about the suitability of
this software for any purpose.  It is provided ``as is'' without express
or implied warranty.

Copyright @copyright{} 1992, 1994, 1995 Cygnus Support.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage

@ifinfo
@node Top
@top Cygnus Network Security

@menu
* Introduction::                A brief introduction to CNS
* User Programs::               General user applications
* Config Decisions::            Finding current realm and other realms
* Administration Tools::        Managing a realm
* Daemons::                     Providing Kerberos-based services
* Glossary::                    A brief description of Kerberos terms
* Authors::                     authors and contributors
* Appendix::                    SecureNet Key Authentication Device
@end menu
@end ifinfo

@node Introduction
@chapter Introduction

@menu
* CNS Description::     How does CNS work?
* Bibliography::        Where to get more information
@end menu

@quotation
@emph{@strong{Kerberos} The three-headed dog @dots{} guards the entrance
to Hades.  He kept the living from entering the infernal regions@dots{}}
@end quotation

@emph{---Dictionary of Classical Mythology--Zimmerman}

Today more than ever, system administrators must balance the ease and
convenience of Internet access, against the need for system security and
confidentiality.  There are many tools that can be used to reach and
manipulate information at remote sites.  Unscrupulous users can pervert
these tools to gain unauthorized access to connected systems.  It is
relatively easy, for example, to steal login IDs and unencrypted
passwords passing over the network during remote logins by legitimate
users.
 
Popular networking programs such as @code{rlogin}, @code{rsh}, and
@code{rcp}, were developed when there were few machines on the network,
and those were owned and managed by central organizations rather than
individuals.  At that time, the Internet was primarily a research
network, and it was reasonable to trust a machine's indication that it
was being used by a particular person.

This is no longer the case.  There are now millions of inexpensive,
individually owned, machines on the network.  In the current Internet
environment, it is no longer prudent to trust individual machines over
the network.  There is no assurance that such machines have adequately
verified their users, nor even that the machine is not being
impersonated by another.

Cygnus Support developed Cygnus Network Security (CNS) to provide strong
system access security, with minimal impact on users' ease of access.
Using Kerberos Version 4 encryption and client-server technology, CNS
assures that user identities can be checked securely without
transmitting passwords in clear over the network.

@node CNS Description
@section How does CNS work?

CNS is based on Kerberos.  Kerberos uses a single trusted server, which
other systems access over the network.  The Kerberos server
@dfn{authenticates} users and application servers.  It guarantees that
authorized users are who they say they are.  Kerberos sends this
information is sent across the network encrypted.  Each user and
application server has a unique secret encryption key it shares with the
Kerberos server.  These secret keys are based on the password of the
user or application server.  Kerberos never sends passwords across the
network in the clear (unencrypted).  Even if an attacker could examine
all data sent across the network, the attacker would not be able to
learn these passwords.@footnote{Kerberos authentication assumes the
Kerberos server is secure.  If an attacker gains superuser access to the
machine, the attacker may be able to masquerade as an authorized user.}

Kerberos provides users with @samp{tickets} they can use to identify
themselves to application servers.  A ticket is a sequence of several
hundred bytes encrypted for a particular user and application.  Kerberos
tickets can be embedded in most network protocol.@footnote{Practically
speaking, Kerberos is mostly used in application-level protocols [ISO
model level 7], such as TELNET or FTP, to provide user to host security.
It is also used as the implicit authentication system of data stream
[such as SOCK_STREAM] or RPC mechanisms [ISO model level 6].  It could
also be used at a lower level for host to host security, in protocols
like IP, UDP, or TCP [ISO model levels 3 and 4].  Such implementations
are rare, if they exist at all.}  Users must decrypt the tickets, using
their correct passwords, before the tickets can be used.@footnote{All
cryptographic manipulations are done by programs; all the CNS user has
to do is enter a password.}  The tickets also contain temporary secret
cryptographic keys (session keys) that permit secure communications
during individual transactions in addition to secure authentication.
This is important if you must type a password on the remote machine.
Using encryption ensures that an attacker watching the network does not
know what you type.  Encryption is optional because it is
computationally intensive, and thus slower.

Generally, the first ticket you get from the server is a
@dfn{ticket-granting ticket}.  It provides authentication to the
Kerberos server and permits users to get more tickets without having to
enter their passwords repeatedly.  (Kerberos keeps user passwords in
memory only long enough to obtain ticket-granting tickets.)  After the
ticket-granting ticket, subsequent tickets are issued automatically by
the Kerberos server at the request of CNS applications.  For example, if
you run the CNS @code{rlogin} program, which starts a login shell on a
remote machine, you automatically get a ticket for the @code{rlogin}
service on the remote machine.  The @code{klogind} daemon running on the
remote machine accepts the ticket as proof of identify and permits the
login (if CNS has been installed on the remote
machine).@footnote{Neither users nor application servers know each
others' cryptographic keys.}

There are Kerberos versions of other familiar network utilities such as
@code{rlogin}, @code{rcp} and @code{rsh}.  The @code{klogind} daemon is
an example of an @dfn{application server}.  Each application server has
a cryptographic keys with which to authenticate itself to the Kerberos
server.@footnote{Cryptographic keys are kept in a file (normally
@file{/etc/krb-srvtab}) on each machine which hosts application servers.
If an attacker becomes a superuser on a remote machine, the attacker can
replace the CNS daemon programs with programs that, for example, record
everything the user types.  This can only be done for application
servers which do not perform mutual authentication.  In general, the CNS
suite of programs perform mutual authentication when using encryption,
but not otherwise.}

Currently, CNS does not support authentication forwarding.  In other
words, if users use @code{rlogin} to login to a remote host, they cannot
use Kerberos services from that host unless they are authenticated on it
(for instance with @code{kinit}).  The user can obtain Kerberos tickets
on the remote host by running CNS programs there in the usual fashion,
but this requires typing a password.  Since this password is transmitted
over the network, this should only be done when using an encrypted
connection.

NOTE: Because CNS software contains DES encryption technology and
provides it as a user-callable facility, it may not be exported from the
US without a special license from the US Department of Commerce.

@node Bibliography
@section Bibliography

The papers listed below have good background information on the Kerberos
protocol and its use in a network environment. The Internet archive
information, when known, is listed at the end of the citation. This is
by no means an exhaustive list of information about Kerberos. Interested
systems administrators should consider reading the Usenet group
@emph{comp.protocols.kerberos}.

@noindent
Jennifer G. Steiner, Clifford Neuman, Jeffrey I. Schiller.
``Kerberos: An Authentication Service for Open Network Systems,'' 
@cite{USENIX Mar 1988}.  @file{athena-dist.mit.edu:pub/kerberos/doc/usenix.PS}

@noindent
S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. Saltzer, 
``Kerberos Authentication and Authorization System,'' 12/21/87.

@noindent
R. M. Needham and M. D.  Schroeder, ``Using Encryption for 
Authentication in Large Networks of Computers,'' @cite{Communications of the 
ACM}, Vol.  21(12), pp. 993-999 (December, 1978).
     
@noindent
V. L. Voydock and S. T. Kent, ``Security Mechanisms in High-Level 
Network Protocols,'' @cite{Computing Surveys}, Vol. 15(2), ACM (June 1983).

@noindent
Li Gong, ``A Security Risk of Depending on Synchronized Clocks,''
@cite{Operating Systems Review}, Vol 26, #1, pp 49--53.

@noindent
S.M. Bellovin and M. Merritt, ``Limitations of the Kerberos 
Authentication System,'' @cite{USENIX Jan 1991}. @*
@file{research.att.com: dist/internet_security/kerblimit.usenix.ps}

@noindent
Refik Molva, Gene Tsudik, Els Van Herreweghen, and Stefano 
Zatti, ``KryptoKnight Authentication and Key Distribution System.'' 
@file{jerico.usc.edu: pub/gene/kryptoknight.ps.Z}

@noindent
C. Neumann and J. Kohl, ``The Kerberos(tm) Network 
Authentication Service (V5),'' September 1993.  RFC1510.

@noindent
Barry Jaspan, @code{<bjaspan@@security.ov.com>}, compiler. @cite{Kerberos 
Users' Frequently Asked Questions}, January 18, 1994.
 
 
@c @subsubheading RESTRICTIONS
@c      COPYRIGHT 1985,1986 Massachusetts Institute of Technology

@node User Programs
@chapter User Programs

@menu
* CNS Intro::           Why do you need CNS? 
* Initial Steps::       Getting registered in CNS
* CNS for the User::    CNS for the User
* Replacements::        replacements for familiar network utilities
* Ticket Management Commands::  Kerberos-specific ticket management tools
@end menu

@node CNS Intro
@section Why do you need CNS?

As a network user accessing data on a remote machine, you want to be
certain that your password can only be used by you.  If you are hooked
into a remote machine with a direct connection, or a modem on a single
phone line linked into your remote machine, you can be relatively
confident that your password is secure.  However, if you use an
Ethernet-linked network, or use the Internet to access a remote host,
your password is at risk.  As we said in the introduction, one of the
easiest ways for your security to be compromised is by the theft of your
password and login ID.  Passwords and IDs can be stolen fairly easily by
using monitoring equipment on a network link.

CNS Kerberos technology allows you to be validated locally, rather than
having to send your passwords and login IDs over the network.  You
authenticate yourself locally to a Kerberos server, which vouches for
your authenticity with the remote host.  The remote host then lets you
use Kerberos versions of familiar remote login programs such as
@code{rlogin}.

@node Initial Steps
@section Initial Steps
 
Before you can use CNS, you must be registered in the Kerberos database.
If you are not sure if you are registered in the database, you may use
the @code{kinit} (@pxref{kinit}) command to find out.  This command
tries to get you a Kerberos `ticket-granting ticket'
(@pxref{Tickets,,Kerberos Tickets}).  @code{kinit} prompts you for a
principal name and password (for more information about Kerberos
principal names, @pxref{Principal names,,Your Kerberos principal name}).
If the Kerberos server issues you a ticket-granting ticket, you have
already been registered.

If you enter your username and @code{kinit} responds with this message:
@smallexample
Principal unknown (kerberos)
@end smallexample
@noindent
you have not been registered as a Kerberos user.  See your system 
administrator.

When your system administrator registers you in the CNS database, you
get a Kerberos username and password.  Many people use a different
password for Kerberos authentication than for their general system
login.  This is done to increase security.

@node CNS for the User
@section CNS for the User

@menu
* Tickets::             What are Kerberos tickets?
* Ticket management::   Using the commands `kinit' and `kdestroy'
* Passwords::           Kerberos password changing
* Principal names::     Your Kerberos principal name
* Remote access::       Remote login, shell, copy (secured by Kerberos)
@end menu

@node Tickets
@subsection Kerberos Tickets

When you authenticate yourself with Kerberos through the @code{kinit}
command, Kerberos gives you a special ticket called a `ticket-granting
ticket.'  (Kerberos tickets are encrypted protocol messages that provide
authentication.)  This special ticket allows you to get tickets for
application servers without having to enter your password again.  The
ticket-granting ticket can be used to get tickets for network utilities
such as @code{rlogin} and @code{rcp}.  The ticket transactions are done
transparently, so you do not have to worry about their management.

For security reasons, tickets expire.  This protects against users
accidentally leaving ticket files around on unattended
machines@footnote{Privileged tickets, such as @samp{root instance}
tickets, expire in a few minutes, while tickets that carry more ordinary
privileges may be good for several hours or a day, depending on the
installation's policy.}.  If your login session extends beyond the time
limit of your ticket-granting ticket, you have to re-authenticate
yourself to Kerberos to get a new one.  Use the @code{kinit} command to
re-authenticate yourself.

If you use the @code{kinit} command to get your tickets, make sure you
use the @code{kdestroy} command to destroy your tickets before you end
your login session.  You should probably put the @code{kdestroy} command
in your @file{.logout} file so that your tickets is destroyed
automatically when you logout.  For more information about the
@code{kinit} and @code{kdestroy} commands, see @ref{kinit} and
@ref{kdestroy}.

@node Ticket management
@subsection Command specifics: @code{kinit}, @code{kdestroy}, @code{klist}

@code{kinit} (@pxref{kinit,,@code{kinit}---Kerberos login utility})
requests an initial ticket-granting ticket from Kerberos, then prompts
for your password and uses it to decrypt the ticket.  By default, this
ticket is valid for ten hours (to cover a typical eight hour workday).
The ticket is stored in a file in @file{/tmp/tkt@var{uid}} (where
@var{uid} specifies your identification number) on the local machine.

@code{kdestroy} (@pxref{kdestroy,,@code{kdestroy}---destroy Kerberos
ticket}) purges the contents of your ticket file and then deletes the
file itself, to prevent any later users from using the tickets to access
services.

@code{klist} (@pxref{klist,,@code{klist}---list currently held tickets})
shows what tickets you currently have and when they are due to expire.
This is most useful for determining if you even have tickets, and for
various debugging purposes.

@node Passwords
@subsection Changing your password

All the general rules for passwords apply to your CNS authentication
password.  Obviously, they should not be words found in standard
dictionaries, names of people related to you or with whom you have a
relationship, numbers like your phone number or social security number.
Gibberish or nonsense syllables that you can easily remember make good
passwords.  In general, you should choose a password that is easy for
you to remember, yet difficult for others to guess.  (For more
information on choosing a good password, see your system administrator.)
No matter how well constructed, passwords should be changed once in
awhile to provide greater security.

@code{kpasswd} (@pxref{kpasswd,,@code{kpasswd}---changing Kerberos
passwords}) allows you to change your Kerberos authentication password,
which may be different from the one you use to log in to your local
machine.

@node Principal names
@subsection Your Kerberos principal name

Every Kerberos user and application server has a Kerberos principal
name.  Principal names are of the form @samp{principal.instance@@realm}.
The following are all valid Kerberos principal names.

@example
harry
tina.root
lmb@@barryar.navy.mil
rlogin.miles@@barryar.navy.mil
@end example

@noindent The @var{primary} name is the name of the user on the
service.  Other names may use the same user's ID on another system, or
trusted users on the same or other systems.  The @var{instance} is
used to distinguish among variations on the principal name.  For
users, the instance is usually null, but if used may indicate special
privileges, such as ``root'' privileges.  In many environments, the
instance is usually the name of the machine on which the server runs.
@var{realm} is usually the business or institution at which the
machine is located.  If no realm is given, the local realm is assumed.
In the example above, @var{rlogin.miles,} is the @code{rlogin} server
on the machine @samp{miles}.  In the example @var{harry}, the
principal is the local realm where the server is running.

@node Remote access
@subsection Remote access to hosts (secured by Kerberos)

CNS provides enhanced versions of the Berkeley r-programs.  If you are
familiar with the Berkeley programs, it will be easy for you to use the
CNS versions.  (If you are not familiar with these programs, they are
described in @ref{Replacements}).

The Berkeley @code{rlogin} program has been enhanced to use Kerberos to
secure the connection.  Kerberos' @code{rlogin} looks the same as a
standard or system @code{rlogin} session, except that it trusts your
tickets rather than the host you are on.  Your @file{.rhosts} file no
longer is used; instead, the system automatically trusts you, and
optionally anyone whose Kerberos name you include in your @file{.klogin}
file.

For more information on the @code{klogin} file, see @ref{rlogin,.klogin
files}.

The @code{-x} option may be used with @code{rlogin} to encrypt the
current session, so that it can not be monitored by anyone with access
to the network.  (Though session encryption is recommended for security
reasons, this is an option, not the default.  You must specify @code{-x}
if you want your session to be encrypted.)

@code{rsh} has been enhanced in the same way that @code{rlogin} has,
except that the @code{-x} option is not supported.

@code{rcp} has been enhanced in the same way @code{rlogin} has.  The
@samp{-x} option may be used to encrypt the file copy.  For example,

@smallexample
rcp -x @var{datafile remotehost:remotedatafile}
@end smallexample

@noindent
securely copies @var{datafile} to @var{remotehost}, without exposing the
data on the network.  (If either file is not on a local disk, if, for
example, it is on a Network File System (NFS) file system, then it could
be exposed to the network during NFS access).

@node Replacements
@section Replacements for Familiar Network Facilities
@menu
* rlogin::              Kerberos remote login
* rsh::                 Kerberos remote shell
* rcp::                 Kerberos remote copy
* pfrom::               Post Office `from'
* tftp::                trivial file transfer program
@end menu

Many standard system facilities have CNS/Kerberos counterparts.  Once
you have set up a Kerberized session, you should set up your path names
to use Kerberos facilities instead of the ordinary system facilities.
Some users create macros such as @code{krlogin} and @code{krcp} to use
the correct Kerberos versions.  If you do not know how to set up macros
or how to set up your pathnames so that the correct Kerberos facilities
are used, see your system administrator.

@node rlogin
@subsection @code{rlogin}---Kerberos remote login

@code{rlogin} connects your terminal on the current local host system
@var{lhost} to the remote host system @var{rhost}.

@subsubheading SYNOPSIS
@smallexample
rlogin @var{rhost} [-ec] [-8] [-c] [-C] [-a] [-t @var{termtype}]
     [-n] [-7] [-d] [-k @var{realm}] [-x] [-noflow]
     [-flow] [-L] [-l @var{username}]
@var{rhost} [-ec] [-8] [-c] [-C] [-a] [-t @var{termtype}]
     [-n] [-7] [-d] [-k @var{realm}] [-x] [-noflow] [-flow]
     [-L] [-l @var{username}]
@end smallexample

@c @subsubheading DESCRIPTION

The version built to use Kerberos authentication is very similar to the
standard Berkeley @code{rlogin}(1), except that instead of the
@file{rhosts} mechanism, it uses Kerberos authentication to determine
whether a user is authorized to use the remote account.

Each user may have a private authorization list in a file @file{.klogin}
in his login directory.  This file functions much like the
@file{.rhosts} file; it allows non-local users to access the Kerberos
service on the machine where the @file{.klogin} file exists.  For
example, user @samp{joe@@EAT.COM} would normally not be permitted to log
in to machines in the @samp{MUSSELS.COM} realm.  However, Joe's friend
@samp{bertha@@MUSSELS.COM} can create a @file{.klogin} file in her home
directory, that contains the line @samp{joe@@EAT.COM}.  This allows Joe
to log in as Bertha to Bertha's machine, even though does not have a
ticket identifying him as Bertha.

Each line in this file should contain a Kerberos principal name of the
form @samp{principal.instance@@realm}.  The following are all valid
Kerberos principal names.

@example
harry
tina.root
lmb@@barryar.navy.mil
rlogin.miles@@barryar.navy.mil
@end example

For more information about Kerberos principal names, see @ref{Principal
names,,Your Kerberos principal name}.

If the originating user is authenticated to one of the principals named
in @file{.klogin}, access is granted to the account.  The principal
@samp{@var{accountname}@@@var{localrealm}} is granted access if there is
no @file{.klogin} file.  Otherwise, a login and password is prompted for
on the remote machine as in @code{login}(1).  To avoid security
problems, the @file{.klogin} file must be owned by the remote user.

If there is some problem in gathering the Kerberos authentication
information, an error message is printed and the standard UCB
@code{rlogin} is executed in place of the Kerberos @code{rlogin}.  This
permits the use of the same @code{rlogin} command to connect to hosts
that do not use CNS, as well as to host which do.

A line of the form `@kbd{~.}' disconnects from the remote host, where
`@kbd{~}' is the escape character.  Similarly, the line `@kbd{~^Z}'
(where `@kbd{^Z}', `@kbd{Control-Z}', is the suspend character) suspends
the @code{rlogin} session.  Substitution of the delayed suspend
character (normally `@kbd{^Y})' for the suspend character suspends the
send portion of the @code{rlogin}, but allows output from the remote
system.

The remote terminal type is the same as your local terminal type (as
given in your environment @samp{TERM} variable), unless the @samp{-t}
option is specified (see below).  The terminal or window size is also
copied to the remote system if the server supports the option, and
changes in size are reflected as well.

All echoing takes place at the remote site, so that the @code{rlogin} is
transparent (except for delays).  Flow control via `@kbd{^S}' and
`@kbd{^Q}' and flushing of input and output on interrupts are handled
properly.

The @samp{-8} option allows an eight-bit input data path at all times;
otherwise parity bits are stripped except when the remote site's stop
and start characters are other than `@kbd{^S}'/`@kbd{^Q}'.  Eight-bit
mode is the default.

The @samp{-L} option allows the @code{rlogin} session to be run in
@samp{litout} mode (see @samp{man stty}).

The @samp{-e} option allows specification of an escape character other
than @kbd{~}.  There is no space separating this option flag and the new
escape character.  If the @samp{-e} option is used without specifying a
character, then there is no escape character.

The @samp{-c} option requires confirmation before disconnecting via
`@kbd{~.}'.  Normally, `@kbd{~.}' causes @code{rlogin} to exit
immediately.

The @samp{-a} option forces the remote machine to ask for a password by
sending a null local username.  This option has no effect unless the
standard UCB @code{rlogin} is executed in place of the Kerberos
@code{rlogin} (see above).

The @samp{-t} option replaces the terminal type passed to the remote
host with @var{termtype}.

The @samp{-n} option prevents suspension of rlogin via `@kbd{~^Z}' or
`@kbd{~^Y}'.

The @samp{-7} option forces seven-bit transmissions.

The @samp{-d} option turns on socket debugging (via
@samp{setsockopt}(2)) on the TCP sockets used for communication with the
remote host.

The @samp{-noflow} option forces transmission of flow control characters
(`@kbd{^S}'/`@kbd{^Q}') to the remote system.  This is now the default;
@samp{-flow} enables local handling of `@kbd{^S}'/`@kbd{^Q}'.

The @samp{-k} option requests @code{rlogin} to obtain tickets for the
remote host in realm @var{realm} instead of the remote host's realm as
determined by @code{krb_realmofhost}.

The @samp{-x} option turns on DES encryption for all data passed via the
@code{rlogin} session.  This significantly reduces response time and
significantly increases CPU utilization.

@ignore
@subsubheading SEE ALSO
@table @ref
@item rsh
@item Kerberos
@item krb_sendauth
@item krb_realmofhost
@end table
@code{rlogin}(1) [UCB version]

@subsubheading FILES
@table @file
@item /usr/hosts/*
for rhost version of the command
@end table

@subsubheading BUGS

More of the environment should be propagated.

@end ignore


@node rsh
@subsection @code{rsh}---Kerberos remote shell

@code{rsh} connects to the specified host, and executes the specified
@var{command}.

@c @subsubheading SYNOPSIS
@smallexample
rsh @var{host} [-l @var{username}] [-n] [-d] [-k @var{realm}] [-p @var{port}]
@var{command}
@var{host} [-l @var{username}] [-n] [-d] [-k @var{realm}] [-p @var{port}]
@var{command}
@end smallexample
@c @subsubheading DESCRIPTION

@code{rsh} copies its standard input to the remote command, the standard
output of the remote command to its standard output, and the standard
error of the remote command to its standard error.  @samp{Interrupt},
@samp{quit} and @samp{terminate} signals are propagated to the remote
command; @code{rsh} normally terminates when the remote command does.

The remote @var{username} used is the same as your local username,
unless you specify a different remote name with the @samp{-l} option.
Kerberos authentication is used, and authorization is determined as in
@ref{rlogin}.

The @samp{-k} @var{realm} option causes @code{rsh} to obtain tickets for
the remote host in @var{realm} instead of the remote host's realm as
determined by @code{krb_realmofhost}.

The @samp{-d} option turns on socket debugging (via
@samp{setsockopt}(2)) on the TCP sockets used for communication with the
remote host.

The @samp{-n} option redirects input from the special device
@file{/dev/null}.

If you are using @code{csh}(1) and put a @code{rsh}(1) in the background
without redirecting its input away from the terminal, it blocks even if
no reads are posted by the remote command.  Use this option if no input
is desired.

The @samp{-p} @var{port} option sets the TCP port number to use.  This
option is not normally used, but can be helpful when testing.

If you omit @var{command}, then instead of executing a single command,
you are logged in on the remote host using @code{rlogin}.

Shell meta-characters which are not in quotes are interpreted on local
machine, while meta-characters in quotes are interpreted on the remote
machine.  Thus the command
@smallexample
rsh @var{otherhost} cat @var{remotefile} >> @var{localfile}
@end smallexample
@noindent
appends the remote file @var{remotefile} to the local file @var{localfile}, 
while
@smallexample
rsh @var{otherhost} cat @var{remotefile} ``>>'' @var{otherremotefile}
@end smallexample

@noindent
appends @var{remotefile} (on the other host) to @var{otherremotefile}
(also on the other host).

On some systems, the host names for local machines are also commands in
the directory @file{/usr/hosts}; if you put this directory in your
search path then the @code{rsh} on the command line can be
omitted.  While it is impractical to maintain such a collection, it may
be useful to make yourself a directory, add it to your path, and put
symbolic links into it that point to @file{/usr/kerberos/bin/rsh}.

@ignore

@subsubheading FILES
@table @file
@item /etc/hosts
@item /usr/hosts/*
@end table

@subsubheading SEE ALSO
@table @ref
@item rlogin
@item Kerberos
@item krb_sendauth
@item krb_realmofhost
@end table

@subsubheading BUGS

You cannot run an interactive command (like @samp{rogue}(6) or
@samp{vi}(1)); use @ref{rlogin}.

Stop signals stop the local @code{rsh} process only; this is arguably
wrong, but currently hard to fix for reasons too complicated to explain
here.
@end ignore

@node rcp
@subsection @code{rcp}---Kerberos remote file copy

@var{rcp} copies files between machines.

@c @subsubheading SYNOPSIS
@smallexample
rcp [-p] [-x] [-k @var{realm}] [-N] [-P @var{port}] @var{file1} @var{file2}
rcp [-p] [-x] [-k @var{realm}] [-r] [-N] [-P @var{port}]
@var{file} @dots{} @var{directory}
@end smallexample

@c @subsubheading DESCRIPTION
Each file or directory argument is either a remote file name of the form
@var{rhost}@samp{:}@var{path}, or a local file name (containing no
@samp{:} characters, or a @samp{/} before any @samp{:}s).

If the @samp{-r} option is specified and any of the source files are
directories, @code{rcp} copies each subtree rooted at that name; in this
case the destination must be a directory.

By default, the mode and owner of @var{file2} are preserved if it
already existed; otherwise the mode of the source file modified by the
@code{umask}(2) on the destination host is used.  The @samp{-p} option
causes @code{rcp} to attempt to preserve (duplicate) in its copies the
modification times and modes of the source files, ignoring the umask.

If path is not a full path name, it is interpreted relative to your
login directory on @code{rhost}.  A path on a remote host may be quoted
(using @samp{\}, @samp{"}, or @samp{'}) so that the meta-characters are
interpreted remotely.

@code{rcp} does not prompt for passwords; it uses Kerberos
authentication when connecting to @var{rhost}.  Authorization is as
described in @ref{rlogin}.

The @samp{-x} option selects encryption of all information transferred
between hosts.  The @samp{-k} @var{realm} option causes @code{rcp} to
obtain tickets for the remote host in @var{realm} instead of the remote
host's realm as determined by @code{krb_realmofhost}.

@code{rcp} handles third party copies, where neither source nor target
files are on the current machine.  Note that Kerberos is only used for
the first connection of a third party copy; the second connection uses
the standard Berkeley @code{rcp} protocol.  This is due to a limitation
of the version 4 protocol.

Hostnames may also take the form
@var{rname}@@@var{rhost}' to use @var{rname} rather than the current
user name on the remote host.

There are two options to @code{rcp} which are not normally used, but
can be helpful when testing.  The @samp{-N} option forces @code{rcp}
to use a network connection, even when copying files which are on the
local host.  The @samp{-P} @var{port} option sets the TCP port number
to use.

@ignore
@subsubheading SEE ALSO
@table @ref
@item rsh
@item rlogin
@item Kerberos
@item krb_realmofhost,,krb_get_lrealm
@end table
See also @code{cp}(1), @code{ftp}(1), @code{rcp}(1) [UCB version].

@subsubheading BUGS

Does not detect all cases where the target of a copy might be a file in
cases where only a directory should be legal.

Is confused by any output generated by commands in a @file{.login},
@file{.profile}, or @file{.cshrc} file on the remote host.

The destination user and hostname may have to be specified as
@var{rhost}@samp{.}@var{rname} when the destination machine is 
running
the 4.2BSD version of @code{rcp}.

@end ignore

@node pfrom
@subsection @code{pfrom}---Who sent me mail?

@c @subsubheading SYNOPSIS
@smallexample
pfrom [-s @var{sender}] [-h @var{host}] [-v] [-d]
@end smallexample

@c @subsubheading DESCRIPTION
If you are using the `POP' mail system (@pxref{popper}) the @code{pfrom}
program prints out the mail header lines in your incoming mail to show
you who your mail is from.  It does this without retrieving the mail
from the post office.  If the @samp{-s} option is given, then only
headers for mail sent by sender are printed.  If the @samp{-h} option is
given, then @var{host} is consulted instead of your default post office.
The @samp{-v} option puts @code{pfrom} into verbose mode, and the
@samp{-d} option puts @code{pfrom} into debug mode.

@code{pfrom} is equivalent to the @code{from} command used on 
traditional
local mail systems.

@ignore
@subsubheading SEE ALSO
Post Office Protocol (revised) (aka RFC-819 with revisions)
@end ignore

@node tftp
@subsection @code{tftp}---trivial file transfer protocol

@c @subsubheading SYNOPSIS
@smallexample
tftp -@var{action} @var{localname} @var{host} @var{foreignname} 
[@var{mode}]
@end smallexample
@c @subsubheading DESCRIPTION
If action is @samp{w}, @samp{p}, or @samp{ap}, @code{tftp} writes the
local file, called @var{localname}, onto the foreign host's file system
as @var{foreignname}.  If action is @samp{ap}, Kerberos authentication
is used.  Note that @var{foreignname} must be in quotes if it contains
shell special characters.  If action is @samp{r}, @samp{g}, or
@samp{ag}, @code{tftp} reads foreign host's file @var{foreignname} into
the local file, @var{localname}.  If action is @samp{ag}, Kerberos
authentication is used.  @code{tftp} does not supersede or overwrite
existing local files, however; to do so, use action @samp{o}.

Mode may be @samp{netascii}, or @samp{image}. @samp{netascii}, the
default mode, transfers the file as standard ASCII characters.
@samp{image} mode transfers the file in binary, with no character
conversion.

If Kerberos authentication is not used with @code{tftp}, access is
denied unless the remote and local host are on the same local-area
network.

@ignore
@subsubheading SEE ALSO
@xref{Kerberos Intro}, Internet Protocol Handbook
@end ignore

@node Ticket Management Commands
@section Ticket Management Commands
@menu
* kinit::       get initial tickets
* klist::       list tickets
* kdestroy::    erase tickets
* kpasswd::     change Kerberos password
* ksu::         switch local user based on Kerberos access list
@end menu


@node kinit
@subsection @code{kinit}---Kerberos login utility

@c @subsubheading SYNOPSIS
@c kinit [-irvl] [@var{user}]
@smallexample
kinit [-ivl]
@end smallexample 
@c @subsubheading DESCRIPTION
The @code{kinit} command is used to login to the Kerberos authentication
and authorization system.  Note that only registered Kerberos users can
use the Kerberos system.  For information about registering as a
Kerberos user, see the @xref{Initial Steps} of the manual, or talk to
your system administrator.

@ignore
If you are logged in to a workstation that is running the @samp{toehold}
service, you do not have to use @code{kinit}.  The @samp{toehold} login
procedure logs you into Kerberos automatically.  You need to use
@code{kinit} only in those situations in which your original tickets
have expired.  (Tickets expire in ten hours, enough to cover a typical
workday.)  Note as well that @samp{toehold} automatically destroys your
tickets when you logout from the workstation. .  .. UPDATE THAT ...
@end ignore

When you use @code{kinit} without options, the utility prompts for your
username and Kerberos password, and tries to authenticate that name
with the local Kerberos server.

If Kerberos authenticates the login attempt, @code{kinit} retrieves your
ticket-granting ticket and puts it in the ticket file specified by your
@samp{KRBTKFILE} environment variable.  If this variable is undefined,
your ticket is stored in the @file{/tmp} directory, in the file
@file{tkt@var{uid}}, where @samp{uid} specifies your user ID number from
the password file.

Make sure you use the @code{kdestroy} command to destroy any active 
tickets before you end your login session.  You may want to put the 
@code{kdestroy} command in your @file{.logout} file so that your 
tickets are destroyed automatically when you logout.

The options to @code{kinit} are as follows:

@table @code
@item -i
@code{kinit} prompts you for a Kerberos instance.

@item -r
@code{kinit} prompts you for a Kerberos realm.  This option lets you
authenticate yourself with a remote Kerberos server.

@item -v
Verbose mode.  @code{kinit} prints the name of the ticket file used, and
a status message indicating the success or failure of your login
attempt.

@item -l
@code{kinit} prompts you for a ticket lifetime in minutes.  Due to
protocol restrictions in Kerberos Version 4, this value must be between
5 and 1275 minutes.

@item -s
@code{kinit} prompts you for a username.  It then challenges you with a
six digit number which you enter into the SNK4.  The SNK4 produces an
eight-digit response which you enter into the system to confirm your
identity.  (See, @ref{Appendix,,SecureNet Key Authentication Device}.)
@end table

@ignore
@subsubheading SEE ALSO
@table @ref
@item Kerberos Intro
@item kdestroy
@item klist
@end table
See also toehold(1).

@subsubheading BUGS

The @samp{-r} option has not been fully implemented.

@end ignore

@node klist
@subsection @code{klist}---list currently held tickets

@c @subsubheading SYNOPSIS
@smallexample
klist [-s|-t] [-file @var{name}] [-srvtab]
@end smallexample
@c @subsubheading DESCRIPTION

@code{klist} prints the name of the ticket file and the identity of the
principal the tickets are for (as listed in the ticket file), and lists
the principal names of all Kerberos tickets currently held by the user,
along with the issue and expire time for each authenticator.  Principal
names are listed in the form
@samp{@var{name}.@var{instance}@@@var{realm}}, with the 
@samp{.}
omitted if the instance is null, and the @samp{@@} omitted if the realm
is null.

If given the @samp{-s} option, @code{klist} does not print the issue and
expire times, the name of the ticket file, or the identity of the
principal.

If given the @samp{-t} option, @code{klist} checks for the existence of
a non-expired ticket-granting ticket in the ticket file.  If one is
present, it exits with status 0, otherwise, it exits with status 1.  No
output is generated when this option is specified.

If given the @samp{-file} option, the following argument is used as the
ticket file.  Otherwise, if the @code{KRBTKFILE} environment variable is
set, it is used.  If this environment variable is not set, the file
@file{/tmp/tkt@var{uid}} is used, where @var{uid} is the current user-ID
of the user.

If given the @samp{-srvtab} option, the file is treated as a service key
file, and the names of the keys contained therein are printed.  If no
file is specified with a @samp{-file} option, the default is
@file{/etc/krb-srvtab}.  See, @ref{Application server entries,,keys for
application servers}.

@ignore

@subsubheading FILES
@table @file
@item /usr/kerberos/lib/krb.conf
to get the name of the local realm
@item /tmp/tkt@var{uid}
as the default ticket file (@var{uid} is the decimal UID of the user).
Note that on the IBM RS/6000, there is an additional file
@file{/tmp/tkt@var{uid}.shm}, due to the shared-memory implementation of
the Kerberos tickets.
@item /etc/krb-srvtab
as the default service key file
@end table

@subsubheading SEE ALSO
@table @ref
@item Kerberos Intro
@item kinit
@item kdestroy
@end table

@subsubheading BUGS

When reading a file as a service key file, very little sanity or error
checking is performed.

@end ignore


@node kdestroy
@subsection @code{kdestroy}---destroy Kerberos tickets

@c @subsubheading SYNOPSIS
@smallexample
kdestroy [-f] [-q]
@end smallexample
@c @subsubheading DESCRIPTION

The @code{kdestroy} utility destroys the user's active Kerberos
authorization tickets by writing zeros to the file that contains them.
If the ticket file does not exist, @code{kdestroy} displays a message to
that effect.

After overwriting the file, @code{kdestroy} removes the file from the
system.  The utility displays a message indicating the success or
failure of the operation.  If @code{kdestroy} is unable to destroy the
ticket file, the utility warns you by making your terminal beep.

You should place the @code{kdestroy} command in your @file{.logout} file
so that your tickets are destroyed automatically when you logout.

The options to @code{kdestroy} are as follows:

@table @code
@item -f
@code{kdestroy} runs without displaying the status message.

@item -q
@code{kdestroy} does not make your terminal beep if it fails to destroy
the tickets.
@end table

@ignore
@subsubheading FILES
@itemize @bullet
@item @code{KRBTKFILE} environment variable if set, otherwise
@item @file{/tmp/tkt@var{uid}}
@end itemize

@subsubheading SEE ALSO
@table @ref
@item Kerberos Intro
@item kinit
@item klist
@end table

@subsubheading BUGS

Note that only the tickets in the user's current ticket file are
destroyed.  Unfortunately, separate ticket files are used to hold root
instance and password changing tickets.
@end ignore

@node kpasswd
@subsection @code{kpasswd}---changing Kerberos passwords

@c @subsubheading SYNOPSIS
@smallexample
kpasswd [-h] [-n @var{name}] [-i @var{instance}] [-r @var{realm}] 
        [-u @var{username}[.@var{instance}][@@@var{realm}]]
@end smallexample
@c @subsubheading DESCRIPTION
The @code{kpasswd} command is used to change a Kerberos principal's
password.

If the @samp{-h} option is specified, a brief summary of the options is
printed, and @code{kpasswd} then exits.

If the @samp{-n} option is specified, @var{name} is used as the
principal name rather than the username of the user running
@code{kpasswd}.  (This is determined from the ticket file if it exists;
otherwise, it is determined from the Unix user ID.)

If the @samp{-i} option is specified, @var{instance} is used as the
instance rather than a null instance.

If the @samp{-r} option is specified, @var{realm} is used as the realm
rather than the local realm.

If the @samp{-u} option is specified, a fully qualified Kerberos
principal can be given.

The utility prompts for the current Kerberos password (printing the name
of the principal for which it intends to change the password), which is
verified by the Kerberos server.  If the old password is correct, the
user is prompted twice for the new password.  A message is printed
indicating the success or failure of the password changing operation.


@ignore
@subsubheading BUGS

@code{kpasswd} does not handle names, instances, or realms with 
special
characters in them when the @samp{-n}, @samp{-i}, or @samp{-r} 
options
are used.  Any valid fullname is accepted, however, if the @samp{-u}
option is used.

If the principal whose password you are trying to change does not exist,
you are not be told until after you have entered the old password.

@subsubheading SEE ALSO
@table @ref
@item Kerberos Intro
@item kinit
@item kpasswd
@item kadmin
@end table
@end ignore

@node ksu
@subsection @code{ksu}---Kerberized substitute user ID 

@code{ksu} requests the Kerberos password for login (or for @samp{root},
if no login is provided), and switches to that user and group ID.  A
shell is then invoked.

@c @subsubheading SYNOPSIS
@smallexample
ksu [-flm] [@var{login}]
@end smallexample

@c @subsubheading DESCRIPTION
By default, your environment is
unmodified with the exception of @samp{USER}, @samp{HOME}, and
@samp{SHELL}.  @samp{HOME} and @samp{SHELL} are set to the target
login's @file{/etc/passwd} values.  @samp{USER} is set to the target
login, unless the target login has a user ID of zero, in which case it is
unmodified.  The invoked shell is that of the target login.

The @samp{-l} option simulates a full login.  The environment is
discarded except for @samp{HOME}, @samp{SHELL}, @samp{PATH},
@samp{TERM}, and @samp{USER}.  @samp{HOME} and @samp{SHELL} are modified
as above.  @samp{USER} is set to the target login.  @samp{PATH} is set
to @samp{/usr/ucb:/bin:/usr/bin}.  @samp{TERM} is imported from your
current environment.  The invoked shell is that of the target login, and
@code{ksu} changes directory to the target login's home directory.

The @samp{-m} option causes the environment to remain unmodified, and
the invoked shell to be your login shell.  No directory changes are
made.  As a security precaution, if the @samp{-m} option is specified,
the target user's shell is a nonstandard shell (as defined by
@samp{getusershell}(3)) and the caller's real user ID is non-zero,
@code{ksu} fails.

If the invoked shell is @code{csh}, the @samp{-f} option prevents it
from reading the @file{.cshrc} file.  Otherwise, this option is ignored.

Only users with root instances listed in @file{~root/.klogin} may @code{ksu}
to @samp{root} (The format of this file is described by @ref{rlogin}.).
When attempting root access, @code{ksu} attempts to fetch a
ticket-granting ticket for @samp{@var{username}.root@@@var{localrealm}},
where @var{username} is the username of the process.  If possible, the
tickets are used to obtain, use, and verify tickets for the service
@samp{rcmd.@var{host}@@@var{localrealm}} where @var{host} is the
canonical host name of the machine (as determined by
@code{krb_get_phost}).  If this verification fails, the @code{ksu} is
disallowed.  (If the service @samp{rcmd.@var{host}@@@var{localrealm}} is
not registered, the @code{ksu} is allowed.)

By default (unless the prompt is reset by a startup file) the super-user
prompt is set to @samp{#} to remind one of its power.

When not attempting to switch to the @samp{root} user, @code{ksu}
behaves exactly like @code{su}(1).

@ignore
@subsubheading SEE ALSO
@table @ref
@item rlogin
@item krb_realmofhost,,krb_get_phost
@end table
See also @code{su}(1), @code{csh}(1), @code{login}(1), 
@code{sh}(1),
@code{passwd}(5), @code{group}(5), @code{environ}(7).
@end ignore


@node Config Decisions
@chapter The Kerberos Administrator: Configuration Decisions

@c list server configs here too.
@menu
* Options::                     naming realms, storage locations, etc.
* General Configuration::       other changes needed
* CNS Configuration::           configuring CNS
@end menu

To make administration of a Kerberos realm simpler, some important
decisions should be made before installation.  Carefully consider the
following options.

@node Options
@section Options for your Kerberos Service

@menu
* Site Configuration::          choice of names and storage
* Client Installation::         what to put on a client
* Host Installation::           what to put on a network service host
* Server Installation::         what to put on the Key Distribution Center
* Slave Server Installation::   adding backup Key Distribution Centers
@end menu


@node Site Configuration
@subsection Choice of Names and Storage

@itemize @bullet 
@item @strong{Resources:}
Kerberos does not require much disk space.  Any client that is already
getting system software via Network File System (NFS) can get Kerberos
software the same way, unless you wish to guard against someone spoofing
the NFS server.  Any application server can do the same, though we
expect most application servers to have system software stored locally;
there must be a small amount of local space for the server private key
(in the @file{krb-srvtab} file).

The Kerberos master server itself needs enough disk space to hold the
key database, and for reliability reasons should have the
@samp{kerberos} and @samp{kadmin} servers locally.

@item @strong{Naming:}
If you are already using the Domain Name Service, which we recommend,
and you are only setting up one Kerberos Realm (i.e., one administrative
authority---size is not an issue) then we suggest

@itemize @bullet
@item @strong{Realm name:}
DNS domain name.

@item @strong{Kerberos server names:}
@samp{kerberos} (for a single server) and @samp{kerberos-@var{n}}
(kerberos-1,2... etc.) for slaves.
@end itemize

If you have multiple administrative areas that may need to work
together, you still want to divide things in a similar manner to how you
have already divided your namespace.  If the namespace is not divided,
you either need to explicitly list members of one domain in the
@file{krb.realms} file or you need to have users specify the @samp{-k}
argument for most commands.
@end itemize

@node Client Installation
@subsection What to put on a client

Everything in this installation can be installed in a common location.
Applications provided are:
@table @code
@item kinit
@item klist
@item kdestroy
@item rlogin
@item rcp
@item rsh
@item telnet
@item ksu
@item kadmin
@item movemail
@item pfrom
@item ftp
@item kpasswd
@end table

A pair of configuration files (@file{krb.conf} and @file{krb.realms})
are needed to identify the realms within which the host needs to
authenticate (see, respectively,
@ref{krb.conf,,@code{krb.conf}---Kerberos configuration file}, and
@pxref{krb.realms,,@code{krb.realms}---host to Kerberos realm
translation file}).  These files are stored in @file{/usr/kerberos/lib}.

@enumerate
@item
Either install the release directly in @file{/usr/kerberos}, or set up
symbolic links or NFS mounts as your configuration warrants.

@item
Generate @file{krb.conf} and @file{krb.realms} files with your
local configuration parameters.  See @xref{krb.realms} for details.

@item
Update the @file{/etc/services} file.
@end enumerate

@node Host Installation
@subsection What to put on a network service host

Executables should be installed reliably (they may be shared between
machines, but this is not usually a good idea.)  Daemons provided
are:
@table @code
@item klogind
@item telnetd
@item kshd
@item popper
@item ksrvutil
@item ftpd
@item login.krb
@item tftpd
@end table

Along with the configuration files used in the client install, you need
to create a @file{krb-srvtab}.  If the @file{krb-srvtab} is compromised,
it is possible to impersonate users and obtain access to the services on
this particular server.

Kerberos-enhanced network services can be installed simply by adding
entries for them to @file{/etc/inetd.conf} on Berkeley Standard
Distribution (BSD) derived systems.  On some systems there is a limit on
the number of services which @code{inetd} can support.  If this is the
case on your system, a simple workaround is to run a second instance of
@code{inetd}, the Internet service daemon, with a configuration file
containing the Kerberos-enhanced services.  On BSD derived systems, this
@code{inetd} should be started in @file{/etc/rc.local} using whatever
idiom was used for the normal @code{inetd}.

@node Server Installation
@subsection What to put on the Key Distribution Center

Executables should be installed very reliably (preferably locally.)
Local disk space is also needed for the Key Database.  The programs are:
@table @code
@item Kerberos
@item kadmind
@item kstash
@item kdb_util
@item kdb_edit
@item kdb_init
@item kdb_destroy
@item kprop
@item kpropd
@item ext_srvtab
@end table

Access to the memory or core dumps from this machine could compromise
security for the entire realm.  If there is a human operator always
available, the Kerberos master key can be manually entered at every
reboot, and not otherwise recorded on disk; if so, normal backups can be
made of the database.  For convenience, @code{kstash} can be used to
store the master key on local disk; care should be taken not to make
this file accessible or to make backups of it.  (@xref{kstash}.)

@node Slave Server Installation
@subsection Adding a Slave Server

The use of slave servers provides continued service in case the master
KDC server is down, unreachable, or overloaded.  Periodically, the
master sends out copies of its entire database to all of it's slave
servers.  When clients cannot reach the master for ticket requests, they
try the slaves.

Note that there is no continued @code{kadmin/kpasswd} service---the
master database is the only one that gets modified, and is defined as
the one on which @code{kadmind} is running.

Follow these steps to set up slave servers.

@itemize @bullet
@item The master server and all slave servers must also be set up as
application servers, with srvtab files containing an @samp{rcmd} key.
@xref{Application server configuration,,Configuring an Application
Server,install,Cygnus Network Security Installation Notes}.

@item Each slave server uses the @code{kpropd} daemon to receive copies
of the Kerberos database from the master server.  Add a line like the
following to @file{/etc/inetd.conf} to make @code{inetd} invoke the
@code{kpropd} daemon when it receives an incoming connection:

@iftex
@let@nonarrowing=@comment
@end iftex
@smallexample
krb_prop stream tcp nowait root /usr/kerberos/etc/in.kpropd in.kpropd
@end smallexample
@iftex
@let@nonarrowing=@relax
@end iftex

@code{in.kpropd} is a simple shell script which invokes @code{kpropd}
with the correct arguments.

@item The master server uses the @code{kprop} program to send copies of
the Kerberos database to the slave servers.  This is most easily done
using the @code{push-kprop} shell script.  Enter the hostname of each
slave server into the file @file{/usr/kerberos/database/slavelist}.
This should be a simple text file, with each hostname on a separate
line.

@item Run the @code{push-kprop} script on the master to send the master
database over to all the slaves.  You should arrange for
@code{push-kprop} to be invoked regularly on the master, using
@code{cron}.  The frequency of the update depends upon how urgently you
need the slave servers to know about database changes, such as changed
passwords or new Kerberos principals.  Once an hour is usually adequate.

@item Once the slaves have received their own copy of the database, you
can start the @code{kerberos} server on the slave.  Start it with the
@samp{-s} option.  You should arrange for each slave server to start the
@code{kerberos} server at boot time, just as on the master server,
except that on the slaves @code{kerberos} should be invoked with
@samp{-s}.

@item Add the slave hostnames to the @file{/usr/kerberos/lib/krb.conf}
file on any machine which should be able to get Kerberos tickets from
the slave servers.  The CNS client programs queries servers in the order
they are listed in @file{krb.conf}, so you can, for example, arrange for
client programs to contact a local slave server before trying the master
server.

@item To add a new slave server, just arrange for @code{kpropd} to be
invoked via @code{inetd} on the slave, add the new slave hostname to
@file{slavelist} on the master server, run @code{push-kprop} on the
master server, and start @code{kerberos -s} on the new slave.
@end itemize

For detailed information on @code{kprop}, see @ref{kprop and
push-kprop}.  For detailed information on @code{kpropd}, see @ref{Slave
Servers,kpropd}.

@node General Configuration
@section General Configuration

A few existing configuration files may be modified for the use of
Kerberos.
@table @file
@item /etc/services
Kerberos Enhanced services use different ports than their traditional
counterparts.  These need to be added to @file{/etc/services} on any
client machine.
@item /etc/inetd.conf
If a machine is hosting any Kerberos Enhanced services, such as
@code{popper} (see @xref{popper}), @code{rlogind} (see @xref{klogind})
or @code{rshd} (see @xref{kshd}), these should be added to
@code{inetd.conf} along with the other services the machine provides.
It is also possible to run a second @code{inetd} with only the Kerberos
services rather than changing the existing list.

Note that if you wish to allow access @strong{only} when
Kerberos-mediated, than you must remove services like @code{rlogin} from
@file{/etc/inetd.conf}, leaving only the versions from Cygnus.  For
further protection, you may allow access to @code{eklogind}, the server
only for encrypted remote logins.

@item /etc/rc
Since the Kerberos Key Distribution Center (and any slave servers)
should be running all the time, the Kerberos server is often started out
of the system @file{/etc/rc} file, or the equivalent on your system.
@xref{Configuring the KDC,,Configuring the KDC,install,Cygnus Network
Security Installation Notes}.

@end table

@node CNS Configuration
@section CNS Configuration

@menu
* krb.conf::    Realm to Server mapping
* krb.realms::  Host to Realm exceptions
@end menu

@node krb.conf
@subsection @code{krb.conf}---Kerberos configuration file

@c @subsubheading DESCRIPTION
@file{krb.conf} contains configuration information describing the
Kerberos realm and the Kerberos key distribution center (KDC) servers
for known realms.

@file{krb.conf} contains the name of the local realm in the first line,
followed by lines indicating realm/host entries.  The first token is a
realm name, and the second is the hostname of a host running a KDC for
that realm.  The words @samp{admin server} following the hostname
indicate that the host also provides an administrative database server,
that is, it is the master Kerberos server for this realm, where requests
to change passwords, add users, etc, are sent.

For example:
@smallexample
CYGNUS.COM
CYGNUS.COM kerberos-1.cygnus.com admin server
CYGNUS.COM kerberos-2.cygnus.com
ANOTHER.CYGNUS.COM kerberos.another.cygnus.com admin server
@end smallexample
@ignore
@subsubheading SEE ALSO
@table @ref
@item krb.realms
@item krb_realmofhost,,krb_get_krbhst
@item krb_realmofhost,,krb_get_lrealm
@end table
@end ignore



@node krb.realms
@subsection @code{krb.realms}---host to Kerberos realm translation file

@c @subsubheading DESCRIPTION
@file{krb.realms} provides a translation from a hostname to the Kerberos
realm name for the services provided by that host.

Each line of the translation file is in one of the following forms
(@var{domain_name} should be of the form @samp{.XXX.YYY}, e.g.
@samp{.CYGNUS.COM}):
@smallexample
          @var{host_name} @var{kerberos_realm}
          @var{domain_name} @var{kerberos_realm}
@end smallexample
If a hostname exactly matches the @var{host_name} field in a line of the
first form, the corresponding realm is the realm of the host.  If a
hostname does not match any @var{host_name} in the file, but its domain
exactly matches the @var{domain_name} field in a line of the second
form, the corresponding realm is the realm of the host.

If no translation entry applies, the host's realm is considered to be
the the domain portion of the hostname converted to upper case.

@ignore
@subsubheading SEE ALSO
@xref{krb_realmofhost}
@end ignore

@node Administration Tools
@chapter Administration Tools

@menu
* General Administration::      How to administer a Kerberos Realm
* Administrative Tools::        kadmin, kstash, ksrvutil, ksrvtgt
* Raw Database Manipulation::   kdb_edit, others
@end menu

@node General Administration
@section How to administer a Kerberos Realm

@menu
* User entries::                Keys for users
* Application server entries::  Keys for application servers
* Admin Tools::                 kadmin and other tools
@end menu

@node User entries
@subsection Keys for users

Users are @dfn{principals} in the database.  Each principal has a secret
key; this key is known only to the user and to the Kerberos server.  The
user actually knows only a password which is a string that is converted
to an encryption key; the server stores only the key, not the password.

You may set and administer initial user names and passwords with
@code{kadmin}.  You should not give users their passwords via email (too
insecure).  You should speak to them directly.  Likewise, you can change
a password, but should only do so when they are certain that the person
requesting the change is really the user in question.

@node Application server entries
@subsection Keys for application servers

Application servers are also principals.  Typically, an application
server uses an application name as the principal name and the name of
the host supporting the application server as the instance.  The key for
this entry is stored in the Kerberos database and in the
@file{krb-srvtab} file on the host supporting the application server.

You must keep the @file{krb-srvtab} file secure, since it is the basis
for all authentication to the application servers on that host.  This
means that you must either generate it locally or transfer it in a
secure manner (either on a physical medium or via an encrypted network.)

One secure way of generating a @file{krb-srvtab} is for a database
administrator to use @code{kadmin} to create the application server key
with a known password.  Then this key must be given to the sysadmin of
the destination system in a secure manner (in person, not via email.)
The sysadmin can then run @code{ksrvutil} on the host (from a directly
connected terminal, such as the system console, not over the network)
and specify the password.  This creates an initial @file{krb-srvtab}
with known password.  It is best to immediately perform a @code{ksrvutil
change} which uses the current key to securely change the key to a new
(randomly generated) value.  (Randomly chosen passwords are more secure
than human chosen ones.)

A short cut in this process (if for example the machine's system
administrator is also a Kerberos database administrator) would be to run
@code{kadmin} directly from the host for which the key is desired, and
then use @code{ksrvutil} change, immediately.  This avoids the need for
any communication of the key.

An alternative approach is to have the administrator use @code{kadmin}
to enter the keys and then use @code{ext_srvtab} to create the new
@file{krb-srvtab} file.  Then that file would be put on a tape and
securely transported to the host site and loaded.  This technique might
be useful for machines which are being installed offline but need to be
immediately accessible from the network at a later time.

@node Admin Tools
@subsection kadmin and other utilities

While @code{kdb_util} and @code{kdb_edit} can be used directly on the
server to change the database, it is more convenient to simply add
administrators to access control lists.  An administrator needs to have
an @samp{admin} instance.  You need to use @code{kdb_edit} to add an
@samp{admin} instance for at least one user.  Once you have an
@code{admin} instance, you can use the simpler @code{kadmin} program to
handle most types of changes to the database.

(For more information about @code{kdb_util}, see @ref{kdb_util}.  For
more information about @code{kdb_edit}, see @ref{kdb_edit}.  For an
example of using them to create an initial @samp{admin} instance, see
@pxref{Configuring the KDC,,Configuring the KDC,install,Cygnus Network
Security Installation Notes}).

A database administrator either adds new entries or changes existing
ones.  New users are added with the @code{ank} (add new key) command to
@samp{kadmin}.  Ideally the users identifies themselves to the
administrator, who then creates the entry and lets the users type their
initial password.  (The users should still change the password at their
earliest convenience.)  An administrator must be listed in the
@file{admin_acl.add} file to do this.  (For information about ACL files,
see @pxref{kadmind,ACL files}).

Occasionally users forget their passwords, or accidentally type them
over the network in cleartext thus compromising the passwords' security.
Anything the user sends over the network after that (including a
@code{kpasswd} command) could be read by an attacker.  The only way to
re-establish a secure password is to have a new one set by a system
administrator.  The @samp{kadmin} @code{cpw} request lets an
administrator change the password of any user.  An administrator must be
listed in the @file{admin_acl.mod} file to do this.

One way to disable an account is to change the password to a value
unknown to the user; this is useful if the password has been exposed or
discovered.  The Kerberos administrative server does not provide any
easy way to delete names, since any name that `expires' may remain on
access control lists, such as @file{.klogin} files or @file{admin_acl.*}
files, long afterwards; reusing the name would provide a new person the
access of a previous one.  (Names can be deleted by dumping and
reloading the database.  This should only be done after access lists are
searched for the old names.)

Database administrators may also create principal names for new
instances of an application servers on their machines.  If a machine is
providing a new authenticated service, it needs a key for that service
(unless it is using an existing one---for example, @code{rlogin} and
@code{rsh} use the same @code{rcmd} principal.)


@node Administrative Tools
@section Administrative Tools

@menu
* kadmin::                      Database Administration
* kstash::                      Master Key Storage
* ksrvutil::                    Host Key Management
* ksrvtgt::                     Application Authentication
* kprop and push-kprop::        Send Database to a Slave Server
@end menu

@node kadmin
@subsection @code{kadmin}---network utility for CNS database administration

@c @subsubheading SYNOPSIS
@smallexample
kadmin [-u @var{user}] [-r @var{default_realm}] [-m]
@end smallexample
@c @subsubheading DESCRIPTION

This utility provides a unified administration interface to the Kerberos
master database.  Kerberos administrators use @code{kadmin} to register
new users and application servers to the master database, and to change
information about existing database entries.  For instance, an
administrator can use @code{kadmin} to change a user's Kerberos
password.  A Kerberos administrator is a user with an @samp{admin}
instance whose name appears on one of the Kerberos administration access
control lists.  If the @samp{-u} option is used, @var{user} is used as
the administrator instead of the local user.  If the @samp{-r} option is
used, @var{default_realm} is used as the default realm for transactions.
Otherwise, the local realm is used by default.  If the @samp{-m} option
is used, multiple requests are permitted on only one entry of the admin
password.  Some sites do not support this option.

The @code{kadmin} program communicates over the network with the
@code{kadmind} program, which runs on the machine housing the Kerberos
master database.  The @code{kadmind} creates new entries and makes
modifications to the database.

When you enter the @code{kadmin} command, the program displays a message
that welcomes you and explains how to ask for help.  Then @code{kadmin}
waits for you to enter commands (which are described below).  It then
asks you for your admin password before accessing the database.

Use the @code{add_new_key} (or @code{ank} for short) command to register
a new principal with the master database.  The command requires one
argument, the principal's name.  The name given can be fully qualified
using the standard @var{name.instance@@realm} convention (see,
@pxref{Principal names,,Your Kerberos principal name}).  You are asked
to enter your admin password, then prompted twice to enter the
principal's new password.  If no realm is specified, the local realm is
used unless another was given on the command line with the @samp{-r}
flag.  If no instance is specified, a null instance is used.  If a realm
other than the default realm is specified, you need to supply your admin
password for the other realm.

Use the @code{change_password} (@code{cpw}) command to change a
principal's Kerberos password.  The command requires one argument, the
principal's name.  You are asked to enter your admin password, then
prompted twice to enter the principal's new password.  The name given
can be fully qualified using the standard @var{name.instance@@realm}
convention.

Use the @code{change_admin_password} (@code{cap}) command to change your
admin instance password.  This command requires no arguments.  It
prompts you for your old admin password, then prompts you twice to enter
the new admin password.  If this is your first command, the default
realm is used.  Otherwise, the realm used in the last command is used.

Use the @code{get_entry} (@code{get}) command to get information about a
principal.  The command requires one argument, the principal's name.
You are prompted to enter your admin password.

Use the @code{delete_principal} (@code{del}) command to delete a
principal.  This command should be used with care.  When you delete an
entry, be sure to take it off any access control lists
(@file{admin_acl.*} files (@pxref{kadmind, ACL files}) and
@file{.klogin} files (@pxref{rlogin, .klogin files})).  If you do not,
then, if the principal name is reused for somebody else, that person
obtains unauthorized access.

Use the @code{destroy_tickets} (@code{dest}) command to destroy your
admin tickets explicitly.

Use the @code{list_requests} (@code{lr}) command to get a list of
possible commands.

Use the @code{help} command to display @code{kadmin}'s various help
messages.  If entered without an argument, help displays a general help
message.  You can get detailed information on specific @code{kadmin}
commands by entering @code{help command_name}.

Use the @code{add_snk_key} or @code{snk} to generate and display random
keys for use initializing or reinitializing SNK4 devices.  (See,
@ref{Appendix,,SecureNet Key Authentication Device}.)

To quit the program, type @code{quit}.


@ignore
@subsubheading BUGS

The user interface is primitive, and the command names could be better.


@subsubheading SEE ALSO
@table @ref
@item Kerberos Intro
@item kadmind
@item kpasswd
@item ksrvutil
@end table

     `A Subsystem Utilities Package for UNIX' by Ken Raeburn
@end ignore



@node kstash
@subsection @code{kstash}---stash CNS Key Database master key

@code{kstash} saves the Kerberos key distribution center (KDC) database
master key in the master key cache file, @file{/.k}.  This is normally
done so that the @code{kerberos} daemon can read the master key from the
file when it starts up at boot time.  If the key is not saved using
@code{kstash}, somebody must enter the master key manually each time the
system is rebooted.

The master key cache file, @file{/.k}, should not be saved on backup
tapes.  If it is, the backup tapes must be guarded with the same level
of security used to protect the master Key Distribution Center machine
itself.  If somebody is able to learn the master key, the contents of
the entire database, including all passwords, are vulnerable.

When @code{kstash} is run, it prompts the user to enter the master key,
to verify the authenticity of the key and the authorization to store the
key in the file.

@subsubheading DIAGNOSTICS
@table @code
@item verify_master_key: Invalid master key, does not match database.
The master key string entered was incorrect.
@item kstash: Unable to open master key file
The attempt to open the cache file for writing failed (probably due to
a system or access permission error).
@item kstash: Write I/O error on master key file
The @code{write}(2) system call returned an error while @code{kstash}
was attempting to write the key to the file.
@end table
@subsubheading FILES
@table @file
@item /usr/kerberos/database/principal.pag
@itemx /usr/kerberos/database/principal.dir
DBM files containing database
@item /.k
Master key cache file.
@end table

@node ksrvutil
@subsection @code{ksrvutil}---host CNS srvtab manipulation utility

@c @subsubheading SYNOPSIS
@smallexample
ksrvutil @var{operation} [-k] [-i] [-f @var{filename}]
@end smallexample
@c @subsubheading DESCRIPTION
@code{ksrvutil} allows a system manager to list or change keys currently
in his srvtab or to add new keys to the srvtab.

Operation must be one of the following:

@table @code
@item list
lists the keys in a srvtab showing version number and principal name.
If the @samp{-k} option is given, keys are also shown.

@item change
changes all the keys in the Kerberos database and in the @samp{srvtab}
by using the regular admin protocol.  If the @samp{-i} flag is given,
@code{ksrvutil} prompts for `yes' or `no' before changing each key.  If
the @samp{-k} option is used, the old and new keys are displayed.

@item add
allows the user to add a key.  @code{add} prompts for name, instance,
realm, and key version number, asks for confirmation, and then asks for
a password.  @code{ksrvutil} then converts the password to a key and
appends the srvtab with the new information.  If the @samp{-k} option
is used, the key is displayed.

@item delete
deletes particular keys in the srvtab, interactively prompting for 
each key.
@end table

In all cases, the default file used is @file{/etc/krb-srvtab} as defined in
@file{krb.h} unless this is overridden by the @samp{-f} option.


@code{ksrvutil} is used to add keys to a key file.  A system manager
asks a Kerberos administrator to create a new service key with
@ref{kadmin} and supplies an initial password.  The manager then uses
@code{ksrvutil} to add the key to the srvtab.  Finally, the manager
changes the key so that it is random and, therefore, unknown to either
the system manager or the Kerberos administrator.

@code{ksrvutil} always makes a backup copy of the srvtab before making
any changes.

@c @subsubheading DIAGNOSTICS
If @code{ksrvutil} should exit on an error condition at any time during
a change or add, a copy of the original srvtab can be found in
@file{@var{filename}.old} where @file{filename} is the name of the
srvtab.  A copy of the file with all new keys, changed or added so far,
can be found in @file{@var{filename}.work}.  The original srvtab is
left unmodified until the program exits.  At that point, it is removed
and replaced it with the workfile.  Appending the workfile to the backup
copy and replacing the srvtab with the result should always give a
usable srvtab.  The resulting srvtab, however, may have some out of
date keys.


@ignore
@subsubheading SEE ALSO
@table @ref
@item kadmin
@item ksrvtgt
@end table
@end ignore

@node ksrvtgt
@subsection @code{ksrvtgt}---fetch and store CNS ticket-granting-ticket using a service key

@c @subsubheading SYNOPSIS 
@smallexample 
ksrvtgt @var{name} @var{instance} [[@var{realm}] @var{srvtab}]
@end smallexample 
@c @subsubheading DESCRIPTION
@code{ksrvtgt} retrieves a ticket-granting ticket with a lifetime of 5
minutes for the principal @var{name}.@var{instance}@@@var{realm} (or
@var{name}.@var{instance}@@@var{localrealm} if realm is not supplied on
the command line), decrypts the response using the service key found in
@var{srvtab} (or in @file{/etc/krb-srvtab} if @var{srvtab} is not
specified on the command line), and stores the ticket in the standard
ticket cache.

This command is intended primarily for use in shell scripts and other
batch-type facilities.  For example, suppose you have one machine with a
tape drive (we'll call it @samp{tapehost}), and you want to be able to
back up all machines on the local network on to that drive, and you want
the backup script to run unattended.

@itemize @bullet
@item Make sure that @file{/etc/krb-srvtab} on @samp{tapehost}
drive has an entry for the @code{rcmd} service.  This is already the
case if @samp{tapehost} is a CNS application server.

@item Add @code{rcmd.tapehost} to the @file{~root/.klogin} file on each
client machine.  This gives anybody with an @code{rcmd.tapehost} ticket
root access to those machines.  (If the backup process on the client
machines need not be run as root, some other user can be used instead).

@item The backup script on @samp{tapehost} can then look something like
this:
@smallexample
for m in @var{clients}; do
  ksrvtgt rcmd @samp{tapehost}
  rsh $m dump | dd of=@var{tapedevice}
done
@end smallexample
The @code{ksrvtgt} command gets a ticket for the principal
@code{rcmd.tapehost} and store it in root's ticket file.  Since
@code{rcmd.tapehost} is in @file{~root/.klogin} on the client machines,
the @code{rsh} is permitted.

@item @code{ksrvtgt} is invoked before each @code{rsh}
command.  This is because the ticket obtained by @code{ksrvtgt} is
short-lived: it is only valid for five minutes.

@item The script must be run by root.  @code{ksrvtgt} must be
able to read the @file{/etc/krb-srvtab} file, which should only be
readable by root.

@item This approach means that if somebody is able to become
root on @samp{tapehost}, they are able to become root on any of the
client machines.  This may introduce a weak point in security, which
should be considered before adding @code{rcmd.tapehost} to the
@file{~root/.klogin} files on the client machines.
@end itemize

@ignore 
@subsubheading DIAGNOSTICS

@samp{Generic Kerberos failure (kfailure)} can indicate a whole range of
problems, the most common of which is the inability to read the service
key file.

@subsubheading FILES
@table @file
@item /usr/kerberos/lib/krb.conf
to get the name of the local realm.
@item /tmp/tkt@var{uid}
The default ticket file.
@item /etc/krb-srvtab
The default service key file.
@end table

@subsubheading SEE ALSO
@table @ref
@item Kerberos Intro
@item kinit
@item kdestroy
@end table
@end ignore

@node kprop and push-kprop
@subsection kprop and push-kprop

@smallexample
kprop [-p] [-force] [-realm @var{realm}] [-private] [-s @var{srvtab}]
      @var{data_file} @var{slaves_file}
@end smallexample

The @code{kprop} program is used to copy the Kerberos database from the
Kerberos master server to a slave server.  Any slave server may serve as
a Key Distribution Center just as the master server does, permitting
people to use CNS client programs even if the master server is
inaccessible.

@xref{Slave Server Installation} for a description of how to use
@code{kprop} and @code{kpropd} to set up slave servers.

The @code{kprop} program communicates with the @code{kpropd} daemon,
which runs on the slave server (@pxref{Slave Servers,kpropd}).

The @var{data_file} argument is a file created by @code{kdb_util} with
the @code{slave_dump} option (@pxref{kdb_util}).

The @var{slaves_file} argument is a text file containing a list of the
hostnames of the slave servers.  It should contain one hostname per
line.  Each hostname may optionally be followed by the port number to
contact, separated by a colon (e.g. host.domain:2754).  The default port
number is found by using @code{getservbyname} to look up the
@samp{krb_prop} service.  If that is not defined, @code{kprop} uses
@samp{754}.

The @code{kprop} program and the @code{kdb_util} program communicate
using a semaphore file.  The name of the file is the @var{data_file}
argument with @file{.dump_ok} appended.  The file is automatically
created by @code{kdb_util} when the @code{slave_dump} option is used.

The @code{push_kprop} shell script may be used to invoke @code{kprop}.
It assumes that the list of slaves is in the file
@file{/usr/kerberos/database/slavelist}.

Normally the Kerberos database is propagated from the server to the
slaves by invoking @code{push_kprop} on a regular basis using
@code{cron}.

The @code{kprop} program requires a srvtab file with an entry for
@samp{rcmd}.@var{HOSTNAME}@@@var{REALM}.  This is the same type of
srvtab file required to run the @code{klogind} or @code{kshd} servers.
Srvtab files can be created using the @code{ksrvutil} program
(@pxref{ksrvutil}).  The default srvtab file is @file{/etc/krb-srvtab}.
This default may be overridden with the @samp{-s} option.

The @samp{-p} option means to use preauthentication when retrieving
tickets.

The @samp{-force} option means to transfer the database even if the
semaphore file generated by @code{kdb_util} indicates that the dump is
not up to date.

The @samp{-realm} @var{realm} option sets the Kerberos realm name.  The
default realm name is obtained using @code{krb_get_lrealm}.

The @samp{-private} option means to encrypt the data being sent to the
slave server.  This is the default.

The @samp{-s} @var{srvtab} sets the name of the srvtab file to use when
retrieving tickets.  The default is @file{/etc/krb-srvtab}.

@node Raw Database Manipulation
@section Raw Database Management
Directly manipulate key database on key distribution center.

@menu
* kdb_edit::    Edit Raw Database
* kdb_init::    Create New Database
* kdb_destroy:: Erase Database
* kdb_util::    Other Manipulation
@end menu

@node kdb_edit
@subsection @code{kdb_edit}---CNS Key Database editing utility

@c @subsubheading SYNOPSIS
@smallexample
kdb_edit [-n] [-k mkeyfile]
@end smallexample

@c @subsubheading DESCRIPTION
@code{kdb_edit} is used to create or change principals stored in the
Kerberos key distribution center (KDC) database.

When executed, @code{kdb_edit} prompts for the master key string and
verifies that it matches the master key stored in the database.  If the
@samp{-n} or @samp{-k} options are specified, the master key is instead
fetched from a master key cache file (as created by @code{kstash}).  The
@samp{-n} option reads the default master key cache file, @file{/.k}.
The @samp{-k} option may be used to name a different key cache file.

Once the master key has been verified, @code{kdb_edit} prompts the user
for the principal and instance to be modified.  If the entry is not
found the user may create it.  Once an entry is found or created, the
user may set the password, expiration date, maximum ticket lifetime, and
attributes.  Default expiration dates, maximum ticket lifetimes, and
attributes are presented in brackets; if the user presses return the
default is selected.  There is no default password.  The password
@samp{RANDOM} is interpreted specially, and if entered the user may have
the program select a random key for the principal.

Upon successfully creating or changing the entry, @samp{Edit O.K.} is
printed.

@ignore
@subsubheading DIAGNOSTICS

@table @code
@item verify_master_key: Invalid master key, does not match database.
The master key string entered was incorrect.
@end table

@subsubheading FILES
@table @file
@item /usr/kerberos/database/principal.pag
@itemx /usr/kerberos/database/principal.dir      
DBM files containing database
@item /.k
Master key cache file.
@end table
@end ignore

@node kdb_init
@subsection @code{kdb_init}---Initialize Kerberos Key Database

@c @subsubheading SYNOPSIS
@smallexample
kdb_init [@var{realm}]
@end smallexample
@c @subsubheading DESCRIPTION
@code{kdb_init} initializes a Kerberos key distribution center database,
creating the necessary principals.

If the optional @var{realm} argument is not present, @code{kdb_init}
prompts for a realm name (or default to the pre-defined value in
@file{/usr/kerberos/include/krb.h}).  After determining the realm to be
created, it prompts for a master key password.  The master key password
is used to encrypt every encryption key stored in the database.  IF THE
MASTER KEY PASSWORD IS LOST, THERE IS NO WAY TO RECOVER ENCRYPTION KEYS
STORED IN THE DATABASE.

@ignore 
@subsubheading DIAGNOSTICS

@table @code
@item /usr/kerberos/database/principal: File exists
An attempt was made to create a database on a machine which already 
had
an existing database.
@end table

@subsubheading FILES
@table @file
@item /usr/kerberos/database/principal.pag
@itemx /usr/kerberos/database/principal.dir
DBM files containing database
@item /usr/kerberos/include/krb.h
Include file defining default realm
@end table

@subsubheading SEE ALSO
@xref{kdb_destroy}.
@end ignore

@node kdb_destroy
@subsection @code{kdb_destroy}---destroy Kerberos Key Database

@c @subsubheading SYNOPSIS
@smallexample
kdb_destroy
@end smallexample
@c @subsubheading DESCRIPTION
@code{kdb_destroy} deletes a Kerberos key distribution center 
database.

The user is prompted to verify that the database should be destroyed.  A
response beginning with @samp{y} or @samp{Y} confirms deletion.  Any
other response aborts deletion.  Extreme caution should be exercised in
the use of this command.

@ignore
@subsubheading DIAGNOSTICS

@table @code
@item Database cannot be deleted at /usr/kerberos/database/principal
The attempt to delete the database failed (probably due to a system or
access permission error).
@item Database not deleted.
The user aborted the deletion.
@end table

@subsubheading FILES
@table @file
@item /usr/kerberos/database/principal.pag
@itemx /usr/kerberos/database/principal.dir
DBM files containing database
@end table

@subsubheading SEE ALSO
@xref{kdb_init}
@end ignore

@node kdb_util
@subsection @code{kdb_util}---Kerberos Key Database utility

@c @subsubheading SYNOPSIS
@smallexample
kdb_util @var{operation} @var{filename}
@end smallexample
@c @subsubheading DESCRIPTION
@code{kdb_util} allows the Kerberos key distribution center (KDC)
database administrator to perform utility functions on the database.

@var{operation} must be one of the following:

@table @code
@item load
Initializes the KDC database with the records described by the text
contained in the file @var{filename}.  Any existing database is
overwritten.
@item dump
dumps the KDC database into a text representation in the file
@var{filename}.
@item slave_dump
performs a database dump like the dump operation, and additionally
creates a semaphore file signaling the propagation software that an
update is available for distribution to slave KDC databases.
@item new_master_key
prompts for the old and new master key strings, and then dumps the KDC
database into a text representation in the file @var{filename}.  The
keys in the text representation are encrypted in the new master key.
@item convert_old_db
prompts for the master key string, and then dumps the KDC database into
a text representation in the file @var{filename}.  The existing database
is encrypted using the old key string (encrypted by the key schedule of
the master key); the dumped database is encrypted using the new key
string (encrypted directly with master key).
@end table

@ignore 
@subsubheading DIAGNOSTICS
@table @code
@item verify_master_key: Invalid master key, does not match database.
The master key string entered was incorrect.
@end table

@subsubheading FILES
@table @file
@item /usr/kerberos/database/principal.pag
@itemx /usr/kerberos/database/principal.dir
DBM files containing database
@item filename.ok
semaphore file created by slave_dump.
@end table
@end ignore

@node Daemons
@chapter Daemons
@menu
* Admin Services::      kadmind
* Interactive Command:: klogind, kshd
* File Transfer::       tftp, tcom
* Slave Servers::       kpropd, in.propd
@end menu

@node Admin Services
@section Admin Services
@menu
* kadmind::     Admin Server
@end menu

@node kadmind
@subsection @code{kadmind}---network daemon for Kerberos database administration

@c @subsubheading SYNOPSIS
@smallexample
kadmind [-n] [-h] [-r @var{realm}] [-f @var{filename}] 
    [-d @var{dbname}] [-a @var{acldir}]
@end smallexample
@c @subsubheading DESCRIPTION
@samp{kadmind} is the network database server for the Kerberos
password-changing and administration tools.

Upon execution, it prompts the user to enter the master key string for
the database.

If the @samp{-n} option is specified, the master key is instead fetched
from the master key cache file.

If the @samp{-r} @var{realm} option is specified, the admin server
pretends that its local realm is @var{realm} instead of the actual local
realm of the host it is running on.  This makes it possible to run a
server for a foreign Kerberos realm.

If the @samp{-f} @var{filename} option is specified, that file is
used to hold the log information instead of the default.

If the @samp{-d} @var{dbname} option is specified, that file is
used as the database name instead of the default.

If the @samp{-a} @var{acldir} option is specified, the directory
@var{acldir} is searched for access control lists.  The default is
@file{/usr/kerberos/database}.

If the @samp{-h} option is specified, @code{kadmind} prints out a short
summary of the permissible control arguments, and then exits.

When performing requests on behalf of clients, @code{kadmind} checks
access control lists (ACLs) to determine if the client is authorized to
perform the requested action.  The ACL files are normally kept in
@file{/usr/kerberos/database}; this may be overridden by the @samp{-a}
option.  Each ACL file is named with a prefix of @file{admin_acl}, and a
suffix indicating the type.  ACL files are simple text files with lists
of principal names, with each principal name on a separate line (i.e.,
the same format as a @file{.klogin} file; @pxref{rlogin, .klogin
files}).

Currently three distinct access types are supported:

@itemize @bullet
@item Addition (@file{.add} ACL file).  If a principal is on this list,
the principal may add new principals to the database.
@item Retrieval (@file{.get} ACL file).  If a principal is on this list,
the principal may retrieve database entries.  NOTE: A principal's
private key is never returned by the get functions.
@item Modification (@file{.mod} ACL file).  If a principal is on this
list, the principal may modify entries in the database. 
@end itemize

A principal is always granted authorization to change its own password.

@subsubheading FILES
@table @file
@item /usr/kerberos/database/admin_server.syslog
Default log file.
@item /usr/kerberos/database
Default access control list directory.
@item admin_acl.add
@itemx admin_acl.get
@itemx admin_acl.mod
Access control list files (within the directory)
@item /usr/kerberos/database/principal.pag
@itemx /usr/kerberos/database/principal.dir
Default DBM files containing database
@item /.k
Master key cache file.
@end table

@ignore
@subsubheading SEE ALSO
@table @ref
@item Kerberos Intro
@item kpasswd
@item kadmin
@item acl_check
@end table
@end ignore

@node Interactive Command
@section Interactive Command
@menu
* popper::      Post Office Server
* klogind::     Kerberized rlogin
* kshd::        Kerberized rsh
@end menu
@node popper
@subsection @code{popper}---pop 3 server

@c @subsubheading SYNOPSIS
@smallexample
/usr/etc/popper [-d] [-t @var{trace-file}]
@end smallexample
@c @subsubheading DESCRIPTION
@code{popper} is an implementation of the Post Office Protocol server
that runs on a variety of Unix computers to manage electronic mail for
Macintosh and MS-DOS computers.  POP allows one host to be a secure mail
server, and allows users on other machines to reliably pick up their
mail from the mail server, without having to log in or worry about NFS
collisions (as could be the case were @var{/var/spool/mail} exported).

The server was developed at the
University of California at Berkeley and conforms fully to the
specifications in RFC 1081 and RFC 1082.  The Berkeley server also has
extensions to send electronic mail on behalf of a client.

@ignore 
@subsubheading THE POP TRANSACTION CYCLE
The Berkeley POP server is a single program (called @code{popper}) that
is launched by @code{inetd} when it gets a service request on the POP
TCP port.  (The official port number specified in RFC 1081 for POP
version 3 is port 110.  However, some POP3 clients attempt to contact
the server at port 109, the POP version 2 port.  Unless you are running
both POP2 and POP3 servers, you can simply define both ports for use by
the POP3 server.  This is explained in the installation instructions
later on.)  The @code{popper} program initializes and verifies that the
peer IP address is registered in the local domain, logging a warning
message when a connection is made to a client whose IP address does not
have a canonical name. For systems using BSD 4.3 bind, it also checks to
see if a canonical name lookup for the client returns the same peer IP
address, logging a warning message if it does not.  The the server
enters the authorization state, during which the client must correctly
identify itself by providing a valid Unix userid and password on the
server's host machine.  No other exchanges are allowed during this state
(other than a request to quit.)  If authentication fails, a warning
message is logged and the session ends.  Once the user is identified,
@code{popper} changes its user and group IDs to match that of the user
and enters the transaction state.  The server makes a temporary copy of
the user's maildrop (ordinarily in @file{/usr/spool/mail}) which is used
for all subsequent transactions.  These the bulk of POP commands to
retrieve mail, delete mail, undelete mail, and so forth.  A Berkeley
extension also allows the user to submit a mail parcel to the server who
mails it using the @code{sendmail} program (this extension is supported
in the HyperMail client distributed with the server).  When the client
quits, the server enters the final update state during which the network
connection is terminated and the user's maildrop is updated with the
(possibly) modified temporary maildrop.

@subsubheading LOGGING
@end ignore

The POP server uses @code{syslog} to keep a record of its activities.
On systems with BSD 4.3 syslogging, the server logs (by default) to the
@samp{local0} facility at priority @samp{notice} for all messages except
debugging which is logged at priority @samp{debug}.  The default log
file is @file{/usr/spool/mqueue/POPlog}.  These can be changed, if
desired.  On systems with 4.2 syslogging all messages are logged to the
local log file, usually @file{/usr/spool/mqueue/syslog}.

@subsubheading DEBUGGING

The @code{popper} program logs debugging information when the @samp{-d}
parameter is specified after its invocation in the @file{inetd.conf}
file.  The @samp{-d} flag sets the socket to debugging and turns on
debugging.  All debugging information is saved using @code{syslog}(8).
Care should be exercised in using this option since it generates
considerable output in the syslog file.  Alternatively, the @samp{-t
@var{file-name}} option places debugging information into file
@var{`file-name'} using @code{fprintf} instead of @code{syslog}.

You can confirm that the POP server is running on Unix by
@code{telnet}ing to port 110 (or 109 if you set it up that way).  For
example:

@smallexample
     %telnet @var{myhost} 110
     Trying...
     Connected to @var{myhost}.berkeley.edu.
     Escape character is '^]'.
     +OK UCB Pop server (version 1.6) at @var{myhost} starting.
     quit
     Connection closed by foreign host.
@end smallexample

@subsubheading FILES
@table @file
@item /usr/spool/mail
mail files
@item /etc/inetd.conf
pop program invocation
@item /etc/syslog.conf
logging specifications
@end table

@ignore
@subsubheading SEE ALSO
@code{inetd}(8), RFC1081, RFC1082.
@end ignore



@node klogind
@subsection @code{klogind}---Kerberos remote login server

@c @subsubheading SYNOPSIS
@smallexample
/usr/kerberos/etc/klogind
/usr/kerberos/etc/Klogind
/usr/kerberos/etc/eklogind
@end smallexample
@c @subsubheading DESCRIPTION
@code{klogind} is the server for the Kerberos version of the
@ref{rlogin} program.  The server provides a remote login facility with
authentication provided by Kerberos.

@code{klogind} listens for service requests at the port indicated in the
@code{klogin} or @code{eklogin} service specification; see
@samp{services}(5).

In the past, invocation as @code{klogind} was used for normal hosts to
which password access was granted if Kerberos authentication failed,
whereas invocation as @code{Klogind} required Kerberos authentication.
However, this distinction has been removed, because @code{klogind} does
not behave identically to the traditional @code{rlogind} server, and
because the password fallback does not work with encryption.  Invocation
as @code{klogind} is now identical to invocation as @code{Klogind}.  It
is still possible to run the system provided @code{rlogind} server to
permit access with a password.

Invocation as @code{eklogind} provides an encrypted communications
channel.

When a service request is received, the server checks the client's
source address and requests the corresponding host name (see
@code{gethostbyaddr}(3N), @samp{hosts}(5) and @samp{named}(8)).  If the
hostname cannot be determined, the dot-notation representation of the
host address is used.

Once the source address has been checked, @code{klogind} allocates a
pseudo terminal (see @samp{pty}(4)), and manipulates file descriptors so
that the slave half of the pseudo terminal becomes the @code{stdin},
@code{stdout}, and @code{stderr} for a login process.  The login process
is an instance of the @code{login}(1) program, invoked with the
@samp{-k}, @samp{-K}, or @samp{-e} option, depending on whether the
@code{klogind} was started as @code{klogind}, @code{Klogind} or
@code{eklogind}, respectively.  The login process then proceeds with the
authentication process as described in @ref{kshd}, but if automatic
authentication fails, the user is re-prompted to login as one would on a
standard terminal line.

The parent of the login process manipulates the master side of the
pseudo terminal, operating as an intermediary between the login process
and the client instance of the @code{rlogin} program.  If @code{klogind}
is invoked as @code{eklogind}, all data passed over the network are
encrypted.  In normal operation, the packet protocol described in
@samp{pty}(4) is invoked to provide @kbd{^S}/@kbd{^Q} type facilities
and propagate interrupt signals to the remote programs.  The login
process propagates the client terminal's baud rate and terminal type, as
found in the environment variable, @samp{TERM}; see @samp{environ}(7).
The screen or window size of the terminal is requested from the client,
and window size changes from the client are propagated to the pseudo
terminal.

@code{Klogind}
accepts three options which may be used for testing purposes.

The @samp{-l} @var{login_program} option sets the login program to
run.  The default value is normally
@file{/usr/kerberos/etc/login.krb}.

The @samp{-r} @var{realm_file} option sets the name of the
@file{krb.realms} file to use.  The default value is normally
@file{/usr/kerberos/lib/krb.realms}.  @xref{krb.realms}.

The @samp{-s} @var{srvtab_file} option sets the name of the srvtab
file to use.  The default value is normally @file{/etc/krb-srvtab}.

@ignore 
@subsubheading DIAGNOSTICS

All diagnostic messages are returned on the connection associated with
the stderr, after which any network connections are closed.  An error is
indicated by a leading byte with a value of 1.
@table @code
@item Try again.
A @code{fork} by the server failed.
@item /bin/sh: @dots{}
The user's login shell could not be started.
@end table
@ignore
@subsubheading SEE ALSO
@xref{kerberos}.

@subsubheading BUGS

A more extensible protocol should be used.
@end ignore

@node kshd
@subsection @code{kshd}---Kerberos remote shell server

@c @subsubheading SYNOPSIS
@smallexample
/usr/kerberos/etc/kshd
@end smallexample

@c @subsubheading DESCRIPTION
@code{kshd} is the server for the @code{kcmd} routine and, 
consequently,
for the @ref{rsh} program.  The server provides remote execution
facilities with authentication based on Kerberos.

@code{kshd} listens for service requests at the port indicated in the
@samp{kshell} service specification; see @samp{services}(5).  When a
service request is received the following protocol is initiated:

@enumerate
@item
The server reads characters from the socket up to a null (\0) byte.  
The resultant string is interpreted as an ASCII number, base 10.
@item
If the number received in step 1 is non-zero, it is interpreted as the
port number of a secondary stream to be used for the @code{stderr}.  A
second connection is then created to the specified port on the client's
machine.
@item
The server checks the client's source address and requests the
corresponding host name (see @code{gethostbyaddr}(3N), 
@samp{hosts}(5)
and @samp{named}(8)).  If the hostname cannot be determined, the
dot-notation representation of the host address is used.
@item
  A Kerberos ticket/authenticator pair are retrieved on the initial
socket. 
@item 
 A null terminated user name of at most 16 characters is retrieved on
the initial socket. This user name is interpreted as a user identity to
use on the server's machine.
@item 
 A null terminated command to be passed to a shell is retrieved
on the initial socket.  The length of the command is limited by the
upper bound on the size of the system's argument list.
@item
@code{kshd} then validates the user according to the following steps.
The local (server-end) user name is looked up in the password file and a
@code{chdir} is performed to the user's home directory.  If either the
lookup or @code{chdir} fail, the connection is terminated.  The
@file{.klogin} file in the home directory is used to mediate access to
the account (via @samp{kuserok}) by the Kerberos principal named in the
ticket/authenticator.  If this authorization check fails, the connection
is terminated.
@item
 A null byte is returned on the initial socket and the command line is
passed to the normal login shell of the user.  The shell inherits the
network connections established by @code{kshd}.
@end enumerate

@code{kshd}
accepts three options which may be used for testing purposes.

The @samp{-p} @var{directory} option sets the directory where Kerberos
programs are found.  This directory is put at the start of @samp{PATH}
before the command is executed.  The default value is normally
@file{/usr/kerberos/bin}.  (For correct operation of Kerberos
@code{rcp}, the Kerberos @code{rcp} program must be in @samp{PATH}
before any other @code{rcp} program.  @xref{rcp}).

The @samp{-r} @var{realm_file} option sets the name of the
@file{krb.realms} file to use.  The default value is normally
@file{/usr/kerberos/lib/krb.realms}.  @xref{krb.realms}.

The @samp{-s} @var{srvtab_file} option sets the name of the srvtab
file to use.  The default value is normally @file{/etc/krb-srvtab}.

@subsubheading DIAGNOSTICS

Except for the last one listed below, all diagnostic messages are
returned on the initial socket, after which any network connections are
closed.  An error is indicated by a leading byte with a value of `1'
(zero is returned in step 8 above upon successful completion of all the
steps prior to the execution of the login shell).
@table @code
@item remuser too long
The name of the user on the remote machine is longer than 16
characters.
@item command too long
The command line passed exceeds the size of the argument list (as
configured into the system).
@item Login incorrect.
No password file entry for the user name existed.
@item No remote directory.
The @code{chdir} command to the home directory failed.
@item Permission denied.
The authorization procedure described above failed.
@item Can not make pipe.
The pipe needed for the @code{stderr}, was not created.
@item Try again.
A @code{fork} by the server failed.
@item @var{shellname}: @dots{}
The user's login shell could not be started.  This message is returned on
the connection associated with the @code{stderr}, and is not preceded by
a flag byte.
@end table

@ignore
@subsubheading SEE ALSO
@table @ref
@item rsh
@item Kerberos
@item kuserok
@end table
@end ignore

@ignore
@subsubheading BUGS

A facility to allow all data exchanges to be encrypted should be
present.

A more extensible protocol should be used.
@end ignore

@node File Transfer
@section File Transfer
@menu
* tftpd::       TFTP
* tcom::        TCOM
@end menu
@node tftpd
@subsection @code{tftpd}---server tftp daemon

@c @subsubheading SYNOPSIS
@smallexample
/etc/tftpd
@end smallexample
@c @subsubheading DESCRIPTION
@code{tftpd} is a daemon which runs the trivial file transfer protocol
server.  It listens for incoming connections, and forks a child to
perform each requested transfer.  It uses the directory @file{/tftpd};
the file @file{lock} in that directory is used to prevent two daemons from
becoming active simultaneously; it also contains the daemon's process
ID, which is used by the @code{tftp} command program @ref{tcom} to
control the daemon's operation.


@subsubheading FILES
@table @file
@item /tftpd/lock
interlock, PID storage
@item /dev/net
the network device
@end table

@ignore
@subsubheading SEE ALSO
@table @ref
@item tftp
@item tcom
@item Internet Protocol Handbook
@end table
@end ignore

@node tcom
@subsection @code{tcom}---control operation of server tftp daemon

@c @subsubheading SYNOPSIS
@smallexample
tcom
@end smallexample
@c @subsubheading DESCRIPTION
@code{tcom} is a program to control the execution of the server trivial
file transfer daemon.  It sends user commands to the daemon by writing
them into a shared file and signaling the daemon; it watches the
daemon's log to obtain the results of the commands.  The following
commands are supported:
@table @code
@item help
display a list of commands
@item input trace on|off
turn tracing of input packets on or off
@item output trace on|off
turn tracing of output packets on or off
@item trace on|off
turn all packet tracing on or off
@item times
display server parent and children  process times
@item uptime
display daemon up time
@item exit
force daemon to shut down and exit
@end table
@subsubheading FILES
@table @file
@item /tftpd/lock
lock file containing daemon's PID
@item /tftpd/command
command file to daemon
@item /tftpd/slog
daemon's log file
@end table

Note that two @code{tcom}s running at the same time result in chaos.  Be
aware that watching the daemon's log file uses a lot of CPU time.

@node Slave Servers
@section Slave Servers

@smallexample
kpropd [-r @var{realm}] [-s @var{srvtab}] [-d @var{database}]
       [-u @var{port}] [-l @var{logfile}] [-i] [-c @var{command}]
       [-C @var{arg}] @var{filename}
@end smallexample

The @code{kpropd} daemon runs on a Kerberos slave server.  A Kerberos
slave server holds a copy of the master Kerberos database.  Any slave
server may serve as a Key Distribution Center just as the master server
does, permitting people to use Kerberos programs even if the master
server is inaccessible.

@xref{Slave Server Installation} for a description of how to use
@code{kprop} and @code{kpropd} to set up slave servers.

The @code{kprop} program running on the master server contacts the
@code{kpropd} daemon running on the slave server in order to copy over
the Kerberos database (@pxref{kprop and push-kprop}).

The
@code{kpropd}
daemon is normally started by arranging for
@code{inetd}
to run the
@code{in.kpropd}
shell script.  Normally, a line like this would be added to the
@file{/etc/inetd.conf}
file:

@smallexample
krb_prop stream tcp nowait root /usr/kerberos/etc/in.kpropd in.kpropd
@end smallexample

The @code{kpropd} daemon may also be run directly as a server.

The @code{kpropd} daemon has a single required argument, which is the
name of a file in which to store the database received from @code{kprop}
running on the master server (the @code{in.kpropd} script passes
@file{/usr/kerberos/database/slavedb}).  After @code{kpropd} receives
the database information, it runs @code{kdb_util} to load it into the
local Kerberos database (@pxref{kdb_util}).

The @code{kpropd} daemon only accepts data from machines which are
listed in @file{krb.conf} as an admin server (@pxref{krb.conf}).

The @samp{-r} @var{realm} option sets the Kerberos realm name.  The
default realm is obtained using @code{krb_get_lrealm}.

The @samp{-s} @var{srvtab} option sets the name of the srvtab file to
use when authenticating the ticket received from @code{kprop}.  The
default is @file{/etc/krb-srvtab}.

The @samp{-d} @var{database} option sets the name of the Kerberos
database.  This is a prefix used to name three files.  The default is
@file{/usr/kerberos/database/principal}.

The @samp{-u} @var{port} option sets the port to accept connections on.
This is only meaningful if the @samp{-i} option is not used.  The
default is to use @code{getservbyname} to look up the @samp{krb_prop}
service.  If that is not defined, @code{kpropd} uses @samp{754}.

The @samp{-l} @var{logfile} option sets the name of the log file.  The
default is @file{/usr/kerberos/database/kpropd.log}.

The @samp{-i} option causes @code{kpropd} to assume that it was run from
@code{inetd}.  The default is for @code{kpropd} to open a socket and to
loop accepting connections.

The @samp{-c} @var{command} option sets the path of the @code{kdb_util}
command which @code{kpropd} should run after receiving the database.
The default is to just run @code{kdb_util}, assuming it is on
@samp{PATH}.

The @samp{-C} @var{arg} option sets the argument to pass to
@code{kdb_util}.  The default argument is @code{load}.

@node Glossary
@chapter A Glossary of Kerberos Terms

@itemize @bullet
@item @strong{Kerberos (Cerberus):} A figure out of Greek and Roman 
mythology, the three-headed dog who guards the entrance to the 
underworld.  Kerberos would howl at the presence of the living among the 
dead.

@item @strong{ACL:} Access Control List.
An access control list determines who has access to do particular
operations.  In Kerberos V4, access control lists are only used to
control access to administrative operations (such as adding users or
changing passwords), and are kept as ordinary ASCII files in
@file{/usr/kerberos/database/admin_acl.*}.  The three lists there control
who can add, get information about, and modify information about
principals in the Kerberos database.

@item @strong{application server:} A program that provides a service,
typically to multiple people at the same time.  For example, file
transfers on the Internet are handled by FTP servers and NFS servers.
You can log in to other machines by using a @code{telnet} server or an
rlogin server.  Application servers often run as ``daemons,'' which are
programs that run quietly in the background inside a machine, invisible
to the person at the console.  (See, `principal'.)

@item @strong{authentication:} The process of proving that you are
who you claim to be.  It usually involves validating a user's identity
by means of a multiple-step transaction.  Automated teller machines do
authentication by making you provide a token (your ATM card) and then
type in a PIN or other secret number to prove you are using the card
legitimately.  Kerberos provides authentication across a computer
network, without revealing the authentication information to
wiretappers.  Once you are authenticated to a host, either Kerberos or
some other process @emph{authorizes} you to perform certain functions.

@item @strong{authorization:} A process whereby you get permission to 
perform actions.  In the example of the bank machine above, you are
@emph{authenticated} to the bank machine by using your card and PIN
number; then the bank's computer @emph{authorizes} you to receive money
if it determines you have enough in your account.  Kerberos provides
simple authorization service via the ACL system; other authorization
services can be built on top of Kerberos if the system administrator
wishes.

@item @strong{client:} A partner in a client-server relationship.  The
client acts as the users' interface to the services offered by the
application server.  (See, `principal'.)

@item @strong{domain:} As in feudal days, a @emph{domain} is an area over
which one administrator exercises control.

@item @strong{Domain Name Service:} 
A service which translates Internet host names to and from numeric
IP addresses.  DNS (as it is usually known) also provides additional
services (e.g., managing email delivery).

@item @strong{instance:} An instance refers to a particular
@emph{role} of a user.  For example, Kerberos administrators have two
roles: that of an ordinary user (with an empty instance); and that of
an administrator (with an instance of @emph{admin}).  Instances are
normally written after the principal name, separated by a dot, as in
@samp{person.admin}.  Some programs (@code{kinit} and @code{kdb_edit})
prompt separately for a principal name and an instance name.
Instances are also used with keys for programs, to indicate on which
hostname the program runs.  For example, @samp{rcmd.host1@@your-realm}
is the principal name for the @code{rcmd} service (the name used by
@code{rlogin, rcp}, and @code{rsh}) for @samp{host1} in your realm.
(See, `principal'.)
 
@item @strong{key:} The encryption secret used to encrypt and decrypt
network @code{rlogin} sessions and other transactions.  Each session has
a temporary key associated with it for exchanging authentication
information (and possibly encrypting other data as well), and each user
and application server has a key of its own.  Users' keys are generated
from their passwords.  The application server's key is generally stored
in a file.

@item @strong{principal:} A Kerberos principal can be a user,
a host, a service, a client, or an application server.  The term
@emph{principal} is a generic name used to describe actors in the
Kerberos function.  The principal name is usually a user's or
application server's name.  Sometimes the entire string
@samp{principal.instance@@realm} is called the principal name.

@item @strong{realm:} An administrative domain which operates a
Kerberos authentication service.  Each user in the realm is identified
in the same way to all machines in the realm.  Realm names are in
capital letters by convention.  For one-host sites, the realm name is
the same as the host name (in capital letters).  At larger sites, the
realm name is usually the capitalized name of the main Internet domain
(e.g., CYGNUS.COM or EFF.ORG).  At large sites, there may be several
realms (e.g., ENG.SUN.COM and MKTG.SUN.COM).

@item @strong{server:} See `application server'.

@item @strong{ticket:} A software token used to securely pass the
identity of a user from the one Kerberos host to another.  Tickets
contain the name of the server, the name of the client, the Internet
address of the client, a time-stamp, a lifetime (or expiration time)
of the ticket, and a random session key.  The contents of the
so-called @emph{ticket file,} where the Kerberos client looks to find
authentication information, is sometimes incorrectly referred to as a
ticket, as well.
@end itemize

@node Authors
@chapter Authors and Contributors

The following people helped out on various aspects of the
system:

Jeff Schiller designed and wrote the administration server and its
user interface, kadmin.  He also wrote the DBM version of the database
management system.

Mark Colan developed the Kerberos versions of rlogin, rsh, and rcp, as
well as contributing work on the servers.

John Ostlund developed the Kerberos versions of passwd and
userreg.

Stan Zanarotti pioneered Kerberos in a foreign realm (LCS),
and made many contributions based on that experience.

Many other people contributed code and/or useful ideas, including: 

@itemize @bullet
@item Bill Bryant, MIT Project Athena
@item Bill Sommerfeld, MIT Project Athena
@item Bob Baldwin
@item Bob McKie, MIT Project Athena
@item Brian Murphy, MIT Project Athena
@item Chris Reed, MIT Project Athena
@item Clifford Neuman, MIT Project Athena
@item Dan Geer, MIT Project Athena
@item David Jedlinsky, MIT Project Athena
@item Douglas A. Church, MIT Project Athena
@item Emanuel Jay Berkenbilt, MIT Project Athena
@item Jeffrey I. Schiller, MIT Project Athena
@item Jennifer Steiner, MIT Project Athena
@item Jim Aspnes, MIT Project Athena
@item Jim Bloom
@item John Barba
@item John T. Kohl, Project Athena/Digital Equipment Corporation
@item John Kubiatowicz, MIT Project Athena
@item Jon Rochlis, MIT Project Athena
@item Ken Raeburn, MIT Project Athena (Now at Cygnus Support)
@item Mark Eichin, Cygnus Support
@item Mike Shanzer, MIT Project Athena
@item Richard Basch, MIT Project Athena
@item Rob French, MIT Project Athena
@item Steve Miller, MIT Project Athena/Digital Equipment  Corporation
@item Ted Ts'o, MIT Project Athena
@item Win Treese, MIT Project Athena/Digital Equipment Corporation
@end itemize

The POP Mail server was the work of:

Bob Campbell, Edward Moy, Austin Shelton, Marshall T. Rose, and cast of
thousands at Rand, UDel, UCI, and elsewhere.  Kerberos authentication
added by Tom Coppeto---MIT Network Services.

Documentation credits include:
@itemize @bullet
@item Massachusetts Institute of Technology, for the @strong{man} pages which
formed the basis of some sections of this documentation.
@item John Gilmore, Mark Eichin and Ken Raeburn of Cygnus Support.
@item Kerberos Users' Frequently Asked Questions Guide, compiled by: 
Barry Jaspan, <bjaspan@@security.ov.com>, OpenVision Technologies.
@end itemize

@node Appendix
@appendix SecureNet Key Authentication Device

@menu
* Intro::                       A brief introduction
* SecureNet Key Device::        Describes the hardware device
* Example of Use::              How it looks to the user
* Protocol Design::             The cryptographic protocol we use
* Cryptographic Design::        Analysis of the protocol's strength
* Implementation::              How we implemented it in Kerberos V4
@end menu

@node Intro
@section Kerberos SecureNet Extension

We at Cygnus Support have designed a simple extension to the Kerberos IV
protocol to support the use of a particular challenge-response
authenticator device, the SecureNet Key.  The device uses DES to encrypt
a randomly generated challenge, producing an 8 decimal digit response.

@node SecureNet Key Device
@section The SecureNet Key Devise

The SecureNet Key device (SNK4) is a product of Digital Pathways.  The
function of the device is simple.

@table @emph
@item Initialization
At first application of power, it is loaded with a DES key, and then a
PIN.  The PIN can be changed later, the DES key can only be changed by
removing the batteries from the device.

@item Use
The device holder is then given a ``challenge,'' consisting of a
randomly generated six digit value.  They power on the device, enter the
PIN, and then enter the challenge.  An eight digit response is
displayed, which the device holder enters into the system, confirming
their identity.

@item Theory
The challenge is interpreted as six ASCII characters.  Two zero bytes
are added to the end of this string, producing an eight character
plaintext block.  This block is fed to the DES ECB encryption function,
using the device key to encrypt it.  The first four bytes of the
resulting block are displayed as the response, as eight hexadecimal
digits.

The display itself is not complete---when the digits @samp{A}, @samp{B},
or @samp{C} appear, they are replaced by the digit @samp{2}; likewise
@samp{D}, @samp{E}, and @samp{F} are replaced by @samp{3}.  This permits
the response to be entered in using only a numeric keypad, and avoids
confusing a user who might not be familiar with non-decimal number
systems.

@end table

@node Example of Use
@section Example of SecureNet Key use

To use an SNK4 device for Kerberos authentication:

@display
% kinit -s username
Challenge: 123456
Response:12345678
% klist
Ticket file:    /tmp/tkt86
Principal:      username.+SNK4@@REALM.ORG

  Issued           Expires          Principal
Dec 31 18:35:30  Dec 32 04:35:30  krbtgt.REALM.ORG@@REALM.ORG
@end display

or

@display
% kinit -s username
Challenge #1: 123456
Response #1:12345678
Challenge #2: 789012
Response #2:78901234
% 
@end display

@node Protocol Design
@section Protocol Design for using the SecureNet Key

Because of the requirement for replicated Key Distribution Centers, it
is impractical to add persistent state about the challenge and response.
(It would at first seem an obvious approach---use existing
pre-authentication support to get the response from the user---except
that if the challenge is not generated by the server, it is vulnerable
to replay.)

Thus, we use the response directly as a shared secret, as the key for
the TGT itself.  We have designed two modes, one which uses a single
challenge, one which uses two independent challenges.  The single
challenge is convenient, but is cryptographically weak enough that it
should only be used for short-lived TGTs, and perhaps should not even be
used there, as it can expose information about challenge-response pairs
that can be used to attack the stronger two-challenge system.  (Note
that the two-challenge version does not cause additional traffic---the
TGT is returned with both challenges as part of the package.)

@node Cryptographic Design
@section Cryptographic Analysis of Protocol Design

For this analysis, we assume that the attacker can perform
known-plaintext attacks on the ticket-granting ticket at a rate of
roughly 25K tries per second.  The first block is random (the session
key) so the attacker needs to chain to the second block, which has the
service principal name, which is known.  (In this case, it is the string
@samp{krbtgt} followed by a zero byte---the eighth byte of the block is
the first character of the realm name, also known.)

The SNK4 device takes basically 20 bits of input and produces 26+ bits
of output; the input bits are public and shared between the KDC and the
user, the output bits are a secret and shared between the KDC and the
user (as the original DES key itself is secret.)

Simply using the response (padded with zero bits) as a key means that
the TGT can be brute forced in roughly an hour, leaving plenty of time
to actually use it.  Also, a lookup table (for a given user/device) that
is indexed by challenge only needs a million 56 bit entries, and would
probably provide enough savings over time to be worth keeping.

Using additional common information (such as the challenge itself or a
common timestamp) for the padding bits would eliminate the advantage of
the lookup table, but would not help against the brute force attack
itself.

Requiring that the user take @emph{two} independent challenges and enter
both responses would double the amount of shared secret material,
squaring the expense of the brute force attack.  This would drive it up
closer to twelve thousand years, keeping the original assumptions---54
bits is nearly as good as a single DES key itself.  (Put another way, a
double challenge takes only one-eighth as long a time to crack as the
internal key itself would.)

@node Implementation
@section Implementation of SecureNet Key in Kerberos V4

There are four parts to this extension:

@table @samp
@item @code{krb_get_in_tkt}
The library function @code{krb_get_in_tkt} already has hooks for a
callback function to do the necessary work.  Callbacks do not work in
Mac drivers, though, so we have split the function around the callback
into @code{krb_mk_in_tkt} and @code{krb_parse_in_tkt} to allow the
client to do the challenge and response locally, without the callback.
@item @code{kinit -s}
An alternate mode of use of of @code{kinit} is provided which prompts as
before but adds +SNK4 to the instance, allowing the KDC to identify and
generate a different response.
@item Kerberos (KDC)
A modification of the normal KDC which recognizes the @samp{+SNK4}
string at the end of an instance and uses the key in the database as the
device key instead of the user's key, and then generates a pair of
challenges, works out the responses, and uses them for the TGT key
instead of the user's key.
@item @code{kadmin snk}
A new query to the @code{kadmin} program, @code{add_snk_key} or
@code{snk} which generates and displays random keys for use initializing
or reinitializing SNK4 devices.  Includes key verification check.
@end table

Since the user is authenticated as
@var{user}@strong{.+SNK4@@}@var{realm} instead of simply
@var{user}@strong{@@}@var{realm} access control can be done using the
standard ACL files---@file{~root/.klogin} for example.

The protocol changes are simple.
@table @emph
@item Request
The request is unchanged, except for the addition of @samp{+SNK4} to the
instance.
@item Reply
The reply is distinctly different, but should not matter as only
@code{kinit -s} ever sees one.

The structure is:
@table @samp
@item version
The eight characters @samp{cnssnk01}
@item challenge 1
Also eight characters, six digits and two zero bytes.
@item challenge 2
Same format as challenge 1. If this is the same string, the user is only
issued one challenge.
@item encrypted ticket
Same as the original protocol raw ticket.
@end table
@end table

Challenge 1 and challenge 2 are encrypted and the first four bytes of
each (with the conversion to digits mentioned elsewhere) are used as key
material.  In order to mix the bits effectively, the two resulting
strings are concatenated, producing eight bytes, which we will call key
1.  Key 1 is used to encrypt key 1, producing key 2.  This avoids losing
particular bits of the response when we fix up the parity.

If we put this data at the end, a normal @code{kinit} could still
decrypt the ticket if it had the right key---but it could not, so we do
not do that.

@contents
@c end of texinfo file
@bye


@c (modify-syntax-entry ?_ "w" para-mode-syntax-table)
@c (modify-syntax-entry ?- "w" para-mode-syntax-table)
@c (modify-syntax-entry ?/ "w" para-mode-syntax-table)