Provided by: krb5-doc_1.21.3-4ubuntu2_all 
NAME
krb5.conf - 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 current realm and for Kerberos
applications, and mappings of hostnames onto Kerberos realms. Normally, you should install your
krb5.conf file in the directory /etc. You can override the default location by setting the environment
variable KRB5_CONFIG. Multiple colon-separated filenames may be specified in KRB5_CONFIG; all files
which are present will be read. Starting in release 1.14, directory names can also be specified in
KRB5_CONFIG; all files within the directory whose names consist solely of alphanumeric characters,
dashes, or underscores will be read.
STRUCTURE
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.
SECTIONS
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
┌────────────────┬───────────────────────────────────────┐
│ │ │
--
PKINIT OPTIONS
NOTE:
The following are PKINIT-specific options. These values may be specified in [libdefaults] as global
defaults, or within a realm-specific subsection of [libdefaults], or may be specified as
realm-specific values in the [realms] section. A realm-specific value overrides, not adds to, a
generic [libdefaults] specification. The search order is:
1. realm-specific subsection of [libdefaults]:
[libdefaults]
EXAMPLE.COM = {
pkinit_anchors = FILE:/usr/local/example.com.crt
}
2. realm-specific value in the [realms] section:
[realms]
OTHERREALM.ORG = {
pkinit_anchors = FILE:/usr/local/otherrealm.org.crt
}
3. generic value in the [libdefaults] section:
[libdefaults]
pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
Specifying PKINIT identity information
The syntax for specifying Public Key identity, trust, and revocation information for PKINIT is as
follows:
FILE:filename[,keyfilename]
This option has context-specific behavior.
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.
DIR:dirname
This option has context-specific behavior.
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.
PKCS12:filename
filename is the name of a PKCS #12 format file, containing the user's certificate and private key.
PKCS11:[module_name=]modname[:slotid=slot-id][:token=token-label][:certid=cert-id][:certlabel=cert-label]
All keyword/values are optional. modname specifies the location of a library implementing PKCS
#11. If a value is encountered with no keyword, it is assumed to be the modname. If no
module-name is specified, the default is opensc-pkcs11.so. slotid= and/or token= may be specified
to force the use of a particular smard card reader or token if there is more than one available.
certid= and/or certlabel= may be specified to force the selection of a particular certificate on
the device. See the pkinit_cert_match configuration option for more ways to select a particular
certificate to use for PKINIT.
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, where environment variable X509_PROXY
has been set to FILE:/tmp/my_proxy.pem.
PKINIT krb5.conf options
pkinit_anchors
Specifies the location of trusted anchor (root) certificates which the client trusts to sign KDC
certificates. This option may be specified multiple times. These values from the config file are
not used if the user specifies X509_anchors on the command line.
pkinit_cert_match
Specifies matching rules that the client certificate must match before it is used to attempt
PKINIT authentication. If a user has multiple certificates available (on a smart card, or via
other media), there must be exactly one certificate chosen before attempting PKINIT
authentication. This option may be specified multiple times. All the available certificates are
checked against each rule in order until there is a match of exactly one certificate.
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:
[relation-operator]component-rule ...
where:
relation-operator
can be either &&, meaning all component rules must match, or ||, meaning only one component
rule must match. The default is &&.
component-rule
can be one of the following. Note that there is no punctuation or whitespace between
component rules.
<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:
• pkinit
• msScLogin
• clientAuth
• emailProtection
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:
• digitalSignature
• keyEncipherment
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
pkinit_eku_checking
This option specifies what Extended Key Usage value the KDC certificate presented to the client
must contain. (Note that if the KDC certificate has the pkinit SubjectAlternativeName encoded as
the Kerberos TGS name, EKU checking is not necessary since the issuing CA has certified this as a
KDC certificate.) The values recognized in the krb5.conf file are:
kpKDC This is the default value and specifies that the KDC must have the id-pkinit-KPKdc EKU as
defined in RFC 4556.
kpServerAuth
If kpServerAuth is specified, a KDC certificate with the id-kp-serverAuth EKU will be
accepted. This key usage value is used in most commercially issued server certificates.
none If none is specified, then the KDC certificate will not be checked to verify it has an
acceptable EKU. The use of this option is not recommended.
pkinit_dh_min_bits
Specifies the size of the Diffie-Hellman key the client will attempt to use. The acceptable
values are 1024, 2048, and 4096. The default is 2048.
pkinit_identities
Specifies the location(s) to be used to find the user's X.509 identity information. If this
option is specified multiple times, each value is attempted in order until certificates are found.
Note that these values are not used if the user specifies X509_user_identity on the command line.
pkinit_kdc_hostname
The presence of this option indicates that the client is willing to accept a KDC certificate with
a dNSName SAN (Subject Alternative Name) rather than requiring the id-pkinit-san as defined in RFC
4556. This option may be specified multiple times. Its value should contain the acceptable
hostname for the KDC (as contained in its certificate).
pkinit_pool
Specifies the location of intermediate certificates which may be used by the client to complete
the trust chain between a KDC certificate and a trusted anchor. This option may be specified
multiple times.
pkinit_require_crl_checking
The default certificate verification process will always check the available revocation
information to see if a certificate has been revoked. If a match is found for the certificate in
a CRL, verification fails. If the certificate being verified is not listed in a CRL, or there is
no CRL present for its issuing CA, and pkinit_require_crl_checking is false, then verification
succeeds.
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.
pkinit_revoke
Specifies the location of Certificate Revocation List (CRL) information to be used by the client
when verifying the validity of the KDC certificate presented. This option may be specified
multiple times.
PARAMETER EXPANSION
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
┌───────────────────┬───────────────────────────────────────┐
│ │ │
SAMPLE KRB5.CONF FILE │ │ │
--
FILES │ │ │
/etc/krb5.conf │ │ │
│ │ │
SEE ALSO │ │ │
syslog(3) │ │ │
│ │ │
AUTHOR │ │ │
MIT
COPYRIGHT
1985-2024, MIT
1.21.3 KRB5.CONF(5)