Kerberos5 chapter [was: Your message to freebsd-doc awaits moderator approval]

[Tom Rhodes]

On Sat, 23 Aug 2003 17:23:22 +0200
"Simon L. Nielsen" <simon at 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 at EXAMPLE.PRV's Password:
> +
> +&prompt.user;k5list
> +Credentials cache: FILE:/tmp/krb5cc_500
> +        Principal: tillman at EXAMPLE.PRV
> +
> +  Issued           Expires          Principal
> +Aug 27 15:37:58  Aug 28 01:37:58  krbtgt/EXAMPLE.PRV at EXAMPLE.PRV
> +Aug 27 15:37:58  Aug 28 01:37:58  krbtgt/EXAMPLE.PRV at 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