This file describes how to use the Kerberos V5 client programs.

Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 by the
Massachusetts Institute of Technology.

     Export of software employing encryption from the United States of
     America may 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.

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.

Kerberos V5 includes documentation and software developed at the
University of California at Berkeley, which includes this copyright
notice:

Copyright (C) 1983 Regents of the University of California.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the
     distribution.

  3. All advertising materials mentioning features or use of this
     software must display the following acknowledgement:
          This product includes software developed by the University of
          California, Berkeley and its contributors.

  4. Neither the name of the University nor the names of its
     contributors may be used to endorse or promote products derived
     from this software without specific prior written permission.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notices 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.

Introduction
************

Kerberos V5 is based on the Kerberos V5 authentication system developed
at MIT.  Kerberos is named for the three-headed watchdog from Greek
mythology, who guarded the entrance to the underworld.

Under Kerberos, a client (generally either a user or a service) sends a
request for a ticket to the Key Distribution Center (KDC).  The KDC
creates a "ticket-granting ticket" (TGT) for the client, encrypts it
using the client's password as the key, and sends the encrypted TGT back
to the client.  The client then attempts to decrypt the TGT, using its
password.  If the client successfully decrypts the TGT (i.e., if the
client gave the correct password), it keeps the decrypted TGT, which
indicates proof of the client's identity.

The TGT, which expires at a specified time, permits the client to obtain
additional tickets, which give permission for specific services.  The
requesting and granting of these additional tickets is user-transparent.

Since Kerberos negotiates authenticated, and optionally encrypted,
communications between two points anywhere on the internet, it provides
a layer of security that is not dependent on which side of a firewall
either client is on.  Since studies have shown that half of the computer
security breaches in industry happen from inside firewalls, MIT's
Kerberos V5 plays a vital role in maintaining your nework security.

The Kerberos V5 package is designed to be easy to use.  Most of the
commands are nearly identical to UNIX network programs you are already
used to.  Kerberos V5 is a "single-sign-on" system, which means that
you have to type your password only once per session, and Kerberos does
the authenticating and encrypting transparently.

What is a Ticket?
=================

Your Kerberos "credentials", or ""tickets"", are a set of electronic
information that can be used to verify your identity.  Your Kerberos
tickets may be stored in a file, or they may exist only in memory.

The first ticket you obtain is a "ticket-granting ticket", which
permits you to obtain additional tickets.  These additional tickets give
you permission for specific services.  The requesting and granting of
these additional tickets happens transparently.

A good analogy for the ticket-granting ticket is a three-day ski pass
that is good at four different resorts.  You show the pass at whichever
resort you decide to go to (until it expires), and you receive a lift
ticket for that resort.  Once you have the lift ticket, you can ski all
you want at that resort.  If you go to another resort the next day, you
once again show your pass, and you get an additional lift ticket for the
new resort.  The difference is that the Kerberos V5 programs notice
that you have the weekend ski pass, and get the lift ticket for you, so
you don't have to perform the transactions yourself.

What is a Kerberos Principal?
=============================

