Unfortunately, pre-1.7 krshd fails to support keyed checksums because
[krb5.git] / src / config-files / krb5.conf.M
1 .\" Copyright 1995 by the Massachusetts Institute of Technology.
2 .\"
3 .\" Export of this software from the United States of America may
4 .\"   require a specific license from the United States Government.
5 .\"   It is the responsibility of any person or organization contemplating
6 .\"   export to obtain such a license before exporting.
7 .\" 
8 .\" WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
9 .\" distribute this software and its documentation for any purpose and
10 .\" without fee is hereby granted, provided that the above copyright
11 .\" notice appear in all copies and that both that copyright notice and
12 .\" this permission notice appear in supporting documentation, and that
13 .\" the name of M.I.T. not be used in advertising or publicity pertaining
14 .\" to distribution of the software without specific, written prior
15 .\" permission.  Furthermore if you modify this software you must label
16 .\" your software as modified software and not distribute it in such a
17 .\" fashion that it might be confused with the original M.I.T. software.
18 .\" M.I.T. makes no representations about the suitability of
19 .\" this software for any purpose.  It is provided "as is" without express
20 .\" or implied warranty.
21 .\" "
22 .TH KRB5.CONF 5
23 .SH NAME
24 krb5.conf \- Kerberos configuration file
25 .SH DESCRIPTION
26 .I krb5.conf
27 contains configuration information needed by the Kerberos V5 library.
28 This includes information describing the default Kerberos realm, and the
29 location of the Kerberos key distribution centers for known realms.
30 .PP
31 The 
32 .I krb5.conf
33 file uses an INI-style format.  Sections are delimited by square braces;
34 within each section, there are relations where tags can be assigned to
35 have specific values.  Tags can also contain a subsection, which
36 contains further relations or subsections.  A tag can be assigned to
37 multiple values.  Here is an example of the INI-style format used by
38 .IR krb5.conf :
39
40 .sp
41 .nf
42 .in +1i
43 [section1]
44         tag1 = value_a
45         tag1 = value_b
46         tag2 = value_c
47
48 [section 2]
49         tag3 = {
50                 subtag1 = subtag_value_a
51                 subtag1 = subtag_value_b
52                 subtag2 = subtag_value_c
53         }
54         tag4 = {
55                 subtag1 = subtag_value_d
56                 subtag2 = subtag_value_e
57         }
58 .in -1i
59 .fi
60 .sp
61
62 .PP
63 The following sections are currently used in the 
64 .I krb5.conf
65 file:
66 .IP [libdefaults]
67 Contains various default values used by the Kerberos V5 library.
68
69 .IP [login]
70 Contains default values used by the Kerberos V5 login program,
71 .IR login.krb5 (8).
72
73 .IP [appdefaults]
74 Contains default values that can be used by Kerberos V5 applications.
75
76 .IP [realms]
77 Contains subsections keyed by Kerberos realm names which describe where
78 to find the Kerberos servers for a particular realm, and other
79 realm-specific information.
80
81 .IP [domain_realm]
82 Contains relations which map subdomains and domain names to Kerberos
83 realm names.  This is used by programs to determine what realm a host
84 should be in, given its fully qualified domain name.
85
86 .IP [logging]
87 Contains relations which determine how Kerberos entities are to perform
88 their logging.
89
90 .IP [capaths]
91 Contains the authentication paths used with non-hierarchical
92 cross-realm. Entries in the section are used by the client to determine
93 the intermediate realms which may be used in cross-realm
94 authentication. It is also used by the end-service when checking the
95 transited field for trusted intermediate realms.
96
97 .IP [dbdefaults]
98 Contains default values for database specific parameters.
99
100 .IP [dbmodules]
101 Contains database specific parameters used by the database library.
102 .PP 
103 Each of these sections will be covered in more details in the following
104 sections.
105 .SH LIBDEFAULTS SECTION
106 The following relations are defined in the [libdefaults] section:
107
108 .IP default_keytab_name
109 This relation specifies the default keytab name to be used by
110 application severs such as telnetd and rlogind.  The default is
111 "/etc/krb5.keytab".  This formerly defaulted to "/etc/v5srvtab", but
112 was changed to the current value.
113
114 .IP default_realm
115 This relation identifies the default realm to be used in a client host's
116 Kerberos activity.
117
118 .IP default_tgs_enctypes
119 This relation identifies the supported list of session key encryption
120 types that should be returned by the KDC. The list may be delimited with
121 commas or whitespace.
122
123 .IP default_tkt_enctypes
124 This relation identifies the supported list of session key encryption
125 types that should be requested by the client, in the same format.
126
127 .IP permitted_enctypes
128 This relation identifies the permitted list of session key encryption
129 types.
130
131 .IP clockskew 
132 This relation sets the maximum allowable amount of clockskew in seconds
133 that the library will tolerate before assuming that a Kerberos message
134 is invalid.  The default value is 300 seconds, or five minutes.
135
136 .IP kdc_timesync 
137 If the value of this relation is non-zero (the default), the library
138 will compute the difference between the system clock and the time
139 returned by the KDC and in order to correct for an inaccurate system
140 clock.  This corrective factor is only used by the Kerberos library.
141
142 .IP kdc_req_checksum_type
143 For compatability with DCE security servers which do not support the
144 default CKSUMTYPE_RSA_MD5 used by this version of Kerberos. Use a value
145 of 2 to use the CKSUMTYPE_RSA_MD4 instead. This applies to DCE 1.1 and
146 earlier.  This value is only used for DES keys; other keys use the
147 preferred checksum type for those keys.
148
149 .IP ap_req_checksum_type 
150 If set  this variable  controls what ap-req checksum will be used in  authenticators. This variable should be unset so the appropriate checksum for the encryption key in use will be used.   This can be set if backward compatibility requires a specific checksum type.
151
152 .IP safe_checksum_type 
153 This allows you to set the preferred keyed-checksum type for use in KRB_SAFE
154 messages.  The default value for this type is CKSUMTYPE_RSA_MD5_DES.
155 For compatibility with applications linked against DCE version 1.1 or
156 earlier Kerberos
157 libraries, use a value of 3 to use the CKSUMTYPE_RSA_MD4_DES
158 instead.  This field is ignored when its value is incompatible with
159 the session key type.
160
161 .IP preferred_preauth_types
162 This allows you to set the preferred preauthentication types which the
163 client will attempt before others which may be advertised by a KDC.  The
164 default value for this setting is "17, 16, 15, 14", which forces libkrb5
165 to attempt to use PKINIT if it is supported.
166
167 .IP ccache_type
168 User this parameter on systems which are DCE clients, to specify the
169 type of cache to be created by kinit, or when forwarded tickets are
170 received. DCE and Kerberos can share the cache, but some versions of DCE
171 do not support the default cache as created by this version of
172 Kerberos. Use a value of 1 on DCE 1.0.3a systems, and a value of 2 on
173 DCE 1.1 systems.
174
175 .IP dns_lookup_kdc
176 Indicate whether DNS SRV records shoud be used to locate the KDCs and 
177 other servers for a realm, if they are not listed in the information 
178 for the realm.  The default is to use these records.
179
180 .IP dns_lookup_realm
181 Indicate whether DNS TXT records should be used to determine the Kerberos
182 realm of a host.  The default is not to use these records.
183
184 .IP dns_fallback
185 General flag controlling the use of DNS for Kerberos information.  If both
186 of the preceding options are specified, this option has no effect.
187
188 .IP realm_try_domains
189 Indicate whether a host's domain components should be used to
190 determine the Kerberos realm of the host.  The value of this variable
191 is an integer: -1 means not to search, 0 means to try the host's
192 domain itself, 1 means to also try the domain's immediate parent, and
193 so forth.  The library's usual mechanism for locating Kerberos realms
194 is used to determine whether a domain is a valid realm--which may
195 involve consulting DNS if dns_lookup_kdc is set.  The default is not
196 to search domain components.
197
198 .IP extra_addresses
199 This allows a computer to use multiple local addresses, in order to
200 allow Kerberos to work in a network that uses NATs.  The addresses should
201 be in a comma-separated list.
202
203 .IP udp_preference_limit
204 When sending a message to the KDC, the library will try using TCP
205 before UDP if the size of the message is above "udp_preference_limit".
206 If the message is smaller than "udp_preference_limit", then UDP will be
207 tried before TCP.  Regardless of the size, both protocols will be
208 tried if the first attempt fails.
209
210 .IP verify_ap_req_nofail
211 If this flag is set, then an attempt to get initial credentials will
212 fail if the client machine does not have a keytab.  The default for the
213 flag is false.
214
215 .IP renew_lifetime
216 The value of this tag is the default renewable lifetime for initial
217 tickets.  The default value for the tag is 0.
218
219 .IP noaddresses
220 Setting this flag causes the initial Kerberos ticket to be addressless.
221 The default for the flag is true.
222
223 .IP forwardable
224 If this flag is set, initial tickets by default will be forwardable.
225 The default value for this flag is false.
226
227 .IP proxiable
228 If this flag is set, initial tickets by default will be proxiable.
229 The default value for this flag is false.
230
231 .SH APPDEFAULTS SECTION
232
233 Each tag in the [appdefaults] section names a Kerberos V5 application
234 or an option that is used by some Kerberos V5 application[s].  The
235 four ways that you can set values for options are as follows, in
236 decreasing order of precedence:
237
238 .sp
239 .nf
240 .in +1i
241 #1)     
242         application = {
243                 realm1 = {
244                         option = value
245                 }
246                 realm2 = {
247                         option = value
248                 }
249         }
250 #2)     
251         application = {
252                 option1 = value
253                 option2 = value
254         }
255 #3)     
256         realm = {
257                 option = value
258         }
259 #4)     
260         option = value
261 .in -1in
262 .fi
263 .sp
264
265 .SH LOGIN SECTION
266 The [login] section is used to configure the behavior of the Kerberos V5
267 login program,
268 .IR login.krb5 (8).
269 Refer to the manual entry for
270 .I login.krb5
271 for a description of the relations allowed in this section.
272 .SH REALMS SECTION
273 Each tag in the [realms] section of the file names a Kerberos realm.
274 The value of the tag is a subsection where the relations in that
275 subsection define the properties of that particular realm.  For example:
276
277 .sp
278 .nf
279 .in +1i
280 [realms]
281         ATHENA.MIT.EDU = {
282                 admin_server = KERBEROS.MIT.EDU
283                 default_domain = MIT.EDU
284                 database_module = ldapconf
285                 v4_instance_convert = {
286                         mit = mit.edu
287                         lithium = lithium.lcs.mit.edu
288                 }
289                 v4_realm = LCS.MIT.EDU
290         }
291 .in -1i
292 .fi
293 .sp
294
295 For each realm, the following tags may be specified in the realm's
296 subsection:
297
298 .IP kdc
299 The value of this relation is the name of a host running a KDC for that
300 realm.  An optional port number (preceded by a colon) may be appended to
301 the hostname.  This tag should generally be used only if the realm
302 administrator has not made the information available through DNS.
303
304 .IP admin_server
305 This relation identifies the host where the administration server is
306 running.  Typically this is the Master Kerberos server.
307
308 .IP database_module
309 This relation indicates the name of the configuration section under dbmodules
310 for database specific parameters used by the loadable database library.
311
312 .IP default_domain
313 This relation identifies the default domain for which hosts in this
314 realm are assumed to be in.  This is needed for translating V4 principal
315 names (which do not contain a domain name) to V5 principal names (which
316 do).
317
318 .IP v4_instance_convert
319 This subsection allows the administrator to configure exceptions to the
320 default_domain mapping rule.  It contains V4 instances (the tag name)
321 which should be translated to some specific hostname (the tag value) as
322 the second component in a Kerberos V5 principal name.
323
324 .IP v4_realm
325 This relation is used by the krb524 library routines when converting 
326 a V5 principal name to a V4 principal name. It is used when V4 realm
327 name and the V5 realm are not the same, but still share the same 
328 principal names and passwords. The tag value is the Kerberos V4 realm 
329 name. 
330
331 .IP auth_to_local_names
332 This subsection allows you to set explicit mappings from principal
333 names to local user names.  The tag is the mapping name, and the value
334 is the corresponding local user name.
335
336 .IP auth_to_local
337 This tag allows you to set a general rule for mapping principal names
338 to local user names.  It will be used if there is not an explicit
339 mapping for the principal name that is being translated.  The possible
340 values are:
341
342 .in +.5i
343 DB:<filename>
344 .in +.5i
345 The principal will be looked up in the database <filename>.
346 Support for this is not currently compiled in by default.
347 .in -.5in
348 RULE:<exp>
349 .in +.5i
350 The local name will be formulated from <exp>.
351 .in -.5i
352 DEFAULT
353 .in +.5i
354 The principal name will be used as the local name.  If the
355 principal has more than one component or is not in the default
356 realm, this rule is not applicable and the conversion will fail.
357 .in -1i
358
359 .SH DOMAIN_REALM SECTION
360
361 The [domain_realm] section provides a translation from a hostname to the
362 Kerberos realm name for the services provided by that host.
363 .PP
364 The tag name can be a hostname, or a domain name, where domain names are
365 indicated by a prefix of a period ('.') character.  The value of the
366 relation is the Kerberos realm name for that particular host or domain.
367 Host names and domain names should be in lower case.
368 .PP
369 If no translation entry applies, the host's realm is considered to be
370 the hostname's domain portion converted to upper case.  For example, the
371 following [domain_realm] section:
372
373 .sp
374 .nf
375 .in +1i
376 [domain_realm]
377         .mit.edu = ATHENA.MIT.EDU
378         mit.edu = ATHENA.MIT.EDU 
379         dodo.mit.edu = SMS_TEST.MIT.EDU
380         .ucsc.edu = CATS.UCSC.EDU
381 .in -1i
382 .fi
383 .sp
384 maps dodo.mit.edu into the SMS_TEST.MIT.EDU realm, all other hosts in
385 the MIT.EDU domain to the ATHENA.MIT.EDU realm, and all hosts in the
386 UCSC.EDU domain into the CATS.UCSC.EDU realm.  ucbvax.berkeley.edu would
387 be mapped by the default rules to the BERKELEY.EDU realm, while
388 sage.lcs.mit.edu would be mapped to the LCS.MIT.EDU realm.
389
390 .SH LOGGING SECTION
391
392 The [logging] section indicates how a particular entity is to perform
393 its logging.  The relations specified in this section assign one or more
394 values to the entity name.
395 .PP
396 Currently, the following entities are used:
397 .IP kdc
398 These entries specify how the KDC is to perform its logging.
399 .IP admin_server
400 These entries specify how the administrative server is to perform its logging.
401 .IP default
402 These entries specify how to perform logging in the absence of explicit
403 specifications otherwise.
404 .PP
405 Values are of the following forms:
406 .IP FILE=<filename>
407 .IP FILE:<filename>
408 This value causes the entity's logging messages to go to the specified
409 file.  If the
410 .B =
411 form is used, then the file is overwritten.  Otherwise, the file is
412 appended to.
413 .IP STDERR
414 This value causes the entity's logging messages to go to its standard
415 error stream.
416 .IP CONSOLE
417 This value causes the entity's logging messages to go to the console, if
418 the system supports it.
419 .IP DEVICE=<devicename>
420 This causes the entity's logging messages to go to the specified device.
421 .IP SYSLOG[:<severity>[:<facility>]]
422 This causes the entity's logging messages to go to the system log.
423
424 The
425 .B severity
426 argument specifies the default severity of system log messages.  This
427 may be any of the following severities supported by the
428 .I syslog(3)
429 call minus the LOG_ prefix: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR,
430 LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG.  For example, to
431 specify LOG_CRIT severity, one would use CRIT for
432 .B severity.
433
434 The
435 .B facility
436 argument specifies the facility under which the messages are logged.
437 This may be any of the following facilities supported by the
438 .I syslog(3)
439 call minus the LOG_ prefix: LOG_KERN, LOG_USER, LOG_MAIL, LOG_DAEMON,
440 LOG_AUTH, LOG_LPR, LOG_NEWS, LOG_UUCP, LOG_CRON, and LOG_LOCAL0 through
441 LOG_LOCAL7.
442
443 If no
444 .B severity
445 is specified, the default is ERR, and if no
446 .B facility
447 is specified, the default is AUTH.
448 .PP
449 In the following example, the logging messages from the KDC will go to
450 the console and to the system log under the facility LOG_DAEMON with
451 default severity of LOG_INFO; and the logging messages from the
452 administrative server will be appended to the file /var/adm/kadmin.log
453 and sent to the device /dev/tty04.
454 .sp
455 .nf
456 .in +1i
457 [logging]
458         kdc = CONSOLE
459         kdc = SYSLOG:INFO:DAEMON
460         admin_server = FILE:/var/adm/kadmin.log
461         admin_server = DEVICE=/dev/tty04
462 .in -1i
463 .fi
464 .sp
465
466 .SH CAPATHS SECTION
467
468 Cross-realm authentication is typically organized hierarchically.  This
469 hierarchy is based on the name of the realm, which thus imposes
470 restrictions on the choice of realm names, and on who may participate in
471 a cross-realm authentication. A non hierarchical orgization may be used,
472 but requires a database to construct the authentication paths between
473 the realms. This section defines that database.
474 .PP
475 A client will use this section to find the authentication path between
476 its realm and the realm of the server. The server will use this section
477 to verify the authentication path used be the client, by checking the
478 transited field of the received ticket.
479 .PP
480 There is a tag name for each participating realm, and each tag has
481 subtags for each of the realms. The value of the subtags is an
482 intermediate realm which may participate in the cross-realm
483 authentication. The subtags may be repeated if there is more then one
484 intermediate realm. A value of "." means that the two realms share keys
485 directly, and no intermediate realms should be allowed to participate.
486 .PP
487 There are n**2 possible entries in this table, but only those entries
488 which will be needed on the client or the server need to be present. The
489 client needs a tag for its local realm, with subtags for all the realms
490 of servers it will need to authenticate with.  A server needs a tag for
491 each realm of the clients it will serve.
492 .PP
493 For example, ANL.GOV, PNL.GOV, and NERSC.GOV all wish to use the ES.NET
494 realm as an intermediate realm. ANL has a sub realm of TEST.ANL.GOV
495 which will authenticate with NERSC.GOV but not PNL.GOV.  The [capath]
496 section for ANL.GOV systems would look like this:
497 .sp
498 .nf
499 .in +1i
500 [capaths]
501         ANL.GOV = {
502                 TEST.ANL.GOV = .
503                 PNL.GOV = ES.NET
504                 NERSC.GOV = ES.NET
505                 ES.NET = .
506         }
507         TEST.ANL.GOV = {
508                 ANL.GOV = .
509         }
510         PNL.GOV = {
511                 ANL.GOV = ES.NET
512         }
513         NERSC.GOV = {
514                 ANL.GOV = ES.NET
515         }
516         ES.NET = {
517                 ANL.GOV = .
518         }
519 .in -1i
520 .fi
521 .sp
522 The [capath] section of the configuration file used on NERSC.GOV systems
523 would look like this:
524 .sp
525 .nf
526 .in +1i
527 [capaths]
528         NERSC.GOV = {
529                 ANL.GOV = ES.NET
530                 TEST.ANL.GOV = ES.NET
531                 TEST.ANL.GOV = ANL.GOV
532                 PNL.GOV = ES.NET
533                 ES.NET = .
534         }
535         ANL.GOV = {
536                 NERSC.GOV = ES.NET
537         }
538         PNL.GOV = {
539                 NERSC.GOV = ES.NET
540         }
541         ES.NET = {
542                 NERSC.GOV = .
543         }
544         TEST.ANL.GOV = {
545                 NERSC.GOV = ANL.GOV
546                 NERSC.GOV = ES.NET
547         }
548 .in -1i
549 .fi
550 .sp
551 In the above examples, the ordering is not important, except when the
552 same subtag name is used more then once. The client will use this to
553 determing the path. (It is not important to the server, since the
554 transited field is not sorted.)
555 .PP
556 If this section is not present, or if the client or server cannot find a
557 client/server path, then normal hierarchical orginization is assumed.
558 .PP
559 This feature is not currently supported by DCE. DCE security servers can
560 be used with Kerberized clients and servers, but versions prior to DCE
561 1.1 did not fill in the transited field, and should be used with
562 caution.
563
564 .SH DATABASE DEFAULT SECTION
565
566 The [dbdefaults] section indicates default values for the database specific parameters.
567 It can also specify the configuration section under dbmodules for database
568 specific parameters used by the loadable database library.  
569
570 .PP
571 The following tags are used in this section:
572 .IP database_module
573 This relation indicates the name of the configuration section under dbmodules
574 for database specific parameters used by the loadable database library.
575
576 .IP ldap_kerberos_container_dn 
577 This LDAP specific tag indicates the DN of the container object where the realm
578 objects will be located. This value is used if no object DN is mentioned in the
579 configuration section under dbmodules.
580
581 .IP ldap_kdc_dn
582 This LDAP specific tag indicates the default bind DN for the KDC server.
583 The KDC server does a login to the directory as this object. This value is used if
584 no object DN is mentioned in the configuration section under dbmodules.
585
586 .IP ldap_kadmind_dn
587 This LDAP specific tag indicates the default bind DN for the
588 Administration server. The Administration server does a login to the directory
589 as this object. This value is used if no object DN is mentioned in
590 the configuration section under dbmodules.
591
592 .IP ldap_service_password_file
593 This LDAP specific tag indicates the file containing the stashed passwords for the
594 objects used for starting the Kerberos servers. This value is used if no
595 service password file is mentioned in the configuration section under dbmodules.
596
597 .IP ldap_servers
598 This LDAP specific tag indicates the list of LDAP servers. The list of LDAP servers
599 is whitespace-separated. The LDAP server is specified by a LDAP URI.
600 This value is used if no LDAP servers are mentioned in the configuration
601 section under dbmodules.
602
603 .IP ldap_conns_per_server
604 This LDAP specific tag indicates the number of connections to be maintained per
605 LDAP server. This value is used if the number of connections per LDAP server are not 
606 mentioned in the configuration section under dbmodules. The default value is 5.
607
608 .SH DATABASE MODULE SECTION
609 Each tag in the [dbmodules] section of the file names a configuration section
610 for database specific parameters that can be referred to by a realm. 
611 The value of the tag is a subsection where the relations in that subsection
612 define the database specific parameters.
613
614 .PP
615 For each section, the following tags may be specified in the subsection:
616
617 .IP db_library
618 This tag indicates the name of the loadable database library.
619 The value should be db2 for db2 database and kldap for LDAP database.
620
621 .IP ldap_kerberos_container_dn 
622 This LDAP specific tag indicates the DN of the container object where the realm
623 objects will be located.
624
625 .IP ldap_kdc_dn
626 This LDAP specific tag indicates the bind DN for the KDC server.
627 The KDC does a login to the directory as this object.
628
629 .IP ldap_kadmind_dn
630 This LDAP specific tag indicates the bind DN for the Administration server.
631 The Administration server does a login to the directory
632 as this object.
633
634 .IP ldap_service_password_file
635 This LDAP specific tag indicates the file containing the stashed passwords for the
636 objects used for starting the Kerberos servers.
637
638 .IP ldap_servers
639 This LDAP specific tag indicates the list of LDAP servers. The list of LDAP servers
640 is whitespace-separated. The LDAP server is specified by a LDAP URI.
641
642 .IP ldap_conns_per_server
643 This LDAP specific tag indicates the number of connections to be maintained per
644 LDAP server.
645 .SH FILES 
646 /etc/krb5.conf
647 .SH SEE ALSO
648 syslog(3)