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 * Serving Kerberos 4/524/kaserver::
21 * Remote administration::
23 * Testing clients and servers::
25 * Incremental propagation::
26 * Encryption types and salting::
27 * Credential cache server - KCM::
31 * Using LDAP to store the database::
32 * Providing Kerberos credentials to servers and programs::
33 * Setting up PK-INIT::
34 * Debugging Kerberos problems::
37 @node Configuration file, Creating the database, Setting up a realm, Setting up a realm
38 @section Configuration file
40 To setup a realm you will first have to create a configuration file:
41 @file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many
42 configuration options, some of which are described here.
44 There is a sample @file{krb5.conf} supplied with the distribution.
46 The configuration file is a hierarchical structure consisting of
47 sections, each containing a list of bindings (either variable
48 assignments or subsections). A section starts with
49 @samp{[@samp{section-name}]}. A binding consists of a left hand side, an equal sign
50 (@samp{=}) and a right hand side (the left hand side tag must be
51 separated from the equal sign with some whitespace). Subsections have a
52 @samp{@{} as the first non-whitespace character after the equal sign. All
53 other bindings are treated as variable assignments. The value of a
54 variable extends to the end of the line.
60 other-var = value with @{@}
65 var = some other value
67 var = yet another value
70 In this manual, names of sections and bindings will be given as strings
71 separated by slashes (@samp{/}). The @samp{other-var} variable will thus
72 be @samp{section1/a-subsection/other-var}.
74 For in-depth information about the contents of the configuration file, refer to
75 the @file{krb5.conf} manual page. Some of the more important sections
76 are briefly described here.
78 The @samp{libdefaults} section contains a list of library configuration
79 parameters, such as the default realm and the timeout for KDC
80 responses. The @samp{realms} section contains information about specific
81 realms, such as where they hide their KDC@. This section serves the same
82 purpose as the Kerberos 4 @file{krb.conf} file, but can contain more
83 information. Finally the @samp{domain_realm} section contains a list of
84 mappings from domains to realms, equivalent to the Kerberos 4
85 @file{krb.realms} file.
87 To continue with the realm setup, you will have to create a configuration file,
88 with contents similar to the following.
92 default_realm = MY.REALM
95 kdc = my.kdc my.slave.kdc
98 kdc = [2001:6b0:1:ea::100]:88
101 .my.domain = MY.REALM
105 If you use a realm name equal to your domain name, you can omit the
106 @samp{libdefaults}, and @samp{domain_realm}, sections. If you have a DNS
107 SRV-record for your realm, or your Kerberos server has DNS CNAME
108 @samp{kerberos.my.realm}, you can omit the @samp{realms} section too.
110 @node Creating the database, Modifying the database, Configuration file, Setting up a realm
111 @section Creating the database
113 The database library will look for the database in the directory
114 @file{@value{dbdir}}, so you should probably create that directory.
115 Make sure the directory has restrictive permissions.
121 The keys of all the principals are stored in the database. If you
122 choose to, these can be encrypted with a master key. You do not have to
123 remember this key (or password), but just to enter it once and it will
124 be stored in a file (@file{/var/heimdal/m-key}). If you want to have a
125 master key, run @samp{kstash} to create this master key:
130 Verifying password - Master key:
133 If you want to generate a random master key you can use the
134 @kbd{--random-key} flag to kstash. This will make sure you have a good key
135 on which attackers can't do a dictionary attack.
137 If you have a master key, make sure you make a backup of your master
138 key file; without it backups of the database are of no use.
140 To initialise the database use the @command{kadmin} program, with the
141 @kbd{-l} option (to enable local database mode). First issue a
142 @kbd{init MY.REALM} command. This will create the database and insert
143 default principals for that realm. You can have more than one realm in
144 one database, so @samp{init} does not destroy any old database.
146 Before creating the database, @samp{init} will ask you some questions
147 about maximum ticket lifetimes.
149 After creating the database you should probably add yourself to it. You
150 do this with the @samp{add} command. It takes as argument the name of a
151 principal. The principal should contain a realm, so if you haven't set up
152 a default realm, you will need to explicitly include the realm.
156 kadmin> init MY.REALM
157 Realm max ticket life [unlimited]:
158 Realm max renewable ticket life [unlimited]:
160 Max ticket life [unlimited]:
161 Max renewable life [unlimited]:
164 Verifying password - Password:
167 Now start the KDC and try getting a ticket.
172 me@@MY.REALMS's Password:
174 Credentials cache: /tmp/krb5cc_0
175 Principal: me@@MY.REALM
177 Issued Expires Principal
178 Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM
181 If you are curious you can use the @samp{dump} command to list all the
182 entries in the database. It should look something similar to the
183 following example (note that the entries here are truncated for
184 typographical reasons):
188 me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ...
189 kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ...
190 krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ...
191 kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ...
194 @node Modifying the database, Checking the setup, Creating the database, Setting up a realm
195 @section Modifying the database
197 All modifications of principals are done with with kadmin.
199 A principal has several attributes and lifetimes associated with it.
201 Principals are added, renamed, modified, and deleted with the kadmin
202 commands @samp{add}, @samp{rename}, @samp{modify}, @samp{delete}.
203 Both interactive editing and command line flags can be used (use --help
204 to list the available options).
206 There are different kinds of types for the fields in the database;
207 attributes, absolute time times and relative times.
209 @subsection Attributes
211 When doing interactive editing, attributes are listed with @samp{?}.
213 The attributes are given in a comma (@samp{,}) separated list.
214 Attributes are removed from the list by prefixing them with @samp{-}.
218 Max ticket life [1 day]:
219 Max renewable life [1 week]:
220 Principal expiration time [never]:
221 Password expiration time [never]:
222 Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable
224 Principal: me@@MY.REALM
226 Attributes: requires-pre-auth
229 @subsection Absolute times
231 The format for absolute times are any of the following:
241 @subsection Relative times
243 The format for relative times are any of the following combined:
254 @c Describe more of kadmin commands here...
256 @node Checking the setup, keytabs, Modifying the database, Setting up a realm
257 @section Checking the setup
259 There are two tools that can check the consistency of the Kerberos
260 configuration file and the Kerberos database.
262 The Kerberos configuration file is checked using
263 @command{verify_krb5_conf}. The tool checks for common errors, but
264 commonly there are several uncommon configuration entries that are
265 never added to the tool and thus generates ``unknown entry'' warnings.
266 This is usually nothing to worry about.
268 The database check is built into the kadmin tool. It will check for
269 common configuration error that will cause problems later. Common
270 check are for existence and flags on important principals. The
271 database check by run by the following command :
274 kadmin -l check REALM.EXAMPLE.ORG
277 @node keytabs, Serving Kerberos 4/524/kaserver, Checking the setup, Setting up a realm
280 To extract a service ticket from the database and put it in a keytab, you
281 need to first create the principal in the database with @samp{add}
282 (using the @kbd{--random-key} flag to get a random key) and then
283 extract it with @samp{ext_keytab}.
286 kadmin> add --random-key host/my.host.name
287 Max ticket life [unlimited]:
288 Max renewable life [unlimited]:
290 kadmin> ext host/my.host.name
293 Version Type Principal
294 1 des-cbc-md5 host/my.host.name@@MY.REALM
295 1 des-cbc-md4 host/my.host.name@@MY.REALM
296 1 des-cbc-crc host/my.host.name@@MY.REALM
297 1 des3-cbc-sha1 host/my.host.name@@MY.REALM
300 @node Serving Kerberos 4/524/kaserver, Remote administration, keytabs, Setting up a realm
301 @section Serving Kerberos 4/524/kaserver
303 Heimdal can be configured to support 524, Kerberos 4 or kaserver. All
304 these services are turned off by default. Kerberos 4 is always
305 supported by the KDC, but the Kerberos 4 client support also depends
306 on Kerberos 4 support having been included at compile-time, using
307 @kbd{--with-krb4=dir}.
311 524 is a service that allows the KDC to convert Kerberos 5 tickets to
312 Kerberos 4 tickets for backward compatibility. See also Using 2b
313 tokens with AFS in @xref{AFS}.
315 524 can be turned on by adding this to the configuration file
322 @subsection Kerberos 4
324 Kerberos 4 is the predecessor to to Kerberos 5. It only supports
325 single DES@. You should only enable Kerberos 4 support if you have
326 needs for compatibility with an installed base of Kerberos 4
329 Kerberos 4 can be turned on by adding this to the configuration file
333 enable-kerberos4 = yes
338 Kaserver is a Kerberos 4 that is used in AFS@. The protocol has some
339 extra features over plain Kerberos 4, but like Kerberos 4, only uses
342 You should only enable Kaserver support if you have needs for
343 compatibility with an installed base of AFS machines.
345 Kaserver can be turned on by adding this to the configuration file
349 enable-kaserver = yes
352 @node Remote administration, Password changing, Serving Kerberos 4/524/kaserver, Setting up a realm
353 @section Remote administration
355 The administration server, @command{kadmind}, can be started by
356 @command{inetd} (which isn't recommended) or run as a normal daemon. If you
357 want to start it from @command{inetd} you should add a line similar to the
358 one below to your @file{/etc/inetd.conf}.
361 kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind
364 You might need to add @samp{kerberos-adm} to your @file{/etc/services}
367 Access to the administration server is controlled by an ACL file,
368 (default @file{/var/heimdal/kadmind.acl}.) The file has the following
371 principal [priv1,priv2,...] [glob-pattern]
374 The matching is from top to bottom for matching principals (and if given,
375 glob-pattern). When there is a match, the access rights of that line are
378 The privileges you can assign to a principal are: @samp{add},
379 @samp{change-password} (or @samp{cpw} for short), @samp{delete},
380 @samp{get}, @samp{list}, and @samp{modify}, or the special privilege
381 @samp{all}. All of these roughly correspond to the different commands
384 If a @var{glob-pattern} is given on a line, it restricts the access
385 rights for the principal to only apply for subjects that match the
386 pattern. The patterns are of the same type as those used in shell
387 globbing, see @url{none,,fnmatch(3)}.
389 In the example below @samp{lha/admin} can change every principal in the
390 database. @samp{jimmy/admin} can only modify principals that belong to
391 the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the
392 help desk, so he should only be able to change the passwords for single
393 component principals (ordinary users). He will not be able to change any
394 @samp{/admin} principal.
397 lha/admin@@E.KTH.SE all
398 jimmy/admin@@E.KTH.SE all *@@E.KTH.SE
399 jimmy/admin@@E.KTH.SE all */*@@E.KTH.SE
400 mille/admin@@E.KTH.SE change-password *@@E.KTH.SE
403 @node Password changing, Testing clients and servers, Remote administration, Setting up a realm
404 @section Password changing
406 To allow users to change their passwords, you should run @command{kpasswdd}.
407 It is not run from @command{inetd}.
409 You might need to add @samp{kpasswd} to your @file{/etc/services} as
412 @subsection Password quality assurance
414 It is important that users have good passwords, both to make it harder
415 to guess them and to avoid off-line attacks (although
416 pre-authentication provides some defence against off-line attacks).
417 To ensure that the users choose good passwords, you can enable
418 password quality controls in @command{kpasswdd} and @command{kadmind}.
419 The controls themselves are done in a shared library or an external
420 program that is used by @command{kpasswdd}. To configure in these
421 controls, add lines similar to the following to your
422 @file{/etc/krb5.conf}:
426 policies = external-check builtin:minimum-length modulename:policyname
427 external_program = /bin/false
428 policy_libraries = @var{library1.so} @var{library2.so}
431 In @samp{[password_quality]policies} the module name is optional if
432 the policy name is unique in all modules (members of
433 @samp{policy_libraries}). All built-in policies can be qualified with
434 a module name of @samp{builtin} to unambiguously specify the built-in
435 policy and not a policy by the same name from a loaded module.
437 The built-in policies are
443 Executes the program specified by @samp{[password_quality]external_program}.
445 A number of key/value pairs are passed as input to the program, one per
446 line, ending with the string @samp{end}. The key/value lines are of
449 principal: @var{principal}
450 new-password: @var{password}
452 where @var{password} is the password to check for the previous
455 If the external application approves the password, it should return
456 @samp{APPROVED} on standard out and exit with exit code 0. If it
457 doesn't approve the password, an one line error message explaining the
458 problem should be returned on standard error and the application
459 should exit with exit code 0. In case of a fatal error, the
460 application should, if possible, print an error message on standard
461 error and exit with a non-zero error code.
465 The minimum length password quality check reads the configuration file
466 stanza @samp{[password_quality]min_length} and requires the password
467 to be at least this length.
469 @item character-class
471 The character-class password quality check reads the configuration
472 file stanza @samp{[password_quality]min_classes}. The policy requires
473 the password to have characters from at least that many character
474 classes. Default value if not given is 3.
476 The four different characters classes are, uppercase, lowercase,
477 number, special characters.
481 If you want to write your own shared object to check password
482 policies, see the manual page @manpage{kadm5_pwcheck,3}.
484 Code for a password quality checking function that uses the cracklib
485 library can be found in @file{lib/kadm5/sample_password_check.c} in
486 the source code distribution. It requires that the cracklib library
487 be built with the patch available at
488 @url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}.
490 A sample policy external program is included in
491 @file{lib/kadm5/check-cracklib.pl}.
493 If no password quality checking function is configured, the only check
494 performed is that the password is at least six characters long.
496 To check the password policy settings, use the command
497 @command{verify-password-quality} in @command{kadmin} program. The password
498 verification is only performed locally, on the client. It may be
499 convenient to set the environment variable @samp{KRB5_CONFIG} to point
500 to a test version of @file{krb5.conf} while you're testing the
501 @samp{[password_quality]} stanza that way.
503 @node Testing clients and servers, Slave Servers, Password changing, Setting up a realm
504 @section Testing clients and servers
506 Now you should be able to run all the clients and servers. Refer to the
507 appropriate man pages for information on how to use them.
509 @node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm
510 @section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm
512 It is desirable to have at least one backup (slave) server in case the
513 master server fails. It is possible to have any number of such slave
514 servers but more than three usually doesn't buy much more redundancy.
516 All Kerberos servers for a realm must have the same database so that
517 they present the same service to the users. The
519 @command{hprop} program, running on the master, will propagate the database
520 to the slaves, running
522 @command{hpropd} processes.
524 Every slave needs a database directory, the master key (if it was used
525 for the database) and a keytab with the principal
526 @samp{hprop/@var{hostname}}. Add the principal with the
528 @command{ktutil} command and start
530 @command{hpropd}, as follows:
533 slave# ktutil get -p foo/admin hprop/`hostname`
534 slave# mkdir /var/heimdal
538 The master will use the principal @samp{kadmin/hprop} to authenticate to
539 the slaves. This principal should be added when running @kbd{kadmin -l
540 init} but if you do not have it in your database for whatever reason,
541 please add it with @kbd{kadmin -l add}.
545 @code{hprop} on the master:
551 This was just an hands-on example to make sure that everything was
552 working properly. Doing it manually is of course the wrong way, and to
553 automate this you will want to start
555 @command{hpropd} from @command{inetd} on the slave(s) and regularly run
557 @command{hprop} on the master to regularly propagate the database.
558 Starting the propagation once an hour from @command{cron} is probably a
561 @node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm
562 @section Incremental propagation
564 There is also a newer mechanism for
565 doing incremental propagation in Heimdal. Instead of sending the whole
566 database regularly, it sends the changes as they happen on the master to
567 the slaves. The master keeps track of all the changes by assigning a
568 version number to every change to the database. The slaves know which
569 was the latest version they saw and in this way it can be determined if
570 they are in sync or not. A log of all the changes is kept on the master,
571 and when a slave is at an older version than the oldest one in the
572 log, the whole database has to be sent.
574 Protocol-wise, all the slaves connect to the master and as a greeting
575 tell it the latest version that they have (@samp{IHAVE} message). The
576 master then responds by sending all the changes between that version and
577 the current version at the master (a series of @samp{FORYOU} messages)
578 or the whole database in a @samp{TELLYOUEVERYTHING} message. There is
579 also a keep-alive protocol that makes sure all slaves are up and running.
581 In addition on listening on the network to get connection from new
582 slaves, the ipropd-master also listens on a status unix
583 socket. kadmind and kpasswdd both open that socket when a transation
584 is done and written a notification to the socket. That cause
585 ipropd-master to check for new version in the log file. As a fallback in
586 case a notification is lost by the unix socket, the log file is
587 checked after 30 seconds of no event.
589 @subsection Configuring incremental propagation
591 The program that runs on the master is @command{ipropd-master} and all
592 clients run @command{ipropd-slave}.
594 Create the file @file{/var/heimdal/slaves} on the master containing all
595 the slaves that the database should be propagated to. Each line contains
596 the full name of the principal (for example
597 @samp{iprop/hemligare.foo.se@@FOO.SE}).
599 You should already have @samp{iprop/tcp} defined as 2121, in your
600 @file{/etc/services}. Otherwise, or if you need to use a different port
601 for some peculiar reason, you can use the @kbd{--port} option. This is
602 useful when you have multiple realms to distribute from one server.
604 Then you need to create those principals that you added in the
605 configuration file. Create one @samp{iprop/hostname} for the master and
610 master# /usr/heimdal/sbin/ktutil get iprop/`hostname`
614 slave# /usr/heimdal/sbin/ktutil get iprop/`hostname`
618 The next step is to start the @command{ipropd-master} process on the master
619 server. The @command{ipropd-master} listens on the UNIX domain socket
620 @file{/var/heimdal/signal} to know when changes have been made to the
621 database so they can be propagated to the slaves. There is also a
622 safety feature of testing the version number regularly (every 30
623 seconds) to see if it has been modified by some means that do not raise
624 this signal. Then, start @command{ipropd-slave} on all the slaves:
627 master# /usr/heimdal/libexec/ipropd-master &
628 slave# /usr/heimdal/libexec/ipropd-slave master &
631 To manage the iprop log file you should use the @command{iprop-log}
632 command. With it you can dump, truncate and replay the logfile.
634 @node Encryption types and salting, Credential cache server - KCM, Incremental propagation, Setting up a realm
635 @section Encryption types and salting
637 @cindex Encryption types
639 The encryption types that the KDC is going to assign by default is
640 possible to change. Since the keys used for user authentication is
641 salted the encryption types are described together with the salt
644 Salting is used to make it harder to pre-calculate all possible
645 keys. Using a salt increases the search space to make it almost
646 impossible to pre-calculate all keys. Salting is the process of mixing a
647 public string (the salt) with the password, then sending it through an
648 encryption type specific string-to-key function that will output the
649 fixed size encryption key.
651 In Kerberos 5 the salt is determined by the encryption type, except in
654 In @code{des} there is the Kerberos 4 salt
655 (none at all) or the afs-salt (using the cell (realm in
658 In @code{arcfour} (the encryption type that Microsoft Windows 2000 uses)
659 there is no salt. This is to be compatible with NTLM keys in Windows
662 @code{[kadmin]default_keys} in @file{krb5.conf} controls
665 The syntax of @code{[kadmin]default_keys} is
666 @samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption
667 type (des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96),
668 @code{salt-type} is the type of salt (pw-salt or afs3-salt), and the
669 salt-string is the string that will be used as salt (remember that if
670 the salt is appended/prepended, the empty salt "" is the same thing as
673 Common types of salting include
676 @item @code{v4} (or @code{des:pw-salt:})
678 The Kerberos 4 salting is using no salt at all. Reason there is colon
679 at the end of the salt string is that it makes the salt the empty
680 string (same as no salt).
682 @item @code{v5} (or @code{pw-salt})
684 @code{pw-salt} uses the default salt for each encryption type is
685 specified for. If the encryption type @samp{etype} isn't given, all
686 default encryption will be used.
688 @item @code{afs3-salt}
690 @code{afs3-salt} is the salt that is used with Transarc kaserver. It's
691 the cell name appended to the password.
695 @node Credential cache server - KCM, Cross realm, Encryption types and salting, Setting up a realm
696 @section Credential cache server - KCM
698 @cindex Credential cache server
700 When KCM running is easy for users to switch between different
701 kerberos principals using @file{kswitch} or built in support in
702 application, like OpenSSH's GSSAPIClientIdentity.
704 Other advantages are that there is the long term credentials are not
705 written to disk and on reboot the credential is removed when kcm
706 process stopps running.
708 Configure the system startup script to start the kcm process,
709 @file{/usr/heimdal/libexec/kcm} and then configure the system to use kcm in @file{krb5.conf}.
713 default_cc_type = KCM
716 Now when you run @command{kinit} it doesn't overwrite your existing
717 credentials but rather just add them to the set of
718 credentials. @command{klist -l} lists the credentials and the star
719 marks the default credential.
723 lha@@KTH.SE's Password:
725 Name Cache name Expires
726 lha@@KTH.SE 0 Nov 22 23:09:40 *
727 lha@@SU.SE Initial default ccache Nov 22 14:14:24
730 When switching between credentials you can use @command{kswitch}.
740 After switching, a new set of credentials are used as default.
744 Name Cache name Expires
745 lha@@SU.SE Initial default ccache Nov 22 14:14:24 *
746 lha@@KTH.SE 0 Nov 22 23:09:40
749 Som applications, like openssh with Simon Wilkinsons patch applied,
750 support specifiying that credential to use. The example below will
751 login to the host computer.kth.se using lha@@KTH.SE (not the current
756 -o GSSAPIAuthentication=yes \
757 -o GSSAPIKeyExchange=yes \
758 -o GSSAPIClientIdentity=lha@@KTH.SE \
764 @node Cross realm, Transit policy, Credential cache server - KCM, Setting up a realm
768 Suppose you reside in the realm @samp{MY.REALM}, how do you
769 authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in
770 @samp{MY.REALM} allows you to communicate with Kerberised services in that
771 realm. However, the computer in the other realm does not have a secret
772 key shared with the Kerberos server in your realm.
774 It is possible to share keys between two realms that trust each
775 other. When a client program, such as @command{telnet} or @command{ssh},
776 finds that the other computer is in a different realm, it will try to
777 get a ticket granting ticket for that other realm, but from the local
778 Kerberos server. With that ticket granting ticket, it will then obtain
779 service tickets from the Kerberos server in the other realm.
781 For a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM}
782 add the following principals to each realm. The principals should be
783 @samp{krbtgt/OTHER.REALM@@MY.REALM} and
784 @samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and
785 @samp{krbtgt/MY.REALM@@OTHER.REALM} and
786 @samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}.
788 In Kerberos 5 the trust can be configured to be one way. So that
789 users from @samp{MY.REALM} can authenticate to services in
790 @samp{OTHER.REALM}, but not the opposite. In the example above, the
791 @samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed.
793 The two principals must have the same key, key version number, and the
794 same set of encryption types. Remember to transfer the two keys in a
799 Credentials cache: FILE:/tmp/krb5cc_913.console
800 Principal: lha@@E.KTH.SE
802 Issued Expires Principal
803 May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE
805 vr$ telnet -l lha hummel.it.su.se
806 Trying 2001:6b0:5:1095:250:fcff:fe24:dbf...
807 Connected to hummel.it.su.se.
808 Escape character is '^]'.
809 Waiting for encryption to be negotiated...
810 [ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ]
811 [ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ]
812 Encryption negotiated.
813 Last login: Sat May 3 14:11:47 from vr.l.nxs.se
817 Credentials cache: FILE:/tmp/krb5cc_913.console
818 Principal: lha@@E.KTH.SE
820 Issued Expires Principal
821 May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE
822 May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@@E.KTH.SE
823 May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE
827 @node Transit policy, Setting up DNS, Cross realm, Setting up a realm
828 @section Transit policy
829 @cindex Transit policy
831 Under some circumstances, you may not wish to set up direct
832 cross-realm trust with every realm to which you wish to authenticate
833 or from which you wish to accept authentications. Kerberos supports
834 multi-hop cross-realm trust where a client principal in realm A
835 authenticates to a service in realm C through a realm B with which
836 both A and C have cross-realm trust relationships. In this situation,
837 A and C need not set up cross-realm principals between each other.
839 If you want to use cross-realm authentication through an intermediate
840 realm, it must be explicitly allowed by either the KDCs for the realm
841 to which the client is authenticating (in this case, realm C), or the
842 server receiving the request. This is done in @file{krb5.conf} in the
843 @code{[capaths]} section.
845 In addition, the client in realm A need to be configured to know how
846 to reach realm C via realm B. This can be done either on the client or
847 via KDC configuration in the KDC for realm A.
849 @subsection Allowing cross-realm transits
851 When the ticket transits through a realm to another realm, the
852 destination realm adds its peer to the "transited-realms" field in the
853 ticket. The field is unordered, since there is no way to know if know
854 if one of the transited-realms changed the order of the list. For the
855 authentication to be accepted by the final destination realm, all of
856 the transited realms must be listed as trusted in the @code{[capaths]}
857 configuration, either in the KDC for the destination realm or on the
858 server receiving the authentication.
860 The syntax for @code{[capaths]} section is:
865 SERVER-REALM = PERMITTED-CROSS-REALMS ...
869 In the following example, the realm @code{STACKEN.KTH.SE} only has
870 direct cross-realm set up with @code{KTH.SE}. @code{KTH.SE} has
871 direct cross-realm set up with @code{STACKEN.KTH.SE} and @code{SU.SE}.
872 @code{DSV.SU.SE} only has direct cross-realm set up with @code{SU.SE}.
873 The goal is to allow principals in the @code{DSV.SU.SE} or
874 @code{SU.SE} realms to authenticate to services in
875 @code{STACKEN.KTH.SE}. This is done with the following
876 @code{[capaths]} entry on either the server accepting authentication
877 or on the KDC for @code{STACKEN.KTH.SE}.
882 STACKEN.KTH.SE = KTH.SE
885 STACKEN.KTH.SE = SU.SE KTH.SE
889 The first entry allows cross-realm authentication from clients in
890 @code{SU.SE} transiting through @code{KTH.SE} to
891 @code{STACKEN.KTH.SE}. The second entry allows cross-realm
892 authentication from clients in @code{DSV.SU.SE} transiting through
893 both @code{SU.SE} and @code{KTH.SE} to @code{STACKEN.KTH.SE}.
895 Be careful of which realm goes where; it's easy to put realms in the
896 wrong place. The block is tagged with the client realm (the realm of
897 the principal authenticating), and the realm before the equal sign is
898 the final destination realm: the realm to which the client is
899 authenticating. After the equal sign go all the realms that the
900 client transits through.
902 The order of the @code{PERMITTED-CROSS-REALMS} is not important when
903 doing transit cross realm verification.
905 @subsection Configuring client cross-realm transits
907 The @code{[capaths]} section is also used for another purpose: to tell
908 clients which realm to transit through to reach a realm with which
909 their local realm does not have cross-realm trust. This can be done
910 by either putting a @code{[capaths]} entry in the configuration of the
911 client or by putting the entry in the configuration of the KDC for the
912 client's local realm. In the latter case, the KDC will then hand back
913 a referral to the client when the client requests a cross-realm ticket
914 to the destination realm, telling the client to try to go through an
917 For client configuration, the order of @code{PERMITTED-CROSS-REALMS}
918 is significant, since only the first realm in this section (after the
919 equal sign) is used by the client.
921 For example, again consider the @code{[capaths]} entry above for the
922 case of a client in the @code{SU.SE} realm, and assume that the client
923 or the @code{SU.SE} KDC has that @code{[capaths]} entry. If the
924 client attempts to authenticate to a service in the
925 @code{STACKEN.KTH.SE} realm, that entry says to first authenticate
926 cross-realm to the @code{KTH.SE} realm (the first realm listed in the
927 @code{PERMITTED-CROSS-REALMS} section), and then from there to
928 @code{STACKEN.KTH.SE}.
930 Each entry in @code{[capaths]} can only give the next hop, since only
931 the first realm in @code{PERMITTED-CROSS-REALMS} is used. If, for
932 instance, a client in @code{DSV.SU.SE} had a @code{[capaths]}
933 configuration as above but without the first block for @code{SU.SE},
934 they would not be able to reach @code{STACKEN.KTH.SE}. They would get
935 as far as @code{SU.SE} based on the @code{DSV.SU.SE} entry in
936 @code{[capaths]} and then attempt to go directly from there to
937 @code{STACKEN.KTH.SE} and get stuck (unless, of course, the
938 @code{SU.SE} KDC had the additional entry required to tell the client
939 to go through @code{KTH.SE}).
941 @subsection Active Directory forest example
943 One common place where a @code{[capaths]} configuration is desirable
944 is with Windows Active Directory forests. One common Active Directory
945 configuration is to have one top-level Active Directory realm but then
946 divide systems, services, and users into child realms (perhaps based
947 on organizational unit). One generally establishes cross-realm trust
948 only with the top-level realm, and then uses transit policy to permit
949 authentications to and from the child realms.
951 For example, suppose an organization has a Heimdal realm
952 @code{EXAMPLE.COM}, a Windows Active Directory realm
953 @code{WIN.EXAMPLE.COM}, and then child Active Directory realms
954 @code{ENGR.WIN.EXAMPLE.COM} and @code{SALES.WIN.EXAMPLE.COM}. The
955 goal is to allow users in any of these realms to authenticate to
956 services in any of these realms. The @code{EXAMPLE.COM} KDC (and
957 possibly client) configuration should therefore contain a
958 @code{[capaths]} section as follows:
962 ENGR.WIN.EXAMPLE.COM = @{
963 EXAMPLE.COM = WIN.EXAMPLE.COM
965 SALES.WIN.EXAMPLE.COM = @{
966 EXAMPLE.COM = WIN.EXAMPLE.COM
969 ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
970 SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
974 The first two blocks allow clients in the @code{ENGR.WIN.EXAMPLE.COM}
975 and @code{SALES.WIN.EXAMPLE.COM} realms to authenticate to services in
976 the @code{EXAMPLE.COM} realm. The third block tells the client (or
977 tells the KDC to tell the client via referrals) to transit through
978 @code{WIN.EXAMPLE.COM} to reach these realms. Both sides of the
979 configuration are needed for bi-directional transited cross-realm
982 @c To test the cross realm configuration, use:
983 @c kmumble transit-check client server transit-realms ...
985 @node Setting up DNS, Using LDAP to store the database, Transit policy, Setting up a realm
986 @section Setting up DNS
987 @cindex Setting up DNS
989 @subsection Using DNS to find KDC
991 If there is information about where to find the KDC or kadmind for a
992 realm in the @file{krb5.conf} for a realm, that information will be
993 preferred, and DNS will not be queried.
995 Heimdal will try to use DNS to find the KDCs for a realm. First it
996 will try to find a @code{SRV} resource record (RR) for the realm. If no
997 SRV RRs are found, it will fall back to looking for an @code{A} RR for
998 a machine named kerberos.REALM, and then kerberos-1.REALM, etc
1000 Adding this information to DNS minimises the client configuration (in
1001 the common case, resulting in no configuration needed) and allows the
1002 system administrator to change the number of KDCs and on what machines
1003 they are running without caring about clients.
1005 The downside of using DNS is that the client might be fooled to use the
1006 wrong server if someone fakes DNS replies/data, but storing the IP
1007 addresses of the KDC on all the clients makes it very hard to change
1010 An example of the configuration for the realm @code{EXAMPLE.COM}:
1014 $ORIGIN example.com.
1015 _kerberos._tcp SRV 10 1 88 kerberos.example.com.
1016 _kerberos._udp SRV 10 1 88 kerberos.example.com.
1017 _kerberos._tcp SRV 10 1 88 kerberos-1.example.com.
1018 _kerberos._udp SRV 10 1 88 kerberos-1.example.com.
1019 _kpasswd._udp SRV 10 1 464 kerberos.example.com.
1020 _kerberos-adm._tcp SRV 10 1 749 kerberos.example.com.
1024 More information about DNS SRV resource records can be found in
1025 RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)).
1027 @subsection Using DNS to map hostname to Kerberos realm
1029 Heimdal also supports a way to lookup a realm from a hostname. This to
1030 minimise configuration needed on clients. Using this has the drawback
1031 that clients can be redirected by an attacker to realms within the
1032 same cross realm trust and made to believe they are talking to the
1033 right server (since Kerberos authentication will succeed).
1035 An example configuration that informs clients that for the realms
1036 it.example.com and srv.example.com, they should use the realm
1041 $ORIGIN example.com.
1042 _kerberos.it TXT "EXAMPLE.COM"
1043 _kerberos.srv TXT "EXAMPLE.COM"
1047 @node Using LDAP to store the database, Providing Kerberos credentials to servers and programs, Setting up DNS, Setting up a realm
1048 @section Using LDAP to store the database
1049 @cindex Using the LDAP backend
1051 This document describes how to install the LDAP backend for
1052 Heimdal. Note that before attempting to configure such an
1053 installation, you should be aware of the implications of storing
1054 private information (such as users' keys) in a directory service
1055 primarily designed for public information. Nonetheless, with a
1056 suitable authorisation policy, it is possible to set this up in a
1057 secure fashion. A knowledge of LDAP, Kerberos, and C is necessary to
1058 install this backend. The HDB schema was devised by Leif Johansson.
1060 This assumes, OpenLDAP 2.3 or later.
1067 A current release of Heimdal, configured with
1068 @code{--with-openldap=/usr/local} (adjust according to where you have
1069 installed OpenLDAP).
1071 You can verify that you manage to configure LDAP support by running
1072 @file{kdc --builtin-hdb}, and checking that @samp{ldap:} is one entry
1075 Its also possible to configure the ldap backend as a shared module,
1076 see option --hdb-openldap-module to configure.
1079 Configure OpenLDAP with @kbd{--enable-local} to enable the local transport.
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 over the
1091 local transport. For example:
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 Since Heimdal talks to the LDAP server over a UNIX domain socket, and
1112 uses external sasl authentication, it's not possible to require
1113 security layer quality (ssf in cyrus-sasl lingo). So that requirement
1114 has to be turned off in OpenLDAP @command{slapd} configuration file
1118 sasl-secprops minssf=0
1123 Start @command{slapd} with the local listener (as well as the default TCP/IP
1124 listener on port 389) as follows:
1127 slapd -h "ldapi:/// ldap:///"
1130 Note: These is a bug in @command{slapd} where it appears to corrupt the krb5Key
1131 binary attribute on shutdown. This may be related to our use of the V3
1132 schema definition syntax instead of the old UMich-style, V2 syntax.
1135 You should specify the distinguished name under which your
1136 principals will be stored in @file{krb5.conf}. Also you need to
1137 enter the path to the kadmin acl file:
1143 dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com
1144 hdb-ldap-structural-object = inetOrgPerson
1145 acl_file = /path/to/kadmind.acl
1146 mkey_file = /path/to/mkey
1150 @samp{mkey_file} can be excluded if you feel that you trust your ldap
1151 directory to have the raw keys inside it. The
1152 hdb-ldap-structural-object is not necessary if you do not need Samba
1158 Once you have built Heimdal and started the LDAP server, run kadmin
1159 (as usual) to initialise the database. Note that the instructions for
1160 stashing a master key are as per any Heimdal installation.
1164 kadmin> init EXAMPLE.COM
1165 Realm max ticket life [unlimited]:
1166 Realm max renewable ticket life [unlimited]:
1168 Max ticket life [1 day]:
1169 Max renewable life [1 week]:
1170 Principal expiration time [never]:
1171 Password expiration time [never]:
1173 lukeh@@EXAMPLE.COM's Password:
1174 Verifying password - lukeh@@EXAMPLE.COM's Password:
1178 Verify that the principal database has indeed been stored in the
1179 directory with the following command:
1182 kdc# ldapsearch -L -h localhost -D cn=manager \
1183 -w secret -b ou=KerberosPrincipals,dc=example,dc=com \
1184 'objectclass=krb5KDCEntry'
1188 Now consider adding indexes to the database to speed up the access, at
1189 least theses should be added to slapd.conf.
1192 index objectClass eq
1193 index cn eq,sub,pres
1194 index uid eq,sub,pres
1195 index displayName eq,sub,pres
1196 index krb5PrincipalName eq
1201 @subsection smbk5pwd overlay
1203 The smbk5pwd overlay, updates the krb5Key and krb5KeyVersionNumber
1204 appropriately when it receives an LDAP Password change Extended
1207 @url{http://www.openldap.org/devel/cvsweb.cgi/contrib/slapd-modules/smbk5pwd/README?hideattic=1&sortbydate=0}
1209 @subsection Troubleshooting guide
1211 @url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide}
1214 @subsection Using Samba LDAP password database
1217 @c @node Using Samba LDAP password database, Providing Kerberos credentials to servers and programs, Using LDAP to store the database, Setting up a realm
1218 @c @section Using Samba LDAP password database
1220 The Samba domain and the Kerberos realm can have different names since
1221 arcfour's string to key functions principal/realm independent. So now
1222 will be your first and only chance name your Kerberos realm without
1223 needing to deal with old configuration files.
1225 First, you should set up Samba and get that working with LDAP backend.
1227 Now you can proceed as in @xref{Using LDAP to store the database}.
1228 Heimdal will pick up the Samba LDAP entries if they are in the same
1229 search space as the Kerberos entries.
1231 @node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm
1232 @section Providing Kerberos credentials to servers and programs
1234 Some services require Kerberos credentials when they start to make
1235 connections to other services or need to use them when they have started.
1237 The easiest way to get tickets for a service is to store the key in a
1238 keytab. Both ktutil get and kadmin ext can be used to get a
1239 keytab. ktutil get is better in that way it changes the key/password
1240 for the user. This is also the problem with ktutil. If ktutil is used
1241 for the same service principal on several hosts, they keytab will only
1242 be useful on the last host. In that case, run the extract command on
1243 one host and then securely copy the keytab around to all other hosts
1247 host# ktutil -k /etc/krb5-service.keytab \
1248 get -p lha/admin@@EXAMPLE.ORG service-principal@@EXAMPLE.ORG
1249 lha/admin@@EXAMPLE.ORG's Password:
1252 To get a Kerberos credential file for the service, use kinit in the
1253 @kbd{--keytab} mode. This will not ask for a password but instead fetch the
1254 key from the keytab.
1257 service@@host$ kinit --cache=/var/run/service_krb5_cache \
1258 --keytab=/etc/krb5-service.keytab \
1259 service-principal@@EXAMPLE.ORG
1262 Long running services might need credentials longer then the
1263 expiration time of the tickets. kinit can run in a mode that refreshes
1264 the tickets before they expire. This is useful for services that write
1265 into AFS and other distributed file systems using Kerberos. To run the
1266 long running script, just append the program and arguments (if any)
1267 after the principal. kinit will stop refreshing credentials and remove
1268 the credentials when the script-to-start-service exits.
1271 service@@host$ kinit --cache=/var/run/service_krb5_cache \
1272 --keytab=/etc/krb5-service.keytab \
1273 service-principal@@EXAMPLE.ORG \
1274 script-to-start-service argument1 argument2
1278 @node Setting up PK-INIT, Debugging Kerberos problems, Providing Kerberos credentials to servers and programs, Setting up a realm
1279 @section Setting up PK-INIT
1281 PK-INIT leverages an existing PKI (public key infrastructure), using
1282 certificates to get the initial ticket (usually the krbtgt
1283 ticket-granting ticket).
1285 To use PK-INIT you must first have a PKI. If you don't have one, it is
1286 time to create it. You should first read the whole chapter of the
1287 document to see the requirements imposed on the CA software.
1289 A mapping between the PKI certificate and what principals that
1290 certificate is allowed to use must exist. There are several ways to do
1291 this. The administrator can use a configuration file, store the
1292 principal in the SubjectAltName extension of the certificate, or store
1293 the mapping in the principals entry in the kerberos database.
1295 @section Certificates
1297 This section documents the requirements on the KDC and client
1298 certificates and the format used in the id-pkinit-san OtherName
1301 @subsection KDC certificate
1303 The certificate for the KDC has serveral requirements.
1305 First, the certificate should have an Extended Key Usage (EKU)
1306 id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second, there must be a
1307 subjectAltName otherName using OID id-pkinit-san (1.3.6.1.5.2.2) in
1308 the type field and a DER encoded KRB5PrincipalName that matches the
1309 name of the TGS of the target realm. Also, if the certificate has a
1310 nameConstraints extention with a Generalname with dNSName or iPAdress,
1311 it must match the hostname or adress of the KDC.
1313 The client is not required by the standard to check the server
1314 certificate for this information if the client has external
1315 information confirming which certificate the KDC is supposed to be
1316 using. However, adding this information to the KDC certificate removes
1317 the need to specially configure the client to recognize the KDC
1320 Remember that if the client would accept any certificate as the KDC's
1321 certificate, the client could be fooled into trusting something that
1322 isn't a KDC and thus expose the user to giving away information (like
1323 a password or other private information) that it is supposed to keep
1326 @subsection Client certificate
1328 The client certificate may need to have a EKU id-pkekuoid
1329 (1.3.6.1.5.2.3.4) set depending on the certifiate on the KDC.
1331 It possible to store the principal (if allowed by the KDC) in the
1332 certificate and thus delegate responsibility to do the mapping between
1333 certificates and principals to the CA.
1335 This behavior is controlled by KDC configuration option:
1339 pkinit_principal_in_certificate = yes
1342 @subsubsection Using KRB5PrincipalName in id-pkinit-san
1344 The OtherName extention in the GeneralName is used to do the mapping
1345 between certificate and principal. For the KDC certificate, this
1346 stores the krbtgt principal name for that KDC. For the client
1347 certificate, this stores the principal for which that certificate is
1348 allowed to get tickets.
1350 The principal is stored in a SubjectAltName in the certificate using
1351 OtherName. The OID in the type is id-pkinit-san.
1354 id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6)
1355 internet (1) security (5) kerberosv5 (2) 2 @}
1358 The data part of the OtherName is filled with the following DER
1359 encoded ASN.1 structure:
1362 KRB5PrincipalName ::= SEQUENCE @{
1364 principalName [1] PrincipalName
1368 where Realm and PrincipalName is defined by the Kerberos ASN.1
1371 @section Naming certificate using hx509
1373 hx509 is the X.509 software used in Heimdal to handle
1374 certificates. hx509 supports several different syntaxes for specifying
1375 certificate files or formats. Several formats may be used: PEM,
1376 certificates embedded in PKCS#12 files, certificates embedded in
1377 PKCS#11 devices, and raw DER encoded certificates.
1379 Those formats may be specified as follows:
1385 DIR specifies a directory which contains certificates in the DER or
1388 The main feature of DIR is that the directory is read on demand when
1389 iterating over certificates. This allows applications, in some
1390 situations, to avoid having to store all certificates in memory. It's
1391 very useful for tests that iterate over large numbers of certificates.
1396 DIR:/path/to/der/files
1401 FILE: specifies a file that contains a certificate or private key.
1402 The file can be either a PEM (openssl) file or a raw DER encoded
1403 certificate. If it's a PEM file, it can contain several keys and
1404 certificates and the code will try to match the private key and
1405 certificate together. Multiple files may be specified, separated by
1408 It's useful to have one PEM file that contains all the trust anchors.
1413 FILE:certificate.pem,private-key.key,other-cert.pem,....
1418 PKCS11: is used to handle smartcards via PKCS#11 drivers, such as
1419 soft-token, opensc, or muscle. The argument specifies a shared object
1420 that implements the PKCS#11 API. The default is to use all slots on
1426 PKCS11:shared-object.so
1431 PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have
1432 the extension pfx or p12.
1437 PKCS12:/path/to/file.pfx
1442 @section Configure the Kerberos software
1444 First configure the client's trust anchors and what parameters to
1445 verify. See the subsections below for how to do that. Then, you can
1446 use kinit to get yourself tickets. For example:
1449 $ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG
1450 Enter your private key passphrase:
1451 : lha@@nutcracker ; klist
1452 Credentials cache: FILE:/tmp/krb5cc_19100a
1453 Principal: lha@@EXAMPLE.ORG
1455 Issued Expires Principal
1456 Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
1459 Using PKCS#11 it can look like this instead:
1462 $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG
1463 PIN code for SoftToken (slot):
1465 Credentials cache: API:4
1466 Principal: lha@@EXAMPLE.ORG
1468 Issued Expires Principal
1469 Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
1472 TODO: Write about the KDC.
1474 @section Configure the client
1478 pkinit_anchors = FILE:/path/to/trust-anchors.pem
1482 pkinit_require_eku = true
1483 pkinit_require_krbtgt_otherName = true
1485 pkinit_win2k_require_binding = yes
1490 @section Configure the KDC
1495 pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key
1496 pkinit_anchors = FILE:/path/to/trust-anchors.pem
1497 pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx
1498 pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem
1499 pkinit_allow_proxy_certificate = no
1500 pkinit_win2k_require_binding = yes
1501 pkinit_principal_in_certificate = no
1504 @subsection Using pki-mapping file
1506 Note that the file name is space sensitive.
1509 # cat /var/heimdal/pki-mapping
1510 # comments starts with #
1511 lha@@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha
1512 lha@@EXAMPLE.ORG:CN=Love,UID=lha
1515 @subsection Using the Kerberos database
1517 @section Use hxtool to create certificates
1519 @subsection Generate certificates
1521 First, you need to generate a CA certificate. This example creates a
1522 CA certificate that will be valid for 10 years.
1524 You need to change --subject in the command below to something
1525 appropriate for your site.
1528 hxtool issue-certificate \
1531 --generate-key=rsa \
1532 --subject="CN=CA,DC=test,DC=h5l,DC=se" \
1533 --lifetime=10years \
1534 --certificate="FILE:ca.pem"
1537 The KDC needs to have a certificate, so generate a certificate of the
1538 type ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the
1539 name of the krbtgt of the realm.
1541 You need to change --subject and --pk-init-principal in the command
1542 below to something appropriate for your site.
1545 hxtool issue-certificate \
1546 --ca-certificate=FILE:ca.pem \
1547 --generate-key=rsa \
1548 --type="pkinit-kdc" \
1549 --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
1550 --subject="uid=kdc,DC=test,DC=h5l,DC=se" \
1551 --certificate="FILE:kdc.pem"
1554 The users also needs to have certificates. For your first client,
1555 generate a certificate of type ``pkinit-client''. The client doesn't
1556 need to have the PK-INIT SubjectAltName set; you can have the Subject
1557 DN in the ACL file (pki-mapping) instead.
1559 You need to change --subject and --pk-init-principal in the command
1560 below to something appropriate for your site. You can omit
1561 --pk-init-principal if you're going to use the ACL file instead.
1564 hxtool issue-certificate \
1565 --ca-certificate=FILE:ca.pem \
1566 --generate-key=rsa \
1567 --type="pkinit-client" \
1568 --pk-init-principal="lha@@TEST.H5L.SE" \
1569 --subject="uid=lha,DC=test,DC=h5l,DC=se" \
1570 --certificate="FILE:user.pem"
1573 @subsection Validate the certificate
1575 hxtool also contains a tool that will validate certificates according
1576 to rules from the PKIX document. These checks are not complete, but
1577 they provide a good test of whether you got all of the basic bits
1578 right in your certificates.
1581 hxtool validate FILE:user.pem
1584 @section Use OpenSSL to create certificates
1586 This section tries to give the CA owners hints how to create
1587 certificates using OpenSSL (or CA software based on OpenSSL).
1589 @subsection Using OpenSSL to create certificates with krb5PrincipalName
1591 To make OpenSSL create certificates with krb5PrincipalName, use an
1592 @file{openssl.cnf} as described below. To see a complete example of
1593 creating client and KDC certificates, see the test-data generation
1594 script @file{lib/hx509/data/gen-req.sh} in the source-tree. The
1595 certicates it creates are used to test the PK-INIT functionality in
1596 @file{tests/kdc/check-kdc.in}.
1598 To use this example you have to use OpenSSL 0.9.8a or later.
1603 subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name
1606 realm = EXP:0, GeneralString:MY.REALM
1607 principal_name = EXP:1, SEQUENCE:principal_seq
1610 name_type = EXP:0, INTEGER:1
1611 name_string = EXP:1, SEQUENCE:principals
1614 princ1 = GeneralString:userid
1621 openssl x509 -extensions user_certificate
1622 openssl ca -extensions user_certificate
1626 @c --- ms certificate
1629 @c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2
1632 @c [ req_smartcard ]
1633 @c keyUsage = digitalSignature, keyEncipherment
1634 @c extendedKeyUsage = msSmartcardLogin, clientAuth
1635 @c msCertificateTemplateName = ASN1:BMP:SmartcardLogon
1636 @c subjectAltName = otherName:msUPN;UTF8:lukeh@dsg.padl.com
1637 @c #subjectAltName = email:copy
1640 @section Using PK-INIT with Windows
1642 @subsection Client configration
1644 Clients using a Windows KDC with PK-INIT need configuration since
1645 windows uses pre-standard format and this can't be autodetected.
1647 The pkinit_win2k_require_binding option requires the reply for the KDC
1648 to be of the new, secure, type that binds the request to
1649 reply. Before, clients could fake the reply from the KDC. To use this
1650 option you have to apply a fix from Microsoft.
1656 pkinit_win2k_require_binding = no
1660 @subsection Certificates
1662 The client certificates need to have the extended keyusage ``Microsoft
1663 Smartcardlogin'' (openssl has the OID shortname msSmartcardLogin).
1665 See Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling
1666 Smart Card Logon with Third-Party Certification Authorities'' for a
1667 more extensive description of how set setup an external CA so that it
1668 includes all the information required to make a Windows KDC happy.
1670 @subsection Configure Windows 2000 CA
1672 To enable Microsoft Smartcardlogin for certificates in your Windows
1673 2000 CA, you want to look at Microsoft Knowledge Base Article - 313274
1674 ``HOW TO: Configure a Certification Authority to Issue Smart Card
1675 Certificates in Windows''.
1677 @node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm
1678 @section Debugging Kerberos problems
1680 To debug Kerberos client and server problems you can enable debug
1681 traceing by adding the following to @file{/etc/krb5,conf}. Note that the
1682 trace logging is sparse at the moment, but will continue to improve.
1686 libkrb5 = 0-/SYSLOG: