krb5: Update to 1.21.1 - src - FreeBSD source tree

diff options


context:
space:
mode:

author	Cy Schubert <cy@FreeBSD.org>	2023-08-04 17:53:10 +0000
committer	Cy Schubert <cy@FreeBSD.org>	2023-08-04 17:53:10 +0000
commit	0320e0d5bb9fbb5da53478b3fd80ad79b110191d (patch)
tree	e1185f75bd2d3f87b0c17f787debc3ee8648214b /doc/html/admin/realm_config.html
parent	b0e4d68d5124581ae353493d69bea352de4cff8a (diff)

vendor/krb5/1.21.1

Diffstat (limited to 'doc/html/admin/realm_config.html')

-rw-r--r--

doc/html/admin/realm_config.html

199

1 files changed, 100 insertions, 99 deletions

diff --git a/doc/html/admin/realm_config.html b/doc/html/admin/realm_config.html
index 2d5ca3ae7918..cec418366e0a 100644
--- a/doc/html/admin/realm_config.html
+++ b/doc/html/admin/realm_config.html

@@ -1,33 +1,31 @@

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

- <title>Realm configuration decisions — MIT Kerberos Documentation</title>

+ <title>Realm configuration decisions — MIT Kerberos Documentation</title>

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '../',

- VERSION: '1.16',

+ VERSION: '1.21.1',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

- HAS_SOURCE: true

+ HAS_SOURCE: true,

+ SOURCELINK_SUFFIX: '.txt'

};

</script>

+ <link rel="index" title="Index" href="../genindex.html" />

+ <link rel="search" title="Search" href="../search.html" />

- <link rel="top" title="MIT Kerberos Documentation" href="../index.html" />

- <link rel="up" title="For administrators" href="index.html" />

</head>

@@ -61,7 +59,7 @@

- <div class="body">

+ <div class="body" role="main">

<h1>Realm configuration decisions<a class="headerlink" href="#realm-configuration-decisions" title="Permalink to this headline">¶</a></h1>

@@ -73,23 +71,23 @@ need more than one).</li>

<li>How you will assign your hostnames to Kerberos realms.</li>

<li>Which ports your KDC and and kadmind services will use, if they will

not be using the default ports.</li>

-<li>How many slave KDCs you need and where they should be located.</li>

-<li>The hostnames of your master and slave KDCs.</li>

-<li>How frequently you will propagate the database from the master KDC

-to the slave KDCs.</li>

+<li>How many replica KDCs you need and where they should be located.</li>

+<li>The hostnames of your primary and replica KDCs.</li>

+<li>How frequently you will propagate the database from the primary KDC

+to the replica KDCs.</li>

</ul>

<h2>Realm name<a class="headerlink" href="#realm-name" title="Permalink to this headline">¶</a></h2>

Although your Kerberos realm can be any ASCII string, convention is to

make it the same as your domain name, in upper-case letters.

-For example, hosts in the domain <tt class="docutils literal">example.com</tt> would be in the

+For example, hosts in the domain <code class="docutils literal">example.com</code> would be in the

Kerberos realm:

-<div class="highlight-python"><div class="highlight"><pre>EXAMPLE.COM

+<div class="highlight-default"><div class="highlight"><pre>EXAMPLE.COM

</pre></div>

</div>

If you need multiple Kerberos realms, MIT recommends that you use

descriptive names which end with your domain name, such as:

-<div class="highlight-python"><div class="highlight"><pre>BOSTON.EXAMPLE.COM

+<div class="highlight-default"><div class="highlight"><pre>BOSTON.EXAMPLE.COM

HOUSTON.EXAMPLE.COM

</pre></div>

</div>

@@ -98,33 +96,33 @@ descriptive names which end with your domain name, such as:

<h2>Mapping hostnames onto Kerberos realms<a class="headerlink" href="#mapping-hostnames-onto-kerberos-realms" title="Permalink to this headline">¶</a></h2>

Mapping hostnames onto Kerberos realms is done in one of three ways.

The first mechanism works through a set of rules in the

-<a class="reference internal" href="conf_files/krb5_conf.html#domain-realm">[domain_realm]</a> section of <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a>. You can specify

+<a class="reference internal" href="conf_files/krb5_conf.html#domain-realm">[domain_realm]</a> section of <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a>. You can specify

mappings for an entire domain or on a per-hostname basis. Typically

you would do this by specifying the mappings for a given domain or

subdomain and listing the exceptions.

The second mechanism is to use KDC host-based service referrals. With

-this method, the KDC’s krb5.conf has a full [domain_realm] mapping for

+this method, the KDC’s krb5.conf has a full [domain_realm] mapping for

hosts, but the clients do not, or have mappings for only a subset of

the hosts they might contact. When a client needs to contact a server

-host for which it has no mapping, it will ask the client realm’s KDC

+host for which it has no mapping, it will ask the client realm’s KDC

for the service ticket, and will receive a referral to the appropriate

service realm.

To use referrals, clients must be running MIT krb5 1.6 or later, and

the KDC must be running MIT krb5 1.7 or later. The

host_based_services and no_host_referral variables in the

-<a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms">[realms]</a> section of <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5">kdc.conf</a> can be used to

+<a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms">[realms]</a> section of <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5">kdc.conf</a> can be used to

fine-tune referral behavior on the KDC.

It is also possible for clients to use DNS TXT records, if

-dns_lookup_realm is enabled in <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a>. Such lookups

+dns_lookup_realm is enabled in <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a>. Such lookups

are disabled by default because DNS is an insecure protocol and security

holes could result if DNS records are spoofed. If enabled, the client

will try to look up a TXT record formed by prepending the prefix

-<tt class="docutils literal">_kerberos</tt> to the hostname in question. If that record is not

-found, the client will attempt a lookup by prepending <tt class="docutils literal">_kerberos</tt> to the

-host’s domain name, then its parent domain, up to the top-level domain.

-For the hostname <tt class="docutils literal">boston.engineering.example.com</tt>, the names looked up

+<code class="docutils literal">_kerberos</code> to the hostname in question. If that record is not

+found, the client will attempt a lookup by prepending <code class="docutils literal">_kerberos</code> to the

+host’s domain name, then its parent domain, up to the top-level domain.

+For the hostname <code class="docutils literal">boston.engineering.example.com</code>, the names looked up

would be:

-<div class="highlight-python"><div class="highlight"><pre>_kerberos.boston.engineering.example.com

+<div class="highlight-default"><div class="highlight"><pre>_kerberos.boston.engineering.example.com

_kerberos.engineering.example.com

_kerberos.example.com

_kerberos.com

@@ -138,44 +136,44 @@ you may wish to set it up anyway, for use when interacting with other sites.

<h2>Ports for the KDC and admin services<a class="headerlink" href="#ports-for-the-kdc-and-admin-services" title="Permalink to this headline">¶</a></h2>

The default ports used by Kerberos are port 88 for the KDC and port

749 for the admin server. You can, however, choose to run on other

-ports, as long as they are specified in each host’s

-<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a> files or in DNS SRV records, and the

-<a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5">kdc.conf</a> file on each KDC. For a more thorough treatment of

+ports, as long as they are specified in each host’s

+<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a> files or in DNS SRV records, and the

+<a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5">kdc.conf</a> file on each KDC. For a more thorough treatment of

port numbers used by the Kerberos V5 programs, refer to the

-<a class="reference internal" href="appl_servers.html#conf-firewall">Configuring your firewall to work with Kerberos V5</a>.

+<a class="reference internal" href="appl_servers.html#conf-firewall">Configuring your firewall to work with Kerberos V5</a>.

</div>

-<div class="section" id="slave-kdcs">

-<h2>Slave KDCs<a class="headerlink" href="#slave-kdcs" title="Permalink to this headline">¶</a></h2>

-Slave KDCs provide an additional source of Kerberos ticket-granting

-services in the event of inaccessibility of the master KDC. The

-number of slave KDCs you need and the decision of where to place them,

+<div class="section" id="replica-kdcs">

+<h2>Replica KDCs<a class="headerlink" href="#replica-kdcs" title="Permalink to this headline">¶</a></h2>

+Replica KDCs provide an additional source of Kerberos ticket-granting

+services in the event of inaccessibility of the primary KDC. The

+number of replica KDCs you need and the decision of where to place them,

both physically and logically, depends on the specifics of your

network.

Kerberos authentication requires that each client be able to contact a

KDC. Therefore, you need to anticipate any likely reason a KDC might

-be unavailable and have a slave KDC to take up the slack.

+be unavailable and have a replica KDC to take up the slack.

Some considerations include:

-<li>Have at least one slave KDC as a backup, for when the master KDC is

-down, is being upgraded, or is otherwise unavailable.</li>

+<li>Have at least one replica KDC as a backup, for when the primary KDC

+is down, is being upgraded, or is otherwise unavailable.</li>

<li>If your network is split such that a network outage is likely to

cause a network partition (some segment or segments of the network

-to become cut off or isolated from other segments), have a slave KDC

-accessible to each segment.</li>

-<li>If possible, have at least one slave KDC in a different building

-from the master, in case of power outages, fires, or other localized

