xref: /freebsd/crypto/heimdal/lib/krb5/krb5.conf.5 (revision f4b792fa6754e42df78d3ebff8c919f81d051f7a)
1.\" Copyright (c) 1999 - 2005 Kungliga Tekniska Högskolan
2.\" (Royal Institute of Technology, Stockholm, Sweden).
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\"
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\"
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" 3. Neither the name of the Institute nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" $Id$
33.\"
34.Dd May  4, 2005
35.Dt KRB5.CONF 5
36.Os HEIMDAL
37.Sh NAME
38.Nm krb5.conf
39.Nd configuration file for Kerberos 5
40.Sh SYNOPSIS
41.In krb5.h
42.Sh DESCRIPTION
43The
44.Nm
45file specifies several configuration parameters for the Kerberos 5
46library, as well as for some programs.
47.Pp
48The file consists of one or more sections, containing a number of
49bindings.
50The value of each binding can be either a string or a list of other
51bindings.
52The grammar looks like:
53.Bd -literal -offset indent
54file:
55	/* empty */
56	sections
57
58sections:
59	section sections
60	section
61
62section:
63	'[' section_name ']' bindings
64
65section_name:
66	STRING
67
68bindings:
69	binding bindings
70	binding
71
72binding:
73	name '=' STRING
74	name '=' '{' bindings '}'
75
76name:
77	STRING
78
79.Ed
80.Li STRINGs
81consists of one or more non-whitespace characters.
82.Pp
83STRINGs that are specified later in this man-page uses the following
84notation.
85.Bl -tag -width "xxx" -offset indent
86.It boolean
87values can be either yes/true or no/false.
88.It time
89values can be a list of year, month, day, hour, min, second.
90Example: 1 month 2 days 30 min.
91If no unit is given, seconds is assumed.
92.It etypes
93valid encryption types are: des-cbc-crc, des-cbc-md4, des-cbc-md5,
94des3-cbc-sha1, arcfour-hmac-md5, aes128-cts-hmac-sha1-96, and
95aes256-cts-hmac-sha1-96 .
96.It address
97an address can be either a IPv4 or a IPv6 address.
98.El
99.Pp
100Currently recognised sections and bindings are:
101.Bl -tag -width "xxx" -offset indent
102.It Li [appdefaults]
103Specifies the default values to be used for Kerberos applications.
104You can specify defaults per application, realm, or a combination of
105these.
106The preference order is:
107.Bl -enum -compact
108.It
109.Va application Va realm Va option
110.It
111.Va application Va option
112.It
113.Va realm Va option
114.It
115.Va option
116.El
117.Pp
118The supported options are:
119.Bl -tag -width "xxx" -offset indent
120.It Li forwardable = Va boolean
121When obtaining initial credentials, make the credentials forwardable.
122.It Li proxiable = Va boolean
123When obtaining initial credentials, make the credentials proxiable.
124.It Li no-addresses = Va boolean
125When obtaining initial credentials, request them for an empty set of
126addresses, making the tickets valid from any address.
127.It Li ticket_lifetime = Va time
128Default ticket lifetime.
129.It Li renew_lifetime = Va time
130Default renewable ticket lifetime.
131.It Li encrypt = Va boolean
132Use encryption, when available.
133.It Li forward = Va boolean
134Forward credentials to remote host (for
135.Xr rsh 1 ,
136.Xr telnet 1 ,
137etc).
138.El
139.It Li [libdefaults]
140.Bl -tag -width "xxx" -offset indent
141.It Li default_realm = Va REALM
142Default realm to use, this is also known as your
143.Dq local realm .
144The default is the result of
145.Fn krb5_get_host_realm "local hostname" .
146.It Li allow_weak_crypto = Va boolean
147is weaks crypto algorithms allowed to be used, among others, DES is
148considered weak.
149.It Li clockskew = Va time
150Maximum time differential (in seconds) allowed when comparing
151times.
152Default is 300 seconds (five minutes).
153.It Li kdc_timeout = Va time
154Maximum time to wait for a reply from the kdc, default is 3 seconds.
155.It Li v4_name_convert
156.It Li v4_instance_resolve
157These are described in the
158.Xr krb5_425_conv_principal  3
159manual page.
160.It Li capath = {
161.Bl -tag -width "xxx" -offset indent
162.It Va destination-realm Li = Va next-hop-realm
163.It ...
164.It Li }
165.El
166This is deprecated, see the
167.Li capaths
168section below.
169.It Li default_cc_type = Va cctype
170sets the default credentials type.
171.It Li default_cc_name = Va ccname
172the default credentials cache name.
173If you want to change the type only use
174.Li default_cc_type .
175The string can contain variables that are expanded on runtime.
176Only support variable now is
177.Li %{uid}
178that expands to the current user id.
179.It Li default_etypes = Va etypes ...
180A list of default encryption types to use. (Default: all enctypes if
181allow_weak_crypto = TRUE, else all enctypes except single DES enctypes.)
182.It Li default_as_etypes = Va etypes ...
183A list of default encryption types to use in AS requests.  (Default: the
184value of default_etypes.)
185.It Li default_tgs_etypes = Va etypes ...
186A list of default encryption types to use in TGS requests.  (Default:
187the value of default_etypes.)
188.It Li default_etypes_des = Va etypes ...
189A list of default encryption types to use when requesting a DES credential.
190.It Li default_keytab_name = Va keytab
191The keytab to use if no other is specified, default is
192.Dq FILE:/etc/krb5.keytab .
193.It Li dns_lookup_kdc = Va boolean
194Use DNS SRV records to lookup KDC services location.
195.It Li dns_lookup_realm = Va boolean
196Use DNS TXT records to lookup domain to realm mappings.
197.It Li kdc_timesync = Va boolean
198Try to keep track of the time differential between the local machine
199and the KDC, and then compensate for that when issuing requests.
200.It Li max_retries = Va number
201The max number of times to try to contact each KDC.
202.It Li large_msg_size = Va number
203The threshold where protocols with tiny maximum message sizes are not
204considered usable to send messages to the KDC.
205.It Li ticket_lifetime = Va time
206Default ticket lifetime.
207.It Li renew_lifetime = Va time
208Default renewable ticket lifetime.
209.It Li forwardable = Va boolean
210When obtaining initial credentials, make the credentials forwardable.
211This option is also valid in the [realms] section.
212.It Li proxiable = Va boolean
213When obtaining initial credentials, make the credentials proxiable.
214This option is also valid in the [realms] section.
215.It Li verify_ap_req_nofail = Va boolean
216If enabled, failure to verify credentials against a local key is a
217fatal error.
218The application has to be able to read the corresponding service key
219for this to work.
220Some applications, like
221.Xr su 1 ,
222enable this option unconditionally.
223.It Li warn_pwexpire = Va time
224How soon to warn for expiring password.
225Default is seven days.
226.It Li http_proxy = Va proxy-spec
227A HTTP-proxy to use when talking to the KDC via HTTP.
228.It Li dns_proxy = Va proxy-spec
229Enable using DNS via HTTP.
230.It Li extra_addresses = Va address ...
231A list of addresses to get tickets for along with all local addresses.
232.It Li time_format = Va string
233How to print time strings in logs, this string is passed to
234.Xr strftime 3 .
235.It Li date_format = Va string
236How to print date strings in logs, this string is passed to
237.Xr strftime 3 .
238.It Li log_utc = Va boolean
239Write log-entries using UTC instead of your local time zone.
240.It Li scan_interfaces = Va boolean
241Scan all network interfaces for addresses, as opposed to simply using
242the address associated with the system's host name.
243.It Li fcache_version = Va int
244Use file credential cache format version specified.
245.It Li krb4_get_tickets = Va boolean
246Also get Kerberos 4 tickets in
247.Nm kinit ,
248.Nm login ,
249and other programs.
250This option is also valid in the [realms] section.
251.It Li fcc-mit-ticketflags = Va boolean
252Use MIT compatible format for file credential cache.
253It's the field ticketflags that is stored in reverse bit order for
254older than Heimdal 0.7.
255Setting this flag to
256.Dv TRUE
257make it store the MIT way, this is default for Heimdal 0.7.
258.It Li check-rd-req-server
259If set to "ignore", the framework will ignore any the server input to
260.Xr krb5_rd_req 3 ,
261this is very useful when the GSS-API server input the
262wrong server name into the gss_accept_sec_context call.
263.El
264.It Li [domain_realm]
265This is a list of mappings from DNS domain to Kerberos realm.
266Each binding in this section looks like:
267.Pp
268.Dl domain = realm
269.Pp
270The domain can be either a full name of a host or a trailing
271component, in the latter case the domain-string should start with a
272period.
273The trailing component only matches hosts that are in the same domain, ie
274.Dq .example.com
275matches
276.Dq foo.example.com ,
277but not
278.Dq foo.test.example.com .
279.Pp
280The realm may be the token `dns_locate', in which case the actual
281realm will be determined using DNS (independently of the setting
282of the `dns_lookup_realm' option).
283.It Li [realms]
284.Bl -tag -width "xxx" -offset indent
285.It Va REALM Li = {
286.Bl -tag -width "xxx" -offset indent
287.It Li kdc = Va [service/]host[:port]
288Specifies a list of kdcs for this realm.
289If the optional
290.Va port
291is absent, the
292default value for the
293.Dq kerberos/udp
294.Dq kerberos/tcp ,
295and
296.Dq http/tcp
297port (depending on service) will be used.
298The kdcs will be used in the order that they are specified.
299.Pp
300The optional
301.Va service
302specifies over what medium the kdc should be
303contacted.
304Possible services are
305.Dq udp ,
306.Dq tcp ,
307and
308.Dq http .
309Http can also be written as
310.Dq http:// .
311Default service is
312.Dq udp
313and
314.Dq tcp .
315.It Li admin_server = Va host[:port]
316Specifies the admin server for this realm, where all the modifications
317to the database are performed.
318.It Li kpasswd_server = Va host[:port]
319Points to the server where all the password changes are performed.
320If there is no such entry, the kpasswd port on the admin_server host
321will be tried.
322.It Li krb524_server = Va host[:port]
323Points to the server that does 524 conversions.
324If it is not mentioned, the krb524 port on the kdcs will be tried.
325.It Li v4_instance_convert
326.It Li v4_name_convert
327.It Li default_domain
328See
329.Xr krb5_425_conv_principal 3 .
330.It Li tgs_require_subkey
331a boolan variable that defaults to false.
332Old DCE secd (pre 1.1) might need this to be true.
333.El
334.It Li }
335.El
336.It Li [capaths]
337.Bl -tag -width "xxx" -offset indent
338.It Va client-realm Li = {
339.Bl -tag -width "xxx" -offset indent
340.It Va server-realm Li = Va hop-realm ...
341This serves two purposes. First the first listed
342.Va hop-realm
343tells a client which realm it should contact in order to ultimately
344obtain credentials for a service in the
345.Va server-realm .
346Secondly, it tells the KDC (and other servers) which realms are
347allowed in a multi-hop traversal from
348.Va client-realm
349to
350.Va server-realm .
351Except for the client case, the order of the realms are not important.
352.El
353.It Va }
354.El
355.It Li [logging]
356.Bl -tag -width "xxx" -offset indent
357.It Va entity Li = Va destination
358Specifies that
359.Va entity
360should use the specified
361.Li destination
362for logging.
363See the
364.Xr krb5_openlog 3
365manual page for a list of defined destinations.
366.El
367.It Li [kdc]
368.Bl -tag -width "xxx" -offset indent
369.It Li database Li = {
370.Bl -tag -width "xxx" -offset indent
371.It Li dbname Li = Va DATABASENAME
372Use this database for this realm.
373See the info documetation how to configure different database backends.
374.It Li realm Li = Va REALM
375Specifies the realm that will be stored in this database.
376It realm isn't set, it will used as the default database, there can
377only be one entry that doesn't have a
378.Li realm
379stanza.
380.It Li mkey_file Li = Pa FILENAME
381Use this keytab file for the master key of this database.
382If not specified
383.Va DATABASENAME Ns .mkey
384will be used.
385.It Li acl_file Li = PA FILENAME
386Use this file for the ACL list of this database.
387.It Li log_file Li = Pa FILENAME
388Use this file as the log of changes performed to the database.
389This file is used by
390.Nm ipropd-master
391for propagating changes to slaves.
392.El
393.It Li }
394.It Li max-request = Va SIZE
395Maximum size of a kdc request.
396.It Li require-preauth = Va BOOL
397If set pre-authentication is required.
398Since krb4 requests are not pre-authenticated they will be rejected.
399.It Li ports = Va "list of ports"
400List of ports the kdc should listen to.
401.It Li addresses = Va "list of interfaces"
402List of addresses the kdc should bind to.
403.It Li enable-kerberos4 = Va BOOL
404Turn on Kerberos 4 support.
405.It Li v4-realm = Va REALM
406To what realm v4 requests should be mapped.
407.It Li enable-524 = Va BOOL
408Should the Kerberos 524 converting facility be turned on.
409Default is the same as
410.Va enable-kerberos4 .
411.It Li enable-http = Va BOOL
412Should the kdc answer kdc-requests over http.
413.It Li enable-kaserver = Va BOOL
414If this kdc should emulate the AFS kaserver.
415.It Li tgt-use-strongest-session-key = Va BOOL
416If this is TRUE then the KDC will prefer the strongest key from the
417client's AS-REQ or TGS-REQ enctype list for the ticket session key that
418is supported by the KDC and the target principal when the target
419principal is a krbtgt principal.  Else it will prefer the first key from
420the client's AS-REQ enctype list that is also supported by the KDC and
421the target principal. Defaults to TRUE.
422.It Li svc-use-strongest-session-key = Va BOOL
423Like tgt-use-strongest-session-key, but applies to the session key
424enctype of tickets for services other than krbtgt principals. Defaults
425to TRUE.
426.It Li preauth-use-strongest-session-key = Va BOOL
427If TRUE then select the strongest possible enctype from the client's
428AS-REQ for PA-ETYPE-INFO2 (i.e., for password-based pre-authentication).
429Else pick the first supported enctype from the client's AS-REQ. Defaults
430to TRUE.
431.It Li use-strongest-server-key = Va BOOL
432If TRUE then the KDC picks, for the ticket encrypted part's key, the
433first supported enctype from the target service principal's hdb entry's
434current keyset. Else the KDC picks the first supported enctype from the
435target service principal's hdb entry's current keyset. Defaults to TRUE.
436.It Li check-ticket-addresses = Va BOOL
437Verify the addresses in the tickets used in tgs requests.
438.\" XXX
439.It Li allow-null-ticket-addresses = Va BOOL
440Allow address-less tickets.
441.\" XXX
442.It Li allow-anonymous = Va BOOL
443If the kdc is allowed to hand out anonymous tickets.
444.It Li encode_as_rep_as_tgs_rep = Va BOOL
445Encode as-rep as tgs-rep tobe compatible with mistakes older DCE secd did.
446.\" XXX
447.It Li kdc_warn_pwexpire = Va TIME
448The time before expiration that the user should be warned that her
449password is about to expire.
450.It Li logging = Va Logging
451What type of logging the kdc should use, see also [logging]/kdc.
452.It Li use_2b = {
453.Bl -tag -width "xxx" -offset indent
454.It Va principal Li = Va BOOL
455boolean value if the 524 daemon should return AFS 2b tokens for
456.Fa principal .
457.It ...
458.El
459.It Li }
460.It Li hdb-ldap-structural-object Va structural object
461If the LDAP backend is used for storing principals, this is the
462structural object that will be used when creating and when reading
463objects.
464The default value is account .
465.It Li hdb-ldap-create-base Va creation dn
466is the dn that will be appended to the principal when creating entries.
467Default value is the search dn.
468.It Li enable-digest = Va BOOL
469Should the kdc answer digest requests. The default is FALSE.
470.It Li digests_allowed = Va list of digests
471Specifies the digests the kdc will reply to. The default is
472.Li ntlm-v2 .
473.El
474.It Li [kadmin]
475.Bl -tag -width "xxx" -offset indent
476.It Li require-preauth = Va BOOL
477If pre-authentication is required to talk to the kadmin server.
478.It Li password_lifetime = Va time
479If a principal already have its password set for expiration, this is
480the time it will be valid for after a change.
481.It Li default_keys = Va keytypes...
482For each entry in
483.Va default_keys
484try to parse it as a sequence of
485.Va etype:salttype:salt
486syntax of this if something like:
487.Pp
488[(des|des3|etype):](pw-salt|afs3-salt)[:string]
489.Pp
490If
491.Ar etype
492is omitted it means everything, and if string is omitted it means the
493default salt string (for that principal and encryption type).
494Additional special values of keytypes are:
495.Bl -tag -width "xxx" -offset indent
496.It Li v5
497The Kerberos 5 salt
498.Va pw-salt
499.It Li v4
500The Kerberos 4 salt
501.Va des:pw-salt:
502.El
503.It Li use_v4_salt = Va BOOL
504When true, this is the same as
505.Pp
506.Va default_keys = Va des3:pw-salt Va v4
507.Pp
508and is only left for backwards compatibility.
509.El
510.It Li [password_quality]
511Check the Password quality assurance in the info documentation for
512more information.
513.Bl -tag -width "xxx" -offset indent
514.It Li check_library = Va library-name
515Library name that contains the password check_function
516.It Li check_function = Va function-name
517Function name for checking passwords in check_library
518.It Li policy_libraries = Va library1 ... libraryN
519List of libraries that can do password policy checks
520.It Li policies = Va policy1 ... policyN
521List of policy names to apply to the password. Builtin policies are
522among other minimum-length, character-class, external-check.
523.El
524.El
525.Sh ENVIRONMENT
526.Ev KRB5_CONFIG
527points to the configuration file to read.
528.Sh FILES
529.Bl -tag -width "/etc/krb5.conf"
530.It Pa /etc/krb5.conf
531configuration file for Kerberos 5.
532.El
533.Sh EXAMPLES
534.Bd -literal -offset indent
535[libdefaults]
536	default_realm = FOO.SE
537[domain_realm]
538	.foo.se = FOO.SE
539	.bar.se = FOO.SE
540[realms]
541	FOO.SE = {
542		kdc = kerberos.foo.se
543		v4_name_convert = {
544			rcmd = host
545		}
546		v4_instance_convert = {
547			xyz = xyz.bar.se
548		}
549		default_domain = foo.se
550	}
551[logging]
552	kdc = FILE:/var/heimdal/kdc.log
553	kdc = SYSLOG:INFO
554	default = SYSLOG:INFO:USER
555.Ed
556.Sh DIAGNOSTICS
557Since
558.Nm
559is read and parsed by the krb5 library, there is not a lot of
560opportunities for programs to report parsing errors in any useful
561format.
562To help overcome this problem, there is a program
563.Nm verify_krb5_conf
564that reads
565.Nm
566and tries to emit useful diagnostics from parsing errors.
567Note that this program does not have any way of knowing what options
568are actually used and thus cannot warn about unknown or misspelled
569ones.
570.Sh SEE ALSO
571.Xr kinit 1 ,
572.Xr krb5_425_conv_principal 3 ,
573.Xr krb5_openlog 3 ,
574.Xr strftime 3 ,
575.Xr verify_krb5_conf 8
576