[RFC] Kerberos5 chapter re-write

Giorgos Keramidas keramida at freebsd.org
Sat Nov 27 18:39:46 UTC 2004

On 2004-11-25 23:54, Giorgos Keramidas <keramida at ceid.upatras.gr> wrote:
>On 2004-11-25 09:35, Tillman Hodgson <tillman at seekingfire.com> wrote:
>>On Thu, Nov 25, 2004 at 11:35:10AM +0200, Giorgos Keramidas wrote:
>>>On 2004-11-24 11:42, Tillman Hodgson <tillman at seekingfire.com> wrote:
>>>> For the impatient:
>>>> =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
>>>> The patch is at http://www.seekingfire.com/patches/kerberos5.patch
>>> The version I am working on can be found at:
>>> http://people.freebsd.org/~keramida/tillman-kerberos5.patch
>> I've pulled a copy of that down and started to hand-compare it to the
>> original I had to see if I could pick up on areas where I had
>> technical docbook problems.
> Don't worry too much about this.  I can send you a commented version of
> the patch you have at: http://www.seekingfire.com/patches/kerberos5.patch

Here's the commented version I was working on.  See if you like any of
the suggested changes.  The line numbers refer to the version I found at
26 Nov 2004 22:00 UTC at http://www.seekingfire.com/patches/kerberos5.patch
All my suggestions are on lines that start with '%'.

  25: +      Services such as remote login, remote copy, secure inter-system
  26: +      file copying and other high-risk tasks are made considerably
  27: +      safer (through encryption and identity verification) and more
  28: +      controllable.</para>

The "high-risk" part is a bit of an exaggeration.  "other tasks that
depend on the identity of a user or client program" is probably better.

  53:        identity-verifying proxy system.  It can also be described as a
  54:        trusted third-party authentication system.
  65: +      <application>Kerberos</application> provides only one function
  66: +      — the secure authentication of users on the network.  It

It is probably a good idea to avoid whitespace around — entities.
Having whitespace around long dashes is probably going to bite us when
the text happens to wrap immediately *before* the dash, resulting in
text like this:

%       Kerberos provides only one function
%       -- the secure authentication of users
%       on the network.

This doesn't look too good.  One way to avoid it is to precede every
— with a non-breaking space (an   entity) instead of plain
whitespace.  Another is to entirely avoid whitespace around em-dashes.

Moreover, I would probably replace the em-dash with a colon here, aiming
at something like this:

%       Kerberos provides only one function:
%       the secure authentication of users
%       on the network.

  84: +    <para>The following instructions can be used as a guide on how to
  85: +      set up <application>Kerberos</application> as distributed for
  86: +      &os;.  However, you should refer to the relevant manual pages
  87: +      for a complete description.</para>

"However... ...description" is almost ok.  We could always reword it a
bit to look even better though.  I'd go for something like this:

%       The following instructions can be used as a guide on how to set
%       up `Kerberos' as distributed with FreeBSD releases.  Note that
%       this is not a complete and detailed guide of all the options or
%       all the functionality provided by Kerberos though.  Whenever
%       you need to find out these details, please consult the relevant
%       manual pages.

I initially had an even shorter version of this:

%       The following instructions can be used as a guide on how to set
%       up Kerberos as distributed for FreeBSD.  You should also refer
%       to the relevant manual pages, as needed, for a complete
%       description of all the details.

  89: +    <para>For purposes of demonstrating a
  90: +      <application>Kerberos</application> installation, the various
  91: +      name spaces will be handled as follows:</para>

  The `example.org' domain should be wrapped in <hostid> tags right
  after these lines.  The Kerberos realm EXAMPLE.ORG needs <literal>
  tags too.  These were not affected by your diff, Tillman.  I just
  noticed them while skimming through the original chapter.

 112: +      <title>Setting up <application>Kerberos</application></title>

<application> tags look horrible in tables of contents.  They render as
bold in most CSS-aware browsers and really hurt the eyes of the reader,
standing out as they do from the rest of the text.