A Kerberos "principal" is a unique identity to which Kerberos can
assign tickets.  By convention, a principal is divided into three parts:
the "primary", the "instance", and the "realm".  The format of a
typical Kerberos V5 principal is `primary/instance@REALM'.

   * The "primary" is the first part of the principal.  In the case of
     a user, it's the same as your username.  For a host, the primary is
     the word `host'.

   * The "instance" is an optional string that qualifies the primary.
     The instance is separated from the primary by a slash (`/').  In
     the case of a user, the instance is usually null, but a user might
     also have an additional principal, with an instance called
     `admin', which he/she uses to administrate a database.  The
     principal `jennifer@ATHENA.MIT.EDU' is completely separate from
     the principal `jennifer/admin@ATHENA.MIT.EDU', with a separate
     password, and separate permissions.  In the case of a host, the
     instance is the fully qualified hostname, e.g.,
     `daffodil.mit.edu'.

   * The "realm" is your Kerberos realm.  In most cases, your Kerberos
     realm is your domain name, in upper-case letters.  For example,
     the machine `daffodil.mit.edu' would be in the realm
     `ATHENA.MIT.EDU'.

Kerberos V5
utorial
********************

This tutorial is intended to familiarize you with the Kerberos V5
client programs.  We will represent your prompt as "`shell%'".  So an
instruction to type the "`ls'" command would be represented as follows:

     shell% ls

In these examples, we will use sample usernames, such as `jennifer' and
`david', sample hostnames, such as `daffodil' and `trillium', and
sample domain names, such as `mit.edu' and `fubar.org'.  When you see
one of these, substitute your username, hostname, or domain name
accordingly.

Setting Up to Use Kerberos V5
=============================

Your system administrator will have installed the Kerberos V5 programs
in whichever directory makes the most sense for your system.  We will
use `/usr/krb5' throughout this guide to refer to the top-level
directory Kerberos V5 directory.  We will therefor use `/usr/krb5/bin'
to denote the location of the Kerberos V5 user programs.  In your
installation, the directory name may be different, but whatever the
directory name is, you should make sure it is included in your path.
You will probably want to put it ahead of the directories `/bin' and
`/usr/bin' so you will get the Kerberos V5 network programs, rather
than the standard UNIX versions, when you type their command names.

Ticket Management
=================

On many systems, Kerberos is built into the login program, and you get
tickets automatically when you log in.  Other programs, such as /`rsh',
`rcp', `telnet', and `rlogin', can forward copies of your tickets to
the remote host.  Most of these programs also automatically destroy
your tickets when they exit.  However, MIT recommends that you
explicitly destroy your Kerberos tickets when you are through with
them, just to be sure.  One way to help ensure that this happens is to
add the `kdestroy' command to your `.logout' file.  Additionally, if
you are going to be away from your machine and are concerned about an
intruder using your permissions, it is safest to either destroy all
copies of your tickets, or use a screensaver that locks the screen.

Obtaining Tickets with kinit
----------------------------

If your site is using the Kerberos V5 login program, you will get
Kerberos tickets automatically when you log in.  If your site uses a
different login program, you may need to explicitly obtain your Kerberos
tickets, using the `kinit' program.  Similarly, if your Kerberos
tickets expire, use the `kinit' program to obtain new ones.

To use the `kinit' program, simply type `kinit' and then type your
password at the prompt.  For example, Jennifer (whose username is
`jennifer') works for Bleep, Inc. (a fictitious company with the domain
name `mit.edu' and the Kerberos realm `ATHENA.MIT.EDU').  She would
type:

     shell% kinit
     Password for jennifer@ATHENA.MIT.EDU: <-- [Type jennifer's password here.]
     shell%

If you type your password incorrectly, kinit will give you the following
error message:

     shell% kinit
     Password for jennifer@ATHENA.MIT.EDU: <-- [Type the wrong password here.]
     kinit: Password incorrect
     shell%

and you won't get Kerberos tickets.

Notice that `kinit' assumes you want tickets for your own username in
your default realm.  Suppose Jennifer's friend David is visiting, and
he wants to borrow a window to check his mail.  David needs to get
tickets for himself in his own realm, FUBAR.ORG.(1)  He would type:

     shell% kinit david@FUBAR.ORG
     Password for david@FUBAR.ORG: <-- [Type david's password here.]
     shell%

David would then have tickets which he could use to log onto his own
machine.  Note that he typed his password locally on Jennifer's
machine, but it never went over the network.  Kerberos on the local host
performed the authentication to the KDC in the other realm.

If you want to be able to forward your tickets to another host, you need
to request "forwardable" tickets.  You do this by specifying the `-f'
option:

     shell% kinit -f
     Password for jennifer@ATHENA.MIT.EDU: <-- [Type your password here.]
     shell%

Note that `kinit' does not tell you that it obtained forwardable
tickets; you can verify this using the `klist' command (see Viewing Your Tickets with klist.).

Normally, your tickets are good for your system's default ticket
lifetime, which is ten hours on many systems.  You can specify a
different ticket lifetime with the `-l' option.  Add the letter `s' to
the value for seconds, `m' for minutes, `h' for hours, or `d' for days.
For example, to obtain forwardable tickets for `david@FUBAR.ORG' that
would be good for three hours, you would type:

     shell% kinit -f -l 3h david@FUBAR.ORG
     Password for david@FUBAR.ORG: <-- [Type david's password here.]
     shell%

You cannot mix units; specifying a lifetime of `3h30m' would result in
an error.  Note also that most systems specify a maximum ticket
lifetime.  If you request a longer ticket lifetime, it will be
automatically truncated to the maximum lifetime.

---------- Footnotes ----------

(1)  Note:  the realm FUBAR.ORG must be listed in your computer's
Kerberos configuration file, `/etc/krb5.conf'.

Viewing Your Tickets with klist
-------------------------------

The `klist' command shows your tickets.  When you first obtain tickets,
you will have only the ticket-granting ticket.  (see What is a Ticket?.)
The listing would look like this:

     shell% klist
     Ticket cache: /tmp/krb5cc_ttypa
     Default principal: jennifer@ATHENA.MIT.EDU

     Valid starting     Expires            Service principal
     06/07/96 19:49:21  06/08/96 05:49:19  krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
     shell%

The ticket cache is the location of your ticket file.  In the above
example, this file is named `/tmp/krb5cc_ttypa'.  The default principal
is your kerberos "principal".  (see What is a Kerberos Principal?.)

The "valid starting" and "expires" fields describe the period of time
during which the ticket is valid.  The "service principal" describes
each ticket.  The ticket-granting ticket has the primary `krbtgt', and
the instance is the realm name.

Now, if jennifer connected to the machine `daffodil.mit.edu', and then
typed `klist' again, she would have gotten the following result:

     shell% klist
     Ticket cache: /tmp/krb5cc_ttypa
     Default principal: jennifer@ATHENA.MIT.EDU

     Valid starting     Expires            Service principal
     06/07/96 19:49:21  06/08/96 05:49:19  krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
     06/07/96 20:22:30  06/08/96 05:49:19  host/daffodil.mit.edu@ATHENA.MIT.EDU
     shell%

Here's what happened:  when jennifer used telnet to connect to the host
`daffodil.mit.edu', the telnet program presented her ticket-granting
ticket to the KDC and requested a host ticket for the host
`daffodil.mit.edu'.  The KDC sent the host ticket, which telnet then
presented to the host `daffodil.mit.edu', and she was allowed to log in
without typing her password.

Suppose your Kerberos tickets allow you to log into a host in another
domain, such as `trillium.fubar.org', which is also in another Kerberos
realm, `FUBAR.ORG'.  If you telnet to this host, you will receive a
ticket-granting ticket for the realm `FUBAR.ORG', plus the new `host'
ticket for `trillium.fubar.org'.  `klist' will now show:

     shell% klist
     Ticket cache: /tmp/krb5cc_ttypa
     Default principal: jennifer@ATHENA.MIT.EDU

     Valid starting     Expires            Service principal
     06/07/96 19:49:21  06/08/96 05:49:19  krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
     06/07/96 20:22:30  06/08/96 05:49:19  host/daffodil.mit.edu@ATHENA.MIT.EDU
     06/07/96 20:24:18  06/08/96 05:49:19  krbtgt/FUBAR.ORG@ATHENA.MIT.EDU
     06/07/96 20:24:18  06/08/96 05:49:19  host/trillium.fubar.org@ATHENA.MIT.EDU
     shell%

You can use the `-f' option to view the "flags" that apply to your
tickets.  The flags are:

F
     Forwardable

f
     forwarded

P
     Proxiable

p
     proxy

D
     postDateable

d
     postdated

R
     Renewable

I
     Initial

i
     invalid

Here is a sample listing.  In this example, the user jennifer obtained
her initial tickets (`I'), which are forwardable (`F') and postdated
(`d') but not yet validated (`i').  (see kinit Reference for more
information about postdated tickets.)

     shell% klist -f
     Ticket cache: /tmp/krb5cc_320
     Default principal: jennifer@ATHENA.MIT.EDU

     Valid starting      Expires             Service principal
     31 Jul 96 19:06:25  31 Jul 96 19:16:25  krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
             Flags: FdiI
     shell%

In the following example, the user david's tickets were forwarded (`f')
to this host from another host.  The tickets are reforwardable (`F').

     shell% klist -f
     Ticket cache: /tmp/krb5cc_p11795
     Default principal: david@FUBAR.ORG

     Valid starting     Expires            Service principal
     07/31/96 11:52:29  07/31/96 21:11:23  krbtgt/FUBAR.ORG@FUBAR.ORG
             Flags: Ff
     07/31/96 12:03:48  07/31/96 21:11:23  host/trillium.fubar.org@FUBAR.ORG
             Flags: Ff
     shell%

Destroying Your Tickets with kdestroy
-------------------------------------

Your Kerberos tickets are proof that you are indeed yourself, and
tickets can be stolen.  If this happens, the person who has them can
masquerade as you until they expire.  For this reason, you should
destroy your Kerberos tickets when you are away from your computer.

Destroying your tickets is easy.  Simply type `kdestroy'.

     shell% kdestroy
     shell%

If `kdestroy' fails to destroy your tickets, it will beep and give an
error message.  For example, if `kdestroy' can't find any tickets to
destroy, it will give the following message:

     shell% kdestroy
     kdestroy: No credentials cache file found while destroying cache
     Ticket cache NOT destroyed!
     shell%

Password Management
===================

Your password is the only way Kerberos has of verifying your identity.
If someone finds out your password, that person can masquerade as
you--send email that comes from you, read, edit, or delete your files,
or log into other hosts as you--and no one will be able to tell the
difference.  For this reason, it is important that you choose a good
password (see Password Advice.), and keep it secret.  If you need to
give access to your account to someone else, you can do so through
Kerberos.  (see Granting Access to Your Account.)  You should never
tell your password to anyone, including your system administrator, for
any reason.  You should change your password frequently, particularly
any time you think someone may have found out what it is.

Changing Your Password
----------------------

To change your Kerberos password, use the `kpasswd' command.  It will
ask you for your old password (to prevent someone else from walking up
to your computer when you're not there and changing your password), and
then prompt you for the new one twice.  (The reason you have to type it
twice is to make sure you have typed it correctly.)  For example, user
`david' would do the following:

     shell% kpasswd
     Old password for david:    <- Type your old password.
     New Password for david:    <- Type your new password.
     Verifying, please re-enter New Password for david:  <- Type the new password again.
     Password changed.
     shell%

If david typed the incorrect old password, he would get the following
message:

     shell% kpasswd
     Old password for david:  <- Type the incorrect old password.
     Incorrect old password.
     shell%

If you make a mistake and don't type the new password the same way
twice, `kpasswd' will ask you to try again:

     shell% kpasswd
     Old password for david:  <- Type the old password.
     New Password for david:  <- Type the new password.
     Verifying, please re-enter New Password for david: <- Type a different new password.
     Mismatch - try again
     New Password for david:  <- Type the new password.
     Verifying, please re-enter New Password for david: <- Type the same new password.
     Password changed.
     shell%

Once you change your password, it takes some time for the change to
propagate through the system.  Depending on how your system is set up,
this might be anywhere from a few minutes to an hour or more.  If you
need to get new Kerberos tickets shortly after changing your password,
try the new password.  If the new password doesn't work, try again using
the old one.

Password Advice
---------------

Your password can include almost any character you can type (except
control keys and the "enter" key).  A good password is one you can
remember, but that no one else can easily guess.  Examples of bad
passwords are words that can be found in a dictionary, any common or
popular name, especially a famous person (or cartoon character), your
name or username in any form (e.g., forward, backward, repeated twice,
etc.), your spouse's, child's, or pet's name, your birth date, your
social security number, and any sample password that appears in this
(or any other) manual.

MIT recommends that your password be at least 6 characters long, and
contain UPPER- and lower-case letters, numbers, and/or punctuation
marks.  Some passwords that would be good if they weren't listed in
this manual include:

   * some initials, like "GykoR-66." for "Get your kicks on Route 66."

   * an easy-to-pronounce nonsense word, like "slaRooBey" or "krang-its"

   * a misspelled phrase, like "2HotPeetzas!" or "ItzAGurl!!!"

Note:  don't actually use any of the above passwords.  They're only
meant to show you how to make up a good password.  Passwords that
appear in a manual are the first ones intruders will try.

Kerberos V5 allows your system administrators to automatically reject
bad passwords, based on whatever criteria they choose.  For example, if
the user `jennifer' chose a bad password, Kerberos would give an error
message like the following:

     shell% kpasswd
     Old password for jennifer:  <- Type your old password here.
     New Password for jennifer:  <- Type an insecure new password.
     Verifying, please re-enter New Password for jennifer:  <- Type it again.

     ERROR: Insecure password not accepted.  Please choose another.

     kpasswd: Insecure password rejected while attempting to change password.
     Please choose another password.

     New Password for jennifer:  <- Type a good password here.
     Verifying, please re-enter New Password for david:  <- Type it again.
     Password changed.
     shell%

Your system administrators can choose the message that is displayed if
you choose a bad password, so the message you see may be different from
the above example.

Granting Access to Your Account
-------------------------------

If you need to give someone access to log into your account, you can do
so through Kerberos, without telling the person your password.  Simply
create a file called `.k5login' in your home directory.  This file
should contain the Kerberos principal (see What is a Kerberos Principal?)
of each person to whom you wish to give access.  Each
principal must be on a separate line.  Here is a sample `.k5login' file:

     jennifer@ATHENA.MIT.EDU
     david@FUBAR.ORG

This file would allow the users `jennifer' and `david' to use your user
ID, provided that they had Kerberos tickets in their respective realms.
If you will be logging into other hosts across a network, you will
want to include your own Kerberos principal in your `.k5login' file on
each of these hosts.

Using a `.k5login' file is much safer than giving out your password,
because:

   * You can take access away any time simply by removing the principal
     from your `.k5login' file.

   * Although the user has full access to your account on one
     particular host (or set of hosts if your `.k5login' file is shared,
     e.g., over NFS), that user does not inherit your network
     privileges.

   * Kerberos keeps a log of who obtains tickets, so a system
     administrator could find out, if necessary, who was capable of
     using your user ID at a particular time.

One common application is to have a `.k5login' file in `root''s home
directory, giving root access to that machine to the Kerberos
principals listed.  This allows system administrators to allow users to
become root locally, or to log in remotely as `root', without their
having to give out the root password, and without anyone having to type
the root password over the network.

Kerberos V5
pplications
========================

Kerberos V5 is a "single-sign-on" system.  This means that you only
have to type your password once, and the Kerberos V5 programs do the
authenticating (and optionally encrypting) for you.  The way this works
is that Kerberos has been built into each of a suite of network
programs.  For example, when you use a Kerberos V5 program to connect
to a remote host, the program, the KDC, and the remote host perform a
set of rapid negotiations.  When these negotiations are completed, your
program has proven your identity on your behalf to the remote host, and
the remote host has granted you access, all in the space of a few
seconds.

The Kerberos V5 applications are versions of existing UNIX network
programs with the Kerberos features added.

Overview of Additional Features
-------------------------------

The Kerberos V5 "network programs" are those programs that connect to
another host somewhere on the internet.  These programs include
`rlogin', `telnet', `ftp', `rsh', `rcp', and `ksu'.  These programs
have all of the original features of the corresponding non-Kerberos
`rlogin', `telnet', `ftp', `rsh', `rcp', and `su' programs, plus
additional features that transparently use your Kerberos tickets for
negotiating authentication and optional encryption with the remote host.
In most cases, all you'll notice is that you no longer have to type your
password, because Kerberos has already proven your identity.

The Kerberos V5 network programs allow you the options of forwarding
your tickets to the remote host (if you obtained forwardable tickets
with the `kinit' program; see Obtaining Tickets with kinit.), and
encrypting data transmitted between you and the remote host.

