From owner-freebsd-doc@FreeBSD.ORG Sun Aug 24 04:11:52 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 B1DE816A4BF; Sun, 24 Aug 2003 04:11:52 -0700 (PDT) Received: from Kain.sumuk.de (Kain.sumuk.de [213.221.86.114]) by mx1.FreeBSD.org (Postfix) with ESMTP id 1205A43FAF; Sun, 24 Aug 2003 04:11:49 -0700 (PDT) (envelope-from vincent@sumuk.de) Received: from Moses.earth.sol (Moses.earth.sol [192.168.1.1]) by Kain.sumuk.de (8.12.9/8.12.8) with ESMTP id h7OBBlZ6032057; Sun, 24 Aug 2003 13:11:47 +0200 (CEST) (envelope-from vincent@sumuk.de) Received: from Moses.earth.sol (localhost.earth.sol [127.0.0.1]) by Moses.earth.sol (8.12.5/8.12.5) with ESMTP id h7OBBjPg064693; Sun, 24 Aug 2003 13:11:46 +0200 (CEST) (envelope-from vincent@Moses.earth.sol) Received: (from vincent@localhost) by Moses.earth.sol (8.12.5/8.12.5/Submit) id h7OBBjZ4064692; Sun, 24 Aug 2003 13:11:45 +0200 (CEST) Date: Sun, 24 Aug 2003 13:11:44 +0200 From: Martin Heinen To: Tom Rhodes Message-ID: <20030824131144.A62111@sumuk.de> References: <20030823092754.1e3dc84c.trhodes@FreeBSD.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <20030823092754.1e3dc84c.trhodes@FreeBSD.org>; from trhodes@freebsd.org on Sat, Aug 23, 2003 at 09:27:54AM -0400 cc: FreeBSD-doc@freebsd.org Subject: Re: [Review Request: Kerberos5] handbook security chapter review X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list Reply-To: FreeBSD-doc@freebsd.org List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 24 Aug 2003 11:11:52 -0000 On Sat, Aug 23, 2003 at 09:27:54AM -0400, Tom Rhodes wrote: > Greetings, > > Here I bring the kerberos5 handbook section to everyone for review. Great, thanks to both of you. You will find my suggestions inline. There are a lot of contractions (you're) inside which need to be expanded (I did not mark them all). > 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! This is a long patch to review, it took me at least three runs :-) > --- 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. This would be a separate commit? > > 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 > > [ ... ] > + <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 ^^^^^^^^^^^^^^^^^^^^ ... applies only 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. [1] (reference, see below) The introduction should also explain the common Kerberos buzzwords (e.g. tickets, principals). > + > + 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. ^^^^^^^^^^^^^^^^^^^ ... which provide authorization > + > + 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: ^^^^^^^^^^^^^^ ... namespaces will > + > + > + > + The DNS domain (zone) will be example.prv. > + > + > + > + The Kerberos realm will be > + EXAMPLE.PRV. > + > + All domain names in examples should be "example.org". > + > + 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. I would like to put this into a note and reformulate it a bit: Please use real domain names when setting up Kerberos. This avoids DNS problems and assures interoperation with other Kerberos realms. > + > + > + Background: History If history is background information, then there is no need to state this: 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). Maybe "what users are allowed to do" sounds better? > + 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 ^ RFC 1510. > + was designed to provide strong authentication for client/server > + applications (such as traditional Internet services like > + FTP and telnet) by using secret-key > + cryptography. The purpose of Kerberos was already described above [1]. The last sentence could be removed. > + > + 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 Split this into two sentences? package. Kerberos is commonly ... > + 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 ^^^^ UNIX or &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. > + > + This section tells nothing new and should be removed. > + > + > + Setting up a Heimdal <acronym>KDC</acronym> > + > + The KDC, or Key Distribution Center, is the The Key Distribution Center (KDC) > + 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" Don't know exactly: ... kerberos5_server_enable="YES" CURRENT does not have "Kerberos_stash" in /etc/defaults/rc.conf. > + > + Next we'll set up your Kerberos we will > + config file, /etc/krb5.conf: > + > + [libdefaults] > + default_realm = EXAMPLE.PRV > +[realms] > + EXAMPLE.PRV = { > + kdc = Kerberos.example.prv ^^^^^^^^^^^^^ I don't think we should markup to program listings. The listings are provided as is. > + } > +[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 How about: The database contains the keys of all principals encrypted with a master password. > + 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> ^ 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. ^^^^^ 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.PRV > +Realm max ticket life [unlimited]: > +kadmin> add tillman > +Max ticket life [unlimited]: > +Max renewable life [unlimited]: > +Attributes []: > +Password: xxxxxxxx > +Verifying password - Password: xxxxxxxx This should be a screen element and entered text should be marked up with tags. There should be space between the prompt and the command. > + > + Now it's time to start up the KDC services. ^^^^ ... it is > + 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) This "screen shot" should use too. > + > + > + > + > + <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). Does /etc/krb5.conf really need to be transfered in a secure fashion? After all, it contains only information which is already public. > + > + Next you need a /etc/krb5.keytab file. > + This is the major difference between a server provide ^^^^^^^ ... providing > + Kerberos enabled daemons and a > + workstation -- the server must have a keytab file. This file — "keytab" and all further instances should probably be marked up with keytab. > + 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. Instead of stating what not to do, it is better to explain how to transfer the file in a secure fashion (scp, floppy). > + > + Typically, you transfer to the keytab to the server using the ^^^^^^^^^^^^^^^^^^^^ ... transfer the keytab file to > + kadmin program. This is handy because you also > + need to create the host principal (the KDC end > + of the krb5.keytab) using > + kadmin. > + [ ... ] > + &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. Delete "which is handy" The example following proves that this is not 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 ^^ Missing ".". > + > + 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 ... It is now > + 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. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ &man.telnetd.8; > + > + > + > + > + <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 ^^^^^^^^ See above. > + 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 ^^^^^ Missing "able". > + applications to connect to Kerberos > + enabled servers, though if that doesn't work and obtaining a ^^^^^^^ ... does not > + ticket does the problem is likely with the server and not with > + the client or the KDC. [ ... ] > + > + User config file: .k5login and .k5users .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. How about: 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.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 I don't know if everyone is familar with sudo. The file .k5login is similar to .rhosts, which is well known. > + this problem. For example, if a .k5login > + with the following contents: [ ... ] > + > + 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. It will fail: ... minutes) authentication fails. > + > + > + > + MITand Heimdal interoperate nicely. ^^^ ... and > + 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 ^^^^^^^ is for error messages. > + 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 ^^^^ lifetime > + 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. ^^^^^ lifetime > + > + > + > + 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, Is "..." really needed here? &ellip; > + 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 it is ... > + 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 it is ... > + allows the Kerberos server to verify > + the authenticity of each TGT. > + > + > + > + > + <application>Kerberos</application> Tips Time synchronization and ticket lifetimes were discussed in "Troubleshooting". How about one section "Tips and Troubleshooting"? > + > + > + > + > + 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 ^^^^ ... lifetime > + 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 ^^^^^^^^ manual page > + 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 ^^^^^^^ symbolic link > + /usr/share/dict/words might be > + useful. > + > + > + > + > + > + > + Differences with the MIT port > + > + The major differences between the MIT difference > + 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 chown does not seem to be a proper verb. > + 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. &ellip; if it is really needed here. > + > + > + > + > + <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 What is "global" about /tmp? ... in the /tmp directory > + /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 The KDC is a single point of failure It's not only about security: If you loose the master database, everything is lost! > + > + By design, the KDC must be secure as 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 denail-of-service attack. This can > + alleviated with multiple KDCs (a single KDCs > + master and one or more slaves) and with careful implementation > + of secondary or fall-back authentication > + (PAM is excellent for this). > + > + [ ... ] -- Marxpitn