In general, I try to avoid <application> tags in titles.  This is not a
hard rule of the Doc Project IIRC; just a personal style note.

 117:        </indexterm>
 152: +      <sect3>

This is one of the places where a section title is immediately followed
by a subsection.  The rendered HTML output looks as if there's something
`missing' in between.  I tried to add short paragraphs in lieu of
"Synopsis" sections in such places.  Near line 152 of the diff, I added
the following description of the section contents:

%       <para>This section describes the configuration of
%         <application>Kerberos</application>, the setup of related
%         network services and minimal examples of configuration files
%         used by <application>Kerberos</application>-enabled
%         software.</para>
%       <para>After reading this section you will know:</para>
%       <itemizedlist>
%         <listitem>
%           <para>What services are related to
%             <application>Kerberos</application> and how to configure
%             them for your Kerberos realm.</para>
%         </listitem>
%         <listitem>
%           <para>How to set up a Key Distribution Center.</para>
%         </listitem>
%         <listitem>
%           <para>How to set up the Kerberos administrative
%             service.</para>
%         </listitem>
%         <listitem>
%           <para>How to enable Kerberos on the server side of
%             the available services.</para>
%         </listitem>
%         <listitem>
%           <para>How to enable Kerberos on the client side of
%             the available services.</para>
%         </listitem>
%       </itemizedlist>

 153: +       title>Setting up related services</title>
 154: +       <indexterm>
 155: +      <primary>Kerberos5</primary>
 156: +      <secondary>Setting up related services</secondary>
 157: +       </indexterm>
 161: +       <sect4>
 162: +         <title>Configuring NTP for
 163: +           <application>Kerberos</application></title>

This looks a bit like the following section too, i.e. `empty' when the
document is rendered to HTML.  The `missing stuff' feeling can be
avoided by inserting a short description of the section contents as
introductory section material:

%       <para><application>Kerberos</application> can be used in
%         conjunction with many of the services provided by a &os;
%         host.  Practically, all services that use PAM for
%         authentication can be configured to use
%         <application>Kerberos</application>-based authentication,
%         accounting or password management through
%         &man.pam.krb5.8;.</para>
%       <para>This section does not attempt to list all the possible
%         ways in which <application>Kerberos</application> support
%         can be configured for available services.</para>
%       <para>After reading this section you will know how and why you
%         should configure services that are either directly used by
%         Kerberos, or are essential for the correct and safe
%         operation of Kerberos.  These are:</para>
%       <itemizedlist>
%         <listitem>
%           <para>NTP: the Network Time Protocol.</para>
%         </listitem>
%         <listitem>
%           <para>DNS: the Domain Name Service.</para>
%         </listitem>
%       </itemizedlist>

Then the NTP subsection can immediately begin :-)

 177: +         <para>See <xref linkend="network-ntp"> for details about
 178: +           setting up NTP synchronization of your system clock.
 179: +           </para>

Please, please don't do that.  When a <para>, <screen>, <programlisting>
ends, delete any whitespace between the text and the closing tag,
letting the final tag `cuddle to the text' as below:

%              <para>See <xref linkend="network-ntp"> for details about
%                setting up NTP synchronization of your system clock.</para>

Note that there are several many instances of this minor stylistic bug
in the original kerberos5.patch.

 191: +         <para>Kerberos configurable can be made more simple by
 192: +           having the important global configuration information
 193: +           served through the <acronym>DNS</acronym> service.

In line 191: configurable = configuration, right?

 232: +         <para>The SRV record shown assumes that you have a host
 233: +           named <hostid role="fqdn">kerberos.example.org</hostid>
 234: +           acting as your <acronym>KDC</acronym>.  If that is not the
 235: +           case, you should create a CNAME to point the <hostid
 236: +           role="fqdn">kerberos.example.org</hostid> record to the

