[src/netbsd-1-5]: src/crypto/dist/heimdal/doc Pull up revisions 1.1.1.2-1.1.1...

[he <he%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/17c6f0f041b9
branches:  netbsd-1-5
changeset: 491183:17c6f0f041b9
user:      he <he%NetBSD.org@localhost>
date:      Thu Apr 05 23:32:43 2001 +0000

description:
Pull up revisions 1.1.1.2-1.1.1.3 (via patch, requested by assar):
  Upgrade Heimdal to version 0.3e.

diffstat:

 crypto/dist/heimdal/doc/setup.texi |  200 +++++++++++++++++++++++++++++++++++-
 1 files changed, 194 insertions(+), 6 deletions(-)

diffs (269 lines):

diff -r 4944788cea8c -r 17c6f0f041b9 crypto/dist/heimdal/doc/setup.texi
--- a/crypto/dist/heimdal/doc/setup.texi        Thu Apr 05 23:32:07 2001 +0000
+++ b/crypto/dist/heimdal/doc/setup.texi        Thu Apr 05 23:32:43 2001 +0000
@@ -1,6 +1,21 @@
+@c $Id: setup.texi,v 1.1.1.1.2.1 2001/04/05 23:32:43 he Exp $
+
 @node Setting up a realm, Things in search for a better place, Building and Installing, Top
+
 @chapter Setting up a realm
 
+@menu
+* Configuration file::          
+* Creating the database::       
+* keytabs::                     
+* Remote administration::       
+* Password changing::           
+* Testing clients and servers::  
+* Slave Servers::               
+* Incremental propagation::     
+* Salting::
+@end menu
+
 A
 @cindex realm
 realm is an administrative domain.  The name of a Kerberos realm is
@@ -8,6 +23,7 @@
 as your Internet domain name if you do not have strong reasons for not
 doing so.  It will make life easier for you and everyone else.
 
+@node  Configuration file, Creating the database, Setting up a realm, Setting up a realm
 @section Configuration file
 
 To setup a realm you will first have to create a configuration file:
@@ -77,6 +93,7 @@
 SRV-record for your realm, or your kerberos server has CNAME called
 @samp{kerberos.my.realm}, you can omit the @samp{realms} section too.
 
+@node Creating the database, keytabs, Configuration file, Setting up a realm
 @section Creating the database
 
 The database library will look for the database in @file{/var/heimdal},
@@ -148,15 +165,16 @@
 kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ...
 @end smallexample
 
+@node keytabs, Remote administration, Creating the database, Setting up a realm
 @section keytabs
 
 To extract a service ticket from the database and put it in a keytab you
 need to first create the principal in the database with @samp{ank}
-(using the @kbd{--random} flag to get a random password) and then
+(using the @kbd{--random-key} flag to get a random key) and then
 extract it with @samp{ext_keytab}.
 
 @example
-kadmin> add --random host/my.host.name
+kadmin> add --random-key host/my.host.name
 Max ticket life [unlimited]:
 Max renewable life [unlimited]:
 Attributes []:
@@ -169,11 +187,13 @@
      1   des3-cbc-sha1    host/my.host.name@@MY.REALM
 @end example
 
+@node Remote administration, Password changing, keytabs, Setting up a realm
 @section Remote administration
 
-The administration server, @samp{kadmind}, is started by @samp{inetd}
-and you should add a line similar to the one below to your
-@file{/etc/inetd.conf}.
+The administration server, @samp{kadmind}, can be started by
+@samp{inetd} (which isn't recommended) or run as a normal daemon. If you
+want to start it from @samp{inetd} you should add a line similar to the
+one below to your @file{/etc/inetd.conf}.
 
 @example
 kerberos-adm stream     tcp     nowait  root /usr/heimdal/libexec/kadmind kadmind
@@ -186,7 +206,7 @@
 @file{/var/heimdal/kadmind.acl}.) The lines in the access file, has the
 following syntax:
 @smallexample
-principal       [priv1,priv2,...]
+principal       [priv1,priv2,...]       [glob-pattern]
 @end smallexample
 
 The privileges you can assign to a principal are: @samp{add},
@@ -195,6 +215,26 @@
 @samp{all}. All of these roughly corresponds to the different commands
 in @samp{kadmin}.
 
+If a @var{glob-pattern} is given on a line, it restricts the right for
+the principal to only apply for the subjects that match the pattern.
+The patters are of the same type as those used in shell globbing, see
+@url{none,,fnmatch(3)}.
+
+In the example below @samp{lha/admin} can change every principal in the
+database. @samp{jimmy/admin} can only modify principals that belong to
+the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the
+helpdesk, so he should only be able to change the passwords for single
+component principals (ordinary users). He will not be able to change any
+@samp{/admin} principal.
+
+@example
+lha/admin@@E.KTH.SE    all
+jimmy/admin@@E.KTH.SE  all             *@@E.KTH.SE
+jimmy/admin@@E.KTH.SE  all             */*@@E.KTH.SE
+mille/admin@@E.KTH.SE  change-password *@@E.KTH.SE
+@end example
+
+@node Password changing, Testing clients and servers, Remote administration, Setting up a realm
 @section Password changing
 
 To allow users to change their passwords, you should run @samp{kpasswdd}.
@@ -241,7 +281,155 @@
 If no password quality checking function is configured, it is only
 verified that it is at least six characters of length.
 
+@node Testing clients and servers, Slave Servers, Password changing, Setting up a realm
 @section Testing clients and servers
 
 Now you should be able to run all the clients and servers.  Refer to the
 appropriate man pages for information on how to use them.
+
+@node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm
+@section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm
+
+It is desirable to have at least one backup (slave) server in case the
+master server fails. It is possible to have any number of such slave
+servers but more than three usually doesn't buy much more redundancy.
+
+All Kerberos servers for a realm shall have the same database so that
+they present the same service to all the users.  The
+@pindex hprop
+@code{hprop} program, running on the master, will propagate the database
+to the slaves, running
+@pindex hpropd
+@code{hpropd} processes.
+
+Every slave needs a keytab with a principal,
+@samp{hprop/@var{hostname}}.  Add that with the
+@pindex ktutil
+@code{ktutil} command and start
+@pindex hpropd
+@code{propd}, as follows:
+
+@example
+slave# ktutil get -p foo/admin host/`hostname`
+slave# hpropd
+@end example
+
+The master will use the principal @samp{kadmin/hprop} to authenticate to
+the slaves.  This principal should be added when running @kbd{kadmin -l
+init} but if you do not have it in your database for whatever reason,
+please add it with @kbd{kadmin -l add}.
+
+Then run
+@pindex hprop
+@code{hprop} on the master:
+
+@example
+master# hprop slave
+@end example
+
+This was just an on-hands example to make sure that everything was
+working properly.  Doing it manually is of course the wrong way and to
+automate this you will want to start
+@pindex hpropd
+@code{hpropd} from @code{inetd} on the slave(s) and regularly run
+@pindex hprop
+@code{hprop} on the master to regularly propagate the database.
+Starting the propagation once an hour from @code{cron} is probably a
+good idea.
+
+@node Incremental propagation, Salting , Slave Servers, Setting up a realm
+@section Incremental propagation
+
+There is also a newer and still somewhat experimental mechanism for
+doing incremental propagation in Heimdal.  Instead of sending the whole
+database regularly, it sends the changes as they happen on the master to
+the slaves.  The master keeps track of all the changes by assigned a
+version number to every change to the database.  The slaves know which
+was the latest version they saw and in this way it can be determined if
+they are in sync or not.  A log of all the changes is kept on the master
+and when a slave is at an older versioner than the oldest one in the
+log, the whole database has to be sent.
+
+Protocol-wise, all the slaves connects to the master and as a greeting
+tell it the latest version that they have (@samp{IHAVE} message).  The
+master then responds by sending all the changes between that version and
+the current version at the master (a series of @samp{FORYOU} messages)
+or the whole database in a @samp{TELLYOUEVERYTHING} message.
+
+@subsection Configuring incremental propagation
+
+The program that runs on the master is @code{ipropd-master} and all
+clients run @code{ipropd-slave}.
+
+Create the file @file{/var/heimdal/slaves} on the master containing all
+the slaves that the database should be propagated to.  Each line contains
+the full name of the principal (for example
+@samp{iprop/hemligare.foo.se@@FOO.SE}).
+
+You should already have @samp{iprop/tcp} defined as 2121, in your
+@file{/etc/services}.  Otherwise, or if you need to use a different port
+for some peculiar reason, you can use the @kbd{--port} option.  This is
+useful when you have multiple realms to distribute from one server.
+
+Then you need to create these principals that you added in the
+configuration file.  Create one @samp{iprop/hostname} for the master and
+for every slave.
+
+
+@example
+master# /usr/heimdal/sbin/ktutil get iprop/`hostname`
+@end example
+
+The next step is to start the @code{ipropd-master} process on the master
+server.  The @code{ipropd-master} listens on the UNIX-socket
+@file{/var/heimdal/signal} to know when changes have been made to the
+database so they can be propagated to the slaves.  There is also a
+safety feature of testing the version number regularly (every 30
+seconds) to see if it has been modified by some means that do not raise
+this signal.  Then, start @code{ipropd-slave} on all the slaves:
+
+@example
+master# /usr/heimdal/libexec/ipropd-master &
+slave#  /usr/heimdal/libexec/ipropd-slave master &
+@end example
+
+@node Salting, , Incremental propagation, Setting up a realm
+@section Salting
+@cindex Salting
+
+Salting is used to make it harder to precalculate all possible
+keys. Using a salt increases the search space to make it almost
+impossible to precalculate all keys. In salting you just append the salt
+to the password, or somehow merge the password with the salt.
+
+In Kerberos 5 the salting is determined by the encryption-type, except
+in case of @code{des}. In @code{des} there is the kerberos 4 salting
+(none at all) or the afs-salting (using the cell (realm in
+afs-lingo)). @code{[kadmin]default_keys} in @file{krb5.conf} controls
+what salting to use,
+
+The syntax of @code{[kadmin]default_keys} is
+@samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption
+type (des, des3, arcfour), @code{salt-type} is the type of salt (pw-salt
+or afs3-salt), and the salt-string is the string that will be used as
+salt (remember that if the salt is appened/prepended, the empty salt ""
+is the same thing as no salt at all).
+
+Common types of salting includes
+
+@itemize @bullet
+@item @code{v4} (or @code{des:pw-salt:})
+
+The Kerberos 4 salting is using no salt att all. Reson there is colon
+that the end is that 
+
+@item @code{v5} (or @code{pw-salt})
+
+@code{pw-salt} means all regular encryption-types that is regular 
+
+@item @code{afs3-salt}
+
+@code{afs3-salt} is the salting that is used with Transarc kaserver. Its
+the cell appended to the password.
+
+@end itemize