path: root/share/doc/handbook/kerberos.sgml

<!-- $Id: kerberos.sgml,v 1.4 1995/07/10 20:14:08 markm Exp $ -->
<!-- The FreeBSD Documentation Project -->

<sect><heading>Kerberos<label id="kerberos"></heading>

<p><em>Contributed by &a.mark; (based on contribution by &a.md;).</em>

    Kerberos is a network add-on system/protocol that allows users to
    authenticate themselves through the services of a secure server.
    Services such as remote login, remote copy, secure inter-system
    file copying and other high-risk tasks are made considerably safer
    and more controllable.

    The following instructions can be used as a guide on how to
    set up Kerberos as distributed for FreeBSD. However, you should refer
    to the relevant manual pages for a complete description.

    In FreeBSD, the Kerberos is not that from the original 4.4 BSD,
    distribution, but eBones, which had been previously ported to
    FreeBSD 1.1.5.1, and was sourced from outside the USA/Canada,
    and is thus available to system owners outside those countries.

    For those needing to get a legal foreign distribution of this
    software, please <em>DO NOT</em> get it from a USA or Canada site.
    You will get that site in <em>big</em> trouble! A legal copy of this is
    available from <tt>skeleton.mikom.csir.co.za</tt>, which is in South
    Africa.

 <sect1>
 <heading>Creating the initial database</heading>

 <p>This is done on the Kerberos server only. First make sure that your
    don't have any old Kerberos databases around. You should change to the
    directory <tt>/etc/kerberosIV</tt> and check that only the following
    files are present:

<tscreen><verb>
grunt# cd /etc/kerberosIV
grunt# ls
README          krb.conf        krb.realms
</verb></tscreen>

 <p>If any additional files (such as <tt>principal.*</tt> or
    <tt>master_key</tt>) exist, then use the <tt>kdb_destroy</tt>
    command to destroy the old Kerberos database, of if Kerberos
    is not running, simply delete the extra files with <tt>rm</tt>.

    You should now edit the <tt>krb.conf</tt> and <tt>krb.realms</tt>
    files to define your Kerberos realm. In this case the realm will
    be <it>GRONDAR.ZA</it> and the server is <it>grunt.grondar.za</it>.
    We edit or create the <tt>krb.conf</tt> file:

<tscreen><verb>
grunt# cat krb.conf
GRONDAR.ZA
GRONDAR.ZA grunt.grondar.za admin server
CS.BERKELEY.EDU okeeffe.berkeley.edu
ATHENA.MIT.EDU kerberos.mit.edu
ATHENA.MIT.EDU kerberos-1.mit.edu
ATHENA.MIT.EDU kerberos-2.mit.edu
ATHENA.MIT.EDU kerberos-3.mit.edu
LCS.MIT.EDU kerberos.lcs.mit.edu
TELECOM.MIT.EDU bitsy.mit.edu
ARC.NASA.GOV trident.arc.nasa.gov
</verb></tscreen>

 <p>In this case, the other realms do not need to be there.
    They are here as an example of how a machine may be made aware
    of multiple realms. You may wish to not include them for simplicity.

    The first line names the realm in which this system works. The other
    lines contain realm/host entries. The first item on a line is a realm,
    and the second is a host in that realm that is acting as a ``key
    distribution centre''. The words ``admin server'' following a hosts
    name means that host also provides an administrative database server.
    For further explanation of these terms, please consult the Kerberos
    man pages.

    Now we have to add <it>grunt.grondar.za</it> to the <it>GRONDAR.ZA</it>
    realm and also add an entry to put all hosts in the <it>.grondar.za</it>
    domain in the <it>GRONDAR.ZA</it> realm.  The <tt>krb.realms</tt> file
    would be updated as follows:

<tscreen><verb>
 grunt# cat krb.realms
 grunt.grondar.za GRONDAR.ZA
 .grondar.za GRONDAR.ZA
 .berkeley.edu CS.BERKELEY.EDU
 .MIT.EDU ATHENA.MIT.EDU
 .mit.edu ATHENA.MIT.EDU
</verb></tscreen>

 <p>Again, the other realms do not need to be there.
    They are here as an example of how a machine may be made aware
    of multiple realms. You may wish to remove them to simplify things.

    The first line puts the <it>specific</it> system into the named
    realm. The rest of the lines show how to default systems of a
    particular subdomain to a named realm.

    Now we're ready to create the database. This only needs to run on
    the Kerberos server (or Key Distribution Centre). Issue the
    <tt>kdb_init</tt> command to do this:

<tscreen><verb>
grunt# kdb_init
Realm name [default  ATHENA.MIT.EDU ]: GRONDAR.ZA
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.

Enter Kerberos master key: 
</verb></tscreen>

 <p>Now we have to save the key so that servers on the local
    machine can pick it up.  Use the <tt>kstash</tt> command to
    do this.