I'd wrap CNAME in <literal> tags, since it's a literal excerpt from the
configuration of BIND.  Another minor point here is that some times it's
better to wrap lines prematurely, to avoid opening a tag in one line
and writing the rest of the attributes in a second line.  I would
probably move the opening <hostid part of line 235 one line down and
write the entire <hostid>...</hostid> on a single line if possible.

This is not strictly necessary.  It's not even helpful at all, if one is
used at hitting ESC-q in Emacs (as I am).  IMHO, it does look a bit
better when reading the SGML source though and it will certainly save a
bit of space when the <hostid> tag is replaced with something else.
Only one line will have to be touched :-)

 258: +         <application>Kerberos</application> provides — it is
 259: +         the computer that issues <application>Kerberos</application>
 260: +         tickets.

em-dash whitespace in line 258.

 274: +         <para>To begin setting up a <acronym>KDC</acronym>, ensure
 275: +           that your <filename>/etc/rc.conf</filename> file contains
 276: +           the correct settings to act as a <acronym>KDC</acronym>:
 277: +           </para>

Here a </para> is in a line of its own.

 296: -      <para>Next we will set up your <application>Kerberos</application>
 297: -       config file, <filename>/etc/krb5.conf</filename>:</para>
 298: +         <para>Next we will set up your
 299: +           <application>Kerberos</application> config file,
 300: +           <filename>/etc/krb5.conf</filename>:</para>

The times a paragraph starts with "Next we will" are far too many to
mention them all.  There are many ways to start a new paragraph,
especially if it also happens to be the first part of a new section.

I know that many of these "Next" instances were in the original,
unpatched by Tillman, text.  We'll still have to fix them.

 345: +         <note>
 346: +           <para>For clients to be able to find the
 347: +             <application>Kerberos</application> services, you
 348: +             <emphasis>must</emphasis> have either a fully configured
 349: +             <filename>/etc/krb5.conf</filename> or a minimally
 350: +             configured <filename>/etc/krb5.conf</filename>
 351: +             <emphasis>and</emphasis> a properly configured DNS
 352: +             server.</para>
 353: +         </note>

This paragraph begs to be converted to a list of alternatives:

%               <note>
%                 <para>Clients that depend on
%                   <application>Kerberos</application> services will
%                   need one of the following, in order to function
%                   correctly as part of a
%                   <application>Kerberos</application> realm:</para>
%                 <itemizedlist>
%                   <listitem>
%                     <para>a fully configured <filename>/etc/krb5.conf</filename></para>
%                   </listitem>
%                   <listitem>
%                     <para>a minimal <filename>/etc/krb5.conf</filename>
%                       <emphasis>and</emphasis> a properly configured
%                       DNS server</para>
%                   </listitem>
%                 </itemizedlist>
%               </note>

 364: +       <sect4>
 365: +         <title>Configuring the initial
 366: +           <application>Kerberos</application> database</title>
 396: +         <para>Next we will create the
 397: +           <application>Kerberos</application> database.

Here's another one of the numerous "next" steps I previously (sic)
mentioned :-)

 401: +           (<filename>/var/heimdal/m-key</filename>).  To create the
 402: +           master key, run <command>kstash</command> and enter a
 403: +           password.</para>

Use &man.kstash.8; here, but make sure the manpage entity is added in
doc/share/sgml/man-refs.ent too, otherwise the build of the Handbook
will break.

 405: +         <para>Once the master key has been created, you can
 406: +           initialize the database using the
 407: +           <command>kadmin</command> program with the
 408: +           <literal>-l</literal> option (standing for
 409: +           <quote>local</quote>).  This option instructs
 410: +           <command>kadmin</command> to modify the database files
 411: +           directly rather than going through the
 412: +           <command>kadmind</command> network service.  This handles
 413: +           the chicken-and-egg problem of trying to connect to the
 414: +           database before it is created.  Once you have the
 415: +           <command>kadmin</command> prompt, use the
 416: +           <command>init</command> command to create your realms
 417: +           initial database.</para>