-disasters.</li>

+to become cut off or isolated from other segments), have a replica

+KDC accessible to each segment.</li>

+<li>If possible, have at least one replica KDC in a different building

+from the primary, in case of power outages, fires, or other

+localized disasters.</li>

</ul>

</div>

<h2>Hostnames for KDCs<a class="headerlink" href="#hostnames-for-kdcs" title="Permalink to this headline">¶</a></h2>

MIT recommends that your KDCs have a predefined set of CNAME records

-(DNS hostname aliases), such as <tt class="docutils literal">kerberos</tt> for the master KDC and

-<tt class="docutils literal">kerberos-1</tt>, <tt class="docutils literal">kerberos-2</tt>, ... for the slave KDCs. This way, if

-you need to swap a machine, you only need to change a DNS entry,

+(DNS hostname aliases), such as <code class="docutils literal">kerberos</code> for the primary KDC and

+<code class="docutils literal">kerberos-1</code>, <code class="docutils literal">kerberos-2</code>, … for the replica KDCs. This way,

+if you need to swap a machine, you only need to change a DNS entry,

rather than having to change hostnames.

-As of MIT krb5 1.4, clients can locate a realm’s KDCs through DNS

-using SRV records (<a class="rfc reference external" href="http://tools.ietf.org/html/rfc2782.html">RFC 2782</a>), assuming the Kerberos realm name is

+As of MIT krb5 1.4, clients can locate a realm’s KDCs through DNS

+using SRV records (<a class="rfc reference external" href="https://tools.ietf.org/html/rfc2782.html">RFC 2782</a>), assuming the Kerberos realm name is

also a DNS domain name. These records indicate the hostname and port

number to contact for that service, optionally with weighting and

prioritization. The domain name used in the SRV record name is the

@@ -187,36 +185,38 @@ used:

the most often. Normally you should list port 88 on each of your

KDCs.</dd>

<dt>_kerberos._tcp</dt>

-<dd>This is for contacting any KDC by TCP. The MIT KDC by default

-will not listen on any TCP ports, so unless you’ve changed the

-configuration or you’re running another KDC implementation, you

-should leave this unspecified. If you do enable TCP support,

-normally you should use port 88.</dd>

+<dd>This is for contacting any KDC by TCP. Normally you should use

+port 88. This entry should be omitted if the KDC does not listen

+on TCP ports, as was the default prior to release 1.13.</dd>

<dt>_kerberos-master._udp</dt>

<dd>This entry should refer to those KDCs, if any, that will

immediately see password changes to the Kerberos database. If a

user is logging in and the password appears to be incorrect, the

-client will retry with the master KDC before failing with an

-“incorrect password” error given.

+client will retry with the primary KDC before failing with an

+“incorrect password” error given.

If you have only one KDC, or for whatever reason there is no

accessible KDC that would get database changes faster than the

-others, you do not need to define this entry.

-</dd>

-<dt>_kerberos-adm._tcp</dt>

-<dd>This should list port 749 on your master KDC. Support for it is

+others, you do not need to define this entry. _kerberos-adm._tcp

+This should list port 749 on your primary KDC. Support for it is

not complete at this time, but it will eventually be used by the

-<a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1">kadmin</a> program and related utilities. For now, you will

-also need the admin_server variable in <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a>.</dd>

+<a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1">kadmin</a> program and related utilities. For now, you will

+also need the admin_server variable in <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a>.

+</dd>

+<dt>_kerberos-master._tcp</dt>

+<dd>The corresponding TCP port for _kerberos-master._udp, assuming the

+primary KDC listens on a TCP port.</dd>

<dt>_kpasswd._udp</dt>

-<dd>This should list port 464 on your master KDC. It is used when a

-user changes her password. If this entry is not defined but a

-_kerberos-adm._tcp entry is defined, the client will use the

-_kerberos-adm._tcp entry with the port number changed to 749.</dd>

+<dd>This entry should list port 464 on your primary KDC. It is used

+when a user changes her password. If this entry is not defined

+but a _kerberos-adm._tcp entry is defined, the client will use the

+_kerberos-adm._tcp entry with the port number changed to 464.</dd>

+<dt>_kpasswd._tcp</dt>

+<dd>The corresponding TCP port for _kpasswd._udp.</dd>

</dl>

The DNS SRV specification requires that the hostnames listed be the

canonical names, not aliases. So, for example, you might include the

following records in your (BIND-style) zone file:

-<div class="highlight-python"><div class="highlight"><pre>$ORIGIN foobar.com.

+<div class="highlight-default"><div class="highlight"><pre>$ORIGIN foobar.com.

_kerberos TXT "FOOBAR.COM"

