EVOLUTION-MANAGER
Edit File: pkinit.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>PKINIT configuration — 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.15.1', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </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="author" title="About these documents" href="../about.html" /> <link rel="copyright" title="Copyright" href="../copyright.html" /> <link rel="top" title="MIT Kerberos Documentation" href="../index.html" /> <link rel="up" title="For administrators" href="index.html" /> <link rel="next" title="OTP Preauthentication" href="otp.html" /> <link rel="prev" title="Backups of secure hosts" href="backup_host.html" /> </head> <body> <div class="header-wrapper"> <div class="header"> <h1><a href="../index.html">MIT Kerberos Documentation</a></h1> <div class="rel"> <a href="../index.html" title="Full Table of Contents" accesskey="C">Contents</a> | <a href="backup_host.html" title="Backups of secure hosts" accesskey="P">previous</a> | <a href="otp.html" title="OTP Preauthentication" accesskey="N">next</a> | <a href="../genindex.html" title="General Index" accesskey="I">index</a> | <a href="../search.html" title="Enter search criteria" accesskey="S">Search</a> | <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__PKINIT configuration">feedback</a> </div> </div> </div> <div class="content-wrapper"> <div class="content"> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="pkinit-configuration"> <span id="pkinit"></span><h1>PKINIT configuration<a class="headerlink" href="#pkinit-configuration" title="Permalink to this headline">¶</a></h1> <p>PKINIT is a preauthentication mechanism for Kerberos 5 which uses X.509 certificates to authenticate the KDC to clients and vice versa. PKINIT can also be used to enable anonymity support, allowing clients to communicate securely with the KDC or with application servers without authenticating as a particular client principal.</p> <div class="section" id="creating-certificates"> <h2>Creating certificates<a class="headerlink" href="#creating-certificates" title="Permalink to this headline">¶</a></h2> <p>PKINIT requires an X.509 certificate for the KDC and one for each client principal which will authenticate using PKINIT. For anonymous PKINIT, a KDC certificate is required, but client certificates are not. A commercially issued server certificate can be used for the KDC certificate, but generally cannot be used for client certificates.</p> <p>The instruction in this section describe how to establish a certificate authority and create standard PKINIT certificates. Skip this section if you are using a commercially issued server certificate as the KDC certificate for anonymous PKINIT, or if you are configuring a client to use an Active Directory KDC.</p> <div class="section" id="generating-a-certificate-authority-certificate"> <h3>Generating a certificate authority certificate<a class="headerlink" href="#generating-a-certificate-authority-certificate" title="Permalink to this headline">¶</a></h3> <p>You can establish a new certificate authority (CA) for use with a PKINIT deployment with the commands:</p> <div class="highlight-python"><pre>openssl genrsa -out cakey.pem 2048 openssl req -key cakey.pem -new -x509 -out cacert.pem -days 3650</pre> </div> <p>The second command will ask for the values of several certificate fields. These fields can be set to any values. You can adjust the expiration time of the CA certificate by changing the number after <tt class="docutils literal"><span class="pre">-days</span></tt>. Since the CA certificate must be deployed to client machines each time it changes, it should normally have an expiration time far in the future; however, expiration times after 2037 may cause interoperability issues in rare circumstances.</p> <p>The result of these commands will be two files, cakey.pem and cacert.pem. cakey.pem will contain a 2048-bit RSA private key, which must be carefully protected. cacert.pem will contain the CA certificate, which must be placed in the filesytems of the KDC and each client host. cakey.pem will be required to create KDC and client certificates.</p> </div> <div class="section" id="generating-a-kdc-certificate"> <h3>Generating a KDC certificate<a class="headerlink" href="#generating-a-kdc-certificate" title="Permalink to this headline">¶</a></h3> <p>A KDC certificate for use with PKINIT is required to have some unusual fields, which makes generating them with OpenSSL somewhat complicated. First, you will need a file containing the following:</p> <div class="highlight-python"><pre>[kdc_cert] basicConstraints=CA:FALSE keyUsage=nonRepudiation,digitalSignature,keyEncipherment,keyAgreement extendedKeyUsage=1.3.6.1.5.2.3.5 subjectKeyIdentifier=hash authorityKeyIdentifier=keyid,issuer issuerAltName=issuer:copy subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:kdc_princ_name [kdc_princ_name] realm=EXP:0,GeneralString:${ENV::REALM} principal_name=EXP:1,SEQUENCE:kdc_principal_seq [kdc_principal_seq] name_type=EXP:0,INTEGER:1 name_string=EXP:1,SEQUENCE:kdc_principals [kdc_principals] princ1=GeneralString:krbtgt princ2=GeneralString:${ENV::REALM}</pre> </div> <p>If the above contents are placed in extensions.kdc, you can generate and sign a KDC certificate with the following commands:</p> <div class="highlight-python"><pre>openssl genrsa -out kdckey.pem 2048 openssl req -new -out kdc.req -key kdckey.pem env REALM=YOUR_REALMNAME openssl x509 -req -in kdc.req \ -CAkey cakey.pem -CA cacert.pem -out kdc.pem -days 365 \ -extfile extensions.kdc -extensions kdc_cert -CAcreateserial rm kdc.req</pre> </div> <p>The second command will ask for the values of certificate fields, which can be set to any values. In the third command, substitute your KDC’s realm name for YOUR_REALMNAME. You can adjust the certificate’s expiration date by changing the number after <tt class="docutils literal"><span class="pre">-days</span></tt>. Remember to create a new KDC certificate before the old one expires.</p> <p>The result of this operation will be in two files, kdckey.pem and kdc.pem. Both files must be placed in the KDC’s filesystem. kdckey.pem, which contains the KDC’s private key, must be carefully protected.</p> <p>If you examine the KDC certificate with <tt class="docutils literal"><span class="pre">openssl</span> <span class="pre">x509</span> <span class="pre">-in</span> <span class="pre">kdc.pem</span> <span class="pre">-text</span> <span class="pre">-noout</span></tt>, OpenSSL will not know how to display the KDC principal name in the Subject Alternative Name extension, so it will appear as <tt class="docutils literal"><span class="pre">othername:<unsupported></span></tt>. This is normal and does not mean anything is wrong with the KDC certificate.</p> </div> <div class="section" id="generating-client-certificates"> <h3>Generating client certificates<a class="headerlink" href="#generating-client-certificates" title="Permalink to this headline">¶</a></h3> <p>PKINIT client certificates also must have some unusual certificate fields. To generate a client certificate with OpenSSL for a single-component principal name, you will need an extensions file (different from the KDC extensions file above) containing:</p> <div class="highlight-python"><pre>[client_cert] basicConstraints=CA:FALSE keyUsage=digitalSignature,keyEncipherment,keyAgreement extendedKeyUsage=1.3.6.1.5.2.3.4 subjectKeyIdentifier=hash authorityKeyIdentifier=keyid,issuer issuerAltName=issuer:copy subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name [princ_name] realm=EXP:0,GeneralString:${ENV::REALM} principal_name=EXP:1,SEQUENCE:principal_seq [principal_seq] name_type=EXP:0,INTEGER:1 name_string=EXP:1,SEQUENCE:principals [principals] princ1=GeneralString:${ENV::CLIENT}</pre> </div> <p>If the above contents are placed in extensions.client, you can generate and sign a client certificate with the following commands:</p> <div class="highlight-python"><pre>openssl genrsa -out clientkey.pem 2048 openssl req -new -key clientkey.pem -out client.req env REALM=YOUR_REALMNAME CLIENT=YOUR_PRINCNAME openssl x509 \ -CAkey cakey.pem -CA cacert.pem -req -in client.req \ -extensions client_cert -extfile extensions.client \ -days 365 -out client.pem rm client.req</pre> </div> <p>Normally, the first two commands should be run on the client host, and the resulting client.req file transferred to the certificate authority host for the third command. As in the previous steps, the second command will ask for the values of certificate fields, which can be set to any values. In the third command, substitute your realm’s name for YOUR_REALMNAME and the client’s principal name (without realm) for YOUR_PRINCNAME. You can adjust the certificate’s expiration date by changing the number after <tt class="docutils literal"><span class="pre">-days</span></tt>.</p> <p>The result of this operation will be two files, clientkey.pem and client.pem. Both files must be present on the client’s host; clientkey.pem, which contains the client’s private key, must be protected from access by others.</p> <p>As in the KDC certificate, OpenSSL will display the client principal name as <tt class="docutils literal"><span class="pre">othername:<unsupported></span></tt> in the Subject Alternative Name extension of a PKINIT client certificate.</p> <p>If the client principal name contains more than one component (e.g. <tt class="docutils literal"><span class="pre">host/example.com@REALM</span></tt>), the <tt class="docutils literal"><span class="pre">[principals]</span></tt> section of <tt class="docutils literal"><span class="pre">extensions.client</span></tt> must be altered to contain multiple entries. (Simply setting <tt class="docutils literal"><span class="pre">CLIENT</span></tt> to <tt class="docutils literal"><span class="pre">host/example.com</span></tt> would generate a certificate for <tt class="docutils literal"><span class="pre">host\/example.com@REALM</span></tt> which would not match the multi-component principal name.) For a two-component principal, the section should read:</p> <div class="highlight-python"><pre>[principals] princ1=GeneralString:${ENV::CLIENT1} princ2=GeneralString:${ENV::CLIENT2}</pre> </div> <p>The environment variables <tt class="docutils literal"><span class="pre">CLIENT1</span></tt> and <tt class="docutils literal"><span class="pre">CLIENT2</span></tt> must then be set to the first and second components when running <tt class="docutils literal"><span class="pre">openssl</span> <span class="pre">x509</span></tt>.</p> </div> </div> <div class="section" id="configuring-the-kdc"> <h2>Configuring the KDC<a class="headerlink" href="#configuring-the-kdc" title="Permalink to this headline">¶</a></h2> <p>The KDC must have filesystem access to the KDC certificate (kdc.pem) and the KDC private key (kdckey.pem). Configure the following relation in the KDC’s <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><em>kdc.conf</em></a> file, either in the <a class="reference internal" href="conf_files/kdc_conf.html#kdcdefaults"><em>[kdcdefaults]</em></a> section or in a <a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms"><em>[realms]</em></a> subsection (with appropriate pathnames):</p> <div class="highlight-python"><pre>pkinit_identity = FILE:/var/lib/krb5kdc/kdc.pem,/var/lib/krb5kdc/kdckey.pem</pre> </div> <p>If any clients will authenticate using regular (as opposed to anonymous) PKINIT, the KDC must also have filesystem access to the CA certificate (cacert.pem), and the following configuration (with the appropriate pathname):</p> <div class="highlight-python"><pre>pkinit_anchors = FILE:/var/lib/krb5kdc/cacert.pem</pre> </div> <p>Because of the larger size of requests and responses using PKINIT, you may also need to allow TCP access to the KDC:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">kdc_tcp_listen</span> <span class="o">=</span> <span class="mi">88</span> </pre></div> </div> <p>Restart the <a class="reference internal" href="admin_commands/krb5kdc.html#krb5kdc-8"><em>krb5kdc</em></a> daemon to pick up the configuration changes.</p> <p>The principal entry for each PKINIT-using client must be configured to require preauthentication. Ensure this with the command:</p> <div class="highlight-python"><pre>kadmin -q 'modprinc +requires_preauth YOUR_PRINCNAME'</pre> </div> <p>Starting with release 1.12, it is possible to remove the long-term keys of a principal entry, which can save some space in the database and help to clarify some PKINIT-related error conditions by not asking for a password:</p> <div class="highlight-python"><pre>kadmin -q 'purgekeys -all YOUR_PRINCNAME'</pre> </div> <p>These principal options can also be specified at principal creation time as follows:</p> <div class="highlight-python"><pre>kadmin -q 'add_principal +requires_preauth -nokey YOUR_PRINCNAME'</pre> </div> <p>By default, the KDC requires PKINIT client certificates to have the standard Extended Key Usage and Subject Alternative Name attributes for PKINIT. Starting in release 1.16, it is possible to authorize client certificates based on the subject or other criteria instead of the standard PKINIT Subject Alternative Name, by setting the <strong>pkinit_cert_match</strong> string attribute on each client principal entry. For example:</p> <div class="highlight-python"><pre>kadmin set_string user@REALM pkinit_cert_match "<SUBJECT>CN=user@REALM$"</pre> </div> <p>The <strong>pkinit_cert_match</strong> string attribute follows the syntax used by the <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><em>krb5.conf</em></a> <strong>pkinit_cert_match</strong> relation. To allow the use of non-PKINIT client certificates, it will also be necessary to disable key usage checking using the <strong>pkinit_eku_checking</strong> relation; for example:</p> <div class="highlight-python"><pre>[kdcdefaults] pkinit_eku_checking = none</pre> </div> </div> <div class="section" id="configuring-the-clients"> <h2>Configuring the clients<a class="headerlink" href="#configuring-the-clients" title="Permalink to this headline">¶</a></h2> <p>Client hosts must be configured to trust the issuing authority for the KDC certificate. For a newly established certificate authority, the client host must have filesystem access to the CA certificate (cacert.pem) and the following relation in <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><em>krb5.conf</em></a> in the appropriate <a class="reference internal" href="conf_files/krb5_conf.html#realms"><em>[realms]</em></a> subsection (with appropriate pathnames):</p> <div class="highlight-python"><pre>pkinit_anchors = FILE:/etc/krb5/cacert.pem</pre> </div> <p>If the KDC certificate is a commercially issued server certificate, the issuing certificate is most likely included in a system directory. You can specify it by filename as above, or specify the whole directory like so:</p> <div class="highlight-python"><pre>pkinit_anchors = DIR:/etc/ssl/certs</pre> </div> <p>A commercially issued server certificate will usually not have the standard PKINIT principal name or Extended Key Usage extensions, so the following additional configuration is required:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">pkinit_eku_checking</span> <span class="o">=</span> <span class="n">kpServerAuth</span> <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> </pre></div> </div> <p>Multiple <strong>pkinit_kdc_hostname</strong> relations can be configured to recognize multiple KDC certificates. If the KDC is an Active Directory domain controller, setting <strong>pkinit_kdc_hostname</strong> is necessary, but it should not be necessary to set <strong>pkinit_eku_checking</strong>.</p> <p>To perform regular (as opposed to anonymous) PKINIT authentication, a client host must have filesystem access to a client certificate (client.pem), and the corresponding private key (clientkey.pem). Configure the following relations in the client host’s <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><em>krb5.conf</em></a> file in the appropriate <a class="reference internal" href="conf_files/krb5_conf.html#realms"><em>[realms]</em></a> subsection (with appropriate pathnames):</p> <div class="highlight-python"><pre>pkinit_identities = FILE:/etc/krb5/client.pem,/etc/krb5/clientkey.pem</pre> </div> <p>If the KDC and client are properly configured, it should now be possible to run <tt class="docutils literal"><span class="pre">kinit</span> <span class="pre">username</span></tt> without entering a password.</p> </div> <div class="section" id="anonymous-pkinit"> <span id="id1"></span><h2>Anonymous PKINIT<a class="headerlink" href="#anonymous-pkinit" title="Permalink to this headline">¶</a></h2> <p>Anonymity support in Kerberos allows a client to obtain a ticket without authenticating as any particular principal. Such a ticket can be used as a FAST armor ticket, or to securely communicate with an application server anonymously.</p> <p>To configure anonymity support, you must generate or otherwise procure a KDC certificate and configure the KDC host, but you do not need to generate any client certificates. On the KDC, you must set the <strong>pkinit_identity</strong> variable to provide the KDC certificate, but do not need to set the <strong>pkinit_anchors</strong> variable or store the issuing certificate if you won’t have any client certificates to verify. On client hosts, you must set the <strong>pkinit_anchors</strong> variable (and possibly <strong>pkinit_kdc_hostname</strong> and <strong>pkinit_eku_checking</strong>) in order to trust the issuing authority for the KDC certificate, but do not need to set the <strong>pkinit_identities</strong> variable.</p> <p>Anonymity support is not enabled by default. To enable it, you must create the principal <tt class="docutils literal"><span class="pre">WELLKNOWN/ANONYMOUS</span></tt> using the command:</p> <div class="highlight-python"><pre>kadmin -q 'addprinc -randkey WELLKNOWN/ANONYMOUS'</pre> </div> <p>Some Kerberos deployments include application servers which lack proper access control, and grant some level of access to any user who can authenticate. In such an environment, enabling anonymity support on the KDC would present a security issue. If you need to enable anonymity support for TGTs (for use as FAST armor tickets) without enabling anonymous authentication to application servers, you can set the variable <strong>restrict_anonymous_to_tgt</strong> to <tt class="docutils literal"><span class="pre">true</span></tt> in the appropriate <a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms"><em>[realms]</em></a> subsection of the KDC’s <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><em>kdc.conf</em></a> file.</p> <p>To obtain anonymous credentials on a client, run <tt class="docutils literal"><span class="pre">kinit</span> <span class="pre">-n</span></tt>, or <tt class="docutils literal"><span class="pre">kinit</span> <span class="pre">-n</span> <span class="pre">@REALMNAME</span></tt> to specify a realm. The resulting tickets will have the client name <tt class="docutils literal"><span class="pre">WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS</span></tt>.</p> </div> </div> </div> </div> </div> </div> <div class="sidebar"> <h2>On this page</h2> <ul> <li><a class="reference internal" href="#">PKINIT configuration</a><ul> <li><a class="reference internal" href="#creating-certificates">Creating certificates</a><ul> <li><a class="reference internal" href="#generating-a-certificate-authority-certificate">Generating a certificate authority certificate</a></li> <li><a class="reference internal" href="#generating-a-kdc-certificate">Generating a KDC certificate</a></li> <li><a class="reference internal" href="#generating-client-certificates">Generating client certificates</a></li> </ul> </li> <li><a class="reference internal" href="#configuring-the-kdc">Configuring the KDC</a></li> <li><a class="reference internal" href="#configuring-the-clients">Configuring the clients</a></li> <li><a class="reference internal" href="#anonymous-pkinit">Anonymous PKINIT</a></li> </ul> </li> </ul> <br/> <h2>Table of contents</h2> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../user/index.html">For users</a></li> <li class="toctree-l1 current"><a class="reference internal" href="index.html">For administrators</a><ul class="current"> <li class="toctree-l2"><a class="reference internal" href="install.html">Installation guide</a></li> <li class="toctree-l2"><a class="reference internal" href="conf_files/index.html">Configuration Files</a></li> <li class="toctree-l2"><a class="reference internal" href="realm_config.html">Realm configuration decisions</a></li> <li class="toctree-l2"><a class="reference internal" href="database.html">Database administration</a></li> <li class="toctree-l2"><a class="reference internal" href="lockout.html">Account lockout</a></li> <li class="toctree-l2"><a class="reference internal" href="conf_ldap.html">Configuring Kerberos with OpenLDAP back-end</a></li> <li class="toctree-l2"><a class="reference internal" href="appl_servers.html">Application servers</a></li> <li class="toctree-l2"><a class="reference internal" href="host_config.html">Host configuration</a></li> <li class="toctree-l2"><a class="reference internal" href="backup_host.html">Backups of secure hosts</a></li> <li class="toctree-l2 current"><a class="current reference internal" href="">PKINIT configuration</a><ul class="simple"> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="otp.html">OTP Preauthentication</a></li> <li class="toctree-l2"><a class="reference internal" href="princ_dns.html">Principal names and DNS</a></li> <li class="toctree-l2"><a class="reference internal" href="enctypes.html">Encryption types</a></li> <li class="toctree-l2"><a class="reference internal" href="https.html">HTTPS proxy configuration</a></li> <li class="toctree-l2"><a class="reference internal" href="auth_indicator.html">Authentication indicators</a></li> <li class="toctree-l2"><a class="reference internal" href="admin_commands/index.html">Administration programs</a></li> <li class="toctree-l2"><a class="reference internal" href="../mitK5defaults.html">MIT Kerberos defaults</a></li> <li class="toctree-l2"><a class="reference internal" href="env_variables.html">Environment variables</a></li> <li class="toctree-l2"><a class="reference internal" href="troubleshoot.html">Troubleshooting</a></li> <li class="toctree-l2"><a class="reference internal" href="advanced/index.html">Advanced topics</a></li> <li class="toctree-l2"><a class="reference internal" href="various_envs.html">Various links</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../appdev/index.html">For application developers</a></li> <li class="toctree-l1"><a class="reference internal" href="../plugindev/index.html">For plugin module developers</a></li> <li class="toctree-l1"><a class="reference internal" href="../build/index.html">Building Kerberos V5</a></li> <li class="toctree-l1"><a class="reference internal" href="../basic/index.html">Kerberos V5 concepts</a></li> <li class="toctree-l1"><a class="reference internal" href="../formats/index.html">Protocols and file formats</a></li> <li class="toctree-l1"><a class="reference internal" href="../mitK5features.html">MIT Kerberos features</a></li> <li class="toctree-l1"><a class="reference internal" href="../build_this.html">How to build this documentation from the source</a></li> <li class="toctree-l1"><a class="reference internal" href="../about.html">Contributing to the MIT Kerberos Documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li> </ul> <br/> <h4><a href="../index.html">Full Table of Contents</a></h4> <h4>Search</h4> <form class="search" action="../search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <div class="clearer"></div> </div> </div> <div class="footer-wrapper"> <div class="footer" > <div class="right" ><i>Release: 1.15.1</i><br /> © <a href="../copyright.html">Copyright</a> 1985-2017, MIT. </div> <div class="left"> <a href="../index.html" title="Full Table of Contents" >Contents</a> | <a href="backup_host.html" title="Backups of secure hosts" >previous</a> | <a href="otp.html" title="OTP Preauthentication" >next</a> | <a href="../genindex.html" title="General Index" >index</a> | <a href="../search.html" title="Enter search criteria" >Search</a> | <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__PKINIT configuration">feedback</a> </div> </div> </div> </body> </html>