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