source: postlfs/security/mitkrb.xml@ b15e2b7

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY mitkrb-download-http "http://web.mit.edu/kerberos/www/dist/krb5/1.10/krb5-&mitkrb-version;-signed.tar">
  <!ENTITY mitkrb-download-ftp " ">
  <!ENTITY mitkrb-md5sum "0b2c8366468f74c6bb8e11a5417645c1">
  <!ENTITY mitkrb-size "10 MB">
  <!ENTITY mitkrb-buildsize "100 MB">
  <!ENTITY mitkrb-time "1.0 SBU">
]>

<sect1 id="mitkrb" xreflabel="MIT Kerberos V5-&mitkrb-version;">
  <?dbhtml filename="mitkrb.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>MIT Kerberos V5-&mitkrb-version;</title>

  <indexterm zone="mitkrb">
    <primary sortas="a-MIT-Kerberos">MIT Kerberos V5</primary>
  </indexterm>

    <sect2 role="package">
      <title>Introduction to MIT Kerberos V5</title>

    <para><application>MIT Kerberos V5</application> is a free implementation
    of Kerberos 5. Kerberos is a network authentication protocol. It
    centralizes the authentication database and uses kerberized
    applications to work with servers or services that support Kerberos
    allowing single logins and encrypted communication over internal
    networks or the Internet.</para>

    &lfs70_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&mitkrb-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&mitkrb-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &mitkrb-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &mitkrb-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &mitkrb-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &mitkrb-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">MIT Kerberos V5 Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="keyutils"/>,
    <xref linkend="openldap"/>, and
    <xref linkend="dejagnu"/> (required to run the test suite)</para>

    <note>
      <para>Some sort of time synchronization facility on your system (like
      <xref linkend="ntp"/>) is required since Kerberos won't authenticate if
      there is a time difference between a kerberized client and the
      KDC server.</para>
    </note>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/mitkrb"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of MIT Kerberos V5</title>

    <para><application>MIT Kerberos V5</application> is distributed in a
    TAR file containing a compressed TAR package and a detached PGP
    <filename class="extension">ASC</filename> file. You'll need to unpack
    the distribution tar file, then unpack the compressed tar file before
    starting the build.</para>

    <para>After unpacking the distribution tarball and if you have
    <xref linkend="gnupg"/> installed, you can
    authenticate the package with the following command:</para>

<screen><userinput>gpg - -verify krb5-&mitkrb-version;.tar.gz.asc</userinput></screen>

    <para>Build <application>MIT Kerberos V5</application> by running the
    following commands:</para>

<screen><userinput>cd src &amp;&amp;
./configure CPPFLAGS="-I/usr/include/et -I/usr/include/ss" \
            --prefix=/usr \
            --localstatedir=/var/lib \
            --with-system-et \
            --with-system-ss \
            --enable-dns-for-realm &amp;&amp;
make</userinput></screen>

    <para>The regression test suite is designed to be run after the
    installation has been completed.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;

mv -v /usr/bin/ksu /bin &amp;&amp;
chmod -v 755 /bin/ksu &amp;&amp;
mv -v /usr/lib/libkrb5.so.3* /lib &amp;&amp;
mv -v /usr/lib/libk5crypto.so.3* /lib &amp;&amp;
mv -v /usr/lib/libkrb5support.so.0* /lib &amp;&amp;

ln -v -sf ../../lib/libkrb5.so.3.3 /usr/lib/libkrb5.so &amp;&amp;
ln -v -sf ../../lib/libk5crypto.so.3.1 /usr/lib/libk5crypto.so &amp;&amp;
ln -v -sf ../../lib/libkrb5support.so.0.1 /usr/lib/libkrb5support.so &amp;&amp;

install -m644 -v ../doc/*.info /usr/share/info &amp;&amp;
for INFOFILE in 5-admin 5-install 5-user; do
    install-info --info-dir=/usr/share/info \
                 /usr/share/info/krb$INFOFILE.info
    rm ../doc/krb$INFOFILE.info
done &amp;&amp;

install -m755 -v -d /usr/share/doc/krb5-&mitkrb-version; &amp;&amp;
cp -Rv ../doc/* /usr/share/doc/krb5-&mitkrb-version;</userinput></screen>

    <!--
    <para>If <application>CrackLib</application> is installed, or if any
    word list has been put in
    <filename class='directory'>/usr/share/dict</filename>, the following
    should be entered as the <systemitem class="username">root</systemitem>
    user:</para>

<screen role="root"><userinput>ln -s /usr/share/dict/words /var/lib/krb5kdc/kadmin.dict</userinput></screen>
    -->

<!-- Remove this for now as portmap cannot be built until upstream fixes it

    <para>To test the installation, you must have
    <xref linkend="dejagnu"/> installed and issue: <command>make
    check</command>. The RPC layer tests will require a portmap daemon
    (see <xref linkend="portmap"/>) running and configured to listen on the
    regular network interface (not localhost). See the <quote>Testing the
    Build</quote> section of the <filename>krb5-install.html</filename> file
    in the <filename class='directory'>../doc</filename> directory for complete
    information on running the regression tests.</para>
-->
  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>--enable-dns-for-realm</parameter>: This parameter allows
    realms to be resolved using the DNS server.</para>

    <para><parameter>--with-system-et</parameter>: This parameter causes the
    build to use the system-installed versions of the error-table support
    software.</para>

    <para><parameter>--with-system-ss</parameter>: This parameter causes the
    build to use the system-installed versions of the subsystem command-line
    interface software.</para>

    <para><parameter>--localstatedir=/var/lib</parameter>: This parameter is
    used so that the Kerberos variable run-time data is located in
    <filename class='directory'>/var/lib</filename> instead of
    <filename class='directory'>/usr/var</filename>.</para>

    <para><command>mv -v /usr/bin/ksu /bin</command>: Moves the
    <command>ksu</command> program to the
    <filename class="directory">/bin</filename> directory so that it is
    available when the <filename class="directory">/usr</filename>
    filesystem is not mounted.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring MIT Kerberos V5</title>

    <sect3 id="krb5-config">
      <title>Config Files</title>

      <para><filename>/etc/krb5.conf</filename> and
      <filename>/var/lib/krb5kdc/kdc.conf</filename></para>

      <indexterm zone="mitkrb krb5-config">
        <primary sortas="e-etc-krb5.conf">/etc/krb5.conf</primary>
      </indexterm>

      <indexterm zone="mitkrb krb5-config">
        <primary sortas="e-var-lib-krb5kdc-kdc.conf">/var/lib/krb5kdc/kdc.conf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <sect4>
        <title>Kerberos Configuration</title>

        <tip>
          <para>You should consider installing some sort of password checking
          dictionary so that you can configure the installation to only
          accept strong passwords. A suitable dictionary to use is shown in
          the <xref linkend="cracklib"/> instructions. Note that only one
          file can be used, but you can concatenate many files into one. The
          configuration file shown below assumes you have installed a
          dictionary to <filename>/usr/share/dict/words</filename>.</para>
        </tip>

        <para>Create the Kerberos configuration file with the following
        commands issued by the <systemitem class="username">root</systemitem>
        user:</para>

<screen role="root"><userinput>cat &gt; /etc/krb5.conf &lt;&lt; "EOF"
<literal># Begin /etc/krb5.conf

[libdefaults]
    default_realm = <replaceable>&lt;LFS.ORG&gt;</replaceable>
    encrypt = true

[realms]
    <replaceable>&lt;LFS.ORG&gt;</replaceable> = {
        kdc = <replaceable>&lt;belgarath.lfs.org&gt;</replaceable>
        admin_server = <replaceable>&lt;belgarath.lfs.org&gt;</replaceable>
        dict_file = /usr/share/dict/words
    }

[domain_realm]
    .<replaceable>&lt;lfs.org&gt;</replaceable> = <replaceable>&lt;LFS.ORG&gt;</replaceable>

[logging]
    kdc = SYSLOG[:INFO[:AUTH]]
    admin_server = SYSLOG[INFO[:AUTH]]
    default = SYSLOG[[:SYS]]

# End /etc/krb5.conf</literal>
EOF</userinput></screen>

        <para>You will need to substitute your domain and proper hostname
        for the occurrences of the <replaceable>&lt;belgarath&gt;</replaceable> and
        <replaceable>&lt;lfs.org&gt;</replaceable> names.</para>

        <para><option>default_realm</option> should be the name of your
        domain changed to ALL CAPS. This isn't required, but both
        <application>Heimdal</application> and MIT recommend it.</para>

        <para><option>encrypt = true</option> provides encryption of all
        traffic between kerberized clients and servers. It's not necessary
        and can be left off. If you leave it off, you can encrypt all traffic
        from the client to the server using a switch on the client program
        instead.</para>

        <para>The <option>[realms]</option> parameters tell the client
        programs where to look for the KDC authentication services.</para>

        <para>The <option>[domain_realm]</option> section maps a domain to
        a realm.</para>

        <para>Create the KDC database:</para>

<screen role="root"><userinput>kdb5_util create -r <replaceable>&lt;LFS.ORG&gt;</replaceable> -s</userinput></screen>

        <para>Now you should populate the database with principles
        (users). For now, just use your regular login name or
        <systemitem class="username">root</systemitem>.</para>

<screen role="root"><userinput>kadmin.local
<prompt>kadmin:</prompt> add_policy dict-only
<prompt>kadmin:</prompt> addprinc -policy dict-only <replaceable>&lt;loginname&gt;</replaceable></userinput></screen>

        <para>The KDC server and any machine running kerberized
        server daemons must have a host key installed:</para>

<screen role='root'><userinput><prompt>kadmin:</prompt> addprinc -randkey host/<replaceable>&lt;belgarath.lfs.org&gt;</replaceable></userinput></screen>

        <para>After choosing the defaults when prompted, you will have to
        export the data to a keytab file:</para>

<screen role='root'><userinput><prompt>kadmin:</prompt> ktadd host/<replaceable>&lt;belgarath.lfs.org&gt;</replaceable></userinput></screen>

        <para>This should have created a file in
        <filename class="directory">/etc</filename> named
        <filename>krb5.keytab</filename> (Kerberos 5). This file should
        have 600 (<systemitem class="username">root</systemitem> rw only)
        permissions. Keeping the keytab files from public access is crucial
        to the overall security of the Kerberos installation.</para>

        <para>Exit the <command>kadmin</command> program (use
        <command>quit</command> or <command>exit</command>) and return
        back to the shell prompt. Start the KDC daemon manually, just to
        test out the installation:</para>

<screen role='root'><userinput>/usr/sbin/krb5kdc</userinput></screen>

        <para>Attempt to get a ticket with the following command:</para>

<screen><userinput>kinit <replaceable>&lt;loginname&gt;</replaceable></userinput></screen>

        <para>You will be prompted for the password you created. After you
        get your ticket, you can list it with the following command:</para>

<screen><userinput>klist</userinput></screen>

        <para>Information about the ticket should be displayed on the
        screen.</para>

        <para>To test the functionality of the keytab file, issue the
        following command:</para>

<screen><userinput>ktutil
<prompt>ktutil:</prompt> rkt /etc/krb5.keytab
<prompt>ktutil:</prompt> l</userinput></screen>

        <para>This should dump a list of the host principal, along with
        the encryption methods used to access the principal.</para>

        <para>At this point, if everything has been successful so far, you
        can feel fairly confident in the installation and configuration of
        the package.</para>

        <para>Install the <filename>/etc/rc.d/init.d/kerberos</filename> init
        script included in the <xref linkend="bootscripts"/>
        package.</para>

<screen role="root"><userinput>make install-kerberos</userinput></screen>

      </sect4>

      <sect4>
        <title>Additional Information</title>

        <para>For additional information consult <ulink
        url="http://web.mit.edu/kerberos/www/krb5-1.10/#documentation">
        Documentation for krb-&mitkrb-version;</ulink> on which the above
        instructions are based.</para>

      </sect4>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>
    <para></para>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>gss-client, gss-server, k5srvutil, kadmin, kadmin.local, 
        kadmind, kdb5_ldap_util, kdb5_util, kdestroy, kinit, klist, 
        kpasswd, kprop, kpropd, krb5-config, krb5kdc, krb5-send-pr, 
        ksu, kswitch, ktutil, kvno, sclient, sim_client, sim_server, 
        sserver, uuclient, and uuserver</seg>
        <seg>libgssapi_krb5.so, libgssrpc.so, libk5crypto.so, 
        libkadm5clnt.so, libkadm5srv.so, libkdb5.so, libkdb_ldap.so, 
        libkrb5.so, libkrb5support.so, libverto-k5ev.so and 
        libverto.so</seg>
        <seg>/usr/include/{gssapi,gssrpc,kadm5,krb5}, /usr/lib/krb5, 
        /usr/share/{doc/krb5-&mitkrb-version;,examples/krb5,gnats}
        and /var/lib/krb5kdc</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="k5srvutil">
        <term><command>k5srvutil</command></term>
        <listitem>
          <para>is a host keytable manipulation utility.</para>
          <indexterm zone="mitkrb k5srvutil">
            <primary sortas="b-k5srvutil">k5srvutil</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kadmin-mitkrb">
        <term><command>kadmin</command></term>
        <listitem>
          <para>is an utility used to make modifications
          to the Kerberos database.</para>
          <indexterm zone="mitkrb kadmin-mitkrb">
            <primary sortas="b-kadmin">kadmin</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kadmind-mitkrb">
        <term><command>kadmind</command></term>
        <listitem>
          <para>is a server for administrative access
          to a Kerberos database.</para>
          <indexterm zone="mitkrb kadmind-mitkrb">
            <primary sortas="b-kadmind">kadmind</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kdb5_util">
        <term><command>kdb5_util</command></term>
        <listitem>
          <para>is the KDC database utility.</para>
          <indexterm zone="mitkrb kdb5_util">
            <primary sortas="b-kdb5_util">kdb5_util</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kdestroy-mitkrb">
        <term><command>kdestroy</command></term>
        <listitem>
          <para>removes the current set of tickets.</para>
          <indexterm zone="mitkrb kdestroy-mitkrb">
            <primary sortas="b-kdestroy">kdestroy</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kinit-mitkrb">
        <term><command>kinit</command></term>
        <listitem>
          <para>is used to authenticate to the Kerberos server as a
          principal and acquire a ticket granting ticket that can
          later be used to obtain tickets for other services.</para>
          <indexterm zone="mitkrb kinit-mitkrb">
            <primary sortas="b-kinit">kinit</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="klist-mitkrb">
        <term><command>klist</command></term>
        <listitem>
          <para>reads and displays the current tickets in
          the credential cache.</para>
          <indexterm zone="mitkrb klist-mitkrb">
            <primary sortas="b-klist">klist</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kpasswd-mitkrb">
        <term><command>kpasswd</command></term>
        <listitem>
          <para>is a program for changing Kerberos 5 passwords.</para>
          <indexterm zone="mitkrb kpasswd-mitkrb">
            <primary sortas="b-kpasswd">kpasswd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kprop">
        <term><command>kprop</command></term>
        <listitem>
          <para>takes a principal database in a specified format and
          converts it into a stream of database records.</para>
          <indexterm zone="mitkrb kprop">
            <primary sortas="b-kprop">kprop</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kpropd">
        <term><command>kpropd</command></term>
        <listitem>
          <para>receives a database sent by <command>kprop</command>
          and writes it as a local database.</para>
          <indexterm zone="mitkrb kpropd">
            <primary sortas="b-kpropd">kpropd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="krb5-config-prog2">
        <term><command>krb5-config</command></term>
        <listitem>
          <para>gives information on how to link programs against
          libraries.</para>
          <indexterm zone="mitkrb krb5-config-prog2">
            <primary sortas="b-krb5-config">krb5-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="krb5kdc">
        <term><command>krb5kdc</command></term>
        <listitem>
          <para>is a Kerberos 5 server.</para>
          <indexterm zone="mitkrb krb5kdc">
            <primary sortas="b-krb5kdc">krb5kdc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ksu">
        <term><command>ksu</command></term>
        <listitem>
          <para>is the super user program using Kerberos protocol.
          Requires a properly configured
          <filename class="directory">/etc/shells</filename> and
          <filename>~/.k5login</filename> containing principals
          authorized to become super users.</para>
          <indexterm zone="mitkrb ksu">
            <primary sortas="b-ksu">ksu</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kswitch">
        <term><command>kswitch</command></term>
        <listitem>
          <para>makes the specified credential cache the 
          primary cache for the collection, if a cache 
          collection is available.</para>
          <indexterm zone="mitkrb kswitch">
            <primary sortas="b-kswitch">kswitch</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ktutil-mitkrb">
        <term><command>ktutil</command></term>
        <listitem>
          <para>is a program for managing Kerberos keytabs.</para>
          <indexterm zone="mitkrb ktutil-mitkrb">
            <primary sortas="b-ktutil">ktutil</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kvno">
        <term><command>kvno</command></term>
        <listitem>
          <para>prints keyversion numbers of Kerberos principals.</para>
          <indexterm zone="mitkrb kvno">
            <primary sortas="b-kvno">kvno</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sclient">
        <term><command>sclient</command></term>
        <listitem>
          <para>used to contact a sample server and authenticate to it
          using Kerberos version 5 tickets, then display the server's 
          response.</para>
          <indexterm zone="mitkrb sclient">
            <primary sortas="b-sclient">sclient</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sserver">
        <term><command>sserver</command></term>
        <listitem>
          <para>sample Kerberos version 5 server.</para>
          <indexterm zone="mitkrb sserver">
            <primary sortas="b-sserver">sserver</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgssapi_krb5-mitkrb">
        <term><filename class='libraryfile'>libgssapi_krb5.so</filename></term>
        <listitem>
          <para>contain the Generic Security Service Application
          Programming Interface (GSSAPI) functions which provides security
          services to callers in a generic fashion, supportable with a range of
          underlying mechanisms and technologies and hence allowing source-level
          portability of applications to different environments.</para>
          <indexterm zone="mitkrb libgssapi_krb5-mitkrb">
            <primary sortas="c-libgssapi_krb5">libgssapi_krb5.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libkadm5clnt-mitkrb">
        <term><filename class='libraryfile'>libkadm5clnt.so</filename></term>
        <listitem>
          <para>contains the administrative authentication and password
          checking functions required by Kerberos 5 client-side programs.</para>
          <indexterm zone="mitkrb libkadm5clnt-mitkrb">
            <primary sortas="c-libkadm5clnt">libkadm5clnt.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libkadm5srv-mitkrb">
        <term><filename class='libraryfile'>libkadm5srv.so</filename></term>
        <listitem>
          <para>contain the administrative authentication and password
          checking functions required by Kerberos 5 servers.</para>
          <indexterm zone="mitkrb libkadm5srv-mitkrb">
            <primary sortas="c-libkadm5srv">libkadm5srv.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libkdb5">
        <term><filename class='libraryfile'>libkdb5.so</filename></term>
        <listitem>
          <para>is a Kerberos 5 authentication/authorization database
          access library.</para>
          <indexterm zone="mitkrb libkdb5">
            <primary sortas="c-libkdb5">libkdb5.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libkrb5-mitkrb">
        <term><filename class='libraryfile'>libkrb5.so</filename></term>
        <listitem>
          <para>is an all-purpose Kerberos 5 library.</para>
          <indexterm zone="mitkrb libkrb5-mitkrb">
            <primary sortas="c-libkrb5">libkrb5.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>