<tscreen><verb>
grunt# kstash

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
</verb></tscreen>

 <p>This saves the encrypted master password in
    <tt>/etc/kerberosIV/master_key</tt>.

 <sect1>
  <heading>Making it all run</heading>

 <p>Two principals need to be added to the database for <it>each</it>
    system that will be secured with Kerberos. Their names are
    <tt>kpasswd</tt> and <tt>rcmd</tt> These two principals are
    made for each system, with the instance being the name of the
    individual system.

    These daemons, <tt>kpasswd</tt> and <tt>rcmd</tt> allow other systems
    to change Kerberos passwords and run commands like <tt>rcp</tt>,
    <tt>rlogin</tt> and <tt>rsh</tt>.

   Now lets add these entries:

<tscreen><verb>
grunt# kdb_edit
Opening database...

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.

Principal name: passwd
Instance: grunt

<Not found>, Create [y] ? y

Principal: passwd, Instance: grunt, kdc_key_ver: 1
New Password:                    <---- enter RANDOM here
Verifying password

New Password:                    <---- enter RANDOM here

Random password [y] ? y

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 
Attributes [ 0 ] ? 
Edit O.K.
Principal name: rcmd
Instance: grunt

<Not found>, Create [y] ? 

Principal: rcmd, Instance: grunt, kdc_key_ver: 1
New Password:                    <---- enter RANDOM here
Verifying password

New Password:                    <---- enter RANDOM here

Random password [y] ? 

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 
Attributes [ 0 ] ? 
Edit O.K.
Principal name:                  <---- null entry here will cause an exit
</verb></tscreen>

 <sect1>
  <heading>Creating the server file</heading>

 <p>We now have to extract all the instances which define the services
    on each machine.  For this we use the <tt>ext_srvtab</tt> command.
    This will create a file which must be copied or moved <it>by secure
    means</it> to each Kerberos client's /etc/kerberosIV directory. This
    file must be present on each server and client, and is crucial to the
    operation of Kerberos.

<tscreen><verb>
grunt# ext_srvtab grunt

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Generating 'grunt-new-srvtab'....
</verb></tscreen>

 <p>Now, this command only generates a temporary file
    which must be renamed to <tt>srvtab</tt> so that all the
    server can pick it up.  Use the <tt>mv</tt> command to move it
    into place on the original system:

<tscreen><verb>
grunt# mv grunt-new-srvtab srvtab
</verb></tscreen>

 <p>If the file is for a client system, and the network is not
    deemed safe, then copy the <tt>&lt;client&gt;-new-srvtab</tt> to
    removable media and transport it by secure physical means. Be
    sure to rename it to <tt>srvtab</tt> in the client's
    <tt>/etc/kerberosIV</tt> directory, and make sure it is mode 600:

<tscreen><verb>
grumble# mv grumble-new-srvtab srvtab
grumble# chmod 600 srvtab
</verb></tscreen>

 <sect1>
  <heading>Populating the database</heading>

 <p>We now have to add some user entries into the database.
    First lets create an entry for the user <it>jane</it>.  Use
    the <tt>kdb_edit</tt> command to do this:

<tscreen><verb>
grunt# kdb_edit
Opening database...

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.

Principal name: jane
Instance:

<Not found>, Create [y] ? y

Principal: jane, Instance: , kdc_key_ver: 1
New Password:                    <---- enter a secure password here
Verifying password

New Password:                    <---- re-enter the password here

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 
Attributes [ 0 ] ? 
Edit O.K.
Principal name:                  <---- null entry here will cause an exit
</verb></tscreen>

 <sect1>
  <heading>Testing it all out</heading>

 <p>First we have to start the Kerberos daemons. NOTE that if you have
    correctly edited your <tt>/etc/sysconfig</tt> then this will happen
    automatically when you reboot. This is only necessary on the Kerberos
    server. Kerberos clients will automagically get what they need from
    the <tt>/etc/kerberosIV</tt> directory.

<tscreen><verb>
grunt# kerberos &
grunt# Kerberos server starting
        Sleep forever on error
        Log file is /var/log/kerberos.log
Current Kerberos master key version is 1.

Master key entered.  BEWARE!

Current Kerberos master key version is 1
Local realm: GRONDAR.ZA
grunt# kadmind -n &
grunt# KADM Server KADM0.0A initializing
Please do not use 'kill -9' to kill this job, use a
regular kill instead

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
</verb></tscreen>

 <p>Now we can try using the <tt>kinit</tt> command to get a ticket for
    the id <it>jane</it> that we created above:

<tscreen><verb>
grunt$ kinit jane
MIT Project Athena (grunt.grondar.za)
Kerberos Initialization for "jane"
Password: 
</verb></tscreen>

 <p>Try listing the tokens using <tt>klist</tt> to see if we really have them:

<tscreen><verb>
grunt$ klist
Ticket file:    /tmp/tkt245
Principal:    jane@GRONDAR.ZA

  Issued           Expires          Principal
Apr 30 11:23:22  Apr 30 19:23:22  krbtgt.GRONDAR.ZA@GRONDAR.ZA
</verb></tscreen>

 <p>Now try changing the password using <tt>passwd</tt> to check if the
    kpasswd daemon can get authorization to the Kerberos database:

<tscreen><verb>
grunt$ passwd
realm GRONDAR.ZA
Old password for jane:
New Password for jane:
Verifying password
New Password for jane:
Password changed.
</verb></tscreen>

 <sect1>
  <heading>Adding <tt>su</tt> privileges</heading>

 <p>Kerberos allows us to give <it>each</it> user who needs root
    privileges their own <it>separate</it> <tt>su</tt>password. We
    could now add an id which is authorized to <tt>su</tt> to <it>root</it>.
    This is controlled by having an instance of <it>root</it> associated
    with a principal.  Using <tt>kdb_edit</tt> we can create the entry
    <it>jane.root</it> in the Kerberos database:

<tscreen><verb>
grunt# kdb_edit
Opening database...

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.

Principal name: jane
Instance: root

<Not found>, Create [y] ? y

Principal: jane, Instance: root, kdc_key_ver: 1
New Password:                    <---- enter a SECURE password here
Verifying password

New Password:                    <---- re-enter the password here

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 12 <--- Keep this short!
Attributes [ 0 ] ? 
Edit O.K.
Principal name:                  <---- null entry here will cause an exit
</verb></tscreen>

 <p>Now try getting tokens for it to make sure it works:

<tscreen><verb>
grunt# kinit jane.root
MIT Project Athena (grunt.grondar.za)
Kerberos Initialization for "jane.root"
Password: 
 </verb></tscreen>

 <p>Now we need to add the user to root's <tt>.klogin</tt> file:

<tscreen><verb>
grunt# cat /root/.klogin
jane.root@GRONDAR.ZA
</verb></tscreen>

 <p>Now try doing the <tt>su</tt>:

<tscreen><verb>
[jane@grunt 10407] su
Password: 
grunt#
      </verb></tscreen>

    and take a look at what tokens we have:

<tscreen><verb>
grunt# klist
Ticket file:	/tmp/tkt_root_245
Principal:	jane.root@GRONDAR.ZA

  Issued           Expires          Principal
May  2 20:43:12  May  3 04:43:12  krbtgt.GRONDAR.ZA@GRONDAR.ZA
</verb></tscreen>

 <sect1>
  <heading>Using other commands</heading>

 <p>In an earlier example, we created a principal called <tt>jane</tt>
    with an instance <tt>root</tt>. This was based on a user with the
    same name as the principal, and this is a Kerberos default; that a
    <em>&lt;principal&gt;.&lt;instance&gt;</em> of the form
    <em>&lt;username&gt;.</em><tt>root</tt> will allow that
    <em>&lt;username&gt;</em> to <tt>su</tt> to root if the necessary
    entries are in the <tt>.klogin</tt> file in <tt>root</tt>'s home
    directory:

<tscreen><verb>
grunt# cat /root/.klogin
jane.root@GRONDAR.ZA
</verb></tscreen>

 <p>Likewise, if a user has in their own home directory lines of the
    form:

<tscreen><verb>
[jane@grunt 10543] cat ~/.klogin
jane@GRONDAR.ZA
jack@GRONDAR.ZA
</verb></tscreen>

 <p>This allows anyone in the <em>GRONDAR.ZA</em> realm who has
    authenticated themselves to <em>jane</em> or <em>jack</em> (via
    <tt>kinit</tt>, see above) access to <tt>rlogin</tt> to <em>jane</em>'s
    account or files on this system (<em>grunt</em>) via <tt>rlogin</tt>,
    <tt>rsh</tt> or <tt>rcp</tt>.

    For example, Jane now logs into another system, using Kerberos:

<tscreen><verb>
[jane@grumble 573] kinit
MIT Project Athena (grunt.grondar.za)
Password: 
[jane@grumble 574] rlogin grunt
Last login: Mon May  1 21:14:47 from grumble
Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
	The Regents of the University of California.   All rights reserved.

FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995

[jane@grunt 10567]
</verb></tscreen>

 <p>Or Jack logs into Jane's account on the same machine (Jane having set up
    the <tt>.klogin</tt> file as above, and the person in charge of Kerberos
    having set up principal <em>jack</em> with a null instance:

<tscreen><verb>
[jack@grumble 573] kinit
[jack@grumble 574] rlogin grunt -l jane
MIT Project Athena (grunt.grondar.za)
Password: 
Last login: Mon May  1 21:16:55 from grumble
Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
	The Regents of the University of California.   All rights reserved.

FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995

[jane@grunt 10578]
</verb></tscreen>