All the <command> elements above should be entities, except for the
`-l', `local' and `init' instances.  `kadmin' and `kadmind' should be
replaced with &man.kadmin.8; and &man.kadmind.8; respectively.

 419: +         <para>Lastly, while still in <command>kadmin</command>,

&man.kadmin.8; here too.

 428: -      <para>A sample database creation session is shown below:</para>
 429: +         <para>A sample database creation session is shown below:
 430: +           </para>

Please move back the closing </para> tag, deleting any whitespace
immediately preceding the tag.

 449: +         <para>Now it is time to start up the <acronym>KDC</acronym>
 450: +           services.  Run <command>/etc/rc.d/kerberos start</command>
 451: +           to bring up the services.  Note that you won't have any
 452: +           kerberized daemons running at this point but you should be
 453: +           able to confirm the that the <acronym>KDC</acronym> is
 454: +           functioning by obtaining and listing a ticket for the
 455: +           principal (user) that you just created from the
 456: +           command-line of the <acronym>KDC</acronym> itself:</para>

Expanding a bit on the description of the init script is probably ok.
Here's a first attempt at replacing the above paragraph with a couple of
more verbose ones and a user-friendly <screen> sample of running the
kerberos rc.d script:

%         <para>Now it is time to start up the <acronym>KDC</acronym>
%           services.  The canonical way of starting
%           <application>Kerberos</application> in &os; 5.X or later
%           is through the <filename>kerberos</filename> startup
%           script:</para>
%         <screen>&prompt.root; <userinput>/etc/rc.d/kerberos start</userinput></screen>
%         <para>This will bring up all the necessary 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>

 477: +       <para>The <command>kadmind</command> daemon provides remote
 478: +         administrative service for the <acronym>Kerberos</acronym>
 479: +         database.  It's possible that this is not required for your
 480: +         network — for example, you might be more comfortable
 481: +         reducing any potential security risks by performing all
 482: +         database administration at the local console with
 483: +         <command>kadmin -l</command>. If so, you can skip this
 484: +         configuration section.</para>

<command>kadmind</command> -> &man.kadmind.8;

``It's'' is a contraction.  We have to expand it.

Whitespace around — should be cleaned up.

It's probably better to use &man.kadmin.8; in the last sentence and add
an example in a <screen> element if that's deemed necessary.

%     <para>The &man.kadmind.8; daemon provides remote administrative
%       services for the <acronym>Kerberos</acronym> database.  It is
%       possible that this is not required for your network—for
%       example, you might be more comfortable reducing any potential
%       security risks by performing all database administration at the
%       local console with &man.kadmin.8;.  If so, you can skip this
%       configuration section.</para>

 486: +       <para>For remote <command>kadmind</command> access to work,
 487: +         several things must be true: you must have already obtained
 488: +         a ticket, this ticket must be allowed to use the
 489: +         <command>kadmin</command> interface (controlled by the
 490: +         <filename>kadmind.acl</filename> file), and the
 491: +         <command>kadmind</command> remote database administration
 492: +         service must be running and configured.</para>

Some of the <command> elements can be converted to manpage references.
The parenthesized explanation of kadmind.acl can be expanded a bit.
A similar paragraph with these changes incorporated is:

%     <para>For remote &man.kadmind.8; access to work, several things
%       must be true:</para>
%     <itemizedlist>
%       <listitem>
%         <para>The &man.kadmind.8; remote database administration
%           service must be configured and running.</para>
%       </listitem>
%       <listitem>
%         <para>A valid Kerberos ticket has to be obtained.</para>
%       </listitem>
%       <listitem>
%         <para>Access to the database administration service must be
%           allowed for the principal associated with the ticket.
%           See the &man.kadmind.8; manual page for details of setting
%           up the access control list, in the
%           <filename>kadmind.acl</filename> file.</para>
%       </listitem>
%     </itemizedlist>

I've tried to put the requirements of kadmind(8) in a more or less
logical order.  The last item of the <itemizedlist> is what I'd like
you, Tillman, or other people experienced with Kerberos, to review.

