1KRB5.CONF(5) MIT Kerberos KRB5.CONF(5)
2
6 krb5.conf - Kerberos configuration file
7 The krb5.conf file contains Kerberos configuration information, includ‐
9 ing the locations of KDCs and admin servers for the Kerberos realms of
10 interest, defaults for the current realm and for Kerberos applications,
11 and mappings of hostnames onto Kerberos realms. Normally, you should
12 install your krb5.conf file in the directory /etc. You can override
13 the default location by setting the environment variable KRB5_CONFIG.
14 Multiple colon-separated filenames may be specified in KRB5_CONFIG; all
15 files which are present will be read. Starting in release 1.14, direc‐
16 tory names can also be specified in KRB5_CONFIG; all files within the
17 directory whose names consist solely of alphanumeric characters,
18 dashes, or underscores will be read.
19
21 The krb5.conf file is set up in the style of a Windows INI file. Sec‐
22 tions are headed by the section name, in square brackets. Each section
23 may contain zero or more relations, of the form:
24 foo = bar
26 or:
28 fubar = {
30 foo = bar
31 baz = quux
32 }
33 Placing a '*' at the end of a line indicates that this is the final
35 value for the tag. This means that neither the remainder of this con‐
36 figuration file nor any other configuration file will be checked for
37 any other values for this tag.
38 For example, if you have the following lines:
40 foo = bar*
42 foo = baz
43 then the second value of foo (baz) would never be read.
45 The krb5.conf file can include other files using either of the follow‐
47 ing directives at the beginning of a line:
48 include FILENAME
50 includedir DIRNAME
51 FILENAME or DIRNAME should be an absolute path. The named file or
53 directory must exist and be readable. Including a directory includes
54 all files within the directory whose names consist solely of alphanu‐
55 meric characters, dashes, or underscores. Starting in release 1.15,
56 files with names ending in ".conf" are also included, unless the name
57 begins with ".". Included profile files are syntactically independent
58 of their parents, so each included file must begin with a section
59 header. Starting in release 1.17, files are read in alphanumeric
60 order; in previous releases, they may be read in any order.
61 The krb5.conf file can specify that configuration should be obtained
63 from a loadable module, rather than the file itself, using the follow‐
64 ing directive at the beginning of a line before any section headers:
65 module MODULEPATH:RESIDUAL
67 MODULEPATH may be relative to the library path of the krb5 installa‐
69 tion, or it may be an absolute path. RESIDUAL is provided to the mod‐
70 ule at initialization time. If krb5.conf uses a module directive,
71 kdc.conf(5) should also use one if it exists.
72
74 The krb5.conf file may contain the following sections:
75 ┌───────────────┬────────────────────────────┐
77 │[libdefaults] │ Settings used by the Ker‐ │
78 │ │ beros V5 library │
79 ├───────────────┼────────────────────────────┤
80 │[realms] │ Realm-specific contact │
81 │ │ information and settings │
82 ├───────────────┼────────────────────────────┤
83 │[domain_realm] │ Maps server hostnames to │
84 │ │ Kerberos realms │
85 ├───────────────┼────────────────────────────┤
86 │[capaths] │ Authentication paths for │
87 │ │ non-hierarchical │
88 │ │ cross-realm │
89 ├───────────────┼────────────────────────────┤
90 │[appdefaults] │ Settings used by some Ker‐ │
91 │ │ beros V5 applications │
92 ├───────────────┼────────────────────────────┤
93 │[plugins] │ Controls plugin module │
94 │ │ registration │
95 └───────────────┴────────────────────────────┘
96 Additionally, krb5.conf may include any of the relations described in
98 kdc.conf(5), but it is not a recommended practice.
99 [libdefaults]
101 The libdefaults section may contain any of the following relations:
102 allow_weak_crypto
104 If this flag is set to false, then weak encryption types (as
105 noted in Encryption_types in kdc.conf(5)) will be filtered out
106 of the lists default_tgs_enctypes, default_tkt_enctypes, and
107 permitted_enctypes. The default value for this tag is false,
108 which may cause authentication failures in existing Kerberos in‐
109 frastructures that do not support strong crypto. Users in
110 affected environments should set this tag to true until their
111 infrastructure adopts stronger ciphers.
112 ap_req_checksum_type
114 An integer which specifies the type of AP-REQ checksum to use in
115 authenticators. This variable should be unset so the appropri‐
116 ate checksum for the encryption key in use will be used. This
117 can be set if backward compatibility requires a specific check‐
118 sum type. See the kdc_req_checksum_type configuration option
119 for the possible values and their meanings.
120 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 ccache_type
128 This parameter determines the format of credential cache types
129 created by kinit(1) or other programs. The default value is 4,
130 which represents the most current format. Smaller values can be
131 used for compatibility with very old implementations of Kerberos
132 which interact with credential caches on the same host.
133 clockskew
135 Sets the maximum allowable amount of clockskew in seconds that
136 the library will tolerate before assuming that a Kerberos mes‐
137 sage is invalid. The default value is 300 seconds, or five min‐
138 utes.
139 The clockskew setting is also used when evaluating ticket start
141 and expiration times. For example, tickets that have reached
142 their expiration time can still be used (and renewed if they are
143 renewable tickets) if they have been expired for a shorter dura‐
144 tion than the clockskew setting.
145 default_ccache_name
147 This relation specifies the name of the default credential
148 cache. The default is FILE:/tmp/krb5cc_%{uid}. This relation
149 is subject to parameter expansion (see below). New in release
150 1.11.
151 default_client_keytab_name
153 This relation specifies the name of the default keytab for
154 obtaining client credentials. The default is FILE:/var/ker‐
155 beros/krb5/user/%{euid}/client.keytab. This relation is subject
156 to parameter expansion (see below). New in release 1.11.
157 default_keytab_name
159 This relation specifies the default keytab name to be used by
160 application servers such as sshd. The default is
161 FILE:/etc/krb5.keytab. This relation is subject to parameter
162 expansion (see below).
163 default_realm
165 Identifies the default Kerberos realm for the client. Set its
166 value to your Kerberos realm. If this value is not set, then a
167 realm must be specified with every Kerberos principal when
168 invoking programs such as kinit(1).
169 default_tgs_enctypes
171 Identifies the supported list of session key encryption types
172 that the client should request when making a TGS-REQ, in order
173 of preference from highest to lowest. The list may be delimited
174 with commas or whitespace. See Encryption_types in kdc.conf(5)
175 for a list of the accepted values for this tag. The default
176 value is aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
177 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camel‐
178 lia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4, but sin‐
179 gle-DES encryption types will be implicitly removed from this
180 list if the value of allow_weak_crypto is false.
181 Do not set this unless required for specific backward compati‐
183 bility purposes; stale values of this setting can prevent
184 clients from taking advantage of new stronger enctypes when the
185 libraries are upgraded.
186 default_tkt_enctypes
188 Identifies the supported list of session key encryption types
189 that the client should request when making an AS-REQ, in order
190 of preference from highest to lowest. The format is the same as
191 for default_tgs_enctypes. The default value for this tag is
192 aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1
193 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac
194 des-cbc-crc des-cbc-md5 des-cbc-md4, but single-DES encryption
195 types will be implicitly removed from this list if the value of
196 allow_weak_crypto is false.
197 Do not set this unless required for specific backward compati‐
199 bility purposes; stale values of this setting can prevent
200 clients from taking advantage of new stronger enctypes when the
201 libraries are upgraded.
202 dns_canonicalize_hostname
204 Indicate whether name lookups will be used to canonicalize host‐
205 names for use in service principal names. Setting this flag to
206 false can improve security by reducing reliance on DNS, but
207 means that short hostnames will not be canonicalized to
208 fully-qualified hostnames. The default value is true.
209 dns_lookup_kdc
211 Indicate whether DNS SRV records should be used to locate the
212 KDCs and other servers for a realm, if they are not listed in
213 the krb5.conf information for the realm. (Note that the
214 admin_server entry must be in the krb5.conf realm information in
215 order to contact kadmind, because the DNS implementation for
216 kadmin is incomplete.)
217 Enabling this option does open up a type of denial-of-service
219 attack, if someone spoofs the DNS records and redirects you to
220 another server. However, it's no worse than a denial of ser‐
221 vice, because that fake KDC will be unable to decode anything
222 you send it (besides the initial ticket request, which has no
223 encrypted data), and anything the fake KDC sends will not be
224 trusted without verification using some secret that it won't
225 know.
226 dns_uri_lookup
228 Indicate whether DNS URI records should be used to locate the
229 KDCs and other servers for a realm, if they are not listed in
230 the krb5.conf information for the realm. SRV records are used
231 as a fallback if no URI records were found. The default value
232 is true. New in release 1.15.
233 err_fmt
235 This relation allows for custom error message formatting. If a
236 value is set, error messages will be formatted by substituting a
237 normal error message for %M and an error code for %C in the
238 value.
239 extra_addresses
241 This allows a computer to use multiple local addresses, in order
242 to allow Kerberos to work in a network that uses NATs while
243 still using address-restricted tickets. The addresses should be
244 in a comma-separated list. This option has no effect if noad‐
245 dresses is true.
246 forwardable
248 If this flag is true, initial tickets will be forwardable by
249 default, if allowed by the KDC. The default value is false.
250 ignore_acceptor_hostname
252 When accepting GSSAPI or krb5 security contexts for host-based
253 service principals, ignore any hostname passed by the calling
254 application, and allow clients to authenticate to any service
255 principal in the keytab matching the service name and realm name
256 (if given). This option can improve the administrative flexi‐
257 bility of server applications on multihomed hosts, but could
258 compromise the security of virtual hosting environments. The
259 default value is false. New in release 1.10.
260 k5login_authoritative
262 If this flag is true, principals must be listed in a local
263 user's k5login file to be granted login access, if a .k5login(5)
264 file exists. If this flag is false, a principal may still be
265 granted login access through other mechanisms even if a k5login
266 file exists but does not list the principal. The default value
267 is true.
268 k5login_directory
270 If set, the library will look for a local user's k5login file
271 within the named directory, with a filename corresponding to the
272 local username. If not set, the library will look for k5login
273 files in the user's home directory, with the filename .k5login.
274 For security reasons, .k5login files must be owned by the local
275 user or by root.
276 kcm_mach_service
278 On OS X only, determines the name of the bootstrap service used
279 to contact the KCM daemon for the KCM credential cache type. If
280 the value is -, Mach RPC will not be used to contact the KCM
281 daemon. The default value is org.h5l.kcm.
282 kcm_socket
284 Determines the path to the Unix domain socket used to access the
285 KCM daemon for the KCM credential cache type. If the value is
286 -, Unix domain sockets will not be used to contact the KCM dae‐
287 mon. The default value is /var/run/.heim_org.h5l.kcm-socket.
288 kdc_default_options
290 Default KDC options (Xored for multiple values) when requesting
291 initial tickets. By default it is set to 0x00000010
292 (KDC_OPT_RENEWABLE_OK).
293 kdc_timesync
295 Accepted values for this relation are 1 or 0. If it is nonzero,
296 client machines will compute the difference between their time
297 and the time returned by the KDC in the timestamps in the tick‐
298 ets and use this value to correct for an inaccurate system clock
299 when requesting service tickets or authenticating to services.
300 This corrective factor is only used by the Kerberos library; it
301 is not used to change the system clock. The default value is 1.
302 kdc_req_checksum_type
304 An integer which specifies the type of checksum to use for the
305 KDC requests, for compatibility with very old KDC implementa‐
306 tions. This value is only used for DES keys; other keys use the
307 preferred checksum type for those keys.
308 The possible values and their meanings are as follows.
310 ┌─────┬────────────────────────────┐
312 │1 │ CRC32 │
313 ├─────┼────────────────────────────┤
314 │2 │ RSA MD4 │
315 ├─────┼────────────────────────────┤
316 │3 │ RSA MD4 DES │
317 ├─────┼────────────────────────────┤
318 │4 │ DES CBC │
319 ├─────┼────────────────────────────┤
320 │7 │ RSA MD5 │
321 ├─────┼────────────────────────────┤
322 │8 │ RSA MD5 DES │
323 ├─────┼────────────────────────────┤
324 │9 │ NIST SHA │
325 ├─────┼────────────────────────────┤
326 │12 │ HMAC SHA1 DES3 │
327 └─────┴────────────────────────────┘
328 │-138 │ Microsoft MD5 HMAC check‐ │
332 │ │ sum type │
333 └─────┴────────────────────────────┘
334 noaddresses
336 If this flag is true, requests for initial tickets will not be
337 made with address restrictions set, allowing the tickets to be
338 used across NATs. The default value is true.
339 permitted_enctypes
341 Identifies all encryption types that are permitted for use in
342 session key encryption. The default value for this tag is
343 aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1
344 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac
345 des-cbc-crc des-cbc-md5 des-cbc-md4, but single-DES encryption
346 types will be implicitly removed from this list if the value of
347 allow_weak_crypto is false.
348 plugin_base_dir
350 If set, determines the base directory where krb5 plugins are
351 located. The default value is the krb5/plugins subdirectory of
352 the krb5 library directory.
353 preferred_preauth_types
355 This allows you to set the preferred preauthentication types
356 which the client will attempt before others which may be adver‐
357 tised by a KDC. The default value for this setting is "17, 16,
358 15, 14", which forces libkrb5 to attempt to use PKINIT if it is
359 supported.
360 proxiable
362 If this flag is true, initial tickets will be proxiable by
363 default, if allowed by the KDC. The default value is false.
364 rdns If this flag is true, reverse name lookup will be used in addi‐
366 tion to forward name lookup to canonicalizing hostnames for use
367 in service principal names. If dns_canonicalize_hostname is set
368 to false, this flag has no effect. The default value is true.
369 realm_try_domains
371 Indicate whether a host's domain components should be used to
372 determine the Kerberos realm of the host. The value of this
373 variable is an integer: -1 means not to search, 0 means to try
374 the host's domain itself, 1 means to also try the domain's imme‐
375 diate parent, and so forth. The library's usual mechanism for
376 locating Kerberos realms is used to determine whether a domain
377 is a valid realm, which may involve consulting DNS if
378 dns_lookup_kdc is set. The default is not to search domain com‐
379 ponents.
380 renew_lifetime
382 (duration string.) Sets the default renewable lifetime for ini‐
383 tial ticket requests. The default value is 0.
384 safe_checksum_type
386 An integer which specifies the type of checksum to use for the
387 KRB-SAFE requests. By default it is set to 8 (RSA MD5 DES).
388 For compatibility with applications linked against DCE version
389 1.1 or earlier Kerberos libraries, use a value of 3 to use the
390 RSA MD4 DES instead. This field is ignored when its value is
391 incompatible with the session key type. See the kdc_req_check‐
392 sum_type configuration option for the possible values and their
393 meanings.
394 ticket_lifetime
396 (duration string.) Sets the default lifetime for initial ticket
397 requests. The default value is 1 day.
398 udp_preference_limit
400 When sending a message to the KDC, the library will try using
401 TCP before UDP if the size of the message is above udp_prefer‐
402 ence_limit. If the message is smaller than udp_prefer‐
403 ence_limit, then UDP will be tried before TCP. Regardless of
404 the size, both protocols will be tried if the first attempt
405 fails.
406 verify_ap_req_nofail
408 If this flag is true, then an attempt to verify initial creden‐
409 tials will fail if the client machine does not have a keytab.
410 The default value is false.
411 [realms]
413 Each tag in the [realms] section of the file is the name of a Kerberos
414 realm. The value of the tag is a subsection with relations that define
415 the properties of that particular realm. For each realm, the following
416 tags may be specified in the realm's subsection:
417 admin_server
419 Identifies the host where the administration server is running.
420 Typically, this is the master Kerberos server. This tag must be
421 given a value in order to communicate with the kadmind(8) server
422 for the realm.
423 auth_to_local
425 This tag allows you to set a general rule for mapping principal
426 names to local user names. It will be used if there is not an
427 explicit mapping for the principal name that is being trans‐
428 lated. The possible values are:
429 RULE:exp
431 The local name will be formulated from exp.
432 The format for exp is [n:string](regexp)s/pat‐
434 tern/replacement/g. The integer n indicates how many
435 components the target principal should have. If this
436 matches, then a string will be formed from string, sub‐
437 stituting the realm of the principal for $0 and the n'th
438 component of the principal for $n (e.g., if the principal
439 was johndoe/admin then [2:$2$1foo] would result in the
440 string adminjohndoefoo). If this string matches regexp,
441 then the s//[g] substitution command will be run over the
442 string. The optional g will cause the substitution to be
443 global over the string, instead of replacing only the
444 first match in the string.
445 DEFAULT
447 The principal name will be used as the local user name.
448 If the principal has more than one component or is not in
449 the default realm, this rule is not applicable and the
450 conversion will fail.
451 For example:
453 [realms]
455 ATHENA.MIT.EDU = {
456 auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/
457 auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$//
458 auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/
459 auto_to_local = DEFAULT
460 }
461 would result in any principal without root or admin as the sec‐
463 ond component to be translated with the default rule. A princi‐
464 pal with a second component of admin will become its first com‐
465 ponent. root will be used as the local name for any principal
466 with a second component of root. The exception to these two
467 rules are any principals johndoe/*, which will always get the
468 local name guest.
469 auth_to_local_names
471 This subsection allows you to set explicit mappings from princi‐
472 pal names to local user names. The tag is the mapping name, and
473 the value is the corresponding local user name.
474 default_domain
476 This tag specifies the domain used to expand hostnames when
477 translating Kerberos 4 service principals to Kerberos 5 princi‐
478 pals (for example, when converting rcmd.hostname to host/host‐
479 name.domain).
480 http_anchors
482 When KDCs and kpasswd servers are accessed through HTTPS prox‐
483 ies, this tag can be used to specify the location of the CA cer‐
484 tificate which should be trusted to issue the certificate for a
485 proxy server. If left unspecified, the system-wide default set
486 of CA certificates is used.
487 The syntax for values is similar to that of values for the
489 pkinit_anchors tag:
490 FILE: filename
492 filename is assumed to be the name of an OpenSSL-style ca-bundle
494 file.
495 DIR: dirname
497 dirname is assumed to be an directory which contains CA certifi‐
499 cates. All files in the directory will be examined; if they
500 contain certificates (in PEM format), they will be used.
501 ENV: envvar
503 envvar specifies the name of an environment variable which has
505 been set to a value conforming to one of the previous values.
506 For example, ENV:X509_PROXY_CA, where environment variable
507 X509_PROXY_CA has been set to FILE:/tmp/my_proxy.pem.
508 kdc The name or address of a host running a KDC for that realm. An
510 optional port number, separated from the hostname by a colon,
511 may be included. If the name or address contains colons (for
512 example, if it is an IPv6 address), enclose it in square brack‐
513 ets to distinguish the colon from a port separator. For your
514 computer to be able to communicate with the KDC for each realm,
515 this tag must be given a value in each realm subsection in the
516 configuration file, or there must be DNS SRV records specifying
517 the KDCs.
518 kpasswd_server
520 Points to the server where all the password changes are per‐
521 formed. If there is no such entry, the port 464 on the
522 admin_server host will be tried.
523 master_kdc
525 Identifies the master KDC(s). Currently, this tag is used in
526 only one case: If an attempt to get credentials fails because of
527 an invalid password, the client software will attempt to contact
528 the master KDC, in case the user's password has just been
529 changed, and the updated database has not been propagated to the
530 slave servers yet.
531 v4_instance_convert
533 This subsection allows the administrator to configure exceptions
534 to the default_domain mapping rule. It contains V4 instances
535 (the tag name) which should be translated to some specific host‐
536 name (the tag value) as the second component in a Kerberos V5
537 principal name.
538 v4_realm
540 This relation is used by the krb524 library routines when con‐
541 verting a V5 principal name to a V4 principal name. It is used
542 when the V4 realm name and the V5 realm name are not the same,
543 but still share the same principal names and passwords. The tag
544 value is the Kerberos V4 realm name.
545 [domain_realm]
547 The [domain_realm] section provides a translation from a domain name or
548 hostname to a Kerberos realm name. The tag name can be a host name or
549 domain name, where domain names are indicated by a prefix of a period
550 (.). The value of the relation is the Kerberos realm name for that
551 particular host or domain. A host name relation implicitly provides
552 the corresponding domain name relation, unless an explicit domain name
553 relation is provided. The Kerberos realm may be identified either in
554 the realms section or using DNS SRV records. Host names and domain
555 names should be in lower case. For example:
556 [domain_realm]
558 crash.mit.edu = TEST.ATHENA.MIT.EDU
559 .dev.mit.edu = TEST.ATHENA.MIT.EDU
560 mit.edu = ATHENA.MIT.EDU
561 maps the host with the name crash.mit.edu into the TEST.ATHENA.MIT.EDU
563 realm. The second entry maps all hosts under the domain dev.mit.edu
564 into the TEST.ATHENA.MIT.EDU realm, but not the host with the name
565 dev.mit.edu. That host is matched by the third entry, which maps the
566 host mit.edu and all hosts under the domain mit.edu that do not match a
567 preceding rule into the realm ATHENA.MIT.EDU.
568 If no translation entry applies to a hostname used for a service prin‐
570 cipal for a service ticket request, the library will try to get a
571 referral to the appropriate realm from the client realm's KDC. If that
572 does not succeed, the host's realm is considered to be the hostname's
573 domain portion converted to uppercase, unless the realm_try_domains
574 setting in [libdefaults] causes a different parent domain to be used.
575 [capaths]
577 In order to perform direct (non-hierarchical) cross-realm authentica‐
578 tion, configuration is needed to determine the authentication paths
579 between realms.
580 A client will use this section to find the authentication path between
582 its realm and the realm of the server. The server will use this sec‐
583 tion to verify the authentication path used by the client, by checking
584 the transited field of the received ticket.
585 There is a tag for each participating client realm, and each tag has
587 subtags for each of the server realms. The value of the subtags is an
588 intermediate realm which may participate in the cross-realm authentica‐
589 tion. The subtags may be repeated if there is more then one intermedi‐
590 ate realm. A value of "." means that the two realms share keys
591 directly, and no intermediate realms should be allowed to participate.
592 Only those entries which will be needed on the client or the server
594 need to be present. A client needs a tag for its local realm with sub‐
595 tags for all the realms of servers it will need to authenticate to. A
596 server needs a tag for each realm of the clients it will serve, with a
597 subtag of the server realm.
598 For example, ANL.GOV, PNL.GOV, and NERSC.GOV all wish to use the ES.NET
600 realm as an intermediate realm. ANL has a sub realm of TEST.ANL.GOV
601 which will authenticate with NERSC.GOV but not PNL.GOV. The [capaths]
602 section for ANL.GOV systems would look like this:
603 [capaths]
605 ANL.GOV = {
606 TEST.ANL.GOV = .
607 PNL.GOV = ES.NET
608 NERSC.GOV = ES.NET
609 ES.NET = .
610 }
611 TEST.ANL.GOV = {
612 ANL.GOV = .
613 }
614 PNL.GOV = {
615 ANL.GOV = ES.NET
616 }
617 NERSC.GOV = {
618 ANL.GOV = ES.NET
619 }
620 ES.NET = {
621 ANL.GOV = .
622 }
623 The [capaths] section of the configuration file used on NERSC.GOV sys‐
625 tems would look like this:
626 [capaths]
628 NERSC.GOV = {
629 ANL.GOV = ES.NET
630 TEST.ANL.GOV = ES.NET
631 TEST.ANL.GOV = ANL.GOV
632 PNL.GOV = ES.NET
633 ES.NET = .
634 }
635 ANL.GOV = {
636 NERSC.GOV = ES.NET
637 }
638 PNL.GOV = {
639 NERSC.GOV = ES.NET
640 }
641 ES.NET = {
642 NERSC.GOV = .
643 }
644 TEST.ANL.GOV = {
645 NERSC.GOV = ANL.GOV
646 NERSC.GOV = ES.NET
647 }
648 When a subtag is used more than once within a tag, clients will use the
650 order of values to determine the path. The order of values is not
651 important to servers.
652 [appdefaults]
654 Each tag in the [appdefaults] section names a Kerberos V5 application
655 or an option that is used by some Kerberos V5 application[s]. The
656 value of the tag defines the default behaviors for that application.
657 For example:
659 [appdefaults]
661 telnet = {
662 ATHENA.MIT.EDU = {
663 option1 = false
664 }
665 }
666 telnet = {
667 option1 = true
668 option2 = true
669 }
670 ATHENA.MIT.EDU = {
671 option2 = false
672 }
673 option2 = true
674 The above four ways of specifying the value of an option are shown in
676 order of decreasing precedence. In this example, if telnet is running
677 in the realm EXAMPLE.COM, it should, by default, have option1 and
678 option2 set to true. However, a telnet program in the realm
679 ATHENA.MIT.EDU should have option1 set to false and option2 set to
680 true. Any other programs in ATHENA.MIT.EDU should have option2 set to
681 false by default. Any programs running in other realms should have
682 option2 set to true.
683 The list of specifiable options for each application may be found in
685 that application's man pages. The application defaults specified here
686 are overridden by those specified in the realms section.
687 [plugins]
689 · pwqual interface
690 · kadm5_hook interface
692 · clpreauth and kdcpreauth interfaces
694 Tags in the [plugins] section can be used to register dynamic plugin
696 modules and to turn modules on and off. Not every krb5 pluggable
697 interface uses the [plugins] section; the ones that do are documented
698 here.
699 New in release 1.9.
701 Each pluggable interface corresponds to a subsection of [plugins]. All
703 subsections support the same tags:
704 disable
706 This tag may have multiple values. If there are values for this
707 tag, then the named modules will be disabled for the pluggable
708 interface.
709 enable_only
711 This tag may have multiple values. If there are values for this
712 tag, then only the named modules will be enabled for the plug‐
713 gable interface.
714 module This tag may have multiple values. Each value is a string of
716 the form modulename:pathname, which causes the shared object
717 located at pathname to be registered as a dynamic module named
718 modulename for the pluggable interface. If pathname is not an
719 absolute path, it will be treated as relative to the plug‐
720 in_base_dir value from [libdefaults].
721 For pluggable interfaces where module order matters, modules registered
723 with a module tag normally come first, in the order they are regis‐
724 tered, followed by built-in modules in the order they are documented
725 below. If enable_only tags are used, then the order of those tags
726 overrides the normal module order.
727 The following subsections are currently supported within the [plugins]
729 section:
730 ccselect interface
732 The ccselect subsection controls modules for credential cache selection
733 within a cache collection. In addition to any registered dynamic mod‐
734 ules, the following built-in modules exist (and may be disabled with
735 the disable tag):
736 k5identity
738 Uses a .k5identity file in the user's home directory to select a
739 client principal
740 realm Uses the service realm to guess an appropriate cache from the
742 collection
743 pwqual interface
745 The pwqual subsection controls modules for the password quality inter‐
746 face, which is used to reject weak passwords when passwords are
747 changed. The following built-in modules exist for this interface:
748 dict Checks against the realm dictionary file
750 empty Rejects empty passwords
752 hesiod Checks against user information stored in Hesiod (only if Ker‐
754 beros was built with Hesiod support)
755 princ Checks against components of the principal name
757 kadm5_hook interface
759 The kadm5_hook interface provides plugins with information on principal
760 creation, modification, password changes and deletion. This interface
761 can be used to write a plugin to synchronize MIT Kerberos with another
762 database such as Active Directory. No plugins are built in for this
763 interface.
764 clpreauth and kdcpreauth interfaces
766 The clpreauth and kdcpreauth interfaces allow plugin modules to provide
767 client and KDC preauthentication mechanisms. The following built-in
768 modules exist for these interfaces:
769 pkinit This module implements the PKINIT preauthentication mechanism.
771 encrypted_challenge
773 This module implements the encrypted challenge FAST factor.
774 encrypted_timestamp
776 This module implements the encrypted timestamp mechanism.
777 hostrealm interface
779 The hostrealm section (introduced in release 1.12) controls modules for
780 the host-to-realm interface, which affects the local mapping of host‐
781 names to realm names and the choice of default realm. The following
782 built-in modules exist for this interface:
783 profile
785 This module consults the [domain_realm] section of the profile
786 for authoritative host-to-realm mappings, and the default_realm
787 variable for the default realm.
788 dns This module looks for DNS records for fallback host-to-realm
790 mappings and the default realm. It only operates if the
791 dns_lookup_realm variable is set to true.
792 domain This module applies heuristics for fallback host-to-realm map‐
794 pings. It implements the realm_try_domains variable, and uses
795 the uppercased parent domain of the hostname if that does not
796 produce a result.
797 localauth interface
799 The localauth section (introduced in release 1.12) controls modules for
800 the local authorization interface, which affects the relationship
801 between Kerberos principals and local system accounts. The following
802 built-in modules exist for this interface:
803 default
805 This module implements the DEFAULT type for auth_to_local val‐
806 ues.
807 rule This module implements the RULE type for auth_to_local values.
809 names This module looks for an auth_to_local_names mapping for the
811 principal name.
812 auth_to_local
814 This module processes auth_to_local values in the default
815 realm's section, and applies the default method if no
816 auth_to_local values exist.
817 k5login
819 This module authorizes a principal to a local account according
820 to the account's .k5login(5) file.
821 an2ln This module authorizes a principal to a local account if the
823 principal name maps to the local account name.
824 certauth interface
826 The certauth section (introduced in release 1.16) controls modules for
827 the certificate authorization interface, which determines whether a
828 certificate is allowed to preauthenticate a user via PKINIT. The fol‐
829 lowing built-in modules exist for this interface:
830 pkinit_san
832 This module authorizes the certificate if it contains a PKINIT
833 Subject Alternative Name for the requested client principal, or
834 a Microsoft UPN SAN matching the principal if pkinit_allow_upn
835 is set to true for the realm.
836 pkinit_eku
838 This module rejects the certificate if it does not contain an
839 Extended Key Usage attribute consistent with the
840 pkinit_eku_checking value for the realm.
841
843 NOTE:
844 The following are PKINIT-specific options. These values may be
845 specified in [libdefaults] as global defaults, or within a
846 realm-specific subsection of [libdefaults], or may be specified as
847 realm-specific values in the [realms] section. A realm-specific
848 value overrides, not adds to, a generic [libdefaults] specification.
849 The search order is:
850 1. realm-specific subsection of [libdefaults]:
852 [libdefaults]
854 EXAMPLE.COM = {
855 pkinit_anchors = FILE:/usr/local/example.com.crt
856 }
857 2. realm-specific value in the [realms] section:
859 [realms]
861 OTHERREALM.ORG = {
862 pkinit_anchors = FILE:/usr/local/otherrealm.org.crt
863 }
864 3. generic value in the [libdefaults] section:
866 [libdefaults]
868 pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
869 Specifying PKINIT identity information
871 The syntax for specifying Public Key identity, trust, and revocation
872 information for PKINIT is as follows:
873 FILE:filename[,keyfilename]
875 This option has context-specific behavior.
876 In pkinit_identity or pkinit_identities, filename specifies the
878 name of a PEM-format file containing the user's certificate. If
879 keyfilename is not specified, the user's private key is expected
880 to be in filename as well. Otherwise, keyfilename is the name
881 of the file containing the private key.
882 In pkinit_anchors or pkinit_pool, filename is assumed to be the
884 name of an OpenSSL-style ca-bundle file.
885 DIR:dirname
887 This option has context-specific behavior.
888 In pkinit_identity or pkinit_identities, dirname specifies a
890 directory with files named *.crt and *.key where the first part
891 of the file name is the same for matching pairs of certificate
892 and private key files. When a file with a name ending with .crt
893 is found, a matching file ending with .key is assumed to contain
894 the private key. If no such file is found, then the certificate
895 in the .crt is not used.
896 In pkinit_anchors or pkinit_pool, dirname is assumed to be an
898 OpenSSL-style hashed CA directory where each CA cert is stored
899 in a file named hash-of-ca-cert.#. This infrastructure is
900 encouraged, but all files in the directory will be examined and
901 if they contain certificates (in PEM format), they will be used.
902 In pkinit_revoke, dirname is assumed to be an OpenSSL-style
904 hashed CA directory where each revocation list is stored in a
905 file named hash-of-ca-cert.r#. This infrastructure is encour‐
906 aged, but all files in the directory will be examined and if
907 they contain a revocation list (in PEM format), they will be
908 used.
909 PKCS12:filename
911 filename is the name of a PKCS #12 format file, containing the
912 user's certificate and private key.
913 PKCS11:[module_name=]modname[:slotid=slot-id][:token=token-label][:cer‐
915 tid=cert-id][:certlabel=cert-label]
916 All keyword/values are optional. modname specifies the location
917 of a library implementing PKCS #11. If a value is encountered
918 with no keyword, it is assumed to be the modname. If no mod‐
919 ule-name is specified, the default is opensc-pkcs11.so. slotid=
920 and/or token= may be specified to force the use of a particular
921 smard card reader or token if there is more than one available.
922 certid= and/or certlabel= may be specified to force the selec‐
923 tion of a particular certificate on the device. See the
924 pkinit_cert_match configuration option for more ways to select a
925 particular certificate to use for PKINIT.
926 ENV:envvar
928 envvar specifies the name of an environment variable which has
929 been set to a value conforming to one of the previous values.
930 For example, ENV:X509_PROXY, where environment variable
931 X509_PROXY has been set to FILE:/tmp/my_proxy.pem.
932 PKINIT krb5.conf options
934 pkinit_anchors
935 Specifies the location of trusted anchor (root) certificates
936 which the client trusts to sign KDC certificates. This option
937 may be specified multiple times. These values from the config
938 file are not used if the user specifies X509_anchors on the com‐
939 mand line.
940 pkinit_cert_match
942 Specifies matching rules that the client certificate must match
943 before it is used to attempt PKINIT authentication. If a user
944 has multiple certificates available (on a smart card, or via
945 other media), there must be exactly one certificate chosen
946 before attempting PKINIT authentication. This option may be
947 specified multiple times. All the available certificates are
948 checked against each rule in order until there is a match of
949 exactly one certificate.
950 The Subject and Issuer comparison strings are the RFC 2253
952 string representations from the certificate Subject DN and
953 Issuer DN values.
954 The syntax of the matching rules is:
956 [relation-operator]component-rule ...
957 where:
959 relation-operator
961 can be either &&, meaning all component rules must match,
962 or ||, meaning only one component rule must match. The
963 default is &&.
964 component-rule
966 can be one of the following. Note that there is no punc‐
967 tuation or whitespace between component rules.
968 <SUBJECT>regular-expression
969 <ISSUER>regular-expression
970 <SAN>regular-expression
971 <EKU>extended-key-usage-list
972 <KU>key-usage-list
973 extended-key-usage-list is a comma-separated list of
976 required Extended Key Usage values. All values in the
977 list must be present in the certificate. Extended Key
978 Usage values can be:
979 · pkinit
981 · msScLogin
983 · clientAuth
985 · emailProtection
987 key-usage-list is a comma-separated list of required Key
989 Usage values. All values in the list must be present in
990 the certificate. Key Usage values can be:
991 · digitalSignature
993 · keyEncipherment
995 Examples:
997 pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
999 pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
1000 pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
1001 pkinit_eku_checking
1003 This option specifies what Extended Key Usage value the KDC cer‐
1004 tificate presented to the client must contain. (Note that if
1005 the KDC certificate has the pkinit SubjectAlternativeName
1006 encoded as the Kerberos TGS name, EKU checking is not necessary
1007 since the issuing CA has certified this as a KDC certificate.)
1008 The values recognized in the krb5.conf file are:
1009 kpKDC This is the default value and specifies that the KDC must
1011 have the id-pkinit-KPKdc EKU as defined in RFC 4556.
1012 kpServerAuth
1014 If kpServerAuth is specified, a KDC certificate with the
1015 id-kp-serverAuth EKU will be accepted. This key usage
1016 value is used in most commercially issued server certifi‐
1017 cates.
1018 none If none is specified, then the KDC certificate will not
1020 be checked to verify it has an acceptable EKU. The use
1021 of this option is not recommended.
1022 pkinit_dh_min_bits
1024 Specifies the size of the Diffie-Hellman key the client will
1025 attempt to use. The acceptable values are 1024, 2048, and 4096.
1026 The default is 2048.
1027 pkinit_identities
1029 Specifies the location(s) to be used to find the user's X.509
1030 identity information. This option may be specified multiple
1031 times. Each value is attempted in order until identity informa‐
1032 tion is found and authentication is attempted. Note that these
1033 values are not used if the user specifies X509_user_identity on
1034 the command line.
1035 pkinit_kdc_hostname
1037 The presense of this option indicates that the client is willing
1038 to accept a KDC certificate with a dNSName SAN (Subject Alterna‐
1039 tive Name) rather than requiring the id-pkinit-san as defined in
1040 RFC 4556. This option may be specified multiple times. Its
1041 value should contain the acceptable hostname for the KDC (as
1042 contained in its certificate).
1043 pkinit_pool
1045 Specifies the location of intermediate certificates which may be
1046 used by the client to complete the trust chain between a KDC
1047 certificate and a trusted anchor. This option may be specified
1048 multiple times.
1049 pkinit_require_crl_checking
1051 The default certificate verification process will always check
1052 the available revocation information to see if a certificate has
1053 been revoked. If a match is found for the certificate in a CRL,
1054 verification fails. If the certificate being verified is not
1055 listed in a CRL, or there is no CRL present for its issuing CA,
1056 and pkinit_require_crl_checking is false, then verification suc‐
1057 ceeds.
1058 However, if pkinit_require_crl_checking is true and there is no
1060 CRL information available for the issuing CA, then verification
1061 fails.
1062 pkinit_require_crl_checking should be set to true if the policy
1064 is such that up-to-date CRLs must be present for every CA.
1065 pkinit_revoke
1067 Specifies the location of Certificate Revocation List (CRL)
1068 information to be used by the client when verifying the validity
1069 of the KDC certificate presented. This option may be specified
1070 multiple times.
1071
1073 Starting with release 1.11, several variables, such as
1074 default_keytab_name, allow parameters to be expanded. Valid parameters
1075 are:
1076 ┌──────────────────┬────────────────────────────┐
1078 │%{TEMP} │ Temporary directory │
1079 ├──────────────────┼────────────────────────────┤
1080 │%{uid} │ Unix real UID or Windows │
1081 │ │ SID │
1082 ├──────────────────┼────────────────────────────┤
1083 │%{euid} │ Unix effective user ID or │
1084 │ │ Windows SID │
1085 ├──────────────────┼────────────────────────────┤
1086 │%{USERID} │ Same as %{uid} │
1087 ├──────────────────┼────────────────────────────┤
1088 │%{null} │ Empty string │
1089 ├──────────────────┼────────────────────────────┤
1090 │%{LIBDIR} │ Installation library │
1091 │ │ directory │
1092 ├──────────────────┼────────────────────────────┤
1093 │%{BINDIR} │ Installation binary direc‐ │
1094 │ │ tory │
1095 ├──────────────────┼────────────────────────────┤
1096 │%{SBINDIR} │ Installation admin binary │
1097 │ │ directory │
1098 ├──────────────────┼────────────────────────────┤
1099 │%{username} │ (Unix) Username of effec‐ │
1100 │ │ tive user ID │
1101 ├──────────────────┼────────────────────────────┤
1102 │%{APPDATA} │ (Windows) Roaming applica‐ │
1103 │ │ tion data for current user │
1104 ├──────────────────┼────────────────────────────┤
1105 │%{COMMON_APPDATA} │ (Windows) Application data │
1106 │ │ for all users │
1107 ├──────────────────┼────────────────────────────┤
1108 │%{LOCAL_APPDATA} │ (Windows) Local applica‐ │
1109 │ │ tion data for current user │
1110 ├──────────────────┼────────────────────────────┤
1111 │%{SYSTEM} │ (Windows) Windows system │
1112 │ │ folder │
1113 ├──────────────────┼────────────────────────────┤
1114 │%{WINDOWS} │ (Windows) Windows folder │
1115 ├──────────────────┼────────────────────────────┤
1116 │%{USERCONFIG} │ (Windows) Per-user MIT │
1117 │ │ krb5 config file directory │
1118 ├──────────────────┼────────────────────────────┤
1119 │%{COMMONCONFIG} │ (Windows) Common MIT krb5 │
1120 │ │ config file directory │
1121 └──────────────────┴────────────────────────────┘
1122
1124 Here is an example of a generic krb5.conf file:
1125 [libdefaults]
1127 default_realm = ATHENA.MIT.EDU
1128 dns_lookup_kdc = true
1129 dns_lookup_realm = false
1130 [realms]
1132 ATHENA.MIT.EDU = {
1133 kdc = kerberos.mit.edu
1134 kdc = kerberos-1.mit.edu
1135 kdc = kerberos-2.mit.edu
1136 admin_server = kerberos.mit.edu
1137 master_kdc = kerberos.mit.edu
1138 }
1139 EXAMPLE.COM = {
1140 kdc = kerberos.example.com
1141 kdc = kerberos-1.example.com
1142 admin_server = kerberos.example.com
1143 }
1144 [domain_realm]
1146 mit.edu = ATHENA.MIT.EDU
1147 [capaths]
1149 ATHENA.MIT.EDU = {
1150 EXAMPLE.COM = .
1151 }
1152 EXAMPLE.COM = {
1153 ATHENA.MIT.EDU = .
1154 }
1155
1157 /etc/krb5.conf
1158
1160 syslog(3)
1161
1163 MIT
1164
1166 1985-2017, MIT
11671.15.1 KRB5.CONF(5)