source: postlfs/security/mitkrb.xml@ d5d6554

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

  <!ENTITY mitkrb-download-http "http://web.mit.edu/kerberos/www/dist/krb5/1.3/krb5-&mitkrb-version;.tar">
  <!ENTITY mitkrb-download-ftp " ">
  <!ENTITY mitkrb-size "6.3 MB">
  <!ENTITY mitkrb-buildsize "64 MB">
  <!ENTITY mitkrb-time "2.55 SBU">
]>

<sect1 id="mitkrb" xreflabel="MIT krb5-&mitkrb-version;">
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<?dbhtml filename="mitkrb.html"?>
<title><acronym>MIT</acronym> krb5-&mitkrb-version;</title>
<indexterm zone="mitkrb">
<primary sortas="a-kerberos-MIT">Kerberos5(MIT)</primary></indexterm>


<sect2>
<title>Introduction to <application><acronym>MIT</acronym> krb5</application></title>

<para>
<application><acronym>MIT</acronym> krb5</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>

<sect3><title>Package information</title>
<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 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>
</sect3>

<sect3><title><application><acronym>MIT</acronym> krb5</application> dependencies</title>
<sect4><title>Optional</title>
<para>
<xref linkend="xinetd"/> (services servers only), 
<xref linkend="Linux_PAM"/> (for <command>xdm</command> based logins) and
<xref linkend="openldap"/> (alternative for <command>krb5kdc</command> 
password database)
</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
<acronym>KDC</acronym> server.</para></note> 
</sect4>

</sect3>

</sect2>

<sect2>
<title>Installation of <application><acronym>MIT</acronym> krb5</application></title>

<para>
<application><acronym>MIT</acronym> krb5</application> is distributed in a 
<acronym>TAR</acronym> file containing a compressed <acronym>TAR</acronym> 
package and a detached <acronym>PGP</acronym> 
<filename class="extension">ASC</filename> file.
</para>

<para>
If you have installed <xref linkend="gnupg"/>, you can
authenticate the package with the following command:
</para>

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

<para>
Build <application><acronym>MIT</acronym> krb5</application> by running the 
following commands:
</para>

<screen><userinput><command>cd src &amp;&amp;
./configure --prefix=/usr --sysconfdir=/etc \
    --localstatedir=/var/lib --enable-dns --enable-shared --mandir=/usr/share/man &amp;&amp;
make</command></userinput></screen>

<para>
Install <application><acronym>MIT</acronym> krb5</application> by
running the following commands as root:
</para>

<screen><userinput><command>make install &amp;&amp;
mv /bin/login /bin/login.shadow &amp;&amp;
cp /usr/sbin/login.krb5 /bin/login &amp;&amp;
mv /usr/bin/ksu /bin &amp;&amp;
mv /usr/lib/libkrb5.so.3* /lib &amp;&amp;
mv /usr/lib/libkrb4.so.2* /lib &amp;&amp;
mv /usr/lib/libdes425.so.3* /lib &amp;&amp;
mv /usr/lib/libk5crypto.so.3* /lib &amp;&amp;
mv /usr/lib/libcom_err.so.3* /lib &amp;&amp;
ln -sf ../../lib/libkrb5.so.3 /usr/lib/libkrb5.so &amp;&amp;
ln -sf ../../lib/libkrb4.so.2 /usr/lib/libkrb4.so &amp;&amp;
ln -sf ../../lib/libdes425.so.3 /usr/lib/libdes425.so &amp;&amp;
ln -sf ../../lib/libk5crypto.so.3 /usr/lib/libk5crypto.so &amp;&amp;
ln -sf ../../lib/libcom_err.so.3 /usr/lib/libcom_err.so &amp;&amp;
ldconfig</command></userinput></screen>

</sect2>

<sect2>
<title>Command explanations</title>

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

<para>
<screen><command>mv /bin/login /bin/login.shadow
cp /usr/sbin/login.krb5 /bin/login
mv /usr/bin/ksu /bin</command></screen>
Preserves <application>Shadow</application>'s <command>login</command>
command, moves <command>ksu</command> and <command>login</command> to
the <filename class="directory">/bin</filename> directory.
</para>

<para>
<screen><command>mv /usr/lib/libkrb5.so.3* /lib
mv /usr/lib/libkrb4.so.2* /lib
mv /usr/lib/libdes425.so.3* /lib
mv /usr/lib/libk5crypto.so.3* /lib
mv /usr/lib/libcom_err.so.3* /lib
ln -sf ../../lib/libkrb5.so.3 /usr/lib/libkrb5.so
ln -sf ../../lib/libkrb4.so.2 /usr/lib/libkrb4.so
ln -sf ../../lib/libdes425.so.3 /usr/lib/libdes425.so
ln -sf ../../lib/libk5crypto.so.3 /usr/lib/libk5crypto.so
ln -sf ../../lib/libcom_err.so.3 /usr/lib/libcom_err.so</command></screen>
The <command>login</command> and <command>ksu</command> programs
are linked against these libraries, therefore we move these libraries to 
<filename class="directory">/lib</filename> to allow logins without mounting 
<filename class="directory">/usr</filename>.
</para>

</sect2>

<sect2>
<title>Configuring <application><acronym>MIT</acronym> krb5</application></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-kerberos-config">/etc/krb5.conf</primary>
</indexterm>
</sect3>

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

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

<para>
Create the Kerberos configuration file with the following command:
</para>

<screen><userinput><command>cat &gt; /etc/krb5.conf &lt;&lt; "EOF"</command>
# Begin /etc/krb5.conf

[libdefaults]
    default_realm = <replaceable>[LFS.ORG]</replaceable>
    encrypt = true

[realms]
    <replaceable>[LFS.ORG]</replaceable> = {
        kdc = <replaceable>[belgarath.lfs.org]</replaceable>
        admin_server = <replaceable>[belgarath.lfs.org]</replaceable>
    }

[domain_realm]
    .<replaceable>[lfs.org]</replaceable> = <replaceable>[LFS.ORG]</replaceable>

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

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

<para>
You will need to substitute your domain and proper hostname for the
occurances of the <replaceable>[belgarath]</replaceable> and 
<replaceable>[lfs.org]</replaceable> names.
</para>

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

<para>
<userinput>encrypt = true</userinput> 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 <userinput>[realms]</userinput> parameters tell the client programs where 
to look for the <acronym>KDC</acronym> authentication services.
</para>

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

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

<screen><userinput><command>kdb5_util create -r <replaceable>[LFS.ORG]</replaceable> -s </command></userinput></screen>

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

<screen><userinput><command>kadmin.local</command></userinput>
<prompt>kadmin:</prompt><userinput><command>addprinc <replaceable>[loginname]</replaceable></command></userinput></screen>

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

<screen><prompt>kadmin:</prompt><userinput><command>addprinc -randkey host/<replaceable>[belgarath.lfs.org]</replaceable></command></userinput></screen>

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

<screen><prompt>kadmin:</prompt><userinput><command>ktadd host/<replaceable>[belgarath.lfs.org]</replaceable></command></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
(root rw only) permissions. Keeping the keytab files from public access
is crucial to the overall security of the Kerberos installation.
</para>

<para>
Eventually, you'll want to add server daemon principles to the database
and extract them to the keytab file. You do this in the same way you
created the host principles. Below is an example:
</para>

<screen><prompt>kadmin:</prompt><userinput><command>addprinc -randkey ftp/<replaceable>[belgarath.lfs.org]</replaceable></command></userinput>
<prompt>kadmin:</prompt><userinput><command>ktadd ftp/<replaceable>[belgarath.lfs.org]</replaceable></command></userinput></screen>

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

<screen><userinput><command>/usr/sbin/krb5kdc &amp;</command></userinput></screen>

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

<screen><userinput><command>kinit <replaceable>[loginname]</replaceable></command></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><command>klist</command></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><command>ktutil</command></userinput>
<prompt>ktutil:</prompt><userinput><command>rkt /etc/krb5.keytab</command></userinput>
<prompt>ktutil:</prompt><userinput><command>l</command></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="intro-important-bootscripts"/> package.
</para>

<screen><userinput><command>make install-kerberos</command></userinput></screen>

</sect4>

<sect4><title>Using Kerberized Client Programs</title>

<para>
To use the kerberized client programs (<command>telnet</command>,
<command>ftp</command>, <command>rsh</command>,
<command>rcp</command>, <command>rlogin</command>), you first must get
an authentication ticket. Use the <command>kinit</command> program to
get the ticket. After you've acquired the ticket, you can use the
kerberized programs to connect to any kerberized server on the network.
You will not be prompted for authentication until your ticket expires
(default is one day), unless you specify a different user as a command
line argument to the program.
</para>

<para>
The kerberized programs will connect to non kerberized daemons, warning
you that authentication is not encrypted.
</para>
</sect4>

<sect4><title>Using Kerberized Server Programs</title>
<para>
Using kerberized server programs (<command>telnetd</command>,
<command>kpropd</command>, <command>klogind</command> and 
<command>kshd</command>) requires two additional configuration steps.
First the <filename>/etc/services</filename> file must be updated to
include eklogin and krb5_prop. Second, the <filename>inetd.conf</filename> 
or <filename>xinetd.conf</filename> must be modified for each server that will 
be activated, usually replacing the server from <xref linkend="inetutils"/>.
</para>
</sect4>

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

