*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 (C) 1989 by the Massachusetts Institute of Technology 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. 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 (C) 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. 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. Cygnus Network Security *********************** Introduction ************ **Kerberos* The three-headed dog ... guards the entrance to Hades. He kept the living from entering the infernal regions...* *--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 `rlogin', `rsh', and `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. 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 "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.(1) Kerberos provides users with `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.(2) Users must decrypt the tickets, using their correct passwords, before the tickets can be used.(3) 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 "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 `rlogin' program, which starts a login shell on a remote machine, you automatically get a ticket for the `rlogin' service on the remote machine. The `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).(4) There are Kerberos versions of other familiar network utilities such as `rlogin', `rcp' and `rsh'. The `klogind' daemon is an example of an "application server". Each application server has a cryptographic keys with which to authenticate itself to the Kerberos server.(5) Currently, CNS does not support authentication forwarding. In other words, if users use `rlogin' to login to a remote host, they cannot use Kerberos services from that host unless they are authenticated on it (for instance with `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. ---------- Footnotes ---------- (1) 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. (2) 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. (3) All cryptographic manipulations are done by programs; all the CNS user has to do is enter a password. (4) Neither users nor application servers know each others' cryptographic keys. (5) Cryptographic keys are kept in a file (normally `/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. 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 *comp.protocols.kerberos*. Jennifer G. Steiner, Clifford Neuman, Jeffrey I. Schiller. "Kerberos: An Authentication Service for Open Network Systems," `USENIX Mar 1988'. `athena-dist.mit.edu:pub/kerberos/doc/usenix.PS' S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. Saltzer, "Kerberos Authentication and Authorization System," 12/21/87. R. M. Needham and M. D. Schroeder, "Using Encryption for Authentication in Large Networks of Computers," `Communications of the ACM', Vol. 21(12), pp. 993-999 (December, 1978). V. L. Voydock and S. T. Kent, "Security Mechanisms in High-Level Network Protocols," `Computing Surveys', Vol. 15(2), ACM (June 1983). Li Gong, "A Security Risk of Depending on Synchronized Clocks," `Operating Systems Review', Vol 26, #1, pp 49-53. S.M. Bellovin and M. Merritt, "Limitations of the Kerberos Authentication System," `USENIX Jan 1991'. `research.att.com: dist/internet_security/kerblimit.usenix.ps' Refik Molva, Gene Tsudik, Els Van Herreweghen, and Stefano Zatti, "KryptoKnight Authentication and Key Distribution System." `jerico.usc.edu: pub/gene/kryptoknight.ps.Z' C. Neumann and J. Kohl, "The Kerberos(tm) Network Authentication Service (V5)," September 1993. RFC1510. Barry Jaspan, `', compiler. `Kerberos Users' Frequently Asked Questions', January 18, 1994. User Programs ************* 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 `rlogin'. 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 `kinit' (*note kinit::.) command to find out. This command tries to get you a Kerberos `ticket-granting ticket' (*note Kerberos Tickets: Tickets.). `kinit' prompts you for a principal name and password (for more information about Kerberos principal names, *note Your Kerberos principal name: Principal names.). If the Kerberos server issues you a ticket-granting ticket, you have already been registered. If you enter your username and `kinit' responds with this message: Principal unknown (kerberos) 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. CNS for the User ================ Kerberos Tickets ---------------- When you authenticate yourself with Kerberos through the `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 `rlogin' and `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(1). 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 `kinit' command to re-authenticate yourself. If you use the `kinit' command to get your tickets, make sure you use the `kdestroy' command to destroy your tickets before you end your login session. You should probably put the `kdestroy' command in your `.logout' file so that your tickets is destroyed automatically when you logout. For more information about the `kinit' and `kdestroy' commands, see *Note kinit:: and *Note kdestroy::. ---------- Footnotes ---------- (1) Privileged tickets, such as `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. Command specifics: `kinit', `kdestroy', `klist' ----------------------------------------------- `kinit' (*note `kinit'--Kerberos login utility: kinit.) 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 `/tmp/tktUID' (where UID specifies your identification number) on the local machine. `kdestroy' (*note `kdestroy'--destroy Kerberos ticket: kdestroy.) 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. `klist' (*note `klist'--list currently held tickets: klist.) 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. 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. `kpasswd' (*note `kpasswd'--changing Kerberos passwords: kpasswd.) allows you to change your Kerberos authentication password, which may be different from the one you use to log in to your local machine. Your Kerberos principal name ---------------------------- Every Kerberos user and application server has a Kerberos principal name. Principal names are of the form `principal.instance@realm'. The following are all valid Kerberos principal names. harry tina.root lmb@barryar.navy.mil rlogin.miles@barryar.navy.mil The 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 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. 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, RLOGIN.MILES, is the `rlogin' server on the machine `miles'. In the example HARRY, the principal is the local realm where the server is running. 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 *Note Replacements::). The Berkeley `rlogin' program has been enhanced to use Kerberos to secure the connection. Kerberos' `rlogin' looks the same as a standard or system `rlogin' session, except that it trusts your tickets rather than the host you are on. Your `.rhosts' file no longer is used; instead, the system automatically trusts you, and optionally anyone whose Kerberos name you include in your `.klogin' file. For more information on the `klogin' file, see *Note .klogin files: rlogin. The `-x' option may be used with `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 `-x' if you want your session to be encrypted.) `rsh' has been enhanced in the same way that `rlogin' has, except that the `-x' option is not supported. `rcp' has been enhanced in the same way `rlogin' has. The `-x' option may be used to encrypt the file copy. For example, rcp -x DATAFILE REMOTEHOST:REMOTEDATAFILE securely copies DATAFILE to 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). Replacements for Familiar Network Facilities ============================================ 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 `krlogin' and `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. `rlogin'--Kerberos remote login ------------------------------- `rlogin' connects your terminal on the current local host system LHOST to the remote host system RHOST. SYNOPSIS ........ rlogin RHOST [-ec] [-8] [-c] [-C] [-a] [-t TERMTYPE] [-n] [-7] [-d] [-k REALM] [-x] [-noflow] [-flow] [-L] [-l USERNAME] RHOST [-ec] [-8] [-c] [-C] [-a] [-t TERMTYPE] [-n] [-7] [-d] [-k REALM] [-x] [-noflow] [-flow] [-L] [-l USERNAME] The version built to use Kerberos authentication is very similar to the standard Berkeley `rlogin'(1), except that instead of the `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 `.klogin' in his login directory. This file functions much like the `.rhosts' file; it allows non-local users to access the Kerberos service on the machine where the `.klogin' file exists. For example, user `joe@EAT.COM' would normally not be permitted to log in to machines in the `MUSSELS.COM' realm. However, Joe's friend `bertha@MUSSELS.COM' can create a `.klogin' file in her home directory, that contains the line `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 `principal.instance@realm'. The following are all valid Kerberos principal names. harry tina.root lmb@barryar.navy.mil rlogin.miles@barryar.navy.mil For more information about Kerberos principal names, see *Note Your Kerberos principal name: Principal names. If the originating user is authenticated to one of the principals named in `.klogin', access is granted to the account. The principal `ACCOUNTNAME@LOCALREALM' is granted access if there is no `.klogin' file. Otherwise, a login and password is prompted for on the remote machine as in `login'(1). To avoid security problems, the `.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 `rlogin' is executed in place of the Kerberos `rlogin'. This permits the use of the same `rlogin' command to connect to hosts that do not use CNS, as well as to host which do. A line of the form ``~.'' disconnects from the remote host, where ``~'' is the escape character. Similarly, the line ``~^Z'' (where ``^Z'', ``Control-Z'', is the suspend character) suspends the `rlogin' session. Substitution of the delayed suspend character (normally ``^Y')' for the suspend character suspends the send portion of the `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 `TERM' variable), unless the `-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 `rlogin' is transparent (except for delays). Flow control via ``^S'' and ``^Q'' and flushing of input and output on interrupts are handled properly. The `-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 ``^S''/``^Q''. Eight-bit mode is the default. The `-L' option allows the `rlogin' session to be run in `litout' mode (see `man stty'). The `-e' option allows specification of an escape character other than `~'. There is no space separating this option flag and the new escape character. If the `-e' option is used without specifying a character, then there is no escape character. The `-c' option requires confirmation before disconnecting via ``~.''. Normally, ``~.'' causes `rlogin' to exit immediately. The `-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 `rlogin' is executed in place of the Kerberos `rlogin' (see above). The `-t' option replaces the terminal type passed to the remote host with TERMTYPE. The `-n' option prevents suspension of rlogin via ``~^Z'' or ``~^Y''. The `-7' option forces seven-bit transmissions. The `-d' option turns on socket debugging (via `setsockopt'(2)) on the TCP sockets used for communication with the remote host. The `-noflow' option forces transmission of flow control characters (``^S''/``^Q'') to the remote system. This is now the default; `-flow' enables local handling of ``^S''/``^Q''. The `-k' option requests `rlogin' to obtain tickets for the remote host in realm REALM instead of the remote host's realm as determined by `krb_realmofhost'. The `-x' option turns on DES encryption for all data passed via the `rlogin' session. This significantly reduces response time and significantly increases CPU utilization. `rsh'--Kerberos remote shell ---------------------------- `rsh' connects to the specified host, and executes the specified COMMAND. rsh HOST [-l USERNAME] [-n] [-d] [-k REALM] [-p PORT] COMMAND HOST [-l USERNAME] [-n] [-d] [-k REALM] [-p PORT] COMMAND `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. `Interrupt', `quit' and `terminate' signals are propagated to the remote command; `rsh' normally terminates when the remote command does. The remote USERNAME used is the same as your local username, unless you specify a different remote name with the `-l' option. Kerberos authentication is used, and authorization is determined as in *Note rlogin::. The `-k' REALM option causes `rsh' to obtain tickets for the remote host in REALM instead of the remote host's realm as determined by `krb_realmofhost'. The `-d' option turns on socket debugging (via `setsockopt'(2)) on the TCP sockets used for communication with the remote host. The `-n' option redirects input from the special device `/dev/null'. If you are using `csh'(1) and put a `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 `-p' PORT option sets the TCP port number to use. This option is not normally used, but can be helpful when testing. If you omit COMMAND, then instead of executing a single command, you are logged in on the remote host using `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 rsh OTHERHOST cat REMOTEFILE >> LOCALFILE appends the remote file REMOTEFILE to the local file LOCALFILE, while rsh OTHERHOST cat REMOTEFILE ``>>'' OTHERREMOTEFILE appends REMOTEFILE (on the other host) to OTHERREMOTEFILE (also on the other host). On some systems, the host names for local machines are also commands in the directory `/usr/hosts'; if you put this directory in your search path then the `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 `/usr/kerberos/bin/rsh'. `rcp'--Kerberos remote file copy -------------------------------- RCP copies files between machines. rcp [-p] [-x] [-k REALM] [-N] [-P PORT] FILE1 FILE2 rcp [-p] [-x] [-k REALM] [-r] [-N] [-P PORT] FILE ... DIRECTORY Each file or directory argument is either a remote file name of the form RHOST`:'PATH, or a local file name (containing no `:' characters, or a `/' before any `:'s). If the `-r' option is specified and any of the source files are directories, `rcp' copies each subtree rooted at that name; in this case the destination must be a directory. By default, the mode and owner of FILE2 are preserved if it already existed; otherwise the mode of the source file modified by the `umask'(2) on the destination host is used. The `-p' option causes `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 `rhost'. A path on a remote host may be quoted (using `\', `"', or `'') so that the meta-characters are interpreted remotely. `rcp' does not prompt for passwords; it uses Kerberos authentication when connecting to RHOST. Authorization is as described in *Note rlogin::. The `-x' option selects encryption of all information transferred between hosts. The `-k' REALM option causes `rcp' to obtain tickets for the remote host in REALM instead of the remote host's realm as determined by `krb_realmofhost'. `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 `rcp' protocol. This is due to a limitation of the version 4 protocol. Hostnames may also take the form RNAME@RHOST' to use RNAME rather than the current user name on the remote host. There are two options to `rcp' which are not normally used, but can be helpful when testing. The `-N' option forces `rcp' to use a network connection, even when copying files which are on the local host. The `-P' PORT option sets the TCP port number to use. `pfrom'--Who sent me mail? -------------------------- pfrom [-s SENDER] [-h HOST] [-v] [-d] If you are using the `POP' mail system (*note popper::.) the `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 `-s' option is given, then only headers for mail sent by sender are printed. If the `-h' option is given, then HOST is consulted instead of your default post office. The `-v' option puts `pfrom' into verbose mode, and the `-d' option puts `pfrom' into debug mode. `pfrom' is equivalent to the `from' command used on traditional local mail systems. `tftp'--trivial file transfer protocol -------------------------------------- tftp -ACTION LOCALNAME HOST FOREIGNNAME [MODE] If action is `w', `p', or `ap', `tftp' writes the local file, called LOCALNAME, onto the foreign host's file system as FOREIGNNAME. If action is `ap', Kerberos authentication is used. Note that FOREIGNNAME must be in quotes if it contains shell special characters. If action is `r', `g', or `ag', `tftp' reads foreign host's file FOREIGNNAME into the local file, LOCALNAME. If action is `ag', Kerberos authentication is used. `tftp' does not supersede or overwrite existing local files, however; to do so, use action `o'. Mode may be `netascii', or `image'. `netascii', the default mode, transfers the file as standard ASCII characters. `image' mode transfers the file in binary, with no character conversion. If Kerberos authentication is not used with `tftp', access is denied unless the remote and local host are on the same local-area network. Ticket Management Commands ========================== `kinit'--Kerberos login utility ------------------------------- kinit [-ivl] The `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 *Note Initial Steps:: of the manual, or talk to your system administrator. When you use `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, `kinit' retrieves your ticket-granting ticket and puts it in the ticket file specified by your `KRBTKFILE' environment variable. If this variable is undefined, your ticket is stored in the `/tmp' directory, in the file `tktUID', where `uid' specifies your user ID number from the password file. Make sure you use the `kdestroy' command to destroy any active tickets before you end your login session. You may want to put the `kdestroy' command in your `.logout' file so that your tickets are destroyed automatically when you logout. The options to `kinit' are as follows: `-i' `kinit' prompts you for a Kerberos instance. `-r' `kinit' prompts you for a Kerberos realm. This option lets you authenticate yourself with a remote Kerberos server. `-v' Verbose mode. `kinit' prints the name of the ticket file used, and a status message indicating the success or failure of your login attempt. `-l' `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. `-s' `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, *Note SecureNet Key Authentication Device: Appendix.) `klist'--list currently held tickets ------------------------------------ klist [-s|-t] [-file NAME] [-srvtab] `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 `NAME.INSTANCE@REALM', with the `.' omitted if the instance is null, and the `@' omitted if the realm is null. If given the `-s' option, `klist' does not print the issue and expire times, the name of the ticket file, or the identity of the principal. If given the `-t' option, `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 `-file' option, the following argument is used as the ticket file. Otherwise, if the `KRBTKFILE' environment variable is set, it is used. If this environment variable is not set, the file `/tmp/tktUID' is used, where UID is the current user-ID of the user. If given the `-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 `-file' option, the default is `/etc/krb-srvtab'. See, *Note keys for application servers: Application server entries. `kdestroy'--destroy Kerberos tickets ------------------------------------ kdestroy [-f] [-q] The `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, `kdestroy' displays a message to that effect. After overwriting the file, `kdestroy' removes the file from the system. The utility displays a message indicating the success or failure of the operation. If `kdestroy' is unable to destroy the ticket file, the utility warns you by making your terminal beep. You should place the `kdestroy' command in your `.logout' file so that your tickets are destroyed automatically when you logout. The options to `kdestroy' are as follows: `-f' `kdestroy' runs without displaying the status message. `-q' `kdestroy' does not make your terminal beep if it fails to destroy the tickets. `kpasswd'--changing Kerberos passwords -------------------------------------- kpasswd [-h] [-n NAME] [-i INSTANCE] [-r REALM] [-u USERNAME[.INSTANCE][@REALM]] The `kpasswd' command is used to change a Kerberos principal's password. If the `-h' option is specified, a brief summary of the options is printed, and `kpasswd' then exits. If the `-n' option is specified, NAME is used as the principal name rather than the username of the user running `kpasswd'. (This is determined from the ticket file if it exists; otherwise, it is determined from the Unix user ID.) If the `-i' option is specified, INSTANCE is used as the instance rather than a null instance. If the `-r' option is specified, REALM is used as the realm rather than the local realm. If the `-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. `ksu'--Kerberized substitute user ID ------------------------------------ `ksu' requests the Kerberos password for login (or for `root', if no login is provided), and switches to that user and group ID. A shell is then invoked. ksu [-flm] [LOGIN] By default, your environment is unmodified with the exception of `USER', `HOME', and `SHELL'. `HOME' and `SHELL' are set to the target login's `/etc/passwd' values. `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 `-l' option simulates a full login. The environment is discarded except for `HOME', `SHELL', `PATH', `TERM', and `USER'. `HOME' and `SHELL' are modified as above. `USER' is set to the target login. `PATH' is set to `/usr/ucb:/bin:/usr/bin'. `TERM' is imported from your current environment. The invoked shell is that of the target login, and `ksu' changes directory to the target login's home directory. The `-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 `-m' option is specified, the target user's shell is a nonstandard shell (as defined by `getusershell'(3)) and the caller's real user ID is non-zero, `ksu' fails. If the invoked shell is `csh', the `-f' option prevents it from reading the `.cshrc' file. Otherwise, this option is ignored. Only users with root instances listed in `~root/.klogin' may `ksu' to `root' (The format of this file is described by *Note rlogin::.). When attempting root access, `ksu' attempts to fetch a ticket-granting ticket for `USERNAME.root@LOCALREALM', where USERNAME is the username of the process. If possible, the tickets are used to obtain, use, and verify tickets for the service `rcmd.HOST@LOCALREALM' where HOST is the canonical host name of the machine (as determined by `krb_get_phost'). If this verification fails, the `ksu' is disallowed. (If the service `rcmd.HOST@LOCALREALM' is not registered, the `ksu' is allowed.) By default (unless the prompt is reset by a startup file) the super-user prompt is set to `#' to remind one of its power. When not attempting to switch to the `root' user, `ksu' behaves exactly like `su'(1). The Kerberos Administrator: Configuration Decisions *************************************************** To make administration of a Kerberos realm simpler, some important decisions should be made before installation. Carefully consider the following options. Options for your Kerberos Service ================================= Choice of Names and Storage --------------------------- * *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 `krb-srvtab' file). The Kerberos master server itself needs enough disk space to hold the key database, and for reliability reasons should have the `kerberos' and `kadmin' servers locally. * *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 * *Realm name:* DNS domain name. * *Kerberos server names:* `kerberos' (for a single server) and `kerberos-N' (kerberos-1,2... etc.) for slaves. 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 `krb.realms' file or you need to have users specify the `-k' argument for most commands. What to put on a client ----------------------- Everything in this installation can be installed in a common location. Applications provided are: `kinit' `klist' `kdestroy' `rlogin' `rcp' `rsh' `telnet' `ksu' `kadmin' `movemail' `pfrom' `ftp' `kpasswd' A pair of configuration files (`krb.conf' and `krb.realms') are needed to identify the realms within which the host needs to authenticate (see, respectively, *Note `krb.conf'--Kerberos configuration file: krb.conf, and *note `krb.realms'--host to Kerberos realm translation file: krb.realms.). These files are stored in `/usr/kerberos/lib'. 1. Either install the release directly in `/usr/kerberos', or set up symbolic links or NFS mounts as your configuration warrants. 2. Generate `krb.conf' and `krb.realms' files with your local configuration parameters. See *Note krb.realms:: for details. 3. Update the `/etc/services' file. 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: `klogind' `telnetd' `kshd' `popper' `ksrvutil' `ftpd' `login.krb' `tftpd' Along with the configuration files used in the client install, you need to create a `krb-srvtab'. If the `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 `/etc/inetd.conf' on Berkeley Standard Distribution (BSD) derived systems. On some systems there is a limit on the number of services which `inetd' can support. If this is the case on your system, a simple workaround is to run a second instance of `inetd', the Internet service daemon, with a configuration file containing the Kerberos-enhanced services. On BSD derived systems, this `inetd' should be started in `/etc/rc.local' using whatever idiom was used for the normal `inetd'. 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: `Kerberos' `kadmind' `kstash' `kdb_util' `kdb_edit' `kdb_init' `kdb_destroy' `kprop' `kpropd' `ext_srvtab' 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, `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. (*Note kstash::.) 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 `kadmin/kpasswd' service--the master database is the only one that gets modified, and is defined as the one on which `kadmind' is running. Follow these steps to set up slave servers. * The master server and all slave servers must also be set up as application servers, with srvtab files containing an `rcmd' key. *Note Configuring an Application Server: (install)Application server configuration. * Each slave server uses the `kpropd' daemon to receive copies of the Kerberos database from the master server. Add a line like the following to `/etc/inetd.conf' to make `inetd' invoke the `kpropd' daemon when it receives an incoming connection: krb_prop stream tcp nowait root /usr/kerberos/etc/in.kpropd in.kpropd `in.kpropd' is a simple shell script which invokes `kpropd' with the correct arguments. * The master server uses the `kprop' program to send copies of the Kerberos database to the slave servers. This is most easily done using the `push-kprop' shell script. Enter the hostname of each slave server into the file `/usr/kerberos/database/slavelist'. This should be a simple text file, with each hostname on a separate line. * Run the `push-kprop' script on the master to send the master database over to all the slaves. You should arrange for `push-kprop' to be invoked regularly on the master, using `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. * Once the slaves have received their own copy of the database, you can start the `kerberos' server on the slave. Start it with the `-s' option. You should arrange for each slave server to start the `kerberos' server at boot time, just as on the master server, except that on the slaves `kerberos' should be invoked with `-s'. * Add the slave hostnames to the `/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 `krb.conf', so you can, for example, arrange for client programs to contact a local slave server before trying the master server. * To add a new slave server, just arrange for `kpropd' to be invoked via `inetd' on the slave, add the new slave hostname to `slavelist' on the master server, run `push-kprop' on the master server, and start `kerberos -s' on the new slave. For detailed information on `kprop', see *Note kprop and push-kprop::. For detailed information on `kpropd', see *Note kpropd: Slave Servers. General Configuration ===================== A few existing configuration files may be modified for the use of Kerberos. `/etc/services' Kerberos Enhanced services use different ports than their traditional counterparts. These need to be added to `/etc/services' on any client machine. `/etc/inetd.conf' If a machine is hosting any Kerberos Enhanced services, such as `popper' (see *Note popper::), `rlogind' (see *Note klogind::) or `rshd' (see *Note kshd::), these should be added to `inetd.conf' along with the other services the machine provides. It is also possible to run a second `inetd' with only the Kerberos services rather than changing the existing list. Note that if you wish to allow access *only* when Kerberos-mediated, than you must remove services like `rlogin' from `/etc/inetd.conf', leaving only the versions from Cygnus. For further protection, you may allow access to `eklogind', the server only for encrypted remote logins. `/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 `/etc/rc' file, or the equivalent on your system. *Note Configuring the KDC: (install)Configuring the KDC. CNS Configuration ================= `krb.conf'--Kerberos configuration file --------------------------------------- `krb.conf' contains configuration information describing the Kerberos realm and the Kerberos key distribution center (KDC) servers for known realms. `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 `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: 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 `krb.realms'--host to Kerberos realm translation 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 (DOMAIN_NAME should be of the form `.XXX.YYY', e.g. `.CYGNUS.COM'): HOST_NAME KERBEROS_REALM DOMAIN_NAME KERBEROS_REALM If a hostname exactly matches the 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 HOST_NAME in the file, but its domain exactly matches the 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. Administration Tools ******************** How to administer a Kerberos Realm ================================== Keys for users -------------- Users are "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 `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. 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 `krb-srvtab' file on the host supporting the application server. You must keep the `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 `krb-srvtab' is for a database administrator to use `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 `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 `krb-srvtab' with known password. It is best to immediately perform a `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 `kadmin' directly from the host for which the key is desired, and then use `ksrvutil' change, immediately. This avoids the need for any communication of the key. An alternative approach is to have the administrator use `kadmin' to enter the keys and then use `ext_srvtab' to create the new `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. kadmin and other utilities -------------------------- While `kdb_util' and `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 `admin' instance. You need to use `kdb_edit' to add an `admin' instance for at least one user. Once you have an `admin' instance, you can use the simpler `kadmin' program to handle most types of changes to the database. (For more information about `kdb_util', see *Note kdb_util::. For more information about `kdb_edit', see *Note kdb_edit::. For an example of using them to create an initial `admin' instance, see *note Configuring the KDC: (install)Configuring the KDC.). A database administrator either adds new entries or changes existing ones. New users are added with the `ank' (add new key) command to `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 `admin_acl.add' file to do this. (For information about ACL files, see *note ACL files: kadmind.). 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 `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 `kadmin' `cpw' request lets an administrator change the password of any user. An administrator must be listed in the `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 `.klogin' files or `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, `rlogin' and `rsh' use the same `rcmd' principal.) Administrative Tools ==================== `kadmin'--network utility for CNS database administration --------------------------------------------------------- kadmin [-u USER] [-r DEFAULT_REALM] [-m] This utility provides a unified administration interface to the Kerberos master database. Kerberos administrators use `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 `kadmin' to change a user's Kerberos password. A Kerberos administrator is a user with an `admin' instance whose name appears on one of the Kerberos administration access control lists. If the `-u' option is used, USER is used as the administrator instead of the local user. If the `-r' option is used, DEFAULT_REALM is used as the default realm for transactions. Otherwise, the local realm is used by default. If the `-m' option is used, multiple requests are permitted on only one entry of the admin password. Some sites do not support this option. The `kadmin' program communicates over the network with the `kadmind' program, which runs on the machine housing the Kerberos master database. The `kadmind' creates new entries and makes modifications to the database. When you enter the `kadmin' command, the program displays a message that welcomes you and explains how to ask for help. Then `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 `add_new_key' (or `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 NAME.INSTANCE@REALM convention (see, *note Your Kerberos principal name: Principal names.). 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 `-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 `change_password' (`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 NAME.INSTANCE@REALM convention. Use the `change_admin_password' (`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 `get_entry' (`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 `delete_principal' (`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 (`admin_acl.*' files (*note ACL files: kadmind.) and `.klogin' files (*note .klogin files: rlogin.)). If you do not, then, if the principal name is reused for somebody else, that person obtains unauthorized access. Use the `destroy_tickets' (`dest') command to destroy your admin tickets explicitly. Use the `list_requests' (`lr') command to get a list of possible commands. Use the `help' command to display `kadmin''s various help messages. If entered without an argument, help displays a general help message. You can get detailed information on specific `kadmin' commands by entering `help command_name'. Use the `add_snk_key' or `snk' to generate and display random keys for use initializing or reinitializing SNK4 devices. (See, *Note SecureNet Key Authentication Device: Appendix.) To quit the program, type `quit'. `kstash'--stash CNS Key Database master key ------------------------------------------- `kstash' saves the Kerberos key distribution center (KDC) database master key in the master key cache file, `/.k'. This is normally done so that the `kerberos' daemon can read the master key from the file when it starts up at boot time. If the key is not saved using `kstash', somebody must enter the master key manually each time the system is rebooted. The master key cache 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 `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. DIAGNOSTICS ........... `verify_master_key: Invalid master key, does not match database.' The master key string entered was incorrect. `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). `kstash: Write I/O error on master key file' The `write'(2) system call returned an error while `kstash' was attempting to write the key to the file. FILES ..... `/usr/kerberos/database/principal.pag' `/usr/kerberos/database/principal.dir' DBM files containing database `/.k' Master key cache file. `ksrvutil'--host CNS srvtab manipulation utility ------------------------------------------------ ksrvutil OPERATION [-k] [-i] [-f FILENAME] `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: `list' lists the keys in a srvtab showing version number and principal name. If the `-k' option is given, keys are also shown. `change' changes all the keys in the Kerberos database and in the `srvtab' by using the regular admin protocol. If the `-i' flag is given, `ksrvutil' prompts for `yes' or `no' before changing each key. If the `-k' option is used, the old and new keys are displayed. `add' allows the user to add a key. `add' prompts for name, instance, realm, and key version number, asks for confirmation, and then asks for a password. `ksrvutil' then converts the password to a key and appends the srvtab with the new information. If the `-k' option is used, the key is displayed. `delete' deletes particular keys in the srvtab, interactively prompting for each key. In all cases, the default file used is `/etc/krb-srvtab' as defined in `krb.h' unless this is overridden by the `-f' option. `ksrvutil' is used to add keys to a key file. A system manager asks a Kerberos administrator to create a new service key with *Note kadmin:: and supplies an initial password. The manager then uses `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. `ksrvutil' always makes a backup copy of the srvtab before making any changes. If `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 `FILENAME.old' where `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 `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. `ksrvtgt'--fetch and store CNS ticket-granting-ticket using a service key ------------------------------------------------------------------------- ksrvtgt NAME INSTANCE [[REALM] SRVTAB] `ksrvtgt' retrieves a ticket-granting ticket with a lifetime of 5 minutes for the principal NAME.INSTANCE@REALM (or NAME.INSTANCE@LOCALREALM if realm is not supplied on the command line), decrypts the response using the service key found in SRVTAB (or in `/etc/krb-srvtab' if 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 `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. * Make sure that `/etc/krb-srvtab' on `tapehost' drive has an entry for the `rcmd' service. This is already the case if `tapehost' is a CNS application server. * Add `rcmd.tapehost' to the `~root/.klogin' file on each client machine. This gives anybody with an `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). * The backup script on `tapehost' can then look something like this: for m in CLIENTS; do ksrvtgt rcmd `tapehost' rsh $m dump | dd of=TAPEDEVICE done The `ksrvtgt' command gets a ticket for the principal `rcmd.tapehost' and store it in root's ticket file. Since `rcmd.tapehost' is in `~root/.klogin' on the client machines, the `rsh' is permitted. * `ksrvtgt' is invoked before each `rsh' command. This is because the ticket obtained by `ksrvtgt' is short-lived: it is only valid for five minutes. * The script must be run by root. `ksrvtgt' must be able to read the `/etc/krb-srvtab' file, which should only be readable by root. * This approach means that if somebody is able to become root on `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 `rcmd.tapehost' to the `~root/.klogin' files on the client machines. kprop and push-kprop -------------------- kprop [-p] [-force] [-realm REALM] [-private] [-s SRVTAB] DATA_FILE SLAVES_FILE The `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. *Note Slave Server Installation:: for a description of how to use `kprop' and `kpropd' to set up slave servers. The `kprop' program communicates with the `kpropd' daemon, which runs on the slave server (*note kpropd: Slave Servers.). The DATA_FILE argument is a file created by `kdb_util' with the `slave_dump' option (*note kdb_util::.). The 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 `getservbyname' to look up the `krb_prop' service. If that is not defined, `kprop' uses `754'. The `kprop' program and the `kdb_util' program communicate using a semaphore file. The name of the file is the DATA_FILE argument with `.dump_ok' appended. The file is automatically created by `kdb_util' when the `slave_dump' option is used. The `push_kprop' shell script may be used to invoke `kprop'. It assumes that the list of slaves is in the file `/usr/kerberos/database/slavelist'. Normally the Kerberos database is propagated from the server to the slaves by invoking `push_kprop' on a regular basis using `cron'. The `kprop' program requires a srvtab file with an entry for `rcmd'.HOSTNAME@REALM. This is the same type of srvtab file required to run the `klogind' or `kshd' servers. Srvtab files can be created using the `ksrvutil' program (*note ksrvutil::.). The default srvtab file is `/etc/krb-srvtab'. This default may be overridden with the `-s' option. The `-p' option means to use preauthentication when retrieving tickets. The `-force' option means to transfer the database even if the semaphore file generated by `kdb_util' indicates that the dump is not up to date. The `-realm' REALM option sets the Kerberos realm name. The default realm name is obtained using `krb_get_lrealm'. The `-private' option means to encrypt the data being sent to the slave server. This is the default. The `-s' SRVTAB sets the name of the srvtab file to use when retrieving tickets. The default is `/etc/krb-srvtab'. Raw Database Management ======================= Directly manipulate key database on key distribution center. `kdb_edit'--CNS Key Database editing utility -------------------------------------------- kdb_edit [-n] [-k mkeyfile] `kdb_edit' is used to create or change principals stored in the Kerberos key distribution center (KDC) database. When executed, `kdb_edit' prompts for the master key string and verifies that it matches the master key stored in the database. If the `-n' or `-k' options are specified, the master key is instead fetched from a master key cache file (as created by `kstash'). The `-n' option reads the default master key cache file, `/.k'. The `-k' option may be used to name a different key cache file. Once the master key has been verified, `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 `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, `Edit O.K.' is printed. `kdb_init'--Initialize Kerberos Key Database -------------------------------------------- kdb_init [REALM] `kdb_init' initializes a Kerberos key distribution center database, creating the necessary principals. If the optional REALM argument is not present, `kdb_init' prompts for a realm name (or default to the pre-defined value in `/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. `kdb_destroy'--destroy Kerberos Key Database -------------------------------------------- kdb_destroy `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 `y' or `Y' confirms deletion. Any other response aborts deletion. Extreme caution should be exercised in the use of this command. `kdb_util'--Kerberos Key Database utility ----------------------------------------- kdb_util OPERATION FILENAME `kdb_util' allows the Kerberos key distribution center (KDC) database administrator to perform utility functions on the database. OPERATION must be one of the following: `load' Initializes the KDC database with the records described by the text contained in the file FILENAME. Any existing database is overwritten. `dump' dumps the KDC database into a text representation in the file FILENAME. `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. `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 FILENAME. The keys in the text representation are encrypted in the new master key. `convert_old_db' prompts for the master key string, and then dumps the KDC database into a text representation in the file 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). Daemons ******* Admin Services ============== `kadmind'--network daemon for Kerberos database administration -------------------------------------------------------------- kadmind [-n] [-h] [-r REALM] [-f FILENAME] [-d DBNAME] [-a ACLDIR] `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 `-n' option is specified, the master key is instead fetched from the master key cache file. If the `-r' REALM option is specified, the admin server pretends that its local realm is 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 `-f' FILENAME option is specified, that file is used to hold the log information instead of the default. If the `-d' DBNAME option is specified, that file is used as the database name instead of the default. If the `-a' ACLDIR option is specified, the directory ACLDIR is searched for access control lists. The default is `/usr/kerberos/database'. If the `-h' option is specified, `kadmind' prints out a short summary of the permissible control arguments, and then exits. When performing requests on behalf of clients, `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 `/usr/kerberos/database'; this may be overridden by the `-a' option. Each ACL file is named with a prefix of `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 `.klogin' file; *note .klogin files: rlogin.). Currently three distinct access types are supported: * Addition (`.add' ACL file). If a principal is on this list, the principal may add new principals to the database. * Retrieval (`.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. * Modification (`.mod' ACL file). If a principal is on this list, the principal may modify entries in the database. A principal is always granted authorization to change its own password. FILES ..... `/usr/kerberos/database/admin_server.syslog' Default log file. `/usr/kerberos/database' Default access control list directory. `admin_acl.add' `admin_acl.get' `admin_acl.mod' Access control list files (within the directory) `/usr/kerberos/database/principal.pag' `/usr/kerberos/database/principal.dir' Default DBM files containing database `/.k' Master key cache file. Interactive Command =================== `popper'--pop 3 server ---------------------- /usr/etc/popper [-d] [-t TRACE-FILE] `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/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. The POP server uses `syslog' to keep a record of its activities. On systems with BSD 4.3 syslogging, the server logs (by default) to the `local0' facility at priority `notice' for all messages except debugging which is logged at priority `debug'. The default log file is `/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 `/usr/spool/mqueue/syslog'. DEBUGGING ......... The `popper' program logs debugging information when the `-d' parameter is specified after its invocation in the `inetd.conf' file. The `-d' flag sets the socket to debugging and turns on debugging. All debugging information is saved using `syslog'(8). Care should be exercised in using this option since it generates considerable output in the syslog file. Alternatively, the `-t FILE-NAME' option places debugging information into file `FILE-NAME' using `fprintf' instead of `syslog'. You can confirm that the POP server is running on Unix by `telnet'ing to port 110 (or 109 if you set it up that way). For example: %telnet MYHOST 110 Trying... Connected to MYHOST.berkeley.edu. Escape character is '^]'. +OK UCB Pop server (version 1.6) at MYHOST starting. quit Connection closed by foreign host. FILES ..... `/usr/spool/mail' mail files `/etc/inetd.conf' pop program invocation `/etc/syslog.conf' logging specifications `klogind'--Kerberos remote login server --------------------------------------- /usr/kerberos/etc/klogind /usr/kerberos/etc/Klogind /usr/kerberos/etc/eklogind `klogind' is the server for the Kerberos version of the *Note rlogin:: program. The server provides a remote login facility with authentication provided by Kerberos. `klogind' listens for service requests at the port indicated in the `klogin' or `eklogin' service specification; see `services'(5). In the past, invocation as `klogind' was used for normal hosts to which password access was granted if Kerberos authentication failed, whereas invocation as `Klogind' required Kerberos authentication. However, this distinction has been removed, because `klogind' does not behave identically to the traditional `rlogind' server, and because the password fallback does not work with encryption. Invocation as `klogind' is now identical to invocation as `Klogind'. It is still possible to run the system provided `rlogind' server to permit access with a password. Invocation as `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 `gethostbyaddr'(3N), `hosts'(5) and `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, `klogind' allocates a pseudo terminal (see `pty'(4)), and manipulates file descriptors so that the slave half of the pseudo terminal becomes the `stdin', `stdout', and `stderr' for a login process. The login process is an instance of the `login'(1) program, invoked with the `-k', `-K', or `-e' option, depending on whether the `klogind' was started as `klogind', `Klogind' or `eklogind', respectively. The login process then proceeds with the authentication process as described in *Note 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 `rlogin' program. If `klogind' is invoked as `eklogind', all data passed over the network are encrypted. In normal operation, the packet protocol described in `pty'(4) is invoked to provide `^S'/`^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, `TERM'; see `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. `Klogind' accepts three options which may be used for testing purposes. The `-l' LOGIN_PROGRAM option sets the login program to run. The default value is normally `/usr/kerberos/etc/login.krb'. The `-r' REALM_FILE option sets the name of the `krb.realms' file to use. The default value is normally `/usr/kerberos/lib/krb.realms'. *Note krb.realms::. The `-s' SRVTAB_FILE option sets the name of the srvtab file to use. The default value is normally `/etc/krb-srvtab'. `kshd'--Kerberos remote shell server ------------------------------------ /usr/kerberos/etc/kshd `kshd' is the server for the `kcmd' routine and, consequently, for the *Note rsh:: program. The server provides remote execution facilities with authentication based on Kerberos. `kshd' listens for service requests at the port indicated in the `kshell' service specification; see `services'(5). When a service request is received the following protocol is initiated: 1. The server reads characters from the socket up to a null (\0) byte. The resultant string is interpreted as an ASCII number, base 10. 2. 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 `stderr'. A second connection is then created to the specified port on the client's machine. 3. The server checks the client's source address and requests the corresponding host name (see `gethostbyaddr'(3N), `hosts'(5) and `named'(8)). If the hostname cannot be determined, the dot-notation representation of the host address is used. 4. A Kerberos ticket/authenticator pair are retrieved on the initial socket. 5. 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. 6. 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. 7. `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 `chdir' is performed to the user's home directory. If either the lookup or `chdir' fail, the connection is terminated. The `.klogin' file in the home directory is used to mediate access to the account (via `kuserok') by the Kerberos principal named in the ticket/authenticator. If this authorization check fails, the connection is terminated. 8. 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 `kshd'. `kshd' accepts three options which may be used for testing purposes. The `-p' DIRECTORY option sets the directory where Kerberos programs are found. This directory is put at the start of `PATH' before the command is executed. The default value is normally `/usr/kerberos/bin'. (For correct operation of Kerberos `rcp', the Kerberos `rcp' program must be in `PATH' before any other `rcp' program. *Note rcp::). The `-r' REALM_FILE option sets the name of the `krb.realms' file to use. The default value is normally `/usr/kerberos/lib/krb.realms'. *Note krb.realms::. The `-s' SRVTAB_FILE option sets the name of the srvtab file to use. The default value is normally `/etc/krb-srvtab'. 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). `remuser too long' The name of the user on the remote machine is longer than 16 characters. `command too long' The command line passed exceeds the size of the argument list (as configured into the system). `Login incorrect.' No password file entry for the user name existed. `No remote directory.' The `chdir' command to the home directory failed. `Permission denied.' The authorization procedure described above failed. `Can not make pipe.' The pipe needed for the `stderr', was not created. `Try again.' A `fork' by the server failed. `SHELLNAME: ...' The user's login shell could not be started. This message is returned on the connection associated with the `stderr', and is not preceded by a flag byte. File Transfer ============= `tftpd'--server tftp daemon --------------------------- /etc/tftpd `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 `/tftpd'; the 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 `tftp' command program *Note tcom:: to control the daemon's operation. FILES ..... `/tftpd/lock' interlock, PID storage `/dev/net' the network device `tcom'--control operation of server tftp daemon ----------------------------------------------- tcom `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: `help' display a list of commands `input trace on|off' turn tracing of input packets on or off `output trace on|off' turn tracing of output packets on or off `trace on|off' turn all packet tracing on or off `times' display server parent and children process times `uptime' display daemon up time `exit' force daemon to shut down and exit FILES ..... `/tftpd/lock' lock file containing daemon's PID `/tftpd/command' command file to daemon `/tftpd/slog' daemon's log file Note that two `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. Slave Servers ============= kpropd [-r REALM] [-s SRVTAB] [-d DATABASE] [-u PORT] [-l LOGFILE] [-i] [-c COMMAND] [-C ARG] FILENAME The `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. *Note Slave Server Installation:: for a description of how to use `kprop' and `kpropd' to set up slave servers. The `kprop' program running on the master server contacts the `kpropd' daemon running on the slave server in order to copy over the Kerberos database (*note kprop and push-kprop::.). The `kpropd' daemon is normally started by arranging for `inetd' to run the `in.kpropd' shell script. Normally, a line like this would be added to the `/etc/inetd.conf' file: krb_prop stream tcp nowait root /usr/kerberos/etc/in.kpropd in.kpropd The `kpropd' daemon may also be run directly as a server. The `kpropd' daemon has a single required argument, which is the name of a file in which to store the database received from `kprop' running on the master server (the `in.kpropd' script passes `/usr/kerberos/database/slavedb'). After `kpropd' receives the database information, it runs `kdb_util' to load it into the local Kerberos database (*note kdb_util::.). The `kpropd' daemon only accepts data from machines which are listed in `krb.conf' as an admin server (*note krb.conf::.). The `-r' REALM option sets the Kerberos realm name. The default realm is obtained using `krb_get_lrealm'. The `-s' SRVTAB option sets the name of the srvtab file to use when authenticating the ticket received from `kprop'. The default is `/etc/krb-srvtab'. The `-d' DATABASE option sets the name of the Kerberos database. This is a prefix used to name three files. The default is `/usr/kerberos/database/principal'. The `-u' PORT option sets the port to accept connections on. This is only meaningful if the `-i' option is not used. The default is to use `getservbyname' to look up the `krb_prop' service. If that is not defined, `kpropd' uses `754'. The `-l' LOGFILE option sets the name of the log file. The default is `/usr/kerberos/database/kpropd.log'. The `-i' option causes `kpropd' to assume that it was run from `inetd'. The default is for `kpropd' to open a socket and to loop accepting connections. The `-c' COMMAND option sets the path of the `kdb_util' command which `kpropd' should run after receiving the database. The default is to just run `kdb_util', assuming it is on `PATH'. The `-C' ARG option sets the argument to pass to `kdb_util'. The default argument is `load'. A Glossary of Kerberos Terms **************************** * *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. * *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 `/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. * *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 `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'.) * *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 *authorizes* you to perform certain functions. * *authorization:* A process whereby you get permission to perform actions. In the example of the bank machine above, you are *authenticated* to the bank machine by using your card and PIN number; then the bank's computer *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. * *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'.) * *domain:* As in feudal days, a *domain* is an area over which one administrator exercises control. * *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). * *instance:* An instance refers to a particular *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 *admin*). Instances are normally written after the principal name, separated by a dot, as in `person.admin'. Some programs (`kinit' and `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, `rcmd.host1@your-realm' is the principal name for the `rcmd' service (the name used by `rlogin, rcp', and `rsh') for `host1' in your realm. (See, `principal'.) * *key:* The encryption secret used to encrypt and decrypt network `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. * *principal:* A Kerberos principal can be a user, a host, a service, a client, or an application server. The term *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 `principal.instance@realm' is called the principal name. * *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). * *server:* See `application server'. * *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 *ticket file,* where the Kerberos client looks to find authentication information, is sometimes incorrectly referred to as a ticket, as well. 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: * Bill Bryant, MIT Project Athena * Bill Sommerfeld, MIT Project Athena * Bob Baldwin * Bob McKie, MIT Project Athena * Brian Murphy, MIT Project Athena * Chris Reed, MIT Project Athena * Clifford Neuman, MIT Project Athena * Dan Geer, MIT Project Athena * David Jedlinsky, MIT Project Athena * Douglas A. Church, MIT Project Athena * Emanuel Jay Berkenbilt, MIT Project Athena * Jeffrey I. Schiller, MIT Project Athena * Jennifer Steiner, MIT Project Athena * Jim Aspnes, MIT Project Athena * Jim Bloom * John Barba * John T. Kohl, Project Athena/Digital Equipment Corporation * John Kubiatowicz, MIT Project Athena * Jon Rochlis, MIT Project Athena * Ken Raeburn, MIT Project Athena (Now at Cygnus Support) * Mark Eichin, Cygnus Support * Mike Shanzer, MIT Project Athena * Richard Basch, MIT Project Athena * Rob French, MIT Project Athena * Steve Miller, MIT Project Athena/Digital Equipment Corporation * Ted Ts'o, MIT Project Athena * Win Treese, MIT Project Athena/Digital Equipment Corporation 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: * Massachusetts Institute of Technology, for the *man* pages which formed the basis of some sections of this documentation. * John Gilmore, Mark Eichin and Ken Raeburn of Cygnus Support. * Kerberos Users' Frequently Asked Questions Guide, compiled by: Barry Jaspan, , OpenVision Technologies. SecureNet Key Authentication Device *********************************** 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. The SecureNet Key Devise ======================== The SecureNet Key device (SNK4) is a product of Digital Pathways. The function of the device is simple. *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. *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. *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 `A', `B', or `C' appear, they are replaced by the digit `2'; likewise `D', `E', and `F' are replaced by `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. Example of SecureNet Key use ============================ To use an SNK4 device for Kerberos authentication: % 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 or % kinit -s username Challenge #1: 123456 Response #1:12345678 Challenge #2: 789012 Response #2:78901234 % 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.) 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 `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 *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.) Implementation of SecureNet Key in Kerberos V4 ============================================== There are four parts to this extension: ``krb_get_in_tkt'' The library function `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 `krb_mk_in_tkt' and `krb_parse_in_tkt' to allow the client to do the challenge and response locally, without the callback. ``kinit -s'' An alternate mode of use of of `kinit' is provided which prompts as before but adds +SNK4 to the instance, allowing the KDC to identify and generate a different response. `Kerberos (KDC)' A modification of the normal KDC which recognizes the `+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. ``kadmin snk'' A new query to the `kadmin' program, `add_snk_key' or `snk' which generates and displays random keys for use initializing or reinitializing SNK4 devices. Includes key verification check. Since the user is authenticated as USER*.+SNK4@*REALM instead of simply USER*@*REALM access control can be done using the standard ACL files--`~root/.klogin' for example. The protocol changes are simple. *Request* The request is unchanged, except for the addition of `+SNK4' to the instance. *Reply* The reply is distinctly different, but should not matter as only `kinit -s' ever sees one. The structure is: `version' The eight characters `cnssnk01' `challenge 1' Also eight characters, six digits and two zero bytes. `challenge 2' Same format as challenge 1. If this is the same string, the user is only issued one challenge. `encrypted ticket' Same as the original protocol raw ticket. 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 `kinit' could still decrypt the ticket if it had the right key--but it could not, so we do not do that.