"Fossies" - the Fresh Open Source Software Archive

Member "heimdal-7.7.0/doc/setup.texi" (7 Jun 2019, 61727 Bytes) of package /linux/misc/heimdal-7.7.0.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 @c $Id$
    2 
    3 @node Setting up a realm, Applications, Building and Installing, Top
    4 
    5 @chapter Setting up a realm
    6 
    7 A
    8 @cindex realm
    9 realm is an administrative domain.  The name of a Kerberos realm is
   10 usually the Internet domain name in uppercase.  Call your realm the same
   11 as your Internet domain name if you do not have strong reasons for not
   12 doing so.  It will make life easier for you and everyone else.
   13 
   14 @menu
   15 * Configuration file::
   16 * Creating the database::
   17 * Modifying the database::
   18 * Checking the setup::
   19 * keytabs::
   20 * Remote administration::
   21 * Password changing::
   22 * Testing clients and servers::
   23 * Slave Servers::
   24 * Incremental propagation::
   25 * Encryption types and salting::
   26 * Credential cache server - KCM::
   27 * Cross realm::
   28 * Transit policy::
   29 * Setting up DNS::
   30 * Using LDAP to store the database::
   31 * Providing Kerberos credentials to servers and programs::
   32 * Setting up PK-INIT::
   33 * Debugging Kerberos problems::
   34 @end menu
   35 
   36 @node  Configuration file, Creating the database, Setting up a realm, Setting up a realm
   37 @section Configuration file
   38 
   39 To setup a realm you will first have to create a configuration file:
   40 @file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many
   41 configuration options, some of which are described here.
   42 
   43 There is a sample @file{krb5.conf} supplied with the distribution.
   44 
   45 The configuration file is a hierarchical structure consisting of
   46 sections, each containing a list of bindings (either variable
   47 assignments or subsections). A section starts with
   48 @samp{[@samp{section-name}]}.  A binding consists of a left hand side, an equal sign
   49 (@samp{=}) and a right hand side (the left hand side tag must be
   50 separated from the equal sign with some whitespace). Subsections have a
   51 @samp{@{} as the first non-whitespace character after the equal sign. All
   52 other bindings are treated as variable assignments. The value of a
   53 variable extends to the end of the line.
   54 
   55 @example
   56 [section1]
   57         a-subsection = @{
   58                 var = value1
   59                 other-var = value with @{@}
   60                 sub-sub-section = @{
   61                         var = 123
   62                 @}
   63         @}
   64         var = some other value
   65 [section2]
   66         var = yet another value
   67 @end example
   68 
   69 In this manual, names of sections and bindings will be given as strings
   70 separated by slashes (@samp{/}). The @samp{other-var} variable will thus
   71 be @samp{section1/a-subsection/other-var}.
   72 
   73 For in-depth information about the contents of the configuration file, refer to
   74 the @file{krb5.conf} manual page. Some of the more important sections
   75 are briefly described here.
   76 
   77 The @samp{libdefaults} section contains a list of library configuration
   78 parameters, such as the default realm and the timeout for KDC
   79 responses. The @samp{realms} section contains information about specific
   80 realms, such as where they hide their KDC@. This section serves the same
   81 purpose as the Kerberos 4 @file{krb.conf} file, but can contain more
   82 information. Finally the @samp{domain_realm} section contains a list of
   83 mappings from domains to realms, equivalent to the Kerberos 4
   84 @file{krb.realms} file.
   85 
   86 To continue with the realm setup, you will have to create a configuration file,
   87 with contents similar to the following.
   88 
   89 @example
   90 [libdefaults]
   91         default_realm = MY.REALM
   92 [realms]
   93         MY.REALM = @{
   94                 kdc = my.kdc my.slave.kdc
   95                 kdc = my.third.kdc
   96                 kdc = 130.237.237.17
   97                 kdc = [2001:6b0:1:ea::100]:88
   98         @}
   99 [domain_realm]
  100         .my.domain = MY.REALM
  101 
  102 @end example
  103 
  104 If you use a realm name equal to your domain name, you can omit the
  105 @samp{libdefaults}, and @samp{domain_realm}, sections. If you have a DNS
  106 SRV-record for your realm, or your Kerberos server has DNS CNAME
  107 @samp{kerberos.my.realm}, you can omit the @samp{realms} section too.
  108 
  109 @cindex KRB5_CONFIG
  110 If you want to use a different configuration file then the default you
  111 can point a file with the environment variable @samp{KRB5_CONFIG}.
  112 
  113 @example
  114 env KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM
  115 @end example
  116 
  117 @node Creating the database, Modifying the database, Configuration file, Setting up a realm
  118 @section Creating the database
  119 
  120 The database library will look for the database in the directory
  121 @file{@value{dbdir}}, so you should probably create that directory.
  122 Make sure the directory has restrictive permissions.
  123 
  124 @example
  125 # mkdir /var/heimdal
  126 # chmod og-rwx /var/heimdal
  127 @end example
  128 
  129 Heimdal supports various database backends: lmdb (LMDB), db3 (Berkeley
  130 DB 3.x, 4.x, or 5.x), db1 (Berkeley DB 2.x), sqlite (SQLite3), and ldap
  131 (LDAP).  The default is @value{dbtype}, and is selected at build time
  132 from one of lmdb, db3, or db1.
  133 
  134 These defaults can be overriden in the 'database' key in the @samp{kdc}
  135 section of the configuration.
  136 
  137 @example
  138 [kdc]
  139         database = @{
  140                 dbname = lmdb:/path/to/db-file
  141                 realm = REALM
  142                 acl_file = /path/to/kadmind.acl
  143                 mkey_file = /path/to/mkey
  144                 log_file = /path/to/iprop-log-file
  145         @}
  146 @end example
  147 
  148 To use LDAP, see @xref{Using LDAP to store the database}.
  149 
  150 The keys of all the principals are stored in the database.  If you
  151 choose to, these can be encrypted with a master key.  You do not have to
  152 remember this key (or password), but just to enter it once and it will
  153 be stored in a file (@file{/var/heimdal/m-key}).  If you want to have a
  154 master key, run @samp{kstash} to create this master key:
  155 
  156 @example
  157 # kstash
  158 Master key:
  159 Verifying password - Master key:
  160 @end example
  161 
  162 If you want to generate a random master key you can use the
  163 @kbd{--random-key} flag to kstash. This will make sure you have a good key
  164 on which attackers can't do a dictionary attack.
  165 
  166 If you have a master key, make sure you make a backup of your master
  167 key file; without it backups of the database are of no use.
  168 
  169 To initialise the database use the @command{kadmin} program, with the
  170 @kbd{-l} option (to enable local database mode). First issue a
  171 @kbd{init MY.REALM} command. This will create the database and insert
  172 default principals for that realm. You can have more than one realm in
  173 one database, so @samp{init} does not destroy any old database.
  174 
  175 Before creating the database, @samp{init} will ask you some questions
  176 about maximum ticket lifetimes.
  177 
  178 After creating the database you should probably add yourself to it. You
  179 do this with the @samp{add} command. It takes as argument the name of a
  180 principal. The principal should contain a realm, so if you haven't set up
  181 a default realm, you will need to explicitly include the realm.
  182 
  183 @example
  184 # kadmin -l
  185 kadmin> init MY.REALM
  186 Realm max ticket life [unlimited]:
  187 Realm max renewable ticket life [unlimited]:
  188 kadmin> add me
  189 Max ticket life [unlimited]:
  190 Max renewable life [unlimited]:
  191 Attributes []:
  192 Password:
  193 Verifying password - Password:
  194 @end example
  195 
  196 Now start the KDC and try getting a ticket.
  197 
  198 @example
  199 # kdc &
  200 # kinit me
  201 me@@MY.REALMS's Password:
  202 # klist
  203 Credentials cache: /tmp/krb5cc_0
  204         Principal: me@@MY.REALM
  205 
  206   Issued           Expires          Principal
  207 Aug 25 07:25:55  Aug 25 17:25:55  krbtgt/MY.REALM@@MY.REALM
  208 @end example
  209 
  210 If you are curious you can use the @samp{dump} command to list all the
  211 entries in the database.  It should look something similar to the
  212 following example (note that the entries here are truncated for
  213 typographical reasons):
  214 
  215 @smallexample
  216 kadmin> dump
  217 me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ...
  218 kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ...
  219 krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ...
  220 kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ...
  221 @end smallexample
  222 
  223 @node Modifying the database, Checking the setup, Creating the database, Setting up a realm
  224 @section Modifying the database
  225 
  226 All modifications of principals are done with with kadmin.
  227 
  228 A principal has several attributes and lifetimes associated with it.
  229 
  230 Principals are added, renamed, modified, and deleted with the kadmin
  231 commands @samp{add}, @samp{rename}, @samp{modify}, @samp{delete}.
  232 Both interactive editing and command line flags can be used (use --help
  233 to list the available options).
  234 
  235 There are different kinds of types for the fields in the database;
  236 attributes, absolute time times and relative times.
  237 
  238 @subsection Attributes
  239 
  240 When doing interactive editing, attributes are listed with @samp{?}.
  241 
  242 The attributes are given in a comma (@samp{,}) separated list.
  243 Attributes are removed from the list by prefixing them with @samp{-}.
  244 
  245 @smallexample
  246 kadmin> modify me
  247 Max ticket life [1 day]:
  248 Max renewable life [1 week]:
  249 Principal expiration time [never]:
  250 Password expiration time [never]:
  251 Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable
  252 kadmin> get me
  253             Principal: me@@MY.REALM
  254 [...]
  255            Attributes: requires-pre-auth
  256 @end smallexample
  257 
  258 @subsection Absolute times
  259 
  260 The format for absolute times are any of the following:
  261 
  262 @smallexample
  263 never
  264 now
  265 YYYY-mm-dd
  266 YYYY-mm-dd HH:MM:SS
  267 @end smallexample
  268 
  269 
  270 @subsection Relative times
  271 
  272 The format for relative times are any of the following combined:
  273 
  274 @smallexample
  275 N year
  276 M month
  277 O day
  278 P hour
  279 Q minute
  280 R second
  281 @end smallexample
  282 
  283 @c Describe more of kadmin commands here...
  284 
  285 @node Checking the setup, keytabs, Modifying the database, Setting up a realm
  286 @section Checking the setup
  287 
  288 There are two tools that can check the consistency of the Kerberos
  289 configuration file and the Kerberos database.
  290 
  291 The Kerberos configuration file is checked using
  292 @command{verify_krb5_conf}. The tool checks for common errors, but
  293 commonly there are several uncommon configuration entries that are
  294 never added to the tool and thus generates ``unknown entry'' warnings.
  295 This is usually nothing to worry about.
  296 
  297 The database check is built into the kadmin tool. It will check for
  298 common configuration error that will cause problems later. Common
  299 check are for existence and flags on important principals. The
  300 database check by run by the following command :
  301 
  302 @example
  303 kadmin -l check REALM.EXAMPLE.ORG
  304 @end example
  305 
  306 @node keytabs, Remote administration, Checking the setup, Setting up a realm
  307 @section keytabs
  308 
  309 To extract a service ticket from the database and put it in a keytab, you
  310 need to first create the principal in the database with @samp{add}
  311 (using the @kbd{--random-key} flag to get a random key) and then
  312 extract it with @samp{ext_keytab}.
  313 
  314 @example
  315 kadmin> add --random-key host/my.host.name
  316 Max ticket life [unlimited]:
  317 Max renewable life [unlimited]:
  318 Attributes []:
  319 kadmin> ext host/my.host.name
  320 kadmin> exit
  321 # ktutil list
  322 Version  Type             Principal
  323      1   des-cbc-md5      host/my.host.name@@MY.REALM
  324      1   des-cbc-md4      host/my.host.name@@MY.REALM
  325      1   des-cbc-crc      host/my.host.name@@MY.REALM
  326      1   des3-cbc-sha1    host/my.host.name@@MY.REALM
  327 @end example
  328 
  329 @node Remote administration, Password changing, keytabs, Setting up a realm
  330 @section Remote administration
  331 
  332 The administration server, @command{kadmind}, can be started by
  333 @command{inetd} (which isn't recommended) or run as a normal daemon. If you
  334 want to start it from @command{inetd} you should add a line similar to the
  335 one below to your @file{/etc/inetd.conf}.
  336 
  337 @example
  338 kerberos-adm stream     tcp     nowait  root /usr/heimdal/libexec/kadmind kadmind
  339 @end example
  340 
  341 You might need to add @samp{kerberos-adm} to your @file{/etc/services}
  342 as @samp{749/tcp}.
  343 
  344 Access to the administration server is controlled by an ACL file,
  345 (default @file{/var/heimdal/kadmind.acl}.) The file has the following
  346 syntax:
  347 @smallexample
  348 principal       [priv1,priv2,...]       [glob-pattern]
  349 @end smallexample
  350 
  351 The matching is from top to bottom for matching principals (and if given,
  352 glob-pattern).  When there is a match, the access rights of that line are
  353 applied.
  354 
  355 The privileges you can assign to a principal are: @samp{add},
  356 @samp{change-password} (or @samp{cpw} for short), @samp{delete},
  357 @samp{get}, @samp{list}, and @samp{modify}, or the special privilege
  358 @samp{all}. All of these roughly correspond to the different commands
  359 in @command{kadmin}.
  360 
  361 If a @var{glob-pattern} is given on a line, it restricts the access
  362 rights for the principal to only apply for subjects that match the
  363 pattern.  The patterns are of the same type as those used in shell
  364 globbing, see @url{none,,fnmatch(3)}.
  365 
  366 In the example below @samp{lha/admin} can change every principal in the
  367 database. @samp{jimmy/admin} can only modify principals that belong to
  368 the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the
  369 help desk, so he should only be able to change the passwords for single
  370 component principals (ordinary users). He will not be able to change any
  371 @samp{/admin} principal.
  372 
  373 @example
  374 lha/admin@@E.KTH.SE	all
  375 jimmy/admin@@E.KTH.SE	all		*@@E.KTH.SE
  376 jimmy/admin@@E.KTH.SE	all		*/*@@E.KTH.SE
  377 mille/admin@@E.KTH.SE	change-password	*@@E.KTH.SE
  378 @end example
  379 
  380 @node Password changing, Testing clients and servers, Remote administration, Setting up a realm
  381 @section Password changing
  382 
  383 To allow users to change their passwords, you should run @command{kpasswdd}.
  384 It is not run from @command{inetd}.
  385 
  386 You might need to add @samp{kpasswd} to your @file{/etc/services} as
  387 @samp{464/udp}.  If your realm is not setup to use DNS, you might also
  388 need to add a @samp{kpasswd_server} entry to the realm configuration
  389 in @file{/etc/krb5.conf} on client machines:
  390 
  391 @example
  392 [realms]
  393         MY.REALM = @{
  394                 kdc = my.kdc my.slave.kdc
  395                 kpasswd_server = my.kdc
  396         @}
  397 @end example
  398 
  399 @subsection Password quality assurance
  400 
  401 It is important that users have good passwords, both to make it harder
  402 to guess them and to avoid off-line attacks (although
  403 pre-authentication provides some defence against off-line attacks).
  404 To ensure that the users choose good passwords, you can enable
  405 password quality controls in @command{kpasswdd} and @command{kadmind}.
  406 The controls themselves are done in a shared library or an external
  407 program that is used by @command{kpasswdd}.  To configure in these
  408 controls, add lines similar to the following to your
  409 @file{/etc/krb5.conf}:
  410 
  411 @example
  412 [password_quality]
  413 	policies = external-check builtin:minimum-length modulename:policyname
  414 	external_program = /bin/false
  415 	policy_libraries = @var{library1.so} @var{library2.so}
  416 @end example
  417 
  418 In @samp{[password_quality]policies} the module name is optional if
  419 the policy name is unique in all modules (members of
  420 @samp{policy_libraries}).  All built-in policies can be qualified with
  421 a module name of @samp{builtin} to unambiguously specify the built-in
  422 policy and not a policy by the same name from a loaded module.
  423 
  424 The built-in policies are
  425 
  426 @itemize @bullet
  427 
  428 @item external-check
  429 
  430 Executes the program specified by @samp{[password_quality]external_program}.
  431 
  432 A number of key/value pairs are passed as input to the program, one per
  433 line, ending with the string @samp{end}.  The key/value lines are of
  434 the form
  435 @example
  436 principal: @var{principal}
  437 new-password: @var{password}
  438 @end example
  439 where @var{password} is the password to check for the previous
  440 @var{principal}.
  441 
  442 If the external application approves the password, it should return
  443 @samp{APPROVED} on standard out and exit with exit code 0.  If it
  444 doesn't approve the password, an one line error message explaining the
  445 problem should be returned on standard error and the application
  446 should exit with exit code 0.  In case of a fatal error, the
  447 application should, if possible, print an error message on standard
  448 error and exit with a non-zero error code.
  449 
  450 @item minimum-length
  451 
  452 The minimum length password quality check reads the configuration file
  453 stanza @samp{[password_quality]min_length} and requires the password
  454 to be at least this length.
  455 
  456 @item character-class
  457 
  458 The character-class password quality check reads the configuration
  459 file stanza @samp{[password_quality]min_classes}. The policy requires
  460 the password to have characters from at least that many character
  461 classes. Default value if not given is 3.
  462 
  463 The four different characters classes are, uppercase, lowercase,
  464 number, special characters.
  465 
  466 @end itemize
  467 
  468 If you want to write your own shared object to check password
  469 policies, see the manual page @manpage{kadm5_pwcheck,3}.
  470 
  471 Code for a password quality checking function that uses the cracklib
  472 library can be found in @file{lib/kadm5/sample_password_check.c} in
  473 the source code distribution.  It requires that the cracklib library
  474 be built with the patch available at
  475 @url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}.
  476 
  477 A sample policy external program is included in
  478 @file{lib/kadm5/check-cracklib.pl}.
  479 
  480 If no password quality checking function is configured, the only check
  481 performed is that the password is at least six characters long.
  482 
  483 To check the password policy settings, use the command
  484 @command{verify-password-quality} in @command{kadmin} program. The password
  485 verification is only performed locally, on the client.  It may be
  486 convenient to set the environment variable @samp{KRB5_CONFIG} to point
  487 to a test version of @file{krb5.conf} while you're testing the
  488 @samp{[password_quality]} stanza that way.
  489 
  490 @node Testing clients and servers, Slave Servers, Password changing, Setting up a realm
  491 @section Testing clients and servers
  492 
  493 Now you should be able to run all the clients and servers.  Refer to the
  494 appropriate man pages for information on how to use them.
  495 
  496 @node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm
  497 @section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm
  498 
  499 It is desirable to have at least one backup (slave) server in case the
  500 master server fails. It is possible to have any number of such slave
  501 servers but more than three usually doesn't buy much more redundancy.
  502 
  503 All Kerberos servers for a realm must have the same database so that
  504 they present the same service to the users.  The
  505 @pindex hprop
  506 @command{hprop} program, running on the master, will propagate the database
  507 to the slaves, running
  508 @pindex hpropd
  509 @command{hpropd} processes.
  510 
  511 Every slave needs a database directory, the master key (if it was used
  512 for the database) and a keytab with the principal
  513 @samp{hprop/@var{hostname}}.  Add the principal with the
  514 @pindex ktutil
  515 @command{ktutil} command and start
  516 @pindex hpropd
  517 @command{hpropd}, as follows:
  518 
  519 @example
  520 slave# ktutil get -p foo/admin hprop/`hostname`
  521 slave# mkdir /var/heimdal
  522 slave# hpropd
  523 @end example
  524 
  525 The master will use the principal @samp{kadmin/hprop} to authenticate to
  526 the slaves.  This principal should be added when running @kbd{kadmin -l
  527 init} but if you do not have it in your database for whatever reason,
  528 please add it with @kbd{kadmin -l add}.
  529 
  530 Then run
  531 @pindex hprop
  532 @code{hprop} on the master:
  533 
  534 @example
  535 master# hprop slave
  536 @end example
  537 
  538 This was just an hands-on example to make sure that everything was
  539 working properly.  Doing it manually is of course the wrong way, and to
  540 automate this you will want to start
  541 @pindex hpropd
  542 @command{hpropd} from @command{inetd} on the slave(s) and regularly run
  543 @pindex hprop
  544 @command{hprop} on the master to regularly propagate the database.
  545 Starting the propagation once an hour from @command{cron} is probably a
  546 good idea.
  547 
  548 @node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm
  549 @section Incremental propagation
  550 
  551 There is also a newer mechanism for
  552 doing incremental propagation in Heimdal.  Instead of sending the whole
  553 database regularly, it sends the changes as they happen on the master to
  554 the slaves.  The master keeps track of all the changes by assigning a
  555 version number to every change to the database.  The slaves know which
  556 was the latest version they saw and in this way it can be determined if
  557 they are in sync or not.  A log of all the changes is kept on the master,
  558 and when a slave is at an older version than the oldest one in the
  559 log, the whole database has to be sent.
  560 
  561 Protocol-wise, all the slaves connect to the master and as a greeting
  562 tell it the latest version that they have (@samp{IHAVE} message).  The
  563 master then responds by sending all the changes between that version and
  564 the current version at the master (a series of @samp{FORYOU} messages)
  565 or the whole database in a @samp{TELLYOUEVERYTHING} message.  There is
  566 also a keep-alive protocol that makes sure all slaves are up and running.
  567 
  568 In addition on listening on the network to get connection from new
  569 slaves, the ipropd-master also listens on a status unix
  570 socket. kadmind and kpasswdd both open that socket when a transation
  571 is done and written a notification to the socket. That cause
  572 ipropd-master to check for new version in the log file. As a fallback in
  573 case a notification is lost by the unix socket, the log file is
  574 checked after 30 seconds of no event.
  575 
  576 @subsection Configuring incremental propagation
  577 
  578 The program that runs on the master is @command{ipropd-master} and all
  579 clients run @command{ipropd-slave}.
  580 
  581 Create the file @file{/var/heimdal/slaves} on the master containing all
  582 the slaves that the database should be propagated to.  Each line contains
  583 the full name of the principal (for example
  584 @samp{iprop/hemligare.foo.se@@FOO.SE}).
  585 
  586 You should already have @samp{iprop/tcp} defined as 2121, in your
  587 @file{/etc/services}.  Otherwise, or if you need to use a different port
  588 for some peculiar reason, you can use the @kbd{--port} option.  This is
  589 useful when you have multiple realms to distribute from one server.
  590 
  591 Then you need to create those principals that you added in the
  592 configuration file.  Create one @samp{iprop/hostname} for the master and
  593 for every slave.
  594 
  595 
  596 @example
  597 master# /usr/heimdal/sbin/ktutil get iprop/`hostname`
  598 @end example
  599 
  600 @example
  601 slave# /usr/heimdal/sbin/ktutil get iprop/`hostname`
  602 @end example
  603 
  604 
  605 The next step is to start the @command{ipropd-master} process on the master
  606 server.  The @command{ipropd-master} listens on the UNIX domain socket
  607 @file{/var/heimdal/signal} to know when changes have been made to the
  608 database so they can be propagated to the slaves.  There is also a
  609 safety feature of testing the version number regularly (every 30
  610 seconds) to see if it has been modified by some means that do not raise
  611 this signal.  Then, start @command{ipropd-slave} on all the slaves:
  612 
  613 @example
  614 master# /usr/heimdal/libexec/ipropd-master &
  615 slave#  /usr/heimdal/libexec/ipropd-slave master &
  616 @end example
  617 
  618 To manage the iprop log file you should use the @command{iprop-log}
  619 command. With it you can dump, truncate and replay the logfile.
  620 
  621 @subsection Status of iprop master and slave
  622 
  623 Both the master and slave provides status of the world as they see it.
  624 
  625 The master write outs the current status of the slaves, last seen and
  626 their version number in @file{/var/heimdal/slaves-stats}.
  627 
  628 The slave write out the current status in @file{/var/heimdal/ipropd-slave-status}.
  629 
  630 These locations can be changed with command line options, and in the
  631 case of @command{ipropd_master}, the configuration file.
  632 
  633 @node Encryption types and salting, Credential cache server - KCM, Incremental propagation, Setting up a realm
  634 @section Encryption types and salting
  635 @cindex Salting
  636 @cindex Encryption types
  637 
  638 The encryption types that the KDC is going to assign by default is
  639 possible to change. Since the keys used for user authentication is
  640 salted the encryption types are described together with the salt
  641 strings.
  642 
  643 Salting is used to make it harder to pre-calculate all possible
  644 keys. Using a salt increases the search space to make it almost
  645 impossible to pre-calculate all keys. Salting is the process of mixing a
  646 public string (the salt) with the password, then sending it through an
  647 encryption type specific string-to-key function that will output the
  648 fixed size encryption key.
  649 
  650 In Kerberos 5 the salt is determined by the encryption type, except in
  651 some special cases.
  652 
  653 In @code{des} there is the Kerberos 4 salt
  654 (none at all) or the afs-salt (using the cell (realm in
  655 AFS lingo)).
  656 
  657 In @code{arcfour} (the encryption type that Microsoft Windows 2000 uses)
  658 there is no salt. This is to be compatible with NTLM keys in Windows
  659 NT 4.
  660 
  661 @code{[kadmin]default_keys} in @file{krb5.conf} controls
  662 what salting to use.
  663 
  664 The syntax of @code{[kadmin]default_keys} is
  665 @samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption
  666 type (des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96),
  667 @code{salt-type} is the type of salt (pw-salt or afs3-salt), and the
  668 salt-string is the string that will be used as salt (remember that if
  669 the salt is appended/prepended, the empty salt "" is the same thing as
  670 no salt at all).
  671 
  672 Common types of salting include
  673 
  674 @itemize @bullet
  675 @item @code{v4} (or @code{des:pw-salt:})
  676 
  677 The Kerberos 4 salting is using no salt at all. Reason there is colon
  678 at the end of the salt string is that it makes the salt the empty
  679 string (same as no salt).
  680 
  681 @item @code{v5} (or @code{pw-salt})
  682 
  683 @code{pw-salt} uses the default salt for each encryption type is
  684 specified for. If the encryption type @samp{etype} isn't given, all
  685 default encryption will be used.
  686 
  687 @item @code{afs3-salt}
  688 
  689 @code{afs3-salt} is the salt that is used with Transarc kaserver. It's
  690 the cell name appended to the password.
  691 
  692 @end itemize
  693 
  694 @node Credential cache server - KCM, Cross realm, Encryption types and salting, Setting up a realm
  695 @section Credential cache server - KCM
  696 @cindex KCM
  697 @cindex Credential cache server
  698 
  699 When KCM running is easy for users to switch between different
  700 kerberos principals using @file{kswitch} or built in support in
  701 application, like OpenSSH's GSSAPIClientIdentity.
  702 
  703 Other advantages are that there is the long term credentials are not
  704 written to disk and on reboot the credential is removed when kcm
  705 process stopps running.
  706 
  707 Configure the system startup script to start the kcm process,
  708 @file{/usr/heimdal/libexec/kcm} and then configure the system to use kcm in @file{krb5.conf}.
  709 
  710 @example
  711 [libdefaults]
  712 	default_cc_type = KCM
  713 @end example
  714 
  715 Now when you run @command{kinit} it doesn't overwrite your existing
  716 credentials but rather just add them to the set of
  717 credentials. @command{klist -l} lists the credentials and the star
  718 marks the default credential.
  719 
  720 @example
  721 $ kinit lha@@KTH.SE
  722 lha@@KTH.SE's Password: 
  723 $ klist -l
  724   Name         Cache name               Expires         
  725 lha@@KTH.SE   0                        Nov 22 23:09:40   *
  726 lha@@SU.SE    Initial default ccache   Nov 22 14:14:24   
  727 @end example
  728 
  729 When switching between credentials you can use @command{kswitch}.
  730 
  731 @example
  732 $ kswitch -i
  733      Principal
  734 1    lha@@KTH.SE
  735 2    lha@@SU.SE
  736 Select number: 2
  737 @end example
  738 
  739 After switching, a new set of credentials are used as default.
  740 
  741 @example
  742 $ klist -l
  743   Name         Cache name               Expires         
  744 lha@@SU.SE    Initial default ccache   Nov 22 14:14:24   *
  745 lha@@KTH.SE   0                        Nov 22 23:09:40   
  746 @end example
  747 
  748 Som applications, like openssh with Simon Wilkinsons patch applied,
  749 support specifiying that credential to use.  The example below will
  750 login to the host computer.kth.se using lha@@KTH.SE (not the current
  751 default credential).
  752 
  753 @example
  754 $ ssh \
  755    -o GSSAPIAuthentication=yes \
  756    -o GSSAPIKeyExchange=yes \
  757    -o GSSAPIClientIdentity=lha@@KTH.SE \
  758    computer.kth.se
  759 @end example
  760 
  761 
  762 
  763 @node Cross realm, Transit policy, Credential cache server - KCM, Setting up a realm
  764 @section Cross realm
  765 @cindex Cross realm
  766 
  767 Suppose you reside in the realm @samp{MY.REALM}, how do you
  768 authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in
  769 @samp{MY.REALM} allows you to communicate with Kerberised services in that
  770 realm. However, the computer in the other realm does not have a secret
  771 key shared with the Kerberos server in your realm.
  772 
  773 It is possible to share keys between two realms that trust each
  774 other. When a client program, such as @command{telnet} or @command{ssh},
  775 finds that the other computer is in a different realm, it will try to
  776 get a ticket granting ticket for that other realm, but from the local
  777 Kerberos server. With that ticket granting ticket, it will then obtain
  778 service tickets from the Kerberos server in the other realm.
  779 
  780 For a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM}
  781 add the following principals to each realm. The principals should be
  782 @samp{krbtgt/OTHER.REALM@@MY.REALM} and
  783 @samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and
  784 @samp{krbtgt/MY.REALM@@OTHER.REALM} and
  785 @samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}.
  786 
  787 In Kerberos 5 the trust can be configured to be one way. So that
  788 users from @samp{MY.REALM} can authenticate to services in
  789 @samp{OTHER.REALM}, but not the opposite. In the example above, the
  790 @samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed.
  791 
  792 The two principals must have the same key, key version number, and the
  793 same set of encryption types. Remember to transfer the two keys in a
  794 safe manner.
  795 
  796 @example
  797 vr$ klist
  798 Credentials cache: FILE:/tmp/krb5cc_913.console
  799         Principal: lha@@E.KTH.SE
  800 
  801   Issued           Expires          Principal
  802 May  3 13:55:52  May  3 23:55:54  krbtgt/E.KTH.SE@@E.KTH.SE
  803 
  804 vr$ telnet -l lha hummel.it.su.se
  805 Trying 2001:6b0:5:1095:250:fcff:fe24:dbf...
  806 Connected to hummel.it.su.se.
  807 Escape character is '^]'.
  808 Waiting for encryption to be negotiated...
  809 [ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ]
  810 [ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ]
  811 Encryption negotiated.
  812 Last login: Sat May  3 14:11:47 from vr.l.nxs.se
  813 hummel$ exit
  814 
  815 vr$ klist
  816 Credentials cache: FILE:/tmp/krb5cc_913.console
  817         Principal: lha@@E.KTH.SE
  818 
  819   Issued           Expires          Principal
  820 May  3 13:55:52  May  3 23:55:54  krbtgt/E.KTH.SE@@E.KTH.SE
  821 May  3 13:55:56  May  3 23:55:54  krbtgt/SU.SE@@E.KTH.SE
  822 May  3 14:10:54  May  3 23:55:54  host/hummel.it.su.se@@SU.SE
  823 
  824 @end example
  825 
  826 @node Transit policy, Setting up DNS, Cross realm, Setting up a realm
  827 @section Transit policy
  828 @cindex Transit policy
  829 
  830 Under some circumstances, you may not wish to set up direct
  831 cross-realm trust with every realm to which you wish to authenticate
  832 or from which you wish to accept authentications. Kerberos supports
  833 multi-hop cross-realm trust where a client principal in realm A
  834 authenticates to a service in realm C through a realm B with which
  835 both A and C have cross-realm trust relationships. In this situation,
  836 A and C need not set up cross-realm principals between each other.
  837 
  838 If you want to use cross-realm authentication through an intermediate
  839 realm, it must be explicitly allowed by either the KDCs for the realm
  840 to which the client is authenticating (in this case, realm C), or the
  841 server receiving the request. This is done in @file{krb5.conf} in the
  842 @code{[capaths]} section.
  843 
  844 In addition, the client in realm A need to be configured to know how
  845 to reach realm C via realm B. This can be done either on the client or
  846 via KDC configuration in the KDC for realm A.
  847 
  848 @subsection Allowing cross-realm transits
  849 
  850 When the ticket transits through a realm to another realm, the
  851 destination realm adds its peer to the "transited-realms" field in the
  852 ticket. The field is unordered, since there is no way to know if know
  853 if one of the transited-realms changed the order of the list. For the
  854 authentication to be accepted by the final destination realm, all of
  855 the transited realms must be listed as trusted in the @code{[capaths]}
  856 configuration, either in the KDC for the destination realm or on the
  857 server receiving the authentication.
  858 
  859 The syntax for @code{[capaths]} section is:
  860 
  861 @example
  862 [capaths]
  863         CLIENT-REALM = @{
  864                 SERVER-REALM = PERMITTED-CROSS-REALMS ...
  865         @}
  866 @end example
  867 
  868 In the following example, the realm @code{STACKEN.KTH.SE} only has
  869 direct cross-realm set up with @code{KTH.SE}.  @code{KTH.SE} has
  870 direct cross-realm set up with @code{STACKEN.KTH.SE} and @code{SU.SE}.
  871 @code{DSV.SU.SE} only has direct cross-realm set up with @code{SU.SE}.
  872 The goal is to allow principals in the @code{DSV.SU.SE} or
  873 @code{SU.SE} realms to authenticate to services in
  874 @code{STACKEN.KTH.SE}.  This is done with the following
  875 @code{[capaths]} entry on either the server accepting authentication
  876 or on the KDC for @code{STACKEN.KTH.SE}.
  877 
  878 @example
  879 [capaths]
  880 	SU.SE = @{
  881                     STACKEN.KTH.SE = KTH.SE
  882 	@}
  883 	DSV.SU.SE = @{
  884                     STACKEN.KTH.SE = SU.SE KTH.SE
  885 	@}
  886 @end example
  887 
  888 The first entry allows cross-realm authentication from clients in
  889 @code{SU.SE} transiting through @code{KTH.SE} to
  890 @code{STACKEN.KTH.SE}.  The second entry allows cross-realm
  891 authentication from clients in @code{DSV.SU.SE} transiting through
  892 both @code{SU.SE} and @code{KTH.SE} to @code{STACKEN.KTH.SE}.
  893 
  894 Be careful of which realm goes where; it's easy to put realms in the
  895 wrong place.  The block is tagged with the client realm (the realm of
  896 the principal authenticating), and the realm before the equal sign is
  897 the final destination realm: the realm to which the client is
  898 authenticating.  After the equal sign go all the realms that the
  899 client transits through.
  900 
  901 The order of the @code{PERMITTED-CROSS-REALMS} is not important when
  902 doing transit cross realm verification.
  903 
  904 @subsection Configuring client cross-realm transits
  905 
  906 The @code{[capaths]} section is also used for another purpose: to tell
  907 clients which realm to transit through to reach a realm with which
  908 their local realm does not have cross-realm trust.  This can be done
  909 by either putting a @code{[capaths]} entry in the configuration of the
  910 client or by putting the entry in the configuration of the KDC for the
  911 client's local realm.  In the latter case, the KDC will then hand back
  912 a referral to the client when the client requests a cross-realm ticket
  913 to the destination realm, telling the client to try to go through an
  914 intermediate realm.
  915 
  916 For client configuration, the order of @code{PERMITTED-CROSS-REALMS}
  917 is significant, since only the first realm in this section (after the
  918 equal sign) is used by the client.
  919 
  920 For example, again consider the @code{[capaths]} entry above for the
  921 case of a client in the @code{SU.SE} realm, and assume that the client
  922 or the @code{SU.SE} KDC has that @code{[capaths]} entry.  If the
  923 client attempts to authenticate to a service in the
  924 @code{STACKEN.KTH.SE} realm, that entry says to first authenticate
  925 cross-realm to the @code{KTH.SE} realm (the first realm listed in the
  926 @code{PERMITTED-CROSS-REALMS} section), and then from there to
  927 @code{STACKEN.KTH.SE}.
  928 
  929 Each entry in @code{[capaths]} can only give the next hop, since only
  930 the first realm in @code{PERMITTED-CROSS-REALMS} is used.  If, for
  931 instance, a client in @code{DSV.SU.SE} had a @code{[capaths]}
  932 configuration as above but without the first block for @code{SU.SE},
  933 they would not be able to reach @code{STACKEN.KTH.SE}.  They would get
  934 as far as @code{SU.SE} based on the @code{DSV.SU.SE} entry in
  935 @code{[capaths]} and then attempt to go directly from there to
  936 @code{STACKEN.KTH.SE} and get stuck (unless, of course, the
  937 @code{SU.SE} KDC had the additional entry required to tell the client
  938 to go through @code{KTH.SE}).
  939 
  940 @subsection Active Directory forest example
  941 
  942 One common place where a @code{[capaths]} configuration is desirable
  943 is with Windows Active Directory forests.  One common Active Directory
  944 configuration is to have one top-level Active Directory realm but then
  945 divide systems, services, and users into child realms (perhaps based
  946 on organizational unit).  One generally establishes cross-realm trust
  947 only with the top-level realm, and then uses transit policy to permit
  948 authentications to and from the child realms.
  949 
  950 For example, suppose an organization has a Heimdal realm
  951 @code{EXAMPLE.COM}, a Windows Active Directory realm
  952 @code{WIN.EXAMPLE.COM}, and then child Active Directory realms
  953 @code{ENGR.WIN.EXAMPLE.COM} and @code{SALES.WIN.EXAMPLE.COM}.  The
  954 goal is to allow users in any of these realms to authenticate to
  955 services in any of these realms.  The @code{EXAMPLE.COM} KDC (and
  956 possibly client) configuration should therefore contain a
  957 @code{[capaths]} section as follows:
  958 
  959 @example
  960 [capaths]
  961 	ENGR.WIN.EXAMPLE.COM = @{
  962 		EXAMPLE.COM = WIN.EXAMPLE.COM
  963 	@}
  964 	SALES.WIN.EXAMPLE.COM = @{
  965 		EXAMPLE.COM = WIN.EXAMPLE.COM
  966 	@}
  967 	EXAMPLE.COM = @{
  968 		ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
  969 		SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
  970 	@}
  971 @end example
  972 
  973 The first two blocks allow clients in the @code{ENGR.WIN.EXAMPLE.COM}
  974 and @code{SALES.WIN.EXAMPLE.COM} realms to authenticate to services in
  975 the @code{EXAMPLE.COM} realm.  The third block tells the client (or
  976 tells the KDC to tell the client via referrals) to transit through
  977 @code{WIN.EXAMPLE.COM} to reach these realms.  Both sides of the
  978 configuration are needed for bi-directional transited cross-realm
  979 authentication.
  980 
  981 @c To test the cross realm configuration, use:
  982 @c    kmumble transit-check client server transit-realms ...
  983 
  984 @node Setting up DNS, Using LDAP to store the database, Transit policy, Setting up a realm
  985 @section Setting up DNS
  986 @cindex Setting up DNS
  987 
  988 @subsection Using DNS to find KDC
  989 
  990 If there is information about where to find the KDC or kadmind for a
  991 realm in the @file{krb5.conf} for a realm, that information will be
  992 preferred, and DNS will not be queried.
  993 
  994 Heimdal will try to use DNS to find the KDCs for a realm. First it
  995 will try to find a @code{SRV} resource record (RR) for the realm. If no
  996 SRV RRs are found, it will fall back to looking for an @code{A} RR for
  997 a machine named kerberos.REALM, and then kerberos-1.REALM, etc
  998 
  999 Adding this information to DNS minimises the client configuration (in
 1000 the common case, resulting in no configuration needed) and allows the
 1001 system administrator to change the number of KDCs and on what machines
 1002 they are running without caring about clients.
 1003 
 1004 The downside of using DNS is that the client might be fooled to use the
 1005 wrong server if someone fakes DNS replies/data, but storing the IP
 1006 addresses of the KDC on all the clients makes it very hard to change
 1007 the infrastructure.
 1008 
 1009 An example of the configuration for the realm @code{EXAMPLE.COM}:
 1010 
 1011 @example
 1012 
 1013 $ORIGIN example.com.
 1014 _kerberos._tcp          SRV     10 1 88 kerberos.example.com.
 1015 _kerberos._udp          SRV     10 1 88 kerberos.example.com.
 1016 _kerberos._tcp          SRV     10 1 88 kerberos-1.example.com.
 1017 _kerberos._udp          SRV     10 1 88 kerberos-1.example.com.
 1018 _kpasswd._udp           SRV     10 1 464 kerberos.example.com.
 1019 _kerberos-adm._tcp	SRV	10 1 749 kerberos.example.com.
 1020 
 1021 @end example
 1022 
 1023 More information about DNS SRV resource records can be found in
 1024 RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)).
 1025 
 1026 @subsection Using DNS to map hostname to Kerberos realm
 1027 
 1028 Heimdal also supports a way to lookup a realm from a hostname. This to
 1029 minimise configuration needed on clients. Using this has the drawback
 1030 that clients can be redirected by an attacker to realms within the
 1031 same cross realm trust and made to believe they are talking to the
 1032 right server (since Kerberos authentication will succeed).
 1033 
 1034 An example configuration that informs clients that for the realms
 1035 it.example.com and srv.example.com, they should use the realm
 1036 EXAMPLE.COM:
 1037 
 1038 @example
 1039 
 1040 $ORIGIN example.com.
 1041 _kerberos.it		TXT     "EXAMPLE.COM"
 1042 _kerberos.srv		TXT     "EXAMPLE.COM"
 1043 
 1044 @end example
 1045 
 1046 @node Using LDAP to store the database, Providing Kerberos credentials to servers and programs, Setting up DNS, Setting up a realm
 1047 @section Using LDAP to store the database
 1048 @cindex Using the LDAP backend
 1049 
 1050 This document describes how to install the LDAP backend for
 1051 Heimdal. Note that before attempting to configure such an
 1052 installation, you should be aware of the implications of storing
 1053 private information (such as users' keys) in a directory service
 1054 primarily designed for public information. Nonetheless, with a
 1055 suitable authorisation policy, it is possible to set this up in a
 1056 secure fashion. A knowledge of LDAP, Kerberos, and C is necessary to
 1057 install this backend. The HDB schema was devised by Leif Johansson.
 1058 
 1059 This assumes, OpenLDAP 2.3 or later.
 1060 
 1061 Requirements:
 1062 
 1063 @itemize @bullet
 1064 
 1065 @item
 1066 A current release of Heimdal, configured with
 1067 @code{--with-openldap=/usr/local} (adjust according to where you have
 1068 installed OpenLDAP).
 1069 
 1070 You can verify that you manage to configure LDAP support by running
 1071 @file{kdc --builtin-hdb}, and checking that @samp{ldap:} is one entry
 1072 in the list.
 1073 
 1074 Its also possible to configure the ldap backend as a shared module,
 1075 see option --hdb-openldap-module to configure.
 1076 
 1077 @item
 1078 Optionally configure OpenLDAP with @kbd{--enable-local} to enable the
 1079 local transport.
 1080 
 1081 @item
 1082 Add the hdb schema to the LDAP server, it's included in the source-tree
 1083 in @file{lib/hdb/hdb.schema}. Example from slapd.conf:
 1084 
 1085 @example
 1086 include /usr/local/etc/openldap/schema/hdb.schema
 1087 @end example
 1088 
 1089 @item
 1090 Configure the LDAP server ACLs to accept writes from clients. For
 1091 example:
 1092 
 1093 @example
 1094 access to *
 1095         by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write
 1096         ...
 1097 
 1098 authz-regexp "gidNumber=.*\\\+uidNumber=0,cn=peercred,cn=external,cn=auth''
 1099 	"uid=heimdal,dc=services,dc=example,dc=com"
 1100 
 1101 @end example
 1102 
 1103 The sasl-regexp is for mapping between the SASL/EXTERNAL and a user in
 1104 a tree.  The user that the key is mapped to should be have a
 1105 krb5Principal aux object with krb5PrincipalName set so that the
 1106 ``creator'' and ``modifier'' is right in @file{kadmin}.
 1107 
 1108 Another option is to create an admins group and add the dn to that
 1109 group.
 1110 
 1111 If a non-local LDAP connection is used, the authz-regexp is not
 1112 needed as Heimdal will bind to LDAP over the network using
 1113 provided credentials.
 1114 
 1115 Since Heimdal talks to the LDAP server over a UNIX domain socket when
 1116 configured for ldapi:///, and uses external sasl authentication, it's
 1117 not possible to require security layer quality (ssf in cyrus-sasl lingo).
 1118 So that requirement has to be turned off in OpenLDAP @command{slapd}
 1119 configuration file
 1120 @file{slapd.conf}.
 1121 
 1122 @example
 1123 sasl-secprops minssf=0
 1124 @end example
 1125 
 1126 @item
 1127 
 1128 Start @command{slapd} with the local listener (as well as the default TCP/IP
 1129 listener on port 389) as follows:
 1130 
 1131 @example
 1132     slapd -h "ldapi:/// ldap:///"
 1133 @end example
 1134 
 1135 Note: These is a bug in @command{slapd} where it appears to corrupt the krb5Key
 1136 binary attribute on shutdown. This may be related to our use of the V3
 1137 schema definition syntax instead of the old UMich-style, V2 syntax.
 1138 
 1139 @item
 1140 You should specify the distinguished name under which your
 1141 principals will be stored in @file{krb5.conf}. Also you need to
 1142 enter the path to the kadmin acl file:
 1143 
 1144 
 1145 @example
 1146 [kdc]
 1147 	# Optional configuration
 1148 	hdb-ldap-structural-object = inetOrgPerson
 1149 	hdb-ldap-url = ldapi:/// (default), ldap://hostname or ldaps://hostname
 1150 	hdb-ldap-secret-file = /path/to/file/containing/ldap/credentials
 1151 	hdb-ldap-start-tls = false
 1152 
 1153         database = @{
 1154                 dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com
 1155                 acl_file = /path/to/kadmind.acl
 1156                 mkey_file = /path/to/mkey
 1157         @}
 1158 @end example
 1159 
 1160 @samp{mkey_file} can be excluded if you feel that you trust your ldap
 1161 directory to have the raw keys inside it.  The
 1162 hdb-ldap-structural-object is not necessary if you do not need Samba
 1163 comatibility.
 1164 
 1165 If connecting to a server over a non-local transport, the @samp{hdb-ldap-url}
 1166 and @samp{hdb-ldap-secret-file} options must be provided. The
 1167 @samp{hdb-ldap-secret-file} must contain the bind credentials:
 1168 
 1169 @example
 1170 [kdc]
 1171 	hdb-ldap-bind-dn = uid=heimdal,dc=services,dc=example,dc=com
 1172 	hdb-ldap-bind-password = secretBindPassword
 1173 @end example
 1174 
 1175 The @samp{hdb-ldap-secret-file} and should be protected with appropriate
 1176 file permissions
 1177 
 1178 @item
 1179 Once you have built Heimdal and started the LDAP server, run kadmin
 1180 (as usual) to initialise the database. Note that the instructions for
 1181 stashing a master key are as per any Heimdal installation.
 1182 
 1183 @example
 1184 kdc# kadmin -l
 1185 kadmin> init EXAMPLE.COM
 1186 Realm max ticket life [unlimited]:
 1187 Realm max renewable ticket life [unlimited]:
 1188 kadmin> add lukeh
 1189 Max ticket life [1 day]:
 1190 Max renewable life [1 week]:
 1191 Principal expiration time [never]:
 1192 Password expiration time [never]:
 1193 Attributes []:
 1194 lukeh@@EXAMPLE.COM's Password:
 1195 Verifying password - lukeh@@EXAMPLE.COM's Password:
 1196 kadmin> exit
 1197 @end example
 1198 
 1199 Verify that the principal database has indeed been stored in the
 1200 directory with the following command:
 1201 
 1202 @example
 1203 kdc# ldapsearch -L -h localhost -D cn=manager \
 1204  -w secret -b ou=KerberosPrincipals,dc=example,dc=com \
 1205  'objectclass=krb5KDCEntry'
 1206 @end example
 1207 
 1208 @item
 1209 Now consider adding indexes to the database to speed up the access, at
 1210 least theses should be added to slapd.conf.
 1211 
 1212 @example
 1213 index	objectClass		eq
 1214 index	cn			eq,sub,pres
 1215 index	uid			eq,sub,pres
 1216 index	displayName		eq,sub,pres
 1217 index	krb5PrincipalName	eq
 1218 @end example
 1219 
 1220 @end itemize
 1221 
 1222 @subsection smbk5pwd overlay
 1223 
 1224 The smbk5pwd overlay, updates the krb5Key and krb5KeyVersionNumber
 1225 appropriately when it receives an LDAP Password change Extended
 1226 Operation:
 1227 
 1228 @url{http://www.openldap.org/devel/cvsweb.cgi/contrib/slapd-modules/smbk5pwd/README?hideattic=1&sortbydate=0}
 1229 
 1230 @subsection Troubleshooting guide
 1231 
 1232 @url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide}
 1233 
 1234 
 1235 @subsection Using Samba LDAP password database
 1236 @cindex Samba
 1237 
 1238 @c @node Using Samba LDAP password database, Providing Kerberos credentials to servers and programs, Using LDAP to store the database, Setting up a realm
 1239 @c @section Using Samba LDAP password database
 1240 
 1241 The Samba domain and the Kerberos realm can have different names since
 1242 arcfour's string to key functions principal/realm independent.  So now
 1243 will be your first and only chance name your Kerberos realm without
 1244 needing to deal with old configuration files.
 1245 
 1246 First, you should set up Samba and get that working with LDAP backend.
 1247 
 1248 Now you can proceed as in @xref{Using LDAP to store the database}.
 1249 Heimdal will pick up the Samba LDAP entries if they are in the same
 1250 search space as the Kerberos entries.
 1251 
 1252 @node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm
 1253 @section Providing Kerberos credentials to servers and programs
 1254 
 1255 Some services require Kerberos credentials when they start to make
 1256 connections to other services or need to use them when they have started.
 1257 
 1258 The easiest way to get tickets for a service is to store the key in a
 1259 keytab. Both ktutil get and kadmin ext can be used to get a
 1260 keytab. ktutil get is better in that way it changes the key/password
 1261 for the user. This is also the problem with ktutil. If ktutil is used
 1262 for the same service principal on several hosts, they keytab will only
 1263 be useful on the last host. In that case, run the extract command on
 1264 one host and then securely copy the keytab around to all other hosts
 1265 that need it.
 1266 
 1267 @example
 1268 host# ktutil -k /etc/krb5-service.keytab \
 1269       get -p lha/admin@@EXAMPLE.ORG service-principal@@EXAMPLE.ORG
 1270 lha/admin@@EXAMPLE.ORG's Password:
 1271 @end example
 1272 
 1273 To get a Kerberos credential file for the service, use kinit in the
 1274 @kbd{--keytab} mode. This will not ask for a password but instead fetch the
 1275 key from the keytab.
 1276 
 1277 @example
 1278 service@@host$ kinit --cache=/var/run/service_krb5_cache \
 1279                --keytab=/etc/krb5-service.keytab \
 1280        service-principal@@EXAMPLE.ORG
 1281 @end example
 1282 
 1283 Long running services might need credentials longer then the
 1284 expiration time of the tickets. kinit can run in a mode that refreshes
 1285 the tickets before they expire. This is useful for services that write
 1286 into AFS and other distributed file systems using Kerberos. To run the
 1287 long running script, just append the program and arguments (if any)
 1288 after the principal. kinit will stop refreshing credentials and remove
 1289 the credentials when the script-to-start-service exits.
 1290 
 1291 @example
 1292 service@@host$ kinit --cache=/var/run/service_krb5_cache \
 1293        --keytab=/etc/krb5-service.keytab \
 1294        service-principal@@EXAMPLE.ORG \
 1295        script-to-start-service argument1 argument2
 1296 @end example
 1297 
 1298 
 1299 @node Setting up PK-INIT, Debugging Kerberos problems, Providing Kerberos credentials to servers and programs, Setting up a realm
 1300 @section Setting up PK-INIT
 1301 
 1302 PK-INIT leverages an existing PKI (public key infrastructure), using
 1303 certificates to get the initial ticket (usually the krbtgt
 1304 ticket-granting ticket).
 1305 
 1306 To use PK-INIT you must first have a PKI. If you don't have one, it is
 1307 time to create it. You should first read the whole current chapter of
 1308 the document to see the requirements imposed on the CA software.
 1309 
 1310 A mapping between the PKI certificate and what principals that
 1311 certificate is allowed to use must exist. There are several ways to do
 1312 this. The administrator can use a configuration file, store the
 1313 principal in the SubjectAltName extension of the certificate, or store
 1314 the mapping in the principals entry in the kerberos database.
 1315 
 1316 @section Certificates
 1317 
 1318 This and following subsection documents the requirements on the KDC
 1319 and client certificates and the format used in the id-pkinit-san
 1320 OtherName extension.
 1321 
 1322 On how to create certificates, you should read @ref{Use OpenSSL to
 1323 create certificates}.
 1324 
 1325 @subsection KDC certificate
 1326 
 1327 The certificate for the KDC has several requirements.
 1328 
 1329 First, the certificate should have an Extended Key Usage (EKU)
 1330 id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second, there must be a
 1331 subjectAltName otherName using OID id-pkinit-san (1.3.6.1.5.2.2) in
 1332 the type field and a DER encoded KRB5PrincipalName that matches the
 1333 name of the TGS of the target realm.  Also, if the certificate has a
 1334 nameConstraints extension with a Generalname with dNSName or iPAdress,
 1335 it must match the hostname or adress of the KDC.
 1336 
 1337 The client is not required by the standard to check the server
 1338 certificate for this information if the client has external
 1339 information confirming which certificate the KDC is supposed to be
 1340 using. However, adding this information to the KDC certificate removes
 1341 the need to specially configure the client to recognize the KDC
 1342 certificate.
 1343 
 1344 Remember that if the client would accept any certificate as the KDC's
 1345 certificate, the client could be fooled into trusting something that
 1346 isn't a KDC and thus expose the user to giving away information (like
 1347 a password or other private information) that it is supposed to keep
 1348 secret.
 1349 
 1350 @subsection Client certificate
 1351 
 1352 The client certificate may need to have a EKU id-pkekuoid
 1353 (1.3.6.1.5.2.3.4) set depending on the configuration on the KDC.
 1354 
 1355 It possible to store the principal (if allowed by the KDC) in the
 1356 certificate and thus delegate responsibility to do the mapping between
 1357 certificates and principals to the CA.
 1358 
 1359 This behavior is controlled by KDC configuration option:
 1360 
 1361 @example
 1362 [kdc]
 1363 	pkinit_principal_in_certificate = yes
 1364 @end example
 1365 
 1366 @subsubsection Using KRB5PrincipalName in id-pkinit-san
 1367 
 1368 The OtherName extension in the GeneralName is used to do the mapping
 1369 between certificate and principal.  For the KDC certificate, this
 1370 stores the krbtgt principal name for that KDC.  For the client
 1371 certificate, this stores the principal for which that certificate is
 1372 allowed to get tickets.
 1373 
 1374 The principal is stored in a SubjectAltName in the certificate using
 1375 OtherName. The OID in the type is id-pkinit-san.
 1376 
 1377 @example
 1378 id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6)
 1379 internet (1) security (5) kerberosv5 (2) 2 @}
 1380 @end example
 1381 
 1382 The data part of the OtherName is filled with the following DER
 1383 encoded ASN.1 structure:
 1384 
 1385 @example
 1386 KRB5PrincipalName ::= SEQUENCE @{
 1387 	realm [0] Realm,
 1388 	principalName [1] PrincipalName
 1389 @}
 1390 @end example
 1391 
 1392 where Realm and PrincipalName is defined by the Kerberos ASN.1
 1393 specification.
 1394 
 1395 @section Naming certificate using hx509
 1396 
 1397 hx509 is the X.509 software used in Heimdal to handle
 1398 certificates. hx509 supports several different syntaxes for specifying
 1399 certificate files or formats. Several formats may be used:  PEM,
 1400 certificates embedded in PKCS#12 files, certificates embedded in
 1401 PKCS#11 devices, and raw DER encoded certificates.
 1402 
 1403 Those formats may be specified as follows:
 1404 
 1405 @table @asis
 1406 
 1407 @item DIR:
 1408 
 1409 DIR specifies a directory which contains certificates in the DER or
 1410 PEM format.
 1411 
 1412 The main feature of DIR is that the directory is read on demand when
 1413 iterating over certificates. This allows applications, in some
 1414 situations, to avoid having to store all certificates in memory.  It's
 1415 very useful for tests that iterate over large numbers of certificates.
 1416 
 1417 The syntax is:
 1418 
 1419 @example
 1420 DIR:/path/to/der/files
 1421 @end example
 1422 
 1423 @item FILE:
 1424 
 1425 FILE: specifies a file that contains a certificate or private key.
 1426 The file can be either a PEM (openssl) file or a raw DER encoded
 1427 certificate. If it's a PEM file, it can contain several keys and
 1428 certificates and the code will try to match the private key and
 1429 certificate together. Multiple files may be specified, separated by
 1430 commas.
 1431 
 1432 It's useful to have one PEM file that contains all the trust anchors.
 1433 
 1434 The syntax is:
 1435 
 1436 @example
 1437 FILE:certificate.pem,private-key.key,other-cert.pem,....
 1438 @end example
 1439 
 1440 @item PKCS11:
 1441 
 1442 PKCS11: is used to handle smartcards via PKCS#11 drivers, such as
 1443 soft-token, opensc, or muscle. The argument specifies a shared object
 1444 that implements the PKCS#11 API. The default is to use all slots on
 1445 the device/token.
 1446 
 1447 The syntax is:
 1448 
 1449 @example
 1450 PKCS11:shared-object.so
 1451 @end example
 1452 
 1453 @item PKCS12:
 1454 
 1455 PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have
 1456 the extension pfx or p12.
 1457 
 1458 The syntax is:
 1459 
 1460 @example
 1461 PKCS12:/path/to/file.pfx
 1462 @end example
 1463 
 1464 @end table
 1465 
 1466 @section Configure the Kerberos software
 1467 
 1468 First configure the client's trust anchors and what parameters to
 1469 verify. See the subsections below for how to do that. Then, you can
 1470 use kinit to get yourself tickets. For example:
 1471 
 1472 @example
 1473 $ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG
 1474 Enter your private key passphrase:
 1475 : lha@@nutcracker ; klist
 1476 Credentials cache: FILE:/tmp/krb5cc_19100a
 1477         Principal: lha@@EXAMPLE.ORG
 1478 
 1479   Issued           Expires          Principal
 1480 Apr 20 02:08:08  Apr 20 12:08:08  krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
 1481 @end example
 1482 
 1483 Using PKCS#11 it can look like this instead:
 1484 
 1485 @example
 1486 $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG
 1487 PIN code for SoftToken (slot):
 1488 $ klist
 1489 Credentials cache: API:4
 1490         Principal: lha@@EXAMPLE.ORG
 1491 
 1492   Issued           Expires          Principal
 1493 Mar 26 23:40:10  Mar 27 09:40:10  krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
 1494 @end example
 1495 
 1496 @section Configure the client
 1497 
 1498 @example
 1499 [appdefaults]
 1500 	pkinit_anchors = FILE:/path/to/trust-anchors.pem
 1501 
 1502 [realms]
 1503         EXAMPLE.COM = @{
 1504 		pkinit_require_eku = true
 1505 		pkinit_require_krbtgt_otherName = true
 1506 		pkinit_win2k = no
 1507 		pkinit_win2k_require_binding = yes
 1508 	@}
 1509 
 1510 @end example
 1511 
 1512 @section Configure the KDC
 1513 
 1514 Configuration options for the KDC.
 1515 
 1516 @table @asis
 1517 @item enable-pkinit = bool
 1518 
 1519 Enable PKINIT for this KDC.
 1520 
 1521 @item pkinit_identity = string
 1522 
 1523 Identity that the KDC will use when talking to clients. Mandatory.
 1524 
 1525 @item pkinit_anchors = string
 1526 
 1527 Trust anchors that the KDC will use when evaluating the trust of the
 1528 client certificate. Mandatory.
 1529 
 1530 @item pkinit_pool = strings ...
 1531 
 1532 Extra certificate the KDC will use when building trust chains if it
 1533 can't find enough certificates in the request from the client.
 1534 
 1535 @item pkinit_allow_proxy_certificate = bool
 1536 
 1537 Allow clients to use proxy certificates. The root certificate
 1538 of the client's End Entity certificate is used for authorisation.
 1539 
 1540 @item pkinit_win2k_require_binding = bool
 1541 
 1542 Require windows clients up be upgrade to not allow cut and paste
 1543 attack on encrypted data, applies to Windows XP and windows 2000
 1544 servers.
 1545 
 1546 @item pkinit_principal_in_certificate = bool
 1547 
 1548 Enable the KDC to use id-pkinit-san to determine to determine the
 1549 mapping between a certificate and principal.
 1550 
 1551 @end table
 1552 
 1553 @example
 1554 [kdc]
 1555 	enable-pkinit = yes
 1556 	pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key
 1557 	pkinit_anchors = FILE:/path/to/trust-anchors.pem
 1558 	pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx
 1559 	pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem
 1560 	pkinit_allow_proxy_certificate = no
 1561 	pkinit_win2k_require_binding = yes
 1562 	pkinit_principal_in_certificate = no
 1563 @end example
 1564 
 1565 @subsection Using pki-mapping file
 1566 
 1567 Note that the file contents are space sensitive.
 1568 
 1569 @example
 1570 # cat /var/heimdal/pki-mapping
 1571 # comments starts with #
 1572 lha@@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha
 1573 lha@@EXAMPLE.ORG:CN=Love,UID=lha
 1574 @end example
 1575 
 1576 @subsection Using the Kerberos database
 1577 
 1578 You can also store the subject of the certificate in the principal
 1579 entry in the kerberos database.
 1580 
 1581 @example
 1582 kadmin modify --pkinit-acl="CN=baz,DC=test,DC=h5l,DC=se" user@@REALM
 1583 @end example
 1584 
 1585 @section Use hxtool to create certificates
 1586 
 1587 @subsection Generate certificates
 1588 
 1589 First, you need to generate a CA certificate. This example creates a
 1590 CA certificate that will be valid for 10 years.
 1591 
 1592 You need to change --subject in the command below to something
 1593 appropriate for your site.
 1594 
 1595 @example
 1596 hxtool issue-certificate \
 1597     --self-signed \
 1598     --issue-ca \
 1599     --generate-key=rsa \
 1600     --subject="CN=CA,DC=test,DC=h5l,DC=se" \
 1601     --lifetime=10years \
 1602     --certificate="FILE:ca.pem"
 1603 @end example
 1604 
 1605 The KDC needs to have a certificate, so generate a certificate of the
 1606 type ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the
 1607 name of the krbtgt of the realm.
 1608 
 1609 You need to change --subject and --pk-init-principal in the command
 1610 below to something appropriate for your site.
 1611 
 1612 @example
 1613 hxtool issue-certificate \
 1614     --ca-certificate=FILE:ca.pem \
 1615     --generate-key=rsa \
 1616     --type="pkinit-kdc" \
 1617     --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
 1618     --subject="uid=kdc,DC=test,DC=h5l,DC=se" \
 1619     --certificate="FILE:kdc.pem"
 1620 @end example
 1621 
 1622 The users also needs to have certificates. For your first client,
 1623 generate a certificate of type ``pkinit-client''. The client doesn't
 1624 need to have the PK-INIT SubjectAltName set; you can have the Subject
 1625 DN in the ACL file (pki-mapping) instead.
 1626 
 1627 You need to change --subject and --pk-init-principal in the command
 1628 below to something appropriate for your site. You can omit
 1629 --pk-init-principal if you're going to use the ACL file instead.
 1630 
 1631 @example
 1632 hxtool issue-certificate \
 1633     --ca-certificate=FILE:ca.pem \
 1634     --generate-key=rsa \
 1635     --type="pkinit-client" \
 1636     --pk-init-principal="lha@@TEST.H5L.SE" \
 1637     --subject="uid=lha,DC=test,DC=h5l,DC=se" \
 1638     --certificate="FILE:user.pem"
 1639 @end example
 1640 
 1641 @subsection Validate the certificate
 1642 
 1643 hxtool also contains a tool that will validate certificates according
 1644 to rules from the PKIX document. These checks are not complete, but
 1645 they provide a good test of whether you got all of the basic bits
 1646 right in your certificates.
 1647 
 1648 @example
 1649 hxtool validate FILE:user.pem
 1650 @end example
 1651 
 1652 @section Use OpenSSL to create certificates
 1653 @anchor{Use OpenSSL to create certificates}
 1654 
 1655 This section tries to give the CA owners hints how to create
 1656 certificates using OpenSSL (or CA software based on OpenSSL).
 1657 
 1658 @subsection Using OpenSSL to create certificates with krb5PrincipalName
 1659 
 1660 To make OpenSSL create certificates with krb5PrincipalName, use an
 1661 @file{openssl.cnf} as described below. To see a complete example of
 1662 creating client and KDC certificates, see the test-data generation
 1663 script @file{lib/hx509/data/gen-req.sh} in the source-tree. The
 1664 certicates it creates are used to test the PK-INIT functionality in
 1665 @file{tests/kdc/check-kdc.in}.
 1666 
 1667 To use this example you have to use OpenSSL 0.9.8a or later.
 1668 
 1669 @example
 1670 
 1671 [user_certificate]
 1672 subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name
 1673 
 1674 [princ_name]
 1675 realm = EXP:0, GeneralString:MY.REALM
 1676 principal_name = EXP:1, SEQUENCE:principal_seq
 1677 
 1678 [principal_seq]
 1679 name_type = EXP:0, INTEGER:1
 1680 name_string = EXP:1, SEQUENCE:principals
 1681 
 1682 [principals]
 1683 princ1 = GeneralString:userid
 1684 
 1685 @end example
 1686 
 1687 Command usage:
 1688 
 1689 @example
 1690 openssl x509 -extensions user_certificate
 1691 openssl ca -extensions user_certificate
 1692 @end example
 1693 
 1694 
 1695 @c --- ms certificate
 1696 @c
 1697 @c [ new_oids ]
 1698 @c msCertificateTemplateName       = 1.3.6.1.4.1.311.20.2
 1699 @c
 1700 @c
 1701 @c [ req_smartcard ]
 1702 @c keyUsage                = digitalSignature, keyEncipherment
 1703 @c extendedKeyUsage        = msSmartcardLogin, clientAuth
 1704 @c msCertificateTemplateName       = ASN1:BMP:SmartcardLogon
 1705 @c subjectAltName          = otherName:msUPN;UTF8:lukeh@dsg.padl.com
 1706 @c #subjectAltName         = email:copy
 1707 
 1708 
 1709 @section Using PK-INIT with Windows
 1710 
 1711 @subsection Client configration
 1712 
 1713 Clients using a Windows KDC with PK-INIT need configuration since
 1714 windows uses pre-standard format and this can't be autodetected.
 1715 
 1716 The pkinit_win2k_require_binding option requires the reply for the KDC
 1717 to be of the new, secure, type that binds the request to
 1718 reply. Before, clients could fake the reply from the KDC. To use this
 1719 option you have to apply a fix from Microsoft.
 1720 
 1721 @example
 1722 [realms]
 1723         MY.MS.REALM = @{
 1724                 pkinit_win2k = yes
 1725                 pkinit_win2k_require_binding = no
 1726 	@}
 1727 @end example
 1728 
 1729 @subsection Certificates
 1730 
 1731 The client certificates need to have the extended keyusage ``Microsoft
 1732 Smartcardlogin'' (openssl has the OID shortname msSmartcardLogin).
 1733 
 1734 See Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling
 1735 Smart Card Logon with Third-Party Certification Authorities'' for a
 1736 more extensive description of how set setup an external CA so that it
 1737 includes all the information required to make a Windows KDC happy.
 1738 
 1739 @subsection Configure Windows 2000 CA
 1740 
 1741 To enable Microsoft Smartcardlogin for certificates in your Windows
 1742 2000 CA, you want to look at Microsoft Knowledge Base Article - 313274
 1743 ``HOW TO: Configure a Certification Authority to Issue Smart Card
 1744 Certificates in Windows''.
 1745 
 1746 @node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm
 1747 @section Debugging Kerberos problems
 1748 
 1749 To debug Kerberos client and server problems you can enable debug
 1750 traceing by adding the following to @file{/etc/krb5,conf}. Note that the
 1751 trace logging is sparse at the moment, but will continue to improve.
 1752 
 1753 @example
 1754 [logging]
 1755         libkrb5 = 0-/SYSLOG:
 1756 @end example
 1757 
 1758 
 1759 
 1760