I don't use Kerberos and I may have the details a bit wrong :-)

 493: +
 494: +       <sect4>
 495: +         <title>Configuring <filename>/etc/rc.conf</filename></title>
 496: +
 497: +         <para>To configure <command>kadmind</command> to be started
 498: +           upon boot, ensure that your
 499: +           <filename>/etc/rc.conf</filename> file contains the
 500: +           line:</para>
 501: +
 502: +         <programlisting>kadmind5_server_enable="YES"</programlisting>
 503: +        </sect4>

"To configure XXX to be ..." sounds a bit superficial here.  The word
"configure", "configuring", "configuration" should not be appear too
many times in a row, IMHO.  Maybe something like this would be better:

%       <para>The &man.kadmind.8; service can automatically start at
%         boot time.  To enable it, add the following line to your
%         <filename>/etc/rc.conf</filename> file:</para>
%       <programlisting>kadmind5_server_enable="YES"</programlisting>

 505: -      </sect2>
 506: +       <sect4>
 507: +         <title>Configuring kadmind access control lists</title>
 508: +
 509: +         <para>Remote <application>Kerberos</application> database
 510: +           administration requires that some sort of limitations be
 511: +           imposed on principals (or, users) or else any principal
 512: +           could modify the password of any other principal and thus
 513: +           render the authentication service of
 514: +           <application>Kerberos</application> useless. This
 515: +           per-principal limitation function is provided by an access
 516: +           control list (ACL) stored in the file
 517: +           <filename>/var/heimdal/kadmind.acl</filename>.</para>

