krb5: Import MIT 1.21.3 - src - FreeBSD source tree

diff options


context:
space:
mode:

author	Cy Schubert <cy@FreeBSD.org>	2025-03-19 22:12:25 +0000
committer	Cy Schubert <cy@FreeBSD.org>	2025-03-19 22:12:25 +0000
commit	8f7d3ef26dec89a92ec0665de84a5936310a5574 (patch)
tree	9a465418bd4056bf0d369751320a414eaed29fa4 /doc/html/admin/realm_config.html
parent	1a79b20663ca26acc2998b90ea2ff2aefd8af5b1 (diff)

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

-rw-r--r--

doc/html/admin/realm_config.html

196

1 files changed, 95 insertions, 101 deletions

diff --git a/doc/html/admin/realm_config.html b/doc/html/admin/realm_config.html
index 92851e1ff94f..f90ab88f9897 100644
--- a/doc/html/admin/realm_config.html
+++ b/doc/html/admin/realm_config.html

@@ -1,35 +1,26 @@

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

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

+<!DOCTYPE html>

-<html xmlns="http://www.w3.org/1999/xhtml">

+<html>

<head>

- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

+ <meta charset="utf-8" />

+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

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

- <link rel="stylesheet" href="../_static/agogo.css" type="text/css" />

- <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />

- <link rel="stylesheet" href="../_static/kerb.css" type="text/css" />

- <script type="text/javascript">

- var DOCUMENTATION_OPTIONS = {

- URL_ROOT: '../',

- VERSION: '1.21.2',

- COLLAPSE_INDEX: false,

- FILE_SUFFIX: '.html',

- HAS_SOURCE: true,

- SOURCELINK_SUFFIX: '.txt'

- };

- </script>

- <script type="text/javascript" src="../_static/jquery.js"></script>

- <script type="text/javascript" src="../_static/underscore.js"></script>

- <script type="text/javascript" src="../_static/doctools.js"></script>

+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />

+ <link rel="stylesheet" type="text/css" href="../_static/agogo.css" />

+ <link rel="stylesheet" type="text/css" href="../_static/kerb.css" />

+ <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>

+ <script src="../_static/jquery.js"></script>

+ <script src="../_static/underscore.js"></script>

+ <script src="../_static/doctools.js"></script>

- </head>

- <body>

+ </head><body>

@@ -61,38 +52,38 @@

- <div class="section" id="realm-configuration-decisions">

+ <section id="realm-configuration-decisions">

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

<p>Before installing Kerberos V5, it is necessary to consider the

following issues:</p>

