diff options
Diffstat (limited to 'crypto/heimdal/doc/setup.texi')
| -rw-r--r-- | crypto/heimdal/doc/setup.texi | 200 |
1 files changed, 194 insertions, 6 deletions
diff --git a/crypto/heimdal/doc/setup.texi b/crypto/heimdal/doc/setup.texi index a43eb7e..ed14306 100644 --- a/crypto/heimdal/doc/setup.texi +++ b/crypto/heimdal/doc/setup.texi @@ -1,6 +1,21 @@ +@c $Id: setup.texi,v 1.21 2001/01/29 04:39:46 assar 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 @@ usually the Internet domain name in uppercase. Call your realm the same 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 @@ If you use a realm name equal to your domain name, you can omit the 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 @@ krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... 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 @@ Version Type Principal 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 @@ Access to the admin server is controlled by an acl-file, (default @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 @@ The privileges you can assign to a principal are: @samp{add}, @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 @@ the patch available at 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 +@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 |
