crypto/heimdal/lib/krb5/krb5.conf.5

   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: krb5.conf.5 15514 2005-06-23 18:43:34Z lha $
  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
  43 The
  44 .Nm
  45 file specifies several configuration parameters for the Kerberos 5
  46 library, as well as for some programs.
  47 .Pp
  48 The file consists of one or more sections, containing a number of
  49 bindings.
  50 The value of each binding can be either a string or a list of other
  51 bindings.
  52 The grammar looks like:
  53 .Bd -literal -offset indent
  54 file:
  55         /* empty */
  56         sections
  57
  58 sections:
  59         section sections
  60         section
  61
  62 section:
  63         '[' section_name ']' bindings
  64
  65 section_name:
  66         STRING
  67
  68 bindings:
  69         binding bindings
  70         binding
  71
  72 binding:
  73         name '=' STRING
  74         name '=' '{' bindings '}'
  75
  76 name:
  77         STRING
  78
  79 .Ed
  80 .Li STRINGs
  81 consists of one or more non-whitespace characters.
  82 .Pp
  83 STRINGs that are specified later in this man-page uses the following
  84 notation.
  85 .Bl -tag -width "xxx" -offset indent
  86 .It boolean
  87 values can be either yes/true or no/false.
  88 .It time
  89 values can be a list of year, month, day, hour, min, second.
  90 Example: 1 month 2 days 30 min.
  91 If no unit is given, seconds is assumed.
  92 .It etypes
  93 valid encryption types are: des-cbc-crc, des-cbc-md4, des-cbc-md5,
  94 des3-cbc-sha1, arcfour-hmac-md5, aes128-cts-hmac-sha1-96, and
  95 aes256-cts-hmac-sha1-96 .
  96 .It address
  97 an address can be either a IPv4 or a IPv6 address.
  98 .El
  99 .Pp
 100 Currently recognised sections and bindings are:
 101 .Bl -tag -width "xxx" -offset indent
 102 .It Li [appdefaults]
 103 Specifies the default values to be used for Kerberos applications.
 104 You can specify defaults per application, realm, or a combination of
 105 these.
 106 The 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
 118 The supported options are:
 119 .Bl -tag -width "xxx" -offset indent
 120 .It Li forwardable = Va boolean
 121 When obtaining initial credentials, make the credentials forwardable.
 122 .It Li proxiable = Va boolean
 123 When obtaining initial credentials, make the credentials proxiable.
 124 .It Li no-addresses = Va boolean
 125 When obtaining initial credentials, request them for an empty set of
 126 addresses, making the tickets valid from any address.
 127 .It Li ticket_lifetime = Va time
 128 Default ticket lifetime.
 129 .It Li renew_lifetime = Va time
 130 Default renewable ticket lifetime.
 131 .It Li encrypt = Va boolean
 132 Use encryption, when available.
 133 .It Li forward = Va boolean
 134 Forward credentials to remote host (for
 135 .Xr rsh 1 ,
 136 .Xr telnet 1 ,
 137 etc).
 138 .El
 139 .It Li [libdefaults]
 140 .Bl -tag -width "xxx" -offset indent
 141 .It Li default_realm = Va REALM
 142 Default realm to use, this is also known as your
 143 .Dq local realm .
 144 The default is the result of
 145 .Fn krb5_get_host_realm "local hostname" .
 146 .It Li clockskew = Va time
 147 Maximum time differential (in seconds) allowed when comparing
 148 times.
 149 Default is 300 seconds (five minutes).
 150 .It Li kdc_timeout = Va time
 151 Maximum time to wait for a reply from the kdc, default is 3 seconds.
 152 .It Li v4_name_convert
 153 .It Li v4_instance_resolve
 154 These are described in the
 155 .Xr krb5_425_conv_principal  3
 156 manual page.
 157 .It Li capath = {
 158 .Bl -tag -width "xxx" -offset indent
 159 .It Va destination-realm Li = Va next-hop-realm
 160 .It ...
 161 .It Li }
 162 .El
 163 This is deprecated, see the
 164 .Li capaths
 165 section below.
 166 .It Li default_cc_name = Va ccname
 167 the default credentials cache name.
 168 The string can contain variables that are expanded on runtime.
 169 Only support variable now is
 170 .Li %{uid}
 171 that expands to the current user id.
 172 .It Li default_etypes = Va etypes ...
 173 A list of default encryption types to use.
 174 .It Li default_etypes_des = Va etypes ...
 175 A list of default encryption types to use when requesting a DES credential.
 176 .It Li default_keytab_name = Va keytab
 177 The keytab to use if no other is specified, default is
 178 .Dq FILE:/etc/krb5.keytab .
 179 .It Li dns_lookup_kdc = Va boolean
 180 Use DNS SRV records to lookup KDC services location.
 181 .It Li dns_lookup_realm = Va boolean
 182 Use DNS TXT records to lookup domain to realm mappings.
 183 .It Li kdc_timesync = Va boolean
 184 Try to keep track of the time differential between the local machine
 185 and the KDC, and then compensate for that when issuing requests.
 186 .It Li max_retries = Va number
 187 The max number of times to try to contact each KDC.
 188 .It Li large_msg_size = Va number
 189 The threshold where protocols with tiny maximum message sizes are not
 190 considered usable to send messages to the KDC.
 191 .It Li ticket_lifetime = Va time
 192 Default ticket lifetime.
 193 .It Li renew_lifetime = Va time
 194 Default renewable ticket lifetime.
 195 .It Li forwardable = Va boolean
 196 When obtaining initial credentials, make the credentials forwardable.
 197 This option is also valid in the [realms] section.
 198 .It Li proxiable = Va boolean
 199 When obtaining initial credentials, make the credentials proxiable.
 200 This option is also valid in the [realms] section.
 201 .It Li verify_ap_req_nofail = Va boolean
 202 If enabled, failure to verify credentials against a local key is a
 203 fatal error.
 204 The application has to be able to read the corresponding service key
 205 for this to work.
 206 Some applications, like
 207 .Xr su 1 ,
 208 enable this option unconditionally.
 209 .It Li warn_pwexpire = Va time
 210 How soon to warn for expiring password.
 211 Default is seven days.
 212 .It Li http_proxy = Va proxy-spec
 213 A HTTP-proxy to use when talking to the KDC via HTTP.
 214 .It Li dns_proxy = Va proxy-spec
 215 Enable using DNS via HTTP.
 216 .It Li extra_addresses = Va address ...
 217 A list of addresses to get tickets for along with all local addresses.
 218 .It Li time_format = Va string
 219 How to print time strings in logs, this string is passed to
 220 .Xr strftime 3 .
 221 .It Li date_format = Va string
 222 How to print date strings in logs, this string is passed to
 223 .Xr strftime 3 .
 224 .It Li log_utc = Va boolean
 225 Write log-entries using UTC instead of your local time zone.
 226 .It Li scan_interfaces = Va boolean
 227 Scan all network interfaces for addresses, as opposed to simply using
 228 the address associated with the system's host name.
 229 .It Li fcache_version = Va int
 230 Use file credential cache format version specified.
 231 .It Li krb4_get_tickets = Va boolean
 232 Also get Kerberos 4 tickets in
 233 .Nm kinit ,
 234 .Nm login ,
 235 and other programs.
 236 This option is also valid in the [realms] section.
 237 .It Li fcc-mit-ticketflags = Va boolean
 238 Use MIT compatible format for file credential cache.
 239 It's the field ticketflags that is stored in reverse bit order for
 240 older than Heimdal 0.7.
 241 Setting this flag to
 242 .Dv TRUE
 243 make it store the MIT way, this is default for Heimdal 0.7.
 244 .El
 245 .It Li [domain_realm]
 246 This is a list of mappings from DNS domain to Kerberos realm.
 247 Each binding in this section looks like:
 248 .Pp
 249 .Dl domain = realm
 250 .Pp
 251 The domain can be either a full name of a host or a trailing
 252 component, in the latter case the domain-string should start with a
 253 period.
 254 The trailing component only matches hosts that are in the same domain, ie
 255 .Dq .example.com
 256 matches
 257 .Dq foo.example.com ,
 258 but not
 259 .Dq foo.test.example.com .
 260 .Pp
 261 The realm may be the token `dns_locate', in which case the actual
 262 realm will be determined using DNS (independently of the setting
 263 of the `dns_lookup_realm' option).
 264 .It Li [realms]
 265 .Bl -tag -width "xxx" -offset indent
 266 .It Va REALM Li = {
 267 .Bl -tag -width "xxx" -offset indent
 268 .It Li kdc = Va [service/]host[:port]
 269 Specifies a list of kdcs for this realm.
 270 If the optional
 271 .Va port
 272 is absent, the
 273 default value for the
 274 .Dq kerberos/udp
 275 .Dq kerberos/tcp ,
 276 and
 277 .Dq http/tcp
 278 port (depending on service) will be used.
 279 The kdcs will be used in the order that they are specified.
 280 .Pp
 281 The optional
 282 .Va service
 283 specifies over what medium the kdc should be
 284 contacted.
 285 Possible services are
 286 .Dq udp ,
 287 .Dq tcp ,
 288 and
 289 .Dq http .
 290 Http can also be written as
 291 .Dq http:// .
 292 Default service is
 293 .Dq udp
 294 and
 295 .Dq tcp .
 296 .It Li admin_server = Va host[:port]
 297 Specifies the admin server for this realm, where all the modifications
 298 to the database are performed.
 299 .It Li kpasswd_server = Va host[:port]
 300 Points to the server where all the password changes are performed.
 301 If there is no such entry, the kpasswd port on the admin_server host
 302 will be tried.
 303 .It Li krb524_server = Va host[:port]
 304 Points to the server that does 524 conversions.
 305 If it is not mentioned, the krb524 port on the kdcs will be tried.
 306 .It Li v4_instance_convert
 307 .It Li v4_name_convert
 308 .It Li default_domain
 309 See
 310 .Xr krb5_425_conv_principal 3 .
 311 .It Li tgs_require_subkey
 312 a boolan variable that defaults to false.
 313 Old DCE secd (pre 1.1) might need this to be true.
 314 .El
 315 .It Li }
 316 .El
 317 .It Li [capaths]
 318 .Bl -tag -width "xxx" -offset indent
 319 .It Va client-realm Li = {
 320 .Bl -tag -width "xxx" -offset indent
 321 .It Va server-realm Li = Va hop-realm ...
 322 This serves two purposes. First the first listed
 323 .Va hop-realm
 324 tells a client which realm it should contact in order to ultimately
 325 obtain credentials for a service in the
 326 .Va server-realm .
 327 Secondly, it tells the KDC (and other servers) which realms are
 328 allowed in a multi-hop traversal from
 329 .Va client-realm
 330 to
 331 .Va server-realm .
 332 Except for the client case, the order of the realms are not important.
 333 .El
 334 .It Va }
 335 .El
 336 .It Li [logging]
 337 .Bl -tag -width "xxx" -offset indent
 338 .It Va entity Li = Va destination
 339 Specifies that
 340 .Va entity
 341 should use the specified
 342 .Li destination
 343 for logging.
 344 See the
 345 .Xr krb5_openlog 3
 346 manual page for a list of defined destinations.
 347 .El
 348 .It Li [kdc]
 349 .Bl -tag -width "xxx" -offset indent
 350 .It Li database Li = {
 351 .Bl -tag -width "xxx" -offset indent
 352 .It Li dbname Li = Va DATABASENAME
 353 Use this database for this realm.
 354 See the info documetation how to configure diffrent database backends.
 355 .It Li realm Li = Va REALM
 356 Specifies the realm that will be stored in this database.
 357 It realm isn't set, it will used as the default database, there can
 358 only be one entry that doesn't have a
 359 .Li realm
 360 stanza.
 361 .It Li mkey_file Li = Pa FILENAME
 362 Use this keytab file for the master key of this database.
 363 If not specified
 364 .Va DATABASENAME Ns .mkey
 365 will be used.
 366 .It Li acl_file Li = PA FILENAME
 367 Use this file for the ACL list of this database.
 368 .It Li log_file Li = Pa FILENAME
 369 Use this file as the log of changes performed to the database.
 370 This file is used by
 371 .Nm ipropd-master
 372 for propagating changes to slaves.
 373 .El
 374 .It Li }
 375 .It Li max-request = Va SIZE
 376 Maximum size of a kdc request.
 377 .It Li require-preauth = Va BOOL
 378 If set pre-authentication is required.
 379 Since krb4 requests are not pre-authenticated they will be rejected.
 380 .It Li ports = Va "list of ports"
 381 List of ports the kdc should listen to.
 382 .It Li addresses = Va "list of interfaces"
 383 List of addresses the kdc should bind to.
 384 .It Li enable-kerberos4 = Va BOOL
 385 Turn on Kerberos 4 support.
 386 .It Li v4-realm = Va REALM
 387 To what realm v4 requests should be mapped.
 388 .It Li enable-524 = Va BOOL
 389 Should the Kerberos 524 converting facility be turned on.
 390 Default is the same as
 391 .Va enable-kerberos4 .
 392 .It Li enable-http = Va BOOL
 393 Should the kdc answer kdc-requests over http.
 394 .It Li enable-kaserver = Va BOOL
 395 If this kdc should emulate the AFS kaserver.
 396 .It Li check-ticket-addresses = Va BOOL
 397 Verify the addresses in the tickets used in tgs requests.
 398 .\" XXX
 399 .It Li allow-null-ticket-addresses = Va BOOL
 400 Allow address-less tickets.
 401 .\" XXX
 402 .It Li allow-anonymous = Va BOOL
 403 If the kdc is allowed to hand out anonymous tickets.
 404 .It Li encode_as_rep_as_tgs_rep = Va BOOL
 405 Encode as-rep as tgs-rep tobe compatible with mistakes older DCE secd did.
 406 .\" XXX
 407 .It Li kdc_warn_pwexpire = Va TIME
 408 The time before expiration that the user should be warned that her
 409 password is about to expire.
 410 .It Li logging = Va Logging
 411 What type of logging the kdc should use, see also [logging]/kdc.
 412 .It Li use_2b = {
 413 .Bl -tag -width "xxx" -offset indent
 414 .It Va principal Li = Va BOOL
 415 boolean value if the 524 daemon should return AFS 2b tokens for
 416 .Fa principal .
 417 .It ...
 418 .El
 419 .It Li }
 420 .It Li hdb-ldap-structural-object Va structural object
 421 If the LDAP backend is used for storing principals, this is the
 422 structural object that will be used when creating and when reading
 423 objects.
 424 The default value is account .
 425 .It Li hdb-ldap-create-base Va creation dn
 426 is the dn that will be appended to the principal when creating entries.
 427 Default value is the search dn.
 428 .El
 429 .It Li [kadmin]
 430 .Bl -tag -width "xxx" -offset indent
 431 .It Li require-preauth = Va BOOL
 432 If pre-authentication is required to talk to the kadmin server.
 433 .It Li password_lifetime = Va time
 434 If a principal already have its password set for expiration, this is
 435 the time it will be valid for after a change.
 436 .It Li default_keys = Va keytypes...
 437 For each entry in
 438 .Va default_keys
 439 try to parse it as a sequence of
 440 .Va etype:salttype:salt
 441 syntax of this if something like:
 442 .Pp
 443 [(des|des3|etype):](pw-salt|afs3-salt)[:string]
 444 .Pp
 445 If
 446 .Ar etype
 447 is omitted it means everything, and if string is omitted it means the
 448 default salt string (for that principal and encryption type).
 449 Additional special values of keytypes are:
 450 .Bl -tag -width "xxx" -offset indent
 451 .It Li v5
 452 The Kerberos 5 salt
 453 .Va pw-salt
 454 .It Li v4
 455 The Kerberos 4 salt
 456 .Va des:pw-salt:
 457 .El
 458 .It Li use_v4_salt = Va BOOL
 459 When true, this is the same as
 460 .Pp
 461 .Va default_keys = Va des3:pw-salt Va v4
 462 .Pp
 463 and is only left for backwards compatibility.
 464 .El
 465 .It Li [password-quality]
 466 Check the Password quality assurance in the info documentation for
 467 more information.
 468 .Bl -tag -width "xxx" -offset indent
 469 .It Li check_library = Va library-name
 470 Library name that contains the password check_function
 471 .It Li check_function = Va function-name
 472 Function name for checking passwords in check_library
 473 .It Li policy_libraries = Va library1 ... libraryN
 474 List of libraries that can do password policy checks
 475 .It Li policies = Va policy1 ... policyN
 476 List of policy names to apply to the password. Builtin policies are
 477 among other minimum-length, character-class, external-check.
 478 .El
 479 .El
 480 .Sh ENVIRONMENT
 481 .Ev KRB5_CONFIG
 482 points to the configuration file to read.
 483 .Sh FILES
 484 .Bl -tag -width "/etc/krb5.conf"
 485 .It Pa /etc/krb5.conf
 486 configuration file for Kerberos 5.
 487 .El
 488 .Sh EXAMPLES
 489 .Bd -literal -offset indent
 490 [libdefaults]
 491         default_realm = FOO.SE
 492 [domain_realm]
 493         .foo.se = FOO.SE
 494         .bar.se = FOO.SE
 495 [realms]
 496         FOO.SE = {
 497                 kdc = kerberos.foo.se
 498                 v4_name_convert = {
 499                         rcmd = host
 500                 }
 501                 v4_instance_convert = {
 502                         xyz = xyz.bar.se
 503                 }
 504                 default_domain = foo.se
 505         }
 506 [logging]
 507         kdc = FILE:/var/heimdal/kdc.log
 508         kdc = SYSLOG:INFO
 509         default = SYSLOG:INFO:USER
 510 .Ed
 511 .Sh DIAGNOSTICS
 512 Since
 513 .Nm
 514 is read and parsed by the krb5 library, there is not a lot of
 515 opportunities for programs to report parsing errors in any useful
 516 format.
 517 To help overcome this problem, there is a program
 518 .Nm verify_krb5_conf
 519 that reads
 520 .Nm
 521 and tries to emit useful diagnostics from parsing errors.
 522 Note that this program does not have any way of knowing what options
 523 are actually used and thus cannot warn about unknown or misspelled
 524 ones.
 525 .Sh SEE ALSO
 526 .Xr kinit 1 ,
 527 .Xr krb5_425_conv_principal 3 ,
 528 .Xr krb5_openlog 3 ,
 529 .Xr strftime 3 ,
 530 .Xr verify_krb5_conf 8