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