Quick Start for Kerberos Users

The minimum you need to know

If you already have a Kerberos principal, and are using a UNIX computer that already has Kerberos software installed, then you will use (at least) these commands.

In your .login or .cshrc file:: setenv PATH /usr/krb5/bin:$PATH; or export PATH=/usr/krb5/bin:$PATH in your .profile, .bashrc, or .bash_profile, if you use bash or ksh rather than tcsh or csh.
Once per day, on your desktop (or laptop) machine:: log in at the console. If this does not get you a Kerberos ticket (test with klist), then use...; kinit
To start a new session on a machine (e.g., fcdfsgi2), use one of:: telnet fcdfsgi2; rlogin fcdfsgi2; slogin fcdfsgi2; rsh fcdfsgi2 <command>; ssh fcdfsgi2 <command>; ftp fcdfsgi2
Once within the first 30 days, and at least once per year:: kpasswd to change your Kerberos password
To check whether you have a valid ticket:: klist

Never type your Kerberos password except on your desktop machine. Normally you will only need to do this once per day when you log in (or kinit if your desktop is not set up to get a ticket when you log in); perhaps to unlock your screen; and periodically when you change your Kerberos password with kpasswd. If you do need an encrypted connection for some reason, use ssh or the -x option--for example, telnet -x fcdfsgi2. If any command other than kinit or kpasswd prompts for a password, then something is wrong.

If you don't yet have a Kerberos principal, or you need software installed, or you need other information, keep reading.

Introduction

Note: for more detailed information on the Strong Authentication project at Fermilab, and on using and installing the Kerberos software, see the Strong Authentication at Fermilab Manual.

Preparing to use Kerberos services will take a few days. Not a lot of work on your part is required, but it may take a couple of days to get everything you need. There are four basic steps to this process:

Apply for a Kerberos Principal, essentially a user ID for Kerberos authentication.
Confirm that your workstation has the Kerberized client applications installed.
Modify your work environment to use these Kerberized applications rather than the standard non-Kerberized versions.
Login to the Fermi realm, receive a Kerberos ticket and go to work.

These instructions are designed to assist in the installation and use of the Kerberos client software. The use of Kerberos will allow CDF users to connect directly to fcdfsgi2 and other nodes in a secure manner without interfering with users' current working methods. Installation and use of Kerberos will in no way interfere with your connections to other nodes. However, we recommend that you always use secure protocols such as Kerberos or SSH when you make any connection.

Applying for a Kerberos principal

New CDF users will be given a Kerberos principal automatically when they apply for an account on any of the CDF central Run II analysis nodes fcdfsgi2, fcdfsun1, or fcdflnx1. New users should use the CDF account request form at http://www-cdf.fnal.gov/computing/unixaccountrequest.html to apply. (If you have an account on fcdfsgi2, you should already have a principal. If you have forgotten your Kerberos password, send mail to compdiv@fnal.gov to have it reset.)

Users who require only a Kerberos principal should use the form at http://www.fnal.gov/cd/forms/acctreq_form.html to request a principal.

In either case, you will be notified via email when the principal is ready. This email will include instructions on how to verify your identity and receive your new password.

Confirming that your workstation is ready

While waiting for your principal to arrive, you should verify that your workstation has been Kerberized. To do this, check for the existence of the directory /usr/krb5/bin, which should contain the following files.

ncdf58:~# ls -l /usr/krb5/bin
total 1696
-rwxr-xr-x    1 root     root       187224 May 24 10:28 aklog
-rwxr-xr-x    1 root     root        76992 May 24 10:28 ftp
-rwxr-xr-x    1 root     root        12968 May 24 10:28 gss-client
-rwxr-xr-x    1 root     root        10532 May 24 10:28 kcron
-rwsr-xr-x    1 root     root        10148 May 24 10:28 kcron-create
lrwxrwxrwx    1 root     root           12 Oct  3 16:12 kcron-destroy -> kcron-create
-rwxr-xr-x    1 root     root         4992 May 24 10:27 kdestroy
-rwxr-xr-x    1 root     root        11748 May 24 10:27 kinit
-rwxr-xr-x    1 root     root        11764 May 24 10:27 klist
-rwxr-xr-x    1 root     root        31980 May 24 10:27 kpasswd
-rwxr-xr-x    1 root     root        61968 May 24 10:27 krb524init
-rwsr-xr-x    1 root     root        45660 May 24 10:27 ksu
-rwxr-xr-x    1 root     root        33720 May 24 10:28 rcp
-rwxr-xr-x    1 root     root        29464 May 24 10:28 rlogin
-rwxr-xr-x    1 root     root        27992 May 24 10:28 rsh
-rwxr-xr-x    1 root     root         7404 May 24 10:27 sclient
-rwxr-xr-x    1 root     root         9416 May 24 10:28 sim_client
-rwxr-xr-x    1 root     root       912336 Oct  6 16:27 sshk4
-rwxr-xr-x    1 root     root       124388 May 24 10:28 telnet
-rwxr-xr-x    1 root     root         9076 May 24 10:28 uuclient
-rwsr-xr-x    1 root     root        15220 May 24 10:28 v4rcp
-rwxr-xr-x    1 root     root        40136 May 24 10:27 v5passwd
ncdf58:~#