This section of the tutorial assumes you are familiar with the
non-Kerberos versions of these programs, and highlights the Kerberos
functions added in the Kerberos V5 package.

telnet
------

The Kerberos V5 `telnet' command works exactly like the standard UNIX
telnet program, with the following Kerberos options added:

`-f, --forward'
     forwards a copy of your tickets to the remote host.

`--noforward'
     turns off forwarding of tickets to the remote host.  (This option
     overrides any forwarding specified in your machine's configuration
     files.)

`-F, --forwardable'
     forwards a copy of your tickets to the remote host, and marks them
     re-forwardable from the remote host.

`--noforwardable'
     makes any forwarded tickets nonforwardable.  (This option
     overrides any forwardability specified in your machine's
     configuration files.)

`-k realm'
     requests tickets for the remote host in the specified realm,
     instead of determining the realm itself.

`-K'
     uses your tickets to authenticate to the remote host, but does not
     log you in.

`-a'
     attempt automatic login using your tickets.  `telnet' will assume
     the same username unless you explicitly specify another.

`-x, --encrypt'
     turns on encryption.

`--noencrypt'
     turns off encryption.

For example, if `david' wanted to use the standard UNIX telnet to
connect to the machine `daffodil.mit.edu', he would type:

     shell% telnet daffodil.mit.edu
     Trying 128.0.0.5 ...
     Connected to daffodil.mit.edu.
     Escape character is '^]'.

     NetBSD/i386 (daffodil) (ttyp3)

     login: david
     Password:    <- david types his password here
     Last login: Fri Jun 21 17:13:11 from trillium.fubar.org
     Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
             The Regents of the University of California.   All rights reserved.

     NetBSD 1.1: Tue May 21 00:31:42 EDT 1996

     Welcome to NetBSD!
     shell%

Note that the machine `daffodil.mit.edu' asked for `david''s password.
When he typed it, his password was sent over the network unencrypted.
If an intruder were watching network traffic at the time, that intruder
would know `david''s password.

If, on the other hand, `jennifer' wanted to use the Kerberos V5 telnet
to connect to the machine `trillium.fubar.org', she could forward a
copy of her tickets, request an encrypted session, and log on as herself
as follows:

     shell% telnet -a -f -x trillium.fubar.org
     Trying 128.0.0.5...
     Connected to trillium.fubar.org.
     Escape character is '^]'.
     [ Kerberos V5 accepts you as ``jennifer@fubar.org'' ]
     [ Kerberos V5 accepted forwarded credentials ]
     NetBSD 1.1: Tue May 21 00:31:42 EDT 1996

     Welcome to NetBSD!
     shell%

Note that `jennifer''s machine used Kerberos to authenticate her to
`trillium.fubar.org', and logged her in automatically as herself.  She
had an encrypted session, a copy of her tickets already waiting for
her, and she never typed her password.

If you forwarded your Kerberos tickets, `telnet' automatically destroys
them when it exits.  The full set of options to Kerberos V5 `telnet'
are discussed in the Reference section of this manual.  (see telnet Reference.)

rlogin
------

The Kerberos V5 `rlogin' command works exactly like the standard UNIX
rlogin program, with the following Kerberos options added:

