1 2<!DOCTYPE html> 3 4<html> 5 <head> 6 <meta charset="utf-8" /> 7 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> 8 9 <title>PKINIT configuration — MIT Kerberos Documentation</title> 10 <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> 11 <link rel="stylesheet" type="text/css" href="../_static/agogo.css" /> 12 <link rel="stylesheet" type="text/css" href="../_static/kerb.css" /> 13 <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> 14 <script src="../_static/jquery.js"></script> 15 <script src="../_static/underscore.js"></script> 16 <script src="../_static/doctools.js"></script> 17 <link rel="author" title="About these documents" href="../about.html" /> 18 <link rel="index" title="Index" href="../genindex.html" /> 19 <link rel="search" title="Search" href="../search.html" /> 20 <link rel="copyright" title="Copyright" href="../copyright.html" /> 21 <link rel="next" title="OTP Preauthentication" href="otp.html" /> 22 <link rel="prev" title="Backups of secure hosts" href="backup_host.html" /> 23 </head><body> 24 <div class="header-wrapper"> 25 <div class="header"> 26 27 28 <h1><a href="../index.html">MIT Kerberos Documentation</a></h1> 29 30 <div class="rel"> 31 32 <a href="../index.html" title="Full Table of Contents" 33 accesskey="C">Contents</a> | 34 <a href="backup_host.html" title="Backups of secure hosts" 35 accesskey="P">previous</a> | 36 <a href="otp.html" title="OTP Preauthentication" 37 accesskey="N">next</a> | 38 <a href="../genindex.html" title="General Index" 39 accesskey="I">index</a> | 40 <a href="../search.html" title="Enter search criteria" 41 accesskey="S">Search</a> | 42 <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__PKINIT configuration">feedback</a> 43 </div> 44 </div> 45 </div> 46 47 <div class="content-wrapper"> 48 <div class="content"> 49 <div class="document"> 50 51 <div class="documentwrapper"> 52 <div class="bodywrapper"> 53 <div class="body" role="main"> 54 55 <section id="pkinit-configuration"> 56<span id="pkinit"></span><h1>PKINIT configuration<a class="headerlink" href="#pkinit-configuration" title="Permalink to this headline">¶</a></h1> 57<p>PKINIT is a preauthentication mechanism for Kerberos 5 which uses 58X.509 certificates to authenticate the KDC to clients and vice versa. 59PKINIT can also be used to enable anonymity support, allowing clients 60to communicate securely with the KDC or with application servers 61without authenticating as a particular client principal.</p> 62<section id="creating-certificates"> 63<h2>Creating certificates<a class="headerlink" href="#creating-certificates" title="Permalink to this headline">¶</a></h2> 64<p>PKINIT requires an X.509 certificate for the KDC and one for each 65client principal which will authenticate using PKINIT. For anonymous 66PKINIT, a KDC certificate is required, but client certificates are 67not. A commercially issued server certificate can be used for the KDC 68certificate, but generally cannot be used for client certificates.</p> 69<p>The instruction in this section describe how to establish a 70certificate authority and create standard PKINIT certificates. Skip 71this section if you are using a commercially issued server certificate 72as the KDC certificate for anonymous PKINIT, or if you are configuring 73a client to use an Active Directory KDC.</p> 74<section id="generating-a-certificate-authority-certificate"> 75<h3>Generating a certificate authority certificate<a class="headerlink" href="#generating-a-certificate-authority-certificate" title="Permalink to this headline">¶</a></h3> 76<p>You can establish a new certificate authority (CA) for use with a 77PKINIT deployment with the commands:</p> 78<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">openssl</span> <span class="n">genrsa</span> <span class="o">-</span><span class="n">out</span> <span class="n">cakey</span><span class="o">.</span><span class="n">pem</span> <span class="mi">2048</span> 79<span class="n">openssl</span> <span class="n">req</span> <span class="o">-</span><span class="n">key</span> <span class="n">cakey</span><span class="o">.</span><span class="n">pem</span> <span class="o">-</span><span class="n">new</span> <span class="o">-</span><span class="n">x509</span> <span class="o">-</span><span class="n">out</span> <span class="n">cacert</span><span class="o">.</span><span class="n">pem</span> <span class="o">-</span><span class="n">days</span> <span class="mi">3650</span> 80</pre></div> 81</div> 82<p>The second command will ask for the values of several certificate 83fields. These fields can be set to any values. You can adjust the 84expiration time of the CA certificate by changing the number after 85<code class="docutils literal notranslate"><span class="pre">-days</span></code>. Since the CA certificate must be deployed to client 86machines each time it changes, it should normally have an expiration 87time far in the future; however, expiration times after 2037 may cause 88interoperability issues in rare circumstances.</p> 89<p>The result of these commands will be two files, cakey.pem and 90cacert.pem. cakey.pem will contain a 2048-bit RSA private key, which 91must be carefully protected. cacert.pem will contain the CA 92certificate, which must be placed in the filesystems of the KDC and 93each client host. cakey.pem will be required to create KDC and client 94certificates.</p> 95</section> 96<section id="generating-a-kdc-certificate"> 97<h3>Generating a KDC certificate<a class="headerlink" href="#generating-a-kdc-certificate" title="Permalink to this headline">¶</a></h3> 98<p>A KDC certificate for use with PKINIT is required to have some unusual 99fields, which makes generating them with OpenSSL somewhat complicated. 100First, you will need a file containing the following:</p> 101<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>[kdc_cert] 102basicConstraints=CA:FALSE 103keyUsage=nonRepudiation,digitalSignature,keyEncipherment,keyAgreement 104extendedKeyUsage=1.3.6.1.5.2.3.5 105subjectKeyIdentifier=hash 106authorityKeyIdentifier=keyid,issuer 107issuerAltName=issuer:copy 108subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:kdc_princ_name 109 110[kdc_princ_name] 111realm=EXP:0,GeneralString:${ENV::REALM} 112principal_name=EXP:1,SEQUENCE:kdc_principal_seq 113 114[kdc_principal_seq] 115name_type=EXP:0,INTEGER:2 116name_string=EXP:1,SEQUENCE:kdc_principals 117 118[kdc_principals] 119princ1=GeneralString:krbtgt 120princ2=GeneralString:${ENV::REALM} 121</pre></div> 122</div> 123<p>If the above contents are placed in extensions.kdc, you can generate 124and sign a KDC certificate with the following commands:</p> 125<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">openssl</span> <span class="n">genrsa</span> <span class="o">-</span><span class="n">out</span> <span class="n">kdckey</span><span class="o">.</span><span class="n">pem</span> <span class="mi">2048</span> 126<span class="n">openssl</span> <span class="n">req</span> <span class="o">-</span><span class="n">new</span> <span class="o">-</span><span class="n">out</span> <span class="n">kdc</span><span class="o">.</span><span class="n">req</span> <span class="o">-</span><span class="n">key</span> <span class="n">kdckey</span><span class="o">.</span><span class="n">pem</span> 127<span class="n">env</span> <span class="n">REALM</span><span class="o">=</span><span class="n">YOUR_REALMNAME</span> <span class="n">openssl</span> <span class="n">x509</span> <span class="o">-</span><span class="n">req</span> <span class="o">-</span><span class="ow">in</span> <span class="n">kdc</span><span class="o">.</span><span class="n">req</span> \ 128 <span class="o">-</span><span class="n">CAkey</span> <span class="n">cakey</span><span class="o">.</span><span class="n">pem</span> <span class="o">-</span><span class="n">CA</span> <span class="n">cacert</span><span class="o">.</span><span class="n">pem</span> <span class="o">-</span><span class="n">out</span> <span class="n">kdc</span><span class="o">.</span><span class="n">pem</span> <span class="o">-</span><span class="n">days</span> <span class="mi">365</span> \ 129 <span class="o">-</span><span class="n">extfile</span> <span class="n">extensions</span><span class="o">.</span><span class="n">kdc</span> <span class="o">-</span><span class="n">extensions</span> <span class="n">kdc_cert</span> <span class="o">-</span><span class="n">CAcreateserial</span> 130<span class="n">rm</span> <span class="n">kdc</span><span class="o">.</span><span class="n">req</span> 131</pre></div> 132</div> 133<p>The second command will ask for the values of certificate fields, 134which can be set to any values. In the third command, substitute your 135KDC’s realm name for YOUR_REALMNAME. You can adjust the certificate’s 136expiration date by changing the number after <code class="docutils literal notranslate"><span class="pre">-days</span></code>. Remember to 137create a new KDC certificate before the old one expires.</p> 138<p>The result of this operation will be in two files, kdckey.pem and 139kdc.pem. Both files must be placed in the KDC’s filesystem. 140kdckey.pem, which contains the KDC’s private key, must be carefully 141protected.</p> 142<p>If you examine the KDC certificate with <code class="docutils literal notranslate"><span class="pre">openssl</span> <span class="pre">x509</span> <span class="pre">-in</span> <span class="pre">kdc.pem</span> 143<span class="pre">-text</span> <span class="pre">-noout</span></code>, OpenSSL will not know how to display the KDC principal 144name in the Subject Alternative Name extension, so it will appear as 145<code class="docutils literal notranslate"><span class="pre">othername:<unsupported></span></code>. This is normal and does not mean 146anything is wrong with the KDC certificate.</p> 147</section> 148<section id="generating-client-certificates"> 149<h3>Generating client certificates<a class="headerlink" href="#generating-client-certificates" title="Permalink to this headline">¶</a></h3> 150<p>PKINIT client certificates also must have some unusual certificate 151fields. To generate a client certificate with OpenSSL for a 152single-component principal name, you will need an extensions file 153(different from the KDC extensions file above) containing:</p> 154<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>[client_cert] 155basicConstraints=CA:FALSE 156keyUsage=digitalSignature,keyEncipherment,keyAgreement 157extendedKeyUsage=1.3.6.1.5.2.3.4 158subjectKeyIdentifier=hash 159authorityKeyIdentifier=keyid,issuer 160issuerAltName=issuer:copy 161subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name 162 163[princ_name] 164realm=EXP:0,GeneralString:${ENV::REALM} 165principal_name=EXP:1,SEQUENCE:principal_seq 166 167[principal_seq] 168name_type=EXP:0,INTEGER:1 169name_string=EXP:1,SEQUENCE:principals 170 171[principals] 172princ1=GeneralString:${ENV::CLIENT} 173</pre></div> 174</div> 175<p>If the above contents are placed in extensions.client, you can 176generate and sign a client certificate with the following commands:</p> 177<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">openssl</span> <span class="n">genrsa</span> <span class="o">-</span><span class="n">out</span> <span class="n">clientkey</span><span class="o">.</span><span class="n">pem</span> <span class="mi">2048</span> 178<span class="n">openssl</span> <span class="n">req</span> <span class="o">-</span><span class="n">new</span> <span class="o">-</span><span class="n">key</span> <span class="n">clientkey</span><span class="o">.</span><span class="n">pem</span> <span class="o">-</span><span class="n">out</span> <span class="n">client</span><span class="o">.</span><span class="n">req</span> 179<span class="n">env</span> <span class="n">REALM</span><span class="o">=</span><span class="n">YOUR_REALMNAME</span> <span class="n">CLIENT</span><span class="o">=</span><span class="n">YOUR_PRINCNAME</span> <span class="n">openssl</span> <span class="n">x509</span> \ 180 <span class="o">-</span><span class="n">CAkey</span> <span class="n">cakey</span><span class="o">.</span><span class="n">pem</span> <span class="o">-</span><span class="n">CA</span> <span class="n">cacert</span><span class="o">.</span><span class="n">pem</span> <span class="o">-</span><span class="n">req</span> <span class="o">-</span><span class="ow">in</span> <span class="n">client</span><span class="o">.</span><span class="n">req</span> \ 181 <span class="o">-</span><span class="n">extensions</span> <span class="n">client_cert</span> <span class="o">-</span><span class="n">extfile</span> <span class="n">extensions</span><span class="o">.</span><span class="n">client</span> \ 182 <span class="o">-</span><span class="n">days</span> <span class="mi">365</span> <span class="o">-</span><span class="n">out</span> <span class="n">client</span><span class="o">.</span><span class="n">pem</span> 183<span class="n">rm</span> <span class="n">client</span><span class="o">.</span><span class="n">req</span> 184</pre></div> 185</div> 186<p>Normally, the first two commands should be run on the client host, and 187the resulting client.req file transferred to the certificate authority 188host for the third command. As in the previous steps, the second 189command will ask for the values of certificate fields, which can be 190set to any values. In the third command, substitute your realm’s name 191for YOUR_REALMNAME and the client’s principal name (without realm) for 192YOUR_PRINCNAME. You can adjust the certificate’s expiration date by 193changing the number after <code class="docutils literal notranslate"><span class="pre">-days</span></code>.</p> 194<p>The result of this operation will be two files, clientkey.pem and 195client.pem. Both files must be present on the client’s host; 196clientkey.pem, which contains the client’s private key, must be 197protected from access by others.</p> 198<p>As in the KDC certificate, OpenSSL will display the client principal 199name as <code class="docutils literal notranslate"><span class="pre">othername:<unsupported></span></code> in the Subject Alternative Name 200extension of a PKINIT client certificate.</p> 201<p>If the client principal name contains more than one component 202(e.g. <code class="docutils literal notranslate"><span class="pre">host/example.com@REALM</span></code>), the <code class="docutils literal notranslate"><span class="pre">[principals]</span></code> section of 203<code class="docutils literal notranslate"><span class="pre">extensions.client</span></code> must be altered to contain multiple entries. 204(Simply setting <code class="docutils literal notranslate"><span class="pre">CLIENT</span></code> to <code class="docutils literal notranslate"><span class="pre">host/example.com</span></code> would generate a 205certificate for <code class="docutils literal notranslate"><span class="pre">host\/example.com@REALM</span></code> which would not match the 206multi-component principal name.) For a two-component principal, the 207section should read:</p> 208<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>[principals] 209princ1=GeneralString:${ENV::CLIENT1} 210princ2=GeneralString:${ENV::CLIENT2} 211</pre></div> 212</div> 213<p>The environment variables <code class="docutils literal notranslate"><span class="pre">CLIENT1</span></code> and <code class="docutils literal notranslate"><span class="pre">CLIENT2</span></code> must then be set 214to the first and second components when running <code class="docutils literal notranslate"><span class="pre">openssl</span> <span class="pre">x509</span></code>.</p> 215</section> 216</section> 217<section id="configuring-the-kdc"> 218<h2>Configuring the KDC<a class="headerlink" href="#configuring-the-kdc" title="Permalink to this headline">¶</a></h2> 219<p>The KDC must have filesystem access to the KDC certificate (kdc.pem) 220and the KDC private key (kdckey.pem). Configure the following 221relation in the KDC’s <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a> file, either in the 222<a class="reference internal" href="conf_files/kdc_conf.html#kdcdefaults"><span class="std std-ref">[kdcdefaults]</span></a> section or in a <a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms"><span class="std std-ref">[realms]</span></a> subsection (with 223appropriate pathnames):</p> 224<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkinit_identity</span> <span class="o">=</span> <span class="n">FILE</span><span class="p">:</span><span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">krb5kdc</span><span class="o">/</span><span class="n">kdc</span><span class="o">.</span><span class="n">pem</span><span class="p">,</span><span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">krb5kdc</span><span class="o">/</span><span class="n">kdckey</span><span class="o">.</span><span class="n">pem</span> 225</pre></div> 226</div> 227<p>If any clients will authenticate using regular (as opposed to 228anonymous) PKINIT, the KDC must also have filesystem access to the CA 229certificate (cacert.pem), and the following configuration (with the 230appropriate pathname):</p> 231<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkinit_anchors</span> <span class="o">=</span> <span class="n">FILE</span><span class="p">:</span><span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">krb5kdc</span><span class="o">/</span><span class="n">cacert</span><span class="o">.</span><span class="n">pem</span> 232</pre></div> 233</div> 234<p>Because of the larger size of requests and responses using PKINIT, you 235may also need to allow TCP access to the KDC:</p> 236<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kdc_tcp_listen</span> <span class="o">=</span> <span class="mi">88</span> 237</pre></div> 238</div> 239<p>Restart the <a class="reference internal" href="admin_commands/krb5kdc.html#krb5kdc-8"><span class="std std-ref">krb5kdc</span></a> daemon to pick up the configuration 240changes.</p> 241<p>The principal entry for each PKINIT-using client must be configured to 242require preauthentication. Ensure this with the command:</p> 243<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span> <span class="o">-</span><span class="n">q</span> <span class="s1">'modprinc +requires_preauth YOUR_PRINCNAME'</span> 244</pre></div> 245</div> 246<p>Starting with release 1.12, it is possible to remove the long-term 247keys of a principal entry, which can save some space in the database 248and help to clarify some PKINIT-related error conditions by not asking 249for a password:</p> 250<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span> <span class="o">-</span><span class="n">q</span> <span class="s1">'purgekeys -all YOUR_PRINCNAME'</span> 251</pre></div> 252</div> 253<p>These principal options can also be specified at principal creation 254time as follows:</p> 255<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span> <span class="o">-</span><span class="n">q</span> <span class="s1">'add_principal +requires_preauth -nokey YOUR_PRINCNAME'</span> 256</pre></div> 257</div> 258<p>By default, the KDC requires PKINIT client certificates to have the 259standard Extended Key Usage and Subject Alternative Name attributes 260for PKINIT. Starting in release 1.16, it is possible to authorize 261client certificates based on the subject or other criteria instead of 262the standard PKINIT Subject Alternative Name, by setting the 263<strong>pkinit_cert_match</strong> string attribute on each client principal entry. 264For example:</p> 265<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span> <span class="n">set_string</span> <span class="n">user</span><span class="nd">@REALM</span> <span class="n">pkinit_cert_match</span> <span class="s2">"<SUBJECT>CN=user@REALM$"</span> 266</pre></div> 267</div> 268<p>The <strong>pkinit_cert_match</strong> string attribute follows the syntax used by 269the <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><span class="std std-ref">krb5.conf</span></a> <strong>pkinit_cert_match</strong> relation. To allow the 270use of non-PKINIT client certificates, it will also be necessary to 271disable key usage checking using the <strong>pkinit_eku_checking</strong> relation; 272for example:</p> 273<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">kdcdefaults</span><span class="p">]</span> 274 <span class="n">pkinit_eku_checking</span> <span class="o">=</span> <span class="n">none</span> 275</pre></div> 276</div> 277</section> 278<section id="configuring-the-clients"> 279<h2>Configuring the clients<a class="headerlink" href="#configuring-the-clients" title="Permalink to this headline">¶</a></h2> 280<p>Client hosts must be configured to trust the issuing authority for the 281KDC certificate. For a newly established certificate authority, the 282client host must have filesystem access to the CA certificate 283(cacert.pem) and the following relation in <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><span class="std std-ref">krb5.conf</span></a> in the 284appropriate <a class="reference internal" href="conf_files/krb5_conf.html#realms"><span class="std std-ref">[realms]</span></a> subsection (with appropriate pathnames):</p> 285<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkinit_anchors</span> <span class="o">=</span> <span class="n">FILE</span><span class="p">:</span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">krb5</span><span class="o">/</span><span class="n">cacert</span><span class="o">.</span><span class="n">pem</span> 286</pre></div> 287</div> 288<p>If the KDC certificate is a commercially issued server certificate, 289the issuing certificate is most likely included in a system directory. 290You can specify it by filename as above, or specify the whole 291directory like so:</p> 292<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkinit_anchors</span> <span class="o">=</span> <span class="n">DIR</span><span class="p">:</span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">ssl</span><span class="o">/</span><span class="n">certs</span> 293</pre></div> 294</div> 295<p>A commercially issued server certificate will usually not have the 296standard PKINIT principal name or Extended Key Usage extensions, so 297the following additional configuration is required:</p> 298<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkinit_eku_checking</span> <span class="o">=</span> <span class="n">kpServerAuth</span> 299<span class="n">pkinit_kdc_hostname</span> <span class="o">=</span> <span class="n">hostname</span><span class="o">.</span><span class="n">of</span><span class="o">.</span><span class="n">kdc</span><span class="o">.</span><span class="n">certificate</span> 300</pre></div> 301</div> 302<p>Multiple <strong>pkinit_kdc_hostname</strong> relations can be configured to 303recognize multiple KDC certificates. If the KDC is an Active 304Directory domain controller, setting <strong>pkinit_kdc_hostname</strong> is 305necessary, but it should not be necessary to set 306<strong>pkinit_eku_checking</strong>.</p> 307<p>To perform regular (as opposed to anonymous) PKINIT authentication, a 308client host must have filesystem access to a client certificate 309(client.pem), and the corresponding private key (clientkey.pem). 310Configure the following relations in the client host’s 311<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><span class="std std-ref">krb5.conf</span></a> file in the appropriate <a class="reference internal" href="conf_files/krb5_conf.html#realms"><span class="std std-ref">[realms]</span></a> subsection 312(with appropriate pathnames):</p> 313<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkinit_identities</span> <span class="o">=</span> <span class="n">FILE</span><span class="p">:</span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">krb5</span><span class="o">/</span><span class="n">client</span><span class="o">.</span><span class="n">pem</span><span class="p">,</span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">krb5</span><span class="o">/</span><span class="n">clientkey</span><span class="o">.</span><span class="n">pem</span> 314</pre></div> 315</div> 316<p>If the KDC and client are properly configured, it should now be 317possible to run <code class="docutils literal notranslate"><span class="pre">kinit</span> <span class="pre">username</span></code> without entering a password.</p> 318</section> 319<section id="anonymous-pkinit"> 320<span id="id1"></span><h2>Anonymous PKINIT<a class="headerlink" href="#anonymous-pkinit" title="Permalink to this headline">¶</a></h2> 321<p>Anonymity support in Kerberos allows a client to obtain a ticket 322without authenticating as any particular principal. Such a ticket can 323be used as a FAST armor ticket, or to securely communicate with an 324application server anonymously.</p> 325<p>To configure anonymity support, you must generate or otherwise procure 326a KDC certificate and configure the KDC host, but you do not need to 327generate any client certificates. On the KDC, you must set the 328<strong>pkinit_identity</strong> variable to provide the KDC certificate, but do 329not need to set the <strong>pkinit_anchors</strong> variable or store the issuing 330certificate if you won’t have any client certificates to verify. On 331client hosts, you must set the <strong>pkinit_anchors</strong> variable (and 332possibly <strong>pkinit_kdc_hostname</strong> and <strong>pkinit_eku_checking</strong>) in order 333to trust the issuing authority for the KDC certificate, but do not 334need to set the <strong>pkinit_identities</strong> variable.</p> 335<p>Anonymity support is not enabled by default. To enable it, you must 336create the principal <code class="docutils literal notranslate"><span class="pre">WELLKNOWN/ANONYMOUS</span></code> using the command:</p> 337<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span> <span class="o">-</span><span class="n">q</span> <span class="s1">'addprinc -randkey WELLKNOWN/ANONYMOUS'</span> 338</pre></div> 339</div> 340<p>Some Kerberos deployments include application servers which lack 341proper access control, and grant some level of access to any user who 342can authenticate. In such an environment, enabling anonymity support 343on the KDC would present a security issue. If you need to enable 344anonymity support for TGTs (for use as FAST armor tickets) without 345enabling anonymous authentication to application servers, you can set 346the variable <strong>restrict_anonymous_to_tgt</strong> to <code class="docutils literal notranslate"><span class="pre">true</span></code> in the 347appropriate <a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms"><span class="std std-ref">[realms]</span></a> subsection of the KDC’s 348<a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a> file.</p> 349<p>To obtain anonymous credentials on a client, run <code class="docutils literal notranslate"><span class="pre">kinit</span> <span class="pre">-n</span></code>, or 350<code class="docutils literal notranslate"><span class="pre">kinit</span> <span class="pre">-n</span> <span class="pre">@REALMNAME</span></code> to specify a realm. The resulting tickets 351will have the client name <code class="docutils literal notranslate"><span class="pre">WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS</span></code>.</p> 352</section> 353<section id="freshness-tokens"> 354<h2>Freshness tokens<a class="headerlink" href="#freshness-tokens" title="Permalink to this headline">¶</a></h2> 355<p>Freshness tokens can ensure that the client has recently had access to 356its certificate private key. If freshness tokens are not required by 357the KDC, a client program with temporary possession of the private key 358can compose requests for future timestamps and use them later.</p> 359<p>In release 1.17 and later, freshness tokens are supported by the 360client and are sent by the KDC when the client indicates support for 361them. Because not all clients support freshness tokens yet, they are 362not required by default. To check if freshness tokens are supported 363by a realm’s clients, look in the KDC logs for the lines:</p> 364<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PKINIT</span><span class="p">:</span> <span class="n">freshness</span> <span class="n">token</span> <span class="n">received</span> <span class="kn">from</span> <span class="o"><</span><span class="n">client</span> <span class="n">principal</span><span class="o">></span> 365<span class="n">PKINIT</span><span class="p">:</span> <span class="n">no</span> <span class="n">freshness</span> <span class="n">token</span> <span class="n">received</span> <span class="kn">from</span> <span class="o"><</span><span class="n">client</span> <span class="n">principal</span><span class="o">></span> 366</pre></div> 367</div> 368<p>To require freshness tokens for all clients in a realm (except for 369clients authenticating anonymously), set the 370<strong>pkinit_require_freshness</strong> variable to <code class="docutils literal notranslate"><span class="pre">true</span></code> in the appropriate 371<a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms"><span class="std std-ref">[realms]</span></a> subsection of the KDC’s <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a> file. To 372test that this option is in effect, run <code class="docutils literal notranslate"><span class="pre">kinit</span> <span class="pre">-X</span> <span class="pre">disable_freshness</span></code> 373and verify that authentication is unsuccessful.</p> 374</section> 375</section> 376 377 378 <div class="clearer"></div> 379 </div> 380 </div> 381 </div> 382 </div> 383 <div class="sidebar"> 384 385 <h2>On this page</h2> 386 <ul> 387<li><a class="reference internal" href="#">PKINIT configuration</a><ul> 388<li><a class="reference internal" href="#creating-certificates">Creating certificates</a><ul> 389<li><a class="reference internal" href="#generating-a-certificate-authority-certificate">Generating a certificate authority certificate</a></li> 390<li><a class="reference internal" href="#generating-a-kdc-certificate">Generating a KDC certificate</a></li> 391<li><a class="reference internal" href="#generating-client-certificates">Generating client certificates</a></li> 392</ul> 393</li> 394<li><a class="reference internal" href="#configuring-the-kdc">Configuring the KDC</a></li> 395<li><a class="reference internal" href="#configuring-the-clients">Configuring the clients</a></li> 396<li><a class="reference internal" href="#anonymous-pkinit">Anonymous PKINIT</a></li> 397<li><a class="reference internal" href="#freshness-tokens">Freshness tokens</a></li> 398</ul> 399</li> 400</ul> 401 402 <br/> 403 <h2>Table of contents</h2> 404 <ul class="current"> 405<li class="toctree-l1"><a class="reference internal" href="../user/index.html">For users</a></li> 406<li class="toctree-l1 current"><a class="reference internal" href="index.html">For administrators</a><ul class="current"> 407<li class="toctree-l2"><a class="reference internal" href="install.html">Installation guide</a></li> 408<li class="toctree-l2"><a class="reference internal" href="conf_files/index.html">Configuration Files</a></li> 409<li class="toctree-l2"><a class="reference internal" href="realm_config.html">Realm configuration decisions</a></li> 410<li class="toctree-l2"><a class="reference internal" href="database.html">Database administration</a></li> 411<li class="toctree-l2"><a class="reference internal" href="dbtypes.html">Database types</a></li> 412<li class="toctree-l2"><a class="reference internal" href="lockout.html">Account lockout</a></li> 413<li class="toctree-l2"><a class="reference internal" href="conf_ldap.html">Configuring Kerberos with OpenLDAP back-end</a></li> 414<li class="toctree-l2"><a class="reference internal" href="appl_servers.html">Application servers</a></li> 415<li class="toctree-l2"><a class="reference internal" href="host_config.html">Host configuration</a></li> 416<li class="toctree-l2"><a class="reference internal" href="backup_host.html">Backups of secure hosts</a></li> 417<li class="toctree-l2 current"><a class="current reference internal" href="#">PKINIT configuration</a></li> 418<li class="toctree-l2"><a class="reference internal" href="otp.html">OTP Preauthentication</a></li> 419<li class="toctree-l2"><a class="reference internal" href="spake.html">SPAKE Preauthentication</a></li> 420<li class="toctree-l2"><a class="reference internal" href="dictionary.html">Addressing dictionary attack risks</a></li> 421<li class="toctree-l2"><a class="reference internal" href="princ_dns.html">Principal names and DNS</a></li> 422<li class="toctree-l2"><a class="reference internal" href="enctypes.html">Encryption types</a></li> 423<li class="toctree-l2"><a class="reference internal" href="https.html">HTTPS proxy configuration</a></li> 424<li class="toctree-l2"><a class="reference internal" href="auth_indicator.html">Authentication indicators</a></li> 425<li class="toctree-l2"><a class="reference internal" href="admin_commands/index.html">Administration programs</a></li> 426<li class="toctree-l2"><a class="reference internal" href="../mitK5defaults.html">MIT Kerberos defaults</a></li> 427<li class="toctree-l2"><a class="reference internal" href="env_variables.html">Environment variables</a></li> 428<li class="toctree-l2"><a class="reference internal" href="troubleshoot.html">Troubleshooting</a></li> 429<li class="toctree-l2"><a class="reference internal" href="advanced/index.html">Advanced topics</a></li> 430<li class="toctree-l2"><a class="reference internal" href="various_envs.html">Various links</a></li> 431</ul> 432</li> 433<li class="toctree-l1"><a class="reference internal" href="../appdev/index.html">For application developers</a></li> 434<li class="toctree-l1"><a class="reference internal" href="../plugindev/index.html">For plugin module developers</a></li> 435<li class="toctree-l1"><a class="reference internal" href="../build/index.html">Building Kerberos V5</a></li> 436<li class="toctree-l1"><a class="reference internal" href="../basic/index.html">Kerberos V5 concepts</a></li> 437<li class="toctree-l1"><a class="reference internal" href="../formats/index.html">Protocols and file formats</a></li> 438<li class="toctree-l1"><a class="reference internal" href="../mitK5features.html">MIT Kerberos features</a></li> 439<li class="toctree-l1"><a class="reference internal" href="../build_this.html">How to build this documentation from the source</a></li> 440<li class="toctree-l1"><a class="reference internal" href="../about.html">Contributing to the MIT Kerberos Documentation</a></li> 441<li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li> 442</ul> 443 444 <br/> 445 <h4><a href="../index.html">Full Table of Contents</a></h4> 446 <h4>Search</h4> 447 <form class="search" action="../search.html" method="get"> 448 <input type="text" name="q" size="18" /> 449 <input type="submit" value="Go" /> 450 <input type="hidden" name="check_keywords" value="yes" /> 451 <input type="hidden" name="area" value="default" /> 452 </form> 453 454 </div> 455 <div class="clearer"></div> 456 </div> 457 </div> 458 459 <div class="footer-wrapper"> 460 <div class="footer" > 461 <div class="right" ><i>Release: 1.21.3</i><br /> 462 © <a href="../copyright.html">Copyright</a> 1985-2024, MIT. 463 </div> 464 <div class="left"> 465 466 <a href="../index.html" title="Full Table of Contents" 467 >Contents</a> | 468 <a href="backup_host.html" title="Backups of secure hosts" 469 >previous</a> | 470 <a href="otp.html" title="OTP Preauthentication" 471 >next</a> | 472 <a href="../genindex.html" title="General Index" 473 >index</a> | 474 <a href="../search.html" title="Enter search criteria" 475 >Search</a> | 476 <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__PKINIT configuration">feedback</a> 477 </div> 478 </div> 479 </div> 480 481 </body> 482</html>