Software Installation

If you don't have a /usr/krb5 area, then you need to install the Kerberos software. The installation process is well described by this guide.

The CDF Task Force has installed Kerberos software on workstations that they manage in the CDF trailers. If you encounter any problems, send mail to cdfsys@fnal.gov requesting installation.

If your node (either at Fermilab or at a remote institution) is not managed by the CDF Task Force but runs Linux, then the simplest way to install Kerberos software is probably to use RPMs, as described by "Kerberos Installation Steps (RPM)" in Chapter 15 of the Fermilab Strong Authentication Manual.

If your node has the Fermilab distribution tools UPS and UPD installed, the following steps give a summary for installing Kerberos.

As user products,
1. source ~cdfsoft/cdf2.shrc
  or, if you do not have the CDF Run II software installed,
  source ~products/setups/setups.csh
2. If your node is not in the fnal.gov domain and you have not registered to obtain UPS products, fill out the form at http://www.fnal.gov/cd/forms/upd_registration.html and wait until you receive a confirmation message.
3. setup upd
4. upd install kerberos -G "-c"
  to retrieve the software from the central UPS/UPD server.
As user root,
1. ups install-keep-ssh kerberos
  to install the software in a system area. Answer "no" when asked whether you have the passwords to enable ftp and host services, and ignore error messages of the type:
  could not add principal [host/node.domain] to keytab file.

Options for other operating systems, e.g., MacOS or Windows, are described in Fermilab's Strong Authentication Manual. Also, CDF member Charles Plager has compiled some notes on using Kerberos from a Windows machine, which may be found here.

There are other options as well:

You can use a temporary UPS/UPD installation, following this procedure.
Or, you can retrieve Kerberos source code and binaries (for some platforms) from http://web.mit.edu/kerberos/www/.

