Date: Sat, 27 Nov 2004 20:29:29 +0200 From: Giorgos Keramidas <keramida@freebsd.org> To: Tillman Hodgson <tillman@seekingfire.com> Cc: freebsd-doc@freebsd.org Subject: Re: [RFC] Kerberos5 chapter re-write Message-ID: <20041127182928.GA5316@gothmog.gr> In-Reply-To: <20041125215448.GA703@gothmog.gr> References: <20041124174258.GA28061@seekingfire.com> <20041125093510.GA4043@orion.daedalusnetworks.priv> <20041125153527.GA36101@seekingfire.com> <20041125215448.GA703@gothmog.gr>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2004-11-25 23:54, Giorgos Keramidas <keramida@ceid.upatras.gr> wrote: >On 2004-11-25 09:35, Tillman Hodgson <tillman@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@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20041127182928.GA5316>