From owner-freebsd-doc@FreeBSD.ORG Sat Aug 23 06:52:26 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id A4ECD16A4BF for ; Sat, 23 Aug 2003 06:52:26 -0700 (PDT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id 01BE343FEA for ; Sat, 23 Aug 2003 06:52:24 -0700 (PDT) (envelope-from trhodes@FreeBSD.org) Received: from localhost (bay3-143.fyi.net [206.80.153.143]) by pittgoth.com (8.12.9/8.12.9) with SMTP id h7NDpvvd053310 for ; Sat, 23 Aug 2003 09:52:06 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Sat, 23 Aug 2003 09:27:54 -0400 From: Tom Rhodes To: FreeBSD-doc@FreeBSD.org Message-Id: <20030823092754.1e3dc84c.trhodes@FreeBSD.org> X-Mailer: Sylpheed version 0.9.3claws (GTK+ 1.2.10; i386-portbld-freebsd5.1) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Mailman-Approved-At: Sat, 23 Aug 2003 07:46:05 -0700 Subject: [Review Request: Kerberos5] handbook security chapter review X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 23 Aug 2003 13:52:26 -0000 Greetings, Here I bring the kerberos5 handbook section to everyone for review. A few tidbits of pre-review information: This was done under the theory that KerberosIV is gone from 5.1 and post releases. Thus there is a history part, and some extra information; this was done so that we can fade away the other chapter with ease. If it is desired for some unknown reason, I would like to commit the entire part and then in a seperate commit: remove the history/introduction. This method would allow myself, or another doc hacker to restore that information when the old version is dissolved. I will kill my whitespace lines before the commit, these are here for 'markers' so that I would not get lost during my initial copy-paste merge. Please ignore them. This was submitted to me in plain text, thus I did 95% of the mark up. All mistakes are mine and should be pointed out to me. I plan to commit this on Monday, or even Sunday night EST if I get enough review. Thanks! -- Tom Rhodes --- chapter.old Sat Aug 23 08:11:30 2003 +++ chapter.sgml Sat Aug 23 09:21:11 2003 @@ -106,7 +106,7 @@ servers – meaning that external entities can connect and talk to them. As yesterday's mini-computers and mainframes become today's desktops, and as computers become networked and - internetworked, security becomes an even bigger issue. + inter-networked, security becomes an even bigger issue. Security is best implemented through a layered onion approach. In a nutshell, what you want to do is @@ -1919,6 +1919,740 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 + + + + + + + + + + Tillman + Hodgson + Contributed by + + + + + Mark + Murray + Based on a contribution by + + + + + <application>Kerberos5</application> + + Every &os; release beyond &os;-5.1 includes support + only for Kerberos5. Hence + Kerberos5 is the only version + included, and its configuration is similar in many aspects + to that of KerberosIV. The following + information should only apply to + Kerberos5 in post &os;-5.0 + releases. + + Kerberos is a network add-on + system/protocol that allows users to authenticate themselves + through the services of a secure server. Services such as remote + login, remote copy, secure inter-system file copying and other + high-risk tasks are made considerably safer and more + controllable. + + Kerberos can be described as an + identity-verifying proxy system. It can also be described as a + trusted third-party authentication system. + + Note that Kerberos provides only + authentication services and nothing more. Therefore it is highly + recommended that Kerberos be used with + other security methods which authorization and audit services. + + The following instructions can be used as a guide on how to set + up Kerberos as distributed for &os;. + However, you should refer to the relevant manual pages for a complete + description. + + For purposes of demonstrating a Kerberos + installation, the various namespaceswill be handled as follows: + + + + The DNS domain (zone) will be example.prv. + + + + The Kerberos realm will be + EXAMPLE.PRV. + + + + Please refrain from the use of these namespaces in the real + world. Not only will it not be optimal for your network and + DNS server, it will make interoperating with other + Kerberos realms more difficult. + + + Background: History + + Kerberos was created by + MIT as a solution to network security problems. + The Kerberos protocol uses strong + cryptography so that a client can prove its identity to a server + (and vice versa) across an insecure network connection. + + Kerberos provides only one + function -- the secure authentication of users on the network. It + does not provide authorization functions (what those users are + able to perform) or auditing fuctions (what those users did). + After a client and server have used + Kerberos to prove their identity, they + can also encrypt all of their communications to assure privacy + and data integrity as they go about their business. + + Kerberos is both the name of a + network authentication protocol and an adjective to describe + programs that implement the program + (Kerberos telnet, for example). The + current version of the protocol is version 5, described in + RFC 1510. Kerberos + was designed to provide strong authentication for client/server + applications (such as traditional Internet services like + FTP and telnet) by using secret-key + cryptography. + + Several free implementations of this protocol are available, + covering a wide range of operating systems. The Massachusetts + Institute of Technology, where Kerberos + was originally developed, continues to develop their + Kerberos package and it is commonly used + in the US (as a cryptography product, it has + historically been affected by US export + regulations). The MIT + Kerberos is available as a port + (security/krb5). Heimdal + Kerberos is another version 5 + implementation, and was explicitly developed outside of the + US to avoid export + regulations (and is thus often included in non-commercial Unix + variants). The Heimdal Kerberos + distribution is available as a port + (security/heimdal), and a + minimal installation of it is included in the base &os; + install. + + In order to reach the widest audience, these instructions assume + the use of the Heimdal distribution included in &os;. + + + + + Background: <application>KerberosIV</application> and + <application>Kerberos</application> 5 + + Older versions of Kerberos included both + KerberosIV (eBones) and + Kerberos 5 (Heimdal). Support for + KerberosIV has been dropped as of &os; + 5.0. + + + + + Setting up a Heimdal <acronym>KDC</acronym> + + The KDC, or Key Distribution Center, is the + centralized authentication service that + Kerberos provides -- it is the computer + that issues Kerberos tickets. The + KDC is considered trusted by all + other computers in the Kerberos realm, and thus + has heightened security concerns. + + Note that while running the Kerberos + server requires very few computing resources, a dedicated machine + acting only as a KDC is recommended for security + reasons. + + To begin setting up a KDC, ensure that your + /etc/rc.conf file contains the correct + settings to act as a KDC (you may need to adjust + paths to reflect your own system): + + Kerberos5_server_enable="YES" +kadmind5_server_enable="YES" +Kerberos_stash="YES" + + Next we'll set up your Kerberos + config file, /etc/krb5.conf: + + [libdefaults] + default_realm = EXAMPLE.PRV +[realms] + EXAMPLE.PRV = { + kdc = Kerberos.example.prv + } +[domain_realm] + .example.prv = EXAMPLE.PRV + + Note that this /etc/krb5.conf file implies + that your KDC will have the fully-qualified + hostname of Kerberos.example.prv. You will need + to add a CNAME (alias) entry to your zone file to accomplish this + if your KDC has a different hostname. + + Next we will create the Kerberos + database. The keys of all the principals are stored in this + database in encrypted form with a master password. You are not + required to remember this password, it will be stored in a file + (/var/heimdal/m-key). To create the master + key, run kstash and enter a password. + + Once the master key has been created, you can initialize the + database using the kadmin program with the + -l option (standing for local). + This option instructs kadmin to modify the + database files directly rather than going through the + kadmind network service. This handles the + chicken-and-egg problem of trying to connect to the database + before it is created. Once you have the kadmin> + prompt, use the init command to create your + realms initial database. + + Lastly, while still in kadmin, create your + first principal using the add command. Stick + to the defaults options for the principal for now, you can always + change them later with the modify command. + Note that you can use the ? command at any + prompt to see the available options are. + + A sample database creation session is shown below: + + &prompt.root;kstash +Master key: xxxxxxxx +Verifying password - Master key: xxxxxxxx + +&prompt.root;kadmin -l +kadmin> init EXAMPLE.PRV +Realm max ticket life [unlimited]: +kadmin> add tillman +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +Password: xxxxxxxx +Verifying password - Password: xxxxxxxx + + Now it's time to start up the KDC services. + Run /etc/rc.d/Kerberos start and + /etc/rc.d/kadmind start to bring up the + services. Note that you won't have any Kerberized daemons running + at this point but you should be able to confirm the that the + KDC is functioning by obtaining and listing a + ticket for the principal (user) that you just created from the + command-line of the KDC itself: + + &prompt.user;k5init tillman +tillman@EXAMPLE.PRV's Password: + +&prompt.user;k5list +Credentials cache: FILE:/tmp/krb5cc_500 + Principal: tillman@EXAMPLE.PRV + + Issued Expires Principal +Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.PRV@EXAMPLE.PRV +Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.PRV@EXAMPLE.PRV + +v4-ticket file: /tmp/tkt500 +k5list: No ticket file (tf_util) + + + + + <application>Kerberos</application> enabling a server with + Heimdal services + + First, we need a copy of the Kerberos + configuration file, /etc/krb5.conf. To do + so, simply copy it over to the client computer from the + KDC in a secure fashion (using the network, + such as scp, or physically via a + floppy). + + Next you need a /etc/krb5.keytab file. + This is the major difference between a server provide + Kerberos enabled daemons and a + workstation -- the server must have a keytab file. This file + contains the servers host key, which allows it and the + KDC to verify each others identity. It + must be transmitted to the server in a secure fashion, as the + security of the server can be broken if the key is made public. + This explicitly means that transferring it via a clear text + channel, such as FTP, is a very bad idea. + + Typically, you transfer to the keytab to the server using the + kadmin program. This is handy because you also + need to create the host principal (the KDC end + of the krb5.keytab) using + kadmin. + + Note that you must have already obtained a ticket and that this + ticket must be allowed to use the kadmin + interface in the kadmind.acl. See the section + titled Remote administration in the Heimdal info + pages (info heimdal) for details on designing + access control lists. If you do not want to enable remote + kadmin access, you can simply securely connect + to the KDC (via local console, + ssh or Kerberos + telnet) and perform administration locally + using kadmin -l. + + After installing the /etc/krb5.conf file, + you can use kadmin from the + Kerberos server. The + add --random-key command will let you add the + servers host principal, and the ext command + will allow you to extract the servers host principal to its own + keytab. For example: + + &prompt.root;kadmin +kadmin> add --random-key host/myserver.example.prv +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +kadmin> ext host/myserver.example.prv +kadmin> exit + + Note that the ext command (short for + extract) stores the extracted key in + /etc/krb5.keytab by default, which is + handy. + + If you do not have kadmind running on the + KDC (possibly for security reasons) and thus + do not have access to kadmin remotely, you + can add the host principal + (host/myserver.example.prv) directly on the + KDC and then extract it to a temporary file + (to avoid over-writing the /etc/krb5.keytab + on the KDC) using something like this: + + &prompt.root;kadmin +kadmin> ext --keytab=/tmp/example.keytab host/myserver.smithclan.prv +kadmin> exit + + You can then securely copy the keytab to the server + computer (using scp or a floppy, for + example). Be sure to specify a non-default keytab name + to avoid over-writing the keytab on the + KDC + + At this point your server can communicate with the + KDC (due to it's krb5.conf + file) and it can prove it's own identity (due to the + krb5.keytab file). It's now ready for + you to enable some Kerberos services. + For this example we will enable the telnet + service by putting a line like this into your + /etc/inetd.conf and then restarting the + inetd service with + /etc/rc.d inetd restart: + + telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user + + The critical bit is that the -a + (for authentication) type is set to user. Consult for the + telnetd man page for more details. + + + + + <application>Kerberos</application> enabling a client with Heimdal + + Setting up a client computer is almost trivially easy. As + far as Kerberos configuration goes, + you only need the Kerberos + configuration file, located at /etc/krb5.conf. + Simply securely copy it over to the client computer from the + KDC. + + Test your client computer by attempting to use + kinit, klist and + kdestroy from the client to obtain, show, and + then delete a ticket for the principal you created above. You + should also be to use Kerberos + applications to connect to Kerberos + enabled servers, though if that doesn't work and obtaining a + ticket does the problem is likely with the server and not with + the client or the KDC. + + When testing an application like telnet, + try using a packet sniffer (such as tcpdump) + to confirm that your password is not sent in the clear. Try + using telnet with the -x + option, which encrypts the entire data stream (similar to + ssh). + + The core Kerberos client applications + (traditionally named kinit, + klist, kdestroy and + kpasswd) are installed in + the base &os; install. Note that &os; versions prior to 5.0 + renamed them to k5init, + k5list, k5destroy, + k5passwd, and kstash + (though it's typically only used once). + + Various non-core Kerberos client + applications are also installed by default. This is where the + minimal nature of the base Heimdal installation is + felt: telnet is the only + Kerberos enabled service. + + The Heimdal port adds some of the missing client applications: + Kerberos enabled versions of + ftp, rsh, + rcp, rlogin, and a few + other less common programs. The MIT port also + contains a full suite of Kerberos + client applications. + + + + + User config file: .k5login and .k5users + + Users within a realm typically have their + Kerberos principal (such as + tillman@EXAMPLE.PRV) mapped to a local + user account (such as a local account named + tillman). This well as the user account + usually does not have to be specified when using a client + application such as telnet. + + Occasionally, however, you want to grant access to a local + user account to someone who does not have a matching + Kerberos principal. For example, + tillman@EXAMPLE.PRV may need access to the + local user account webdevelopers. Other + principals may also need access to that local account. + + The .k5login and + .k5users files, placed in a users home + directory, can be used similar to a powerful combination of + .hosts and sudo, solving + this problem. For example, if a .k5login + with the following contents: + + tillman@EXAMPLE.PRV +jdoe@EXAMPLE.PRV + + Were to be placed into the home directory of the local user + webdevelopers then both principals listed + would have access to that account without requiring a shared + password. + + Reading the man pages for these commands is recommended. + Note that the ksu man page covers + .k5users. + + + + + Troubleshooting + + + + When using either the Heimdal or MIT + Kerberos ports ensure that your + PATH environment variable lists the + Kerberos versions of the client + applications before the system versions. + + + + Is your time in sync? Are you sure? If the time is not in + sync (typically within five minutes) authentication often + fails. + + + + MITand Heimdal interoperate nicely. + Except for kadmin, the protocol for + which is not standardized. + + + + If you change your hostname, you also need to change your + host/ principal and update your keytab. + This also applies to special keytab entries like the + www/ principal used for Apache's + mod_auth_kerb. + + + + All hosts in your realm must be resolvable (both forwards + and reverse) in DNS (or + /etc/hosts as a minimum). CNAMEs + will work, but the A and PTR records must be correct and in + place. The error message isn't very intuitive: + KerberosV5 refuses authentication because Read req + failed: Key table entry not found. + + + + Some operating systems that may being acting as clients + to your KDC do not set the permissions + for ksu to be setuid + root. This means that + ksu does not work, which is a good + security idea but annoying. This is not a + KDC error. + + + + With MIT + Kerberos, if you want to allow a + principal to have a ticket life longer than the default ten + hours, you must use modify_prinicpal in + kadmin to change the maxlife of both the + principal in question and the krbtgt + principal. Then the principal can use the + option with kinit + to request a ticket with a longer life. + + + + Note: If you run a packet sniffer on your + KDC to add in troubleshooting and then run + kinit from a workstation, you will notice + that your TGT is sent immediately upon + running kinit -- even before you type your + password! The explanation is that the + Kerberos server freely transmits a + TGT to any unauthorized request ... however, + every TGT is encrypted in a key derived from + the user's password. Therefore, when a user types their + password it is not being sent to the KDC, + it's being used to decrypt the TGT that + kinit already obtained. If the decryption + process results in a valid ticket with a valid time stamp, the + user has valid Kerberos credentials. + These credentials include a session key for establishing secure + communications with the Kerberos + server in the future, as well as the actual ticket-granting + ticket, which is actually encrypted with the + Kerberos server's own key. This + second layer of encryption is unknown to the user, but it's what + allows the Kerberos server to verify + the authenticity of each TGT. + + + + + <application>Kerberos</application> Tips + + + + + You have to keep the time in sync between all the + computers in your realm. NTP is + perfect for this. + + + + If you want to use long ticket lifetimes (a week, for + example) and you are using OpenSSH + to connect to the machine where your ticket is stored, make + sure that Kerberos + is set to no + in your sshd_config or else your tickets + will be deleted when you log out. + + + + Remember that host principals can have a longer ticket + life as well. If your user principal has a lifetime of a + week but the host you're connecting to has a lifetime of nine + hours, you will have an expired host principal in your cache + and the ticket cache will not work as expected. + + + + When setting up a krb5.dict file to + prevent specific bad passwords from being used (the man page for + kadmind covers this briefly), remember that + it only applies to principals that have a password policy + assigned to them. The krb5.dict files + format is simple: one string per line. Creating a symlink to + /usr/share/dict/words might be + useful. + + + + + + + Differences with the MIT port + + The major differences between the MIT + and Heimdal installs relates to the kadmin + program which has a different (but equivalent) set of commands + and uses a different protocol. This has a large implications + if your KDC is MIT as you + will not be able to use the Heimdal kadmin + program to administer your KDC remotely + (or vice versa, for that matter). + + The client applications may also take slightly different + command line options to accomplish the same tasks. Following + the instructions on the MIT + Kerberos web site () + is recommended. Be careful of path issues: the + MIT port installs into + /usr/local/ by default, and the + normal system applications may be run instead + of MIT if your PATH + environment variable lists the system directories first. + + Important note: With the MIT krb5 port + that is provided by &os;, be sure and read the + /usr/local/share/doc/krb5/README.FreeBSD + file installed by the port if you want to understand why logins + via telnetd and klogind + behave somewhat oddly. Most importantly, correcting the + incorrect permissions on cache file behavior + requires that the login.krb5 binary be used + for authentication so that it can properly chown the forwarded + credentials. + + + + + Mitigating limitations found in <application>Kerberos</application> + + + <application>Kerberos</application> is an all-or-nothing approach + + Every service enabled on the network must be modified to + work with Kerberos (or be otherwise + secured against network attacks) or else the users credentials + could be stolen and re-used. An example of this would be + Kerberos enabling all remote shells + (via rsh and telnet, for + example) but not converting the POP3 mail + server ... which sends passwords in plaintext. + + + + + <application>Kerberos</application> is intended for single-user workstations + + In a multi-user environment, + Kerberos is less secure. This is + because it stores the tickets in the global + /tmp directory, which is readable by all + users. If a user is sharing a computer with several other + people simultaneously (i.e. multi-user), it is possible that + the user's tickets can be stolen (copied) by another + user. + + This can be overcome with the -c + filename command-line option or (preferably) the + KRB5CCNAME environment variable, but this + is rarely done. In principal, storing the ticket in the users + home directory and using simple file permissions can mitigate + this problem. + + + + + The KDC is a single point of security failure + + By design, the KDC must be secure as + the master password database is contained on it. The + KDC should have absolutely no other + services running on it and should be physically secured. The + danger is high because Kerberos + stores all passwords encrypted with the same key (the + master key), which in turn is stored as a file + on the KDC. + + As a side note, a compromised master key is not quite as + bad as one might normally fear. The master key is only used + to encrypt the Kerberos database + and as a seed for the random number generator. As long as + access to your KDC is secure, an attacker + cannot do much with the master key. + + Additionally, if the KDC is unavailable + (perhaps due to a denial of service attack or network problems) + the network services are unusable as authentication can not be + performed, a recipe for a denail-of-service attack. This can + alleviated with multiple KDCs (a single + master and one or more slaves) and with careful implementation + of secondary or fall-back authentication + (PAM is excellent for this). + + + + + <application>Kerberos</application> Shortcomings + + Kerberos allows users, hosts + and services to authenticate between themselves. It does not + have a mechanism to authenticate the KDC + to the users, hosts or services. This means that a trojaned + kinit (for example) could record all user + names and passwords. Something like + security/tripwire or + other file system integrity checking tools can alleviate + this. + + + + + + + Resources and further information + + + + + The Kerberos FAQ + + + + Designing + an Authentication System: a Dialogue in Four Scenes + + + + RFC 1510, + The Kerberos Network Authentication Service + (V5) + + + + MIT + Kerberos home page + + + + Heimdal + Kerberos home page + + + + + + + + + +