CRYPTOCards Another solution applies primarily to those nodes that cannot easily run Kerberos software (VMS, X-Terminals; Windows or Macintosh if you don't want to install the Kerberos software for them), although it could be useful for any user. A device called a CRYPTOCard can allow you to securely use Kerberos. These are available as credit card sized devices or as software for the Palm Pilot. In either form, it provides a sequence of responses to login challenges. One challenge is issued per login session, and the CRYPTOCard provides the appropriate response that the user then enters as a password. Each response is effectively a one-time password.

To request a CRYPTOCard, please submit this form, checking the appropriate box near the bottom.

Again, this solution does not require that special software be installed on the user's workstation.

Note: Your Kerberos password will expire if you do not change it within 30 days after your principal is created, and at least once per year after that. (This is not the same as tickets expiring, which happens after 26 hours.) If you never use anything but your CRYPTOCard, you will need to borrow someone else's computer that has Kerberos software installed. You don't need to be logged in as yourself; just issue the command "kpasswd <username>" and you will be prompted for your old and new passwords as usual.

Modifying your work environment

If you have a UPS/UPD installation, you may want to accomplish this task by running setup kerberos each time you begin work instead of using the steps shown below. This method also prepends a Kerberized application directory name to your PATH environment variable. Although the directory entries are different from those shown below, the executables in each directory are identical.

Offsite users should consult their local system administrators before performing the steps shown below since the exact location of the Kerberos software may vary from site to site. As you may have noticed from the directory listing above, many of the Kerberos applications you will use have similar or identical names to some of the programs you currently use. This is no accident. Kerberos tries to provide the basic functionality of certain insecure programs while using a stronger form of authentication. In order to insure that you use the Kerberized versions rather than the standard ones, you can modify your PATH environment variable. Caution: Do not change your PATH until after you receive your Kerberos principal. For users of tcsh, adding

setenv PATH /usr/krb5/bin:$PATH

to your .cshrc file should accomplish this; for bash users, adding

export PATH=/usr/krb5/bin:$PATH

to either your .bashrc or .bash_profile (depending on where you have configured your path) should work. Following your next login, try running

ncdf58:~$ echo $PATH
/usr/krb5/bin:/usr/products/ups/v4_5_1/Linux+2.2/bin:/usr/bin:/bin:/usr/X11R6/bin:/usr/local/bin:/opt/bin
ncdf58:~$

Note that the Kerberos directory is now listed first. If you have difficulty with this task, send email to cdfsys@fnal.gov giving the node name and your username, and someone will assist you.

Getting a ticket

Note: You should never need to type your Kerberos password except when executing the kinit or kpasswd command(*), and you should use these commands only on the machine in front of you--not on a remote node. If you are prompted for a password when logging in, something is wrong; don't try entering your Kerberos password! Also, please see these user precautions.

Login to your workstation. On most CDF trailer machines and some others, you use your Kerberos password to log in at the console, and this gets you a Kerberos ticket (check with the klist command). If your desktop or laptop is not set up this way, or if your existing ticket has expired, then use the kinit command to get a ticket. Some of its options are:

kinit [-l ] [-r ] [-R]
where
   -l lifetime               requests a ticket with the specified lifetime.  This is capped
                             at 26 hours in the Fermi realm.  Syntax for expiration lifetime is
                                #s (seconds)
                                #m (minutes)
                                #h (hours)
                                #d (days)
                             You cannot mix units.
   -r renewable_life         Requests a ticket that is renewable.  Syntax is the same as above.
   -R                        Requests that an unexpired, renewable ticket be renewed.

Most users will probably use this command with no options, as shown below. Note that the password requested is the Kerberos password, not the Unix password. Also, the password is not echoed to the screen in any way.

ncdf58:~$ kinit
Password for rjetton@FNAL.GOV: 
ncdf58:~$

(*) The relatively specialized kcroninit command also requires a Kerberos password. See section 7.3 of the Strong Authentication at Fermilab manual for more details on the Kerberos cron procedures.

Changing your Kerberos password

After receiving your first Kerberos ticket, you should change your Kerberos password. You must also change your Kerberos password at least once a year, or it will expire. Pick a suitable password that satisifies these rules:

It must be at least 10 characters long, and
It must contain characters from at least 2 of these 5 groups:
- lowercase
- uppercase
- numbers
- punctuation
- all other characters

To change your Kerberos password, simply run kpasswd, enter your old Kerberos password when prompted, then enter your new Kerberos password as prompted. You can change your password at any time, even if it has expired.

Listing your Kerberos ticket status

To see the current status of your Kerberos tickets, you should run klist.

ncdf58:~$ klist -f
Ticket cache: /tmp/krb5cc_4292
Default principal: rjetton@FNAL.GOV

Valid starting     Expires            Service principal
04/04/00 16:01:03  04/05/00 05:01:03  krbtgt/FNAL.GOV@FNAL.GOV
	Flags: FIA

The flags field abbreviations are defined in the detailed documentation (see the references at the end of this document).

Destroying Kerberos tickets

Although Kerberos tickets expire in just a few hours (at Fermilab the default is 26 hours), you may occassionally feel the need to remove them earlier. To do this, run kdestroy.

Connecting to remote Kerberized nodes

Kerberos provides client versions of telnet, ftp, rcp, rlogin, and rsh. They work in a similar manner to the standard versions, except with regard to the authentication mechanism that is used. For example,

ncdf58:~$ rlogin fcdfsgi2

User precautions
No security scheme is perfect, so users' awareness and cooperation are critical to the success of this policy. Avoid insecure connections. That is, don't enter your Kerberos password unless the entire network link from your node to the remote server is using Kerberos authentication. Using standard rlogin to pass from your workstation to another and then running kinit leaves your Kerberos password in clear text format while traveling between the first two nodes.

If you use kerberized rlogin or telnet to connect to an un-kerberized server, you will be prompted for a password. Do not enter your Kerberos password at such a prompt. The only Kerberos applications that require your Kerberos password are kinit and kpasswd.*

Never use your Kerberos password as a password on any other system. Since it is relatively easy to capture passwords used for nonstrengthned systems in plain text, you compromise your Kerberos password by using it in this way. Passwords captured in DES encrypted form (used by nearly every Unix password/shadow suite) are subject to compromise by programs such as crack. This program usually breaks from 25 to 50% of typical users' DES encrypted passwords.

What to do if rcp does not copy a file, but gives no error message
A problem occurs when the file $HOME/.cshrc, $HOME/.bashrc, or etc., on the remote computer produces terminal output. If this occurs, prefacing such commands with

    if ($?prompt != 0)

will usually help.

* The relatively specialized kcron-create command also requires a Kerberos password. See section 7.3 of the Strong Authentication at Fermilab manual for more details on the Kerberos cron procedures.

More information

Additional documentation can be found at the following locations.

The Fermilab Computer Security Team maintains the Strong Authentication at Fermilab page, with a well-written manual and other useful links.
Despite its name, the Moron's Guide to Kerberos really is a well written document.
The MIT Kerberos V5 UNIX User's Guide is some of the documentation from the authors of Kerberos.