.H2 "Kerberos"
.Pn kerberos
.X "Kerberos"
\fIKerberos\fP\| is an authentication system intended to allow users to
authenticate themselves securely in an otherwise insecure environment.  It is
now a part of the base FreeBSD system, and it no longer needs installation.
.P
The central part of a Kerberos system is a server which maintains a database of
secret keys for \fIprincipals\fP, which can be users or services.
.P
Each principal belongs to a single administrative domain, which Kerberos calls a
\fIrealm\fP.  The realm can be an organization or a network, and by convention
the name is the domain name in upper case.  Kerberos does not require upper case
realm names, but it is case sensitive.  Each realm has at least one Kerberos
server.
.P
Kerberos uses \fItickets\fP\| to grant access to specific services.  Tickets
expire after about 24 hours.  On successful authentication, the Kerberos server
issues a \fIticket granting ticket\fP, or \fITGT\fP, which enables the issue of
further tickets without additional authentication.  Services such as remote
login, remote copy, secure inter-system file copying and other high-risk tasks
are made considerably safer and more controllable.
.H3 "Creating the Initial Database"
The configuration files for the server database are stored in the
directory
.File /etc/kerberosIV .
Initially this directory is empty.  You need to create the
.File krb.conf
and
.File krb.realms
files.  There are sample files in
.File /usr/src/crypto/kerberosIV/etc ,
but in principle you can create them from scratch.  In this case the realm will
be \fIexample.org\fP, and the server is \fIwait.example.org\fP.  Edit or create
the
.File krb.conf
file:
.Dx
EXAMPLE.ORG
EXAMPLE.ORG wait.example.org 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
.De
Only the first two lines are required.  The other realms are an example of how
to make a machine aware of multiple realms.
.P
The first line names the realm to which this system belongs.  The other lines
contain realm and host entries.  The first item on a line is a realm name, and
the second is the name of a host in that realm that is acting as a \fIkey
distribution center\fP.  The words \f(CWadmin server\fP following a host's name
means that host also provides an administrative database server.
.P
Now we have to add \fIwait.example.org\fP to the
.File EXAMPLE.ORG
realm and also add an entry to put all hosts in the \fI.example.org\fP domain in
the
.File EXAMPLE.ORG
realm.  Update the
.File krb.realms
file to contain the following lines:
.Dx
wait.example.org EXAMPLE.ORG
\&.example.org EXAMPLE.ORG
\&.berkeley.edu CS.BERKELEY.EDU
\&.MIT.EDU ATHENA.MIT.EDU
\&.mit.edu ATHENA.MIT.EDU
.De
Again, the other realms are here as an example of how a machine may be made
aware of multiple realms.
.P
The first line puts the \fIspecific\fP system into the named realm.  The rest of
the lines show how to default systems of a particular subdomain to a named
realm.
.P
Now we are ready to create the database.  This only needs to run on the Kerberos
server (or Key Distribution Center).  Issue the
.Command kdb_init
command to do this:
.Dx
# \f(CBkdb_init\fP
Realm name [default  ATHENA.MIT.EDU ]: \f(CBEXAMPLE.ORG\fP
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter Kerberos master key: \fI(no echo)\fP\|
.De
Now we have to save the key so that servers on the local machine can pick it up.
Use the
.Command kstash
command to do this.
.Dx
# \f(CBkstash\fP
Enter Kerberos master key: \fI(no echo)\fP\|
Current Kerberos master key version is 1.
Master key entered. BEWARE!
.De
This saves the encrypted master password in
.File /etc/kerberosIV/master_key .
.H3 "Making It All Run"
Two principals need to be added to the database for \fIeach\fP system that will
be secured with Kerberos.  Their names are \f(CWkpasswd\fP and \f(CWrcmd\fP.
These two principals are made for each system, with the instance being the name
of the individual system.
.P
These daemons, 
.Daemon kpasswd
and
.Daemon rcmd
allow other systems to change Kerberos passwords and run commands like
.Command rcp ,
.Command rlogin
and
.Command rsh .
.P
Now let us add these entries:
.Dx
# \f(CBkdb_edit\fP
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: \f(CBpasswd\fP
Instance: \f(CBwait\fP
<Not found>, Create [y] ? \f(CBy\fP
Principal: passwd, Instance: wait, kdc_key_ver: 1
New Password:                                   \fIenter RANDOM here\fP
Verifying password
New Password:                                   \fIenter RANDOM here\fP
Random password [y] ? \f(CBy\fP
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: \f(CBrcmd\fP
Instance: \f(CBwait\fP
<Not found>, Create [y] ?
Principal: rcmd, Instance: wait, kdc_key_ver: 1
New Password:                                   \fIenter RANDOM here\fP
Verifying password
New Password:                                   \fIenter RANDOM here\fP
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:                                 \fInull entry here will cause an exit\fP
.De
.H3 "Creating the Server File"
.P
We now have to extract all the instances which define the
services on each machine.  For this we use the
.Command ext_srvtab
command.  This will create a file which must be copied or moved \fIby secure
means\fP to each Kerberos client's
.File /etc/kerberosIV
directory.  This file must be present on each server and client, and is crucial
to the operation of Kerberos.
.Dx
# \f(CBext_srvtab wait\fP
Enter Kerberos master key:
Current Kerberos master key version is 1.
Master key entered. BEWARE!
Generating 'wait-new-srvtab'....
.De
Now, this command only generates a temporary file which must be
renamed to 
.File srvtab
so that all the servers can pick
it up.  Use the 
.Command mv
command to move it into place on
the original system:
.Dx
# \f(CBmv wait-new-srvtab srvtab\fP
.De
If the file is for a client system, and the network is not deemed safe, then
copy the \f(CIclient\fI-new-srvtab\fR to removable media and transport it by
secure physical means.  Be sure to rename it to
.File srvtab
in the client's
.File /etc/kerberosIV
directory, and make sure it is mode 600:
.Dx
# \f(CBmv grumble-new-srvtab srvtab\fP
# \f(CBchmod 600 srvtab\fP
.De
.SPUP
.H3 "Populating the Database"
We now have to add some user entries into the database.  First let us create an
entry for the user \f(CWjane\fP.  Use the
.Command kdb_edit
command to do this:
.Dx
# \f(CBkdb_edit\fP
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: \f(CBjane\fP
Instance:
<Not found>, Create [y] ? \f(CBy\fP
Principal: jane, Instance: , kdc_key_ver: 1
New Password:                                   \fIenter a secure password here\fP
Verifying password
New Password:                                   \fIre-enter the password here\fP
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:                                 \fInull entry here will cause an exit\fP
.De
.H3 "Testing It All Out"
.P
First we have to start the Kerberos daemons.  If you have edited your
.File /etc/rc.conf
correctly, this will happen automatically when you reboot.  This is only
necessary on the Kerberos server.  Kerberos clients will automatically get what
they need from the
.File /etc/kerberosIV
directory.
.Dx
# \f(CBkerberos &\fP
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: EXAMPLE.ORG
# \f(CBkadmind -n &\fP
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!
.De
Now we can try using the 
.Command kinit
command to get a
ticket for the id 
\f(CWjane\fP
that we created
above:
.Dx
$ \f(CBkinit jane\fP
MIT Project Athena (wait.example.org)
Kerberos Initialization for "jane"
Password: 
.De
Try listing the tokens using 
.Command klist
to see if we
really have them:
.Dx
$ \f(CBklist\fP
Ticket file:    /tmp/tkt245
Principal:      jane@EXAMPLE.ORG
  Issued           Expires          Principal
Apr 30 11:23:22  Apr 30 19:23:22  krbtgt.EXAMPLE.ORG@EXAMPLE.ORG
.De
Now try changing the password using 
.Command passwd
to
check if the 
.Daemon kpasswd
daemon can get 
authorization to the Kerberos database:
.Dx
$ \f(CBpasswd\fP
realm EXAMPLE.ORG
Old password for jane:
New Password for jane:
Verifying password
New Password for jane:
Password changed.
.De
.H3 "Adding su Privileges"
Kerberos allows us to give \fIeach\fP user who needs \f(CWroot\fP privileges
their own \fIseparate\fP
.Command su
password.  We could now add an id which is authorized to
.Command su
to \f(CWroot\fP.  This is controlled by having an instance of \f(CWroot\fP
associated with a principal.  Using
.Command kdb_edit
we can create the entry \f(CWjane.root\fP in the
Kerberos database:
.Dx
# \f(CBkdb_edit\fP
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: \f(CBjane\fP
Instance: \f(CBroot\fP
<Not found>, Create [y] ? y
Principal: jane, Instance: root, kdc_key_ver: 1
New Password:                                   \fIenter a SECURE password here\fP
Verifying password
New Password:                                   \fIre-enter the password here\fP
Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?
Max ticket lifetime (*5 minutes) [ 255 ] ? \f(CB12\fP   \fIKeep this short!\fP
Attributes [ 0 ] ?
Edit O.K.
Principal name:                                 \fInull entry here will cause an exit\fP
.De
Now try getting tokens for it to make sure it works:
.Dx
# \f(CBkinit jane.root\fP
MIT Project Athena (wait.example.org)
Kerberos Initialization for "jane.root"
Password:
.De
Now we need to add the user to \f(CWroot\fP's
.File .klogin
file:
.Dx
# \f(CBcat /root/.klogin\fP
jane.root@EXAMPLE.ORG
.De
Now try doing the 
.Command su
:
.Dx
$ \f(CBsu\fP
Password:
.De
and take a look at what tokens we have:
.Dx
# \f(CBklist\fP
Ticket file:    /tmp/tkt_root_245
Principal:      jane.root@EXAMPLE.ORG
  Issued           Expires          Principal
May  2 20:43:12  May  3 04:43:12  krbtgt.EXAMPLE.ORG@EXAMPLE.ORG
.De
.H3 "Using Other Commands"
.P
In an earlier example, we created a principal called \f(CWjane\fP with an
instance \f(CWroot\fP.  This was based on a user with the same name as the
principal, and this is a Kerberos default; that a \f(CW<principal>.<instance>\fP
of the form \f(CW<username>.\fP\f(CWroot\fP will allow that \f(CW<username>\fP
to
.Command su
to \f(CWroot\fP if the following entry is in the
.File .klogin
file in \f(CWroot\fP's home directory:
.Dx
jane.root@EXAMPLE.ORG
.De
Likewise, if a user has in their own 
.File ~/.klogin
lines of the form:
.Dx
jane@EXAMPLE.ORG
joe@EXAMPLE.ORG
.De
This allows anyone in the \fIexample.org\fP\| realm who has authenticated
themselves to \f(CWjane\fP or \f(CWjoe\fP (via
.Command kinit ,
see above) access to
.Command rlogin
to \f(CWjane\fP's
account or files on this system (\fIwait\fP) via
.Command rlogin , 
.Command rsh
or
.Command rcp .
.P
For example, \f(CWjane\fP now logs into another system using Kerberos:
.Dx
$ \f(CBkinit\fP
MIT Project Athena (wait.example.org)
Password:
$ \f(CBrlogin wait\fP
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
.De
Or Joe logs into Jane's account on the same machine (\f(CWjane\fP having set up
the
.File .klogin
file as above, and the person in charge of Kerberos having set up principal
\fIjoe\fP with a null instance:
.Dx
$ \f(CBkinit\fP 
$ \f(CBrlogin wait -l jane\fP 
MIT Project Athena (wait.example.org)
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
.De
.SPUP
