3 @node Setting up a realm, Applications, Building and Installing, Top
5 @chapter Setting up a 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.
15 * Configuration file::
16 * Creating the database::
17 * Modifying the database::
18 * Checking the setup::
20 * Remote administration::
22 * Testing clients and servers::
24 * Incremental propagation::
25 * Encryption types and salting::
26 * Credential cache server - KCM::
30 * Using LDAP to store the database::
31 * Providing Kerberos credentials to servers and programs::
32 * Setting up PK-INIT::
33 * Debugging Kerberos problems::
36 @node Configuration file, Creating the database, Setting up a realm, Setting up a realm
37 @section Configuration file
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.
43 There is a sample @file{krb5.conf} supplied with the distribution.
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.
59 other-var = value with @{@}
64 var = some other value
66 var = yet another value
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}.
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.
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.
86 To continue with the realm setup, you will have to create a configuration file,
87 with contents similar to the following.
91 default_realm = MY.REALM
94 kdc = my.kdc my.slave.kdc
97 kdc = [2001:6b0:1:ea::100]:88
100 .my.domain = MY.REALM
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.
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}.
114 env KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM
117 @node Creating the database, Modifying the database, Configuration file, Setting up a realm
118 @section Creating the database
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.
126 # chmod og-rwx /var/heimdal
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.
134 These defaults can be overriden in the 'database' key in the @samp{kdc}
135 section of the configuration.
140 dbname = lmdb:/path/to/db-file
142 acl_file = /path/to/kadmind.acl
143 mkey_file = /path/to/mkey
144 log_file = /path/to/iprop-log-file
148 To use LDAP, see @xref{Using LDAP to store the database}.
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:
159 Verifying password - Master key:
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.
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.
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.
175 Before creating the database, @samp{init} will ask you some questions
176 about maximum ticket lifetimes.
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.
185 kadmin> init MY.REALM
186 Realm max ticket life [unlimited]:
187 Realm max renewable ticket life [unlimited]:
189 Max ticket life [unlimited]:
190 Max renewable life [unlimited]:
193 Verifying password - Password:
196 Now start the KDC and try getting a ticket.
201 me@@MY.REALMS's Password:
203 Credentials cache: /tmp/krb5cc_0
204 Principal: me@@MY.REALM
206 Issued Expires Principal
207 Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM
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):
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 ...
223 @node Modifying the database, Checking the setup, Creating the database, Setting up a realm
224 @section Modifying the database
226 All modifications of principals are done with with kadmin.
228 A principal has several attributes and lifetimes associated with it.
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).
235 There are different kinds of types for the fields in the database;
236 attributes, absolute time times and relative times.
238 @subsection Attributes
240 When doing interactive editing, attributes are listed with @samp{?}.
242 The attributes are given in a comma (@samp{,}) separated list.
243 Attributes are removed from the list by prefixing them with @samp{-}.
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
253 Principal: me@@MY.REALM
255 Attributes: requires-pre-auth
258 @subsection Absolute times
260 The format for absolute times are any of the following:
270 @subsection Relative times
272 The format for relative times are any of the following combined:
283 @c Describe more of kadmin commands here...
285 @node Checking the setup, keytabs, Modifying the database, Setting up a realm
286 @section Checking the setup
288 There are two tools that can check the consistency of the Kerberos
289 configuration file and the Kerberos database.
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.
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 :
303 kadmin -l check REALM.EXAMPLE.ORG
306 @node keytabs, Remote administration, Checking the setup, Setting up a realm
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}.
315 kadmin> add --random-key host/my.host.name
316 Max ticket life [unlimited]:
317 Max renewable life [unlimited]:
319 kadmin> ext host/my.host.name
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
329 @node Remote administration, Password changing, keytabs, Setting up a realm
330 @section Remote administration
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}.
338 kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind
341 You might need to add @samp{kerberos-adm} to your @file{/etc/services}
344 Access to the administration server is controlled by an ACL file,
345 (default @file{/var/heimdal/kadmind.acl}.) The file has the following
348 principal [priv1,priv2,...] [glob-pattern]
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
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
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)}.
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.
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
380 @node Password changing, Testing clients and servers, Remote administration, Setting up a realm
381 @section Password changing
383 To allow users to change their passwords, you should run @command{kpasswdd}.
384 It is not run from @command{inetd}.
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:
394 kdc = my.kdc my.slave.kdc
395 kpasswd_server = my.kdc
399 @subsection Password quality assurance
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}:
413 policies = external-check builtin:minimum-length modulename:policyname
414 external_program = /bin/false
415 policy_libraries = @var{library1.so} @var{library2.so}
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.
424 The built-in policies are
430 Executes the program specified by @samp{[password_quality]external_program}.
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
436 principal: @var{principal}
437 new-password: @var{password}
439 where @var{password} is the password to check for the previous
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.
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.
456 @item character-class
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.
463 The four different characters classes are, uppercase, lowercase,
464 number, special characters.
468 If you want to write your own shared object to check password
469 policies, see the manual page @manpage{kadm5_pwcheck,3}.
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}.
477 A sample policy external program is included in
478 @file{lib/kadm5/check-cracklib.pl}.
480 If no password quality checking function is configured, the only check
481 performed is that the password is at least six characters long.
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.
490 @node Testing clients and servers, Slave Servers, Password changing, Setting up a realm
491 @section Testing clients and servers
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.
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
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.
503 All Kerberos servers for a realm must have the same database so that
504 they present the same service to the users. The
506 @command{hprop} program, running on the master, will propagate the database
507 to the slaves, running
509 @command{hpropd} processes.
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
515 @command{ktutil} command and start
517 @command{hpropd}, as follows:
520 slave# ktutil get -p foo/admin hprop/`hostname`
521 slave# mkdir /var/heimdal
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}.
532 @code{hprop} on the master:
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
542 @command{hpropd} from @command{inetd} on the slave(s) and regularly run
544 @command{hprop} on the master to regularly propagate the database.
545 Starting the propagation once an hour from @command{cron} is probably a
548 @node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm
549 @section Incremental propagation
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.
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.
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.
576 @subsection Configuring incremental propagation
578 The program that runs on the master is @command{ipropd-master} and all
579 clients run @command{ipropd-slave}.
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}).
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.
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
597 master# /usr/heimdal/sbin/ktutil get iprop/`hostname`
601 slave# /usr/heimdal/sbin/ktutil get iprop/`hostname`
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:
614 master# /usr/heimdal/libexec/ipropd-master &
615 slave# /usr/heimdal/libexec/ipropd-slave master &
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.
621 @subsection Status of iprop master and slave
623 Both the master and slave provides status of the world as they see it.
625 The master write outs the current status of the slaves, last seen and
626 their version number in @file{/var/heimdal/slaves-stats}.
628 The slave write out the current status in @file{/var/heimdal/ipropd-slave-status}.
630 These locations can be changed with command line options, and in the
631 case of @command{ipropd_master}, the configuration file.
633 @node Encryption types and salting, Credential cache server - KCM, Incremental propagation, Setting up a realm
634 @section Encryption types and salting
636 @cindex Encryption types
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
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.
650 In Kerberos 5 the salt is determined by the encryption type, except in
653 In @code{des} there is the Kerberos 4 salt
654 (none at all) or the afs-salt (using the cell (realm in
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
661 @code{[kadmin]default_keys} in @file{krb5.conf} controls
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
672 Common types of salting include
675 @item @code{v4} (or @code{des:pw-salt:})
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).
681 @item @code{v5} (or @code{pw-salt})
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.
687 @item @code{afs3-salt}
689 @code{afs3-salt} is the salt that is used with Transarc kaserver. It's
690 the cell name appended to the password.
694 @node Credential cache server - KCM, Cross realm, Encryption types and salting, Setting up a realm
695 @section Credential cache server - KCM
697 @cindex Credential cache server
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.
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.
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}.
712 default_cc_type = KCM
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.
722 lha@@KTH.SE's Password:
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
729 When switching between credentials you can use @command{kswitch}.
739 After switching, a new set of credentials are used as default.
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
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
755 -o GSSAPIAuthentication=yes \
756 -o GSSAPIKeyExchange=yes \
757 -o GSSAPIClientIdentity=lha@@KTH.SE \
763 @node Cross realm, Transit policy, Credential cache server - KCM, Setting up a realm
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.
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.
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}.
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.
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
798 Credentials cache: FILE:/tmp/krb5cc_913.console
799 Principal: lha@@E.KTH.SE
801 Issued Expires Principal
802 May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE
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
816 Credentials cache: FILE:/tmp/krb5cc_913.console
817 Principal: lha@@E.KTH.SE
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
826 @node Transit policy, Setting up DNS, Cross realm, Setting up a realm
827 @section Transit policy
828 @cindex Transit policy
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.
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.
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.
848 @subsection Allowing cross-realm transits
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.
859 The syntax for @code{[capaths]} section is:
864 SERVER-REALM = PERMITTED-CROSS-REALMS ...
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}.
881 STACKEN.KTH.SE = KTH.SE
884 STACKEN.KTH.SE = SU.SE KTH.SE
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}.
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.
901 The order of the @code{PERMITTED-CROSS-REALMS} is not important when
902 doing transit cross realm verification.
904 @subsection Configuring client cross-realm transits
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
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.
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}.
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}).
940 @subsection Active Directory forest example
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.
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:
961 ENGR.WIN.EXAMPLE.COM = @{
962 EXAMPLE.COM = WIN.EXAMPLE.COM
964 SALES.WIN.EXAMPLE.COM = @{
965 EXAMPLE.COM = WIN.EXAMPLE.COM
968 ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
969 SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
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
981 @c To test the cross realm configuration, use:
982 @c kmumble transit-check client server transit-realms ...
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
988 @subsection Using DNS to find KDC
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.
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
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.
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
1009 An example of the configuration for the realm @code{EXAMPLE.COM}:
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.
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)).
1026 @subsection Using DNS to map hostname to Kerberos realm
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).
1034 An example configuration that informs clients that for the realms
1035 it.example.com and srv.example.com, they should use the realm
1040 $ORIGIN example.com.
1041 _kerberos.it TXT "EXAMPLE.COM"
1042 _kerberos.srv TXT "EXAMPLE.COM"
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
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.
1059 This assumes, OpenLDAP 2.3 or later.
1066 A current release of Heimdal, configured with
1067 @code{--with-openldap=/usr/local} (adjust according to where you have
1068 installed OpenLDAP).
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
1074 Its also possible to configure the ldap backend as a shared module,
1075 see option --hdb-openldap-module to configure.
1078 Optionally configure OpenLDAP with @kbd{--enable-local} to enable the
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:
1086 include /usr/local/etc/openldap/schema/hdb.schema
1090 Configure the LDAP server ACLs to accept writes from clients. For
1095 by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write
1098 authz-regexp "gidNumber=.*\\\+uidNumber=0,cn=peercred,cn=external,cn=auth''
1099 "uid=heimdal,dc=services,dc=example,dc=com"
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}.
1108 Another option is to create an admins group and add the dn to that
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.
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}
1123 sasl-secprops minssf=0
1128 Start @command{slapd} with the local listener (as well as the default TCP/IP
1129 listener on port 389) as follows:
1132 slapd -h "ldapi:/// ldap:///"
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.
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:
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
1154 dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com
1155 acl_file = /path/to/kadmind.acl
1156 mkey_file = /path/to/mkey
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
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:
1171 hdb-ldap-bind-dn = uid=heimdal,dc=services,dc=example,dc=com
1172 hdb-ldap-bind-password = secretBindPassword
1175 The @samp{hdb-ldap-secret-file} and should be protected with appropriate
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.
1185 kadmin> init EXAMPLE.COM
1186 Realm max ticket life [unlimited]:
1187 Realm max renewable ticket life [unlimited]:
1189 Max ticket life [1 day]:
1190 Max renewable life [1 week]:
1191 Principal expiration time [never]:
1192 Password expiration time [never]:
1194 lukeh@@EXAMPLE.COM's Password:
1195 Verifying password - lukeh@@EXAMPLE.COM's Password:
1199 Verify that the principal database has indeed been stored in the
1200 directory with the following command:
1203 kdc# ldapsearch -L -h localhost -D cn=manager \
1204 -w secret -b ou=KerberosPrincipals,dc=example,dc=com \
1205 'objectclass=krb5KDCEntry'
1209 Now consider adding indexes to the database to speed up the access, at
1210 least theses should be added to slapd.conf.
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
1222 @subsection smbk5pwd overlay
1224 The smbk5pwd overlay, updates the krb5Key and krb5KeyVersionNumber
1225 appropriately when it receives an LDAP Password change Extended
1228 @url{http://www.openldap.org/devel/cvsweb.cgi/contrib/slapd-modules/smbk5pwd/README?hideattic=1&sortbydate=0}
1230 @subsection Troubleshooting guide
1232 @url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide}
1235 @subsection Using Samba LDAP password database
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
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.
1246 First, you should set up Samba and get that working with LDAP backend.
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.
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
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.
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
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:
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.
1278 service@@host$ kinit --cache=/var/run/service_krb5_cache \
1279 --keytab=/etc/krb5-service.keytab \
1280 service-principal@@EXAMPLE.ORG
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.
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
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
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).
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.
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.
1316 @section Certificates
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.
1322 On how to create certificates, you should read @ref{Use OpenSSL to
1323 create certificates}.
1325 @subsection KDC certificate
1327 The certificate for the KDC has several requirements.
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.
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
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
1350 @subsection Client certificate
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.
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.
1359 This behavior is controlled by KDC configuration option:
1363 pkinit_principal_in_certificate = yes
1366 @subsubsection Using KRB5PrincipalName in id-pkinit-san
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.
1374 The principal is stored in a SubjectAltName in the certificate using
1375 OtherName. The OID in the type is id-pkinit-san.
1378 id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6)
1379 internet (1) security (5) kerberosv5 (2) 2 @}
1382 The data part of the OtherName is filled with the following DER
1383 encoded ASN.1 structure:
1386 KRB5PrincipalName ::= SEQUENCE @{
1388 principalName [1] PrincipalName
1392 where Realm and PrincipalName is defined by the Kerberos ASN.1
1395 @section Naming certificate using hx509
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.
1403 Those formats may be specified as follows:
1409 DIR specifies a directory which contains certificates in the DER or
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.
1420 DIR:/path/to/der/files
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
1432 It's useful to have one PEM file that contains all the trust anchors.
1437 FILE:certificate.pem,private-key.key,other-cert.pem,....
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
1450 PKCS11:shared-object.so
1455 PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have
1456 the extension pfx or p12.
1461 PKCS12:/path/to/file.pfx
1466 @section Configure the Kerberos software
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:
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
1479 Issued Expires Principal
1480 Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
1483 Using PKCS#11 it can look like this instead:
1486 $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG
1487 PIN code for SoftToken (slot):
1489 Credentials cache: API:4
1490 Principal: lha@@EXAMPLE.ORG
1492 Issued Expires Principal
1493 Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
1496 @section Configure the client
1500 pkinit_anchors = FILE:/path/to/trust-anchors.pem
1504 pkinit_require_eku = true
1505 pkinit_require_krbtgt_otherName = true
1507 pkinit_win2k_require_binding = yes
1512 @section Configure the KDC
1514 Configuration options for the KDC.
1517 @item enable-pkinit = bool
1519 Enable PKINIT for this KDC.
1521 @item pkinit_identity = string
1523 Identity that the KDC will use when talking to clients. Mandatory.
1525 @item pkinit_anchors = string
1527 Trust anchors that the KDC will use when evaluating the trust of the
1528 client certificate. Mandatory.
1530 @item pkinit_pool = strings ...
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.
1535 @item pkinit_allow_proxy_certificate = bool
1537 Allow clients to use proxy certificates. The root certificate
1538 of the client's End Entity certificate is used for authorisation.
1540 @item pkinit_win2k_require_binding = bool
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
1546 @item pkinit_principal_in_certificate = bool
1548 Enable the KDC to use id-pkinit-san to determine to determine the
1549 mapping between a certificate and principal.
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
1565 @subsection Using pki-mapping file
1567 Note that the file contents are space sensitive.
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
1576 @subsection Using the Kerberos database
1578 You can also store the subject of the certificate in the principal
1579 entry in the kerberos database.
1582 kadmin modify --pkinit-acl="CN=baz,DC=test,DC=h5l,DC=se" user@@REALM
1585 @section Use hxtool to create certificates
1587 @subsection Generate certificates
1589 First, you need to generate a CA certificate. This example creates a
1590 CA certificate that will be valid for 10 years.
1592 You need to change --subject in the command below to something
1593 appropriate for your site.
1596 hxtool issue-certificate \
1599 --generate-key=rsa \
1600 --subject="CN=CA,DC=test,DC=h5l,DC=se" \
1601 --lifetime=10years \
1602 --certificate="FILE:ca.pem"
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.
1609 You need to change --subject and --pk-init-principal in the command
1610 below to something appropriate for your site.
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"
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.
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.
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"
1641 @subsection Validate the certificate
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.
1649 hxtool validate FILE:user.pem
1652 @section Use OpenSSL to create certificates
1653 @anchor{Use OpenSSL to create certificates}
1655 This section tries to give the CA owners hints how to create
1656 certificates using OpenSSL (or CA software based on OpenSSL).
1658 @subsection Using OpenSSL to create certificates with krb5PrincipalName
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}.
1667 To use this example you have to use OpenSSL 0.9.8a or later.
1672 subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name
1675 realm = EXP:0, GeneralString:MY.REALM
1676 principal_name = EXP:1, SEQUENCE:principal_seq
1679 name_type = EXP:0, INTEGER:1
1680 name_string = EXP:1, SEQUENCE:principals
1683 princ1 = GeneralString:userid
1690 openssl x509 -extensions user_certificate
1691 openssl ca -extensions user_certificate
1695 @c --- ms certificate
1698 @c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2
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
1709 @section Using PK-INIT with Windows
1711 @subsection Client configration
1713 Clients using a Windows KDC with PK-INIT need configuration since
1714 windows uses pre-standard format and this can't be autodetected.
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.
1725 pkinit_win2k_require_binding = no
1729 @subsection Certificates
1731 The client certificates need to have the extended keyusage ``Microsoft
1732 Smartcardlogin'' (openssl has the OID shortname msSmartcardLogin).
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.
1739 @subsection Configure Windows 2000 CA
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''.
1746 @node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm
1747 @section Debugging Kerberos problems
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.
1755 libkrb5 = 0-/SYSLOG: