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