`-f, --forward'
     forwards a copy of your tickets to the remote host.

`--noforward'
     turns off forwarding of tickets to the remote host.  (This option
     overrides any forwarding specified in your machine's configuration
     files.)

`-F, --forwardable'
     forwards a copy of your tickets to the remote host, and marks them
     re-forwardable from the remote host.

`--noforwardable'
     makes any forwarded tickets nonforwardable.  (This option
     overrides any forwardability specified in your machine's
     configuration files.)

`-k realm'
     requests tickets for the remote host in the specified realm,
     instead of determining the realm itself.

`-x, --encrypt'
     turns on encryption.

`--noencrypt'
     turns off encryption.

For example, if `david' wanted to use the standard UNIX rlogin to
connect to the machine `daffodil.mit.edu', he would type:

     shell% rlogin daffodil.mit.edu -l david
     Password:  <- david types his password here
     Last login: Fri Jun 21 10:36:32 from :0.0
     Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
             The Regents of the University of California.   All rights reserved.

     NetBSD 1.1: Tue May 21 00:31:42 EDT 1996

     Welcome to NetBSD!
     shell%

Note that the machine `daffodil.mit.edu' asked for `david''s password.
When he typed it, his password was sent over the network unencrypted.
If an intruder were watching network traffic at the time, that intruder
would know `david''s password.

If, on the other hand, `jennifer' wanted to use Kerberos V5 rlogin to
connect to the machine `trillium.fubar.org', she could forward a copy
of her tickets, mark them as not forwardable from the remote host, and
request an encrypted session as follows:

     shell% rlogin trillium.fubar.org -f -x
     This rlogin session is using DES encryption for all data transmissions.
     Last login: Thu Jun 20 16:20:50 from daffodil
     SunOS Release 4.1.4 (GENERIC) #2: Tue Nov 14 18:09:31 EST 1995
     Not checking quotas. Try quota.real if you need them.
     shell%

Note that `jennifer''s machine used Kerberos to authenticate her to
`trillium.fubar.org', and logged her in automatically as herself.  She
had an encrypted session, a copy of her tickets were waiting for her,
and she never typed her password.

If you forwarded your Kerberos tickets, `rlogin' automatically destroys
them when it exits.  The full set of options to Kerberos V5 `rlogin'
are discussed in the Reference section of this manual.  (see rlogin Reference.)

FTP
---

The Kerberos V5 `FTP' program works exactly like the standard UNIX FTP
program, with the following Kerberos features added:

`-k realm'
     requests tickets for the remote host in the specified realm,
     instead of determining the realm itself.

`-forward'
     requests that your tickets be forwarded to the remote host.  The
     `-forward' argument must be the last argument on the command line.

`protect level'
     (issued at the `ftp>' prompt) sets the protection level.  "Clear"
     is no protection; "safe" ensures data integrity by verifying the
     checksum, and "private" encrypts the data.  Encryption also ensures
     data integrity.

For example, suppose `jennifer' wants to get her `RMAIL' file from the
directory `~jennifer/Mail', on the host `daffodil.mit.edu'.  She wants
to encrypt the file transfer.  The exchange would look like the
following:

     shell% ftp daffodil.mit.edu
     Connected to daffodil.mit.edu.
     220 daffodil.mit.edu FTP server (Version 5.60) ready.
     334 Using authentication type GSSAPI; ADAT must follow
     GSSAPI accepted as authentication type
     GSSAPI authentication succeeded
     Name (daffodil.mit.edu:jennifer):
     232 GSSAPI user jennifer@ATHENA.MIT.EDU is authorized as jennifer
     230 User jennifer logged in.
     Remote system type is UNIX.
     Using binary mode to transfer files.
     ftp> protect private
     200 Protection level set to Private.
     ftp> cd ~jennifer/MAIL
     250 CWD command successful.
     ftp> get RMAIL
     227 Entering Passive Mode (128,0,0,5,16,49)
     150 Opening BINARY mode data connection for RMAIL (361662 bytes).
     226 Transfer complete.
     361662 bytes received in 2.5 seconds (1.4e+02 Kbytes/s)
     ftp> quit
     shell%

The full set of options to Kerberos V5 `FTP' are discussed in the
Reference section of this manual.  (see FTP Reference.)

rsh
---

The Kerberos V5 `rsh' program works exactly like the standard UNIX
rlogin program, with the following Kerberos features added:

`-f, --forward'
     forwards a copy of your tickets to the remote host.

`--noforward'
     turns off forwarding of tickets to the remote host.  (This option
     overrides any forwarding specified in your machine's configuration
     files.)

`-F, --forwardable'
     forwards a copy of your tickets to the remote host, and marks them
     re-forwardable from the remote host.

`--noforwardable'
     makes any forwarded tickets nonforwardable.  (This option
     overrides any forwardability specified in your machine's
     configuration files.)

`-k realm'
     requests tickets for the remote host in the specified realm,
     instead of determining the realm itself.

`-x, --encrypt'
     turns on encryption.

`--noencrypt'
     turns off encryption.

For example, if your Kerberos tickets allowed you to run programs on the
host `trillium@fubar.org' as root, you could run the `date' program as
follows:

     shell% rsh trillium.fubar.org -l root -x date
     This rsh session is using DES encryption for all data transmissions.
     Fri Jun 21 17:06:12 EDT 1996
     shell%

If you forwarded your Kerberos tickets, `rsh' automatically destroys
them when it exits.  The full set of options to Kerberos V5 `rsh' are
discussed in the Reference section of this manual.  (see rsh Reference.)

rcp
---

The Kerberos V5 `rcp' program works exactly like the standard UNIX rcp
program, with the following Kerberos features added:

`-k realm'
     requests tickets for the remote host in the specified realm,
     instead of determining the realm itself.

`-x, --encrypt'
     turns on encryption.

For example, if you wanted to copy the file `/etc/motd' from the host
`daffodil.mit.edu' into the current directory, via an encrypted
connection, you would simply type:

     shell% rcp -x daffodil.mit.edu:/etc/motd .

The `rcp' program negotiates authentication and encryption
transparently.  The full set of options to Kerberos V5 `rcp' are
discussed in the Reference section of this manual.  (see rcp Reference.)

ksu
---

The Kerberos V5 `ksu' program replaces the standard UNIX su program.
`ksu' first authenticates you to Kerberos.  Depending on the
configuration of your system, `ksu' may ask for your Kerberos password
if authentication fails.  *Note that you should never type your
password if you are remotely logged in using an unencrypted connection.*

Once `ksu' has authenticated you, if your Kerberos principal appears in
the target's `.k5login' file (see Granting Access to Your Account.)
or in the target's `.k5users' file (see below), it switches your user
ID to the target user ID.

For example, `david' has put `jennifer''s Kerberos principal in his
`.k5login' file.  If `jennifer' uses `ksu' to become `david', the
exchange would look like this.  (To differentiate between the two
shells, `jennifer''s prompt is represented as `jennifer%' and
`david''s prompt is represented as `david%'.)

     jennifer% ksu david
     Account david: authorization for jennifer@ATHENA.MIT.EDU successful
     Changing uid to david (3382)
     david%

Note that the new shell has a copy of `jennifer''s tickets.  The ticket
filename contains `david''s UID with `.1' appended to it:

     david% klist
     Ticket cache: /tmp/krb5cc_3382.1
     Default principal: jennifer@ATHENA.MIT.EDU

     Valid starting      Expires             Service principal
     31 Jul 96 21:53:01  01 Aug 96 07:52:53  krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
     31 Jul 96 21:53:39  01 Aug 96 07:52:53  host/daffodil.mit.edu@ATHENA.MIT.EDU
     david%

If `jennifer' had not appeared in `david''s `.k5login' file (and the
system was configured to ask for a password), the exchange would have
looked like this (assuming `david' has taken appropriate precautions in
protecting his password):

     jennifer% ksu david
     WARNING: Your password may be exposed if you enter it here and are logged
              in remotely using an unsecure (non-encrypted) channel.
     Kerberos password for david@ATHENA.MIT.EDU:  <-  `jennifer' types the wrong password here.
     ksu: Password incorrect
     Authentication failed.
     jennifer%

Now, suppose `david' did not want to give `jennifer' full access to his
account, but wanted to give her permission to list his files and use
the "more" command to view them.  He could create a `.k5users' file
giving her permission to run only those specific commands.

The `.k5users' file is like the `.k5login' file, except that each
principal is optionally followed by a list of commands.  `ksu' will let
those principals execute only the commands listed, using the `-e'
option.  `david''s `.k5users' file might look like the following:

     jennifer@ATHENA.MIT.EDU       /bin/ls /usr/bin/more
     joeadmin@ATHENA.MIT.EDU         /bin/ls
     joeadmin/admin@ATHENA.MIT.EDU   *
     david@FUBAR.ORG

