Debian Codegraph @

doc/admin/conf_files/krb5_conf.rst

raw
1 .. _krb5.conf(5):
2
3 krb5.conf
4 =========
5
6 The krb5.conf file contains Kerberos configuration information,
7 including the locations of KDCs and admin servers for the Kerberos
8 realms of interest, defaults for the current realm and for Kerberos
9 applications, and mappings of hostnames onto Kerberos realms.
10 Normally, you should install your krb5.conf file in the directory
11 ``/etc``. You can override the default location by setting the
12 environment variable **KRB5_CONFIG**. Multiple colon-separated
13 filenames may be specified in **KRB5_CONFIG**; all files which are
14 present will be read. Starting in release 1.14, directory names can
15 also be specified in **KRB5_CONFIG**; all files within the directory
16 whose names consist solely of alphanumeric characters, dashes, or
17 underscores will be read.
18
19
20 Structure
21 ---------
22
23 The krb5.conf file is set up in the style of a Windows INI file.
24 Lines beginning with '#' or ';' (possibly after initial whitespace)
25 are ignored as comments. Sections are headed by the section name, in
26 square brackets. Each section may contain zero or more relations, of
27 the form::
28
29 foo = bar
30
31 or::
32
33 fubar = {
34 foo = bar
35 baz = quux
36 }
37
38 The krb5.conf file can include other files using either of the
39 following directives at the beginning of a line::
40
41 include FILENAME
42 includedir DIRNAME
43
44 *FILENAME* or *DIRNAME* should be an absolute path. The named file or
45 directory must exist and be readable. Including a directory includes
46 all files within the directory whose names consist solely of
47 alphanumeric characters, dashes, or underscores. Starting in release
48 1.15, files with names ending in ".conf" are also included, unless the
49 name begins with ".". Included profile files are syntactically
50 independent of their parents, so each included file must begin with a
51 section header. Starting in release 1.17, files are read in
52 alphanumeric order; in previous releases, they may be read in any
53 order.
54
55 Placing a '\*' after the closing bracket of a section name indicates
56 that the section is *final*, meaning that if the same section appears
57 again later, it will be ignored. A subsection can be marked as final
58 by placing a '\*' after either the tag name or the closing brace. A
59 relation can be marked as final by placing a '\*' after the tag name.
60 Prior to release 1.22, only sections and subsections can be marked as
61 final, and the flag only causes values to be ignored if they appear in
62 later files specified in **KRB5_CONFIG**, not if they appear later
63 within the same file or an included file.
64
65 The krb5.conf file can specify that configuration should be obtained
66 from a loadable module, rather than the file itself, using the
67 following directive at the beginning of a line before any section
68 headers::
69
70 module MODULEPATH:RESIDUAL
71
72 *MODULEPATH* may be relative to the library path of the krb5
73 installation, or it may be an absolute path. *RESIDUAL* is provided
74 to the module at initialization time. If krb5.conf uses a module
75 directive, :ref:`kdc.conf(5)` should also use one if it exists.
76
77
78 Sections
79 --------
80
81 The krb5.conf file may contain the following sections:
82
83 =================== =======================================================
84 :ref:`libdefaults` Settings used by the Kerberos V5 library
85 :ref:`realms` Realm-specific contact information and settings
86 :ref:`domain_realm` Maps server hostnames to Kerberos realms
87 :ref:`capaths` Authentication paths for non-hierarchical cross-realm
88 :ref:`appdefaults` Settings used by some Kerberos V5 applications
89 :ref:`plugins` Controls plugin module registration
90 =================== =======================================================
91
92 Additionally, krb5.conf may include any of the relations described in
93 :ref:`kdc.conf(5)`, but it is not a recommended practice.
94
95 .. _libdefaults:
96
97 [libdefaults]
98 ~~~~~~~~~~~~~
99
100 The libdefaults section may contain any of the following relations:
101
102 **allow_des3**
103 Permit the KDC to issue tickets with des3-cbc-sha1 session keys.
104 In future releases, this flag will allow des3-cbc-sha1 to be used
105 at all. The default value for this tag is false. (Added in
106 release 1.21.)
107
108 **allow_rc4**
109 Permit the KDC to issue tickets with arcfour-hmac session keys.
110 In future releases, this flag will allow arcfour-hmac to be used
111 at all. The default value for this tag is false. (Added in
112 release 1.21.)
113
114 **allow_weak_crypto**
115 If this flag is set to false, then weak encryption types (as noted
116 in :ref:`Encryption_types` in :ref:`kdc.conf(5)`) will be filtered
117 out of the lists **default_tgs_enctypes**,
118 **default_tkt_enctypes**, and **permitted_enctypes**. The default
119 value for this tag is false.
120
121 **canonicalize**
122 If this flag is set to true, initial ticket requests to the KDC
123 will request canonicalization of the client principal name, and
124 answers with different client principals than the requested
125 principal will be accepted. The default value is false.
126
127 **ccache_type**
128 This parameter determines the format of credential cache types
129 created by :ref:`kinit(1)` or other programs. The default value
130 is 4, which represents the most current format. Smaller values
131 can be used for compatibility with very old implementations of
132 Kerberos which interact with credential caches on the same host.
133
134 **clockskew**
135 Sets the maximum allowable amount of clockskew in seconds that the
136 library will tolerate before assuming that a Kerberos message is
137 invalid. The default value is 300 seconds, or five minutes.
138
139 The clockskew setting is also used when evaluating ticket start
140 and expiration times. For example, tickets that have reached
141 their expiration time can still be used (and renewed if they are
142 renewable tickets) if they have been expired for a shorter
143 duration than the **clockskew** setting.
144
145 **default_ccache_name**
146 This relation specifies the name of the default credential cache.
147 The default is |ccache|. This relation is subject to parameter
148 expansion (see below). New in release 1.11.
149
150 **default_client_keytab_name**
151 This relation specifies the name of the default keytab for
152 obtaining client credentials. The default is |ckeytab|. This
153 relation is subject to parameter expansion (see below).
154 New in release 1.11.
155
156 **default_keytab_name**
157 This relation specifies the default keytab name to be used by
158 application servers such as sshd. The default is |keytab|. This
159 relation is subject to parameter expansion (see below).
160
161 **default_rcache_name**
162 This relation specifies the name of the default replay cache.
163 The default is ``dfl:``. This relation is subject to parameter
164 expansion (see below). New in release 1.18.
165
166 **default_realm**
167 Identifies the default Kerberos realm for the client. Set its
168 value to your Kerberos realm. If this value is not set, then a
169 realm must be specified with every Kerberos principal when
170 invoking programs such as :ref:`kinit(1)`.
171
172 **default_tgs_enctypes**
173 Identifies the supported list of session key encryption types that
174 the client should request when making a TGS-REQ, in order of
175 preference from highest to lowest. The list may be delimited with
176 commas or whitespace. See :ref:`Encryption_types` in
177 :ref:`kdc.conf(5)` for a list of the accepted values for this tag.
178 Starting in release 1.18, the default value is the value of
179 **permitted_enctypes**. For previous releases or if
180 **permitted_enctypes** is not set, the default value is
181 |defetypes|.
182
183 Do not set this unless required for specific backward
184 compatibility purposes; stale values of this setting can prevent
185 clients from taking advantage of new stronger enctypes when the
186 libraries are upgraded.
187
188 **default_tkt_enctypes**
189 Identifies the supported list of session key encryption types that
190 the client should request when making an AS-REQ, in order of
191 preference from highest to lowest. The format is the same as for
192 default_tgs_enctypes. Starting in release 1.18, the default
193 value is the value of **permitted_enctypes**. For previous
194 releases or if **permitted_enctypes** is not set, the default
195 value is |defetypes|.
196
197 Do not set this unless required for specific backward
198 compatibility purposes; stale values of this setting can prevent
199 clients from taking advantage of new stronger enctypes when the
200 libraries are upgraded.
201
202 **dns_canonicalize_hostname**
203 Indicate whether name lookups will be used to canonicalize
204 hostnames for use in service principal names. Setting this flag
205 to false can improve security by reducing reliance on DNS, but
206 means that short hostnames will not be canonicalized to
207 fully-qualified hostnames. If this option is set to ``fallback`` (new
208 in release 1.18), DNS canonicalization will only be performed the
209 server hostname is not found with the original name when
210 requesting credentials. The default value is true.
211
212 **dns_lookup_kdc**
213 Indicate whether DNS SRV records should be used to locate the KDCs
214 and other servers for a realm, if they are not listed in the
215 krb5.conf information for the realm. (Note that the admin_server
216 entry must be in the krb5.conf realm information in order to
217 contact kadmind, because the DNS implementation for kadmin is
218 incomplete.)
219
220 Enabling this option does open up a type of denial-of-service
221 attack, if someone spoofs the DNS records and redirects you to
222 another server. However, it's no worse than a denial of service,
223 because that fake KDC will be unable to decode anything you send
224 it (besides the initial ticket request, which has no encrypted
225 data), and anything the fake KDC sends will not be trusted without
226 verification using some secret that it won't know.
227
228 **dns_lookup_realm**
229 Indicate whether DNS TXT records should be used to map hostnames
230 to realm names for hostnames not listed in the [domain_realm]
231 section, and to determine the default realm if **default_realm**
232 is not set. The default value is false.
233
234 **dns_uri_lookup**
235 Indicate whether DNS URI records should be used to locate the KDCs
236 and other servers for a realm, if they are not listed in the
237 krb5.conf information for the realm. SRV records are used as a
238 fallback if no URI records were found. The default value is true.
239 New in release 1.15.
240
241 **enforce_ok_as_delegate**
242 If this flag to true, GSSAPI credential delegation will be
243 disabled when the ``ok-as-delegate`` flag is not set in the
244 service ticket. If this flag is false, the ``ok-as-delegate``
245 ticket flag is only enforced when an application specifically
246 requests enforcement. The default value is false.
247
248 **err_fmt**
249 This relation allows for custom error message formatting. If a
250 value is set, error messages will be formatted by substituting a
251 normal error message for %M and an error code for %C in the value.
252
253 **extra_addresses**
254 This allows a computer to use multiple local addresses, in order
255 to allow Kerberos to work in a network that uses NATs while still
256 using address-restricted tickets. The addresses should be in a
257 comma-separated list. This option has no effect if
258 **noaddresses** is true.
259
260 **forwardable**
261 If this flag is true, initial tickets will be forwardable by
262 default, if allowed by the KDC. The default value is false.
263
264 **ignore_acceptor_hostname**
265 When accepting GSSAPI or krb5 security contexts for host-based
266 service principals, ignore any hostname passed by the calling
267 application, and allow clients to authenticate to any service
268 principal in the keytab matching the service name and realm name
269 (if given). This option can improve the administrative
270 flexibility of server applications on multihomed hosts, but could
271 compromise the security of virtual hosting environments. The
272 default value is false. New in release 1.10.
273
274 **k5login_authoritative**
275 If this flag is true, principals must be listed in a local user's
276 k5login file to be granted login access, if a :ref:`.k5login(5)`
277 file exists. If this flag is false, a principal may still be
278 granted login access through other mechanisms even if a k5login
279 file exists but does not list the principal. The default value is
280 true.
281
282 **k5login_directory**
283 If set, the library will look for a local user's k5login file
284 within the named directory, with a filename corresponding to the
285 local username. If not set, the library will look for k5login
286 files in the user's home directory, with the filename .k5login.
287 For security reasons, .k5login files must be owned by
288 the local user or by root.
289
290 **kcm_mach_service**
291 On macOS only, determines the name of the bootstrap service used to
292 contact the KCM daemon for the KCM credential cache type. If the
293 value is ``-``, Mach RPC will not be used to contact the KCM
294 daemon. The default value is ``org.h5l.kcm``.
295
296 **kcm_socket**
297 Determines the path to the Unix domain socket used to access the
298 KCM daemon for the KCM credential cache type. If the value is
299 ``-``, Unix domain sockets will not be used to contact the KCM
300 daemon. The default value is
301 ``/var/run/.heim_org.h5l.kcm-socket``.
302
303 **kdc_default_options**
304 Default KDC options (Xored for multiple values) when requesting
305 initial tickets. By default it is set to 0x00000010
306 (KDC_OPT_RENEWABLE_OK).
307
308 **kdc_timesync**
309 Accepted values for this relation are 1 or 0. If it is nonzero,
310 client machines will compute the difference between their time and
311 the time returned by the KDC in the timestamps in the tickets and
312 use this value to correct for an inaccurate system clock when
313 requesting service tickets or authenticating to services. This
314 corrective factor is only used by the Kerberos library; it is not
315 used to change the system clock. The default value is 1.
316
317 **noaddresses**
318 If this flag is true, requests for initial tickets will not be
319 made with address restrictions set, allowing the tickets to be
320 used across NATs. The default value is true.
321
322 **permitted_enctypes**
323 Identifies the encryption types that servers will permit for
324 session keys and for ticket and authenticator encryption, ordered
325 by preference from highest to lowest. Starting in release 1.18,
326 this tag also acts as the default value for
327 **default_tgs_enctypes** and **default_tkt_enctypes**. The
328 default value for this tag is |defetypes|.
329
330 **plugin_base_dir**
331 If set, determines the base directory where krb5 plugins are
332 located. The default value is the ``krb5/plugins`` subdirectory
333 of the krb5 library directory. This relation is subject to
334 parameter expansion (see below) in release 1.17 and later.
335
336 **preferred_preauth_types**
337 This allows you to set the preferred preauthentication types which
338 the client will attempt before others which may be advertised by a
339 KDC. The default value for this setting is "17, 16, 15, 14",
340 which forces libkrb5 to attempt to use PKINIT if it is supported.
341
342 **proxiable**
343 If this flag is true, initial tickets will be proxiable by
344 default, if allowed by the KDC. The default value is false.
345
346 **qualify_shortname**
347 If this string is set, it determines the domain suffix for
348 single-component hostnames when DNS canonicalization is not used
349 (either because **dns_canonicalize_hostname** is false or because
350 forward canonicalization failed). The default value is the first
351 search domain of the system's DNS configuration. To disable
352 qualification of shortnames, set this relation to the empty string
353 with ``qualify_shortname = ""``. (New in release 1.18.)
354
355 **rdns**
356 If this flag is true, reverse name lookup will be used in addition
357 to forward name lookup to canonicalizing hostnames for use in
358 service principal names. If **dns_canonicalize_hostname** is set
359 to false, this flag has no effect. The default value is true.
360
361 **realm_try_domains**
362 Indicate whether a host's domain components should be used to
363 determine the Kerberos realm of the host. The value of this
364 variable is an integer: -1 means not to search, 0 means to try the
365 host's domain itself, 1 means to also try the domain's immediate
366 parent, and so forth. The library's usual mechanism for locating
367 Kerberos realms is used to determine whether a domain is a valid
368 realm, which may involve consulting DNS if **dns_lookup_kdc** is
369 set. The default is not to search domain components.
370
371 **renew_lifetime**
372 (:ref:`duration` string.) Sets the default renewable lifetime
373 for initial ticket requests. The default value is 0.
374
375 **request_timeout**
376 (:ref:`duration` string.) Sets the maximum total time for KDC and
377 password change requests. This timeout does not affect the
378 intervals between requests, so setting a low timeout may result in
379 fewer requests being attempted and/or some servers not being
380 contacted. A value of 0 indicates no specific maximum, in which
381 case requests will time out if no server responds after several
382 tries. The default value is 0. (New in release 1.22.)
383
384 **spake_preauth_groups**
385 A whitespace or comma-separated list of words which specifies the
386 groups allowed for SPAKE preauthentication. The possible values
387 are:
388
389 ============ ================================
390 edwards25519 Edwards25519 curve (:rfc:`7748`)
391 P-256 NIST P-256 curve (:rfc:`5480`)
392 P-384 NIST P-384 curve (:rfc:`5480`)
393 P-521 NIST P-521 curve (:rfc:`5480`)
394 ============ ================================
395
396 The default value for the client is ``edwards25519``. The default
397 value for the KDC is empty. New in release 1.17.
398
399 **ticket_lifetime**
400 (:ref:`duration` string.) Sets the default lifetime for initial
401 ticket requests. The default value is 1 day.
402
403 **udp_preference_limit**
404 When sending a message to the KDC, the library will try using TCP
405 before UDP if the size of the message is above
406 **udp_preference_limit**. If the message is smaller than
407 **udp_preference_limit**, then UDP will be tried before TCP.
408 Regardless of the size, both protocols will be tried if the first
409 attempt fails.
410
411 **verify_ap_req_nofail**
412 If this flag is true, then an attempt to verify initial
413 credentials will fail if the client machine does not have a
414 keytab. The default value is false.
415
416 **client_aware_channel_bindings**
417 If this flag is true, then all application protocol authentication
418 requests will be flagged to indicate that the application supports
419 channel bindings when operating over a secure channel. The
420 default value is false.
421
422 .. _realms:
423
424 [realms]
425 ~~~~~~~~
426
427 Each tag in the [realms] section of the file is the name of a Kerberos
428 realm. The value of the tag is a subsection with relations that
429 define the properties of that particular realm. For each realm, the
430 following tags may be specified in the realm's subsection:
431
432 **admin_server**
433 Identifies the host where the administration server is running.
434 Typically, this is the primary Kerberos server. This tag must be
435 given a value in order to communicate with the :ref:`kadmind(8)`
436 server for the realm.
437
438 **auth_to_local**
439 This tag allows you to set a general rule for mapping principal
440 names to local user names. It will be used if there is not an
441 explicit mapping for the principal name that is being
442 translated. The possible values are:
443
444 **RULE:**\ *exp*
445 The local name will be formulated from *exp*.
446
447 The format for *exp* is **[**\ *n*\ **:**\ *string*\ **](**\
448 *regexp*\ **)s/**\ *pattern*\ **/**\ *replacement*\ **/g**.
449 The integer *n* indicates how many components the target
450 principal should have. If this matches, then a string will be
451 formed from *string*, substituting the realm of the principal
452 for ``$0`` and the *n*'th component of the principal for
453 ``$n`` (e.g., if the principal was ``johndoe/admin`` then
454 ``[2:$2$1foo]`` would result in the string
455 ``adminjohndoefoo``). If this string matches *regexp*, then
456 the ``s//[g]`` substitution command will be run over the
457 string. The optional **g** will cause the substitution to be
458 global over the *string*, instead of replacing only the first
459 match in the *string*.
460
461 **DEFAULT**
462 The principal name will be used as the local user name. If
463 the principal has more than one component or is not in the
464 default realm, this rule is not applicable and the conversion
465 will fail.
466
467 For example::
468
469 [realms]
470 ATHENA.MIT.EDU = {
471 auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/
472 auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$//
473 auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/
474 auth_to_local = DEFAULT
475 }
476
477 would result in any principal without ``root`` or ``admin`` as the
478 second component to be translated with the default rule. A
479 principal with a second component of ``admin`` will become its
480 first component. ``root`` will be used as the local name for any
481 principal with a second component of ``root``. The exception to
482 these two rules are any principals ``johndoe/*``, which will
483 always get the local name ``guest``.
484
485 **auth_to_local_names**
486 This subsection allows you to set explicit mappings from principal
487 names to local user names. The tag is the mapping name, and the
488 value is the corresponding local user name.
489
490 **default_domain**
491 This tag specifies the domain used to expand hostnames when
492 translating Kerberos 4 service principals to Kerberos 5 principals
493 (for example, when converting ``rcmd.hostname`` to
494 ``host/hostname.domain``).
495
496 **disable_encrypted_timestamp**
497 If this flag is true, the client will not perform encrypted
498 timestamp preauthentication if requested by the KDC. Setting this
499 flag can help to prevent dictionary attacks by active attackers,
500 if the realm's KDCs support SPAKE preauthentication or if initial
501 authentication always uses another mechanism or always uses FAST.
502 This flag persists across client referrals during initial
503 authentication. This flag does not prevent the KDC from offering
504 encrypted timestamp. New in release 1.17.
505
506 **http_anchors**
507 When KDCs and kpasswd servers are accessed through HTTPS proxies, this tag
508 can be used to specify the location of the CA certificate which should be
509 trusted to issue the certificate for a proxy server. If left unspecified,
510 the system-wide default set of CA certificates is used.
511
512 The syntax for values is similar to that of values for the
513 **pkinit_anchors** tag:
514
515 **FILE:** *filename*
516
517 *filename* is assumed to be the name of an OpenSSL-style ca-bundle file.
518
519 **DIR:** *dirname*
520
521 *dirname* is assumed to be an directory which contains CA certificates.
522 All files in the directory will be examined; if they contain certificates
523 (in PEM format), they will be used.
524
525 **ENV:** *envvar*
526
527 *envvar* specifies the name of an environment variable which has been set
528 to a value conforming to one of the previous values. For example,
529 ``ENV:X509_PROXY_CA``, where environment variable ``X509_PROXY_CA`` has
530 been set to ``FILE:/tmp/my_proxy.pem``.
531
532 **kdc**
533 The name or address of a host running a KDC for the realm, or a
534 UNIX domain socket path of a locally running KDC. An optional
535 port number, separated from the hostname by a colon, may be
536 included. If the name or address contains colons (for example, if
537 it is an IPv6 address), enclose it in square brackets to
538 distinguish the colon from a port separator. For your computer to
539 be able to communicate with the KDC for each realm, this tag must
540 be given a value in each realm subsection in the configuration
541 file, or there must be DNS SRV records specifying the KDCs.
542
543 **kpasswd_server**
544 The location of the password change server for the realm, using
545 the same syntax as **kdc**. If there is no such entry, DNS will
546 be queried (unless forbidden by **dns_lookup_kdc**). Finally,
547 port 464 on the **admin_server** host will be tried.
548
549 **master_kdc**
550 The name for **primary_kdc** prior to release 1.19. Its value is
551 used as a fallback if **primary_kdc** is not specified.
552
553 **primary_kdc**
554 Identifies the primary KDC(s). Currently, this tag is used in only
555 one case: If an attempt to get credentials fails because of an
556 invalid password, the client software will attempt to contact the
557 primary KDC, in case the user's password has just been changed, and
558 the updated database has not been propagated to the replica
559 servers yet. New in release 1.19.
560
561 **sitename**
562 Specifies the name of the host's site for the purpose of DNS-based
563 KDC discovery for this realm. New in release 1.22.
564
565 **v4_instance_convert**
566 This subsection allows the administrator to configure exceptions
567 to the **default_domain** mapping rule. It contains V4 instances
568 (the tag name) which should be translated to some specific
569 hostname (the tag value) as the second component in a Kerberos V5
570 principal name.
571
572 **v4_realm**
573 This relation is used by the krb524 library routines when
574 converting a V5 principal name to a V4 principal name. It is used
575 when the V4 realm name and the V5 realm name are not the same, but
576 still share the same principal names and passwords. The tag value
577 is the Kerberos V4 realm name.
578
579
580 .. _domain_realm:
581
582 [domain_realm]
583 ~~~~~~~~~~~~~~
584
585 The [domain_realm] section provides a translation from hostnames to
586 Kerberos realms. Each tag is a domain name, providing the mapping for
587 that domain and all subdomains. If the tag begins with a period
588 (``.``) then it applies only to subdomains. The Kerberos realm may be
589 identified either in the realms_ section or using DNS SRV records.
590 Tag names should be in lower case. For example::
591
592 [domain_realm]
593 crash.mit.edu = TEST.ATHENA.MIT.EDU
594 .dev.mit.edu = TEST.ATHENA.MIT.EDU
595 mit.edu = ATHENA.MIT.EDU
596
597 maps the host with the name ``crash.mit.edu`` into the
598 ``TEST.ATHENA.MIT.EDU`` realm. The second entry maps all hosts under the
599 domain ``dev.mit.edu`` into the ``TEST.ATHENA.MIT.EDU`` realm, but not
600 the host with the name ``dev.mit.edu``. That host is matched
601 by the third entry, which maps the host ``mit.edu`` and all hosts
602 under the domain ``mit.edu`` that do not match a preceding rule
603 into the realm ``ATHENA.MIT.EDU``.
604
605 If no translation entry applies to a hostname used for a service
606 principal for a service ticket request, the library will try to get a
607 referral to the appropriate realm from the client realm's KDC. If
608 that does not succeed, the host's realm is considered to be the
609 hostname's domain portion converted to uppercase, unless the
610 **realm_try_domains** setting in [libdefaults] causes a different
611 parent domain to be used.
612
613
614 .. _capaths:
615
616 [capaths]
617 ~~~~~~~~~
618
619 In order to perform direct (non-hierarchical) cross-realm
620 authentication, configuration is needed to determine the
621 authentication paths between realms.
622
623 A client will use this section to find the authentication path between
624 its realm and the realm of the server. The server will use this
625 section to verify the authentication path used by the client, by
626 checking the transited field of the received ticket.
627
628 There is a tag for each participating client realm, and each tag has
629 subtags for each of the server realms. The value of the subtags is an
630 intermediate realm which may participate in the cross-realm
631 authentication. The subtags may be repeated if there is more then one
632 intermediate realm. A value of "." means that the two realms share
633 keys directly, and no intermediate realms should be allowed to
634 participate.
635
636 Only those entries which will be needed on the client or the server
637 need to be present. A client needs a tag for its local realm with
638 subtags for all the realms of servers it will need to authenticate to.
639 A server needs a tag for each realm of the clients it will serve, with
640 a subtag of the server realm.
641
642 For example, ``ANL.GOV``, ``PNL.GOV``, and ``NERSC.GOV`` all wish to
643 use the ``ES.NET`` realm as an intermediate realm. ANL has a sub
644 realm of ``TEST.ANL.GOV`` which will authenticate with ``NERSC.GOV``
645 but not ``PNL.GOV``. The [capaths] section for ``ANL.GOV`` systems
646 would look like this::
647
648 [capaths]
649 ANL.GOV = {
650 TEST.ANL.GOV = .
651 PNL.GOV = ES.NET
652 NERSC.GOV = ES.NET
653 ES.NET = .
654 }
655 TEST.ANL.GOV = {
656 ANL.GOV = .
657 }
658 PNL.GOV = {
659 ANL.GOV = ES.NET
660 }
661 NERSC.GOV = {
662 ANL.GOV = ES.NET
663 }
664 ES.NET = {
665 ANL.GOV = .
666 }
667
668 The [capaths] section of the configuration file used on ``NERSC.GOV``
669 systems would look like this::
670
671 [capaths]
672 NERSC.GOV = {
673 ANL.GOV = ES.NET
674 TEST.ANL.GOV = ES.NET
675 TEST.ANL.GOV = ANL.GOV
676 PNL.GOV = ES.NET
677 ES.NET = .
678 }
679 ANL.GOV = {
680 NERSC.GOV = ES.NET
681 }
682 PNL.GOV = {
683 NERSC.GOV = ES.NET
684 }
685 ES.NET = {
686 NERSC.GOV = .
687 }
688 TEST.ANL.GOV = {
689 NERSC.GOV = ANL.GOV
690 NERSC.GOV = ES.NET
691 }
692
693 When a subtag is used more than once within a tag, clients will use
694 the order of values to determine the path. The order of values is not
695 important to servers.
696
697
698 .. _appdefaults:
699
700 [appdefaults]
701 ~~~~~~~~~~~~~
702
703 Each tag in the [appdefaults] section names a Kerberos V5 application
704 or an option that is used by some Kerberos V5 application[s]. The
705 value of the tag defines the default behaviors for that application.
706
707 For example::
708
709 [appdefaults]
710 telnet = {
711 ATHENA.MIT.EDU = {
712 option1 = false
713 }
714 }
715 telnet = {
716 option1 = true
717 option2 = true
718 }
719 ATHENA.MIT.EDU = {
720 option2 = false
721 }
722 option2 = true
723
724 The above four ways of specifying the value of an option are shown in
725 order of decreasing precedence. In this example, if telnet is running
726 in the realm EXAMPLE.COM, it should, by default, have option1 and
727 option2 set to true. However, a telnet program in the realm
728 ``ATHENA.MIT.EDU`` should have ``option1`` set to false and
729 ``option2`` set to true. Any other programs in ATHENA.MIT.EDU should
730 have ``option2`` set to false by default. Any programs running in
731 other realms should have ``option2`` set to true.
732
733 The list of specifiable options for each application may be found in
734 that application's man pages. The application defaults specified here
735 are overridden by those specified in the realms_ section.
736
737
738 .. _plugins:
739
740 [plugins]
741 ~~~~~~~~~
742
743 * pwqual_ interface
744 * kadm5_hook_ interface
745 * clpreauth_ and kdcpreauth_ interfaces
746
747 Tags in the [plugins] section can be used to register dynamic plugin
748 modules and to turn modules on and off. Not every krb5 pluggable
749 interface uses the [plugins] section; the ones that do are documented
750 here.
751
752 New in release 1.9.
753
754 Each pluggable interface corresponds to a subsection of [plugins].
755 All subsections support the same tags:
756
757 **disable**
758 This tag may have multiple values. If there are values for this
759 tag, then the named modules will be disabled for the pluggable
760 interface.
761
762 **enable_only**
763 This tag may have multiple values. If there are values for this
764 tag, then only the named modules will be enabled for the pluggable
765 interface.
766
767 **module**
768 This tag may have multiple values. Each value is a string of the
769 form ``modulename:pathname``, which causes the shared object
770 located at *pathname* to be registered as a dynamic module named
771 *modulename* for the pluggable interface. If *pathname* is not an
772 absolute path, it will be treated as relative to the
773 **plugin_base_dir** value from :ref:`libdefaults`.
774
775 For pluggable interfaces where module order matters, modules
776 registered with a **module** tag normally come first, in the order
777 they are registered, followed by built-in modules in the order they
778 are documented below. If **enable_only** tags are used, then the
779 order of those tags overrides the normal module order.
780
781 The following subsections are currently supported within the [plugins]
782 section:
783
784 .. _ccselect:
785
786 ccselect interface
787 ##################
788
789 The ccselect subsection controls modules for credential cache
790 selection within a cache collection. In addition to any registered
791 dynamic modules, the following built-in modules exist (and may be
792 disabled with the disable tag):
793
794 **k5identity**
795 Uses a .k5identity file in the user's home directory to select a
796 client principal
797
798 **realm**
799 Uses the service realm to guess an appropriate cache from the
800 collection
801
802 **hostname**
803 If the service principal is host-based, uses the service hostname
804 to guess an appropriate cache from the collection
805
806 .. _pwqual:
807
808 pwqual interface
809 ################
810
811 The pwqual subsection controls modules for the password quality
812 interface, which is used to reject weak passwords when passwords are
813 changed. The following built-in modules exist for this interface:
814
815 **dict**
816 Checks against the realm dictionary file
817
818 **empty**
819 Rejects empty passwords
820
821 **hesiod**
822 Checks against user information stored in Hesiod (only if Kerberos
823 was built with Hesiod support)
824
825 **princ**
826 Checks against components of the principal name
827
828 .. _kadm5_hook:
829
830 kadm5_hook interface
831 ####################
832
833 The kadm5_hook interface provides plugins with information on
834 principal creation, modification, password changes and deletion. This
835 interface can be used to write a plugin to synchronize MIT Kerberos
836 with another database such as Active Directory. No plugins are built
837 in for this interface.
838
839 .. _kadm5_auth:
840
841 kadm5_auth interface
842 ####################
843
844 The kadm5_auth section (introduced in release 1.16) controls modules
845 for the kadmin authorization interface, which determines whether a
846 client principal is allowed to perform a kadmin operation. The
847 following built-in modules exist for this interface:
848
849 **acl**
850 This module reads the :ref:`kadm5.acl(5)` file, and authorizes
851 operations which are allowed according to the rules in the file.
852
853 **self**
854 This module authorizes self-service operations including password
855 changes, creation of new random keys, fetching the client's
856 principal record or string attributes, and fetching the policy
857 record associated with the client principal.
858
859 .. _clpreauth:
860
861 .. _kdcpreauth:
862
863 clpreauth and kdcpreauth interfaces
864 ###################################
865
866 The clpreauth and kdcpreauth interfaces allow plugin modules to
867 provide client and KDC preauthentication mechanisms. The following
868 built-in modules exist for these interfaces:
869
870 **pkinit**
871 This module implements the PKINIT preauthentication mechanism.
872
873 **encrypted_challenge**
874 This module implements the encrypted challenge FAST factor.
875
876 **encrypted_timestamp**
877 This module implements the encrypted timestamp mechanism.
878
879 .. _hostrealm:
880
881 hostrealm interface
882 ###################
883
884 The hostrealm section (introduced in release 1.12) controls modules
885 for the host-to-realm interface, which affects the local mapping of
886 hostnames to realm names and the choice of default realm. The following
887 built-in modules exist for this interface:
888
889 **profile**
890 This module consults the [domain_realm] section of the profile for
891 authoritative host-to-realm mappings, and the **default_realm**
892 variable for the default realm.
893
894 **dns**
895 This module looks for DNS records for fallback host-to-realm
896 mappings and the default realm. It only operates if the
897 **dns_lookup_realm** variable is set to true.
898
899 **domain**
900 This module applies heuristics for fallback host-to-realm
901 mappings. It implements the **realm_try_domains** variable, and
902 uses the uppercased parent domain of the hostname if that does not
903 produce a result.
904
905 .. _localauth:
906
907 localauth interface
908 ###################
909
910 The localauth section (introduced in release 1.12) controls modules
911 for the local authorization interface, which affects the relationship
912 between Kerberos principals and local system accounts. The following
913 built-in modules exist for this interface:
914
915 **default**
916 This module implements the **DEFAULT** type for **auth_to_local**
917 values.
918
919 **rule**
920 This module implements the **RULE** type for **auth_to_local**
921 values.
922
923 **names**
924 This module looks for an **auth_to_local_names** mapping for the
925 principal name.
926
927 **auth_to_local**
928 This module processes **auth_to_local** values in the default
929 realm's section, and applies the default method if no
930 **auth_to_local** values exist.
931
932 **k5login**
933 This module authorizes a principal to a local account according to
934 the account's :ref:`.k5login(5)` file.
935
936 **an2ln**
937 This module authorizes a principal to a local account if the
938 principal name maps to the local account name.
939
940 .. _certauth:
941
942 certauth interface
943 ##################
944
945 The certauth section (introduced in release 1.16) controls modules for
946 the certificate authorization interface, which determines whether a
947 certificate is allowed to preauthenticate a user via PKINIT. The
948 following built-in modules exist for this interface:
949
950 **pkinit_san**
951 This module authorizes the certificate if it contains a PKINIT
952 Subject Alternative Name for the requested client principal, or a
953 Microsoft UPN SAN matching the principal if **pkinit_allow_upn**
954 is set to true for the realm.
955
956 **pkinit_eku**
957 This module rejects the certificate if it does not contain an
958 Extended Key Usage attribute consistent with the
959 **pkinit_eku_checking** value for the realm.
960
961 **dbmatch**
962 This module authorizes or rejects the certificate according to
963 whether it matches the **pkinit_cert_match** string attribute on
964 the client principal, if that attribute is present.
965
966
967 PKINIT options
968 --------------
969
970 .. note::
971
972 The following are PKINIT-specific options. These values may
973 be specified in [libdefaults] as global defaults, or within
974 a realm-specific subsection of [libdefaults], or may be
975 specified as realm-specific values in the [realms] section.
976 A realm-specific value overrides, not adds to, a generic
977 [libdefaults] specification. The search order is:
978
979 1. realm-specific subsection of [libdefaults]::
980
981 [libdefaults]
982 EXAMPLE.COM = {
983 pkinit_anchors = FILE:/usr/local/example.com.crt
984 }
985
986 2. realm-specific value in the [realms] section::
987
988 [realms]
989 OTHERREALM.ORG = {
990 pkinit_anchors = FILE:/usr/local/otherrealm.org.crt
991 }
992
993 3. generic value in the [libdefaults] section::
994
995 [libdefaults]
996 pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
997
998
999 .. _pkinit_identity:
1000
1001 Specifying PKINIT identity information
1002 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1003
1004 The syntax for specifying Public Key identity, trust, and revocation
1005 information for PKINIT is as follows:
1006
1007 **FILE:**\ *filename*\ [**,**\ *keyfilename*]
1008 This option has context-specific behavior.
1009
1010 In **pkinit_identity** or **pkinit_identities**, *filename*
1011 specifies the name of a PEM-format file containing the user's
1012 certificate. If *keyfilename* is not specified, the user's
1013 private key is expected to be in *filename* as well. Otherwise,
1014 *keyfilename* is the name of the file containing the private key.
1015
1016 In **pkinit_anchors** or **pkinit_pool**, *filename* is assumed to
1017 be the name of an OpenSSL-style ca-bundle file.
1018
1019 **DIR:**\ *dirname*
1020 This option has context-specific behavior.
1021
1022 In **pkinit_identity** or **pkinit_identities**, *dirname*
1023 specifies a directory with files named ``*.crt`` and ``*.key``
1024 where the first part of the file name is the same for matching
1025 pairs of certificate and private key files. When a file with a
1026 name ending with ``.crt`` is found, a matching file ending with
1027 ``.key`` is assumed to contain the private key. If no such file
1028 is found, then the certificate in the ``.crt`` is not used.
1029
1030 In **pkinit_anchors** or **pkinit_pool**, *dirname* is assumed to
1031 be an OpenSSL-style hashed CA directory where each CA cert is
1032 stored in a file named ``hash-of-ca-cert.#``. This infrastructure
1033 is encouraged, but all files in the directory will be examined and
1034 if they contain certificates (in PEM format), they will be used.
1035
1036 In **pkinit_revoke**, *dirname* is assumed to be an OpenSSL-style
1037 hashed CA directory where each revocation list is stored in a file
1038 named ``hash-of-ca-cert.r#``. This infrastructure is encouraged,
1039 but all files in the directory will be examined and if they
1040 contain a revocation list (in PEM format), they will be used.
1041
1042 **PKCS12:**\ *filename*
1043 *filename* is the name of a PKCS #12 format file, containing the
1044 user's certificate and private key.
1045
1046 **PKCS11:**\ [**module_name=**]\ *modname*\ [**:slotid=**\ *slot-id*][**:token=**\ *token-label*][**:certid=**\ *cert-id*][**:certlabel=**\ *cert-label*]
1047 All keyword/values are optional. *modname* specifies the location
1048 of a library implementing PKCS #11. If a value is encountered
1049 with no keyword, it is assumed to be the *modname*. If no
1050 module-name is specified, the default is |pkcs11_modname|.
1051 ``slotid=`` and/or ``token=`` may be specified to force the use of
1052 a particular smard card reader or token if there is more than one
1053 available. ``certid=`` and/or ``certlabel=`` may be specified to
1054 force the selection of a particular certificate on the device.
1055 Specifier values must not contain colon characters, as colons are
1056 always treated as separators. See the **pkinit_cert_match**
1057 configuration option for more ways to select a particular
1058 certificate to use for PKINIT.
1059
1060 **ENV:**\ *envvar*
1061 *envvar* specifies the name of an environment variable which has
1062 been set to a value conforming to one of the previous values. For
1063 example, ``ENV:X509_PROXY``, where environment variable
1064 ``X509_PROXY`` has been set to ``FILE:/tmp/my_proxy.pem``.
1065
1066
1067 PKINIT krb5.conf options
1068 ~~~~~~~~~~~~~~~~~~~~~~~~
1069
1070 **pkinit_anchors**
1071 Specifies the location of trusted anchor (root) certificates which
1072 the client trusts to sign KDC certificates. This option may be
1073 specified multiple times. These values from the config file are
1074 not used if the user specifies X509_anchors on the command line.
1075
1076 **pkinit_cert_match**
1077 Specifies matching rules that the client certificate must match
1078 before it is used to attempt PKINIT authentication. If a user has
1079 multiple certificates available (on a smart card, or via other
1080 media), there must be exactly one certificate chosen before
1081 attempting PKINIT authentication. This option may be specified
1082 multiple times. All the available certificates are checked
1083 against each rule in order until there is a match of exactly one
1084 certificate.
1085
1086 The Subject and Issuer comparison strings are the :rfc:`2253`
1087 string representations from the certificate Subject DN and Issuer
1088 DN values.
1089
1090 The syntax of the matching rules is:
1091
1092 [*relation-operator*\ ]\ *component-rule* ...
1093
1094 where:
1095
1096 *relation-operator*
1097 can be either ``&&``, meaning all component rules must match,
1098 or ``||``, meaning only one component rule must match. The
1099 default is ``&&``.
1100
1101 *component-rule*
1102 can be one of the following. Note that there is no
1103 punctuation or whitespace between component rules.
1104
1105 | **<SUBJECT>**\ *regular-expression*
1106 | **<ISSUER>**\ *regular-expression*
1107 | **<SAN>**\ *regular-expression*
1108 | **<EKU>**\ *extended-key-usage-list*
1109 | **<KU>**\ *key-usage-list*
1110
1111 *extended-key-usage-list* is a comma-separated list of
1112 required Extended Key Usage values. All values in the list
1113 must be present in the certificate. Extended Key Usage values
1114 can be:
1115
1116 * pkinit
1117 * msScLogin
1118 * clientAuth
1119 * emailProtection
1120
1121 *key-usage-list* is a comma-separated list of required Key
1122 Usage values. All values in the list must be present in the
1123 certificate. Key Usage values can be:
1124
1125 * digitalSignature
1126 * keyEncipherment
1127
1128 Examples::
1129
1130 pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
1131 pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
1132 pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
1133
1134 **pkinit_eku_checking**
1135 This option specifies what Extended Key Usage value the KDC
1136 certificate presented to the client must contain. (Note that if
1137 the KDC certificate has the pkinit SubjectAlternativeName encoded
1138 as the Kerberos TGS name, EKU checking is not necessary since the
1139 issuing CA has certified this as a KDC certificate.) The values
1140 recognized in the krb5.conf file are:
1141
1142 **kpKDC**
1143 This is the default value and specifies that the KDC must have
1144 the id-pkinit-KPKdc EKU as defined in :rfc:`4556`.
1145
1146 **kpServerAuth**
1147 If **kpServerAuth** is specified, a KDC certificate with the
1148 id-kp-serverAuth EKU will be accepted. This key usage value
1149 is used in most commercially issued server certificates.
1150
1151 **none**
1152 If **none** is specified, then the KDC certificate will not be
1153 checked to verify it has an acceptable EKU. The use of this
1154 option is not recommended.
1155
1156 **pkinit_dh_min_bits**
1157 Specifies the group of the Diffie-Hellman key the client will
1158 attempt to use. The acceptable values are 1024, 2048, P-256,
1159 4096, P-384, and P-521. The default is 2048. (P-256, P-384, and
1160 P-521 are new in release 1.22.)
1161
1162 **pkinit_identities**
1163 Specifies the location(s) to be used to find the user's X.509
1164 identity information. If this option is specified multiple times,
1165 each value is attempted in order until certificates are found.
1166 Note that these values are not used if the user specifies
1167 **X509_user_identity** on the command line.
1168
1169 **pkinit_kdc_hostname**
1170 The presence of this option indicates that the client is willing
1171 to accept a KDC certificate with a dNSName SAN (Subject
1172 Alternative Name) rather than requiring the id-pkinit-san as
1173 defined in :rfc:`4556`. This option may be specified multiple
1174 times. Its value should contain the acceptable hostname for the
1175 KDC (as contained in its certificate).
1176
1177 **pkinit_pool**
1178 Specifies the location of intermediate certificates which may be
1179 used by the client to complete the trust chain between a KDC
1180 certificate and a trusted anchor. This option may be specified
1181 multiple times.
1182
1183 **pkinit_require_crl_checking**
1184 The default certificate verification process will always check the
1185 available revocation information to see if a certificate has been
1186 revoked. If a match is found for the certificate in a CRL,
1187 verification fails. If the certificate being verified is not
1188 listed in a CRL, or there is no CRL present for its issuing CA,
1189 and **pkinit_require_crl_checking** is false, then verification
1190 succeeds.
1191
1192 However, if **pkinit_require_crl_checking** is true and there is
1193 no CRL information available for the issuing CA, then verification
1194 fails.
1195
1196 **pkinit_require_crl_checking** should be set to true if the
1197 policy is such that up-to-date CRLs must be present for every CA.
1198
1199 **pkinit_revoke**
1200 Specifies the location of Certificate Revocation List (CRL)
1201 information to be used by the client when verifying the validity
1202 of the KDC certificate presented. This option may be specified
1203 multiple times.
1204
1205
1206 .. _parameter_expansion:
1207
1208 Parameter expansion
1209 -------------------
1210
1211 Starting with release 1.11, several variables, such as
1212 **default_keytab_name**, allow parameters to be expanded.
1213 Valid parameters are:
1214
1215 ================= ===================================================
1216 %{TEMP} Temporary directory
1217 %{uid} Unix real UID or Windows SID
1218 %{euid} Unix effective user ID or Windows SID
1219 %{USERID} Same as %{uid}
1220 %{null} Empty string
1221 %{LIBDIR} Installation library directory
1222 %{BINDIR} Installation binary directory
1223 %{SBINDIR} Installation admin binary directory
1224 %{username} (Unix) Username of effective user ID
1225 %{APPDATA} (Windows) Roaming application data for current user
1226 %{COMMON_APPDATA} (Windows) Application data for all users
1227 %{LOCAL_APPDATA} (Windows) Local application data for current user
1228 %{SYSTEM} (Windows) Windows system folder
1229 %{WINDOWS} (Windows) Windows folder
1230 %{USERCONFIG} (Windows) Per-user MIT krb5 config file directory
1231 %{COMMONCONFIG} (Windows) Common MIT krb5 config file directory
1232 ================= ===================================================
1233
1234 Sample krb5.conf file
1235 ---------------------
1236
1237 Here is an example of a generic krb5.conf file::
1238
1239 [libdefaults]
1240 default_realm = ATHENA.MIT.EDU
1241 dns_lookup_kdc = true
1242 dns_lookup_realm = false
1243
1244 [realms]
1245 ATHENA.MIT.EDU = {
1246 kdc = kerberos.mit.edu
1247 kdc = kerberos-1.mit.edu
1248 kdc = kerberos-2.mit.edu
1249 admin_server = kerberos.mit.edu
1250 primary_kdc = kerberos.mit.edu
1251 }
1252 EXAMPLE.COM = {
1253 kdc = kerberos.example.com
1254 kdc = kerberos-1.example.com
1255 admin_server = kerberos.example.com
1256 }
1257
1258 [domain_realm]
1259 mit.edu = ATHENA.MIT.EDU
1260
1261 [capaths]
1262 ATHENA.MIT.EDU = {
1263 EXAMPLE.COM = .
1264 }
1265 EXAMPLE.COM = {
1266 ATHENA.MIT.EDU = .
1267 }
1268
1269 FILES
1270 -----
1271
1272 |krb5conf|
1273
1274
1275 SEE ALSO
1276 --------
1277
1278 syslog(3)