From owner-freebsd-doc@FreeBSD.ORG Thu Sep 4 11:10:27 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 DF2DF16A4BF; Thu, 4 Sep 2003 11:10:26 -0700 (PDT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id 17CF743FFD; Thu, 4 Sep 2003 11:10:24 -0700 (PDT) (envelope-from trhodes@FreeBSD.org) Received: from localhost (acs-24-154-239-225.zoominternet.net [24.154.239.225]) by pittgoth.com (8.12.9/8.12.9) with SMTP id h84IAMvd009286; Thu, 4 Sep 2003 14:10:22 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Thu, 4 Sep 2003 13:34:02 -0400 From: Tom Rhodes To: FreeBSD-doc@FreeBSD.org Message-Id: <20030904133402.06da66da.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 cc: Robert Watson Subject: [Review Request]: Kerberos5 final draft 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: Thu, 04 Sep 2003 18:10:27 -0000 Greetings -doc team, Robert, Please see the diff and give me feedback. This has already gone through a good review on -doc so I'm only really waiting for Robert's review. Although I want to get any final comments or "please commit's" now. Thanks! --- chapter.sgml Thu Sep 4 13:12:30 2003 +++ chapter.new Thu Sep 4 13:19:05 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,7 +1919,746 @@ 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 only applies to + Kerberos5 in post &os;-5.0 + releases. Users who wish to use the + KerberosIV package may install the + security/krb4 port. + + 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. + Kerberos provides only one + function — the secure authentication of users on the network. + It does not provide authorization functions (what users are + allowed to do) or auditing functions (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. + + Therefore it is highly recommended that + Kerberos be used with other security + methods which provide 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 namespaces will be handled as follows: + + + + The DNS domain (zone) + will be EXAMPLE.ORG. + + + + The Kerberos realm will be + EXAMPLE.ORG. + + + + + Please use real domain names when setting up + Kerberos even if you intend to run + it internally. This avoids DNS problems + and assures interoperation with other + Kerberos realms. + + + + 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 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. + + Several free implementations of this protocol are available, + covering a wide range of operating systems. The Massachusetts + Institute of Technology (MIT), where + Kerberos was originally developed, + continues to develop their Kerberos + package. It is commonly used in the US + as a cryptography product, as such 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;. + + + + + Setting up a Heimdal <acronym>KDC</acronym> + + The Key Distribution Center (KDC) 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" + + + The is only available in + &os; 4.X. + + + Next we will set up your Kerberos + config file, /etc/krb5.conf: + + [libdefaults] + default_realm = EXAMPLE.ORG +[realms] + EXAMPLE.ORG = { + kdc = kerberos.EXAMPLE.ORG + } +[domain_realm] + .EXAMPLE.ORG = EXAMPLE.ORG + + Note that this /etc/krb5.conf file implies + that your KDC will have the fully-qualified + hostname of kerberos.EXAMPLE.ORG. + You will need to add a CNAME (alias) entry to your zone file to + accomplish this if your KDC has a different + hostname. + + + For large networks with a properly configured + BIND DNS server, the + above example could be trimmed to: + + [libdefaults] + default_realm = example.org + + With the following lines being appended to the + exmple.org zonefile: + + _kerberos._udp IN SRV 01 00 88 kerberos.example.org. +_kerberos._tcp IN SRV 01 00 88 kerberos.example.org. +_kpasswd._udp IN SRV 01 00 464 kerberos.example.org. +_kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org. +_kerberos IN TXT EXAMPLE.ORG. + + Next we will create the Kerberos + database. This database contains the keys of all principals encrypted + 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. + + 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.ORG + 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.ORG's Password: + + &prompt.user;k5list + Credentials cache: FILE:/tmp/krb5cc_500 + Principal: tillman@EXAMPLE.ORG + + Issued Expires Principal + Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG + Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG + + 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 network utilities, + such as &man.scp.1;, or physically via a + floppy disk). + + Next you need a /etc/krb5.keytab file. + This is the major difference between a server providing + 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, + &man.ssh.1; or Kerberos + &man.telnet.1;) 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.ORG + Max ticket life [unlimited]: + Max renewable life [unlimited]: + Attributes []: + kadmin> ext host/myserver.EXAMPLE.ORG + kadmin> exit + + Note that the ext command (short for + extract) stores the extracted key in + /etc/krb5.keytab by default. + + 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.ORG) 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 + &man.inetd.8; 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 + &man.telnetd.8; manual 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 able to use Kerberos + applications to connect to Kerberos + enabled servers, though if that does not 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 &man.tcpdump.1;) + 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 configuration files: <filename>.k5login</filename> and <filename>.k5users</filename> + + Users within a realm typically have their + Kerberos principal (such as + tillman@EXAMPLE.ORG) mapped to a local + user account (such as a local account named + tillman). Client applications such as + telnet usually do not require a user name + or a principal. + + 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.ORG 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 .rhosts, + solving this problem. For example, if a + .k5login with the following + contents: + + tillman@example.org + jdoe@example.org + + 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. + + + + + <application>Kerberos</application> Tips, Tricks, and 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 will + fail. + + + + MIT and 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 + www/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_principal in + kadmin to change the maxlife of both the + principal in question and the krbtgt + principal. Then the principal can use the + -l option with kinit + to request a ticket with a longer lifetime. + + + + 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 (Ticket Granting + Ticket) 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. + + + + You have to keep the time in sync between all the + computers in your realm. NTP is + perfect for this. For more information on + NTP, see + . + + + + 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 + lifetime as well. If your user principal has a lifetime of a + week but the host you are 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 manual 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 symbolic + link to /usr/share/dict/words might be + useful. + + + + + + + Differences with the <acronym>MIT</acronym> port + + The major difference 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. + + With the MIT + security/krb5 port + that is provided by &os;, be sure to 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 change ownership for + 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 + /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 failure + + By design, the KDC must be as 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 denial-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 + + + + + + + -- Tom Rhodes