doc/html/admin/princ_dns.html

   1
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6   <head>
   7     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   8     <title>Principal names and DNS &#8212; MIT Kerberos Documentation</title>
   9     <link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
  10     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  11     <link rel="stylesheet" href="../_static/kerb.css" type="text/css" />
  12     <script type="text/javascript">
  13       var DOCUMENTATION_OPTIONS = {
  14         URL_ROOT:    '../',
  15         VERSION:     '1.20.1',
  16         COLLAPSE_INDEX: false,
  17         FILE_SUFFIX: '.html',
  18         HAS_SOURCE:  true,
  19         SOURCELINK_SUFFIX: '.txt'
  20       };
  21     </script>
  22     <script type="text/javascript" src="../_static/jquery.js"></script>
  23     <script type="text/javascript" src="../_static/underscore.js"></script>
  24     <script type="text/javascript" src="../_static/doctools.js"></script>
  25     <link rel="author" title="About these documents" href="../about.html" />
  26     <link rel="index" title="Index" href="../genindex.html" />
  27     <link rel="search" title="Search" href="../search.html" />
  28     <link rel="copyright" title="Copyright" href="../copyright.html" />
  29     <link rel="next" title="Encryption types" href="enctypes.html" />
  30     <link rel="prev" title="Addressing dictionary attack risks" href="dictionary.html" />
  31   </head>
  32   <body>
  33     <div class="header-wrapper">
  34         <div class="header">
  35
  36
  37             <h1><a href="../index.html">MIT Kerberos Documentation</a></h1>
  38
  39             <div class="rel">
  40
  41         <a href="../index.html" title="Full Table of Contents"
  42             accesskey="C">Contents</a> |
  43         <a href="dictionary.html" title="Addressing dictionary attack risks"
  44             accesskey="P">previous</a> |
  45         <a href="enctypes.html" title="Encryption types"
  46             accesskey="N">next</a> |
  47         <a href="../genindex.html" title="General Index"
  48             accesskey="I">index</a> |
  49         <a href="../search.html" title="Enter search criteria"
  50             accesskey="S">Search</a> |
  51     <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__Principal names and DNS">feedback</a>
  52             </div>
  53         </div>
  54     </div>
  55
  56     <div class="content-wrapper">
  57       <div class="content">
  58         <div class="document">
  59
  60       <div class="documentwrapper">
  61         <div class="bodywrapper">
  62           <div class="body" role="main">
  63
  64   <div class="section" id="principal-names-and-dns">
  65 <h1>Principal names and DNS<a class="headerlink" href="#principal-names-and-dns" title="Permalink to this headline">¶</a></h1>
  66 <p>Kerberos clients can do DNS lookups to canonicalize service principal
  67 names.  This can cause difficulties when setting up Kerberos
  68 application servers, especially when the client’s name for the service
  69 is different from what the service thinks its name is.</p>
  70 <div class="section" id="service-principal-names">
  71 <h2>Service principal names<a class="headerlink" href="#service-principal-names" title="Permalink to this headline">¶</a></h2>
  72 <p>A frequently used kind of principal name is the host-based service
  73 principal name.  This kind of principal name has two components: a
  74 service name and a hostname.  For example, <code class="docutils literal"><span class="pre">imap/imap.example.com</span></code>
  75 is the principal name of the “imap” service on the host
  76 “imap.example.com”.  Other possible service names for the first
  77 component include “host” (remote login services such as ssh), “HTTP”,
  78 and “nfs” (Network File System).</p>
  79 <p>Service administrators often publish well-known hostname aliases that
  80 they would prefer users to use instead of the canonical name of the
  81 service host.  This gives service administrators more flexibility in
  82 deploying services.  For example, a shell login server might be named
  83 “long-vanity-hostname.example.com”, but users will naturally prefer to
  84 type something like “login.example.com”.  Hostname aliases also allow
  85 for administrators to set up load balancing for some sorts of services
  86 based on rotating <code class="docutils literal"><span class="pre">CNAME</span></code> records in DNS.</p>
  87 </div>
  88 <div class="section" id="service-principal-canonicalization">
  89 <h2>Service principal canonicalization<a class="headerlink" href="#service-principal-canonicalization" title="Permalink to this headline">¶</a></h2>
  90 <p>In the MIT krb5 client library, canonicalization of host-based service
  91 principals is controlled by the <strong>dns_canonicalize_hostname</strong>,
  92 <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>
  93 <p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal"><span class="pre">true</span></code> (the default
  94 value), the client performs forward resolution by looking up the IPv4
  95 and/or IPv6 addresses of the hostname using <code class="docutils literal"><span class="pre">getaddrinfo()</span></code>.  This
  96 process will typically add a domain suffix to the hostname if needed,
  97 and follow CNAME records in the DNS.  If <strong>rdns</strong> is also set to
  98 <code class="docutils literal"><span class="pre">true</span></code> (the default), the client will then perform a reverse lookup
  99 of the first returned Internet address using <code class="docutils literal"><span class="pre">getnameinfo()</span></code>,
 100 finding the name associated with the PTR record.</p>
 101 <p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal"><span class="pre">false</span></code>, the hostname is
 102 not canonicalized using DNS.  If the hostname has only one component
 103 (i.e. it contains no “.” characters), the host’s primary DNS search
 104 domain will be appended, if there is one.  The <strong>qualify_shortname</strong>
 105 variable can be used to override or disable this suffix.</p>
 106 <p>If <strong>dns_canonicalize_hostname</strong> is set to <code class="docutils literal"><span class="pre">fallback</span></code> (added in
 107 release 1.18), the hostname is initially treated according to the
 108 rules for <code class="docutils literal"><span class="pre">dns_canonicalize_hostname=false</span></code>.  If a ticket request
 109 fails because the service principal is unknown, the hostname will be
 110 canonicalized according to the rules for
 111 <code class="docutils literal"><span class="pre">dns_canonicalize_hostname=true</span></code> and the request will be retried.</p>
 112 <p>In all cases, the hostname is converted to lowercase, and any trailing
 113 dot is removed.</p>
 114 </div>
 115 <div class="section" id="reverse-dns-mismatches">
 116 <h2>Reverse DNS mismatches<a class="headerlink" href="#reverse-dns-mismatches" title="Permalink to this headline">¶</a></h2>
 117 <p>Sometimes, an enterprise will have control over its forward DNS but
 118 not its reverse DNS.  The reverse DNS is sometimes under the control
 119 of the Internet service provider of the enterprise, and the enterprise
 120 may not have much influence in setting up reverse DNS records for its
 121 address space.  If there are difficulties with getting forward and
 122 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
 123 machines.</p>
 124 </div>
 125 <div class="section" id="overriding-application-behavior">
 126 <h2>Overriding application behavior<a class="headerlink" href="#overriding-application-behavior" title="Permalink to this headline">¶</a></h2>
 127 <p>Applications can choose to use a default hostname component in their
 128 service principal name when accepting authentication, which avoids
 129 some sorts of hostname mismatches.  Because not all relevant
 130 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>
 131 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">libdefaults</span><span class="p">]</span>
 132     <span class="n">ignore_acceptor_hostname</span> <span class="o">=</span> <span class="n">true</span>
 133 </pre></div>
 134 </div>
 135 <p>will allow the Kerberos library to override the application’s choice
 136 of service principal hostname and will allow a server program to
 137 accept incoming authentications using any key in its keytab that
 138 matches the service name and realm name (if given).  This setting
 139 defaults to “false” and is available in releases krb5-1.10 and later.</p>
 140 </div>
 141 <div class="section" id="provisioning-keytabs">
 142 <h2>Provisioning keytabs<a class="headerlink" href="#provisioning-keytabs" title="Permalink to this headline">¶</a></h2>
 143 <p>One service principal entry that should be in the keytab is a
 144 principal whose hostname component is the canonical hostname that
 145 <code class="docutils literal"><span class="pre">getaddrinfo()</span></code> reports for all known aliases for the host.  If the
 146 reverse DNS information does not match this canonical hostname, an
 147 additional service principal entry should be in the keytab for this
 148 different hostname.</p>
 149 </div>
 150 <div class="section" id="specific-application-advice">
 151 <h2>Specific application advice<a class="headerlink" href="#specific-application-advice" title="Permalink to this headline">¶</a></h2>
 152 <div class="section" id="secure-shell-ssh">
 153 <h3>Secure shell (ssh)<a class="headerlink" href="#secure-shell-ssh" title="Permalink to this headline">¶</a></h3>
 154 <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
 155 of modern versions of the openssh daemon will allow the daemon to try
 156 any key in its keytab when accepting a connection, rather than looking
 157 for the keytab entry that matches the host’s own idea of its name
 158 (typically the name that <code class="docutils literal"><span class="pre">gethostname()</span></code> returns).  This requires
 159 krb5-1.10 or later.</p>
 160 </div>
 161 <div class="section" id="openldap-ldapsearch-etc">
 162 <h3>OpenLDAP (ldapsearch, etc.)<a class="headerlink" href="#openldap-ldapsearch-etc" title="Permalink to this headline">¶</a></h3>
 163 <p>OpenLDAP’s SASL implementation performs reverse DNS lookup in order to
 164 canonicalize service principal names, even if <strong>rdns</strong> is set to
 165 <code class="docutils literal"><span class="pre">false</span></code> in the Kerberos configuration.  To disable this behavior,
 166 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
 167 <code class="docutils literal"><span class="pre">LDAPSASL_NOCANON</span></code> environment variable.</p>
 168 </div>
 169 </div>
 170 </div>
 171
 172
 173           </div>
 174         </div>
 175       </div>
 176         </div>
 177         <div class="sidebar">
 178     <h2>On this page</h2>
 179     <ul>
 180 <li><a class="reference internal" href="#">Principal names and DNS</a><ul>
 181 <li><a class="reference internal" href="#service-principal-names">Service principal names</a></li>
 182 <li><a class="reference internal" href="#service-principal-canonicalization">Service principal canonicalization</a></li>
 183 <li><a class="reference internal" href="#reverse-dns-mismatches">Reverse DNS mismatches</a></li>
 184 <li><a class="reference internal" href="#overriding-application-behavior">Overriding application behavior</a></li>
 185 <li><a class="reference internal" href="#provisioning-keytabs">Provisioning keytabs</a></li>
 186 <li><a class="reference internal" href="#specific-application-advice">Specific application advice</a><ul>
 187 <li><a class="reference internal" href="#secure-shell-ssh">Secure shell (ssh)</a></li>
 188 <li><a class="reference internal" href="#openldap-ldapsearch-etc">OpenLDAP (ldapsearch, etc.)</a></li>
 189 </ul>
 190 </li>
 191 </ul>
 192 </li>
 193 </ul>
 194
 195     <br/>
 196     <h2>Table of contents</h2>
 197     <ul class="current">
 198 <li class="toctree-l1"><a class="reference internal" href="../user/index.html">For users</a></li>
 199 <li class="toctree-l1 current"><a class="reference internal" href="index.html">For administrators</a><ul class="current">
 200 <li class="toctree-l2"><a class="reference internal" href="install.html">Installation guide</a></li>
 201 <li class="toctree-l2"><a class="reference internal" href="conf_files/index.html">Configuration Files</a></li>
 202 <li class="toctree-l2"><a class="reference internal" href="realm_config.html">Realm configuration decisions</a></li>
 203 <li class="toctree-l2"><a class="reference internal" href="database.html">Database administration</a></li>
 204 <li class="toctree-l2"><a class="reference internal" href="dbtypes.html">Database types</a></li>
 205 <li class="toctree-l2"><a class="reference internal" href="lockout.html">Account lockout</a></li>
 206 <li class="toctree-l2"><a class="reference internal" href="conf_ldap.html">Configuring Kerberos with OpenLDAP back-end</a></li>
 207 <li class="toctree-l2"><a class="reference internal" href="appl_servers.html">Application servers</a></li>
 208 <li class="toctree-l2"><a class="reference internal" href="host_config.html">Host configuration</a></li>
 209 <li class="toctree-l2"><a class="reference internal" href="backup_host.html">Backups of secure hosts</a></li>
 210 <li class="toctree-l2"><a class="reference internal" href="pkinit.html">PKINIT configuration</a></li>
 211 <li class="toctree-l2"><a class="reference internal" href="otp.html">OTP Preauthentication</a></li>
 212 <li class="toctree-l2"><a class="reference internal" href="spake.html">SPAKE Preauthentication</a></li>
 213 <li class="toctree-l2"><a class="reference internal" href="dictionary.html">Addressing dictionary attack risks</a></li>
 214 <li class="toctree-l2 current"><a class="current reference internal" href="#">Principal names and DNS</a></li>
 215 <li class="toctree-l2"><a class="reference internal" href="enctypes.html">Encryption types</a></li>
 216 <li class="toctree-l2"><a class="reference internal" href="https.html">HTTPS proxy configuration</a></li>
 217 <li class="toctree-l2"><a class="reference internal" href="auth_indicator.html">Authentication indicators</a></li>
 218 <li class="toctree-l2"><a class="reference internal" href="admin_commands/index.html">Administration  programs</a></li>
 219 <li class="toctree-l2"><a class="reference internal" href="../mitK5defaults.html">MIT Kerberos defaults</a></li>
 220 <li class="toctree-l2"><a class="reference internal" href="env_variables.html">Environment variables</a></li>
 221 <li class="toctree-l2"><a class="reference internal" href="troubleshoot.html">Troubleshooting</a></li>
 222 <li class="toctree-l2"><a class="reference internal" href="advanced/index.html">Advanced topics</a></li>
 223 <li class="toctree-l2"><a class="reference internal" href="various_envs.html">Various links</a></li>
 224 </ul>
 225 </li>
 226 <li class="toctree-l1"><a class="reference internal" href="../appdev/index.html">For application developers</a></li>
 227 <li class="toctree-l1"><a class="reference internal" href="../plugindev/index.html">For plugin module developers</a></li>
 228 <li class="toctree-l1"><a class="reference internal" href="../build/index.html">Building Kerberos V5</a></li>
 229 <li class="toctree-l1"><a class="reference internal" href="../basic/index.html">Kerberos V5 concepts</a></li>
 230 <li class="toctree-l1"><a class="reference internal" href="../formats/index.html">Protocols and file formats</a></li>
 231 <li class="toctree-l1"><a class="reference internal" href="../mitK5features.html">MIT Kerberos features</a></li>
 232 <li class="toctree-l1"><a class="reference internal" href="../build_this.html">How to build this documentation from the source</a></li>
 233 <li class="toctree-l1"><a class="reference internal" href="../about.html">Contributing to the MIT Kerberos Documentation</a></li>
 234 <li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li>
 235 </ul>
 236
 237     <br/>
 238     <h4><a href="../index.html">Full Table of Contents</a></h4>
 239     <h4>Search</h4>
 240     <form class="search" action="../search.html" method="get">
 241       <input type="text" name="q" size="18" />
 242       <input type="submit" value="Go" />
 243       <input type="hidden" name="check_keywords" value="yes" />
 244       <input type="hidden" name="area" value="default" />
 245     </form>
 246         </div>
 247         <div class="clearer"></div>
 248       </div>
 249     </div>
 250
 251     <div class="footer-wrapper">
 252         <div class="footer" >
 253             <div class="right" ><i>Release: 1.20.1</i><br />
 254                 &copy; <a href="../copyright.html">Copyright</a> 1985-2022, MIT.
 255             </div>
 256             <div class="left">
 257
 258         <a href="../index.html" title="Full Table of Contents"
 259             >Contents</a> |
 260         <a href="dictionary.html" title="Addressing dictionary attack risks"
 261             >previous</a> |
 262         <a href="enctypes.html" title="Encryption types"
 263             >next</a> |
 264         <a href="../genindex.html" title="General Index"
 265             >index</a> |
 266         <a href="../search.html" title="Enter search criteria"
 267             >Search</a> |
 268     <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__Principal names and DNS">feedback</a>
 269             </div>
 270         </div>
 271     </div>
 272
 273   </body>
 274 </html>