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.
55 Configuration files can also include other files, or all files in a
56 directory. Use absolute paths in include directives. When including a
57 directoty, only files whose names consist of alphanumeric, hyphen, or
58 underscore characters are allowed, though they may end in '.conf'.
61 include /some/config/file
62 includedir /some/config/directory
66 other-var = value with @{@}
71 var = some other value
73 var = yet another value
76 In this manual, names of sections and bindings will be given as strings
77 separated by slashes (@samp{/}). The @samp{other-var} variable will thus
78 be @samp{section1/a-subsection/other-var}.
80 For in-depth information about the contents of the configuration file, refer to
81 the @file{krb5.conf} manual page. Some of the more important sections
82 are briefly described here.
84 The @samp{libdefaults} section contains a list of library configuration
85 parameters, such as the default realm and the timeout for KDC
86 responses. The @samp{realms} section contains information about specific
87 realms, such as where they hide their KDC@. This section serves the same
88 purpose as the Kerberos 4 @file{krb.conf} file, but can contain more
89 information. Finally the @samp{domain_realm} section contains a list of
90 mappings from domains to realms, equivalent to the Kerberos 4
91 @file{krb.realms} file.
93 To continue with the realm setup, you will have to create a configuration file,
94 with contents similar to the following.
98 default_realm = MY.REALM
101 kdc = my.kdc my.slave.kdc
104 kdc = [2001:6b0:1:ea::100]:88
107 .my.domain = MY.REALM
111 If you use a realm name equal to your domain name, you can omit the
112 @samp{libdefaults}, and @samp{domain_realm}, sections. If you have a DNS
113 SRV-record for your realm, or your Kerberos server has DNS CNAME
114 @samp{kerberos.my.realm}, you can omit the @samp{realms} section too.
117 If you want to use a different configuration file then the default you
118 can point a file with the environment variable @samp{KRB5_CONFIG}.
121 env KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM
124 @node Creating the database, Modifying the database, Configuration file, Setting up a realm
125 @section Creating the database
127 The database library will look for the database in the directory
128 @file{@value{dbdir}}, so you should probably create that directory.
129 Make sure the directory has restrictive permissions.
133 # chmod og-rwx /var/heimdal
136 Heimdal supports various database backends: lmdb (LMDB), db3 (Berkeley
137 DB 3.x, 4.x, or 5.x), db1 (Berkeley DB 2.x), sqlite (SQLite3), and ldap
138 (LDAP). The default is @value{dbtype}, and is selected at build time
139 from one of lmdb, db3, or db1.
141 These defaults can be overriden in the 'database' key in the @samp{kdc}
142 section of the configuration.
147 dbname = lmdb:/path/to/db-file
149 acl_file = /path/to/kadmind.acl
150 mkey_file = /path/to/mkey
151 log_file = /path/to/iprop-log-file
155 To use LDAP, see @xref{Using LDAP to store the database}.
157 The keys of all the principals are stored in the database. If you
158 choose to, these can be encrypted with a master key. You do not have to
159 remember this key (or password), but just to enter it once and it will
160 be stored in a file (@file{/var/heimdal/m-key}). If you want to have a
161 master key, run @samp{kstash} to create this master key:
166 Verifying password - Master key:
169 If you want to generate a random master key you can use the
170 @kbd{--random-key} flag to kstash. This will make sure you have a good key
171 on which attackers can't do a dictionary attack.
173 If you have a master key, make sure you make a backup of your master
174 key file; without it backups of the database are of no use.
176 To initialise the database use the @command{kadmin} program, with the
177 @kbd{-l} option (to enable local database mode). First issue a
178 @kbd{init MY.REALM} command. This will create the database and insert
179 default principals for that realm. You can have more than one realm in
180 one database, so @samp{init} does not destroy any old database.
182 Before creating the database, @samp{init} will ask you some questions
183 about maximum ticket lifetimes.
185 After creating the database you should probably add yourself to it. You
186 do this with the @samp{add} command. It takes as argument the name of a
187 principal. The principal should contain a realm, so if you haven't set up
188 a default realm, you will need to explicitly include the realm.
192 kadmin> init MY.REALM
193 Realm max ticket life [unlimited]:
194 Realm max renewable ticket life [unlimited]:
196 Max ticket life [unlimited]:
197 Max renewable life [unlimited]:
200 Verifying password - Password:
203 Now start the KDC and try getting a ticket.
208 me@@MY.REALMS's Password:
210 Credentials cache: /tmp/krb5cc_0
211 Principal: me@@MY.REALM
213 Issued Expires Principal
214 Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM
217 If you are curious you can use the @samp{dump} command to list all the
218 entries in the database. It should look something similar to the
219 following example (note that the entries here are truncated for
220 typographical reasons):
224 me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ...
225 kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ...
226 krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ...
227 kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ...
230 @node Modifying the database, Checking the setup, Creating the database, Setting up a realm
231 @section Modifying the database
233 All modifications of principals are done with with kadmin.
235 A principal has several attributes and lifetimes associated with it.
237 Principals are added, renamed, modified, and deleted with the kadmin
238 commands @samp{add}, @samp{rename}, @samp{modify}, @samp{delete}.
239 Both interactive editing and command line flags can be used (use --help
240 to list the available options).
242 There are different kinds of types for the fields in the database;
243 attributes, absolute time times and relative times.
245 @subsection Attributes
247 When doing interactive editing, attributes are listed with @samp{?}.
249 The attributes are given in a comma (@samp{,}) separated list.
250 Attributes are removed from the list by prefixing them with @samp{-}.
254 Max ticket life [1 day]:
255 Max renewable life [1 week]:
256 Principal expiration time [never]:
257 Password expiration time [never]:
258 Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable
260 Principal: me@@MY.REALM
262 Attributes: requires-pre-auth
265 @subsection Absolute times
267 The format for absolute times are any of the following:
277 @subsection Relative times
279 The format for relative times are any of the following combined:
290 @c Describe more of kadmin commands here...
292 @node Checking the setup, keytabs, Modifying the database, Setting up a realm
293 @section Checking the setup
295 There are two tools that can check the consistency of the Kerberos
296 configuration file and the Kerberos database.
298 The Kerberos configuration file is checked using
299 @command{verify_krb5_conf}. The tool checks for common errors, but
300 commonly there are several uncommon configuration entries that are
301 never added to the tool and thus generates ``unknown entry'' warnings.
302 This is usually nothing to worry about.
304 The database check is built into the kadmin tool. It will check for
305 common configuration error that will cause problems later. Common
306 check are for existence and flags on important principals. The
307 database check by run by the following command :
310 kadmin -l check REALM.EXAMPLE.ORG
313 @node keytabs, Remote administration, Checking the setup, Setting up a realm
316 To extract a service ticket from the database and put it in a keytab, you
317 need to first create the principal in the database with @samp{add}
318 (using the @kbd{--random-key} flag to get a random key) and then
319 extract it with @samp{ext_keytab}.
322 kadmin> add --random-key host/my.host.name
323 Max ticket life [unlimited]:
324 Max renewable life [unlimited]:
326 kadmin> ext host/my.host.name
329 Version Type Principal
330 1 des-cbc-md5 host/my.host.name@@MY.REALM
331 1 des-cbc-md4 host/my.host.name@@MY.REALM
332 1 des-cbc-crc host/my.host.name@@MY.REALM
333 1 des3-cbc-sha1 host/my.host.name@@MY.REALM
336 @node Remote administration, Password changing, keytabs, Setting up a realm
337 @section Remote administration
339 The administration server, @command{kadmind}, can be started by
340 @command{inetd} (which isn't recommended) or run as a normal daemon. If you
341 want to start it from @command{inetd} you should add a line similar to the
342 one below to your @file{/etc/inetd.conf}.
345 kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind
348 You might need to add @samp{kerberos-adm} to your @file{/etc/services}
351 Access to the administration server is controlled by an ACL file,
352 (default @file{/var/heimdal/kadmind.acl}.) The file has the following
355 principal [priv1,priv2,...] [glob-pattern]
358 The matching is from top to bottom for matching principals (and if given,
359 glob-pattern). When there is a match, the access rights of that line are
362 The privileges you can assign to a principal are: @samp{add},
363 @samp{change-password} (or @samp{cpw} for short), @samp{delete},
364 @samp{get}, @samp{list}, and @samp{modify}, or the special privilege
365 @samp{all}. All of these roughly correspond to the different commands
368 If a @var{glob-pattern} is given on a line, it restricts the access
369 rights for the principal to only apply for subjects that match the
370 pattern. The patterns are of the same type as those used in shell
371 globbing, see @url{none,,fnmatch(3)}.
373 In the example below @samp{lha/admin} can change every principal in the
374 database. @samp{jimmy/admin} can only modify principals that belong to
375 the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the
376 help desk, so he should only be able to change the passwords for single
377 component principals (ordinary users). He will not be able to change any
378 @samp{/admin} principal.
381 lha/admin@@E.KTH.SE all
382 jimmy/admin@@E.KTH.SE all *@@E.KTH.SE
383 jimmy/admin@@E.KTH.SE all */*@@E.KTH.SE
384 mille/admin@@E.KTH.SE change-password *@@E.KTH.SE
387 @node Password changing, Testing clients and servers, Remote administration, Setting up a realm
388 @section Password changing
390 To allow users to change their passwords, you should run @command{kpasswdd}.
391 It is not run from @command{inetd}.
393 You might need to add @samp{kpasswd} to your @file{/etc/services} as
394 @samp{464/udp}. If your realm is not setup to use DNS, you might also
395 need to add a @samp{kpasswd_server} entry to the realm configuration
396 in @file{/etc/krb5.conf} on client machines:
401 kdc = my.kdc my.slave.kdc
402 kpasswd_server = my.kdc
406 @subsection Password quality assurance
408 It is important that users have good passwords, both to make it harder
409 to guess them and to avoid off-line attacks (although
410 pre-authentication provides some defence against off-line attacks).
411 To ensure that the users choose good passwords, you can enable
412 password quality controls in @command{kpasswdd} and @command{kadmind}.
413 The controls themselves are done in a shared library or an external
414 program that is used by @command{kpasswdd}. To configure in these
415 controls, add lines similar to the following to your
416 @file{/etc/krb5.conf}:
420 policies = external-check builtin:minimum-length modulename:policyname
421 external_program = /bin/false
422 policy_libraries = @var{library1.so} @var{library2.so}
425 In @samp{[password_quality]policies} the module name is optional if
426 the policy name is unique in all modules (members of
427 @samp{policy_libraries}). All built-in policies can be qualified with
428 a module name of @samp{builtin} to unambiguously specify the built-in
429 policy and not a policy by the same name from a loaded module.
431 The built-in policies are
437 Executes the program specified by @samp{[password_quality]external_program}.
439 A number of key/value pairs are passed as input to the program, one per
440 line, ending with the string @samp{end}. The key/value lines are of
443 principal: @var{principal}
444 new-password: @var{password}
446 where @var{password} is the password to check for the previous
449 If the external application approves the password, it should return
450 @samp{APPROVED} on standard out and exit with exit code 0. If it
451 doesn't approve the password, an one line error message explaining the
452 problem should be returned on standard error and the application
453 should exit with exit code 0. In case of a fatal error, the
454 application should, if possible, print an error message on standard
455 error and exit with a non-zero error code.
459 The minimum length password quality check reads the configuration file
460 stanza @samp{[password_quality]min_length} and requires the password
461 to be at least this length.
463 @item character-class
465 The character-class password quality check reads the configuration
466 file stanza @samp{[password_quality]min_classes}. The policy requires
467 the password to have characters from at least that many character
468 classes. Default value if not given is 3.
470 The four different characters classes are, uppercase, lowercase,
471 number, special characters.
473 @item enforce_on_admin_set
475 The enforce_on_admin_set check subjects administrative password updates to the
476 password policy. An administrative password update is a create principal or
477 change password request via @command{kadmind}, or a set password request via
478 @command{kpasswdd}. (A set password request is one where the authenticating
479 principal differs from the principal whose password is being changed.) Password
480 policies are always ignored if the authenticating principal is the kadmin
481 service itself, for example when running @command{kadmin} in local mode. The
482 default value for enforce_on_admin_set if not given is true.
486 If you want to write your own shared object to check password
487 policies, see the manual page @manpage{kadm5_pwcheck,3}.
489 Code for a password quality checking function that uses the cracklib
490 library can be found in @file{lib/kadm5/sample_password_check.c} in
491 the source code distribution. It requires that the cracklib library
492 be built with the patch available at
493 @url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}.
495 A sample policy external program is included in
496 @file{lib/kadm5/check-cracklib.pl}.
498 If no password quality checking function is configured, the only check
499 performed is that the password is at least six characters long.
501 To check the password policy settings, use the command
502 @command{verify-password-quality} in @command{kadmin} program. The password
503 verification is only performed locally, on the client. It may be
504 convenient to set the environment variable @samp{KRB5_CONFIG} to point
505 to a test version of @file{krb5.conf} while you're testing the
506 @samp{[password_quality]} stanza that way.
508 @node Testing clients and servers, Slave Servers, Password changing, Setting up a realm
509 @section Testing clients and servers
511 Now you should be able to run all the clients and servers. Refer to the
512 appropriate man pages for information on how to use them.
514 @node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm
515 @section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm
517 It is desirable to have at least one backup (slave) server in case the
518 master server fails. It is possible to have any number of such slave
519 servers but more than three usually doesn't buy much more redundancy.
521 All Kerberos servers for a realm must have the same database so that
522 they present the same service to the users. The
524 @command{hprop} program, running on the master, will propagate the database
525 to the slaves, running
527 @command{hpropd} processes.
529 Every slave needs a database directory, the master key (if it was used
530 for the database) and a keytab with the principal
531 @samp{hprop/@var{hostname}}. Add the principal with the
533 @command{ktutil} command and start
535 @command{hpropd}, as follows:
538 slave# ktutil get -p foo/admin hprop/`hostname`
539 slave# mkdir /var/heimdal
543 The master will use the principal @samp{kadmin/hprop} to authenticate to
544 the slaves. This principal should be added when running @kbd{kadmin -l
545 init} but if you do not have it in your database for whatever reason,
546 please add it with @kbd{kadmin -l add}.
550 @code{hprop} on the master:
556 This was just an hands-on example to make sure that everything was
557 working properly. Doing it manually is of course the wrong way, and to
558 automate this you will want to start
560 @command{hpropd} from @command{inetd} on the slave(s) and regularly run
562 @command{hprop} on the master to regularly propagate the database.
563 Starting the propagation once an hour from @command{cron} is probably a
566 @node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm
567 @section Incremental propagation
569 There is also a newer mechanism for
570 doing incremental propagation in Heimdal. Instead of sending the whole
571 database regularly, it sends the changes as they happen on the master to
572 the slaves. The master keeps track of all the changes by assigning a
573 version number to every change to the database. The slaves know which
574 was the latest version they saw and in this way it can be determined if
575 they are in sync or not. A log of all the changes is kept on the master,
576 and when a slave is at an older version than the oldest one in the
577 log, the whole database has to be sent.
579 Protocol-wise, all the slaves connect to the master and as a greeting
580 tell it the latest version that they have (@samp{IHAVE} message). The
581 master then responds by sending all the changes between that version and
582 the current version at the master (a series of @samp{FORYOU} messages)
583 or the whole database in a @samp{TELLYOUEVERYTHING} message. There is
584 also a keep-alive protocol that makes sure all slaves are up and running.
586 In addition on listening on the network to get connection from new
587 slaves, the ipropd-master also listens on a status unix
588 socket. kadmind and kpasswdd both open that socket when a transation
589 is done and written a notification to the socket. That cause
590 ipropd-master to check for new version in the log file. As a fallback in
591 case a notification is lost by the unix socket, the log file is
592 checked after 30 seconds of no event.
594 @subsection Configuring incremental propagation
596 The program that runs on the master is @command{ipropd-master} and all
597 clients run @command{ipropd-slave}.
599 Create the file @file{/var/heimdal/slaves} on the master containing all
600 the slaves that the database should be propagated to. Each line contains
601 the full name of the principal (for example
602 @samp{iprop/hemligare.foo.se@@FOO.SE}).
604 You should already have @samp{iprop/tcp} defined as 2121, in your
605 @file{/etc/services}. Otherwise, or if you need to use a different port
606 for some peculiar reason, you can use the @kbd{--port} option. This is
607 useful when you have multiple realms to distribute from one server.
609 Then you need to create those principals that you added in the
610 configuration file. Create one @samp{iprop/hostname} for the master and
615 master# /usr/heimdal/sbin/ktutil get iprop/`hostname`
619 slave# /usr/heimdal/sbin/ktutil get iprop/`hostname`
623 The next step is to start the @command{ipropd-master} process on the master
624 server. The @command{ipropd-master} listens on the UNIX domain socket
625 @file{/var/heimdal/signal} to know when changes have been made to the
626 database so they can be propagated to the slaves. There is also a
627 safety feature of testing the version number regularly (every 30
628 seconds) to see if it has been modified by some means that do not raise
629 this signal. Then, start @command{ipropd-slave} on all the slaves:
632 master# /usr/heimdal/libexec/ipropd-master &
633 slave# /usr/heimdal/libexec/ipropd-slave master &
636 To manage the iprop log file you should use the @command{iprop-log}
637 command. With it you can dump, truncate and replay the logfile.
639 @subsection Status of iprop master and slave
641 Both the master and slave provides status of the world as they see it.
643 The master write outs the current status of the slaves, last seen and
644 their version number in @file{/var/heimdal/slaves-stats}.
646 The slave write out the current status in @file{/var/heimdal/ipropd-slave-status}.
648 These locations can be changed with command line options, and in the
649 case of @command{ipropd_master}, the configuration file.
651 @node Encryption types and salting, Credential cache server - KCM, Incremental propagation, Setting up a realm
652 @section Encryption types and salting
654 @cindex Encryption types
656 The encryption types that the KDC is going to assign by default is
657 possible to change. Since the keys used for user authentication is
658 salted the encryption types are described together with the salt
661 Salting is used to make it harder to pre-calculate all possible
662 keys. Using a salt increases the search space to make it almost
663 impossible to pre-calculate all keys. Salting is the process of mixing a
664 public string (the salt) with the password, then sending it through an
665 encryption type specific string-to-key function that will output the
666 fixed size encryption key.
668 In Kerberos 5 the salt is determined by the encryption type, except in
671 In @code{des} there is the Kerberos 4 salt
672 (none at all) or the afs-salt (using the cell (realm in
675 In @code{arcfour} (the encryption type that Microsoft Windows 2000 uses)
676 there is no salt. This is to be compatible with NTLM keys in Windows
679 @code{[kadmin]default_keys} in @file{krb5.conf} controls
682 The syntax of @code{[kadmin]default_keys} is
683 @samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption
684 type (des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96),
685 @code{salt-type} is the type of salt (pw-salt or afs3-salt), and the
686 salt-string is the string that will be used as salt (remember that if
687 the salt is appended/prepended, the empty salt "" is the same thing as
690 Common types of salting include
693 @item @code{v4} (or @code{des:pw-salt:})
695 The Kerberos 4 salting is using no salt at all. Reason there is colon
696 at the end of the salt string is that it makes the salt the empty
697 string (same as no salt).
699 @item @code{v5} (or @code{pw-salt})
701 @code{pw-salt} uses the default salt for each encryption type is
702 specified for. If the encryption type @samp{etype} isn't given, all
703 default encryption will be used.
705 @item @code{afs3-salt}
707 @code{afs3-salt} is the salt that is used with Transarc kaserver. It's
708 the cell name appended to the password.
712 @node Credential cache server - KCM, Cross realm, Encryption types and salting, Setting up a realm
713 @section Credential cache server - KCM
715 @cindex Credential cache server
717 When KCM running is easy for users to switch between different
718 kerberos principals using @file{kswitch} or built in support in
719 application, like OpenSSH's GSSAPIClientIdentity.
721 Other advantages are that there is the long term credentials are not
722 written to disk and on reboot the credential is removed when kcm
723 process stopps running.
725 Configure the system startup script to start the kcm process,
726 @file{/usr/heimdal/libexec/kcm} and then configure the system to use kcm in @file{krb5.conf}.
730 default_cc_type = KCM
733 Now when you run @command{kinit} it doesn't overwrite your existing
734 credentials but rather just add them to the set of
735 credentials. @command{klist -l} lists the credentials and the star
736 marks the default credential.
740 lha@@KTH.SE's Password:
742 Name Cache name Expires
743 lha@@KTH.SE 0 Nov 22 23:09:40 *
744 lha@@SU.SE Initial default ccache Nov 22 14:14:24
747 When switching between credentials you can use @command{kswitch}.
757 After switching, a new set of credentials are used as default.
761 Name Cache name Expires
762 lha@@SU.SE Initial default ccache Nov 22 14:14:24 *
763 lha@@KTH.SE 0 Nov 22 23:09:40
766 Som applications, like openssh with Simon Wilkinsons patch applied,
767 support specifiying that credential to use. The example below will
768 login to the host computer.kth.se using lha@@KTH.SE (not the current
773 -o GSSAPIAuthentication=yes \
774 -o GSSAPIKeyExchange=yes \
775 -o GSSAPIClientIdentity=lha@@KTH.SE \
781 @node Cross realm, Transit policy, Credential cache server - KCM, Setting up a realm
785 Suppose you reside in the realm @samp{MY.REALM}, how do you
786 authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in
787 @samp{MY.REALM} allows you to communicate with Kerberised services in that
788 realm. However, the computer in the other realm does not have a secret
789 key shared with the Kerberos server in your realm.
791 It is possible to share keys between two realms that trust each
792 other. When a client program, such as @command{telnet} or @command{ssh},
793 finds that the other computer is in a different realm, it will try to
794 get a ticket granting ticket for that other realm, but from the local
795 Kerberos server. With that ticket granting ticket, it will then obtain
796 service tickets from the Kerberos server in the other realm.
798 For a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM}
799 add the following principals to each realm. The principals should be
800 @samp{krbtgt/OTHER.REALM@@MY.REALM} and
801 @samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and
802 @samp{krbtgt/MY.REALM@@OTHER.REALM} and
803 @samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}.
805 In Kerberos 5 the trust can be configured to be one way. So that
806 users from @samp{MY.REALM} can authenticate to services in
807 @samp{OTHER.REALM}, but not the opposite. In the example above, the
808 @samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed.
810 The two principals must have the same key, key version number, and the
811 same set of encryption types. Remember to transfer the two keys in a
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
822 vr$ telnet -l lha hummel.it.su.se
823 Trying 2001:6b0:5:1095:250:fcff:fe24:dbf...
824 Connected to hummel.it.su.se.
825 Escape character is '^]'.
826 Waiting for encryption to be negotiated...
827 [ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ]
828 [ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ]
829 Encryption negotiated.
830 Last login: Sat May 3 14:11:47 from vr.l.nxs.se
834 Credentials cache: FILE:/tmp/krb5cc_913.console
835 Principal: lha@@E.KTH.SE
837 Issued Expires Principal
838 May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE
839 May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@@E.KTH.SE
840 May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE
844 @node Transit policy, Setting up DNS, Cross realm, Setting up a realm
845 @section Transit policy
846 @cindex Transit policy
848 Under some circumstances, you may not wish to set up direct
849 cross-realm trust with every realm to which you wish to authenticate
850 or from which you wish to accept authentications. Kerberos supports
851 multi-hop cross-realm trust where a client principal in realm A
852 authenticates to a service in realm C through a realm B with which
853 both A and C have cross-realm trust relationships. In this situation,
854 A and C need not set up cross-realm principals between each other.
856 If you want to use cross-realm authentication through an intermediate
857 realm, it must be explicitly allowed by either the KDCs for the realm
858 to which the client is authenticating (in this case, realm C), or the
859 server receiving the request. This is done in @file{krb5.conf} in the
860 @code{[capaths]} section.
862 In addition, the client in realm A need to be configured to know how
863 to reach realm C via realm B. This can be done either on the client or
864 via KDC configuration in the KDC for realm A.
866 @subsection Allowing cross-realm transits
868 When the ticket transits through a realm to another realm, the
869 destination realm adds its peer to the "transited-realms" field in the
870 ticket. The field is unordered, since there is no way to know if know
871 if one of the transited-realms changed the order of the list. For the
872 authentication to be accepted by the final destination realm, all of
873 the transited realms must be listed as trusted in the @code{[capaths]}
874 configuration, either in the KDC for the destination realm or on the
875 server receiving the authentication.
877 The syntax for @code{[capaths]} section is:
882 SERVER-REALM = PERMITTED-CROSS-REALMS ...
886 In the following example, the realm @code{STACKEN.KTH.SE} only has
887 direct cross-realm set up with @code{KTH.SE}. @code{KTH.SE} has
888 direct cross-realm set up with @code{STACKEN.KTH.SE} and @code{SU.SE}.
889 @code{DSV.SU.SE} only has direct cross-realm set up with @code{SU.SE}.
890 The goal is to allow principals in the @code{DSV.SU.SE} or
891 @code{SU.SE} realms to authenticate to services in
892 @code{STACKEN.KTH.SE}. This is done with the following
893 @code{[capaths]} entry on either the server accepting authentication
894 or on the KDC for @code{STACKEN.KTH.SE}.
899 STACKEN.KTH.SE = KTH.SE
902 STACKEN.KTH.SE = SU.SE KTH.SE
906 The first entry allows cross-realm authentication from clients in
907 @code{SU.SE} transiting through @code{KTH.SE} to
908 @code{STACKEN.KTH.SE}. The second entry allows cross-realm
909 authentication from clients in @code{DSV.SU.SE} transiting through
910 both @code{SU.SE} and @code{KTH.SE} to @code{STACKEN.KTH.SE}.
912 Be careful of which realm goes where; it's easy to put realms in the
913 wrong place. The block is tagged with the client realm (the realm of
914 the principal authenticating), and the realm before the equal sign is
915 the final destination realm: the realm to which the client is
916 authenticating. After the equal sign go all the realms that the
917 client transits through.
919 The order of the @code{PERMITTED-CROSS-REALMS} is not important when
920 doing transit cross realm verification.
922 @subsection Configuring client cross-realm transits
924 The @code{[capaths]} section is also used for another purpose: to tell
925 clients which realm to transit through to reach a realm with which
926 their local realm does not have cross-realm trust. This can be done
927 by either putting a @code{[capaths]} entry in the configuration of the
928 client or by putting the entry in the configuration of the KDC for the
929 client's local realm. In the latter case, the KDC will then hand back
930 a referral to the client when the client requests a cross-realm ticket
931 to the destination realm, telling the client to try to go through an
934 For client configuration, the order of @code{PERMITTED-CROSS-REALMS}
935 is significant, since only the first realm in this section (after the
936 equal sign) is used by the client.
938 For example, again consider the @code{[capaths]} entry above for the
939 case of a client in the @code{SU.SE} realm, and assume that the client
940 or the @code{SU.SE} KDC has that @code{[capaths]} entry. If the
941 client attempts to authenticate to a service in the
942 @code{STACKEN.KTH.SE} realm, that entry says to first authenticate
943 cross-realm to the @code{KTH.SE} realm (the first realm listed in the
944 @code{PERMITTED-CROSS-REALMS} section), and then from there to
945 @code{STACKEN.KTH.SE}.
947 Each entry in @code{[capaths]} can only give the next hop, since only
948 the first realm in @code{PERMITTED-CROSS-REALMS} is used. If, for
949 instance, a client in @code{DSV.SU.SE} had a @code{[capaths]}
950 configuration as above but without the first block for @code{SU.SE},
951 they would not be able to reach @code{STACKEN.KTH.SE}. They would get
952 as far as @code{SU.SE} based on the @code{DSV.SU.SE} entry in
953 @code{[capaths]} and then attempt to go directly from there to
954 @code{STACKEN.KTH.SE} and get stuck (unless, of course, the
955 @code{SU.SE} KDC had the additional entry required to tell the client
956 to go through @code{KTH.SE}).
958 @subsection Active Directory forest example
960 One common place where a @code{[capaths]} configuration is desirable
961 is with Windows Active Directory forests. One common Active Directory
962 configuration is to have one top-level Active Directory realm but then
963 divide systems, services, and users into child realms (perhaps based
964 on organizational unit). One generally establishes cross-realm trust
965 only with the top-level realm, and then uses transit policy to permit
966 authentications to and from the child realms.
968 For example, suppose an organization has a Heimdal realm
969 @code{EXAMPLE.COM}, a Windows Active Directory realm
970 @code{WIN.EXAMPLE.COM}, and then child Active Directory realms
971 @code{ENGR.WIN.EXAMPLE.COM} and @code{SALES.WIN.EXAMPLE.COM}. The
972 goal is to allow users in any of these realms to authenticate to
973 services in any of these realms. The @code{EXAMPLE.COM} KDC (and
974 possibly client) configuration should therefore contain a
975 @code{[capaths]} section as follows:
979 ENGR.WIN.EXAMPLE.COM = @{
980 EXAMPLE.COM = WIN.EXAMPLE.COM
982 SALES.WIN.EXAMPLE.COM = @{
983 EXAMPLE.COM = WIN.EXAMPLE.COM
986 ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
987 SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
991 The first two blocks allow clients in the @code{ENGR.WIN.EXAMPLE.COM}
992 and @code{SALES.WIN.EXAMPLE.COM} realms to authenticate to services in
993 the @code{EXAMPLE.COM} realm. The third block tells the client (or
994 tells the KDC to tell the client via referrals) to transit through
995 @code{WIN.EXAMPLE.COM} to reach these realms. Both sides of the
996 configuration are needed for bi-directional transited cross-realm
999 @c To test the cross realm configuration, use:
1000 @c kmumble transit-check client server transit-realms ...
1002 @node Setting up DNS, Using LDAP to store the database, Transit policy, Setting up a realm
1003 @section Setting up DNS
1004 @cindex Setting up DNS
1006 @subsection Using DNS to find KDC
1008 If there is information about where to find the KDC or kadmind for a
1009 realm in the @file{krb5.conf} for a realm, that information will be
1010 preferred, and DNS will not be queried.
1012 Heimdal will try to use DNS to find the KDCs for a realm. First it
1013 will try to find a @code{SRV} resource record (RR) for the realm. If no
1014 SRV RRs are found, it will fall back to looking for an @code{A} RR for
1015 a machine named kerberos.REALM, and then kerberos-1.REALM, etc
1017 Adding this information to DNS minimises the client configuration (in
1018 the common case, resulting in no configuration needed) and allows the
1019 system administrator to change the number of KDCs and on what machines
1020 they are running without caring about clients.
1022 The downside of using DNS is that the client might be fooled to use the
1023 wrong server if someone fakes DNS replies/data, but storing the IP
1024 addresses of the KDC on all the clients makes it very hard to change
1027 An example of the configuration for the realm @code{EXAMPLE.COM}:
1031 $ORIGIN example.com.
1032 _kerberos._tcp SRV 10 1 88 kerberos.example.com.
1033 _kerberos._udp SRV 10 1 88 kerberos.example.com.
1034 _kerberos._tcp SRV 10 1 88 kerberos-1.example.com.
1035 _kerberos._udp SRV 10 1 88 kerberos-1.example.com.
1036 _kpasswd._udp SRV 10 1 464 kerberos.example.com.
1037 _kerberos-adm._tcp SRV 10 1 749 kerberos.example.com.
1041 More information about DNS SRV resource records can be found in
1042 RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)).
1044 @subsection Using DNS to map hostname to Kerberos realm
1046 Heimdal also supports a way to lookup a realm from a hostname. This to
1047 minimise configuration needed on clients. Using this has the drawback
1048 that clients can be redirected by an attacker to realms within the
1049 same cross realm trust and made to believe they are talking to the
1050 right server (since Kerberos authentication will succeed).
1052 An example configuration that informs clients that for the realms
1053 it.example.com and srv.example.com, they should use the realm
1058 $ORIGIN example.com.
1059 _kerberos.it TXT "EXAMPLE.COM"
1060 _kerberos.srv TXT "EXAMPLE.COM"
1064 @node Using LDAP to store the database, Providing Kerberos credentials to servers and programs, Setting up DNS, Setting up a realm
1065 @section Using LDAP to store the database
1066 @cindex Using the LDAP backend
1068 This document describes how to install the LDAP backend for
1069 Heimdal. Note that before attempting to configure such an
1070 installation, you should be aware of the implications of storing
1071 private information (such as users' keys) in a directory service
1072 primarily designed for public information. Nonetheless, with a
1073 suitable authorisation policy, it is possible to set this up in a
1074 secure fashion. A knowledge of LDAP, Kerberos, and C is necessary to
1075 install this backend. The HDB schema was devised by Leif Johansson.
1077 This assumes, OpenLDAP 2.3 or later.
1084 A current release of Heimdal, configured with
1085 @code{--with-openldap=/usr/local} (adjust according to where you have
1086 installed OpenLDAP).
1088 You can verify that you manage to configure LDAP support by running
1089 @file{kdc --builtin-hdb}, and checking that @samp{ldap:} is one entry
1092 Its also possible to configure the ldap backend as a shared module,
1093 see option --hdb-openldap-module to configure.
1096 Optionally configure OpenLDAP with @kbd{--enable-local} to enable the
1100 Add the hdb schema to the LDAP server, it's included in the source-tree
1101 in @file{lib/hdb/hdb.schema}. Example from slapd.conf:
1104 include /usr/local/etc/openldap/schema/hdb.schema
1108 Configure the LDAP server ACLs to accept writes from clients. For
1113 by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write
1116 authz-regexp "gidNumber=.*\\\+uidNumber=0,cn=peercred,cn=external,cn=auth''
1117 "uid=heimdal,dc=services,dc=example,dc=com"
1121 The sasl-regexp is for mapping between the SASL/EXTERNAL and a user in
1122 a tree. The user that the key is mapped to should be have a
1123 krb5Principal aux object with krb5PrincipalName set so that the
1124 ``creator'' and ``modifier'' is right in @file{kadmin}.
1126 Another option is to create an admins group and add the dn to that
1129 If a non-local LDAP connection is used, the authz-regexp is not
1130 needed as Heimdal will bind to LDAP over the network using
1131 provided credentials.
1133 Since Heimdal talks to the LDAP server over a UNIX domain socket when
1134 configured for ldapi:///, and uses external sasl authentication, it's
1135 not possible to require security layer quality (ssf in cyrus-sasl lingo).
1136 So that requirement has to be turned off in OpenLDAP @command{slapd}
1141 sasl-secprops minssf=0
1146 Start @command{slapd} with the local listener (as well as the default TCP/IP
1147 listener on port 389) as follows:
1150 slapd -h "ldapi:/// ldap:///"
1153 Note: These is a bug in @command{slapd} where it appears to corrupt the krb5Key
1154 binary attribute on shutdown. This may be related to our use of the V3
1155 schema definition syntax instead of the old UMich-style, V2 syntax.
1158 You should specify the distinguished name under which your
1159 principals will be stored in @file{krb5.conf}. Also you need to
1160 enter the path to the kadmin acl file:
1165 # Optional configuration
1166 hdb-ldap-structural-object = inetOrgPerson
1167 hdb-ldap-url = ldapi:/// (default), ldap://hostname or ldaps://hostname
1168 hdb-ldap-secret-file = /path/to/file/containing/ldap/credentials
1169 hdb-ldap-start-tls = false
1172 dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com
1173 acl_file = /path/to/kadmind.acl
1174 mkey_file = /path/to/mkey
1178 @samp{mkey_file} can be excluded if you feel that you trust your ldap
1179 directory to have the raw keys inside it. The
1180 hdb-ldap-structural-object is not necessary if you do not need Samba
1183 If connecting to a server over a non-local transport, the @samp{hdb-ldap-url}
1184 and @samp{hdb-ldap-secret-file} options must be provided. The
1185 @samp{hdb-ldap-secret-file} must contain the bind credentials:
1189 hdb-ldap-bind-dn = uid=heimdal,dc=services,dc=example,dc=com
1190 hdb-ldap-bind-password = secretBindPassword
1193 The @samp{hdb-ldap-secret-file} and should be protected with appropriate
1197 Once you have built Heimdal and started the LDAP server, run kadmin
1198 (as usual) to initialise the database. Note that the instructions for
1199 stashing a master key are as per any Heimdal installation.
1203 kadmin> init EXAMPLE.COM
1204 Realm max ticket life [unlimited]:
1205 Realm max renewable ticket life [unlimited]:
1207 Max ticket life [1 day]:
1208 Max renewable life [1 week]:
1209 Principal expiration time [never]:
1210 Password expiration time [never]:
1212 lukeh@@EXAMPLE.COM's Password:
1213 Verifying password - lukeh@@EXAMPLE.COM's Password:
1217 Verify that the principal database has indeed been stored in the
1218 directory with the following command:
1221 kdc# ldapsearch -L -h localhost -D cn=manager \
1222 -w secret -b ou=KerberosPrincipals,dc=example,dc=com \
1223 'objectclass=krb5KDCEntry'
1227 Now consider adding indexes to the database to speed up the access, at
1228 least theses should be added to slapd.conf.
1231 index objectClass eq
1232 index cn eq,sub,pres
1233 index uid eq,sub,pres
1234 index displayName eq,sub,pres
1235 index krb5PrincipalName eq
1240 @subsection smbk5pwd overlay
1242 The smbk5pwd overlay, updates the krb5Key and krb5KeyVersionNumber
1243 appropriately when it receives an LDAP Password change Extended
1246 @url{http://www.openldap.org/devel/cvsweb.cgi/contrib/slapd-modules/smbk5pwd/README?hideattic=1&sortbydate=0}
1248 @subsection Troubleshooting guide
1250 @url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide}
1253 @subsection Using Samba LDAP password database
1256 @c @node Using Samba LDAP password database, Providing Kerberos credentials to servers and programs, Using LDAP to store the database, Setting up a realm
1257 @c @section Using Samba LDAP password database
1259 The Samba domain and the Kerberos realm can have different names since
1260 arcfour's string to key functions principal/realm independent. So now
1261 will be your first and only chance name your Kerberos realm without
1262 needing to deal with old configuration files.
1264 First, you should set up Samba and get that working with LDAP backend.
1266 Now you can proceed as in @xref{Using LDAP to store the database}.
1267 Heimdal will pick up the Samba LDAP entries if they are in the same
1268 search space as the Kerberos entries.
1270 @node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm
1271 @section Providing Kerberos credentials to servers and programs
1273 Some services require Kerberos credentials when they start to make
1274 connections to other services or need to use them when they have started.
1276 The easiest way to get tickets for a service is to store the key in a
1277 keytab. Both ktutil get and kadmin ext can be used to get a
1278 keytab. ktutil get is better in that way it changes the key/password
1279 for the user. This is also the problem with ktutil. If ktutil is used
1280 for the same service principal on several hosts, they keytab will only
1281 be useful on the last host. In that case, run the extract command on
1282 one host and then securely copy the keytab around to all other hosts
1286 host# ktutil -k /etc/krb5-service.keytab \
1287 get -p lha/admin@@EXAMPLE.ORG service-principal@@EXAMPLE.ORG
1288 lha/admin@@EXAMPLE.ORG's Password:
1291 To get a Kerberos credential file for the service, use kinit in the
1292 @kbd{--keytab} mode. This will not ask for a password but instead fetch the
1293 key from the keytab.
1296 service@@host$ kinit --cache=/var/run/service_krb5_cache \
1297 --keytab=/etc/krb5-service.keytab \
1298 service-principal@@EXAMPLE.ORG
1301 Long running services might need credentials longer then the
1302 expiration time of the tickets. kinit can run in a mode that refreshes
1303 the tickets before they expire. This is useful for services that write
1304 into AFS and other distributed file systems using Kerberos. To run the
1305 long running script, just append the program and arguments (if any)
1306 after the principal. kinit will stop refreshing credentials and remove
1307 the credentials when the script-to-start-service exits.
1310 service@@host$ kinit --cache=/var/run/service_krb5_cache \
1311 --keytab=/etc/krb5-service.keytab \
1312 service-principal@@EXAMPLE.ORG \
1313 script-to-start-service argument1 argument2
1317 @node Setting up PK-INIT, Debugging Kerberos problems, Providing Kerberos credentials to servers and programs, Setting up a realm
1318 @section Setting up PK-INIT
1320 PK-INIT leverages an existing PKI (public key infrastructure), using
1321 certificates to get the initial ticket (usually the krbtgt
1322 ticket-granting ticket).
1324 To use PK-INIT you must first have a PKI. If you don't have one, it is
1325 time to create it. You should first read the whole current chapter of
1326 the document to see the requirements imposed on the CA software.
1328 A mapping between the PKI certificate and what principals that
1329 certificate is allowed to use must exist. There are several ways to do
1330 this. The administrator can use a configuration file, store the
1331 principal in the SubjectAltName extension of the certificate, or store
1332 the mapping in the principals entry in the kerberos database.
1334 @section Certificates
1336 This and following subsection documents the requirements on the KDC
1337 and client certificates and the format used in the id-pkinit-san
1338 OtherName extension.
1340 On how to create certificates, you should read @ref{Use OpenSSL to
1341 create certificates}.
1343 @subsection KDC certificate
1345 The certificate for the KDC has several requirements.
1347 First, the certificate should have an Extended Key Usage (EKU)
1348 id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second, there must be a
1349 subjectAltName otherName using OID id-pkinit-san (1.3.6.1.5.2.2) in
1350 the type field and a DER encoded KRB5PrincipalName that matches the
1351 name of the TGS of the target realm. Also, if the certificate has a
1352 nameConstraints extension with a Generalname with dNSName or iPAdress,
1353 it must match the hostname or adress of the KDC.
1355 The client is not required by the standard to check the server
1356 certificate for this information if the client has external
1357 information confirming which certificate the KDC is supposed to be
1358 using. However, adding this information to the KDC certificate removes
1359 the need to specially configure the client to recognize the KDC
1362 Remember that if the client would accept any certificate as the KDC's
1363 certificate, the client could be fooled into trusting something that
1364 isn't a KDC and thus expose the user to giving away information (like
1365 a password or other private information) that it is supposed to keep
1368 @subsection Client certificate
1370 The client certificate may need to have a EKU id-pkekuoid
1371 (1.3.6.1.5.2.3.4) set depending on the configuration on the KDC.
1373 It possible to store the principal (if allowed by the KDC) in the
1374 certificate and thus delegate responsibility to do the mapping between
1375 certificates and principals to the CA.
1377 This behavior is controlled by KDC configuration option:
1381 pkinit_principal_in_certificate = yes
1384 @subsubsection Using KRB5PrincipalName in id-pkinit-san
1386 The OtherName extension in the GeneralName is used to do the mapping
1387 between certificate and principal. For the KDC certificate, this
1388 stores the krbtgt principal name for that KDC. For the client
1389 certificate, this stores the principal for which that certificate is
1390 allowed to get tickets.
1392 The principal is stored in a SubjectAltName in the certificate using
1393 OtherName. The OID in the type is id-pkinit-san.
1396 id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6)
1397 internet (1) security (5) kerberosv5 (2) 2 @}
1400 The data part of the OtherName is filled with the following DER
1401 encoded ASN.1 structure:
1404 KRB5PrincipalName ::= SEQUENCE @{
1406 principalName [1] PrincipalName
1410 where Realm and PrincipalName is defined by the Kerberos ASN.1
1413 @section Naming certificate using hx509
1415 hx509 is the X.509 software used in Heimdal to handle
1416 certificates. hx509 supports several different syntaxes for specifying
1417 certificate files or formats. Several formats may be used: PEM,
1418 certificates embedded in PKCS#12 files, certificates embedded in
1419 PKCS#11 devices, and raw DER encoded certificates.
1421 Those formats may be specified as follows:
1427 DIR specifies a directory which contains certificates in the DER or
1430 The main feature of DIR is that the directory is read on demand when
1431 iterating over certificates. This allows applications, in some
1432 situations, to avoid having to store all certificates in memory. It's
1433 very useful for tests that iterate over large numbers of certificates.
1438 DIR:/path/to/der/files
1443 FILE: specifies a file that contains a certificate or private key.
1444 The file can be either a PEM (openssl) file or a raw DER encoded
1445 certificate. If it's a PEM file, it can contain several keys and
1446 certificates and the code will try to match the private key and
1447 certificate together. Multiple files may be specified, separated by
1450 It's useful to have one PEM file that contains all the trust anchors.
1455 FILE:certificate.pem,private-key.key,other-cert.pem,....
1460 PKCS11: is used to handle smartcards via PKCS#11 drivers, such as
1461 soft-token, opensc, or muscle. The argument specifies a shared object
1462 that implements the PKCS#11 API. The default is to use all slots on
1468 PKCS11:shared-object.so
1473 PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have
1474 the extension pfx or p12.
1479 PKCS12:/path/to/file.pfx
1484 @section Configure the Kerberos software
1486 First configure the client's trust anchors and what parameters to
1487 verify. See the subsections below for how to do that. Then, you can
1488 use kinit to get yourself tickets. For example:
1491 $ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG
1492 Enter your private key passphrase:
1493 : lha@@nutcracker ; klist
1494 Credentials cache: FILE:/tmp/krb5cc_19100a
1495 Principal: lha@@EXAMPLE.ORG
1497 Issued Expires Principal
1498 Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
1501 Using PKCS#11 it can look like this instead:
1504 $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG
1505 PIN code for SoftToken (slot):
1507 Credentials cache: API:4
1508 Principal: lha@@EXAMPLE.ORG
1510 Issued Expires Principal
1511 Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
1514 @section Configure the client
1518 pkinit_anchors = FILE:/path/to/trust-anchors.pem
1522 pkinit_require_eku = true
1523 pkinit_require_krbtgt_otherName = true
1525 pkinit_win2k_require_binding = yes
1530 @section Configure the KDC
1532 Configuration options for the KDC.
1535 @item enable-pkinit = bool
1537 Enable PKINIT for this KDC.
1539 @item pkinit_identity = string
1541 Identity that the KDC will use when talking to clients. Mandatory.
1543 @item pkinit_anchors = string
1545 Trust anchors that the KDC will use when evaluating the trust of the
1546 client certificate. Mandatory.
1548 @item pkinit_pool = strings ...
1550 Extra certificate the KDC will use when building trust chains if it
1551 can't find enough certificates in the request from the client.
1553 @item pkinit_allow_proxy_certificate = bool
1555 Allow clients to use proxy certificates. The root certificate
1556 of the client's End Entity certificate is used for authorisation.
1558 @item pkinit_win2k_require_binding = bool
1560 Require windows clients up be upgrade to not allow cut and paste
1561 attack on encrypted data, applies to Windows XP and windows 2000
1564 @item pkinit_principal_in_certificate = bool
1566 Enable the KDC to use id-pkinit-san to determine to determine the
1567 mapping between a certificate and principal.
1574 pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key
1575 pkinit_anchors = FILE:/path/to/trust-anchors.pem
1576 pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx
1577 pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem
1578 pkinit_allow_proxy_certificate = no
1579 pkinit_win2k_require_binding = yes
1580 pkinit_principal_in_certificate = no
1583 @subsection Using pki-mapping file
1585 Note that the file contents are space sensitive.
1588 # cat /var/heimdal/pki-mapping
1589 # comments starts with #
1590 lha@@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha
1591 lha@@EXAMPLE.ORG:CN=Love,UID=lha
1594 @subsection Using the Kerberos database
1596 You can also store the subject of the certificate in the principal
1597 entry in the kerberos database.
1600 kadmin modify --pkinit-acl="CN=baz,DC=test,DC=h5l,DC=se" user@@REALM
1603 @section Use hxtool to create certificates
1605 @subsection Generate certificates
1607 First, you need to generate a CA certificate. This example creates a
1608 CA certificate that will be valid for 10 years.
1610 You need to change --subject in the command below to something
1611 appropriate for your site.
1614 hxtool issue-certificate \
1617 --generate-key=rsa \
1618 --subject="CN=CA,DC=test,DC=h5l,DC=se" \
1619 --lifetime=10years \
1620 --certificate="FILE:ca.pem"
1623 The KDC needs to have a certificate, so generate a certificate of the
1624 type ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the
1625 name of the krbtgt of the realm.
1627 You need to change --subject and --pk-init-principal in the command
1628 below to something appropriate for your site.
1631 hxtool issue-certificate \
1632 --ca-certificate=FILE:ca.pem \
1633 --generate-key=rsa \
1634 --type="pkinit-kdc" \
1635 --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
1636 --subject="uid=kdc,DC=test,DC=h5l,DC=se" \
1637 --certificate="FILE:kdc.pem"
1640 The users also needs to have certificates. For your first client,
1641 generate a certificate of type ``pkinit-client''. The client doesn't
1642 need to have the PK-INIT SubjectAltName set; you can have the Subject
1643 DN in the ACL file (pki-mapping) instead.
1645 You need to change --subject and --pk-init-principal in the command
1646 below to something appropriate for your site. You can omit
1647 --pk-init-principal if you're going to use the ACL file instead.
1650 hxtool issue-certificate \
1651 --ca-certificate=FILE:ca.pem \
1652 --generate-key=rsa \
1653 --type="pkinit-client" \
1654 --pk-init-principal="lha@@TEST.H5L.SE" \
1655 --subject="uid=lha,DC=test,DC=h5l,DC=se" \
1656 --certificate="FILE:user.pem"
1659 @subsection Validate the certificate
1661 hxtool also contains a tool that will validate certificates according
1662 to rules from the PKIX document. These checks are not complete, but
1663 they provide a good test of whether you got all of the basic bits
1664 right in your certificates.
1667 hxtool validate FILE:user.pem
1670 @section Use OpenSSL to create certificates
1671 @anchor{Use OpenSSL to create certificates}
1673 This section tries to give the CA owners hints how to create
1674 certificates using OpenSSL (or CA software based on OpenSSL).
1676 @subsection Using OpenSSL to create certificates with krb5PrincipalName
1678 To make OpenSSL create certificates with krb5PrincipalName, use an
1679 @file{openssl.cnf} as described below. To see a complete example of
1680 creating client and KDC certificates, see the test-data generation
1681 script @file{lib/hx509/data/gen-req.sh} in the source-tree. The
1682 certicates it creates are used to test the PK-INIT functionality in
1683 @file{tests/kdc/check-kdc.in}.
1685 To use this example you have to use OpenSSL 0.9.8a or later.
1690 subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name
1693 realm = EXP:0, GeneralString:MY.REALM
1694 principal_name = EXP:1, SEQUENCE:principal_seq
1697 name_type = EXP:0, INTEGER:1
1698 name_string = EXP:1, SEQUENCE:principals
1701 princ1 = GeneralString:userid
1708 openssl x509 -extensions user_certificate
1709 openssl ca -extensions user_certificate
1713 @c --- ms certificate
1716 @c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2
1719 @c [ req_smartcard ]
1720 @c keyUsage = digitalSignature, keyEncipherment
1721 @c extendedKeyUsage = msSmartcardLogin, clientAuth
1722 @c msCertificateTemplateName = ASN1:BMP:SmartcardLogon
1723 @c subjectAltName = otherName:msUPN;UTF8:lukeh@dsg.padl.com
1724 @c #subjectAltName = email:copy
1727 @section Using PK-INIT with Windows
1729 @subsection Client configration
1731 Clients using a Windows KDC with PK-INIT need configuration since
1732 windows uses pre-standard format and this can't be autodetected.
1734 The pkinit_win2k_require_binding option requires the reply for the KDC
1735 to be of the new, secure, type that binds the request to
1736 reply. Before, clients could fake the reply from the KDC. To use this
1737 option you have to apply a fix from Microsoft.
1743 pkinit_win2k_require_binding = no
1747 @subsection Certificates
1749 The client certificates need to have the extended keyusage ``Microsoft
1750 Smartcardlogin'' (openssl has the OID shortname msSmartcardLogin).
1752 See Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling
1753 Smart Card Logon with Third-Party Certification Authorities'' for a
1754 more extensive description of how set setup an external CA so that it
1755 includes all the information required to make a Windows KDC happy.
1757 @subsection Configure Windows 2000 CA
1759 To enable Microsoft Smartcardlogin for certificates in your Windows
1760 2000 CA, you want to look at Microsoft Knowledge Base Article - 313274
1761 ``HOW TO: Configure a Certification Authority to Issue Smart Card
1762 Certificates in Windows''.
1764 @node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm
1765 @section Debugging Kerberos problems
1767 To debug Kerberos client and server problems you can enable debug
1768 tracing by adding the following to @file{/etc/krb5.conf}. Note that the
1769 trace logging is sparse at the moment, but will continue to improve.
1773 libkrb5 = 0-/SYSLOG: