| 1 |
.. _krb5.conf(5): |
| 2 |
|
| 3 |
krb5.conf |
| 4 |
========= |
| 5 |
|
| 6 |
The krb5.conf file contains Kerberos configuration information, |
| 7 |
including the locations of KDCs and admin servers for the Kerberos |
| 8 |
realms of interest, defaults for the current realm and for Kerberos |
| 9 |
applications, and mappings of hostnames onto Kerberos realms. |
| 10 |
Normally, you should install your krb5.conf file in the directory |
| 11 |
``/etc``. You can override the default location by setting the |
| 12 |
environment variable **KRB5_CONFIG**. Multiple colon-separated |
| 13 |
filenames may be specified in **KRB5_CONFIG**; all files which are |
| 14 |
present will be read. Starting in release 1.14, directory names can |
| 15 |
also be specified in **KRB5_CONFIG**; all files within the directory |
| 16 |
whose names consist solely of alphanumeric characters, dashes, or |
| 17 |
underscores will be read. |
| 18 |
|
| 19 |
|
| 20 |
Structure |
| 21 |
--------- |
| 22 |
|
| 23 |
The krb5.conf file is set up in the style of a Windows INI file. |
| 24 |
Lines beginning with '#' or ';' (possibly after initial whitespace) |
| 25 |
are ignored as comments. Sections are headed by the section name, in |
| 26 |
square brackets. Each section may contain zero or more relations, of |
| 27 |
the form:: |
| 28 |
|
| 29 |
foo = bar |
| 30 |
|
| 31 |
or:: |
| 32 |
|
| 33 |
fubar = { |
| 34 |
foo = bar |
| 35 |
baz = quux |
| 36 |
} |
| 37 |
|
| 38 |
The krb5.conf file can include other files using either of the |
| 39 |
following directives at the beginning of a line:: |
| 40 |
|
| 41 |
include FILENAME |
| 42 |
includedir DIRNAME |
| 43 |
|
| 44 |
*FILENAME* or *DIRNAME* should be an absolute path. The named file or |
| 45 |
directory must exist and be readable. Including a directory includes |
| 46 |
all files within the directory whose names consist solely of |
| 47 |
alphanumeric characters, dashes, or underscores. Starting in release |
| 48 |
1.15, files with names ending in ".conf" are also included, unless the |
| 49 |
name begins with ".". Included profile files are syntactically |
| 50 |
independent of their parents, so each included file must begin with a |
| 51 |
section header. Starting in release 1.17, files are read in |
| 52 |
alphanumeric order; in previous releases, they may be read in any |
| 53 |
order. |
| 54 |
|
| 55 |
Placing a '\*' after the closing bracket of a section name indicates |
| 56 |
that the section is *final*, meaning that if the same section appears |
| 57 |
again later, it will be ignored. A subsection can be marked as final |
| 58 |
by placing a '\*' after either the tag name or the closing brace. A |
| 59 |
relation can be marked as final by placing a '\*' after the tag name. |
| 60 |
Prior to release 1.22, only sections and subsections can be marked as |
| 61 |
final, and the flag only causes values to be ignored if they appear in |
| 62 |
later files specified in **KRB5_CONFIG**, not if they appear later |
| 63 |
within the same file or an included file. |
| 64 |
|
| 65 |
The krb5.conf file can specify that configuration should be obtained |
| 66 |
from a loadable module, rather than the file itself, using the |
| 67 |
following directive at the beginning of a line before any section |
| 68 |
headers:: |
| 69 |
|
| 70 |
module MODULEPATH:RESIDUAL |
| 71 |
|
| 72 |
*MODULEPATH* may be relative to the library path of the krb5 |
| 73 |
installation, or it may be an absolute path. *RESIDUAL* is provided |
| 74 |
to the module at initialization time. If krb5.conf uses a module |
| 75 |
directive, :ref:`kdc.conf(5)` should also use one if it exists. |
| 76 |
|
| 77 |
|
| 78 |
Sections |
| 79 |
-------- |
| 80 |
|
| 81 |
The krb5.conf file may contain the following sections: |
| 82 |
|
| 83 |
=================== ======================================================= |
| 84 |
:ref:`libdefaults` Settings used by the Kerberos V5 library |
| 85 |
:ref:`realms` Realm-specific contact information and settings |
| 86 |
:ref:`domain_realm` Maps server hostnames to Kerberos realms |
| 87 |
:ref:`capaths` Authentication paths for non-hierarchical cross-realm |
| 88 |
:ref:`appdefaults` Settings used by some Kerberos V5 applications |
| 89 |
:ref:`plugins` Controls plugin module registration |
| 90 |
=================== ======================================================= |
| 91 |
|
| 92 |
Additionally, krb5.conf may include any of the relations described in |
| 93 |
:ref:`kdc.conf(5)`, but it is not a recommended practice. |
| 94 |
|
| 95 |
.. _libdefaults: |
| 96 |
|
| 97 |
[libdefaults] |
| 98 |
~~~~~~~~~~~~~ |
| 99 |
|
| 100 |
The libdefaults section may contain any of the following relations: |
| 101 |
|
| 102 |
**allow_des3** |
| 103 |
Permit the KDC to issue tickets with des3-cbc-sha1 session keys. |
| 104 |
In future releases, this flag will allow des3-cbc-sha1 to be used |
| 105 |
at all. The default value for this tag is false. (Added in |
| 106 |
release 1.21.) |
| 107 |
|
| 108 |
**allow_rc4** |
| 109 |
Permit the KDC to issue tickets with arcfour-hmac session keys. |
| 110 |
In future releases, this flag will allow arcfour-hmac to be used |
| 111 |
at all. The default value for this tag is false. (Added in |
| 112 |
release 1.21.) |
| 113 |
|
| 114 |
**allow_weak_crypto** |
| 115 |
If this flag is set to false, then weak encryption types (as noted |
| 116 |
in :ref:`Encryption_types` in :ref:`kdc.conf(5)`) will be filtered |
| 117 |
out of the lists **default_tgs_enctypes**, |
| 118 |
**default_tkt_enctypes**, and **permitted_enctypes**. The default |
| 119 |
value for this tag is false. |
| 120 |
|
| 121 |
**canonicalize** |
| 122 |
If this flag is set to true, initial ticket requests to the KDC |
| 123 |
will request canonicalization of the client principal name, and |
| 124 |
answers with different client principals than the requested |
| 125 |
principal will be accepted. The default value is false. |
| 126 |
|
| 127 |
**ccache_type** |
| 128 |
This parameter determines the format of credential cache types |
| 129 |
created by :ref:`kinit(1)` or other programs. The default value |
| 130 |
is 4, which represents the most current format. Smaller values |
| 131 |
can be used for compatibility with very old implementations of |
| 132 |
Kerberos which interact with credential caches on the same host. |
| 133 |
|
| 134 |
**clockskew** |
| 135 |
Sets the maximum allowable amount of clockskew in seconds that the |
| 136 |
library will tolerate before assuming that a Kerberos message is |
| 137 |
invalid. The default value is 300 seconds, or five minutes. |
| 138 |
|
| 139 |
The clockskew setting is also used when evaluating ticket start |
| 140 |
and expiration times. For example, tickets that have reached |
| 141 |
their expiration time can still be used (and renewed if they are |
| 142 |
renewable tickets) if they have been expired for a shorter |
| 143 |
duration than the **clockskew** setting. |
| 144 |
|
| 145 |
**default_ccache_name** |
| 146 |
This relation specifies the name of the default credential cache. |
| 147 |
The default is |ccache|. This relation is subject to parameter |
| 148 |
expansion (see below). New in release 1.11. |
| 149 |
|
| 150 |
**default_client_keytab_name** |
| 151 |
This relation specifies the name of the default keytab for |
| 152 |
obtaining client credentials. The default is |ckeytab|. This |
| 153 |
relation is subject to parameter expansion (see below). |
| 154 |
New in release 1.11. |
| 155 |
|
| 156 |
**default_keytab_name** |
| 157 |
This relation specifies the default keytab name to be used by |
| 158 |
application servers such as sshd. The default is |keytab|. This |
| 159 |
relation is subject to parameter expansion (see below). |
| 160 |
|
| 161 |
**default_rcache_name** |
| 162 |
This relation specifies the name of the default replay cache. |
| 163 |
The default is ``dfl:``. This relation is subject to parameter |
| 164 |
expansion (see below). New in release 1.18. |
| 165 |
|
| 166 |
**default_realm** |
| 167 |
Identifies the default Kerberos realm for the client. Set its |
| 168 |
value to your Kerberos realm. If this value is not set, then a |
| 169 |
realm must be specified with every Kerberos principal when |
| 170 |
invoking programs such as :ref:`kinit(1)`. |
| 171 |
|
| 172 |
**default_tgs_enctypes** |
| 173 |
Identifies the supported list of session key encryption types that |
| 174 |
the client should request when making a TGS-REQ, in order of |
| 175 |
preference from highest to lowest. The list may be delimited with |
| 176 |
commas or whitespace. See :ref:`Encryption_types` in |
| 177 |
:ref:`kdc.conf(5)` for a list of the accepted values for this tag. |
| 178 |
Starting in release 1.18, the default value is the value of |
| 179 |
**permitted_enctypes**. For previous releases or if |
| 180 |
**permitted_enctypes** is not set, the default value is |
| 181 |
|defetypes|. |
| 182 |
|
| 183 |
Do not set this unless required for specific backward |
| 184 |
compatibility purposes; stale values of this setting can prevent |
| 185 |
clients from taking advantage of new stronger enctypes when the |
| 186 |
libraries are upgraded. |
| 187 |
|
| 188 |
**default_tkt_enctypes** |
| 189 |
Identifies the supported list of session key encryption types that |
| 190 |
the client should request when making an AS-REQ, in order of |
| 191 |
preference from highest to lowest. The format is the same as for |
| 192 |
default_tgs_enctypes. Starting in release 1.18, the default |
| 193 |
value is the value of **permitted_enctypes**. For previous |
| 194 |
releases or if **permitted_enctypes** is not set, the default |
| 195 |
value is |defetypes|. |
| 196 |
|
| 197 |
Do not set this unless required for specific backward |
| 198 |
compatibility purposes; stale values of this setting can prevent |
| 199 |
clients from taking advantage of new stronger enctypes when the |
| 200 |
libraries are upgraded. |
| 201 |
|
| 202 |
**dns_canonicalize_hostname** |
| 203 |
Indicate whether name lookups will be used to canonicalize |
| 204 |
hostnames for use in service principal names. Setting this flag |
| 205 |
to false can improve security by reducing reliance on DNS, but |
| 206 |
means that short hostnames will not be canonicalized to |
| 207 |
fully-qualified hostnames. If this option is set to ``fallback`` (new |
| 208 |
in release 1.18), DNS canonicalization will only be performed the |
| 209 |
server hostname is not found with the original name when |
| 210 |
requesting credentials. The default value is true. |
| 211 |
|
| 212 |
**dns_lookup_kdc** |
| 213 |
Indicate whether DNS SRV records should be used to locate the KDCs |
| 214 |
and other servers for a realm, if they are not listed in the |
| 215 |
krb5.conf information for the realm. (Note that the admin_server |
| 216 |
entry must be in the krb5.conf realm information in order to |
| 217 |
contact kadmind, because the DNS implementation for kadmin is |
| 218 |
incomplete.) |
| 219 |
|
| 220 |
Enabling this option does open up a type of denial-of-service |
| 221 |
attack, if someone spoofs the DNS records and redirects you to |
| 222 |
another server. However, it's no worse than a denial of service, |
| 223 |
because that fake KDC will be unable to decode anything you send |
| 224 |
it (besides the initial ticket request, which has no encrypted |
| 225 |
data), and anything the fake KDC sends will not be trusted without |
| 226 |
verification using some secret that it won't know. |
| 227 |
|
| 228 |
**dns_lookup_realm** |
| 229 |
Indicate whether DNS TXT records should be used to map hostnames |
| 230 |
to realm names for hostnames not listed in the [domain_realm] |
| 231 |
section, and to determine the default realm if **default_realm** |
| 232 |
is not set. The default value is false. |
| 233 |
|
| 234 |
**dns_uri_lookup** |
| 235 |
Indicate whether DNS URI records should be used to locate the KDCs |
| 236 |
and other servers for a realm, if they are not listed in the |
| 237 |
krb5.conf information for the realm. SRV records are used as a |
| 238 |
fallback if no URI records were found. The default value is true. |
| 239 |
New in release 1.15. |
| 240 |
|
| 241 |
**enforce_ok_as_delegate** |
| 242 |
If this flag to true, GSSAPI credential delegation will be |
| 243 |
disabled when the ``ok-as-delegate`` flag is not set in the |
| 244 |
service ticket. If this flag is false, the ``ok-as-delegate`` |
| 245 |
ticket flag is only enforced when an application specifically |
| 246 |
requests enforcement. The default value is false. |
| 247 |
|
| 248 |
**err_fmt** |
| 249 |
This relation allows for custom error message formatting. If a |
| 250 |
value is set, error messages will be formatted by substituting a |
| 251 |
normal error message for %M and an error code for %C in the value. |
| 252 |
|
| 253 |
**extra_addresses** |
| 254 |
This allows a computer to use multiple local addresses, in order |
| 255 |
to allow Kerberos to work in a network that uses NATs while still |
| 256 |
using address-restricted tickets. The addresses should be in a |
| 257 |
comma-separated list. This option has no effect if |
| 258 |
**noaddresses** is true. |
| 259 |
|
| 260 |
**forwardable** |
| 261 |
If this flag is true, initial tickets will be forwardable by |
| 262 |
default, if allowed by the KDC. The default value is false. |
| 263 |
|
| 264 |
**ignore_acceptor_hostname** |
| 265 |
When accepting GSSAPI or krb5 security contexts for host-based |
| 266 |
service principals, ignore any hostname passed by the calling |
| 267 |
application, and allow clients to authenticate to any service |
| 268 |
principal in the keytab matching the service name and realm name |
| 269 |
(if given). This option can improve the administrative |
| 270 |
flexibility of server applications on multihomed hosts, but could |
| 271 |
compromise the security of virtual hosting environments. The |
| 272 |
default value is false. New in release 1.10. |
| 273 |
|
| 274 |
**k5login_authoritative** |
| 275 |
If this flag is true, principals must be listed in a local user's |
| 276 |
k5login file to be granted login access, if a :ref:`.k5login(5)` |
| 277 |
file exists. If this flag is false, a principal may still be |
| 278 |
granted login access through other mechanisms even if a k5login |
| 279 |
file exists but does not list the principal. The default value is |
| 280 |
true. |
| 281 |
|
| 282 |
**k5login_directory** |
| 283 |
If set, the library will look for a local user's k5login file |
| 284 |
within the named directory, with a filename corresponding to the |
| 285 |
local username. If not set, the library will look for k5login |
| 286 |
files in the user's home directory, with the filename .k5login. |
| 287 |
For security reasons, .k5login files must be owned by |
| 288 |
the local user or by root. |
| 289 |
|
| 290 |
**kcm_mach_service** |
| 291 |
On macOS only, determines the name of the bootstrap service used to |
| 292 |
contact the KCM daemon for the KCM credential cache type. If the |
| 293 |
value is ``-``, Mach RPC will not be used to contact the KCM |
| 294 |
daemon. The default value is ``org.h5l.kcm``. |
| 295 |
|
| 296 |
**kcm_socket** |
| 297 |
Determines the path to the Unix domain socket used to access the |
| 298 |
KCM daemon for the KCM credential cache type. If the value is |
| 299 |
``-``, Unix domain sockets will not be used to contact the KCM |
| 300 |
daemon. The default value is |
| 301 |
``/var/run/.heim_org.h5l.kcm-socket``. |
| 302 |
|
| 303 |
**kdc_default_options** |
| 304 |
Default KDC options (Xored for multiple values) when requesting |
| 305 |
initial tickets. By default it is set to 0x00000010 |
| 306 |
(KDC_OPT_RENEWABLE_OK). |
| 307 |
|
| 308 |
**kdc_timesync** |
| 309 |
Accepted values for this relation are 1 or 0. If it is nonzero, |
| 310 |
client machines will compute the difference between their time and |
| 311 |
the time returned by the KDC in the timestamps in the tickets and |
| 312 |
use this value to correct for an inaccurate system clock when |
| 313 |
requesting service tickets or authenticating to services. This |
| 314 |
corrective factor is only used by the Kerberos library; it is not |
| 315 |
used to change the system clock. The default value is 1. |
| 316 |
|
| 317 |
**noaddresses** |
| 318 |
If this flag is true, requests for initial tickets will not be |
| 319 |
made with address restrictions set, allowing the tickets to be |
| 320 |
used across NATs. The default value is true. |
| 321 |
|
| 322 |
**permitted_enctypes** |
| 323 |
Identifies the encryption types that servers will permit for |
| 324 |
session keys and for ticket and authenticator encryption, ordered |
| 325 |
by preference from highest to lowest. Starting in release 1.18, |
| 326 |
this tag also acts as the default value for |
| 327 |
**default_tgs_enctypes** and **default_tkt_enctypes**. The |
| 328 |
default value for this tag is |defetypes|. |
| 329 |
|
| 330 |
**plugin_base_dir** |
| 331 |
If set, determines the base directory where krb5 plugins are |
| 332 |
located. The default value is the ``krb5/plugins`` subdirectory |
| 333 |
of the krb5 library directory. This relation is subject to |
| 334 |
parameter expansion (see below) in release 1.17 and later. |
| 335 |
|
| 336 |
**preferred_preauth_types** |
| 337 |
This allows you to set the preferred preauthentication types which |
| 338 |
the client will attempt before others which may be advertised by a |
| 339 |
KDC. The default value for this setting is "17, 16, 15, 14", |
| 340 |
which forces libkrb5 to attempt to use PKINIT if it is supported. |
| 341 |
|
| 342 |
**proxiable** |
| 343 |
If this flag is true, initial tickets will be proxiable by |
| 344 |
default, if allowed by the KDC. The default value is false. |
| 345 |
|
| 346 |
**qualify_shortname** |
| 347 |
If this string is set, it determines the domain suffix for |
| 348 |
single-component hostnames when DNS canonicalization is not used |
| 349 |
(either because **dns_canonicalize_hostname** is false or because |
| 350 |
forward canonicalization failed). The default value is the first |
| 351 |
search domain of the system's DNS configuration. To disable |
| 352 |
qualification of shortnames, set this relation to the empty string |
| 353 |
with ``qualify_shortname = ""``. (New in release 1.18.) |
| 354 |
|
| 355 |
**rdns** |
| 356 |
If this flag is true, reverse name lookup will be used in addition |
| 357 |
to forward name lookup to canonicalizing hostnames for use in |
| 358 |
service principal names. If **dns_canonicalize_hostname** is set |
| 359 |
to false, this flag has no effect. The default value is true. |
| 360 |
|
| 361 |
**realm_try_domains** |
| 362 |
Indicate whether a host's domain components should be used to |
| 363 |
determine the Kerberos realm of the host. The value of this |
| 364 |
variable is an integer: -1 means not to search, 0 means to try the |
| 365 |
host's domain itself, 1 means to also try the domain's immediate |
| 366 |
parent, and so forth. The library's usual mechanism for locating |
| 367 |
Kerberos realms is used to determine whether a domain is a valid |
| 368 |
realm, which may involve consulting DNS if **dns_lookup_kdc** is |
| 369 |
set. The default is not to search domain components. |
| 370 |
|
| 371 |
**renew_lifetime** |
| 372 |
(:ref:`duration` string.) Sets the default renewable lifetime |
| 373 |
for initial ticket requests. The default value is 0. |
| 374 |
|
| 375 |
**request_timeout** |
| 376 |
(:ref:`duration` string.) Sets the maximum total time for KDC and |
| 377 |
password change requests. This timeout does not affect the |
| 378 |
intervals between requests, so setting a low timeout may result in |
| 379 |
fewer requests being attempted and/or some servers not being |
| 380 |
contacted. A value of 0 indicates no specific maximum, in which |
| 381 |
case requests will time out if no server responds after several |
| 382 |
tries. The default value is 0. (New in release 1.22.) |
| 383 |
|
| 384 |
**spake_preauth_groups** |
| 385 |
A whitespace or comma-separated list of words which specifies the |
| 386 |
groups allowed for SPAKE preauthentication. The possible values |
| 387 |
are: |
| 388 |
|
| 389 |
============ ================================ |
| 390 |
edwards25519 Edwards25519 curve (:rfc:`7748`) |
| 391 |
P-256 NIST P-256 curve (:rfc:`5480`) |
| 392 |
P-384 NIST P-384 curve (:rfc:`5480`) |
| 393 |
P-521 NIST P-521 curve (:rfc:`5480`) |
| 394 |
============ ================================ |
| 395 |
|
| 396 |
The default value for the client is ``edwards25519``. The default |
| 397 |
value for the KDC is empty. New in release 1.17. |
| 398 |
|
| 399 |
**ticket_lifetime** |
| 400 |
(:ref:`duration` string.) Sets the default lifetime for initial |
| 401 |
ticket requests. The default value is 1 day. |
| 402 |
|
| 403 |
**udp_preference_limit** |
| 404 |
When sending a message to the KDC, the library will try using TCP |
| 405 |
before UDP if the size of the message is above |
| 406 |
**udp_preference_limit**. If the message is smaller than |
| 407 |
**udp_preference_limit**, then UDP will be tried before TCP. |
| 408 |
Regardless of the size, both protocols will be tried if the first |
| 409 |
attempt fails. |
| 410 |
|
| 411 |
**verify_ap_req_nofail** |
| 412 |
If this flag is true, then an attempt to verify initial |
| 413 |
credentials will fail if the client machine does not have a |
| 414 |
keytab. The default value is false. |
| 415 |
|
| 416 |
**client_aware_channel_bindings** |
| 417 |
If this flag is true, then all application protocol authentication |
| 418 |
requests will be flagged to indicate that the application supports |
| 419 |
channel bindings when operating over a secure channel. The |
| 420 |
default value is false. |
| 421 |
|
| 422 |
.. _realms: |
| 423 |
|
| 424 |
[realms] |
| 425 |
~~~~~~~~ |
| 426 |
|
| 427 |
Each tag in the [realms] section of the file is the name of a Kerberos |
| 428 |
realm. The value of the tag is a subsection with relations that |
| 429 |
define the properties of that particular realm. For each realm, the |
| 430 |
following tags may be specified in the realm's subsection: |
| 431 |
|
| 432 |
**admin_server** |
| 433 |
Identifies the host where the administration server is running. |
| 434 |
Typically, this is the primary Kerberos server. This tag must be |
| 435 |
given a value in order to communicate with the :ref:`kadmind(8)` |
| 436 |
server for the realm. |
| 437 |
|
| 438 |
**auth_to_local** |
| 439 |
This tag allows you to set a general rule for mapping principal |
| 440 |
names to local user names. It will be used if there is not an |
| 441 |
explicit mapping for the principal name that is being |
| 442 |
translated. The possible values are: |
| 443 |
|
| 444 |
**RULE:**\ *exp* |
| 445 |
The local name will be formulated from *exp*. |
| 446 |
|
| 447 |
The format for *exp* is **[**\ *n*\ **:**\ *string*\ **](**\ |
| 448 |
*regexp*\ **)s/**\ *pattern*\ **/**\ *replacement*\ **/g**. |
| 449 |
The integer *n* indicates how many components the target |
| 450 |
principal should have. If this matches, then a string will be |
| 451 |
formed from *string*, substituting the realm of the principal |
| 452 |
for ``$0`` and the *n*'th component of the principal for |
| 453 |
``$n`` (e.g., if the principal was ``johndoe/admin`` then |
| 454 |
``[2:$2$1foo]`` would result in the string |
| 455 |
``adminjohndoefoo``). If this string matches *regexp*, then |
| 456 |
the ``s//[g]`` substitution command will be run over the |
| 457 |
string. The optional **g** will cause the substitution to be |
| 458 |
global over the *string*, instead of replacing only the first |
| 459 |
match in the *string*. |
| 460 |
|
| 461 |
**DEFAULT** |
| 462 |
The principal name will be used as the local user name. If |
| 463 |
the principal has more than one component or is not in the |
| 464 |
default realm, this rule is not applicable and the conversion |
| 465 |
will fail. |
| 466 |
|
| 467 |
For example:: |
| 468 |
|
| 469 |
[realms] |
| 470 |
ATHENA.MIT.EDU = { |
| 471 |
auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/ |
| 472 |
auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$// |
| 473 |
auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/ |
| 474 |
auth_to_local = DEFAULT |
| 475 |
} |
| 476 |
|
| 477 |
would result in any principal without ``root`` or ``admin`` as the |
| 478 |
second component to be translated with the default rule. A |
| 479 |
principal with a second component of ``admin`` will become its |
| 480 |
first component. ``root`` will be used as the local name for any |
| 481 |
principal with a second component of ``root``. The exception to |
| 482 |
these two rules are any principals ``johndoe/*``, which will |
| 483 |
always get the local name ``guest``. |
| 484 |
|
| 485 |
**auth_to_local_names** |
| 486 |
This subsection allows you to set explicit mappings from principal |
| 487 |
names to local user names. The tag is the mapping name, and the |
| 488 |
value is the corresponding local user name. |
| 489 |
|
| 490 |
**default_domain** |
| 491 |
This tag specifies the domain used to expand hostnames when |
| 492 |
translating Kerberos 4 service principals to Kerberos 5 principals |
| 493 |
(for example, when converting ``rcmd.hostname`` to |
| 494 |
``host/hostname.domain``). |
| 495 |
|
| 496 |
**disable_encrypted_timestamp** |
| 497 |
If this flag is true, the client will not perform encrypted |
| 498 |
timestamp preauthentication if requested by the KDC. Setting this |
| 499 |
flag can help to prevent dictionary attacks by active attackers, |
| 500 |
if the realm's KDCs support SPAKE preauthentication or if initial |
| 501 |
authentication always uses another mechanism or always uses FAST. |
| 502 |
This flag persists across client referrals during initial |
| 503 |
authentication. This flag does not prevent the KDC from offering |
| 504 |
encrypted timestamp. New in release 1.17. |
| 505 |
|
| 506 |
**http_anchors** |
| 507 |
When KDCs and kpasswd servers are accessed through HTTPS proxies, this tag |
| 508 |
can be used to specify the location of the CA certificate which should be |
| 509 |
trusted to issue the certificate for a proxy server. If left unspecified, |
| 510 |
the system-wide default set of CA certificates is used. |
| 511 |
|
| 512 |
The syntax for values is similar to that of values for the |
| 513 |
**pkinit_anchors** tag: |
| 514 |
|
| 515 |
**FILE:** *filename* |
| 516 |
|
| 517 |
*filename* is assumed to be the name of an OpenSSL-style ca-bundle file. |
| 518 |
|
| 519 |
**DIR:** *dirname* |
| 520 |
|
| 521 |
*dirname* is assumed to be an directory which contains CA certificates. |
| 522 |
All files in the directory will be examined; if they contain certificates |
| 523 |
(in PEM format), they will be used. |
| 524 |
|
| 525 |
**ENV:** *envvar* |
| 526 |
|
| 527 |
*envvar* specifies the name of an environment variable which has been set |
| 528 |
to a value conforming to one of the previous values. For example, |
| 529 |
``ENV:X509_PROXY_CA``, where environment variable ``X509_PROXY_CA`` has |
| 530 |
been set to ``FILE:/tmp/my_proxy.pem``. |
| 531 |
|
| 532 |
**kdc** |
| 533 |
The name or address of a host running a KDC for the realm, or a |
| 534 |
UNIX domain socket path of a locally running KDC. An optional |
| 535 |
port number, separated from the hostname by a colon, may be |
| 536 |
included. If the name or address contains colons (for example, if |
| 537 |
it is an IPv6 address), enclose it in square brackets to |
| 538 |
distinguish the colon from a port separator. For your computer to |
| 539 |
be able to communicate with the KDC for each realm, this tag must |
| 540 |
be given a value in each realm subsection in the configuration |
| 541 |
file, or there must be DNS SRV records specifying the KDCs. |
| 542 |
|
| 543 |
**kpasswd_server** |
| 544 |
The location of the password change server for the realm, using |
| 545 |
the same syntax as **kdc**. If there is no such entry, DNS will |
| 546 |
be queried (unless forbidden by **dns_lookup_kdc**). Finally, |
| 547 |
port 464 on the **admin_server** host will be tried. |
| 548 |
|
| 549 |
**master_kdc** |
| 550 |
The name for **primary_kdc** prior to release 1.19. Its value is |
| 551 |
used as a fallback if **primary_kdc** is not specified. |
| 552 |
|
| 553 |
**primary_kdc** |
| 554 |
Identifies the primary KDC(s). Currently, this tag is used in only |
| 555 |
one case: If an attempt to get credentials fails because of an |
| 556 |
invalid password, the client software will attempt to contact the |
| 557 |
primary KDC, in case the user's password has just been changed, and |
| 558 |
the updated database has not been propagated to the replica |
| 559 |
servers yet. New in release 1.19. |
| 560 |
|
| 561 |
**sitename** |
| 562 |
Specifies the name of the host's site for the purpose of DNS-based |
| 563 |
KDC discovery for this realm. New in release 1.22. |
| 564 |
|
| 565 |
**v4_instance_convert** |
| 566 |
This subsection allows the administrator to configure exceptions |
| 567 |
to the **default_domain** mapping rule. It contains V4 instances |
| 568 |
(the tag name) which should be translated to some specific |
| 569 |
hostname (the tag value) as the second component in a Kerberos V5 |
| 570 |
principal name. |
| 571 |
|
| 572 |
**v4_realm** |
| 573 |
This relation is used by the krb524 library routines when |
| 574 |
converting a V5 principal name to a V4 principal name. It is used |
| 575 |
when the V4 realm name and the V5 realm name are not the same, but |
| 576 |
still share the same principal names and passwords. The tag value |
| 577 |
is the Kerberos V4 realm name. |
| 578 |
|
| 579 |
|
| 580 |
.. _domain_realm: |
| 581 |
|
| 582 |
[domain_realm] |
| 583 |
~~~~~~~~~~~~~~ |
| 584 |
|
| 585 |
The [domain_realm] section provides a translation from hostnames to |
| 586 |
Kerberos realms. Each tag is a domain name, providing the mapping for |
| 587 |
that domain and all subdomains. If the tag begins with a period |
| 588 |
(``.``) then it applies only to subdomains. The Kerberos realm may be |
| 589 |
identified either in the realms_ section or using DNS SRV records. |
| 590 |
Tag names should be in lower case. For example:: |
| 591 |
|
| 592 |
[domain_realm] |
| 593 |
crash.mit.edu = TEST.ATHENA.MIT.EDU |
| 594 |
.dev.mit.edu = TEST.ATHENA.MIT.EDU |
| 595 |
mit.edu = ATHENA.MIT.EDU |
| 596 |
|
| 597 |
maps the host with the name ``crash.mit.edu`` into the |
| 598 |
``TEST.ATHENA.MIT.EDU`` realm. The second entry maps all hosts under the |
| 599 |
domain ``dev.mit.edu`` into the ``TEST.ATHENA.MIT.EDU`` realm, but not |
| 600 |
the host with the name ``dev.mit.edu``. That host is matched |
| 601 |
by the third entry, which maps the host ``mit.edu`` and all hosts |
| 602 |
under the domain ``mit.edu`` that do not match a preceding rule |
| 603 |
into the realm ``ATHENA.MIT.EDU``. |
| 604 |
|
| 605 |
If no translation entry applies to a hostname used for a service |
| 606 |
principal for a service ticket request, the library will try to get a |
| 607 |
referral to the appropriate realm from the client realm's KDC. If |
| 608 |
that does not succeed, the host's realm is considered to be the |
| 609 |
hostname's domain portion converted to uppercase, unless the |
| 610 |
**realm_try_domains** setting in [libdefaults] causes a different |
| 611 |
parent domain to be used. |
| 612 |
|
| 613 |
|
| 614 |
.. _capaths: |
| 615 |
|
| 616 |
[capaths] |
| 617 |
~~~~~~~~~ |
| 618 |
|
| 619 |
In order to perform direct (non-hierarchical) cross-realm |
| 620 |
authentication, configuration is needed to determine the |
| 621 |
authentication paths between realms. |
| 622 |
|
| 623 |
A client will use this section to find the authentication path between |
| 624 |
its realm and the realm of the server. The server will use this |
| 625 |
section to verify the authentication path used by the client, by |
| 626 |
checking the transited field of the received ticket. |
| 627 |
|
| 628 |
There is a tag for each participating client realm, and each tag has |
| 629 |
subtags for each of the server realms. The value of the subtags is an |
| 630 |
intermediate realm which may participate in the cross-realm |
| 631 |
authentication. The subtags may be repeated if there is more then one |
| 632 |
intermediate realm. A value of "." means that the two realms share |
| 633 |
keys directly, and no intermediate realms should be allowed to |
| 634 |
participate. |
| 635 |
|
| 636 |
Only those entries which will be needed on the client or the server |
| 637 |
need to be present. A client needs a tag for its local realm with |
| 638 |
subtags for all the realms of servers it will need to authenticate to. |
| 639 |
A server needs a tag for each realm of the clients it will serve, with |
| 640 |
a subtag of the server realm. |
| 641 |
|
| 642 |
For example, ``ANL.GOV``, ``PNL.GOV``, and ``NERSC.GOV`` all wish to |
| 643 |
use the ``ES.NET`` realm as an intermediate realm. ANL has a sub |
| 644 |
realm of ``TEST.ANL.GOV`` which will authenticate with ``NERSC.GOV`` |
| 645 |
but not ``PNL.GOV``. The [capaths] section for ``ANL.GOV`` systems |
| 646 |
would look like this:: |
| 647 |
|
| 648 |
[capaths] |
| 649 |
ANL.GOV = { |
| 650 |
TEST.ANL.GOV = . |
| 651 |
PNL.GOV = ES.NET |
| 652 |
NERSC.GOV = ES.NET |
| 653 |
ES.NET = . |
| 654 |
} |
| 655 |
TEST.ANL.GOV = { |
| 656 |
ANL.GOV = . |
| 657 |
} |
| 658 |
PNL.GOV = { |
| 659 |
ANL.GOV = ES.NET |
| 660 |
} |
| 661 |
NERSC.GOV = { |
| 662 |
ANL.GOV = ES.NET |
| 663 |
} |
| 664 |
ES.NET = { |
| 665 |
ANL.GOV = . |
| 666 |
} |
| 667 |
|
| 668 |
The [capaths] section of the configuration file used on ``NERSC.GOV`` |
| 669 |
systems would look like this:: |
| 670 |
|
| 671 |
[capaths] |
| 672 |
NERSC.GOV = { |
| 673 |
ANL.GOV = ES.NET |
| 674 |
TEST.ANL.GOV = ES.NET |
| 675 |
TEST.ANL.GOV = ANL.GOV |
| 676 |
PNL.GOV = ES.NET |
| 677 |
ES.NET = . |
| 678 |
} |
| 679 |
ANL.GOV = { |
| 680 |
NERSC.GOV = ES.NET |
| 681 |
} |
| 682 |
PNL.GOV = { |
| 683 |
NERSC.GOV = ES.NET |
| 684 |
} |
| 685 |
ES.NET = { |
| 686 |
NERSC.GOV = . |
| 687 |
} |
| 688 |
TEST.ANL.GOV = { |
| 689 |
NERSC.GOV = ANL.GOV |
| 690 |
NERSC.GOV = ES.NET |
| 691 |
} |
| 692 |
|
| 693 |
When a subtag is used more than once within a tag, clients will use |
| 694 |
the order of values to determine the path. The order of values is not |
| 695 |
important to servers. |
| 696 |
|
| 697 |
|
| 698 |
.. _appdefaults: |
| 699 |
|
| 700 |
[appdefaults] |
| 701 |
~~~~~~~~~~~~~ |
| 702 |
|
| 703 |
Each tag in the [appdefaults] section names a Kerberos V5 application |
| 704 |
or an option that is used by some Kerberos V5 application[s]. The |
| 705 |
value of the tag defines the default behaviors for that application. |
| 706 |
|
| 707 |
For example:: |
| 708 |
|
| 709 |
[appdefaults] |
| 710 |
telnet = { |
| 711 |
ATHENA.MIT.EDU = { |
| 712 |
option1 = false |
| 713 |
} |
| 714 |
} |
| 715 |
telnet = { |
| 716 |
option1 = true |
| 717 |
option2 = true |
| 718 |
} |
| 719 |
ATHENA.MIT.EDU = { |
| 720 |
option2 = false |
| 721 |
} |
| 722 |
option2 = true |
| 723 |
|
| 724 |
The above four ways of specifying the value of an option are shown in |
| 725 |
order of decreasing precedence. In this example, if telnet is running |
| 726 |
in the realm EXAMPLE.COM, it should, by default, have option1 and |
| 727 |
option2 set to true. However, a telnet program in the realm |
| 728 |
``ATHENA.MIT.EDU`` should have ``option1`` set to false and |
| 729 |
``option2`` set to true. Any other programs in ATHENA.MIT.EDU should |
| 730 |
have ``option2`` set to false by default. Any programs running in |
| 731 |
other realms should have ``option2`` set to true. |
| 732 |
|
| 733 |
The list of specifiable options for each application may be found in |
| 734 |
that application's man pages. The application defaults specified here |
| 735 |
are overridden by those specified in the realms_ section. |
| 736 |
|
| 737 |
|
| 738 |
.. _plugins: |
| 739 |
|
| 740 |
[plugins] |
| 741 |
~~~~~~~~~ |
| 742 |
|
| 743 |
* pwqual_ interface |
| 744 |
* kadm5_hook_ interface |
| 745 |
* clpreauth_ and kdcpreauth_ interfaces |
| 746 |
|
| 747 |
Tags in the [plugins] section can be used to register dynamic plugin |
| 748 |
modules and to turn modules on and off. Not every krb5 pluggable |
| 749 |
interface uses the [plugins] section; the ones that do are documented |
| 750 |
here. |
| 751 |
|
| 752 |
New in release 1.9. |
| 753 |
|
| 754 |
Each pluggable interface corresponds to a subsection of [plugins]. |
| 755 |
All subsections support the same tags: |
| 756 |
|
| 757 |
**disable** |
| 758 |
This tag may have multiple values. If there are values for this |
| 759 |
tag, then the named modules will be disabled for the pluggable |
| 760 |
interface. |
| 761 |
|
| 762 |
**enable_only** |
| 763 |
This tag may have multiple values. If there are values for this |
| 764 |
tag, then only the named modules will be enabled for the pluggable |
| 765 |
interface. |
| 766 |
|
| 767 |
**module** |
| 768 |
This tag may have multiple values. Each value is a string of the |
| 769 |
form ``modulename:pathname``, which causes the shared object |
| 770 |
located at *pathname* to be registered as a dynamic module named |
| 771 |
*modulename* for the pluggable interface. If *pathname* is not an |
| 772 |
absolute path, it will be treated as relative to the |
| 773 |
**plugin_base_dir** value from :ref:`libdefaults`. |
| 774 |
|
| 775 |
For pluggable interfaces where module order matters, modules |
| 776 |
registered with a **module** tag normally come first, in the order |
| 777 |
they are registered, followed by built-in modules in the order they |
| 778 |
are documented below. If **enable_only** tags are used, then the |
| 779 |
order of those tags overrides the normal module order. |
| 780 |
|
| 781 |
The following subsections are currently supported within the [plugins] |
| 782 |
section: |
| 783 |
|
| 784 |
.. _ccselect: |
| 785 |
|
| 786 |
ccselect interface |
| 787 |
################## |
| 788 |
|
| 789 |
The ccselect subsection controls modules for credential cache |
| 790 |
selection within a cache collection. In addition to any registered |
| 791 |
dynamic modules, the following built-in modules exist (and may be |
| 792 |
disabled with the disable tag): |
| 793 |
|
| 794 |
**k5identity** |
| 795 |
Uses a .k5identity file in the user's home directory to select a |
| 796 |
client principal |
| 797 |
|
| 798 |
**realm** |
| 799 |
Uses the service realm to guess an appropriate cache from the |
| 800 |
collection |
| 801 |
|
| 802 |
**hostname** |
| 803 |
If the service principal is host-based, uses the service hostname |
| 804 |
to guess an appropriate cache from the collection |
| 805 |
|
| 806 |
.. _pwqual: |
| 807 |
|
| 808 |
pwqual interface |
| 809 |
################ |
| 810 |
|
| 811 |
The pwqual subsection controls modules for the password quality |
| 812 |
interface, which is used to reject weak passwords when passwords are |
| 813 |
changed. The following built-in modules exist for this interface: |
| 814 |
|
| 815 |
**dict** |
| 816 |
Checks against the realm dictionary file |
| 817 |
|
| 818 |
**empty** |
| 819 |
Rejects empty passwords |
| 820 |
|
| 821 |
**hesiod** |
| 822 |
Checks against user information stored in Hesiod (only if Kerberos |
| 823 |
was built with Hesiod support) |
| 824 |
|
| 825 |
**princ** |
| 826 |
Checks against components of the principal name |
| 827 |
|
| 828 |
.. _kadm5_hook: |
| 829 |
|
| 830 |
kadm5_hook interface |
| 831 |
#################### |
| 832 |
|
| 833 |
The kadm5_hook interface provides plugins with information on |
| 834 |
principal creation, modification, password changes and deletion. This |
| 835 |
interface can be used to write a plugin to synchronize MIT Kerberos |
| 836 |
with another database such as Active Directory. No plugins are built |
| 837 |
in for this interface. |
| 838 |
|
| 839 |
.. _kadm5_auth: |
| 840 |
|
| 841 |
kadm5_auth interface |
| 842 |
#################### |
| 843 |
|
| 844 |
The kadm5_auth section (introduced in release 1.16) controls modules |
| 845 |
for the kadmin authorization interface, which determines whether a |
| 846 |
client principal is allowed to perform a kadmin operation. The |
| 847 |
following built-in modules exist for this interface: |
| 848 |
|
| 849 |
**acl** |
| 850 |
This module reads the :ref:`kadm5.acl(5)` file, and authorizes |
| 851 |
operations which are allowed according to the rules in the file. |
| 852 |
|
| 853 |
**self** |
| 854 |
This module authorizes self-service operations including password |
| 855 |
changes, creation of new random keys, fetching the client's |
| 856 |
principal record or string attributes, and fetching the policy |
| 857 |
record associated with the client principal. |
| 858 |
|
| 859 |
.. _clpreauth: |
| 860 |
|
| 861 |
.. _kdcpreauth: |
| 862 |
|
| 863 |
clpreauth and kdcpreauth interfaces |
| 864 |
################################### |
| 865 |
|
| 866 |
The clpreauth and kdcpreauth interfaces allow plugin modules to |
| 867 |
provide client and KDC preauthentication mechanisms. The following |
| 868 |
built-in modules exist for these interfaces: |
| 869 |
|
| 870 |
**pkinit** |
| 871 |
This module implements the PKINIT preauthentication mechanism. |
| 872 |
|
| 873 |
**encrypted_challenge** |
| 874 |
This module implements the encrypted challenge FAST factor. |
| 875 |
|
| 876 |
**encrypted_timestamp** |
| 877 |
This module implements the encrypted timestamp mechanism. |
| 878 |
|
| 879 |
.. _hostrealm: |
| 880 |
|
| 881 |
hostrealm interface |
| 882 |
################### |
| 883 |
|
| 884 |
The hostrealm section (introduced in release 1.12) controls modules |
| 885 |
for the host-to-realm interface, which affects the local mapping of |
| 886 |
hostnames to realm names and the choice of default realm. The following |
| 887 |
built-in modules exist for this interface: |
| 888 |
|
| 889 |
**profile** |
| 890 |
This module consults the [domain_realm] section of the profile for |
| 891 |
authoritative host-to-realm mappings, and the **default_realm** |
| 892 |
variable for the default realm. |
| 893 |
|
| 894 |
**dns** |
| 895 |
This module looks for DNS records for fallback host-to-realm |
| 896 |
mappings and the default realm. It only operates if the |
| 897 |
**dns_lookup_realm** variable is set to true. |
| 898 |
|
| 899 |
**domain** |
| 900 |
This module applies heuristics for fallback host-to-realm |
| 901 |
mappings. It implements the **realm_try_domains** variable, and |
| 902 |
uses the uppercased parent domain of the hostname if that does not |
| 903 |
produce a result. |
| 904 |
|
| 905 |
.. _localauth: |
| 906 |
|
| 907 |
localauth interface |
| 908 |
################### |
| 909 |
|
| 910 |
The localauth section (introduced in release 1.12) controls modules |
| 911 |
for the local authorization interface, which affects the relationship |
| 912 |
between Kerberos principals and local system accounts. The following |
| 913 |
built-in modules exist for this interface: |
| 914 |
|
| 915 |
**default** |
| 916 |
This module implements the **DEFAULT** type for **auth_to_local** |
| 917 |
values. |
| 918 |
|
| 919 |
**rule** |
| 920 |
This module implements the **RULE** type for **auth_to_local** |
| 921 |
values. |
| 922 |
|
| 923 |
**names** |
| 924 |
This module looks for an **auth_to_local_names** mapping for the |
| 925 |
principal name. |
| 926 |
|
| 927 |
**auth_to_local** |
| 928 |
This module processes **auth_to_local** values in the default |
| 929 |
realm's section, and applies the default method if no |
| 930 |
**auth_to_local** values exist. |
| 931 |
|
| 932 |
**k5login** |
| 933 |
This module authorizes a principal to a local account according to |
| 934 |
the account's :ref:`.k5login(5)` file. |
| 935 |
|
| 936 |
**an2ln** |
| 937 |
This module authorizes a principal to a local account if the |
| 938 |
principal name maps to the local account name. |
| 939 |
|
| 940 |
.. _certauth: |
| 941 |
|
| 942 |
certauth interface |
| 943 |
################## |
| 944 |
|
| 945 |
The certauth section (introduced in release 1.16) controls modules for |
| 946 |
the certificate authorization interface, which determines whether a |
| 947 |
certificate is allowed to preauthenticate a user via PKINIT. The |
| 948 |
following built-in modules exist for this interface: |
| 949 |
|
| 950 |
**pkinit_san** |
| 951 |
This module authorizes the certificate if it contains a PKINIT |
| 952 |
Subject Alternative Name for the requested client principal, or a |
| 953 |
Microsoft UPN SAN matching the principal if **pkinit_allow_upn** |
| 954 |
is set to true for the realm. |
| 955 |
|
| 956 |
**pkinit_eku** |
| 957 |
This module rejects the certificate if it does not contain an |
| 958 |
Extended Key Usage attribute consistent with the |
| 959 |
**pkinit_eku_checking** value for the realm. |
| 960 |
|
| 961 |
**dbmatch** |
| 962 |
This module authorizes or rejects the certificate according to |
| 963 |
whether it matches the **pkinit_cert_match** string attribute on |
| 964 |
the client principal, if that attribute is present. |
| 965 |
|
| 966 |
|
| 967 |
PKINIT options |
| 968 |
-------------- |
| 969 |
|
| 970 |
.. note:: |
| 971 |
|
| 972 |
The following are PKINIT-specific options. These values may |
| 973 |
be specified in [libdefaults] as global defaults, or within |
| 974 |
a realm-specific subsection of [libdefaults], or may be |
| 975 |
specified as realm-specific values in the [realms] section. |
| 976 |
A realm-specific value overrides, not adds to, a generic |
| 977 |
[libdefaults] specification. The search order is: |
| 978 |
|
| 979 |
1. realm-specific subsection of [libdefaults]:: |
| 980 |
|
| 981 |
[libdefaults] |
| 982 |
EXAMPLE.COM = { |
| 983 |
pkinit_anchors = FILE:/usr/local/example.com.crt |
| 984 |
} |
| 985 |
|
| 986 |
2. realm-specific value in the [realms] section:: |
| 987 |
|
| 988 |
[realms] |
| 989 |
OTHERREALM.ORG = { |
| 990 |
pkinit_anchors = FILE:/usr/local/otherrealm.org.crt |
| 991 |
} |
| 992 |
|
| 993 |
3. generic value in the [libdefaults] section:: |
| 994 |
|
| 995 |
[libdefaults] |
| 996 |
pkinit_anchors = DIR:/usr/local/generic_trusted_cas/ |
| 997 |
|
| 998 |
|
| 999 |
.. _pkinit_identity: |
| 1000 |
|
| 1001 |
Specifying PKINIT identity information |
| 1002 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1003 |
|
| 1004 |
The syntax for specifying Public Key identity, trust, and revocation |
| 1005 |
information for PKINIT is as follows: |
| 1006 |
|
| 1007 |
**FILE:**\ *filename*\ [**,**\ *keyfilename*] |
| 1008 |
This option has context-specific behavior. |
| 1009 |
|
| 1010 |
In **pkinit_identity** or **pkinit_identities**, *filename* |
| 1011 |
specifies the name of a PEM-format file containing the user's |
| 1012 |
certificate. If *keyfilename* is not specified, the user's |
| 1013 |
private key is expected to be in *filename* as well. Otherwise, |
| 1014 |
*keyfilename* is the name of the file containing the private key. |
| 1015 |
|
| 1016 |
In **pkinit_anchors** or **pkinit_pool**, *filename* is assumed to |
| 1017 |
be the name of an OpenSSL-style ca-bundle file. |
| 1018 |
|
| 1019 |
**DIR:**\ *dirname* |
| 1020 |
This option has context-specific behavior. |
| 1021 |
|
| 1022 |
In **pkinit_identity** or **pkinit_identities**, *dirname* |
| 1023 |
specifies a directory with files named ``*.crt`` and ``*.key`` |
| 1024 |
where the first part of the file name is the same for matching |
| 1025 |
pairs of certificate and private key files. When a file with a |
| 1026 |
name ending with ``.crt`` is found, a matching file ending with |
| 1027 |
``.key`` is assumed to contain the private key. If no such file |
| 1028 |
is found, then the certificate in the ``.crt`` is not used. |
| 1029 |
|
| 1030 |
In **pkinit_anchors** or **pkinit_pool**, *dirname* is assumed to |
| 1031 |
be an OpenSSL-style hashed CA directory where each CA cert is |
| 1032 |
stored in a file named ``hash-of-ca-cert.#``. This infrastructure |
| 1033 |
is encouraged, but all files in the directory will be examined and |
| 1034 |
if they contain certificates (in PEM format), they will be used. |
| 1035 |
|
| 1036 |
In **pkinit_revoke**, *dirname* is assumed to be an OpenSSL-style |
| 1037 |
hashed CA directory where each revocation list is stored in a file |
| 1038 |
named ``hash-of-ca-cert.r#``. This infrastructure is encouraged, |
| 1039 |
but all files in the directory will be examined and if they |
| 1040 |
contain a revocation list (in PEM format), they will be used. |
| 1041 |
|
| 1042 |
**PKCS12:**\ *filename* |
| 1043 |
*filename* is the name of a PKCS #12 format file, containing the |
| 1044 |
user's certificate and private key. |
| 1045 |
|
| 1046 |
**PKCS11:**\ [**module_name=**]\ *modname*\ [**:slotid=**\ *slot-id*][**:token=**\ *token-label*][**:certid=**\ *cert-id*][**:certlabel=**\ *cert-label*] |
| 1047 |
All keyword/values are optional. *modname* specifies the location |
| 1048 |
of a library implementing PKCS #11. If a value is encountered |
| 1049 |
with no keyword, it is assumed to be the *modname*. If no |
| 1050 |
module-name is specified, the default is |pkcs11_modname|. |
| 1051 |
``slotid=`` and/or ``token=`` may be specified to force the use of |
| 1052 |
a particular smard card reader or token if there is more than one |
| 1053 |
available. ``certid=`` and/or ``certlabel=`` may be specified to |
| 1054 |
force the selection of a particular certificate on the device. |
| 1055 |
Specifier values must not contain colon characters, as colons are |
| 1056 |
always treated as separators. See the **pkinit_cert_match** |
| 1057 |
configuration option for more ways to select a particular |
| 1058 |
certificate to use for PKINIT. |
| 1059 |
|
| 1060 |
**ENV:**\ *envvar* |
| 1061 |
*envvar* specifies the name of an environment variable which has |
| 1062 |
been set to a value conforming to one of the previous values. For |
| 1063 |
example, ``ENV:X509_PROXY``, where environment variable |
| 1064 |
``X509_PROXY`` has been set to ``FILE:/tmp/my_proxy.pem``. |
| 1065 |
|
| 1066 |
|
| 1067 |
PKINIT krb5.conf options |
| 1068 |
~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1069 |
|
| 1070 |
**pkinit_anchors** |
| 1071 |
Specifies the location of trusted anchor (root) certificates which |
| 1072 |
the client trusts to sign KDC certificates. This option may be |
| 1073 |
specified multiple times. These values from the config file are |
| 1074 |
not used if the user specifies X509_anchors on the command line. |
| 1075 |
|
| 1076 |
**pkinit_cert_match** |
| 1077 |
Specifies matching rules that the client certificate must match |
| 1078 |
before it is used to attempt PKINIT authentication. If a user has |
| 1079 |
multiple certificates available (on a smart card, or via other |
| 1080 |
media), there must be exactly one certificate chosen before |
| 1081 |
attempting PKINIT authentication. This option may be specified |
| 1082 |
multiple times. All the available certificates are checked |
| 1083 |
against each rule in order until there is a match of exactly one |
| 1084 |
certificate. |
| 1085 |
|
| 1086 |
The Subject and Issuer comparison strings are the :rfc:`2253` |
| 1087 |
string representations from the certificate Subject DN and Issuer |
| 1088 |
DN values. |
| 1089 |
|
| 1090 |
The syntax of the matching rules is: |
| 1091 |
|
| 1092 |
[*relation-operator*\ ]\ *component-rule* ... |
| 1093 |
|
| 1094 |
where: |
| 1095 |
|
| 1096 |
*relation-operator* |
| 1097 |
can be either ``&&``, meaning all component rules must match, |
| 1098 |
or ``||``, meaning only one component rule must match. The |
| 1099 |
default is ``&&``. |
| 1100 |
|
| 1101 |
*component-rule* |
| 1102 |
can be one of the following. Note that there is no |
| 1103 |
punctuation or whitespace between component rules. |
| 1104 |
|
| 1105 |
| **<SUBJECT>**\ *regular-expression* |
| 1106 |
| **<ISSUER>**\ *regular-expression* |
| 1107 |
| **<SAN>**\ *regular-expression* |
| 1108 |
| **<EKU>**\ *extended-key-usage-list* |
| 1109 |
| **<KU>**\ *key-usage-list* |
| 1110 |
|
| 1111 |
*extended-key-usage-list* is a comma-separated list of |
| 1112 |
required Extended Key Usage values. All values in the list |
| 1113 |
must be present in the certificate. Extended Key Usage values |
| 1114 |
can be: |
| 1115 |
|
| 1116 |
* pkinit |
| 1117 |
* msScLogin |
| 1118 |
* clientAuth |
| 1119 |
* emailProtection |
| 1120 |
|
| 1121 |
*key-usage-list* is a comma-separated list of required Key |
| 1122 |
Usage values. All values in the list must be present in the |
| 1123 |
certificate. Key Usage values can be: |
| 1124 |
|
| 1125 |
* digitalSignature |
| 1126 |
* keyEncipherment |
| 1127 |
|
| 1128 |
Examples:: |
| 1129 |
|
| 1130 |
pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM |
| 1131 |
pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.* |
| 1132 |
pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature |
| 1133 |
|
| 1134 |
**pkinit_eku_checking** |
| 1135 |
This option specifies what Extended Key Usage value the KDC |
| 1136 |
certificate presented to the client must contain. (Note that if |
| 1137 |
the KDC certificate has the pkinit SubjectAlternativeName encoded |
| 1138 |
as the Kerberos TGS name, EKU checking is not necessary since the |
| 1139 |
issuing CA has certified this as a KDC certificate.) The values |
| 1140 |
recognized in the krb5.conf file are: |
| 1141 |
|
| 1142 |
**kpKDC** |
| 1143 |
This is the default value and specifies that the KDC must have |
| 1144 |
the id-pkinit-KPKdc EKU as defined in :rfc:`4556`. |
| 1145 |
|
| 1146 |
**kpServerAuth** |
| 1147 |
If **kpServerAuth** is specified, a KDC certificate with the |
| 1148 |
id-kp-serverAuth EKU will be accepted. This key usage value |
| 1149 |
is used in most commercially issued server certificates. |
| 1150 |
|
| 1151 |
**none** |
| 1152 |
If **none** is specified, then the KDC certificate will not be |
| 1153 |
checked to verify it has an acceptable EKU. The use of this |
| 1154 |
option is not recommended. |
| 1155 |
|
| 1156 |
**pkinit_dh_min_bits** |
| 1157 |
Specifies the group of the Diffie-Hellman key the client will |
| 1158 |
attempt to use. The acceptable values are 1024, 2048, P-256, |
| 1159 |
4096, P-384, and P-521. The default is 2048. (P-256, P-384, and |
| 1160 |
P-521 are new in release 1.22.) |
| 1161 |
|
| 1162 |
**pkinit_identities** |
| 1163 |
Specifies the location(s) to be used to find the user's X.509 |
| 1164 |
identity information. If this option is specified multiple times, |
| 1165 |
each value is attempted in order until certificates are found. |
| 1166 |
Note that these values are not used if the user specifies |
| 1167 |
**X509_user_identity** on the command line. |
| 1168 |
|
| 1169 |
**pkinit_kdc_hostname** |
| 1170 |
The presence of this option indicates that the client is willing |
| 1171 |
to accept a KDC certificate with a dNSName SAN (Subject |
| 1172 |
Alternative Name) rather than requiring the id-pkinit-san as |
| 1173 |
defined in :rfc:`4556`. This option may be specified multiple |
| 1174 |
times. Its value should contain the acceptable hostname for the |
| 1175 |
KDC (as contained in its certificate). |
| 1176 |
|
| 1177 |
**pkinit_pool** |
| 1178 |
Specifies the location of intermediate certificates which may be |
| 1179 |
used by the client to complete the trust chain between a KDC |
| 1180 |
certificate and a trusted anchor. This option may be specified |
| 1181 |
multiple times. |
| 1182 |
|
| 1183 |
**pkinit_require_crl_checking** |
| 1184 |
The default certificate verification process will always check the |
| 1185 |
available revocation information to see if a certificate has been |
| 1186 |
revoked. If a match is found for the certificate in a CRL, |
| 1187 |
verification fails. If the certificate being verified is not |
| 1188 |
listed in a CRL, or there is no CRL present for its issuing CA, |
| 1189 |
and **pkinit_require_crl_checking** is false, then verification |
| 1190 |
succeeds. |
| 1191 |
|
| 1192 |
However, if **pkinit_require_crl_checking** is true and there is |
| 1193 |
no CRL information available for the issuing CA, then verification |
| 1194 |
fails. |
| 1195 |
|
| 1196 |
**pkinit_require_crl_checking** should be set to true if the |
| 1197 |
policy is such that up-to-date CRLs must be present for every CA. |
| 1198 |
|
| 1199 |
**pkinit_revoke** |
| 1200 |
Specifies the location of Certificate Revocation List (CRL) |
| 1201 |
information to be used by the client when verifying the validity |
| 1202 |
of the KDC certificate presented. This option may be specified |
| 1203 |
multiple times. |
| 1204 |
|
| 1205 |
|
| 1206 |
.. _parameter_expansion: |
| 1207 |
|
| 1208 |
Parameter expansion |
| 1209 |
------------------- |
| 1210 |
|
| 1211 |
Starting with release 1.11, several variables, such as |
| 1212 |
**default_keytab_name**, allow parameters to be expanded. |
| 1213 |
Valid parameters are: |
| 1214 |
|
| 1215 |
================= =================================================== |
| 1216 |
%{TEMP} Temporary directory |
| 1217 |
%{uid} Unix real UID or Windows SID |
| 1218 |
%{euid} Unix effective user ID or Windows SID |
| 1219 |
%{USERID} Same as %{uid} |
| 1220 |
%{null} Empty string |
| 1221 |
%{LIBDIR} Installation library directory |
| 1222 |
%{BINDIR} Installation binary directory |
| 1223 |
%{SBINDIR} Installation admin binary directory |
| 1224 |
%{username} (Unix) Username of effective user ID |
| 1225 |
%{APPDATA} (Windows) Roaming application data for current user |
| 1226 |
%{COMMON_APPDATA} (Windows) Application data for all users |
| 1227 |
%{LOCAL_APPDATA} (Windows) Local application data for current user |
| 1228 |
%{SYSTEM} (Windows) Windows system folder |
| 1229 |
%{WINDOWS} (Windows) Windows folder |
| 1230 |
%{USERCONFIG} (Windows) Per-user MIT krb5 config file directory |
| 1231 |
%{COMMONCONFIG} (Windows) Common MIT krb5 config file directory |
| 1232 |
================= =================================================== |
| 1233 |
|
| 1234 |
Sample krb5.conf file |
| 1235 |
--------------------- |
| 1236 |
|
| 1237 |
Here is an example of a generic krb5.conf file:: |
| 1238 |
|
| 1239 |
[libdefaults] |
| 1240 |
default_realm = ATHENA.MIT.EDU |
| 1241 |
dns_lookup_kdc = true |
| 1242 |
dns_lookup_realm = false |
| 1243 |
|
| 1244 |
[realms] |
| 1245 |
ATHENA.MIT.EDU = { |
| 1246 |
kdc = kerberos.mit.edu |
| 1247 |
kdc = kerberos-1.mit.edu |
| 1248 |
kdc = kerberos-2.mit.edu |
| 1249 |
admin_server = kerberos.mit.edu |
| 1250 |
primary_kdc = kerberos.mit.edu |
| 1251 |
} |
| 1252 |
EXAMPLE.COM = { |
| 1253 |
kdc = kerberos.example.com |
| 1254 |
kdc = kerberos-1.example.com |
| 1255 |
admin_server = kerberos.example.com |
| 1256 |
} |
| 1257 |
|
| 1258 |
[domain_realm] |
| 1259 |
mit.edu = ATHENA.MIT.EDU |
| 1260 |
|
| 1261 |
[capaths] |
| 1262 |
ATHENA.MIT.EDU = { |
| 1263 |
EXAMPLE.COM = . |
| 1264 |
} |
| 1265 |
EXAMPLE.COM = { |
| 1266 |
ATHENA.MIT.EDU = . |
| 1267 |
} |
| 1268 |
|
| 1269 |
FILES |
| 1270 |
----- |
| 1271 |
|
| 1272 |
|krb5conf| |
| 1273 |
|
| 1274 |
|
| 1275 |
SEE ALSO |
| 1276 |
-------- |
| 1277 |
|
| 1278 |
syslog(3) |