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. Lines
22 beginning with '#' or ';' (possibly after initial whitespace) are ig‐
23 nored as comments. Sections are headed by the section name, in square
24 brackets. Each section may contain zero or more relations, of the
25 form:
26 foo = bar
28 or:
30 fubar = {
32 foo = bar
33 baz = quux
34 }
35 Placing a '*' after the closing bracket of a section name indicates
37 that the section is final, meaning that if the same section appears
38 within a later file specified in KRB5_CONFIG, it will be ignored. A
39 subsection can be marked as final by placing a '*' after either the tag
40 name or the closing brace.
41 The krb5.conf file can include other files using either of the follow‐
43 ing directives at the beginning of a line:
44 include FILENAME
46 includedir DIRNAME
47 FILENAME or DIRNAME should be an absolute path. The named file or di‐
49 rectory must exist and be readable. Including a directory includes all
50 files within the directory whose names consist solely of alphanumeric
51 characters, dashes, or underscores. Starting in release 1.15, files
52 with names ending in ".conf" are also included, unless the name begins
53 with ".". Included profile files are syntactically independent of
54 their parents, so each included file must begin with a section header.
55 Starting in release 1.17, files are read in alphanumeric order; in pre‐
56 vious releases, they may be read in any order.
57 The krb5.conf file can specify that configuration should be obtained
59 from a loadable module, rather than the file itself, using the follow‐
60 ing directive at the beginning of a line before any section headers:
61 module MODULEPATH:RESIDUAL
63 MODULEPATH may be relative to the library path of the krb5 installa‐
65 tion, or it may be an absolute path. RESIDUAL is provided to the mod‐
66 ule at initialization time. If krb5.conf uses a module directive,
67 kdc.conf should also use one if it exists.
68
70 The krb5.conf file may contain the following sections:
71 ┌───────────────┬────────────────────────────┐
73 │[libdefaults] │ Settings used by the Ker‐ │
74 │ │ beros V5 library │
75 ├───────────────┼────────────────────────────┤
76 │[realms] │ Realm-specific contact in‐ │
77 │ │ formation and settings │
78 ├───────────────┼────────────────────────────┤
79 │[domain_realm] │ Maps server hostnames to │
80 │ │ Kerberos realms │
81 ├───────────────┼────────────────────────────┤
82 │[capaths] │ Authentication paths for │
83 │ │ non-hierarchical │
84 │ │ cross-realm │
85 ├───────────────┼────────────────────────────┤
86 │[appdefaults] │ Settings used by some Ker‐ │
87 │ │ beros V5 applications │
88 ├───────────────┼────────────────────────────┤
89 │[plugins] │ Controls plugin module │
90 │ │ registration │
91 └───────────────┴────────────────────────────┘
92 Additionally, krb5.conf may include any of the relations described in
94 kdc.conf, but it is not a recommended practice.
95 [libdefaults]
97 The libdefaults section may contain any of the following relations:
98 allow_des3
100 Permit the KDC to issue tickets with des3-cbc-sha1 session keys.
101 In future releases, this flag will allow des3-cbc-sha1 to be
102 used at all. The default value for this tag is false. (Added
103 in release 1.21.)
104 allow_rc4
106 Permit the KDC to issue tickets with arcfour-hmac session keys.
107 In future releases, this flag will allow arcfour-hmac to be used
108 at all. The default value for this tag is false. (Added in re‐
109 lease 1.21.)
110 allow_weak_crypto
112 If this flag is set to false, then weak encryption types (as
113 noted in Encryption types in kdc.conf) will be filtered out of
114 the lists default_tgs_enctypes, default_tkt_enctypes, and per‐
115 mitted_enctypes. The default value for this tag is false.
116 canonicalize
118 If this flag is set to true, initial ticket requests to the KDC
119 will request canonicalization of the client principal name, and
120 answers with different client principals than the requested
121 principal will be accepted. The default value is false.
122 ccache_type
124 This parameter determines the format of credential cache types
125 created by kinit or other programs. The default value is 4,
126 which represents the most current format. Smaller values can be
127 used for compatibility with very old implementations of Kerberos
128 which interact with credential caches on the same host.
129 clockskew
131 Sets the maximum allowable amount of clockskew in seconds that
132 the library will tolerate before assuming that a Kerberos mes‐
133 sage is invalid. The default value is 300 seconds, or five min‐
134 utes.
135 The clockskew setting is also used when evaluating ticket start
137 and expiration times. For example, tickets that have reached
138 their expiration time can still be used (and renewed if they are
139 renewable tickets) if they have been expired for a shorter dura‐
140 tion than the clockskew setting.
141 default_ccache_name
143 This relation specifies the name of the default credential
144 cache. The default is FILE:/tmp/krb5cc_%{uid}. This relation
145 is subject to parameter expansion (see below). New in release
146 1.11.
147 default_client_keytab_name
149 This relation specifies the name of the default keytab for ob‐
150 taining client credentials. The default is FILE:/var/ker‐
151 beros/krb5/user/%{euid}/client.keytab. This relation is subject
152 to parameter expansion (see below). New in release 1.11.
153 default_keytab_name
155 This relation specifies the default keytab name to be used by
156 application servers such as sshd. The default is
157 FILE:/etc/krb5.keytab. This relation is subject to parameter
158 expansion (see below).
159 default_rcache_name
161 This relation specifies the name of the default replay cache.
162 The default is dfl:. This relation is subject to parameter ex‐
163 pansion (see below). New in release 1.18.
164 default_realm
166 Identifies the default Kerberos realm for the client. Set its
167 value to your Kerberos realm. If this value is not set, then a
168 realm must be specified with every Kerberos principal when in‐
169 voking programs such as kinit.
170 default_tgs_enctypes
172 Identifies the supported list of session key encryption types
173 that the client should request when making a TGS-REQ, in order
174 of preference from highest to lowest. The list may be delimited
175 with commas or whitespace. See Encryption types in kdc.conf for
176 a list of the accepted values for this tag. Starting in release
177 1.18, the default value is the value of permitted_enctypes. For
178 previous releases or if permitted_enctypes is not set, the de‐
179 fault value is aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
180 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 arc‐
181 four-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac.
182 Do not set this unless required for specific backward compati‐
184 bility purposes; stale values of this setting can prevent
185 clients from taking advantage of new stronger enctypes when the
186 libraries are upgraded.
187 default_tkt_enctypes
189 Identifies the supported list of session key encryption types
190 that the client should request when making an AS-REQ, in order
191 of preference from highest to lowest. The format is the same as
192 for default_tgs_enctypes. Starting in release 1.18, the default
193 value is the value of permitted_enctypes. For previous releases
194 or if permitted_enctypes is not set, the default value is
195 aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
196 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 arc‐
197 four-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac.
198 Do not set this unless required for specific backward compati‐
200 bility purposes; stale values of this setting can prevent
201 clients from taking advantage of new stronger enctypes when the
202 libraries are upgraded.
203 dns_canonicalize_hostname
205 Indicate whether name lookups will be used to canonicalize host‐
206 names for use in service principal names. Setting this flag to
207 false can improve security by reducing reliance on DNS, but
208 means that short hostnames will not be canonicalized to
209 fully-qualified hostnames. If this option is set to fallback
210 (new in release 1.18), DNS canonicalization will only be per‐
211 formed the server hostname is not found with the original name
212 when requesting credentials. The default value is true.
213 dns_lookup_kdc
215 Indicate whether DNS SRV records should be used to locate the
216 KDCs and other servers for a realm, if they are not listed in
217 the krb5.conf information for the realm. (Note that the ad‐
218 min_server entry must be in the krb5.conf realm information in
219 order to contact kadmind, because the DNS implementation for
220 kadmin is incomplete.)
221 Enabling this option does open up a type of denial-of-service
223 attack, if someone spoofs the DNS records and redirects you to
224 another server. However, it's no worse than a denial of ser‐
225 vice, because that fake KDC will be unable to decode anything
226 you send it (besides the initial ticket request, which has no
227 encrypted data), and anything the fake KDC sends will not be
228 trusted without verification using some secret that it won't
229 know.
230 dns_uri_lookup
232 Indicate whether DNS URI records should be used to locate the
233 KDCs and other servers for a realm, if they are not listed in
234 the krb5.conf information for the realm. SRV records are used
235 as a fallback if no URI records were found. The default value
236 is true. New in release 1.15.
237 enforce_ok_as_delegate
239 If this flag to true, GSSAPI credential delegation will be dis‐
240 abled when the ok-as-delegate flag is not set in the service
241 ticket. If this flag is false, the ok-as-delegate ticket flag
242 is only enforced when an application specifically requests en‐
243 forcement. The default value is false.
244 err_fmt
246 This relation allows for custom error message formatting. If a
247 value is set, error messages will be formatted by substituting a
248 normal error message for %M and an error code for %C in the
249 value.
250 extra_addresses
252 This allows a computer to use multiple local addresses, in order
253 to allow Kerberos to work in a network that uses NATs while
254 still using address-restricted tickets. The addresses should be
255 in a comma-separated list. This option has no effect if noad‐
256 dresses is true.
257 forwardable
259 If this flag is true, initial tickets will be forwardable by de‐
260 fault, if allowed by the KDC. The default value is false.
261 ignore_acceptor_hostname
263 When accepting GSSAPI or krb5 security contexts for host-based
264 service principals, ignore any hostname passed by the calling
265 application, and allow clients to authenticate to any service
266 principal in the keytab matching the service name and realm name
267 (if given). This option can improve the administrative flexi‐
268 bility of server applications on multihomed hosts, but could
269 compromise the security of virtual hosting environments. The
270 default value is false. New in release 1.10.
271 k5login_authoritative
273 If this flag is true, principals must be listed in a local
274 user's k5login file to be granted login access, if a .k5login
275 file exists. If this flag is false, a principal may still be
276 granted login access through other mechanisms even if a k5login
277 file exists but does not list the principal. The default value
278 is true.
279 k5login_directory
281 If set, the library will look for a local user's k5login file
282 within the named directory, with a filename corresponding to the
283 local username. If not set, the library will look for k5login
284 files in the user's home directory, with the filename .k5login.
285 For security reasons, .k5login files must be owned by the local
286 user or by root.
287 kcm_mach_service
289 On macOS only, determines the name of the bootstrap service used
290 to contact the KCM daemon for the KCM credential cache type. If
291 the value is -, Mach RPC will not be used to contact the KCM
292 daemon. The default value is org.h5l.kcm.
293 kcm_socket
295 Determines the path to the Unix domain socket used to access the
296 KCM daemon for the KCM credential cache type. If the value is
297 -, Unix domain sockets will not be used to contact the KCM dae‐
298 mon. The default value is /var/run/.heim_org.h5l.kcm-socket.
299 kdc_default_options
301 Default KDC options (Xored for multiple values) when requesting
302 initial tickets. By default it is set to 0x00000010
303 (KDC_OPT_RENEWABLE_OK).
304 kdc_timesync
306 Accepted values for this relation are 1 or 0. If it is nonzero,
307 client machines will compute the difference between their time
308 and the time returned by the KDC in the timestamps in the tick‐
309 ets and use this value to correct for an inaccurate system clock
310 when requesting service tickets or authenticating to services.
311 This corrective factor is only used by the Kerberos library; it
312 is not used to change the system clock. The default value is 1.
313 noaddresses
315 If this flag is true, requests for initial tickets will not be
316 made with address restrictions set, allowing the tickets to be
317 used across NATs. The default value is true.
318 permitted_enctypes
320 Identifies the encryption types that servers will permit for
321 session keys and for ticket and authenticator encryption, or‐
322 dered by preference from highest to lowest. Starting in release
323 1.18, this tag also acts as the default value for de‐
324 fault_tgs_enctypes and default_tkt_enctypes. The default value
325 for this tag is aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
326 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 arc‐
327 four-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac.
328 plugin_base_dir
330 If set, determines the base directory where krb5 plugins are lo‐
331 cated. The default value is the krb5/plugins subdirectory of
332 the krb5 library directory. This relation is subject to parame‐
333 ter expansion (see below) in release 1.17 and later.
334 preferred_preauth_types
336 This allows you to set the preferred preauthentication types
337 which the client will attempt before others which may be adver‐
338 tised by a KDC. The default value for this setting is "17, 16,
339 15, 14", which forces libkrb5 to attempt to use PKINIT if it is
340 supported.
341 proxiable
343 If this flag is true, initial tickets will be proxiable by de‐
344 fault, if allowed by the KDC. The default value is false.
345 qualify_shortname
347 If this string is set, it determines the domain suffix for sin‐
348 gle-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
351 first search domain of the system's DNS configuration. To dis‐
352 able qualification of shortnames, set this relation to the empty
353 string with qualify_shortname = "". (New in release 1.18.)
354 radius_md5_fips_override
356 Downstream-only option to enable use of MD5 in RADIUS communica‐
357 tion (libkrad). This allows for local (or protected tunnel)
358 communication with a RADIUS server that doesn't use krad (e.g.,
359 freeradius) while in FIPS mode.
360 rdns If this flag is true, reverse name lookup will be used in addi‐
362 tion to forward name lookup to canonicalizing hostnames for use
363 in service principal names. If dns_canonicalize_hostname is set
364 to false, this flag has no effect. The default value is true.
365 realm_try_domains
367 Indicate whether a host's domain components should be used to
368 determine the Kerberos realm of the host. The value of this
369 variable is an integer: -1 means not to search, 0 means to try
370 the host's domain itself, 1 means to also try the domain's imme‐
371 diate parent, and so forth. The library's usual mechanism for
372 locating Kerberos realms is used to determine whether a domain
373 is a valid realm, which may involve consulting DNS if
374 dns_lookup_kdc is set. The default is not to search domain com‐
375 ponents.
376 renew_lifetime
378 (Time duration string.) Sets the default renewable lifetime for
379 initial ticket requests. The default value is 0.
380 spake_preauth_groups
382 A whitespace or comma-separated list of words which specifies
383 the groups allowed for SPAKE preauthentication. The possible
384 values are:
385 ┌─────────────┬────────────────────────────┐
387 │edwards25519 │ Edwards25519 curve (RFC │
388 │ │ 7748) │
389 ├─────────────┼────────────────────────────┤
390 │P-256 │ NIST P-256 curve (RFC │
391 │ │ 5480) │
392 ├─────────────┼────────────────────────────┤
393 │P-384 │ NIST P-384 curve (RFC │
394 │ │ 5480) │
395 └─────────────┴────────────────────────────┘
396 │P-521 │ NIST P-521 curve (RFC │
400 │ │ 5480) │
401 └─────────────┴────────────────────────────┘
402 The default value for the client is edwards25519. The default
404 value for the KDC is empty. New in release 1.17.
405 ticket_lifetime
407 (Time duration string.) Sets the default lifetime for initial
408 ticket requests. The default value is 1 day.
409 udp_preference_limit
411 When sending a message to the KDC, the library will try using
412 TCP before UDP if the size of the message is above udp_prefer‐
413 ence_limit. If the message is smaller than udp_prefer‐
414 ence_limit, then UDP will be tried before TCP. Regardless of
415 the size, both protocols will be tried if the first attempt
416 fails.
417 verify_ap_req_nofail
419 If this flag is true, then an attempt to verify initial creden‐
420 tials will fail if the client machine does not have a keytab.
421 The default value is false.
422 client_aware_channel_bindings
424 If this flag is true, then all application protocol authentica‐
425 tion requests will be flagged to indicate that the application
426 supports channel bindings when operating over a secure channel.
427 The default value is false.
428 [realms]
430 Each tag in the [realms] section of the file is the name of a Kerberos
431 realm. The value of the tag is a subsection with relations that define
432 the properties of that particular realm. For each realm, the following
433 tags may be specified in the realm's subsection:
434 admin_server
436 Identifies the host where the administration server is running.
437 Typically, this is the primary Kerberos server. This tag must
438 be given a value in order to communicate with the kadmind server
439 for the realm.
440 auth_to_local
442 This tag allows you to set a general rule for mapping principal
443 names to local user names. It will be used if there is not an
444 explicit mapping for the principal name that is being trans‐
445 lated. The possible values are:
446 RULE:exp
448 The local name will be formulated from exp.
449 The format for exp is [n:string](regexp)s/pattern/re‐
451 placement/g. The integer n indicates how many components
452 the target principal should have. If this matches, then
453 a string will be formed from string, substituting the
454 realm of the principal for $0 and the n'th component of
455 the principal for $n (e.g., if the principal was john‐
456 doe/admin then [2:$2$1foo] would result in the string ad‐
457 minjohndoefoo). If this string matches regexp, then the
458 s//[g] substitution command will be run over the string.
459 The optional g will cause the substitution to be global
460 over the string, instead of replacing only the first
461 match in the string.
462 DEFAULT
464 The principal name will be used as the local user name.
465 If the principal has more than one component or is not in
466 the default realm, this rule is not applicable and the
467 conversion will fail.
468 For example:
470 [realms]
472 ATHENA.MIT.EDU = {
473 auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/
474 auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$//
475 auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/
476 auth_to_local = DEFAULT
477 }
478 would result in any principal without root or admin as the sec‐
480 ond component to be translated with the default rule. A princi‐
481 pal with a second component of admin will become its first com‐
482 ponent. root will be used as the local name for any principal
483 with a second component of root. The exception to these two
484 rules are any principals johndoe/*, which will always get the
485 local name guest.
486 auth_to_local_names
488 This subsection allows you to set explicit mappings from princi‐
489 pal names to local user names. The tag is the mapping name, and
490 the value is the corresponding local user name.
491 default_domain
493 This tag specifies the domain used to expand hostnames when
494 translating Kerberos 4 service principals to Kerberos 5 princi‐
495 pals (for example, when converting rcmd.hostname to host/host‐
496 name.domain).
497 disable_encrypted_timestamp
499 If this flag is true, the client will not perform encrypted
500 timestamp preauthentication if requested by the KDC. Setting
501 this flag can help to prevent dictionary attacks by active at‐
502 tackers, if the realm's KDCs support SPAKE preauthentication or
503 if initial authentication always uses another mechanism or al‐
504 ways uses FAST. This flag persists across client referrals dur‐
505 ing initial authentication. This flag does not prevent the KDC
506 from offering encrypted timestamp. New in release 1.17.
507 http_anchors
509 When KDCs and kpasswd servers are accessed through HTTPS prox‐
510 ies, this tag can be used to specify the location of the CA cer‐
511 tificate which should be trusted to issue the certificate for a
512 proxy server. If left unspecified, the system-wide default set
513 of CA certificates is used.
514 The syntax for values is similar to that of values for the
516 pkinit_anchors tag:
517 FILE: filename
519 filename is assumed to be the name of an OpenSSL-style ca-bundle
521 file.
522 DIR: dirname
524 dirname is assumed to be an directory which contains CA certifi‐
526 cates. All files in the directory will be examined; if they
527 contain certificates (in PEM format), they will be used.
528 ENV: envvar
530 envvar specifies the name of an environment variable which has
532 been set to a value conforming to one of the previous values.
533 For example, ENV:X509_PROXY_CA, where environment variable
534 X509_PROXY_CA has been set to FILE:/tmp/my_proxy.pem.
535 kdc The name or address of a host running a KDC for that realm. An
537 optional port number, separated from the hostname by a colon,
538 may be included. If the name or address contains colons (for
539 example, if it is an IPv6 address), enclose it in square brack‐
540 ets to distinguish the colon from a port separator. For your
541 computer to be able to communicate with the KDC for each realm,
542 this tag must be given a value in each realm subsection in the
543 configuration file, or there must be DNS SRV records specifying
544 the KDCs.
545 kpasswd_server
547 Points to the server where all the password changes are per‐
548 formed. If there is no such entry, DNS will be queried (unless
549 forbidden by dns_lookup_kdc). Finally, port 464 on the ad‐
550 min_server host will be tried.
551 master_kdc
553 The name for primary_kdc prior to release 1.19. Its value is
554 used as a fallback if primary_kdc is not specified.
555 primary_kdc
557 Identifies the primary KDC(s). Currently, this tag is used in
558 only one case: If an attempt to get credentials fails because of
559 an invalid password, the client software will attempt to contact
560 the primary KDC, in case the user's password has just been
561 changed, and the updated database has not been propagated to the
562 replica servers yet. New in release 1.19.
563 v4_instance_convert
565 This subsection allows the administrator to configure exceptions
566 to the default_domain mapping rule. It contains V4 instances
567 (the tag name) which should be translated to some specific host‐
568 name (the tag value) as the second component in a Kerberos V5
569 principal name.
570 v4_realm
572 This relation is used by the krb524 library routines when con‐
573 verting a V5 principal name to a V4 principal name. It is used
574 when the V4 realm name and the V5 realm name are not the same,
575 but still share the same principal names and passwords. The tag
576 value is the Kerberos V4 realm name.
577 [domain_realm]
579 The [domain_realm] section provides a translation from hostnames to
580 Kerberos realms. Each tag is a domain name, providing the mapping for
581 that domain and all subdomains. If the tag begins with a period (.)
582 then it applies only to subdomains. The Kerberos realm may be identi‐
583 fied either in the realms section or using DNS SRV records. Tag names
584 should be in lower case. For example:
585 [domain_realm]
587 crash.mit.edu = TEST.ATHENA.MIT.EDU
588 .dev.mit.edu = TEST.ATHENA.MIT.EDU
589 mit.edu = ATHENA.MIT.EDU
590 maps the host with the name crash.mit.edu into the TEST.ATHENA.MIT.EDU
592 realm. The second entry maps all hosts under the domain dev.mit.edu
593 into the TEST.ATHENA.MIT.EDU realm, but not the host with the name
594 dev.mit.edu. That host is matched by the third entry, which maps the
595 host mit.edu and all hosts under the domain mit.edu that do not match a
596 preceding rule into the realm ATHENA.MIT.EDU.
597 If no translation entry applies to a hostname used for a service prin‐
599 cipal for a service ticket request, the library will try to get a re‐
600 ferral to the appropriate realm from the client realm's KDC. If that
601 does not succeed, the host's realm is considered to be the hostname's
602 domain portion converted to uppercase, unless the realm_try_domains
603 setting in [libdefaults] causes a different parent domain to be used.
604 [capaths]
606 In order to perform direct (non-hierarchical) cross-realm authentica‐
607 tion, configuration is needed to determine the authentication paths be‐
608 tween realms.
609 A client will use this section to find the authentication path between
611 its realm and the realm of the server. The server will use this sec‐
612 tion to verify the authentication path used by the client, by checking
613 the transited field of the received ticket.
614 There is a tag for each participating client realm, and each tag has
616 subtags for each of the server realms. The value of the subtags is an
617 intermediate realm which may participate in the cross-realm authentica‐
618 tion. The subtags may be repeated if there is more then one intermedi‐
619 ate realm. A value of "." means that the two realms share keys di‐
620 rectly, and no intermediate realms should be allowed to participate.
621 Only those entries which will be needed on the client or the server
623 need to be present. A client needs a tag for its local realm with sub‐
624 tags for all the realms of servers it will need to authenticate to. A
625 server needs a tag for each realm of the clients it will serve, with a
626 subtag of the server realm.
627 For example, ANL.GOV, PNL.GOV, and NERSC.GOV all wish to use the ES.NET
629 realm as an intermediate realm. ANL has a sub realm of TEST.ANL.GOV
630 which will authenticate with NERSC.GOV but not PNL.GOV. The [capaths]
631 section for ANL.GOV systems would look like this:
632 [capaths]
634 ANL.GOV = {
635 TEST.ANL.GOV = .
636 PNL.GOV = ES.NET
637 NERSC.GOV = ES.NET
638 ES.NET = .
639 }
640 TEST.ANL.GOV = {
641 ANL.GOV = .
642 }
643 PNL.GOV = {
644 ANL.GOV = ES.NET
645 }
646 NERSC.GOV = {
647 ANL.GOV = ES.NET
648 }
649 ES.NET = {
650 ANL.GOV = .
651 }
652 The [capaths] section of the configuration file used on NERSC.GOV sys‐
654 tems would look like this:
655 [capaths]
657 NERSC.GOV = {
658 ANL.GOV = ES.NET
659 TEST.ANL.GOV = ES.NET
660 TEST.ANL.GOV = ANL.GOV
661 PNL.GOV = ES.NET
662 ES.NET = .
663 }
664 ANL.GOV = {
665 NERSC.GOV = ES.NET
666 }
667 PNL.GOV = {
668 NERSC.GOV = ES.NET
669 }
670 ES.NET = {
671 NERSC.GOV = .
672 }
673 TEST.ANL.GOV = {
674 NERSC.GOV = ANL.GOV
675 NERSC.GOV = ES.NET
676 }
677 When a subtag is used more than once within a tag, clients will use the
679 order of values to determine the path. The order of values is not im‐
680 portant to servers.
681 [appdefaults]
683 Each tag in the [appdefaults] section names a Kerberos V5 application
684 or an option that is used by some Kerberos V5 application[s]. The
685 value of the tag defines the default behaviors for that application.
686 For example:
688 [appdefaults]
690 telnet = {
691 ATHENA.MIT.EDU = {
692 option1 = false
693 }
694 }
695 telnet = {
696 option1 = true
697 option2 = true
698 }
699 ATHENA.MIT.EDU = {
700 option2 = false
701 }
702 option2 = true
703 The above four ways of specifying the value of an option are shown in
705 order of decreasing precedence. In this example, if telnet is running
706 in the realm EXAMPLE.COM, it should, by default, have option1 and op‐
707 tion2 set to true. However, a telnet program in the realm
708 ATHENA.MIT.EDU should have option1 set to false and option2 set to
709 true. Any other programs in ATHENA.MIT.EDU should have option2 set to
710 false by default. Any programs running in other realms should have op‐
711 tion2 set to true.
712 The list of specifiable options for each application may be found in
714 that application's man pages. The application defaults specified here
715 are overridden by those specified in the realms section.
716 [plugins]
718 • pwqual interface
719 • kadm5_hook interface
721 • clpreauth and kdcpreauth interfaces
723 Tags in the [plugins] section can be used to register dynamic plugin
725 modules and to turn modules on and off. Not every krb5 pluggable in‐
726 terface uses the [plugins] section; the ones that do are documented
727 here.
728 New in release 1.9.
730 Each pluggable interface corresponds to a subsection of [plugins]. All
732 subsections support the same tags:
733 disable
735 This tag may have multiple values. If there are values for this
736 tag, then the named modules will be disabled for the pluggable
737 interface.
738 enable_only
740 This tag may have multiple values. If there are values for this
741 tag, then only the named modules will be enabled for the plug‐
742 gable interface.
743 module This tag may have multiple values. Each value is a string of
745 the form modulename:pathname, which causes the shared object lo‐
746 cated at pathname to be registered as a dynamic module named
747 modulename for the pluggable interface. If pathname is not an
748 absolute path, it will be treated as relative to the
749 plugin_base_dir value from [libdefaults].
750 For pluggable interfaces where module order matters, modules registered
752 with a module tag normally come first, in the order they are regis‐
753 tered, followed by built-in modules in the order they are documented
754 below. If enable_only tags are used, then the order of those tags
755 overrides the normal module order.
756 The following subsections are currently supported within the [plugins]
758 section:
759 ccselect interface
761 The ccselect subsection controls modules for credential cache selection
762 within a cache collection. In addition to any registered dynamic mod‐
763 ules, the following built-in modules exist (and may be disabled with
764 the disable tag):
765 k5identity
767 Uses a .k5identity file in the user's home directory to select a
768 client principal
769 realm Uses the service realm to guess an appropriate cache from the
771 collection
772 hostname
774 If the service principal is host-based, uses the service host‐
775 name to guess an appropriate cache from the collection
776 pwqual interface
778 The pwqual subsection controls modules for the password quality inter‐
779 face, which is used to reject weak passwords when passwords are
780 changed. The following built-in modules exist for this interface:
781 dict Checks against the realm dictionary file
783 empty Rejects empty passwords
785 hesiod Checks against user information stored in Hesiod (only if Ker‐
787 beros was built with Hesiod support)
788 princ Checks against components of the principal name
790 kadm5_hook interface
792 The kadm5_hook interface provides plugins with information on principal
793 creation, modification, password changes and deletion. This interface
794 can be used to write a plugin to synchronize MIT Kerberos with another
795 database such as Active Directory. No plugins are built in for this
796 interface.
797 kadm5_auth interface
799 The kadm5_auth section (introduced in release 1.16) controls modules
800 for the kadmin authorization interface, which determines whether a
801 client principal is allowed to perform a kadmin operation. The follow‐
802 ing built-in modules exist for this interface:
803 acl This module reads the kadm5.acl file, and authorizes operations
805 which are allowed according to the rules in the file.
806 self This module authorizes self-service operations including pass‐
808 word changes, creation of new random keys, fetching the client's
809 principal record or string attributes, and fetching the policy
810 record associated with the client principal.
811 clpreauth and kdcpreauth interfaces
813 The clpreauth and kdcpreauth interfaces allow plugin modules to provide
814 client and KDC preauthentication mechanisms. The following built-in
815 modules exist for these interfaces:
816 pkinit This module implements the PKINIT preauthentication mechanism.
818 encrypted_challenge
820 This module implements the encrypted challenge FAST factor.
821 encrypted_timestamp
823 This module implements the encrypted timestamp mechanism.
824 hostrealm interface
826 The hostrealm section (introduced in release 1.12) controls modules for
827 the host-to-realm interface, which affects the local mapping of host‐
828 names to realm names and the choice of default realm. The following
829 built-in modules exist for this interface:
830 profile
832 This module consults the [domain_realm] section of the profile
833 for authoritative host-to-realm mappings, and the default_realm
834 variable for the default realm.
835 dns This module looks for DNS records for fallback host-to-realm
837 mappings and the default realm. It only operates if the
838 dns_lookup_realm variable is set to true.
839 domain This module applies heuristics for fallback host-to-realm map‐
841 pings. It implements the realm_try_domains variable, and uses
842 the uppercased parent domain of the hostname if that does not
843 produce a result.
844 localauth interface
846 The localauth section (introduced in release 1.12) controls modules for
847 the local authorization interface, which affects the relationship be‐
848 tween Kerberos principals and local system accounts. The following
849 built-in modules exist for this interface:
850 default
852 This module implements the DEFAULT type for auth_to_local val‐
853 ues.
854 rule This module implements the RULE type for auth_to_local values.
856 names This module looks for an auth_to_local_names mapping for the
858 principal name.
859 auth_to_local
861 This module processes auth_to_local values in the default
862 realm's section, and applies the default method if no
863 auth_to_local values exist.
864 k5login
866 This module authorizes a principal to a local account according
867 to the account's .k5login file.
868 an2ln This module authorizes a principal to a local account if the
870 principal name maps to the local account name.
871 certauth interface
873 The certauth section (introduced in release 1.16) controls modules for
874 the certificate authorization interface, which determines whether a
875 certificate is allowed to preauthenticate a user via PKINIT. The fol‐
876 lowing built-in modules exist for this interface:
877 pkinit_san
879 This module authorizes the certificate if it contains a PKINIT
880 Subject Alternative Name for the requested client principal, or
881 a Microsoft UPN SAN matching the principal if pkinit_allow_upn
882 is set to true for the realm.
883 pkinit_eku
885 This module rejects the certificate if it does not contain an
886 Extended Key Usage attribute consistent with the
887 pkinit_eku_checking value for the realm.
888 dbmatch
890 This module authorizes or rejects the certificate according to
891 whether it matches the pkinit_cert_match string attribute on the
892 client principal, if that attribute is present.
893
895 NOTE:
896 The following are PKINIT-specific options. These values may be
897 specified in [libdefaults] as global defaults, or within a
898 realm-specific subsection of [libdefaults], or may be specified as
899 realm-specific values in the [realms] section. A realm-specific
900 value overrides, not adds to, a generic [libdefaults] specification.
901 The search order is:
902 1. realm-specific subsection of [libdefaults]:
904 [libdefaults]
906 EXAMPLE.COM = {
907 pkinit_anchors = FILE:/usr/local/example.com.crt
908 }
909 2. realm-specific value in the [realms] section:
911 [realms]
913 OTHERREALM.ORG = {
914 pkinit_anchors = FILE:/usr/local/otherrealm.org.crt
915 }
916 3. generic value in the [libdefaults] section:
918 [libdefaults]
920 pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
921 Specifying PKINIT identity information
923 The syntax for specifying Public Key identity, trust, and revocation
924 information for PKINIT is as follows:
925 FILE:filename[,keyfilename]
927 This option has context-specific behavior.
928 In pkinit_identity or pkinit_identities, filename specifies the
930 name of a PEM-format file containing the user's certificate. If
931 keyfilename is not specified, the user's private key is expected
932 to be in filename as well. Otherwise, keyfilename is the name
933 of the file containing the private key.
934 In pkinit_anchors or pkinit_pool, filename is assumed to be the
936 name of an OpenSSL-style ca-bundle file.
937 DIR:dirname
939 This option has context-specific behavior.
940 In pkinit_identity or pkinit_identities, dirname specifies a di‐
942 rectory with files named *.crt and *.key where the first part of
943 the file name is the same for matching pairs of certificate and
944 private key files. When a file with a name ending with .crt is
945 found, a matching file ending with .key is assumed to contain
946 the private key. If no such file is found, then the certificate
947 in the .crt is not used.
948 In pkinit_anchors or pkinit_pool, dirname is assumed to be an
950 OpenSSL-style hashed CA directory where each CA cert is stored
951 in a file named hash-of-ca-cert.#. This infrastructure is en‐
952 couraged, but all files in the directory will be examined and if
953 they contain certificates (in PEM format), they will be used.
954 In pkinit_revoke, dirname is assumed to be an OpenSSL-style
956 hashed CA directory where each revocation list is stored in a
957 file named hash-of-ca-cert.r#. This infrastructure is encour‐
958 aged, but all files in the directory will be examined and if
959 they contain a revocation list (in PEM format), they will be
960 used.
961 PKCS12:filename
963 filename is the name of a PKCS #12 format file, containing the
964 user's certificate and private key.
965 PKCS11:[module_name=]modname[:slotid=slot-id][:token=token-label][:cer‐
967 tid=cert-id][:certlabel=cert-label]
968 All keyword/values are optional. modname specifies the location
969 of a library implementing PKCS #11. If a value is encountered
970 with no keyword, it is assumed to be the modname. If no mod‐
971 ule-name is specified, the default is p11-kit-proxy.so. slotid=
972 and/or token= may be specified to force the use of a particular
973 smard card reader or token if there is more than one available.
974 certid= and/or certlabel= may be specified to force the selec‐
975 tion of a particular certificate on the device. See the
976 pkinit_cert_match configuration option for more ways to select a
977 particular certificate to use for PKINIT.
978 ENV:envvar
980 envvar specifies the name of an environment variable which has
981 been set to a value conforming to one of the previous values.
982 For example, ENV:X509_PROXY, where environment variable
983 X509_PROXY has been set to FILE:/tmp/my_proxy.pem.
984 PKINIT krb5.conf options
986 pkinit_anchors
987 Specifies the location of trusted anchor (root) certificates
988 which the client trusts to sign KDC certificates. This option
989 may be specified multiple times. These values from the config
990 file are not used if the user specifies X509_anchors on the com‐
991 mand line.
992 pkinit_cert_match
994 Specifies matching rules that the client certificate must match
995 before it is used to attempt PKINIT authentication. If a user
996 has multiple certificates available (on a smart card, or via
997 other media), there must be exactly one certificate chosen be‐
998 fore attempting PKINIT authentication. This option may be spec‐
999 ified multiple times. All the available certificates are
1000 checked against each rule in order until there is a match of ex‐
1001 actly one certificate.
1002 The Subject and Issuer comparison strings are the RFC 2253
1004 string representations from the certificate Subject DN and Is‐
1005 suer DN values.
1006 The syntax of the matching rules is:
1008 [relation-operator]component-rule ...
1009 where:
1011 relation-operator
1013 can be either &&, meaning all component rules must match,
1014 or ||, meaning only one component rule must match. The
1015 default is &&.
1016 component-rule
1018 can be one of the following. Note that there is no punc‐
1019 tuation or whitespace between component rules.
1020 <SUBJECT>regular-expression
1021 <ISSUER>regular-expression
1022 <SAN>regular-expression
1023 <EKU>extended-key-usage-list
1024 <KU>key-usage-list
1025 extended-key-usage-list is a comma-separated list of re‐
1028 quired Extended Key Usage values. All values in the list
1029 must be present in the certificate. Extended Key Usage
1030 values can be:
1031 • pkinit
1033 • msScLogin
1035 • clientAuth
1037 • emailProtection
1039 key-usage-list is a comma-separated list of required Key
1041 Usage values. All values in the list must be present in
1042 the certificate. Key Usage values can be:
1043 • digitalSignature
1045 • keyEncipherment
1047 Examples:
1049 pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
1051 pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
1052 pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
1053 pkinit_eku_checking
1055 This option specifies what Extended Key Usage value the KDC cer‐
1056 tificate presented to the client must contain. (Note that if
1057 the KDC certificate has the pkinit SubjectAlternativeName en‐
1058 coded as the Kerberos TGS name, EKU checking is not necessary
1059 since the issuing CA has certified this as a KDC certificate.)
1060 The values recognized in the krb5.conf file are:
1061 kpKDC This is the default value and specifies that the KDC must
1063 have the id-pkinit-KPKdc EKU as defined in RFC 4556.
1064 kpServerAuth
1066 If kpServerAuth is specified, a KDC certificate with the
1067 id-kp-serverAuth EKU will be accepted. This key usage
1068 value is used in most commercially issued server certifi‐
1069 cates.
1070 none If none is specified, then the KDC certificate will not
1072 be checked to verify it has an acceptable EKU. The use
1073 of this option is not recommended.
1074 pkinit_dh_min_bits
1076 Specifies the size of the Diffie-Hellman key the client will at‐
1077 tempt to use. The acceptable values are 1024, 2048, and 4096.
1078 The default is 2048.
1079 pkinit_identities
1081 Specifies the location(s) to be used to find the user's X.509
1082 identity information. If this option is specified multiple
1083 times, each value is attempted in order until certificates are
1084 found. Note that these values are not used if the user speci‐
1085 fies X509_user_identity on the command line.
1086 pkinit_kdc_hostname
1088 The presence of this option indicates that the client is willing
1089 to accept a KDC certificate with a dNSName SAN (Subject Alterna‐
1090 tive Name) rather than requiring the id-pkinit-san as defined in
1091 RFC 4556. This option may be specified multiple times. Its
1092 value should contain the acceptable hostname for the KDC (as
1093 contained in its certificate).
1094 pkinit_pool
1096 Specifies the location of intermediate certificates which may be
1097 used by the client to complete the trust chain between a KDC
1098 certificate and a trusted anchor. This option may be specified
1099 multiple times.
1100 pkinit_require_crl_checking
1102 The default certificate verification process will always check
1103 the available revocation information to see if a certificate has
1104 been revoked. If a match is found for the certificate in a CRL,
1105 verification fails. If the certificate being verified is not
1106 listed in a CRL, or there is no CRL present for its issuing CA,
1107 and pkinit_require_crl_checking is false, then verification suc‐
1108 ceeds.
1109 However, if pkinit_require_crl_checking is true and there is no
1111 CRL information available for the issuing CA, then verification
1112 fails.
1113 pkinit_require_crl_checking should be set to true if the policy
1115 is such that up-to-date CRLs must be present for every CA.
1116 pkinit_revoke
1118 Specifies the location of Certificate Revocation List (CRL) in‐
1119 formation to be used by the client when verifying the validity
1120 of the KDC certificate presented. This option may be specified
1121 multiple times.
1122
1124 Starting with release 1.11, several variables, such as de‐
1125 fault_keytab_name, allow parameters to be expanded. Valid parameters
1126 are:
1127 ┌──────────────────┬────────────────────────────┐
1129 │%{TEMP} │ Temporary directory │
1130 ├──────────────────┼────────────────────────────┤
1131 │%{uid} │ Unix real UID or Windows │
1132 │ │ SID │
1133 └──────────────────┴────────────────────────────┘
1134 │%{euid} │ Unix effective user ID or │
1137 │ │ Windows SID │
1138 ├──────────────────┼────────────────────────────┤
1139 │%{USERID} │ Same as %{uid} │
1140 ├──────────────────┼────────────────────────────┤
1141 │%{null} │ Empty string │
1142 ├──────────────────┼────────────────────────────┤
1143 │%{LIBDIR} │ Installation library di‐ │
1144 │ │ rectory │
1145 ├──────────────────┼────────────────────────────┤
1146 │%{BINDIR} │ Installation binary direc‐ │
1147 │ │ tory │
1148 ├──────────────────┼────────────────────────────┤
1149 │%{SBINDIR} │ Installation admin binary │
1150 │ │ directory │
1151 ├──────────────────┼────────────────────────────┤
1152 │%{username} │ (Unix) Username of effec‐ │
1153 │ │ tive user ID │
1154 ├──────────────────┼────────────────────────────┤
1155 │%{APPDATA} │ (Windows) Roaming applica‐ │
1156 │ │ tion data for current user │
1157 ├──────────────────┼────────────────────────────┤
1158 │%{COMMON_APPDATA} │ (Windows) Application data │
1159 │ │ for all users │
1160 ├──────────────────┼────────────────────────────┤
1161 │%{LOCAL_APPDATA} │ (Windows) Local applica‐ │
1162 │ │ tion data for current user │
1163 ├──────────────────┼────────────────────────────┤
1164 │%{SYSTEM} │ (Windows) Windows system │
1165 │ │ folder │
1166 ├──────────────────┼────────────────────────────┤
1167 │%{WINDOWS} │ (Windows) Windows folder │
1168 ├──────────────────┼────────────────────────────┤
1169 │%{USERCONFIG} │ (Windows) Per-user MIT │
1170 │ │ krb5 config file directory │
1171 ├──────────────────┼────────────────────────────┤
1172 │%{COMMONCONFIG} │ (Windows) Common MIT krb5 │
1173 │ │ config file directory │
1174 └──────────────────┴────────────────────────────┘
1175
1177 Here is an example of a generic krb5.conf file:
1178 [libdefaults]
1180 default_realm = ATHENA.MIT.EDU
1181 dns_lookup_kdc = true
1182 dns_lookup_realm = false
1183 [realms]
1185 ATHENA.MIT.EDU = {
1186 kdc = kerberos.mit.edu
1187 kdc = kerberos-1.mit.edu
1188 kdc = kerberos-2.mit.edu
1189 admin_server = kerberos.mit.edu
1190 primary_kdc = kerberos.mit.edu
1191 }
1192 EXAMPLE.COM = {
1193 kdc = kerberos.example.com
1194 kdc = kerberos-1.example.com
1195 admin_server = kerberos.example.com
1196 }
1197 [domain_realm]
1199 mit.edu = ATHENA.MIT.EDU
1200 [capaths]
1202 ATHENA.MIT.EDU = {
1203 EXAMPLE.COM = .
1204 }
1205 EXAMPLE.COM = {
1206 ATHENA.MIT.EDU = .
1207 }
1208
1210 /etc/krb5.conf
1211
1213 syslog(3)
1214
1216 MIT
1217
1219 1985-2023, MIT
12201.21 KRB5.CONF(5)