kerberos CNAME daisy

kerberos-1 CNAME use-the-force-luke

@@ -231,35 +231,35 @@ _kpasswd._udp SRV 0 0 464 daisy

</div>

Clients can also be configured with the explicit location of services

using the kdc, master_kdc, admin_server, and

-kpasswd_server variables in the <a class="reference internal" href="conf_files/krb5_conf.html#realms">[realms]</a> section of

-<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a>. Even if some clients will be configured with

+kpasswd_server variables in the <a class="reference internal" href="conf_files/krb5_conf.html#realms">[realms]</a> section of

+<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a>. Even if some clients will be configured with

explicit server locations, providing SRV records will still benefit

unconfigured clients, and be useful for other sites.

</div>

<h2>KDC Discovery<a class="headerlink" href="#kdc-discovery" title="Permalink to this headline">¶</a></h2>

As of MIT krb5 1.15, clients can also locate KDCs in DNS through URI

-records (<a class="rfc reference external" href="http://tools.ietf.org/html/rfc7553.html">RFC 7553</a>). Limitations with the SRV record format may

+records (<a class="rfc reference external" href="https://tools.ietf.org/html/rfc7553.html">RFC 7553</a>). Limitations with the SRV record format may

result in extra DNS queries in situations where a client must failover

-to other transport types, or find a master server. The URI record can

-convey more information about a realm’s KDCs with a single query.

+to other transport types, or find a primary server. The URI record

+can convey more information about a realm’s KDCs with a single query.

The client performs a query for the following URI records:

-<li><tt class="docutils literal">_kerberos.REALM</tt> for finding KDCs.</li>

-<li><tt class="docutils literal">_kerberos-adm.REALM</tt> for finding kadmin services.</li>

-<li><tt class="docutils literal">_kpasswd.REALM</tt> for finding password services.</li>

+<li><code class="docutils literal">_kerberos.REALM</code> for finding KDCs.</li>

+<li><code class="docutils literal">_kerberos-adm.REALM</code> for finding kadmin services.</li>

+<li><code class="docutils literal">_kpasswd.REALM</code> for finding password services.</li>

</ul>

The URI record includes a priority, weight, and a URI string that

consists of case-insensitive colon separated fields, in the form

-<tt class="docutils literal">scheme:[flags]:transport:residual</tt>.

+<code class="docutils literal">scheme:[flags]:transport:residual</code>.

<li>scheme defines the registered URI type. It should always be

-<tt class="docutils literal">krb5srv</tt>.</li>

+<code class="docutils literal">krb5srv</code>.</li>

<li>flags contains zero or more flag characters. Currently the only

-valid flag is <tt class="docutils literal">m</tt>, which indicates that the record is for a master

-server.</li>

+valid flag is <code class="docutils literal">m</code>, which indicates that the record is for a

+primary server.</li>

<li>transport defines the transport type of the residual URL or

-address. Accepted values are <tt class="docutils literal">tcp</tt>, <tt class="docutils literal">udp</tt>, or <tt class="docutils literal">kkdcp</tt> for the

+address. Accepted values are <code class="docutils literal">tcp</code>, <code class="docutils literal">udp</code>, or <code class="docutils literal">kkdcp</code> for the

MS-KKDCP type.</li>

<li>residual contains the hostname, IP address, or URL to be

contacted using the specified transport, with an optional port

@@ -267,34 +267,34 @@ extension. The MS-KKDCP transport type uses a HTTPS URL, and can

include a port and/or path extension.</li>

</ul>

An example of URI records in a zone file:

-<div class="highlight-python"><div class="highlight"><pre>_kerberos.EXAMPLE.COM URI 10 1 krb5srv:m:tcp:kdc1.example.com

- URI 20 1 krb5srv:m:udp:kdc2.example.com:89

- URI 40 1 krb5srv::udp:10.10.0.23

- URI 30 1 krb5srv::kkdcp:https://proxy:89/auth

+<div class="highlight-default"><div class="highlight"><pre>_kerberos.EXAMPLE.COM URI 10 1 krb5srv:m:tcp:kdc1.example.com

+ URI 20 1 krb5srv:m:udp:kdc2.example.com:89

+ URI 40 1 krb5srv::udp:10.10.0.23

+ URI 30 1 krb5srv::kkdcp:https://proxy:89/auth

</pre></div>

</div>

URI lookups are enabled by default, and can be disabled by setting

-dns_uri_lookup in the <a class="reference internal" href="conf_files/krb5_conf.html#libdefaults">[libdefaults]</a> section of

-<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a> to False. When enabled, URI lookups take

