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$
  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 allow_weak_crypto = Va boolean
 147 is weaks crypto algorithms allowed to be used, among others, DES is
 148 considered weak.
 149 .It Li clockskew = Va time
 150 Maximum time differential (in seconds) allowed when comparing
 151 times.
 152 Default is 300 seconds (five minutes).
 153 .It Li kdc_timeout = Va time
 154 Maximum 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
 157 These are described in the
 158 .Xr krb5_425_conv_principal  3
 159 manual 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
 166 This is deprecated, see the
 167 .Li capaths
 168 section below.
 169 .It Li default_cc_type = Va cctype
 170 sets the default credentials type.
 171 .It Li default_cc_name = Va ccname
 172 the default credentials cache name.
 173 If you want to change the type only use
 174 .Li default_cc_type .
 175 The string can contain variables that are expanded on runtime.
 176 Only support variable now is
 177 .Li %{uid}
 178 that expands to the current user id.
 179 .It Li default_etypes = Va etypes ...
 180 A list of default encryption types to use. (Default: all enctypes if
 181 allow_weak_crypto = TRUE, else all enctypes except single DES enctypes.)
 182 .It Li default_as_etypes = Va etypes ...
 183 A list of default encryption types to use in AS requests.  (Default: the
 184 value of default_etypes.)
 185 .It Li default_tgs_etypes = Va etypes ...
 186 A list of default encryption types to use in TGS requests.  (Default:
 187 the value of default_etypes.)
 188 .It Li default_etypes_des = Va etypes ...
 189 A list of default encryption types to use when requesting a DES credential.
 190 .It Li default_keytab_name = Va keytab
 191 The keytab to use if no other is specified, default is
 192 .Dq FILE:/etc/krb5.keytab .
 193 .It Li dns_lookup_kdc = Va boolean
 194 Use DNS SRV records to lookup KDC services location.
 195 .It Li dns_lookup_realm = Va boolean
 196 Use DNS TXT records to lookup domain to realm mappings.
 197 .It Li kdc_timesync = Va boolean
 198 Try to keep track of the time differential between the local machine
 199 and the KDC, and then compensate for that when issuing requests.
 200 .It Li max_retries = Va number
 201 The max number of times to try to contact each KDC.
 202 .It Li large_msg_size = Va number
 203 The threshold where protocols with tiny maximum message sizes are not
 204 considered usable to send messages to the KDC.
 205 .It Li ticket_lifetime = Va time
 206 Default ticket lifetime.
 207 .It Li renew_lifetime = Va time
 208 Default renewable ticket lifetime.
 209 .It Li forwardable = Va boolean
 210 When obtaining initial credentials, make the credentials forwardable.
 211 This option is also valid in the [realms] section.
 212 .It Li proxiable = Va boolean
 213 When obtaining initial credentials, make the credentials proxiable.
 214 This option is also valid in the [realms] section.
 215 .It Li verify_ap_req_nofail = Va boolean
 216 If enabled, failure to verify credentials against a local key is a
 217 fatal error.
 218 The application has to be able to read the corresponding service key
 219 for this to work.
 220 Some applications, like
 221 .Xr su 1 ,
 222 enable this option unconditionally.
 223 .It Li warn_pwexpire = Va time
 224 How soon to warn for expiring password.
 225 Default is seven days.
 226 .It Li http_proxy = Va proxy-spec
 227 A HTTP-proxy to use when talking to the KDC via HTTP.
 228 .It Li dns_proxy = Va proxy-spec
 229 Enable using DNS via HTTP.
 230 .It Li extra_addresses = Va address ...
 231 A list of addresses to get tickets for along with all local addresses.
 232 .It Li time_format = Va string
 233 How to print time strings in logs, this string is passed to
 234 .Xr strftime 3 .
 235 .It Li date_format = Va string
 236 How to print date strings in logs, this string is passed to
 237 .Xr strftime 3 .
 238 .It Li log_utc = Va boolean
 239 Write log-entries using UTC instead of your local time zone.
 240 .It Li scan_interfaces = Va boolean
 241 Scan all network interfaces for addresses, as opposed to simply using
 242 the address associated with the system's host name.
 243 .It Li fcache_version = Va int
 244 Use file credential cache format version specified.
 245 .It Li krb4_get_tickets = Va boolean
 246 Also get Kerberos 4 tickets in
 247 .Nm kinit ,
 248 .Nm login ,
 249 and other programs.
 250 This option is also valid in the [realms] section.
 251 .It Li fcc-mit-ticketflags = Va boolean
 252 Use MIT compatible format for file credential cache.
 253 It's the field ticketflags that is stored in reverse bit order for
 254 older than Heimdal 0.7.
 255 Setting this flag to
 256 .Dv TRUE
 257 make it store the MIT way, this is default for Heimdal 0.7.
 258 .It Li check-rd-req-server
 259 If set to "ignore", the framework will ignore any the server input to
 260 .Xr krb5_rd_req 3,
 261 this is very useful when the GSS-API server input the
 262 wrong server name into the gss_accept_sec_context call.
 263 .El
 264 .It Li [domain_realm]
 265 This is a list of mappings from DNS domain to Kerberos realm.
 266 Each binding in this section looks like:
 267 .Pp
 268 .Dl domain = realm
 269 .Pp
 270 The domain can be either a full name of a host or a trailing
 271 component, in the latter case the domain-string should start with a
 272 period.
 273 The trailing component only matches hosts that are in the same domain, ie
 274 .Dq .example.com
 275 matches
 276 .Dq foo.example.com ,
 277 but not
 278 .Dq foo.test.example.com .
 279 .Pp
 280 The realm may be the token `dns_locate', in which case the actual
 281 realm will be determined using DNS (independently of the setting
 282 of 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]
 288 Specifies a list of kdcs for this realm.
 289 If the optional
 290 .Va port
 291 is absent, the
 292 default value for the
 293 .Dq kerberos/udp
 294 .Dq kerberos/tcp ,
 295 and
 296 .Dq http/tcp
 297 port (depending on service) will be used.
 298 The kdcs will be used in the order that they are specified.
 299 .Pp
 300 The optional
 301 .Va service
 302 specifies over what medium the kdc should be
 303 contacted.
 304 Possible services are
 305 .Dq udp ,
 306 .Dq tcp ,
 307 and
 308 .Dq http .
 309 Http can also be written as
 310 .Dq http:// .
 311 Default service is
 312 .Dq udp
 313 and
 314 .Dq tcp .
 315 .It Li admin_server = Va host[:port]
 316 Specifies the admin server for this realm, where all the modifications
 317 to the database are performed.
 318 .It Li kpasswd_server = Va host[:port]
 319 Points to the server where all the password changes are performed.
 320 If there is no such entry, the kpasswd port on the admin_server host
 321 will be tried.
 322 .It Li krb524_server = Va host[:port]
 323 Points to the server that does 524 conversions.
 324 If 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
 328 See
 329 .Xr krb5_425_conv_principal 3 .
 330 .It Li tgs_require_subkey
 331 a boolan variable that defaults to false.
 332 Old 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 ...
 341 This serves two purposes. First the first listed
 342 .Va hop-realm
 343 tells a client which realm it should contact in order to ultimately
 344 obtain credentials for a service in the
 345 .Va server-realm .
 346 Secondly, it tells the KDC (and other servers) which realms are
 347 allowed in a multi-hop traversal from
 348 .Va client-realm
 349 to
 350 .Va server-realm .
 351 Except 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
 358 Specifies that
 359 .Va entity
 360 should use the specified
 361 .Li destination
 362 for logging.
 363 See the
 364 .Xr krb5_openlog 3
 365 manual 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
 372 Use this database for this realm.
 373 See the info documetation how to configure different database backends.
 374 .It Li realm Li = Va REALM
 375 Specifies the realm that will be stored in this database.
 376 It realm isn't set, it will used as the default database, there can
 377 only be one entry that doesn't have a
 378 .Li realm
 379 stanza.
 380 .It Li mkey_file Li = Pa FILENAME
 381 Use this keytab file for the master key of this database.
 382 If not specified
 383 .Va DATABASENAME Ns .mkey
 384 will be used.
 385 .It Li acl_file Li = PA FILENAME
 386 Use this file for the ACL list of this database.
 387 .It Li log_file Li = Pa FILENAME
 388 Use this file as the log of changes performed to the database.
 389 This file is used by
 390 .Nm ipropd-master
 391 for propagating changes to slaves.
 392 .El
 393 .It Li }
 394 .It Li max-request = Va SIZE
 395 Maximum size of a kdc request.
 396 .It Li require-preauth = Va BOOL
 397 If set pre-authentication is required.
 398 Since krb4 requests are not pre-authenticated they will be rejected.
 399 .It Li ports = Va "list of ports"
 400 List of ports the kdc should listen to.
 401 .It Li addresses = Va "list of interfaces"
 402 List of addresses the kdc should bind to.
 403 .It Li enable-kerberos4 = Va BOOL
 404 Turn on Kerberos 4 support.
 405 .It Li v4-realm = Va REALM
 406 To what realm v4 requests should be mapped.
 407 .It Li enable-524 = Va BOOL
 408 Should the Kerberos 524 converting facility be turned on.
 409 Default is the same as
 410 .Va enable-kerberos4 .
 411 .It Li enable-http = Va BOOL
 412 Should the kdc answer kdc-requests over http.
 413 .It Li enable-kaserver = Va BOOL
 414 If this kdc should emulate the AFS kaserver.
 415 .It Li tgt-use-strongest-session-key = Va BOOL
 416 If this is TRUE then the KDC will prefer the strongest key from the
 417 client's AS-REQ or TGS-REQ enctype list for the ticket session key that
 418 is supported by the KDC and the target principal when the target
 419 principal is a krbtgt principal.  Else it will prefer the first key from
 420 the client's AS-REQ enctype list that is also supported by the KDC and
 421 the target principal. Defaults to TRUE.
 422 .It Li svc-use-strongest-session-key = Va BOOL
 423 Like tgt-use-strongest-session-key, but applies to the session key
 424 enctype of tickets for services other than krbtgt principals. Defaults
 425 to TRUE.
 426 .It Li preauth-use-strongest-session-key = Va BOOL
 427 If TRUE then select the strongest possible enctype from the client's
 428 AS-REQ for PA-ETYPE-INFO2 (i.e., for password-based pre-authentication).
 429 Else pick the first supported enctype from the client's AS-REQ. Defaults
 430 to TRUE.
 431 .It Li use-strongest-server-key = Va BOOL
 432 If TRUE then the KDC picks, for the ticket encrypted part's key, the
 433 first supported enctype from the target service principal's hdb entry's
 434 current keyset. Else the KDC picks the first supported enctype from the
 435 target service principal's hdb entry's current keyset. Defaults to TRUE.
 436 .It Li check-ticket-addresses = Va BOOL
 437 Verify the addresses in the tickets used in tgs requests.
 438 .\" XXX
 439 .It Li allow-null-ticket-addresses = Va BOOL
 440 Allow address-less tickets.
 441 .\" XXX
 442 .It Li allow-anonymous = Va BOOL
 443 If the kdc is allowed to hand out anonymous tickets.
 444 .It Li encode_as_rep_as_tgs_rep = Va BOOL
 445 Encode as-rep as tgs-rep tobe compatible with mistakes older DCE secd did.
 446 .\" XXX
 447 .It Li kdc_warn_pwexpire = Va TIME
 448 The time before expiration that the user should be warned that her
 449 password is about to expire.
 450 .It Li logging = Va Logging
 451 What 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
 455 boolean 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
 461 If the LDAP backend is used for storing principals, this is the
 462 structural object that will be used when creating and when reading
 463 objects.
 464 The default value is account .
 465 .It Li hdb-ldap-create-base Va creation dn
 466 is the dn that will be appended to the principal when creating entries.
 467 Default value is the search dn.
 468 .It Li enable-digest = Va BOOL
 469 Should the kdc answer digest requests. The default is FALSE.
 470 .It Li digests_allowed = Va list of digests
 471 Specifies 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
 477 If pre-authentication is required to talk to the kadmin server.
 478 .It Li password_lifetime = Va time
 479 If a principal already have its password set for expiration, this is
 480 the time it will be valid for after a change.
 481 .It Li default_keys = Va keytypes...
 482 For each entry in
 483 .Va default_keys
 484 try to parse it as a sequence of
 485 .Va etype:salttype:salt
 486 syntax of this if something like:
 487 .Pp
 488 [(des|des3|etype):](pw-salt|afs3-salt)[:string]
 489 .Pp
 490 If
 491 .Ar etype
 492 is omitted it means everything, and if string is omitted it means the
 493 default salt string (for that principal and encryption type).
 494 Additional special values of keytypes are:
 495 .Bl -tag -width "xxx" -offset indent
 496 .It Li v5
 497 The Kerberos 5 salt
 498 .Va pw-salt
 499 .It Li v4
 500 The Kerberos 4 salt
 501 .Va des:pw-salt:
 502 .El
 503 .It Li use_v4_salt = Va BOOL
 504 When true, this is the same as
 505 .Pp
 506 .Va default_keys = Va des3:pw-salt Va v4
 507 .Pp
 508 and is only left for backwards compatibility.
 509 .El
 510 .It Li [password_quality]
 511 Check the Password quality assurance in the info documentation for
 512 more information.
 513 .Bl -tag -width "xxx" -offset indent
 514 .It Li check_library = Va library-name
 515 Library name that contains the password check_function
 516 .It Li check_function = Va function-name
 517 Function name for checking passwords in check_library
 518 .It Li policy_libraries = Va library1 ... libraryN
 519 List of libraries that can do password policy checks
 520 .It Li policies = Va policy1 ... policyN
 521 List of policy names to apply to the password. Builtin policies are
 522 among other minimum-length, character-class, external-check.
 523 .El
 524 .El
 525 .Sh ENVIRONMENT
 526 .Ev KRB5_CONFIG
 527 points to the configuration file to read.
 528 .Sh FILES
 529 .Bl -tag -width "/etc/krb5.conf"
 530 .It Pa /etc/krb5.conf
 531 configuration 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
 557 Since
 558 .Nm
 559 is read and parsed by the krb5 library, there is not a lot of
 560 opportunities for programs to report parsing errors in any useful
 561 format.
 562 To help overcome this problem, there is a program
 563 .Nm verify_krb5_conf
 564 that reads
 565 .Nm
 566 and tries to emit useful diagnostics from parsing errors.
 567 Note that this program does not have any way of knowing what options
 568 are actually used and thus cannot warn about unknown or misspelled
 569 ones.
 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