The above `.k5users' file would let `jennifer' run only the commands
`/bin/ls' and `/usr/bin/more'.  It would let `joeadmin' run only the
command `/bin/ls' if he had regular tickets, but if he had tickets for
his `admin' instance, `joeadmin/admin@ATHENA.MIT.EDU', he would be able
to execute any command.  The last line gives `david' in the realm
FUBAR.ORG permission to execute any command.  (I.e., having only a
Kerberos principal on a line is equivalent to giving that principal
permission to execute `*'.)  This is so that david can allow himself to
execute commands when he logs in, using Kerberos, from a machine in the
realm FUBAR.ORG.

Then, when `jennifer' wanted to list his home directory, she would type:

     jennifer% ksu david -e ls ~david
     Authenticated jennifer@ATHENA.MIT.EDU
     Account david: authorization for jennifer@ATHENA.MIT.EDU for execution of
                    /bin/ls successful
     Changing uid to david (3382)
     Mail            News            Personal        misc            bin
     jennifer%

If `jennifer' had tried to give a different command to `ksu', it would
have prompted for a password as with the previous example.

Note that unless the `.k5users' file gives the target permission to run
any command, the user must use `ksu' with the `-e' command option.

The `ksu' options you are most likely to use are:

`-n principal'
     specifies which Kerberos principal you want to use for `ksu'.
     (e.g., the user `joeadmin' might want to use his `admin' instance.
     See What is a Ticket?.)

`-c'
     specifies the location of your Kerberos credentials cache (ticket
     file).

`-C'
     specifies the location you want the Kerberos credentials cache
     (ticket file) to be for the target user ID.