The "(or, users)" bit on line 511 should probably go away.  Kerberos
calls them `principals'.  That's what we should call them too, IMHO.

 525: +         <para>Designing access control lists is very specific to the
 526: +           needs of your <application>Kerberos</application> realm.
 527: +           User password changes, for example, can be performed over
 528: +           <command>kadmin</command>.  See the section titled
 529: +           <quote>Remote administration</quote> in the Heimdal info
 530: +           pages (<command>info heimdal</command>) for more details
 531: +           on designing access control lists.</para> </sect4>

The <sect4> that closes the chapter needs to be put in a line by itself.
The <command> element that wraps kadmind may be written as a manpage
reference.  The reference to Texinfo pages can also be written as a
<note> below the paragraph, or even as a separate paragraph.  This
eliminates the need to a parenthetical expression in the midst of an
otherwise short and to the point sentence:

%         [...]
%         User password changes, for example, can be preformed over
%         &man.kadmind.8;.  See the section titled <quote>Remote
%         administration</quote> in the Heimdal info pages for more
%         details on the design of access lists.</para>
%       <para>You can read the Heimdal info pages with the
%         &man.info.1; utility:</para>
%       <screen>&prompt.user; <userinput>info heimdal</userinput></screen>

 543: +         <para>Run <command>/etc/rc.d/kadmind start</command> to
 544: +           bring up the remote database administration service.  You
 545: +           should be able to confirm that the
 546: +           <command>kadmind</command> service is running by
 547: +           connecting to the <acronym>KDC</acronym> from a client
 548: +           host using <command>kadmin</command>. Only functions that
 549: +           your principal is allowed to perform should
 550: +           operate.</para>

The bit about the rc.d script can probably expand a bit more, to cover
more details.  The use of "you", "your", "yours" should be avoided, as
it may be considered rude by the reader.  Perhaps something like this is
slightly better?

%     <para>The remote database administration service is automatically
%       started at boot time if the <filename>rc.conf</filename> file
%       sets <quote>kadmind5_server_enable</quote> to
%       <literal>YES</literal>.  The service can also be started by
%       manually running the <command>kadmind</command> startup
%       script:</para>
%     <screen>&prompt.root; <userinput>/etc/rc.d/kadmind start</userinput></screen>
%     <para>After the KDC is brought up without problems, the
%       &man.kadmin.8; utility should be able to connect to the it,
%       confirming that remote administration works.  Normally, only
%       functions that are permitted for the current principal will be
%       available to &man.kadmin.8;.</para>

 555: +      <sect3>
 556: +       <title><application>Kerberos</application> enabling a server
 557: +         with Heimdal services</title>
 558: +       <indexterm>
 559:           <primary>Kerberos5</primary>
 560:           <secondary>Enabling Services</secondary>
 562: +       </indexterm>
 563: +
 564: +       <sect4>
 565: +         <title>Configuring <filename>/etc/krb5.conf</filename>
 566: +           </title>

The closing </title> tag has whitespace before it.

A short introduction to the topics discussed in this section would also
be nice between the <sect3> and <sect4>.  Something like this perhaps?

%             <para>After you have configured
%               <application>Kerberos</application> and started the
%               KDC services, as described in
%               <xref linkend="kdc-start">, you can start using
%               Kerberos authentication for services of the systems
%               that are part of the
%               <application>Kerberos</application> realm.
%               This section describes the configuration options that
%               must be set to enable
%               <application>Kerberos</application> authentication for
%               some of the services commonly provided by &os;.</para>
%             <para>After reading this section you will know:</para>
%             <itemizedlist>
%               <listitem>
%                 <para>How to set up a
%                   <filename>/etc/krb5.conf</filename> file.</para>
%               </listitem>
%               <listitem>
%                 <para>How to set up a
%                   <filename>/etc/krb5.keytab</filename> file.</para>
%               </listitem>
%               <listitem>
%                 <para>How to configure
%                   <filename>inetd.conf</filename> services for
%                   <application>Kerberos authentication.</para>
%               </listitem>
%             </itemizedlist>

 613: +         <para>First, we need a copy of the
 614: +           <application>Kerberos</application> configuration file,
 615: +           <filename>/etc/krb5.conf</filename>.  To do so, simply
 616: +           copy it over to the client computer [...]

"To do so" doesn't look very good to me, but I'll probably think of a
better way to put this paragraph in words later.

 621: +
 622: +       <sect4>
 623: +         <title>Configuring <filename>/etc/krb5.keytab</filename>
 624: +           </title>
 627: +         <para>Next you need a <filename>/etc/krb5.keytab</filename>
 628: +           file.  This is the major difference between a server

"Next" again :-/

 629: +           providing <application>Kerberos</application> enabled
 630: +           daemons and a workstation — the server must have a
 631: +           <filename>keytab</filename> file.  This file contains the
 632: +           servers host key, which allows it and the
 633: +           <acronym>KDC</acronym> to verify each others identity.

What does "it" refer to?

 634: +           It must be transmitted to the server in a secure fashion,
 635: +           as the security of the server can be broken if the key is
 636: +           made public.  This explicitly means that transferring it
 637: +           via a clear text channel, such as <acronym>FTP</acronym>,
 638: +           is a very bad idea.</para>

An attempt to rewrite this paragraph in a manner that is probably less
confusing would be:

%               <para>Every server providing
%                 <application>Kerberos</application> authenticated
%                 services needs a
%                 <filename>/etc/krb5.keytab</filename> file.
%                 This file contains the host key of the server, which
%                 is used by the server and the KDC when they verify
%                 each other's identity.</para>
%               <para>The server host key <emphasis>must</emphasis> be
%                 transferred to the server in a secure fashion.  This
%                 means that transferring the key over a clear text
%                 channel, such as <acronym>FTP</acronym>, is a
%                 <emphasis>very bad</emphasis> idea.</para>

I haven't had the time to review any other parts of the patch yet
(approximately 66% of the original patch is what I still haven't had a
chance to read carefully through).  Since it may take a while, or
other changes may be made before I finish, I'm sending what I have
so far.

It would be very nice if anyone else has already checked the rest of the
diff, or is part-way through the review process.  The proposed changes
Tillman has made are IMHO a step in the right direction :-)

- Giorgos

More information about the freebsd-doc mailing list