+dns_uri_lookup in the <a class="reference internal" href="conf_files/krb5_conf.html#libdefaults">[libdefaults]</a> section of

+<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a> to False. When enabled, URI lookups take

precedence over SRV lookups, falling back to SRV lookups if no URI

records are found.

</div>

<h2>Database propagation<a class="headerlink" href="#database-propagation" title="Permalink to this headline">¶</a></h2>

-The Kerberos database resides on the master KDC, and must be

-propagated regularly (usually by a cron job) to the slave KDCs. In

+The Kerberos database resides on the primary KDC, and must be

+propagated regularly (usually by a cron job) to the replica KDCs. In

deciding how frequently the propagation should happen, you will need

to balance the amount of time the propagation takes against the

maximum reasonable amount of time a user should have to wait for a

password change to take effect.

If the propagation time is longer than this maximum reasonable time

(e.g., you have a particularly large database, you have a lot of

-slaves, or you experience frequent network delays), you may wish to

+replicas, or you experience frequent network delays), you may wish to

cut down on your propagation delay by performing the propagation in

-parallel. To do this, have the master KDC propagate the database to

-one set of slaves, and then have each of these slaves propagate the

-database to additional slaves.

-See also <a class="reference internal" href="database.html#incr-db-prop">Incremental database propagation</a>

+parallel. To do this, have the primary KDC propagate the database to

+one set of replicas, and then have each of these replicas propagate

+the database to additional replicas.

+See also <a class="reference internal" href="database.html#incr-db-prop">Incremental database propagation</a>

</div>

@@ -310,7 +310,7 @@ database to additional slaves.

<li><a class="reference internal" href="#realm-name">Realm name</a></li>

<li><a class="reference internal" href="#mapping-hostnames-onto-kerberos-realms">Mapping hostnames onto Kerberos realms</a></li>

<li><a class="reference internal" href="#ports-for-the-kdc-and-admin-services">Ports for the KDC and admin services</a></li>

-<li><a class="reference internal" href="#slave-kdcs">Slave KDCs</a></li>

+<li><a class="reference internal" href="#replica-kdcs">Replica KDCs</a></li>

<li><a class="reference internal" href="#hostnames-for-kdcs">Hostnames for KDCs</a></li>

<li><a class="reference internal" href="#kdc-discovery">KDC Discovery</a></li>

<li><a class="reference internal" href="#database-propagation">Database propagation</a></li>

@@ -325,10 +325,9 @@ database to additional slaves.

<li class="toctree-l1 current"><a class="reference internal" href="index.html">For administrators</a><ul class="current">

<li class="toctree-l2"><a class="reference internal" href="install.html">Installation guide</a></li>

<li class="toctree-l2"><a class="reference internal" href="conf_files/index.html">Configuration Files</a></li>

-<li class="toctree-l2 current"><a class="current reference internal" href="">Realm configuration decisions</a><ul class="simple">

-</ul>

-</li>

+<li class="toctree-l2 current"><a class="current reference internal" href="#">Realm configuration decisions</a></li>

<li class="toctree-l2"><a class="reference internal" href="database.html">Database administration</a></li>

+<li class="toctree-l2"><a class="reference internal" href="dbtypes.html">Database types</a></li>

<li class="toctree-l2"><a class="reference internal" href="lockout.html">Account lockout</a></li>

<li class="toctree-l2"><a class="reference internal" href="conf_ldap.html">Configuring Kerberos with OpenLDAP back-end</a></li>

<li class="toctree-l2"><a class="reference internal" href="appl_servers.html">Application servers</a></li>

@@ -336,6 +335,8 @@ database to additional slaves.

<li class="toctree-l2"><a class="reference internal" href="backup_host.html">Backups of secure hosts</a></li>

<li class="toctree-l2"><a class="reference internal" href="pkinit.html">PKINIT configuration</a></li>

<li class="toctree-l2"><a class="reference internal" href="otp.html">OTP Preauthentication</a></li>

+<li class="toctree-l2"><a class="reference internal" href="spake.html">SPAKE Preauthentication</a></li>

+<li class="toctree-l2"><a class="reference internal" href="dictionary.html">Addressing dictionary attack risks</a></li>

<li class="toctree-l2"><a class="reference internal" href="princ_dns.html">Principal names and DNS</a></li>

<li class="toctree-l2"><a class="reference internal" href="enctypes.html">Encryption types</a></li>

<li class="toctree-l2"><a class="reference internal" href="https.html">HTTPS proxy configuration</a></li>

@@ -375,8 +376,8 @@ database to additional slaves.

- <div class="right" >Release: 1.16

+ <div class="right" >Release: 1.21.1

</div>