[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>
118:
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>
158:
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>
625:
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