-<li>The name of your Kerberos realm (or the name of each realm, if you

-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 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>

+<li><p>The name of your Kerberos realm (or the name of each realm, if you

+need more than one).</p></li>

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

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

+not be using the default ports.</p></li>

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

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

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

+to the replica KDCs.</p></li>

</ul>

-<div class="section" id="realm-name">

+<section id="realm-name">

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

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

make it the same as your domain name, in upper-case letters.</p>

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

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

Kerberos realm:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span>

</pre></div>

</div>

<p>If you need multiple Kerberos realms, MIT recommends that you use

descriptive names which end with your domain name, such as:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">BOSTON</span><span class="o">.</span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">BOSTON</span><span class="o">.</span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span>

<span class="n">HOUSTON</span><span class="o">.</span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span>

</pre></div>

</div>

-</div>

-<div class="section" id="mapping-hostnames-onto-kerberos-realms">

+</section>

+<section id="mapping-hostnames-onto-kerberos-realms">

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

<p>Mapping hostnames onto Kerberos realms is done in one of three ways.</p>

<p>The first mechanism works through a set of rules in the

@@ -117,12 +108,12 @@ fine-tune referral behavior on the KDC.</p>

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

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

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

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

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

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

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

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

would be:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">_kerberos</span><span class="o">.</span><span class="n">boston</span><span class="o">.</span><span class="n">engineering</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>

<span class="n">_kerberos</span><span class="o">.</span><span class="n">engineering</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>

<span class="n">_kerberos</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>

<span class="n">_kerberos</span><span class="o">.</span><span class="n">com</span>

@@ -131,8 +122,8 @@ would be:</p>

<p>The value of the first TXT record found is taken as the realm name.</p>

<p>Even if you do not choose to use this mechanism within your site,

you may wish to set it up anyway, for use when interacting with other sites.</p>

-</div>

-<div class="section" id="ports-for-the-kdc-and-admin-services">

+</section>

+<section id="ports-for-the-kdc-and-admin-services">

<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>

<p>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

@@ -141,8 +132,8 @@ ports, as long as they are specified in each host’s

<a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></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"><span class="std std-ref">Configuring your firewall to work with Kerberos V5</span></a>.</p>

-</div>

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

+</section>

+<section id="replica-kdcs">

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

<p>Replica KDCs provide an additional source of Kerberos ticket-granting

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

@@ -154,22 +145,22 @@ KDC. Therefore, you need to anticipate any likely reason a KDC might

be unavailable and have a replica KDC to take up the slack.</p>

<p>Some considerations include:</p>

-<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

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

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

+<li><p>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 replica

-KDC accessible to each segment.</li>

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

+KDC accessible to each segment.</p></li>

+<li><p>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>

+localized disasters.</p></li>

</ul>

-</div>

-<div class="section" id="hostnames-for-kdcs">

+</section>

+<section id="hostnames-for-kdcs">

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

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

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

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

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

+<code class="docutils literal notranslate"><span class="pre">kerberos-1</span></code>, <code class="docutils literal notranslate"><span class="pre">kerberos-2</span></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.</p>

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

@@ -179,44 +170,44 @@ number to contact for that service, optionally with weighting and

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

realm name. Several different Kerberos-related service names are

used:</p>

-<dl class="docutils">

-<dt>_kerberos._udp</dt>

-<dd>This is for contacting any KDC by UDP. This entry will be used

+<dl>

+<dt>_kerberos._udp</dt><dd><p>This is for contacting any KDC by UDP. This entry will be 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. Normally you should use

+KDCs.</p>

+</dd>

+<dt>_kerberos._tcp</dt><dd><p>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><p class="first">This entry should refer to those KDCs, if any, that will

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

+</dd>

+<dt>_kerberos-master._udp</dt><dd><p>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 primary KDC before failing with an

“incorrect password” error given.</p>

-<p class="last">If you have only one KDC, or for whatever reason there is no

+<p>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. _kerberos-adm._tcp

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

+others, you do not need to define this entry.</p>

+</dd>

+<dt>_kerberos-adm._tcp</dt><dd><p>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"><span class="std std-ref">kadmin</span></a> program and related utilities. For now, you will

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

</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 entry should list port 464 on your primary KDC. It is used

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

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

+</dd>

+<dt>_kpasswd._udp</dt><dd><p>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>

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

+</dd>

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

+</dd>

</dl>

<p>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:</p>

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

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

_kerberos TXT "FOOBAR.COM"

kerberos CNAME daisy

kerberos-1 CNAME use-the-force-luke

@@ -235,8 +226,8 @@ using the <strong>kdc</strong>, <strong>master_kdc</strong>, <strong>admin_serve

<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><span class="std std-ref">krb5.conf</span></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.</p>

-</div>

-<div class="section" id="kdc-discovery">

+</section>

+<section id="kdc-discovery">

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

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

records (<span class="target" id="index-1"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc7553.html"><strong>RFC 7553</strong></a>). Limitations with the SRV record format may

@@ -245,31 +236,31 @@ 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.</p>

<p>The client performs a query for the following URI records:</p>

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

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

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

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

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

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

</ul>

<p>The URI record includes a priority, weight, and a URI string that

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

-<code class="docutils literal"><span class="pre">scheme:[flags]:transport:residual</span></code>.</p>

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

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

-<code class="docutils literal"><span class="pre">krb5srv</span></code>.</li>

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

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

-primary server.</li>

-<li><em>transport</em> defines the transport type of the residual URL or

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

-MS-KKDCP type.</li>

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

+<li><p><em>scheme</em> defines the registered URI type. It should always be

+<code class="docutils literal notranslate"><span class="pre">krb5srv</span></code>.</p></li>

+<li><p><em>flags</em> contains zero or more flag characters. Currently the only

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

+primary server.</p></li>

+<li><p><em>transport</em> defines the transport type of the residual URL or

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

+MS-KKDCP type.</p></li>

+<li><p><em>residual</em> contains the hostname, IP address, or URL to be

contacted using the specified transport, with an optional port

extension. The MS-KKDCP transport type uses a HTTPS URL, and can

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

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

</ul>

<p>An example of URI records in a zone file:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">_kerberos</span><span class="o">.</span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span> <span class="n">URI</span> <span class="mi">10</span> <span class="mi">1</span> <span class="n">krb5srv</span><span class="p">:</span><span class="n">m</span><span class="p">:</span><span class="n">tcp</span><span class="p">:</span><span class="n">kdc1</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">_kerberos</span><span class="o">.</span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span> <span class="n">URI</span> <span class="mi">10</span> <span class="mi">1</span> <span class="n">krb5srv</span><span class="p">:</span><span class="n">m</span><span class="p">:</span><span class="n">tcp</span><span class="p">:</span><span class="n">kdc1</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>

<span class="n">URI</span> <span class="mi">20</span> <span class="mi">1</span> <span class="n">krb5srv</span><span class="p">:</span><span class="n">m</span><span class="p">:</span><span class="n">udp</span><span class="p">:</span><span class="n">kdc2</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="mi">89</span>

- <span class="n">URI</span> <span class="mi">40</span> <span class="mi">1</span> <span class="n">krb5srv</span><span class="p">::</span><span class="n">udp</span><span class="p">:</span><span class="mf">10.10</span><span class="o">.</span><span class="mf">0.23</span>

+ <span class="n">URI</span> <span class="mi">40</span> <span class="mi">1</span> <span class="n">krb5srv</span><span class="p">::</span><span class="n">udp</span><span class="p">:</span><span class="mf">10.10.0.23</span>

<span class="n">URI</span> <span class="mi">30</span> <span class="mi">1</span> <span class="n">krb5srv</span><span class="p">::</span><span class="n">kkdcp</span><span class="p">:</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">proxy</span><span class="p">:</span><span class="mi">89</span><span class="o">/</span><span class="n">auth</span>

</pre></div>

</div>

@@ -278,8 +269,8 @@ include a port and/or path extension.</li>

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

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

records are found.</p>

-</div>

-<div class="section" id="database-propagation">

+</section>

+<section id="database-propagation">

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

<p>The Kerberos database resides on the primary KDC, and must be

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

@@ -295,15 +286,17 @@ 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.</p>

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

-</div>

+</section>

+ <div class="clearer"></div>

</div>

<ul>

<li><a class="reference internal" href="#">Realm configuration decisions</a><ul>

@@ -369,6 +362,7 @@ the database to additional replicas.</p>

</form>

</div>

</div>

@@ -376,8 +370,8 @@ the database to additional replicas.</p>

- <div class="right" ><i>Release: 1.21.2</i><br />

+ <div class="right" ><i>Release: 1.21.3</i><br />

</div>