[Review Request: Kerberos5] handbook security chapter review

[Martin Heinen]

On Sun, Aug 24, 2003 at 01:44:47PM -0600, Tillman Hodgson wrote:
> On Sun, Aug 24, 2003 at 01:11:44PM +0200, Martin Heinen wrote:
> > On Sat, Aug 23, 2003 at 09:27:54AM -0400, Tom Rhodes wrote:

> > The introduction should also explain the common
> > Kerberos buzzwords (e.g. tickets, principals).
> 
> Would reference to an outside reference (the MIT glossary, for example)
> work?

The text should at least explain the terms which are
used later on.  That a principal could be something
other than a normal user (a service) is not obvious.

Simon, in his review, noticed the "sudden" appearance
of the term TGT.  If the reader knows what a ticket
granting ticket is, he probably already knows how to
set up Kerberos.  Forcing the reader into a search engine
is not a good idea.

For further details we could reference the reader
to the original documentation.

> I could also incorporate the glossary I wrote for ROSPA (pages 16 and 17
> of http://www.rospa.ca/projects/kerberos/Heimdal_Kerberos.pdf). It's
> probably too wordy though.

Thinking of references, we might want to
add Brian Tung's Kerberos book to the bibliography:

http://www.awprofessional.com/catalog/product.asp?product_id={B2EC5D6E-D38A-4C96-BEB1-9EECCAB7D36D}

> >   <note>
> >     <para>Please use real domain names when setting up
> >       <application>Kerberos</application>.  This avoids
> >       <acronym>DNS</acronym> problems and assures
> >       interoperation with other <application>Kerberos</application>
> >       realms.</para>
> >   </note>
> 
> I'd add:
> 
> "... when setting up <application>Kerberos</application> even if you
> intend to run it internally."

Good point.

> > > +    <para>In order to reach the widest audience, these instructions assume
> > > +	the use of the Heimdal distribution included in &os;.</para>
> 
> <snip>
> 
> > This section tells nothing new and should be removed.
> 
> I think it's important to note that we're using the Heimdal in the base
> OS. MIT is more common by far in North America and the base Heimdal
> doesn't include all the applications and daemons that the full Heimdal
> package does.
> 
> I would install a Kerberos system differently if I wasn't using the base
> Heimdal, for example.

I only meant to remove the section "KerberosIV and Kerberos 5".
That Kerberos IV has been dropped was already mentioned in
the introduction.  If it is important to mention eBones and
Heimdal we could do that in the first paragraphs too.

> > > +    <programlisting>Kerberos5_server_enable="YES"
> > > +kadmind5_server_enable="YES"
> > > +Kerberos_stash="YES"</programlisting>
> > 
> > Don't know exactly:
> > 
> >   ... kerberos5_server_enable="YES"
> > 
> > CURRENT does not have "Kerberos_stash" in /etc/defaults/rc.conf.
> 
> That's true. I think it's a leftover in my conversion of
> the document from -STABLE to -CURRENT. It's not needed in -CURRENT.

Aah, I only checked -CURRENT, we should add a note
for -CURRENT then (the Handbook covers both -CURRENT
and -STABLE).

> >   "keytab" and all further instances should probably be
> >   marked up with <filename>keytab</filename>.
> 
> Definitely for isntances of /etc/krb5.keytab. I was using "keytab" in
> it's generic sense here ... does that still qualify for <filename>
> treatment?
> 
> I think there is a need for a generic term. For example, on the ROSPA
> web server there is also a keytab in /usr/local/etc/apache/ (for use
> with mod_auth_kerb). Several other daemons also liek their own keytab
> and special keytabs are commonly used for Kerberos authenticated cron
> jobs.

If "keytab" references to file containing keys,
we should write <filename>keytab</filename>.  In the
handbook "supfile" is used in this way.

> > Instead of stating what not to do, it is better to
> > explain how to transfer the file in a secure fashion
> > (scp, floppy).
> 
> Can we reuse the wording from the krb5.conf section?

ok.

> > > +	  <command>telnetd</command> man page for more details.</para>
> >           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >   &man.telnetd.8;
> 
> 
> Oh, that's how that's done. Neat.

I love this one too.
It's described in the Documentation Project Primer
http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html
which has a lot of other cool stuff :-)

> > > +	  <listitem>
> > > +	    <para>Is your time in sync? Are you sure? If the time is not in
> > > +	      sync (typically within five minutes) authentication often
> > > +	      fails.</para>
> > 
> > It will fail:
> >   ... minutes) authentication fails.</para>
> 
> Is it worth adding that the number of minutes of "drift" that is allowed
> can be controlled by the krb5.conf "clockskew" setting?

No, I don't think so.  The chapter should not deal
with Kerberos in detail, it should be just a
"Getting Started".  Describing all details duplicates
existing (external) documentation.

> > Time synchronization and ticket lifetimes were discussed
> > in "Troubleshooting".  How about one section "Tips and
> > Troubleshooting"?
> 
> I'm not positive that those sections overlap nicely.
> 
> For example, if authentication fails discovering that clockskew can
> cause that is troubleshooting. Recommending that NTP be used to prevent
> that isn't.
> 
> It coudl be made to work if all the tips were worded such that expressed
> the negative ("long ticket lifetimes don't work", etc), but that might
> be awkward.

Indeed, that sounds strange.  If the sections do not duplicate
information, I'm fine with them.

-- 
Marxpitn