$Id: README,v 1.9 1997/10/23 04:23:18 kenh Exp kenh $ Kerberos Kit README kenh@cmf.nrl.navy.mil INTRODUCTION ------------ This is the README file for the CCS Kerberos kit. This file explains how to use this Kerberos kit to access CCS computers securely from remote locations. WHERE TO GET IT --------------- You can retrieve CCS Kerberos kits from the following ftp site: ftp://ftp.cmf.nrl.navy.mil/pub/kerberos5 These kits are compressed Unix tar archives (for Unix systems), Stuffit self-extracting archives for Macintosh computers, and PkZip archives for MSDOS/Wintel machines. Each archive will name the system it is build for in the name of the archive (ie - "krb5-sunos4.tar.Z", "krb5-irix5.tar.Z", "krb5-mac-ppc.sit"). Download the appropriate kit for your architecture. NOTE: In the case of Macintosh Eudora kit, the filename will be "krb-mac-eudora.sit.hqx". In the case of the Windows Eudora kit, the filename will be "krb-win-eudora.exe". HOW TO USE IT ------------- First, you must already have a Kerberos 5 account here at CCS. If you already have a regular user account on our systems, then you have a Kerberos 5 account. Next, unpack the archive using the appropriate dearchiver for your system (Uncompress/tar for Unix systems, StuffIt for Macintoshes, PkUnZip for Wintel systems). You've probably already done this, since you're reading this file :-) Then follow the architecure-specific directions below. If you have questions or problems, please contact the CCS help group at ccshelp@cmf.nrl.navy.mil or (202) 404-7337. ***************************************************************************** *** *** *** NOTE TO HPC USERS *** *** *** *** If you are an HPC user, you must contact the center that is your *** *** home realm for support with this kit. NRL does not provide support *** *** for Kerberos to HPC MSRC users. *** *** *** ***************************************************************************** Note: no matter which architecture you're using, it would be a good idea to read the "TIPS FOR GOOD SECURITY" section below. DIRECTIONS FOR UNIX PLATFORMS ----------------------------- After you've unpacked the tar file, you will find that you have the following files in a subdirectory called "ccs-krb5": README krb5.conf kdestroy kftp kinit klist kpasswd krcp krlogin krsh ktelnet On some systems, you may also find an "aklog" program included. If you have root on the system, install the krb5.conf file in /etc. If you don't have root or prefer not to modify the system you're using, place the krb5.conf file wherever you want, but set the environment variable KRB5_CONFIG to point to this location. Ie - if you place the krb5.conf file in "/usr/people/somebody/krb5.conf", you should do: Bourne, Korn, and Bash shells % KRB5_CONFIG=/usr/people/somebody/krb5.conf; export KRB5_CONFIG Csh, Tcsh, and similar "C-shell" lookalikes % setenv KRB5_CONFIG /usr/people/somebody/krb5.conf Next, you need to place all of the above binaries somewhere in your path. The location doesn't really matter, as long as you can run them. Once this is done, you need to perform the following steps to login to our systems: 1) First, get some Kerberos credentials. Run "kinit". If your username on the system you're using doesn't match the username here at CMF, you'll need to provide the user name on the command line. For example: % kinit somebody Would be used to get credentials for the user "somebody". If this is successful, kinit should return with no errors. To verify that you have Kerberos credentials, you should run "klist". It should return something similar to this: % klist Ticket cache: /tmp/krb5cc_32767 Default principal: somebody@CMF.NRL.NAVY.MIL Valid starting Expires Service principal 09/26/96 10:40:35 09/27/96 11:40:33 krbtgt/CMF.NRL.NAVY.MIL@CMF.NRL.NAVY.MIL Please note that some systems include a form of Kerberos already distributed with the system (Solaris is one example). In the majority of these cases, these Kerberos binaries will not work with our system, so you must insure that you're running the correct versions of "kinit", "klist", and "kdestroy". If you want to do cross realming from one site to another issue a command like this: %klist somename@SOMEHOST.EXAMPLE.DOMAIN.ORG Running klist will show you that you have the required new credientials. Notice that the example SOMEHOST.EXAMPLE.DOMAIN.ORG is in all CAPS. DNS is not case sensitive, but KERBEROS is. 2) Next, telnet/rlogin to the appropriate system at CMF. Either krlogin or ktelnet should work fine. All of the systems at CMF are setup to accept incoming Kerberos connections. Example: % ktelnet abogus.host.hpc.navy.mil And for krlogin: % krlogin abogus.host.hpc.navy.mil And once you do that, you should be logged in, and already have an AFS token. 3) You can also use "kftp" to ftp into our systems, "kpasswd" to change your password, and "aklog" to obtain AFS tokens (if your system supports AFS). DIRECTIONS FOR WIN32 (WINDOWS 95 AND WINDOWS NT) PLATFORMS ---------------------------------------------------------- After you have extracted the archive, you will see the following files: o README - This file o COMERR32.DLL \ o KRB5_32.DLL \ o GSSAPI32.DLL -- Dynamically loadable modules used by Kerberos o KRB4_32.DLL / o KRBSAP32.DLL / o TELNET.EXE - The Kerberos telnet application o FTP.EXE - The Kerberos ftp application o KRB5.EXE - The Kerberos ticket manager o AKLOG.EXE - AFS authentication program (only used if you run AFS) o KRB5.INI - The Kerberos configuration file Move KRB5.INI to wherever .INI are stored on your system. On Windows 95, this is typically C:\WINDOWS. Under Windows NT, this is typically C:\WINNT. You can install the Kerberos DLL's in the default system location, or leave them in the same location as the other executables. Once you have all of the files installed, run the Kerberos ticket manager (KRB5.EXE). Go under the "File" menu, select "Options", and check the "Forwardable" checkbox. This makes sure your tickets are forwardable, which is required to use our systems properly. Once this is done, enter your username in the "Name" box, enter your password in the "Password" box, and press the "Login" button. If everything is working correctly, then you should see your ticket listed in the box in the middle of the Kerberos ticket manager. Once you get an initial ticket, start up the "Telnet" program that comes with the kit. At the "Open New Telnet Connection" dialog box, make sure the "Forward credentials", "Forward remote credentials", and the "Enable encryption" boxes are checked. Enter in the name of the host you wish to connect to and your username on the remote system. Once you do that, click on the "OK" button, and you should login successfully to our systems, and automatically have the correct AFS tokens. You can also use the ftp program to transfer files to and from your PC. This ftp program is command-line based and functions similar to the included ftp program that comes with Windows 95 and NT. You can use the "Change Password" button on the Kerberos Ticket manager (KRB5.EXE) to change your password. Common Problems with the WIN32 Kerberos kit: - You get the message "MSVCRT.DLL not available" when you try to run any of the Kerberos programs. Kerberos requires the MicroSoft Visual C runtime library. If you don't have this installed already (you will get a message saying "MSVCRT.DLL not installed" when trying to run the Kerberos executables), you can download this from: ftp://ftp.cmf.nrl.navy.mil/pub/kerberos5/msvcrt.exe DIRECTIONS FOR INSTALLING THE EUDORA KERBEROS POP PLUGIN FOR MAC/OS ------------------------------------------------------------------- After you have extracted the archive, you should have a folder called "CMF Kerberos Kit". This will contain four files: o README - This file o KClient - The Kerberos Client driver module o Kerberos Client Preferences - Preferences file for "KClient" o Kerberos Settings - Plugin for Eudora First, install "Kerberos Client Preferences" in the "Preferences" folder of your System Folder. Next, install the KClient module in the Control Panel folder of your system folder. If you use a program to manage control panels/ extensions, please be sure to enable KClient. Reboot your Macintosh. Upon boot, you should see the KClient icon (a box with a key in it) among your startup icons. Go into "Control Panels" and open KClient. You should already see "CMF.NRL.NAVY.MIL" as the default local realm. If you do not, then perform the next step to set your realm information. If you don't see CMF.NRL.NAVY.MIL as your default realm, click the "Add" button in the Realms box. For the realm name, enter "CMF.NRL.NAVY.MIL" without the quotes (note: case is important). For the associated Internet domain name, enter ".cmf.nrl.navy.mil", again without quotes, and be sure to include the leading dot. Once you've entered the realm name, select "CMF.NRL.NAVY.MIL", and press the "Add" button in the Servers box. For the hostname, enter "guardian.cmf.nrl.navy.mil", leave the port at 750, and do _not_ select "Server supports updating". Under the "Options" button in KClient, be sure that 'Sync time with Kerberos Server' and 'Save Login Name' are both checked. To test out KClient, press the "Login" button. Enter your username in the "Network ID" field, and your Kerberos password in the "Password" field. The dialog box should disappear without any errors. If you encounter an error, please notify Ken Hornstein , x4-4765. Once you have KClient working, install the "Kerberos Settings" Eudora plugin in the same folder as the Eudora program. Note: if you have Eudora Pro 3.0, you may already have a copy of the Kerberos Settings plugin in "Extras:Plugins" -- If you do, then use that copy rather then the copy that is included with the CMF Kerberos distributions. Once you have the Kerberos Settings plugin installed, restart Eudora. Select the Settings dialog (under the Special menu entry), and scroll down until you find the "Kerberos Settings" entry. Under this, set the following things: Kerberos POP3 Port - 1109 Realm - CMF.NRL.NAVY.MIL Service - pop Service format - ^0.^1@^2 Then, under the "Checking Mail" entry (also in the Settings dialog), change your POP account to be "@ginger.cmf.nrl.navy.mil". Note - you _CANNOT_ use mailhost.cmf.nrl.navy.mil for this! Also, change the authentication mechanism to Kerberos (this is at the very bottom of the page in the "Checking Mail" setting box). Once this is done, try checking mail (command-M). If you haven't used KClient yet, you will get prompted for your password. If you have, then Eudora will not ask again until you Kerberos ticket expires (typically, this happens once a day). Note that when you use Kerberos POP with Eudora, this will disable the "Save password" feature of Eudora. DIRECTIONS FOR INSTALLING THE EUDORA KERBEROS PLUGIN FOR WINDOWS ---------------------------------------------------------------- After you have extracted the archive, you will see the following files: o README - This file o KCLIENT.DLL - DLL that interfaces with Eudora o KRBV4WIN.DLL - Another DLL that provides a Windows API o KRB.CON - The Kerberos configuration file o KERB16.EXE - A program that prompts for tickets Place all of these files into the directory C:\NET\KERB ***NOTE*** All of these files MUST BE IN C:\NET\KERB ! THEY CANNOT BE ANYWHERE ELSE. Set your path variable (set in AUTOEXEC.BAT) to include C:\NET\KERB. Also, in your AUTOEXEC.BAT, place the following line: SET KRBTKFILE= C:\NET\KERB\TICKET.KRB Also, make sure the time on yout machine is set correctly. It must be within five minutes of the time of our machines. Our machines are automatically synchronized to UTC, so if you set your machine to the "correct" time, then that will be good enough. Once these steps are done, reboot your machine. Once your machine comes back up, go into the "Settings" dialog in Eudora. Scroll down until you see the "Kerberos" box, and select it. Under this, select the following things: Kerberos POP3 Port - 1109 Realm - CMF.NRL.NAVY.MIL Service - pop Service format - %1.%4@%3 (The default for the service format will most likely be correct.) Then, under the "Checking Mail" entry (also in the Settings dialog), change your POP account to be "@ginger.cmf.nrl.navy.mil". Note - you _CANNOT_ use mailhost.cmf.nrl.navy.mil for this! Also, change the authentication mechanism to Kerberos (this is at the very bottom of the page in the "Checking Mail" setting box). Once this is done, try checking mail (under the File menu entry). You should be prompted for your Kerberos name and password. After you enter both items, Eudora should connect to the POP server and download your email. TIPS FOR GOOD SECURITY ---------------------- Here are some general security tips to keep in mind when using the Kerberos kit: - Try to insure your password does _not_ travel over any network. If you have to connect to another system to use the Kerberos kit, insure that you do _not_ connect to another system across the global Internet - otherwise you have negated any advantages of using Kerberos. - If you are only going to be connected for a short time, consider limiting your ticket lifetime by using the "-l" option to kinit. For example: % kinit -l 4h Gives you a ticket that will expire in four hours. This way, if your ticket is compromised, it can only be used for four hours. Note that this isn't possible, unfortunately, with the Macintosh KClient extension. - Run "kdestroy" when you're done to delete your Kerberos tickets. If you're using the Macintosh KClient extension, open the KClient control panel and press the "Logout" button. Unfortunately, this is not possible currently with the PC Eudora kit.