From owner-freebsd-doc@FreeBSD.ORG Wed Sep 3 13:49:48 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 CFC4D16A4BF; Wed, 3 Sep 2003 13:49:48 -0700 (PDT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id 4369743FF3; Wed, 3 Sep 2003 13:49:47 -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 h83Knivd006125; Wed, 3 Sep 2003 16:49:44 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Wed, 3 Sep 2003 16:13:24 -0400 From: Tom Rhodes To: "Simon L. Nielsen" Message-Id: <20030903161324.390bd217.trhodes@FreeBSD.org> In-Reply-To: <20030823152320.GC391@FreeBSD.org> References: <20030823094817.76e3b847.trhodes@FreeBSD.org> <20030823152320.GC391@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: 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: Wed, 03 Sep 2003 20:49:49 -0000 On Sat, 23 Aug 2003 17:23:22 +0200 "Simon L. Nielsen" wrote: > 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: > > > > 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 ()? No worries, I think that's been worked out. > + 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). Done... > > + 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. Ok. > > + 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 role="domainname"> ? Martin recommended changing it to example, do you think a role would or should still be applicable? > > + > + > + > + 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. Done. > > + 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. > > + > + [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 > > For the role defaults to 'hostname', so I think role="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 ? I used literal as Martin suggested. > > + 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: ^ Good catch! > > + 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... Thats a thought. Done. > > + > + &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 ? ^ > Yes it is, or was. > + /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; ? > > + 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; ? You mean &man.inetd.8; right. :) > > + /etc/rc.d inetd restart: > ^ > Missing / Added > + 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 I'm using here. :) > > + 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? At this point we should have used enough references for everything. > + > + 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? Hmmm, I don't seem to have one either. Strange... > > + .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 > > + > + > + 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 ? Replaced application with filename role="package" tag(s) > + > + 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? > > + > + > + 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. > > + > + > + Differences with the MIT port > > around MIT here? Not a bad idea. :) > + > + This can be overcome with the -c > >