1 KRB5.CONF(4) File Formats and Configurations KRB5.CONF(4)
2
3
4
5 NAME
6 krb5.conf - Kerberos configuration file
7
8 SYNOPSIS
9 /etc/krb5/krb5.conf
10
11
12 DESCRIPTION
13 The krb5.conf file contains Kerberos configuration information,
14 including the locations of KDCs and administration daemons for the
15 Kerberos realms of interest, defaults for the current realm and for
16 Kerberos applications, and mappings of host names onto Kerberos realms.
17 This file must reside on all Kerberos clients.
18
19
20 The format of the krb5.conf consists of sections headings in square
21 brackets. Each section can contain zero or more configuration variables
22 (called relations), of the form:
23
24
25 relation= relation-value
26
27
28 or
29
30
31 relation-subsection = {
32 relation= relation-value
33 relation= relation-value
34
35
36 }
37
38
39 The krb5.conf file can contain any or all of the following sections:
40
41 libdefaults
42
43 Contains default values used by the Kerberos V5 library.
44
45
46 appdefaults
47
48 Contains subsections for Kerberos V5 applications, where relation-
49 subsection is the name of an application. Each subsection describes
50 application-specific defaults.
51
52
53 realms
54
55 Contains subsections for Kerberos realms, where relation-subsection
56 is the name of a realm. Each subsection contains relations that
57 define the properties for that particular realm.
58
59
60 domain_realm
61
62 Contains relations which map domain names and subdomains onto
63 Kerberos realm names. This is used by programs to determine what
64 realm a host should be in, given its fully qualified domain name.
65
66
67 logging
68
69 Contains relations which determine how Kerberos programs are to
70 perform logging.
71
72
73 capaths
74
75 Contains the authentication paths used with direct
76 (nonhierarchical) cross-realm authentication. Entries in this
77 section are used by the client to determine the intermediate realms
78 which can be used in cross-realm authentication. It is also used by
79 the end-service when checking the transited field for trusted
80 intermediate realms.
81
82
83 dbmodules
84
85 Contains relations for Kerberos database plug-in-specific
86 configuration information.
87
88
89 kdc
90
91 For a Key Distribution Center (KDC), can contain the location of
92 the kdc.conf file.
93
94
95 The [libdefaults] Section
96 The [libdefaults] section can contain any of the following relations:
97
98 database_module
99
100 Selects the dbmodule section entry to use to access the Kerberos
101 database. If this parameter is not present the code uses the
102 standard db2-based Kerberos database.
103
104
105 default_keytab_name
106
107 Specifies the default keytab name to be used by application servers
108 such as telnetd and rlogind. The default is /etc/krb5/krb5.keytab.
109
110
111 default_realm
112
113 Identifies the default Kerberos realm for the client. Set its value
114 to your Kerberos realm.
115
116
117 default_tgs_enctypes
118
119 Identifies the supported list of session key encryption types that
120 should be returned by the KDC. The list can be delimited with
121 commas or whitespace. The supported encryption types are des3-cbc-
122 sha1-kd, des-cbc-crc, des-cbc-md5, arcfour-hmac-md5, arcfour-hmac-
123 md5-exp, aes128-cts-hmac-sha1-96, and aes256-cts-hmac-sha1-96.
124
125
126 default_tkt_enctypes
127
128 Identifies the supported list of session key encryption types that
129 should be requested by the client. The format is the same as for
130 default_tgs_enctypes. The supported encryption types are des3-cbc-
131 sha1-kd, des-cbc-crc, des-cbc-md5, arcfour-hmac-md5, arcfour-hmac-
132 md5-exp, aes128-cts-hmac-sha1-96, and aes256-cts-hmac-sha1-96.
133
134
135 clockskew
136
137 Sets the maximum allowable amount of clock skew in seconds that the
138 library tolerates before assuming that a Kerberos message is
139 invalid. The default value is 300 seconds, or five minutes.
140
141
142 forwardable = [true | false]
143
144 Sets the "forwardable" flag in all tickets. This allows users to
145 transfer their credentials from one host to another without
146 reauthenticating. This option can also be set in the [appdefaults]
147 or [realms] section (see below) to limit its use in particular
148 applications or just to a specific realm.
149
150
151 permitted_enctypes
152
153 This relation controls the encryption types for session keys
154 permitted by server applications that use Kerberos for
155 authentication. In addition, it controls the encryption types of
156 keys added to a keytab by means of the kadmin(1M) ktadd command.
157 The default is: aes256-cts-hmac-sha1-96, aes128-cts-hmac-sha1-96,
158 des3-hmac-sha1-kd, arcfour-hmac-md5, arcfour-hmac-md5-exp, des-cbc-
159 md5, des-cbc-crc.
160
161
162 proxiable = [true | false]
163
164 Sets the proxiable flag in all tickets. This allows users to create
165 a proxy ticket that can be transferred to a kerberized service to
166 allow that service to perform some function on behalf of the
167 original user. This option can also be set in the [appdefaults] or
168 [realms] section (see below) to limit its use in particular
169 applications or just to a specific realm.
170
171
172 renew_lifetime =lifetime
173
174 Requests renewable tickets, with a total lifetime of lifetime. The
175 value for lifetime must be followed immediately by one of the
176 following delimiters:
177
178 s
179
180 seconds
181
182
183 m
184
185 minutes
186
187
188 h
189
190 hours
191
192
193 d
194
195 days
196
197 Example:
198
199 renew_lifetime = 90m
200
201
202 Do not mix units. A value of "3h30m" results in an error.
203
204
205 max_lifetime =lifetime
206
207 Sets the requested maximum lifetime of the ticket. The values for
208 lifetime follow the format described for the renew_lifetime option,
209 above.
210
211
212 dns_lookup_kdc
213
214 Indicates whether DNS SRV records need to be used to locate the
215 KDCs and the other servers for a realm, if they have not already
216 been listed in the [realms] section. This option makes the machine
217 vulnerable to a certain type of DoS attack if someone spoofs the
218 DNS records and does a redirect to another server. This is,
219 however, no worse than a DoS, since the bogus KDC is unable to
220 decode anything sent (excepting the initial ticket request, which
221 has no encrypted data). Also, anything the fake KDC sends out isl
222 not trusted without verification (the local machine is unaware of
223 the secret key to be used). If dns_lookup_kdc is not specified but
224 dns_fallback is, then that value is used instead. In either case,
225 values (if present) in the [realms] section override DNS.
226 dns_lookup_kdc is enabled by default.
227
228
229 dns_lookup_realm
230
231 Indicates whether DNS TXT records need to be used to determine the
232 Kerberos realm information and/or the host/domain name-to-realm
233 mapping of a host, if this information is not already present in
234 the krb5.conf file. Enabling this option might make the host
235 vulnerable to a redirection attack, wherein spoofed DNS replies
236 persuade a client to authenticate to the wrong realm. In a realm
237 with no cross-realm trusts, this a DoS attack. If dns_lookup_realm
238 is not specified but dns_fallback is, then that value is used
239 instead. In either case, values (if present) in the [libdefaults]
240 and [domain_realm] sections override DNS.
241
242
243 dns_fallback
244
245 Generic flag controlling the use of DNS for retrieval of
246 information about Kerberos servers and host/domain name-to-realm
247 mapping. If both dns_lookup_kdc and dns_lookup_realm have been
248 specified, this option has no effect.
249
250
251 verify_ap_req_nofail [true | false]
252
253 If true, the local keytab file (/etc/krb5/krb5.keytab) must contain
254 an entry for the local host principal, for example,
255 host/foo.bar.com@FOO.COM. This entry is needed to verify that the
256 TGT requested was issued by the same KDC that issued the key for
257 the host principal. If undefined, the behavior is as if this option
258 were set to true. Setting this value to false leaves the system
259 vulnerable to DNS spoofing attacks. This parameter can be in the
260 [realms] section to set it on a per-realm basis, or it can be in
261 the [libdefaults] section to make it a network-wide setting for all
262 realms.
263
264
265 The [appdefaults] Section
266 This section contains subsections for Kerberos V5 applications, where
267 relation-subsection is the name of an application. Each subsection
268 contains relations that define the default behaviors for that
269 application.
270
271
272 The following relations can be found in the [appdefaults] section,
273 though not all relations are recognized by all kerberized applications.
274 Some are specific to particular applications.
275
276 autologin = [true | false]
277
278 Forces the application to attempt automatic login by presenting
279 Kerberos credentials. This is valid for the following applications:
280 rlogin, rsh, rcp, rdist, and telnet.
281
282
283 encrypt = [true | false]
284
285 Forces applications to use encryption by default (after
286 authentication) to protect the privacy of the sessions. This is
287 valid for the following applications: rlogin, rsh, rcp, rdist, and
288 telnet.
289
290
291 forward = [true | false]
292
293 Forces applications to forward the user'ss credentials (after
294 authentication) to the remote server. This is valid for the
295 following applications: rlogin, rsh, rcp, rdist, and telnet.
296
297
298 forwardable = [true | false]
299
300 See the description in the [libdefaults] section above. This is
301 used by any application that creates a ticket granting ticket and
302 also by applications that can forward tickets to a remote server.
303
304
305 proxiable = [true | false]
306
307 See the description in the [libdefaults] section above. This is
308 used by any application that creates a ticket granting ticket.
309
310
311 renewable = [true | false]
312
313 Creates a TGT that can be renewed (prior to the ticket expiration
314 time). This is used by any application that creates a ticket
315 granting ticket.
316
317
318 no_addresses = [true | false]
319
320 Creates tickets with no address bindings. This is to allow tickets
321 to be used across a NAT boundary or when using multi-homed systems.
322 This option is valid in the kinit [appdefault] section only.
323
324
325 max_life =lifetime
326
327 Sets the maximum lifetime of the ticket, with a total lifetime of
328 lifetime. The values for lifetime follow the format described in
329 the [libdefaults] section above. This option is obsolete and is
330 removed in a future release of the Solaris operating system.
331
332
333 max_renewable_life =lifetime
334
335 Requests renewable tickets, with a total lifetime of lifetime. The
336 values for lifetime follow the format described in the
337 [libdefaults] section above. This option is obsolete and is removed
338 in a future release of the Solaris operating system.
339
340
341 rcmd_protocol = [ rcmdv1 | rcmdv2 ]
342
343 Specifies which Kerberized "rcmd" protocol to use when using the
344 Kerberized rlogin(1), rsh(1), rcp(1), or rdist(1) programs. The
345 default is to use rcmdv2 by default, as this is the more secure and
346 more recent update of the protocol. However, when talking to older
347 MIT or SEAM-based "rcmd" servers, it can be necessary to force the
348 new clients to use the older rcmdv1 protocol. This option is valid
349 only for the following applications: rlogin, rcp, rsh, and rdist.
350
351
352
353 The following application defaults can be set to true or false:
354
355 kinit
356 forwardable = true
357 proxiable = true
358 renewable = true
359 no_addresses = true
360 max_life = delta_time
361 max_renewable_life = delta_time
362
363
364
365
366 See kinit(1) for the valid time duration formats you can specify for
367 delta_time.
368
369
370 In the following example, kinit gets forwardable tickets by default and
371 telnet has three default behaviors specified:
372
373 [appdefaults]
374 kinit = {
375 forwardable = true
376 }
377
378 telnet = {
379 forward = true
380 encrypt = true
381 autologin = true
382 }
383
384
385
386
387 The application defaults specified here are overridden by those
388 specified in the [realms] section.
389
390 The [realms] Section
391 This section contains subsections for Kerberos realms, where relation-
392 subsection is the name of a realm. Each subsection contains relations
393 that define the properties for that particular realm. The following
394 relations can be specified in each [realms] subsection:
395
396 admin_server
397
398 Identifies the host where the Kerberos administration daemon
399 (kadmind) is running. Typically, this is the master KDC.
400
401
402 application defaults
403
404 Application defaults that are specific to a particular realm can be
405 specified within a [realms] subsection. Realm-specific application
406 defaults override the global defaults specified in the
407 [appdefaults] section.
408
409
410 auth_to_local_realm
411
412 For use in the default realm, non-default realms can be equated
413 with the default realm for authenticated name-to-local name
414 mapping.
415
416
417 auth_to_local_names
418
419 This subsection allows you to set explicit mappings from principal
420 names to local user names. The tag is the mapping name and the
421 value is the corresponding local user name.
422
423
424 auth_to_local
425
426 This tag allows you to set a general rule for mapping principal
427 names to local user names. It is used if there is not an explicit
428 mapping for the principal name that is being translated. The
429 possible values are:
430
431 RULE:[<ncomps>:<format>](<regex>)s/<regex>/<text>/
432
433 Each rule has three parts:
434
435 First part--Formulate the string on which to perform operations:
436
437 If not present then the string defaults to the fully flattened
438 principal minus the realm name. Otherwise the syntax is as
439 follows:
440
441 "[" <ncomps> ":" <format> "]"
442
443 Where:
444
445 <ncomps> is the number of expected components for this rule. If
446 the particular principal does not have this number of
447 components, then this rule does not apply.
448
449 <format> is a string of <component> or verbatim characters to
450 be inserted.
451
452 <component> is of the form "$"<number> to select the <number>th
453 component. <number> begins from 1.
454
455
456 Second part--select rule validity:
457
458 If not present, this rule can apply to all selections.
459 Otherwise the syntax is as follows:
460
461 "(" <regex> ")"
462
463 Where:
464
465 <regex> is a selector regular expression. If this regular
466 expression matches the whole pattern generated from the first
467 part, then this rule still applies.
468
469
470 Third part--Transform rule:
471
472 If not present, then the selection string is passed verbatim
473 and is matched. Otherwise, the syntax is as follows:
474
475 <rule> ...
476
477 Where:
478
479 <rule> is of the form:
480
481 "s/" <regex> "/" <text> "/" ["g"]
482
483 Regular expressions are defined in regex(5).
484
485 For example:
486
487 auth_to_local = RULE:[1:$1@$0](.*@.*ACME.COM)s/@.*//
488
489 The preceding maps username@ACME.COM and all sub-realms of
490 ACME.COM to username.
491
492
493 DEFAULT
494
495 The principal name is used as the local name. If the principal
496 has more than one component or is not in the default realm,
497 this rule is not applicable and the conversion fails.
498
499
500
501 database_module
502
503 Selects the dbmodule section entry to use to access the Kerberos
504 database.
505
506
507 extra_addresses...
508
509 This allows a computer to use multiple local addresses, to allow
510 Kerberos to work in a network that uses NATs. The addresses should
511 be in a comma-separated list.
512
513
514 kdc
515
516 The name of a host running a KDC for that realm. An optional port
517 number (separated from the hostname by a colon) can be included.
518
519
520 kpasswd_server
521
522 Identifies the host where the Kerberos password-changing server is
523 running. Typically, this is the same as host indicated in the
524 admin_server. If this parameter is omitted, the host in
525 admin_server is used. You can also specify a port number if the
526 server indicated by kpasswd_server runs on a port other than 464
527 (the default). The format of this parameter is: hostname[:port].
528
529
530 kpasswd_protocol
531
532 Identifies the protocol to be used when communicating with the
533 server indicated by kpasswd_server. By default, this parameter is
534 defined to be RPCSEC_GSS, which is the protocol used by Solaris-
535 based administration servers. To be able to change a principal's
536 password stored on non-Solaris Kerberos server, such as Microsoft
537 Active Directory or MIT Kerberos, this value should be SET_CHANGE.
538 This indicates that a non-RPC- based protocol is used to
539 communicate the password change request to the server in the
540 kpasswd_server entry.
541
542
543 udp_preference_limit
544
545 When sending a message to the KDC, the library tries using TCP
546 before UDP if the size of the message is above
547 udp_preference_limit. If the message is smaller than
548 udp_preference_limit, then UDP is tried before TCP. Regardless of
549 the size, both protocols are tried if the first attempt fails.
550
551
552 verify_ap_req_nofail [true | false]
553
554 If true, the local keytab file (/etc/krb5/krb5.keytab) must contain
555 an entry for the local host principal, for example,
556 host/foo.bar.com@FOO.COM. This entry is needed to verify that the
557 TGT requested was issued by the same KDC that issued the key for
558 the host principal. If undefined, the behavior is as if this option
559 were set to true. Setting this value to false leaves the system
560 vulnerable to DNS spoofing attacks. This parameter might be in the
561 [realms] section to set it on a per-realm basis, or it might be in
562 the [libdefaults] section to make it a network-wide setting for all
563 realms.
564
565
566
567 The parameters "forwardable", "proxiable", and "renew_lifetime" as
568 described in the [libdefaults] section (see above) are also valid in
569 the [realms] section.
570
571
572 Notice that kpasswd_server and kpasswd_protocol are realm-specific
573 parameters. Most often, you need to specify them only when using a non-
574 Solaris-based Kerberos server. Otherwise, the change request is sent
575 over RPCSEC_GSS to the Solaris Kerberos administration server.
576
577 The [domain_realm] Section
578 This section provides a translation from a domain name or hostname to a
579 Kerberos realm name. The relation can be a host name, or a domain name,
580 where domain names are indicated by a period (`.') prefix. relation-
581 value is the Kerberos realm name for that particular host or domain.
582 Host names and domain names should be in lower case.
583
584
585 If no translation entry applies, the host's realm is considered to be
586 the hostname's domain portion converted to upper case. For example, the
587 following [domain_realm] section maps crash.mit.edu into the
588 TEST.ATHENA.MIT.EDU realm:
589
590 [domain_realm]
591 .mit.edu = ATHENA.MIT.EDU
592 mit.edu = ATHENA.MIT.EDU
593 crash.mit.edu = TEST.ATHENA.MIT.EDU
594 .fubar.org = FUBAR.ORG
595 fubar.org = FUBAR.ORG
596
597
598
599
600 All other hosts in the mit.edu domain maps by default to the
601 ATHENA.MIT.EDU realm, and all hosts in the fubar.org domain maps by
602 default into the FUBAR.ORG realm. The entries for the hosts mit.edu and
603 fubar.org. Without these entries, these hosts would be mapped into the
604 Kerberos realms EDU and ORG, respectively.
605
606 The [logging] Section
607 This section indicates how Kerberos programs are to perform logging.
608 There are two types of relations for this section: relations to specify
609 how to log and a relation to specify how to rotate kdc log files.
610
611
612 The following relations can be defined to specify how to log. The same
613 relation can be repeated if you want to assign it multiple logging
614 methods.
615
616 admin_server
617
618 Specifies how to log the Kerberos administration daemon (kadmind).
619 The default is FILE:/var/krb5/kadmin.log.
620
621
622 default
623
624 Specifies how to perform logging in the absence of explicit
625 specifications otherwise.
626
627
628 kdc
629
630 Specifies how the KDC is to perform its logging. The default is
631 FILE:/var/krb5/kdc.log.
632
633
634
635 The admin_server, default, and kdc relations can have the following
636 values:
637
638 FILE:filename
639 FILE=filename
640
641 This value causes the entity's logging messages to go to the
642 specified file. If the `=' form is used, the file is overwritten.
643 If the `:' form is used, the file is appended to.
644
645
646 STDERR
647
648 This value causes the entity's logging messages to go to its
649 standard error stream.
650
651
652 CONSOLE
653
654 This value causes the entity's logging messages to go to the
655 console, if the system supports it.
656
657
658 DEVICE=devicename
659
660 This causes the entity's logging messages to go to the specified
661 device.
662
663
664 SYSLOG[:severity[:facility]]
665
666 This causes the entity's logging messages to go to the system log.
667
668
669
670 The severity argument specifies the default severity of system log
671 messages. This can be any of the following severities supported by the
672 syslog(3C) call, minus the LOG_ prefix: LOG_EMERG, LOG_ALERT, LOG_CRIT,
673 LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG. For example,
674 a value of CRIT would specify LOG_CRIT severity.
675
676
677 The facility argument specifies the facility under which the messages
678 are logged. This can be any of the following facilities supported by
679 the syslog(3C) call minus the LOG_ prefix: LOG_KERN, LOG_USER,
680 LOG_MAIL, LOG_DAEMON, LOG_AUTH, LOG_LPR, LOG_NEWS, LOG_UUCP, LOG_CRON,
681 and LOG_LOCAL0 through LOG_LOCAL7.
682
683
684 If no severity is specified, the default is ERR. If no facility is
685 specified, the default is AUTH.
686
687
688 The following relation can be defined to specify how to rotate kdc log
689 files if the FILE: value is being used to log:
690
691 kdc_rotate
692
693 A relation subsection that enables kdc logging to be rotated to
694 multiple files based on a time interval. This can be used to avoid
695 logging to one file, which might grow too large and bring the KDC
696 to a halt.
697
698
699
700 The time interval for the rotation is specified by the period relation.
701 The number of log files to be rotated is specified by the versions
702 relation. Both the period and versions (described below) should be
703 included in this subsection. And, this subsection applies only if the
704 kdc relation has a FILE: value.
705
706
707 The following relations can be specified for the kdc_rotate relation
708 subsection:
709
710 period=delta_time
711
712 Specifies the time interval before a new log file is created. See
713 the TimeFormats section in kinit(1) for the valid time duration
714 formats you can specify for delta_time. If period is not specified
715 or set to never, no rotation occurs.
716
717
718
719 Specifying a time interval does not mean that the log files are rotated
720 at the time interval based on real time. This is because the time
721 interval is checked at each attempt to write a record to the log, or
722 when logging is actually occurring. Therefore, rotation occurs only
723 when logging has actually occurred for the specified time interval.
724
725 versions=number
726
727 Specifies how many previous versions are saved before the rotation
728 begins. A number is appended to the log file, starting with 0 and
729 ending with (number - 1). For example, if versions is set to 2, up
730 to three logging files are created (filename, filename.0, and
731 filename.1) before the first one is overwritten to begin the
732 rotation.
733
734
735
736 Notice that if versions is not specified or set to 0, only one log file
737 is created, but it is overwritten whenever the time interval is met.
738
739
740 In the following example, the logging messages from the Kerberos
741 administration daemon goes to the console. The logging messages from
742 the KDC is appended to the /var/krb5/kdc.log, which is rotated between
743 twenty-one log files with a specified time interval of a day.
744
745 [logging]
746 admin_server = CONSOLE
747 kdc = FILE:/export/logging/kadmin.log
748 kdc_rotate = {
749 period = 1d
750 versions = 20
751 }
752
753
754
755 The [capaths] Section
756 In order to perform direct (non-hierarchical) cross-realm
757 authentication, a database is needed to construct the authentication
758 paths between the realms. This section defines that database.
759
760
761 A client uses this section to find the authentication path between its
762 realm and the realm of the server. The server uses this section to
763 verify the authentication path used by the client, by checking the
764 transited field of the received ticket.
765
766
767 There is a subsection for each participating realm, and each subsection
768 has relations named for each of the realms. The relation-value is an
769 intermediate realm which can participate in the cross-realm
770 authentication. The relations can be repeated if there is more than one
771 intermediate realm. A value of '.' means that the two realms share keys
772 directly, and no intermediate realms should be allowed to participate.
773
774
775 There are n**2 possible entries in this table, but only those entries
776 which is needed on the client or the server need to be present. The
777 client needs a subsection named for its local realm, with relations
778 named for all the realms of servers it needs to authenticate with. A
779 server needs a subsection named for each realm of the clients it
780 serves.
781
782
783 For example, ANL.GOV, PNL.GOV, and NERSC.GOV all wish to use the ES.NET
784 realm as an intermediate realm. ANL has a sub realm of TEST.ANL.GOV,
785 which authenticates with NERSC.GOV but not PNL.GOV. The [capath]
786 section for ANL.GOV systems would look like this:
787
788 [capaths]
789 ANL.GOV = {
790 TEST.ANL.GOV = .
791 PNL.GOV = ES.NET
792 NERSC.GOV = ES.NET
793 ES.NET = .
794 }
795
796 TEST.ANL.GOV = {
797 ANL.GOV = .
798 }
799
800 PNL.GOV = {
801 ANL.GOV = ES.NET
802 }
803
804 NERSC.GOV = {
805 ANL.GOV = ES.NET
806 }
807
808 ES.NET = {
809 ANL.GOV = .
810 }
811
812
813
814
815 The [capath] section of the configuration file used on NERSC.GOV
816 systems would look like this:
817
818 [capaths]
819 NERSC.GOV = {
820 ANL.GOV = ES.NET
821 TEST.ANL.GOV = ES.NET
822 TEST.ANL.GOV = ANL.GOV
823 PNL.GOV = ES.NET
824 ES.NET = .
825 }
826
827 ANL.GOV = {
828 NERSC.GOV = ES.NET
829 }
830
831 PNL.GOV = {
832 NERSC.GOV = ES.NET
833 }
834
835 ES.NET = {
836 NERSC.GOV = .
837 }
838
839 TEST.ANL.GOV = {
840 NERSC.GOV = ANL.GOV
841 NERSC.GOV = ES.NET
842 }
843
844
845
846
847 In the above examples, the ordering is not important, except when the
848 same relation is used more than once. The client uses this to determine
849 the path. (It is not important to the server, since the transited
850 field is not sorted.)
851
852 PKINIT-specific Options
853 The following are pkinit-specific options. These values can be
854 specified in [libdefaults] as global defaults, or within a realm-
855 specific subsection of [libdefaults], or can be specified as realm-
856 specific values in the [realms] section. A realm-specific value
857 overrides, does not add to, a generic [libdefaults] specification.
858
859
860 The search order is:
861
862 1. realm-specific subsection of [libdefaults]
863
864 [libdefaults]
865 EXAMPLE.COM = {
866 pkinit_anchors = FILE:/usr/local/example.com.crt
867
868
869 2. realm-specific value in the [realms] section
870
871 [realms]
872 OTHERREALM.ORG = {
873 pkinit_anchors = FILE:/usr/local/otherrealm.org.crt
874
875
876 3. generic value in the [libdefaults] section
877
878 [libdefaults]
879 pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
880
881
882
883 The syntax for specifying Public Key identity, trust, and revocation
884 information for pkinit is as follows:
885
886 pkinit_identities = URI
887
888 Specifies the location(s) to be used to find the user's X.509
889 identity information. This option can be specified multiple times.
890 Each value is attempted in order until identity information is
891 found and authentication is attempted. These values are not used if
892 the user specifies X509_user_identity on the command line.
893
894 Valid URI types are FILE, DIR, PKCS11, PKCS12, and ENV. See the
895 PKINIT URI Types section for more details.
896
897
898 pkinit_anchors = URI
899
900 Specifies the location of trusted anchor (root) certificates which
901 the client trusts to sign KDC certificates. This option can be
902 specified multiple times. These values from the config file are
903 not used if the user specifies X509_anchors on the command line.
904
905 Valid URI types are FILE and DIR. See the PKINIT URI Types section
906 for more details.
907
908
909 pkinit_pool = URI
910
911 Specifies the location of intermediate certificates which can be
912 used by the client to complete the trust chain between a KDC
913 certificate and a trusted anchor. This option can be specified
914 multiple times.
915
916 Valid URI types are FILE and DIR. See the PKINIT URI Types
917 section for more details.
918
919
920 pkinit_revoke = URI
921
922 Specifies the location of Certificate Revocation List (CRL)
923 information to be used by the client when verifying the validity of
924 the KDC certificate presented. This option can be specified
925 multiple times.
926
927 The only valid URI type is DIR. See the PKINIT URI Types section
928 for more details.
929
930
931 pkinit_require_crl_checking = value
932
933 The default certificate verification process always checks the
934 available revocation information to see if a certificate has been
935 revoked. If a match is found for the certificate in a CRL,
936 verification fails. If the certificate being verified is not listed
937 in a CRL, or there is no CRL present for its issuing CA, and
938 pkinit_require_crl_checking is false, then verification succeeds.
939 However, if pkinit_require_crl_checking is true and there is no CRL
940 information available for the issuing CA, then verification fails.
941 pkinit_require_crl_checking should be set to true if the policy is
942 such that up-to-date CRLs must be present for every CA.
943
944
945 pkinit_dh_min_bits = value
946
947 Specifies the size of the Diffie-Hellman key the client attempts to
948 use. The acceptable values are currently 1024, 2048, and 4096. The
949 default is 2048.
950
951
952 pkinit_win2k = value
953
954 This flag specifies whether the target realm is assumed to support
955 only the old, pre-RFC version of the protocol. The default is
956 false.
957
958
959 pkinit_win2k_require_binding = value
960
961 If this flag is set to true, it expects that the target KDC is
962 patched to return a reply with a checksum rather than a nonce. The
963 default is false.
964
965
966 pkinit_eku_checking = value
967
968 This option specifies what Extended Key Usage value the KDC
969 certificate presented to the client must contain. If the KDC
970 certificate has the pkinit SubjectAlternativeName encoded as the
971 Kerberos TGS name, EKU checking is not necessary since the issuing
972 CA has certified this as a KDC certificate. The values recognized
973 in the krb5.conf file are:
974
975 kpKDC
976 This is the default value and specifies that the
977 KDC must have the id-pkinit-KPKdc EKU as defined in
978 RFC4556.
979
980
981 kpServerAuth
982 If kpServerAuth is specified, a KDC certificate
983 with the id-kp-serverAuth EKU as used by Microsoft
984 is accepted.
985
986
987 none
988 If none is specified, then the KDC certificate is
989 not checked to verify it has an acceptable EKU. The
990 use of this option is not recommended.
991
992
993
994 pkinit_kdc_hostname = value
995
996 The presence of this option indicates that the client is willing to
997 accept a KDC certificate with a dNSName SAN (Subject Alternative
998 Name) rather than requiring the id-pkinit-san as defined in
999 RFC4556. This option can be specified multiple times. Its value
1000 should contain the acceptable hostname for the KDC (as contained in
1001 its certificate).
1002
1003
1004 pkinit_cert_match = rule
1005
1006 Specifies matching rules that the client certificate must match
1007 before it is used to attempt pkinit authentication. If a user has
1008 multiple certificates available (on a smart card, or by way of
1009 another media), there must be exactly one certificate chosen before
1010 attempting pkinit authentication. This option can be specified
1011 multiple times. All the available certificates are checked against
1012 each rule in order until there is a match of exactly one
1013 certificate.
1014
1015 The Subject and Issuer comparison strings are the RFC2253 string
1016 representations from the certificate Subject DN and Issuer DN
1017 values.
1018
1019 The syntax of the matching rules is:
1020
1021 [relation-operator]component-rule `...'
1022
1023 where
1024
1025 relation-operator
1026 Specify relation-operator as &&, meaning all
1027 component rules must match, or ||, meaning
1028 only one component rule must match. If
1029 relation-operator is not specified, the
1030 default is &&.
1031
1032
1033 component-rule
1034 There is no punctuation or white space between
1035 component rules.Specify component-rule as one
1036 of the following:
1037
1038 `<SUBJECT>'regular-expression
1039
1040 `<ISSUER>'regular-expression
1041
1042 `<SAN>'regular-expression
1043
1044 `<EKU>'extended-key-usage-list
1045 where extended-key-usage-list is a comma-separated list
1046 of required Extended Key Usage values. All values in
1047 the list must be present in the certificate.
1048 `pkinit'
1049 `msScLogin'
1050 `clientAuth'
1051 `emailProtection'
1052 `<KU>'key-usage-list
1053 where key-usage-list is a comma-separated list of
1054 required Key Usage values. All values in the list must
1055 be present in the certificate.
1056 `digitalSignature'
1057
1058
1059 Examples:
1060
1061 pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
1062 pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
1063 pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
1064
1065
1066
1067 PKINIT URI Types
1068 FILE:file-name[,key-file-name]
1069
1070 This option has context-specific behavior.
1071
1072 pkinit_identities
1073 file-name specifies the name of a PEM-format
1074 file containing the user's certificate. If
1075 key-file-name is not specified, the user's
1076 private key is expected to be in file-name as
1077 well. Otherwise, key-file-name is the name of
1078 the file containing the private key.
1079
1080
1081 pkinit_anchors
1082 pkinit_pool
1083 file-name is assumed to be the name of an
1084 OpenSSL-style ca-bundle file. The ca-bundle
1085 file should be base-64 encoded.
1086
1087
1088
1089 DIR:directory-name
1090
1091 This option has context-specific behavior.
1092
1093 pkinit_identities
1094 directory-name specifies a directory with
1095 files named *.crt and *.key, where the first
1096 part of the file name is the same for matching
1097 pairs of certificate and private key files.
1098 When a file with a name ending with .crt is
1099 found, a matching file ending with .key is
1100 assumed to contain the private key. If no such
1101 file is found, then the certificate in the
1102 .crt is not used.
1103
1104
1105 pkinit_anchors
1106 pkinit_pool
1107 directory-name is assumed to be an OpenSSL-
1108 style hashed CA directory where each CA cert
1109 is stored in a file named hash-of-ca-cert.#.
1110 This infrastructure is encouraged, but all
1111 files in the directory are examined and if
1112 they contain certificates (in PEM format),
1113 they are used.
1114
1115
1116
1117 PKCS12:pkcs12-file-name
1118
1119 pkcs12-file-name is the name of a PKCS #12 format file, containing
1120 the user's certificate and private key.
1121
1122
1123 PKCS11:[slotid=slot-id][:token=token-label][:cert id=cert-
1124 id][:certlabel=cert-label]
1125
1126 All keyword/values are optional. PKCS11 modules (for example,
1127 opensc-pkcs11.so) must be installed as a crypto provider under
1128 libpkcs11(3LIB). slotid= and/or token= can be specified to force
1129 the use of a particular smart card reader or token if there is more
1130 than one available. certid= and/or certlabel= can be specified to
1131 force the selection of a particular certificate on the device. See
1132 the pkinit_cert_match configuration option for more ways to select
1133 a particular certificate to use for pkinit.
1134
1135
1136 ENV:environment-variable-name
1137
1138 environment-variable-name specifies the name of an environment
1139 variable which has been set to a value conforming to one of the
1140 previous values. For example, ENV:X509_PROXY, where environment
1141 variable X509_PROXY has been set to FILE:/tmp/my_proxy.pem.
1142
1143
1144 The [dbmodules] Section
1145 This section consists of relations that provide configuration
1146 information for plug-in modules. In particular, the relations describe
1147 the configuration for LDAP KDB plug-in. Use of the db2 KDB plug-in is
1148 the default behavior and that this section does not need to be filled
1149 out in that case.
1150
1151 db_library
1152
1153 Name of the plug-in library. To use the LDAP KDB plug-in the name
1154 must be kdb_ldap. The default value is db2.
1155
1156
1157 db_module_dir
1158
1159 Path to the plug-in libraries. The default is /usr/lib/krb5.
1160
1161
1162 ldap_cert_path
1163
1164 Path to the Network Security Services (NSS) trusted database for an
1165 SSL connection. This is a required parameter when using the LDAP
1166 KDB plug-in.
1167
1168
1169 ldap_conns_per_server
1170
1171 Number of connections per LDAP instance. The default is 5.
1172
1173
1174 ldap_kadmind_dn
1175
1176 Bind DN for kadmind. This specifies the DN that the kadmind service
1177 uses when binding to the LDAP Directory Server. The password for
1178 this bind DN should be in the ldap_service_password_file.
1179
1180
1181 ldap_kdc_dn
1182
1183 Bind DN for a Key Distribution Center (KDC). This specifies the DN
1184 that the krb5kdc service use when binding to the LDAP Directory
1185 Server. The password for this bind DN should be in the
1186 ldap_service_password_file.
1187
1188
1189 ldap_servers
1190
1191 List of LDAP directory servers in URI format. Use of either of the
1192 following is acceptable.
1193
1194 ldap://<ds hostname>:<SSL port>
1195 ldap://<ds hostname>
1196
1197
1198 Each server URI should be separated by whitespace.
1199
1200
1201 ldap_service_password_file
1202
1203 File containing stashed passwords used by the KDC when binding to
1204 the LDAP Directory Server. The default is /var/krb5/service_passwd.
1205 This file is created using kdb5_ldap_util(1M).
1206
1207
1208 ldap_ssl_port
1209
1210 Port number for SSL connection with directory server. The default
1211 is 389.
1212
1213
1214 EXAMPLES
1215 Example 1 Sample File
1216
1217
1218 The following is an example of a generic krb5.conf file:
1219
1220
1221 [libdefaults]
1222 default_realm = ATHENA.MIT.EDU
1223 default_tkt_enctypes = des-cbc-crc
1224 default_tgs_enctypes = des-cbc-crc
1225
1226 [realms]
1227 ATHENA.MIT.EDU = {
1228 kdc = kerberos.mit.edu
1229 kdc = kerberos-1.mit.edu
1230 kdc = kerberos-2.mit.edu
1231 admin_server = kerberos.mit.edu
1232 auth_to_local_realm = KRBDEV.ATHENA.MIT.EDU
1233 }
1234
1235 FUBAR.ORG = {
1236 kdc = kerberos.fubar.org
1237 kdc = kerberos-1.fubar.org
1238 admin_server = kerberos.fubar.org
1239 }
1240
1241 [domain_realm]
1242 .mit.edu = ATHENA.MIT.EDU
1243 mit.edu = ATHENA.MIT.EDU
1244
1245
1246
1247 Example 2 KDC Using the LDAP KDB plug-in, realms and dbmodules Sections
1248
1249
1250 The following is an example of the realms and dbmodules sections of a
1251 Kerberos configuration file when the KDC is using the LDAP KDB plug-in.
1252
1253
1254 [realms]
1255 SUN.COM = {
1256 kdc = kc-umpk-01.athena.mit.edu
1257 kdc = kc-umpk-02.athena.mit.edu
1258 admin_server = kc-umpk-01.athena.mit.edu
1259 database_module = LDAP
1260 }
1261
1262 [dbmodules]
1263 LDAP = {
1264 db_library = kdb_ldap
1265 ldap_kerberos_container_dn = "cn=krbcontainer,dc=mit,dc=edu"
1266 ldap_kdc_dn = "cn=kdc service,ou=profile,dc=mit,dc=edu"
1267 ldap_kadmind_dn = "cn=kadmin service,ou=profile,dc=mit,dc=edu"
1268 ldap_cert_path = /var/ldap
1269 ldap_servers = ldaps://ds.mit.edu
1270 }
1271
1272
1273
1274 FILES
1275 /var/krb5/kdc.log
1276
1277 KDC logging file
1278
1279
1280 ATTRIBUTES
1281 See attributes(5) for descriptions of the following attributes:
1282
1283
1284
1285
1286 +--------------------+-----------------+
1287 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
1288 +--------------------+-----------------+
1289 |Interface Stability | See below. |
1290 +--------------------+-----------------+
1291
1292
1293 All of the keywords are Committed, except for the PKINIT keywords,
1294 which are Volatile.
1295
1296 SEE ALSO
1297 kinit(1), rcp(1), rdist(1), rlogin(1), rsh(1), telnet(1), syslog(3C),
1298 attributes(5), kerberos(5), regex(5)
1299
1300 NOTES
1301 If the krb5.conf file is not formatted properly, the telnet command
1302 fails. However, the dtlogin and login commands still succeed, even if
1303 the krb5.conf file is specified as required for the commands. If this
1304 occurs, the following error message is displayed:
1305
1306 Error initializing krb5: Improper format of item
1307
1308
1309
1310
1311 To bypass any other problems that might occur, you should fix the file
1312 as soon as possible.
1313
1314
1315 The max_life and max_renewable_life options are obsolete and is removed
1316 in a future release of the Solaris operating system.
1317
1318
1319
1320 May 16, 2020 KRB5.CONF(4)