</sect4>

</sect3>

</sect2>

<sect2>
<title>Contents</title>

<para>
The <application>MIT krb5</application> package contains
<command>compile-et</command>,
<command>ftp</command>,
<command>ftpd</command>,
<command>gss-client</command>,
<command>gss-server</command>,
<command>k5srvutil</command>,
<command>kadmin</command>,
<command>kadmin.local</command>,
<command>kadmind</command>,
<command>kadmind4</command>,
<command>kdb5_util</command>
<command>kdestroy</command>,
<command>kinit</command>,
<command>klist</command>,
<command>klogind</command>,
<command>kpasswd</command>,
<command>kprop</command>,
<command>kpropd</command>,
<command>krb5-send-pr</command>,
<command>krb5-config</command>,
<command>krb524d</command>,
<command>krb524init</command>,
<command>krb5kdc</command>,
<command>kshd</command>,
<command>ksu</command>,
<command>ktutil</command>,
<command>kvno</command>,
<command>login.krb5</command>,
<command>rcp</command>,
<command>rlogin</command>,
<command>rsh</command>,
<command>rshd</command>,
<command>rxtelnet</command>,
<command>rxterm</command>,
<command>sclient</command>,
<command>sim_client</command>,
<command>sim_server</command>,
<command>sserver</command>,
<command>telnet</command>,
<command>telnetd</command>,
<command>uuclient</command>,
<command>uuserver</command>,
<command>v5passwd</command>,
<command>v5passwdd</command>,
<filename class="libraryfile">libcom_err</filename>,
<filename class="libraryfile">libdes425</filename>,
<filename class="libraryfile">libgssapi</filename>,
<filename class="libraryfile">libgssrpc</filename>,
<filename class="libraryfile">lib5crypto</filename>,
<filename class="libraryfile">libkadm5clnt</filename>,
<filename class="libraryfile">libkadm5srv</filename>,
<filename class="libraryfile">libkdb5</filename>,
<filename class="libraryfile">libkrb4</filename> and 
<filename class="libraryfile">libkrb5</filename>.
</para>

</sect2>

<sect2><title>Description</title>

<sect3><title>compile_et</title>
<para>
<command>compile_et</command> converts the table listing
error-code names into a <application>C</application> source file.
</para>
</sect3>

<sect3><title>k5srvutil</title>
<para>
<command>k5srvutil</command> is a host keytable manipulation utility.
</para>
</sect3>

<sect3><title>kadmin</title>
<para>
<command>kadmin</command> is an utility used to make modifications
to the Kerberos database.
</para>
</sect3>

<sect3><title>kadmind</title>
<para>
<command>kadmind</command> is a server for administrative access
to a Kerberos database.
</para>
</sect3>

<sect3><title>kinit</title>
<para>
<command>kinit</command> 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>
</sect3>

<sect3><title>krb5kdc</title>
<para>
<command>krb5kdc</command> is a Kerberos 5 server.
</para>
</sect3>

<sect3><title>kdestroy</title>
<para>
<command>kdestroy</command> removes the current set of tickets.
</para>
</sect3>

<sect3><title>kdb5_util</title>
<para>
<command>kdb5_util</command> is the <acronym>KDC</acronym> database utility.
</para>
</sect3>

<sect3><title>klist</title>
<para>
<command>klist</command> reads and displays the current tickets in
the credential cache.
</para>
</sect3>

<sect3><title>klogind</title>
<para>
<command>klogind</command> is the server that responds to 
<command>rlogin</command> requests.
</para>
</sect3>

<sect3><title>kpasswd</title>
<para>
<command>kpasswd</command> is a program for changing Kerberos 5 passwords.
</para>
</sect3>

<sect3><title>kprop</title>
<para>
<command>kprop</command> takes a principal database in a specified
format and converts it into a stream of database
records.
</para>
</sect3>

<sect3><title>kpropd</title>
<para>
<command>kpropd</command> receives a database sent by
<command>hprop</command> and writes it as a local database.
</para>
</sect3>

<sect3><title>krb5-config</title>
<para>
<command>krb5-config</command> gives information on how to link
programs against libraries.
</para>
</sect3>

<sect3><title>ksu</title>
<para>
<command>ksu</command> 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>
</sect3>

<sect3><title>ktutil</title>
<para>
<command>ktutil</command> is a program for managing Kerberos keytabs.
</para>
</sect3>

<sect3><title>kvno</title>
<para>
<command>kvno</command> prints keyversion numbers of Kerberos principals.
</para>
</sect3>

</sect2>

</sect1>