`-k'
     tells `ksu' not to destroy your Kerberos tickets when `ksu' is
     finished.

`-f'
     requests forwardable tickets.  (see Obtaining Tickets with kinit.)
     This is only applicable if `ksu' needs to obtain
     tickets.

`-l lifetime'
     sets the ticket lifetime.  (see Obtaining Tickets with kinit.)
     This is only applicable if `ksu' needs to obtain tickets.

`-z'
     tells `ksu' to copy your Kerberos tickets only if the UID you are
     switching is the same as the Kerberos primary (either yours or the
     one specified by the `-n' option).

`-Z'
     tells `ksu' not to copy any Kerberos tickets to the new UID.

`-e command'
     tells `ksu' to execute command and then exit.  See the description
     of the `.k5users' file above.

`-a text'
     (at the end of the command line) tells `ksu' to pass everything
     after `-a' to the target shell.

The full set of options to Kerberos V5 `ksu' are discussed in the
Reference section of this manual.  (see ksu Reference.)

Kerberos V5
eference
*********************

This section will include copies of the manual pages for the Kerberos
V5 client programs.  You can read the manual entry for any command by
typing `man' command, where command is the name of the command for
which you want to read the manual entry.  For example, to read the
`kinit' manual entry, you would type:

     shell% man kinit

Note:  To be able to view the Kerberos V5 manual pages on line, you may
need to add the directory `/usr/krb5/man' to your MANPATH environment
variable.  (Remember to replace `/usr/krb5' with the top-level
directory in which Kerberos V5 is installed.)  For example, if you had
the the following line in your `.login' file(1):

     setenv MANPATH /usr/local/man:/usr/man

and the Kerberos V5 man pages were in the directory `/usr/krb5/man',
you would change the line to the following:

     setenv MANPATH /usr/krb5/man:/usr/local/man:/usr/man

Note to info users:  the manual pages are not available within this info
tree.  You can read them from emacs with the command:

     M-x manual-entry *command*

---------- Footnotes ----------

(1)  The MANPATH variable may be specified in a different
initialization file, depending on your operating system.  Some of the
files in which you might specify environment variables include
`.login', `.profile', or `.cshrc'.

kinit Reference
===============

Type `M-x manual-entry kinit' to read this manual page.

klist Reference
===============

Type `M-x manual-entry klist' to read this manual page.

kdestroy Reference
==================

Type `M-x manual-entry kdestroy' to read this manual page.

kpasswd Reference
=================

Type `M-x manual-entry kpasswd' to read this manual page.

telnet Reference
================

Type `M-x manual-entry telnet' to read this manual page.

rlogin Reference
================

Type `M-x manual-entry rlogin' to read this manual page.

FTP Reference
=============

Type `M-x manual-entry FTP' to read this manual page.

rsh Reference
=============

Type `M-x manual-entry rsh' to read this manual page.

rcp Reference
=============

Type `M-x manual-entry rcp' to read this manual page.

ksu Reference
=============

Type `M-x manual-entry ksu' to read this manual page.

Kerberos Glossary
*****************

client
     an entity that can obtain a ticket.  This entity is usually either
     a user or a host.

host
     a computer that can be accessed over a network.

Kerberos
     in Greek mythology, the three-headed dog that guards the entrance
     to the underworld.  In the computing world, Kerberos is a network
     security package that was developed at MIT.

KDC
     Key Distribution Center.  A machine that issues Kerberos tickets.

keytab
     a key table file containing one or more keys.  A host or service
     uses a "keytab" file in much the same way as a user uses his/her
     password.

principal
     a string that names a specific entity to which a set of
     credentials may be assigned.  It generally has three parts:

    primary
          the first part of a Kerberos principal.  In the case of a
          user, it is the username.  In the case of a service, it is
          the name of the service.

    instance
          the second part of a Kerberos principal.  It gives
          information that qualifies the primary.  The instance may be
          null.  In the case of a user, the instance is often used to
          describe the intended use of the corresponding credentials.
          In the case of a host, the instance is the fully qualified
          hostname.

    realm
          the logical network served by a single Kerberos database and
          a set of Key Distribution Centers.  By convention, realm
          names are generally all uppercase letters, to differentiate
          the realm from the internet domain.

     The typical format of a typical Kerberos principal is
     primary/instance@REALM.

service
     any program or computer you access over a network.  Examples of
     services include "host" (a host, e.g., when you use `telnet' and
     `rsh'), "ftp" (FTP), "krbtgt" (authentication; cf. ticket-granting
     ticket), and "pop" (email).

ticket
     a temporary set of electronic credentials that verify the identity
     of a client for a particular service.

TGT
     Ticket-Granting Ticket.  A special Kerberos ticket that permits the
     client to obtain additional Kerberos tickets within the same
     Kerberos realm.