Kerberos configuration file The krb5.conf file contains Kerberos configuration information, including the locations of KDCs and admin servers for the Kerberos realms of interest, defaults for the …
The krb5.conf file is set up in the style of a Windows INI file. Lines beginning with '#' or ';' (possibly after initial whitespace) are ignored as comments. Sections are headed by the section name, in square brackets. Each section may contain zero or more relations, of the form:
foo = bar
or:
fubar = {
foo = bar
baz = quux
}
Placing a '*' after the closing bracket of a section name indicates that the section is final, meaning that if the same section appears within a later file specified in KRB5_CONFIG, it will be ignored. A subsection can be marked as final by placing a '*' after either the tag name or the closing brace.
The krb5.conf file can include other files using either of the following directives at the beginning of a line:
include FILENAME includedir DIRNAME
FILENAME or DIRNAME should be an absolute path. The named file or directory must exist and be readable. Including a directory includes all files within the directory whose names consist solely of alphanumeric characters, dashes, or underscores. Starting in release 1.15, files with names ending in ".conf" are also included, unless the name begins with ".". Included profile files are syntactically independent of their parents, so each included file must begin with a section header. Starting in release 1.17, files are read in alphanumeric order; in previous releases, they may be read in any order.
The krb5.conf file can specify that configuration should be obtained from a loadable module, rather than the file itself, using the following directive at the beginning of a line before any section headers:
module MODULEPATH:RESIDUAL
MODULEPATH may be relative to the library path of the krb5 installation, or it may be an absolute path. RESIDUAL is provided to the module at initialization time. If krb5.conf uses a module directive, kdc.conf(5) should also use one if it exists.
The krb5.conf file may contain the following sections:
| [libdefaults] | Settings used by the Kerberos V5 library |
| [realms] | Realm-specific contact information and settings |
| [domain_realm] | Maps server hostnames to Kerberos realms |
| [capaths] | Authentication paths for non-hierarchical cross-realm |
| [appdefaults] | Settings used by some Kerberos V5 applications |
| [plugins] | Controls plugin module registration |
Additionally, krb5.conf may include any of the relations described in kdc.conf(5), but it is not a recommended practice.
The libdefaults section may contain any of the following relations:
The clockskew setting is also used when evaluating ticket start and expiration times. For example, tickets that have reached their expiration time can still be used (and renewed if they are renewable tickets) if they have been expired for a shorter duration than the clockskew setting.
Do not set this unless required for specific backward compatibility purposes; stale values of this setting can prevent clients from taking advantage of new stronger enctypes when the libraries are upgraded.
Do not set this unless required for specific backward compatibility purposes; stale values of this setting can prevent clients from taking advantage of new stronger enctypes when the libraries are upgraded.
Enabling this option does open up a type of denial-of-service attack, if someone spoofs the DNS records and redirects you to another server. However, it's no worse than a denial of service, because that fake KDC will be unable to decode anything you send it (besides the initial ticket request, which has no encrypted data), and anything the fake KDC sends will not be trusted without verification using some secret that it won't know.
| edwards25519 | Edwards25519 curve (RFC 7748) |
| P-256 | NIST P-256 curve (RFC 5480) |
| P-384 | NIST P-384 curve (RFC 5480) |
| P-521 | NIST P-521 curve (RFC 5480) |
The default value for the client is edwards25519. The default value for the KDC is empty. New in release 1.17.
Each tag in the [realms] section of the file is the name of a Kerberos realm. The value of the tag is a subsection with relations that define the properties of that particular realm. For each realm, the following tags may be specified in the realm's subsection:
The format for exp is [n:string](regexp)s/pattern/replacement/g. The integer n indicates how many components the target principal should have. If this matches, then a string will be formed from string, substituting the realm of the principal for $0 and the n'th component of the principal for $n (e.g., if the principal was johndoe/admin then [2:$2$1foo] would result in the string adminjohndoefoo). If this string matches regexp, then the s//[g] substitution command will be run over the string. The optional g will cause the substitution to be global over the string, instead of replacing only the first match in the string.
For example:
[realms]
ATHENA.MIT.EDU = {
auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/
auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$//
auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/
auth_to_local = DEFAULT
}
would result in any principal without root or admin as the second component to be translated with the default rule. A principal with a second component of admin will become its first component. root will be used as the local name for any principal with a second component of root. The exception to these two rules are any principals johndoe/*, which will always get the local name guest.
The syntax for values is similar to that of values for the pkinit_anchors tag:
FILE: filename
filename is assumed to be the name of an OpenSSL-style ca-bundle file.
DIR: dirname
dirname is assumed to be an directory which contains CA certificates. All files in the directory will be examined; if they contain certificates (in PEM format), they will be used.
ENV: envvar
envvar specifies the name of an environment variable which has been set to a value conforming to one of the previous values. For example, ENV:X509_PROXY_CA, where environment variable X509_PROXY_CA has been set to FILE:/tmp/my_proxy.pem.
The [domain_realm] section provides a translation from a domain name or hostname to a Kerberos realm name. The tag name can be a host name or domain name, where domain names are indicated by a prefix of a period (.). The value of the relation is the Kerberos realm name for that particular host or domain. A host name relation implicitly provides the corresponding domain name relation, unless an explicit domain name relation is provided. The Kerberos realm may be identified either in the realms section or using DNS SRV records. Host names and domain names should be in lower case. For example:
[domain_realm]
crash.mit.edu = TEST.ATHENA.MIT.EDU
.dev.mit.edu = TEST.ATHENA.MIT.EDU
mit.edu = ATHENA.MIT.EDU
maps the host with the name crash.mit.edu into the TEST.ATHENA.MIT.EDU realm. The second entry maps all hosts under the domain dev.mit.edu into the TEST.ATHENA.MIT.EDU realm, but not the host with the name dev.mit.edu. That host is matched by the third entry, which maps the host mit.edu and all hosts under the domain mit.edu that do not match a preceding rule into the realm ATHENA.MIT.EDU.
If no translation entry applies to a hostname used for a service principal for a service ticket request, the library will try to get a referral to the appropriate realm from the client realm's KDC. If that does not succeed, the host's realm is considered to be the hostname's domain portion converted to uppercase, unless the realm_try_domains setting in [libdefaults] causes a different parent domain to be used.
In order to perform direct (non-hierarchical) cross-realm authentication, configuration is needed to determine the authentication paths between realms.
A client will use this section to find the authentication path between its realm and the realm of the server. The server will use this section to verify the authentication path used by the client, by checking the transited field of the received ticket.
There is a tag for each participating client realm, and each tag has subtags for each of the server realms. The value of the subtags is an intermediate realm which may participate in the cross-realm authentication. The subtags may be repeated if there is more then one intermediate realm. A value of "." means that the two realms share keys directly, and no intermediate realms should be allowed to participate.
Only those entries which will be needed on the client or the server need to be present. A client needs a tag for its local realm with subtags for all the realms of servers it will need to authenticate to. A server needs a tag for each realm of the clients it will serve, with a subtag of the server realm.
For example, ANL.GOV, PNL.GOV, and NERSC.GOV all wish to use the ES.NET realm as an intermediate realm. ANL has a sub realm of TEST.ANL.GOV which will authenticate with NERSC.GOV but not PNL.GOV. The [capaths] section for ANL.GOV systems would look like this:
[capaths]
ANL.GOV = {
TEST.ANL.GOV = .
PNL.GOV = ES.NET
NERSC.GOV = ES.NET
ES.NET = .
}
TEST.ANL.GOV = {
ANL.GOV = .
}
PNL.GOV = {
ANL.GOV = ES.NET
}
NERSC.GOV = {
ANL.GOV = ES.NET
}
ES.NET = {
ANL.GOV = .
}
The [capaths] section of the configuration file used on NERSC.GOV systems would look like this:
[capaths]
NERSC.GOV = {
ANL.GOV = ES.NET
TEST.ANL.GOV = ES.NET
TEST.ANL.GOV = ANL.GOV
PNL.GOV = ES.NET
ES.NET = .
}
ANL.GOV = {
NERSC.GOV = ES.NET
}
PNL.GOV = {
NERSC.GOV = ES.NET
}
ES.NET = {
NERSC.GOV = .
}
TEST.ANL.GOV = {
NERSC.GOV = ANL.GOV
NERSC.GOV = ES.NET
}
When a subtag is used more than once within a tag, clients will use the order of values to determine the path. The order of values is not important to servers.
Each tag in the [appdefaults] section names a Kerberos V5 application or an option that is used by some Kerberos V5 application[s]. The value of the tag defines the default behaviors for that application.
For example:
[appdefaults]
telnet = {
ATHENA.MIT.EDU = {
option1 = false
}
}
telnet = {
option1 = true
option2 = true
}
ATHENA.MIT.EDU = {
option2 = false
}
option2 = true
The above four ways of specifying the value of an option are shown in order of decreasing precedence. In this example, if telnet is running in the realm EXAMPLE.COM, it should, by default, have option1 and option2 set to true. However, a telnet program in the realm ATHENA.MIT.EDU should have option1 set to false and option2 set to true. Any other programs in ATHENA.MIT.EDU should have option2 set to false by default. Any programs running in other realms should have option2 set to true.
The list of specifiable options for each application may be found in that application's man pages. The application defaults specified here are overridden by those specified in the realms section.
Tags in the [plugins] section can be used to register dynamic plugin modules and to turn modules on and off. Not every krb5 pluggable interface uses the [plugins] section; the ones that do are documented here.
New in release 1.9.
Each pluggable interface corresponds to a subsection of [plugins]. All subsections support the same tags:
For pluggable interfaces where module order matters, modules registered with a module tag normally come first, in the order they are registered, followed by built-in modules in the order they are documented below. If enable_only tags are used, then the order of those tags overrides the normal module order.
The following subsections are currently supported within the [plugins] section:
The ccselect subsection controls modules for credential cache selection within a cache collection. In addition to any registered dynamic modules, the following built-in modules exist (and may be disabled with the disable tag):
The pwqual subsection controls modules for the password quality interface, which is used to reject weak passwords when passwords are changed. The following built-in modules exist for this interface:
The kadm5_hook interface provides plugins with information on principal creation, modification, password changes and deletion. This interface can be used to write a plugin to synchronize MIT Kerberos with another database such as Active Directory. No plugins are built in for this interface.
The kadm5_auth section (introduced in release 1.16) controls modules for the kadmin authorization interface, which determines whether a client principal is allowed to perform a kadmin operation. The following built-in modules exist for this interface:
The clpreauth and kdcpreauth interfaces allow plugin modules to provide client and KDC preauthentication mechanisms. The following built-in modules exist for these interfaces:
The hostrealm section (introduced in release 1.12) controls modules for the host-to-realm interface, which affects the local mapping of hostnames to realm names and the choice of default realm. The following built-in modules exist for this interface:
The localauth section (introduced in release 1.12) controls modules for the local authorization interface, which affects the relationship between Kerberos principals and local system accounts. The following built-in modules exist for this interface:
The certauth section (introduced in release 1.16) controls modules for the certificate authorization interface, which determines whether a certificate is allowed to preauthenticate a user via PKINIT. The following built-in modules exist for this interface:
NOTE:
[libdefaults]
EXAMPLE.COM = {
pkinit_anchors = FILE:/usr/local/example.com.crt
}
[realms]
OTHERREALM.ORG = {
pkinit_anchors = FILE:/usr/local/otherrealm.org.crt
}
[libdefaults]
pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
The syntax for specifying Public Key identity, trust, and revocation information for PKINIT is as follows:
In pkinit_identity or pkinit_identities, filename specifies the name of a PEM-format file containing the user's certificate. If keyfilename is not specified, the user's private key is expected to be in filename as well. Otherwise, keyfilename is the name of the file containing the private key.
In pkinit_anchors or pkinit_pool, filename is assumed to be the name of an OpenSSL-style ca-bundle file.
In pkinit_identity or pkinit_identities, dirname specifies a directory with files named *.crt and *.key where the first part of the file name is the same for matching pairs of certificate and private key files. When a file with a name ending with .crt is found, a matching file ending with .key is assumed to contain the private key. If no such file is found, then the certificate in the .crt is not used.
In pkinit_anchors or pkinit_pool, dirname is assumed to be an OpenSSL-style hashed CA directory where each CA cert is stored in a file named hash-of-ca-cert.#. This infrastructure is encouraged, but all files in the directory will be examined and if they contain certificates (in PEM format), they will be used.
In pkinit_revoke, dirname is assumed to be an OpenSSL-style hashed CA directory where each revocation list is stored in a file named hash-of-ca-cert.r#. This infrastructure is encouraged, but all files in the directory will be examined and if they contain a revocation list (in PEM format), they will be used.
The Subject and Issuer comparison strings are the RFC 2253 string representations from the certificate Subject DN and Issuer DN values.
The syntax of the matching rules is:
where:
<SUBJECT>regular-expression <ISSUER>regular-expression <SAN>regular-expression <EKU>extended-key-usage-list <KU>key-usage-list
extended-key-usage-list is a comma-separated list of required Extended Key Usage values. All values in the list must be present in the certificate. Extended Key Usage values can be:
key-usage-list is a comma-separated list of required Key Usage values. All values in the list must be present in the certificate. Key Usage values can be:
Examples:
pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.* pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
However, if pkinit_require_crl_checking is true and there is no CRL information available for the issuing CA, then verification fails.
pkinit_require_crl_checking should be set to true if the policy is such that up-to-date CRLs must be present for every CA.
Starting with release 1.11, several variables, such as default_keytab_name, allow parameters to be expanded. Valid parameters are:
| %{TEMP} | Temporary directory |
| %{uid} | Unix real UID or Windows SID |
| %{euid} | Unix effective user ID or Windows SID |
| %{USERID} | Same as %{uid} |
| %{null} | Empty string |
| %{LIBDIR} | Installation library directory |
| %{BINDIR} | Installation binary directory |
| %{SBINDIR} | Installation admin binary directory |
| %{username} | (Unix) Username of effective user ID |
| %{APPDATA} | (Windows) Roaming application data for current user |
| %{COMMON_APPDATA} | (Windows) Application data for all users |
| %{LOCAL_APPDATA} | (Windows) Local application data for current user |
| %{SYSTEM} | (Windows) Windows system folder |
| %{WINDOWS} | (Windows) Windows folder |
| %{USERCONFIG} | (Windows) Per-user MIT krb5 config file directory |
| %{COMMONCONFIG} | (Windows) Common MIT krb5 config file directory |
Here is an example of a generic krb5.conf file:
[libdefaults]
default_realm = ATHENA.MIT.EDU
dns_lookup_kdc = true
dns_lookup_realm = false
[realms]
ATHENA.MIT.EDU = {
kdc = kerberos.mit.edu
kdc = kerberos-1.mit.edu
kdc = kerberos-2.mit.edu
admin_server = kerberos.mit.edu
primary_kdc = kerberos.mit.edu
}
EXAMPLE.COM = {
kdc = kerberos.example.com
kdc = kerberos-1.example.com
admin_server = kerberos.example.com
}
[domain_realm]
mit.edu = ATHENA.MIT.EDU
[capaths]
ATHENA.MIT.EDU = {
EXAMPLE.COM = .
}
EXAMPLE.COM = {
ATHENA.MIT.EDU = .
}
/etc/krb5.conf
MIT
1985-2021, MIT