freebsd-dev/share/doc/handbook/kerberos.sgml
Jordan K. Hubbard 1130b656e5 Make the long-awaited change from $Id$ to $FreeBSD$
This will make a number of things easier in the future, as well as (finally!)
avoiding the Id-smashing problem which has plagued developers for so long.

Boy, I'm glad we're not using sup anymore.  This update would have been
insane otherwise.
1997-01-14 07:20:47 +00:00

481 lines
15 KiB
Plaintext

<!-- $FreeBSD$ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>Kerberos<label id="kerberos"></heading>
<p><em>Contributed by &a.markm; (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.4BSD-Lite,
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
do not 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 are 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>