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/princ_dns.html
parent	1a79b20663ca26acc2998b90ea2ff2aefd8af5b1 (diff)

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

-rw-r--r--

doc/html/admin/princ_dns.html

114

1 files changed, 54 insertions, 60 deletions

diff --git a/doc/html/admin/princ_dns.html b/doc/html/admin/princ_dns.html
index 00051ae59301..845f788e300b 100644
--- a/doc/html/admin/princ_dns.html
+++ b/doc/html/admin/princ_dns.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>Principal names and DNS — 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,17 +52,17 @@

- <div class="section" id="principal-names-and-dns">

+ <section id="principal-names-and-dns">

<h1>Principal names and DNS<a class="headerlink" href="#principal-names-and-dns" title="Permalink to this headline">¶</a></h1>

<p>Kerberos clients can do DNS lookups to canonicalize service principal

names. This can cause difficulties when setting up Kerberos

application servers, especially when the client’s name for the service

is different from what the service thinks its name is.</p>

-<div class="section" id="service-principal-names">

+<section id="service-principal-names">

<h2>Service principal names<a class="headerlink" href="#service-principal-names" title="Permalink to this headline">¶</a></h2>

<p>A frequently used kind of principal name is the host-based service

principal name. This kind of principal name has two components: a

-service name and a hostname. For example, <code class="docutils literal"><span class="pre">imap/imap.example.com</span></code>

+service name and a hostname. For example, <code class="docutils literal notranslate"><span class="pre">imap/imap.example.com</span></code>

is the principal name of the “imap” service on the host

“imap.example.com”. Other possible service names for the first

component include “host” (remote login services such as ssh), “HTTP”,

@@ -83,52 +74,52 @@ deploying services. For example, a shell login server might be named

“long-vanity-hostname.example.com”, but users will naturally prefer to

type something like “login.example.com”. Hostname aliases also allow

for administrators to set up load balancing for some sorts of services

-based on rotating <code class="docutils literal"><span class="pre">CNAME</span></code> records in DNS.</p>

-</div>

-<div class="section" id="service-principal-canonicalization">

+based on rotating <code class="docutils literal notranslate"><span class="pre">CNAME</span></code> records in DNS.</p>

+</section>

+<section id="service-principal-canonicalization">

<h2>Service principal canonicalization<a class="headerlink" href="#service-principal-canonicalization" title="Permalink to this headline">¶</a></h2>

<p>In the MIT krb5 client library, canonicalization of host-based service

principals is controlled by the <strong>dns_canonicalize_hostname</strong>,

<strong>rnds</strong>, and <strong>qualify_shortname</strong> variables in <a class="reference internal" href="conf_files/krb5_conf.html#libdefaults"><span class="std std-ref">[libdefaults]</span></a>.</p>

-<p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal"><span class="pre">true</span></code> (the default

+<p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal notranslate"><span class="pre">true</span></code> (the default

value), the client performs forward resolution by looking up the IPv4

-and/or IPv6 addresses of the hostname using <code class="docutils literal"><span class="pre">getaddrinfo()</span></code>. This

+and/or IPv6 addresses of the hostname using <code class="docutils literal notranslate"><span class="pre">getaddrinfo()</span></code>. This

process will typically add a domain suffix to the hostname if needed,

and follow CNAME records in the DNS. If <strong>rdns</strong> is also set to

-<code class="docutils literal"><span class="pre">true</span></code> (the default), the client will then perform a reverse lookup

-of the first returned Internet address using <code class="docutils literal"><span class="pre">getnameinfo()</span></code>,

+<code class="docutils literal notranslate"><span class="pre">true</span></code> (the default), the client will then perform a reverse lookup

+of the first returned Internet address using <code class="docutils literal notranslate"><span class="pre">getnameinfo()</span></code>,

finding the name associated with the PTR record.</p>

-<p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal"><span class="pre">false</span></code>, the hostname is

+<p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal notranslate"><span class="pre">false</span></code>, the hostname is

not canonicalized using DNS. If the hostname has only one component

(i.e. it contains no “.” characters), the host’s primary DNS search

domain will be appended, if there is one. The <strong>qualify_shortname</strong>

variable can be used to override or disable this suffix.</p>

-<p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal"><span class="pre">fallback</span></code> (added in

+<p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal notranslate"><span class="pre">fallback</span></code> (added in

release 1.18), the hostname is initially treated according to the

-rules for <code class="docutils literal"><span class="pre">dns_canonicalize_hostname=false</span></code>. If a ticket request

+rules for <code class="docutils literal notranslate"><span class="pre">dns_canonicalize_hostname=false</span></code>. If a ticket request

fails because the service principal is unknown, the hostname will be

canonicalized according to the rules for

-<code class="docutils literal"><span class="pre">dns_canonicalize_hostname=true</span></code> and the request will be retried.</p>

+<code class="docutils literal notranslate"><span class="pre">dns_canonicalize_hostname=true</span></code> and the request will be retried.</p>

<p>In all cases, the hostname is converted to lowercase, and any trailing

dot is removed.</p>

-</div>

-<div class="section" id="reverse-dns-mismatches">

+</section>

+<section id="reverse-dns-mismatches">

<h2>Reverse DNS mismatches<a class="headerlink" href="#reverse-dns-mismatches" title="Permalink to this headline">¶</a></h2>

