Date: Wed, 3 Sep 2003 16:13:24 -0400 From: Tom Rhodes <trhodes@FreeBSD.org> To: "Simon L. Nielsen" <simon@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: Kerberos5 chapter [was: Your message to freebsd-doc awaits moderator approval] Message-ID: <20030903161324.390bd217.trhodes@FreeBSD.org> In-Reply-To: <20030823152320.GC391@FreeBSD.org> References: <mailman.0.1061646779.19958.freebsd-doc@freebsd.org> <20030823094817.76e3b847.trhodes@FreeBSD.org> <20030823152320.GC391@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sat, 23 Aug 2003 17:23:22 +0200
"Simon L. Nielsen" <simon@FreeBSD.org> 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.
> + <para>Every &os; release beyond &os;-5.1 includes support
> + only for <application>Kerberos5</application>. Hence
> + <application>Kerberos5</application> 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 <application>KerberosIV</application>. The following
> + information should only apply to
> + <application>Kerberos5</application> in post &os;-5.0
> + releases.</para>
> +
> + <para><application>Kerberos</application> 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.</para>
> +
> + <para><application>Kerberos</application> can be described as an
> + identity-verifying proxy system. It can also be described as a
> + trusted third-party authentication system.</para>
> +
> + <para>Note that <application>Kerberos</application> provides only
> + authentication services and nothing more. Therefore it is highly
> + recommended that <application>Kerberos</application> be used with
> + other security methods which authorization and audit services.</para>
>
> 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.
>
> + <para>The following instructions can be used as a guide on how to set
> + up <application>Kerberos</application> as distributed for &os;.
> + However, you should refer to the relevant manual pages for a complete
> + description.</para>
> +
> + <para>For purposes of demonstrating a <application>Kerberos</application>
> + installation, the various namespaceswill be handled as follows:</para>
> +
> + <itemizedList>
> + <listitem>
> + <para>The DNS domain (<quote>zone</quote>) will be example.prv.</para>
>
> Perhaps 'example.prv' should be marked up with <hostid
> role="domainname"> ?
Martin recommended changing it to example, do you think a role would
or should still be applicable?
>
> + </listitem>
> +
> + <listitem>
> + <para>The <application>Kerberos</application> realm will be
> + EXAMPLE.PRV.</para>
> + </listitem>
> + </itemizedList>
> +
> + <para>Please refrain from the use of these namespaces in the real
> + world. Not only will it not be optimal for your network and
> + <acronym>DNS</acronym> server, it will make interoperating with other
> + <application>Kerberos</application> realms more difficult.</para>
> +
> + <sect2>
> + <title>Background: History</title>
> +
> + <para><application>Kerberos</application> was created by
> + <acronym>MIT</acronym> as a solution to network security problems.
> + The <application>Kerberos</application> protocol uses strong
> + cryptography so that a client can prove its identity to a server
> + (and vice versa) across an insecure network connection.</para>
> +
> + <para><application>Kerberos</application> 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
> + <application>Kerberos</application> to prove their identity, they
> + can also encrypt all of their communications to assure privacy
> + and data integrity as they go about their business.</para>
> +
> + <para><application>Kerberos</application> is both the name of a
> + network authentication protocol and an adjective to describe
> + programs that implement the program
> + (<application>Kerberos</application> telnet, for example). The
> + current version of the protocol is version 5, described in
> + <acronym>RFC</acronym> 1510. <application>Kerberos</application>
> + was designed to provide strong authentication for client/server
> + applications (such as traditional Internet services like
> + <acronym>FTP</acronym> and telnet) by using secret-key
> + cryptography.</para>
> +
> + <para>Several free implementations of this protocol are available,
> + covering a wide range of operating systems. The Massachusetts
> + Institute of Technology, where <application>Kerberos</application>
> Perhaps insert ^ "(<acronym>MIT</acronym>)"
>
> I think it's a good idea to introduce acronyms, so there is no doubt what
> is meant when using them later.
>
> +
> + <programlisting>[libdefaults]
> + default_realm = EXAMPLE.PRV
> +[realms]
> + EXAMPLE.PRV = {
> + kdc = <application>Kerberos</application>.example.prv
> + }
> +[domain_realm]
> + .example.prv = EXAMPLE.PRV</programlisting>
> +
> + <para>Note that this <filename>/etc/krb5.conf</filename> file implies
> + that your <acronym>KDC</acronym> will have the fully-qualified
> + hostname of <hostid>Kerberos.example.prv</hostid>. You will need
>
> For <hostid> 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 <acronym>KDC</acronym> has a different hostname.</para>
> +
> + <para>Next we will create the <application>Kerberos</application>
> + 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
> + (<filename>/var/heimdal/m-key</filename>). To create the master
> + key, run <command>kstash</command> and enter a password.</para>
> +
> + <para>Once the master key has been created, you can initialize the
> + database using the <command>kadmin</command> 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).
>
> + <command>-l</command> option (standing for <quote>local</quote>).
>
> <paramenter>-l</parameter> ?
I used literal as Martin suggested.
>
> + This option instructs <command>kadmin</command> to modify the
> + database files directly rather than going through the
> + <command>kadmind</command> network service. This handles the
> + chicken-and-egg problem of trying to connect to the database
> + before it is created. Once you have the <literal>kadmin></literal>
> Typo:
^
Good catch!
>
> + prompt, use the <command>init</command> command to create your
> + realms initial database.</para>
> +
> + <para>Lastly, while still in <command>kadmin</command>, create your
> + first principal using the <command>add</command> command. Stick
> + to the defaults options for the principal for now, you can always
> + change them later with the <command>modify</command> command.
> + Note that you can use the <command>?</command> command at any
> + prompt to see the available options are.</para>
> +
> + <para>A sample database creation session is shown below:</para>
>
> How about marking up all occurrences of tillman with <replaceable> ?
>
> I haven't tried it; it might look silly, I'm not really sure...
Thats a thought. Done.
>
> +
> + <programlisting>&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</programlisting>
> +
> + <para>Now it's time to start up the <acronym>KDC</acronym> services.
> + Run <command>/etc/rc.d/Kerberos start</command> and
> Typo ? ^
>
Yes it is, or was.
> + <command>/etc/rc.d/kadmind start</command> 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
> + <acronym>KDC</acronym> is functioning by obtaining and listing a
> + ticket for the principal (user) that you just created from the
> + command-line of the <acronym>KDC</acronym> itself:</para>
> +
> + <programlisting>&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)</programlisting>
> +
> + </sect2>
> +
> + <sect2>
> + <title><application>Kerberos</application> enabling a server with
> + Heimdal services</title>
> +
> + <para>First, we need a copy of the <application>Kerberos</application>
> + configuration file, <filename>/etc/krb5.conf</filename>. To do
> + so, simply copy it over to the client computer from the
> + <acronym>KDC</acronym> in a secure fashion (using the network,
> + such as <command>scp</command>, or physically via a
>
> &man.scp.1; ?
>
> + floppy).</para>
> +
> + <para>Next you need a <filename>/etc/krb5.keytab</filename> file.
> + This is the major difference between a server provide
> + <application>Kerberos</application> enabled daemons and a
> + workstation -- the server must have a keytab file. This file
> + contains the servers host key, which allows it and the
> + <acronym>KDC</acronym> 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 <acronym>FTP</acronym>, is a very bad idea.</para>
> +
> + <para>Typically, you transfer to the keytab to the server using the
> + <command>kadmin</command> program. This is handy because you also
> + need to create the host principal (the <acronym>KDC</acronym> end
> + of the <filename>krb5.keytab</filename>) using
> + <command>kadmin</command>.</para>
> +
> + <para>Note that you must have already obtained a ticket and that this
> + ticket must be allowed to use the <command>kadmin</command>
> + interface in the <filename>kadmind.acl</filename>. See the section
> + titled <quote>Remote administration</quote> in the Heimdal info
> + pages (<command>info heimdal</command>) for details on designing
> + access control lists. If you do not want to enable remote
> + <command>kadmin</command> access, you can simply securely connect
> + to the <acronym>KDC</acronym> (via local console,
> + <command>ssh</command> or <application>Kerberos</application>
>
> &man.ssh.1; ?
>
> + <command>telnet</command>) and perform administration locally
>
> &man.telnet.1; ?
>
> + <para>At this point your server can communicate with the
> + <acronym>KDC</acronym> (due to it's <filename>krb5.conf</filename>
> + file) and it can prove it's own identity (due to the
> + <filename>krb5.keytab</filename> file). It's now ready for
> + you to enable some <application>Kerberos</application> services.
> + For this example we will enable the <command>telnet</command>
> + service by putting a line like this into your
> + <filename>/etc/inetd.conf</filename> and then restarting the
> + <command>inetd</command> service with
>
> &man.inetd.1; ?
You mean &man.inetd.8; right. :)
>
> + <command>/etc/rc.d inetd restart</command>:</para>
> ^
> Missing /
Added
> + <para>When testing an application like <command>telnet</command>,
> + try using a packet sniffer (such as <command>tcpdump</command>)
>
> &man.tcpdump.1;
>
> + to confirm that your password is not sent in the clear. Try
> + using <command>telnet</command> with the <command>-x</command>
> ^^
> <parameter>-x</parameter>
I'm using <literal> here. :)
>
> + option, which encrypts the entire data stream (similar to
> + <command>ssh</command>).</para>
> +
> + <para>The core <application>Kerberos</application> client applications
> + (traditionally named <command>kinit</command>,
> + <command>klist</command>, <command>kdestroy</command> and
> + <command>kpasswd</command>) are installed in
>
> Manual page references for the above commands?
At this point we should have used enough references for everything.
> +
> + <para>Were to be placed into the home directory of the local user
> + <username>webdevelopers</username> then both principals listed
> + would have access to that account without requiring a shared
> + password.</para>
> +
> + <para>Reading the man pages for these commands is recommended.
> + Note that the <command>ksu</command> 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...
>
> + <filename>.k5users</filename>.</para>
> +
> + </sect2>
> +
> + <sect2>
> + <title>Troubleshooting</title>
> +
> + <itemizedlist>
> + <listitem>
> + <para>When using either the Heimdal or <acronym>MIT</acronym>
> + <application>Kerberos</application> ports ensure that your
> + <literal>PATH</literal> environment variable lists the
>
> I think this should be <envar>PATH</envar>
>
> +
> + <listitem>
> + <para>If you change your hostname, you also need to change your
> + <username>host/</username> principal and update your keytab.
> + This also applies to special keytab entries like the
> + <username>www/</username> principal used for Apache's
> + <application>mod_auth_kerb</application>.</para>
>
> Perhaps a reference to the port www/mod_auth_kerb ?
Replaced application with filename role="package" tag(s)
> + <listitem>
> + <para>With <acronym>MIT</acronym>
> + <application>Kerberos</application>, if you want to allow a
> + principal to have a ticket life longer than the default ten
> + hours, you must use <command>modify_prinicpal</command> in
> + <command>kadmin</command> to change the maxlife of both the
> + principal in question and the <username>krbtgt</username>
> + principal. Then the principal can use the
> + <option>-l</option> option with <command>kinit</command>
>
> Hmm, here you use <option>... I don't really know when to use <option>
> and when to use <parameter> (which I suggested earlier). Perhaps you
> should also use <option> where I suggested <parameter>.
I used literal yet again.
>
> + to request a ticket with a longer life.</para>
> + </listitem>
> + </itemizedlist>
> +
> + <para>Note: If you run a packet sniffer on your
> + <acronym>KDC</acronym> to add in troubleshooting and then run
> + <command>kinit</command> from a workstation, you will notice
> + that your <acronym>TGT</acronym> is sent immediately upon
>
> Hmm, I don't remeber TGT being mentioned before?
>
> +
> + <listitem>
> + <para>You have to keep the time in sync between all the
> + computers in your realm. <acronym>NTP</acronym> is
> + perfect for this.</para>
> + </listitem>
>
> Perhaps a reference to section 19.11 which describes NTP.
>
> +
> + <sect2>
> + <title>Differences with the MIT port</title>
>
> <acronym> around MIT here?
Not a bad idea. :)
> +
> + <para>This can be overcome with the <command>-c</command>
>
> <option> or <parameter> for -c IMO.
>
> + filename command-line option or (preferably) the
> + <literal>KRB5CCNAME</literal> environment variable, but this
>
> <envar>KRB5CCNAME</envar>
>
> [END/no more comments]
>
> Use at will..
Used at will my friend. :)
--
Tom Rhodes
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030903161324.390bd217.trhodes>