From owner-freebsd-doc@FreeBSD.ORG Sat Aug 23 08:23:25 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 6A38E16A4BF; Sat, 23 Aug 2003 08:23:25 -0700 (PDT) Received: from arthur.nitro.dk (port324.ds1-khk.adsl.cybercity.dk [212.242.113.79]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9E64C43FE0; Sat, 23 Aug 2003 08:23:23 -0700 (PDT) (envelope-from simon@arthur.nitro.dk) Received: by arthur.nitro.dk (Postfix, from userid 1000) id 87C2110BFA8; Sat, 23 Aug 2003 17:23:22 +0200 (CEST) Date: Sat, 23 Aug 2003 17:23:22 +0200 From: "Simon L. Nielsen" To: Tom Rhodes Message-ID: <20030823152320.GC391@FreeBSD.org> References: <20030823094817.76e3b847.trhodes@FreeBSD.org> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="s2ZSL+KKDSLx8OML" Content-Disposition: inline In-Reply-To: <20030823094817.76e3b847.trhodes@FreeBSD.org> User-Agent: Mutt/1.5.4i cc: freebsd-doc@FreeBSD.org Subject: Re: Kerberos5 chapter [was: Your message to freebsd-doc awaits moderator approval] 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 15:23:25 -0000 --s2ZSL+KKDSLx8OML Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On 2003.08.23 09:48:17 -0400, Tom Rhodes wrote: > We can't send plain text emails anymore?? It normally works fine for me. Perhaps the spam filters have been set to be a bit more aggressive due to all the worm bounce mails lately (just a guess). > Here I bring the kerberos5 handbook section to everyone for review. > A few tidbits of pre-review information: >=20 > 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'm not really sure exactly which part you are talking about, but it's a part that should be enabled later, perhaps it could just be committed and "hidden" inside an SGML comment ()? --- chapter.old Sat Aug 23 08:11:30 2003 +++ chapter.sgml Sat Aug 23 09:21:11 2003 @@ -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 The first sentence and the first part of the second sentence seems to say the same? Perhaps a note about KerberosIV being available as a port for FreeBSD 5.1? (I think the the port is security/krb4). + 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. How about moving the note about what authorization and audit is to this paragraph since this is the first time the distinction is mentioned. + 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. Perhaps 'example.prv' should be marked up with ? + + + + 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). I meant these notes about authorization and auditing which I think should be moved up in the document. + 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 Perhaps insert ^ "(MIT)" I think it's a good idea to introduce acronyms, so there is no doubt what is meant when using them later. + 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 b= oth + 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=3D"YES" +kadmind5_server_enable=3D"YES" +Kerberos_stash=3D"YES" + + Next we'll set up your Kerberos + config file, /etc/krb5.conf: + + [libdefaults] + default_realm =3D EXAMPLE.PRV +[realms] + EXAMPLE.PRV =3D { + kdc =3D Kerberos.example.prv + } +[domain_realm] + .example.prv =3D 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 For the role defaults to 'hostname', so I think role=3D"fqdn" should be added above. + 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 Use &man.kadmin.8; ? (Since the manual page webinterface is broken for crypto pages right now the link will probably be bogus at the moment, but I think this will be fixed at some point). + -l option (standing for local). -l ? + 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> Typo: ^ + 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: How about marking up all occurrences of tillman with ? I haven't tried it; it might look silly, I'm not really sure... + + &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 Typo ? ^ + /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 &man.scp.1; ? + 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 &man.ssh.1; ? + telnet) and perform administration locally &man.telnet.1; ? + 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=3D/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 &man.inetd.1; ? + /etc/rc.d inetd restart: ^ Missing / + + telnet stream tcp nowait root /usr/libexec/te= lnetd 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) &man.tcpdump.1; + to confirm that your password is not sent in the clear. Try + using telnet with the -x ^^ -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 Manual page references for the above commands? + 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 Perhaps for the above files? I don't know if that's normally done in titles.. + + 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 Hmm, I don't have a ksu manual page.. Perhaps it's only in MIT Kerberos? + .k5users. + + + + + Troubleshooting + + + + When using either the Heimdal or MIT + Kerberos ports ensure that your + PATH environment variable lists the I think this should be PATH + 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. Perhaps a reference to the port 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_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 Hmm, here you use + + + + 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 Hmm, I don't remeber TGT being mentioned before? + 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. + Perhaps a reference to section 19.11 which describes NTP. + + + 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 around MIT here? + + 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 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