<p>Sometimes, an enterprise will have control over its forward DNS but

not its reverse DNS. The reverse DNS is sometimes under the control

of the Internet service provider of the enterprise, and the enterprise

may not have much influence in setting up reverse DNS records for its

address space. If there are difficulties with getting forward and

-reverse DNS to match, it is best to set <code class="docutils literal"><span class="pre">rdns</span> <span class="pre">=</span> <span class="pre">false</span></code> on client

+reverse DNS to match, it is best to set <code class="docutils literal notranslate"><span class="pre">rdns</span> <span class="pre">=</span> <span class="pre">false</span></code> on client

machines.</p>

-</div>

-<div class="section" id="overriding-application-behavior">

+</section>

+<section id="overriding-application-behavior">

<h2>Overriding application behavior<a class="headerlink" href="#overriding-application-behavior" title="Permalink to this headline">¶</a></h2>

<p>Applications can choose to use a default hostname component in their

service principal name when accepting authentication, which avoids

some sorts of hostname mismatches. Because not all relevant

applications do this yet, using the <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><span class="std std-ref">krb5.conf</span></a> setting:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">libdefaults</span><span class="p">]</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">libdefaults</span><span class="p">]</span>

<span class="n">ignore_acceptor_hostname</span> <span class="o">=</span> <span class="n">true</span>

</pre></div>

</div>

@@ -137,44 +128,46 @@ of service principal hostname and will allow a server program to

accept incoming authentications using any key in its keytab that

matches the service name and realm name (if given). This setting

defaults to “false” and is available in releases krb5-1.10 and later.</p>

-</div>

-<div class="section" id="provisioning-keytabs">

+</section>

+<section id="provisioning-keytabs">

<h2>Provisioning keytabs<a class="headerlink" href="#provisioning-keytabs" title="Permalink to this headline">¶</a></h2>

<p>One service principal entry that should be in the keytab is a

principal whose hostname component is the canonical hostname that

-<code class="docutils literal"><span class="pre">getaddrinfo()</span></code> reports for all known aliases for the host. If the

+<code class="docutils literal notranslate"><span class="pre">getaddrinfo()</span></code> reports for all known aliases for the host. If the

reverse DNS information does not match this canonical hostname, an

additional service principal entry should be in the keytab for this

different hostname.</p>

-</div>

-<div class="section" id="specific-application-advice">

+</section>

+<section id="specific-application-advice">

<h2>Specific application advice<a class="headerlink" href="#specific-application-advice" title="Permalink to this headline">¶</a></h2>

-<div class="section" id="secure-shell-ssh">

+<section id="secure-shell-ssh">

<h3>Secure shell (ssh)<a class="headerlink" href="#secure-shell-ssh" title="Permalink to this headline">¶</a></h3>

-<p>Setting <code class="docutils literal"><span class="pre">GSSAPIStrictAcceptorCheck</span> <span class="pre">=</span> <span class="pre">no</span></code> in the configuration file

+<p>Setting <code class="docutils literal notranslate"><span class="pre">GSSAPIStrictAcceptorCheck</span> <span class="pre">=</span> <span class="pre">no</span></code> in the configuration file

of modern versions of the openssh daemon will allow the daemon to try

any key in its keytab when accepting a connection, rather than looking

for the keytab entry that matches the host’s own idea of its name

-(typically the name that <code class="docutils literal"><span class="pre">gethostname()</span></code> returns). This requires

+(typically the name that <code class="docutils literal notranslate"><span class="pre">gethostname()</span></code> returns). This requires

krb5-1.10 or later.</p>

-</div>

-<div class="section" id="openldap-ldapsearch-etc">

+</section>

+<section id="openldap-ldapsearch-etc">

<h3>OpenLDAP (ldapsearch, etc.)<a class="headerlink" href="#openldap-ldapsearch-etc" title="Permalink to this headline">¶</a></h3>

<p>OpenLDAP’s SASL implementation performs reverse DNS lookup in order to

canonicalize service principal names, even if <strong>rdns</strong> is set to

-<code class="docutils literal"><span class="pre">false</span></code> in the Kerberos configuration. To disable this behavior,

-add <code class="docutils literal"><span class="pre">SASL_NOCANON</span> <span class="pre">on</span></code> to <code class="docutils literal"><span class="pre">ldap.conf</span></code>, or set the

-<code class="docutils literal"><span class="pre">LDAPSASL_NOCANON</span></code> environment variable.</p>

-</div>

+<code class="docutils literal notranslate"><span class="pre">false</span></code> in the Kerberos configuration. To disable this behavior,

+add <code class="docutils literal notranslate"><span class="pre">SASL_NOCANON</span> <span class="pre">on</span></code> to <code class="docutils literal notranslate"><span class="pre">ldap.conf</span></code>, or set the

+<code class="docutils literal notranslate"><span class="pre">LDAPSASL_NOCANON</span></code> environment variable.</p>

+</section>

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

</div>

<ul>

<li><a class="reference internal" href="#">Principal names and DNS</a><ul>

@@ -243,6 +236,7 @@ add <code class="docutils literal"><span class="pre">SASL_NOCANON</span> <span c

</form>

</div>

</div>

@@ -250,8 +244,8 @@ add <code class="docutils literal"><span class="pre">SASL_NOCANON</span> <span c

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

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

</div>