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

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

-rw-r--r--

doc/html/admin/pkinit.html

158

1 files changed, 76 insertions, 82 deletions

diff --git a/doc/html/admin/pkinit.html b/doc/html/admin/pkinit.html
index 4b5eab334b49..40791a2e8f76 100644
--- a/doc/html/admin/pkinit.html
+++ b/doc/html/admin/pkinit.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>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.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,14 +52,14 @@

- <div class="section" id="pkinit-configuration">

+ <section id="pkinit-configuration">

<h1>PKINIT configuration<a class="headerlink" href="#pkinit-configuration" title="Permalink to this headline">¶</a></h1>

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.

-<div class="section" id="creating-certificates">

+<section id="creating-certificates">

<h2>Creating certificates<a class="headerlink" href="#creating-certificates" title="Permalink to this headline">¶</a></h2>

PKINIT requires an X.509 certificate for the KDC and one for each

client principal which will authenticate using PKINIT. For anonymous

@@ -80,18 +71,18 @@ 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.

-<div class="section" id="generating-a-certificate-authority-certificate">

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

You can establish a new certificate authority (CA) for use with a

PKINIT deployment with the commands:

-<div class="highlight-default"><div class="highlight"><pre>openssl genrsa -out cakey.pem 2048

+<div class="highlight-default notranslate"><div class="highlight"><pre>openssl genrsa -out cakey.pem 2048

openssl req -key cakey.pem -new -x509 -out cacert.pem -days 3650

</pre></div>

</div>

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

-<code class="docutils literal">-days</code>. Since the CA certificate must be deployed to client

+<code class="docutils literal notranslate">-days</code>. 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.

@@ -101,13 +92,13 @@ must be carefully protected. cacert.pem will contain the CA

certificate, which must be placed in the filesystems of the KDC and

each client host. cakey.pem will be required to create KDC and client

certificates.

-</div>

-<div class="section" id="generating-a-kdc-certificate">

+</section>

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

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:

-<div class="highlight-default"><div class="highlight"><pre>[kdc_cert]

+<div class="highlight-default notranslate"><div class="highlight"><pre>[kdc_cert]

basicConstraints=CA:FALSE

keyUsage=nonRepudiation,digitalSignature,keyEncipherment,keyAgreement

extendedKeyUsage=1.3.6.1.5.2.3.5

@@ -131,7 +122,7 @@ princ2=GeneralString:${ENV::REALM}

</div>

If the above contents are placed in extensions.kdc, you can generate

and sign a KDC certificate with the following commands:

-<div class="highlight-default"><div class="highlight"><pre>openssl genrsa -out kdckey.pem 2048

+<div class="highlight-default notranslate"><div class="highlight"><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 \

@@ -142,25 +133,25 @@ and sign a KDC certificate with the following commands:

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 <code class="docutils literal">-days</code>. Remember to

+expiration date by changing the number after <code class="docutils literal notranslate">-days</code>. Remember to

create a new KDC certificate before the old one expires.

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.

-If you examine the KDC certificate with <code class="docutils literal">openssl x509 -in kdc.pem

+If you examine the KDC certificate with <code class="docutils literal notranslate">openssl x509 -in kdc.pem

-text -noout</code>, OpenSSL will not know how to display the KDC principal

name in the Subject Alternative Name extension, so it will appear as

-<code class="docutils literal">othername:<unsupported></code>. This is normal and does not mean

+<code class="docutils literal notranslate">othername:<unsupported></code>. This is normal and does not mean

anything is wrong with the KDC certificate.

-</div>

-<div class="section" id="generating-client-certificates">

+</section>

+<section id="generating-client-certificates">

<h3>Generating client certificates<a class="headerlink" href="#generating-client-certificates" title="Permalink to this headline">¶</a></h3>

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:

-<div class="highlight-default"><div class="highlight"><pre>[client_cert]

+<div class="highlight-default notranslate"><div class="highlight"><pre>[client_cert]

basicConstraints=CA:FALSE

keyUsage=digitalSignature,keyEncipherment,keyAgreement

extendedKeyUsage=1.3.6.1.5.2.3.4

@@ -183,7 +174,7 @@ princ1=GeneralString:${ENV::CLIENT}

</div>

If the above contents are placed in extensions.client, you can

generate and sign a client certificate with the following commands:

-<div class="highlight-default"><div class="highlight"><pre>openssl genrsa -out clientkey.pem 2048

+<div class="highlight-default notranslate"><div class="highlight"><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 \

@@ -199,69 +190,69 @@ 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 <code class="docutils literal">-days</code>.

+changing the number after <code class="docutils literal notranslate">-days</code>.

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.

As in the KDC certificate, OpenSSL will display the client principal

-name as <code class="docutils literal">othername:<unsupported></code> in the Subject Alternative Name

+name as <code class="docutils literal notranslate">othername:<unsupported></code> in the Subject Alternative Name

extension of a PKINIT client certificate.

If the client principal name contains more than one component

-(e.g. <code class="docutils literal">host/example.com@REALM</code>), the <code class="docutils literal">[principals]</code> section of

-<code class="docutils literal">extensions.client</code> must be altered to contain multiple entries.

-(Simply setting <code class="docutils literal">CLIENT</code> to <code class="docutils literal">host/example.com</code> would generate a

-certificate for <code class="docutils literal">host\/example.com@REALM</code> which would not match the

+(e.g. <code class="docutils literal notranslate">host/example.com@REALM</code>), the <code class="docutils literal notranslate">[principals]</code> section of

+<code class="docutils literal notranslate">extensions.client</code> must be altered to contain multiple entries.

+(Simply setting <code class="docutils literal notranslate">CLIENT</code> to <code class="docutils literal notranslate">host/example.com</code> would generate a

+certificate for <code class="docutils literal notranslate">host\/example.com@REALM</code> which would not match the

multi-component principal name.) For a two-component principal, the

section should read:

-<div class="highlight-default"><div class="highlight"><pre>[principals]

+<div class="highlight-default notranslate"><div class="highlight"><pre>[principals]

princ1=GeneralString:${ENV::CLIENT1}

princ2=GeneralString:${ENV::CLIENT2}

</pre></div>

</div>

-The environment variables <code class="docutils literal">CLIENT1</code> and <code class="docutils literal">CLIENT2</code> must then be set

-to the first and second components when running <code class="docutils literal">openssl x509</code>.

-</div>

-<div class="section" id="configuring-the-kdc">

+The environment variables <code class="docutils literal notranslate">CLIENT1</code> and <code class="docutils literal notranslate">CLIENT2</code> must then be set

+to the first and second components when running <code class="docutils literal notranslate">openssl x509</code>.

+</section>

+<section id="configuring-the-kdc">

<h2>Configuring the KDC<a class="headerlink" href="#configuring-the-kdc" title="Permalink to this headline">¶</a></h2>

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">kdc.conf</a> file, either in the

<a class="reference internal" href="conf_files/kdc_conf.html#kdcdefaults">[kdcdefaults]</a> section or in a <a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms">[realms]</a> subsection (with

appropriate pathnames):

-<div class="highlight-default"><div class="highlight"><pre>pkinit_identity = FILE:/var/lib/krb5kdc/kdc.pem,/var/lib/krb5kdc/kdckey.pem

+<div class="highlight-default notranslate"><div class="highlight"><pre>pkinit_identity = FILE:/var/lib/krb5kdc/kdc.pem,/var/lib/krb5kdc/kdckey.pem

</pre></div>

</div>

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

-<div class="highlight-default"><div class="highlight"><pre>pkinit_anchors = FILE:/var/lib/krb5kdc/cacert.pem

+<div class="highlight-default notranslate"><div class="highlight"><pre>pkinit_anchors = FILE:/var/lib/krb5kdc/cacert.pem

</pre></div>

</div>

Because of the larger size of requests and responses using PKINIT, you

may also need to allow TCP access to the KDC:

-<div class="highlight-default"><div class="highlight"><pre>kdc_tcp_listen = 88

+<div class="highlight-default notranslate"><div class="highlight"><pre>kdc_tcp_listen = 88

</pre></div>

</div>

Restart the <a class="reference internal" href="admin_commands/krb5kdc.html#krb5kdc-8">krb5kdc</a> daemon to pick up the configuration

changes.

The principal entry for each PKINIT-using client must be configured to

require preauthentication. Ensure this with the command:

-<div class="highlight-default"><div class="highlight"><pre>kadmin -q 'modprinc +requires_preauth YOUR_PRINCNAME'

+<div class="highlight-default notranslate"><div class="highlight"><pre>kadmin -q 'modprinc +requires_preauth YOUR_PRINCNAME'

</pre></div>

</div>

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:

</pre></div>

</div>

These principal options can also be specified at principal creation

time as follows:

</pre></div>

</div>

By default, the KDC requires PKINIT client certificates to have the

@@ -271,7 +262,7 @@ client certificates based on the subject or other criteria instead of

the standard PKINIT Subject Alternative Name, by setting the

pkinit_cert_match string attribute on each client principal entry.

For example:

-<div class="highlight-default"><div class="highlight"><pre>kadmin set_string user@REALM pkinit_cert_match "<SUBJECT>CN=user@REALM$"

+<div class="highlight-default notranslate"><div class="highlight"><pre>kadmin set_string user@REALM pkinit_cert_match "<SUBJECT>CN=user@REALM$"

</pre></div>

</div>

The pkinit_cert_match string attribute follows the syntax used by

@@ -279,32 +270,32 @@ the <a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><

use of non-PKINIT client certificates, it will also be necessary to

disable key usage checking using the pkinit_eku_checking relation;

for example:

-<div class="highlight-default"><div class="highlight"><pre>[kdcdefaults]

+<div class="highlight-default notranslate"><div class="highlight"><pre>[kdcdefaults]

pkinit_eku_checking = none

</pre></div>

</div>

-</div>

-<div class="section" id="configuring-the-clients">

+</section>

+<section id="configuring-the-clients">

<h2>Configuring the clients<a class="headerlink" href="#configuring-the-clients" title="Permalink to this headline">¶</a></h2>

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">krb5.conf</a> in the

appropriate <a class="reference internal" href="conf_files/krb5_conf.html#realms">[realms]</a> subsection (with appropriate pathnames):

-<div class="highlight-default"><div class="highlight"><pre>pkinit_anchors = FILE:/etc/krb5/cacert.pem

+<div class="highlight-default notranslate"><div class="highlight"><pre>pkinit_anchors = FILE:/etc/krb5/cacert.pem

</pre></div>

</div>

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:

-<div class="highlight-default"><div class="highlight"><pre>pkinit_anchors = DIR:/etc/ssl/certs

+<div class="highlight-default notranslate"><div class="highlight"><pre>pkinit_anchors = DIR:/etc/ssl/certs

</pre></div>

</div>

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:

-<div class="highlight-default"><div class="highlight"><pre>pkinit_eku_checking = kpServerAuth

+<div class="highlight-default notranslate"><div class="highlight"><pre>pkinit_eku_checking = kpServerAuth

pkinit_kdc_hostname = hostname.of.kdc.certificate

</pre></div>

</div>

@@ -319,13 +310,13 @@ client host must have filesystem access to a client certificate

Configure the following relations in the client host’s

<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5">krb5.conf</a> file in the appropriate <a class="reference internal" href="conf_files/krb5_conf.html#realms">[realms]</a> subsection

(with appropriate pathnames):

-<div class="highlight-default"><div class="highlight"><pre>pkinit_identities = FILE:/etc/krb5/client.pem,/etc/krb5/clientkey.pem

+<div class="highlight-default notranslate"><div class="highlight"><pre>pkinit_identities = FILE:/etc/krb5/client.pem,/etc/krb5/clientkey.pem

</pre></div>

</div>

If the KDC and client are properly configured, it should now be

-possible to run <code class="docutils literal">kinit username</code> without entering a password.

-</div>

-<div class="section" id="anonymous-pkinit">

+possible to run <code class="docutils literal notranslate">kinit username</code> without entering a password.

+</section>

+<section id="anonymous-pkinit">

<h2>Anonymous PKINIT<a class="headerlink" href="#anonymous-pkinit" title="Permalink to this headline">¶</a></h2>

Anonymity support in Kerberos allows a client to obtain a ticket

without authenticating as any particular principal. Such a ticket can

@@ -342,8 +333,8 @@ possibly pkinit_kdc_hostname and pkinit_eku_checking</s

to trust the issuing authority for the KDC certificate, but do not

need to set the pkinit_identities variable.

Anonymity support is not enabled by default. To enable it, you must

-create the principal <code class="docutils literal">WELLKNOWN/ANONYMOUS</code> using the command:

+create the principal <code class="docutils literal notranslate">WELLKNOWN/ANONYMOUS</code> using the command:

</pre></div>

</div>

Some Kerberos deployments include application servers which lack

@@ -352,14 +343,14 @@ 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 restrict_anonymous_to_tgt to <code class="docutils literal">true</code> in the

+the variable restrict_anonymous_to_tgt to <code class="docutils literal notranslate">true</code> in the

appropriate <a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms">[realms]</a> subsection of the KDC’s

<a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5">kdc.conf</a> file.

-To obtain anonymous credentials on a client, run <code class="docutils literal">kinit -n</code>, or

-<code class="docutils literal">kinit -n @REALMNAME</code> to specify a realm. The resulting tickets

-will have the client name <code class="docutils literal">WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS</code>.

-</div>

-<div class="section" id="freshness-tokens">

+To obtain anonymous credentials on a client, run <code class="docutils literal notranslate">kinit -n</code>, or

+<code class="docutils literal notranslate">kinit -n @REALMNAME</code> to specify a realm. The resulting tickets

+will have the client name <code class="docutils literal notranslate">WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS</code>.

+</section>

+<section id="freshness-tokens">

<h2>Freshness tokens<a class="headerlink" href="#freshness-tokens" title="Permalink to this headline">¶</a></h2>

Freshness tokens can ensure that the client has recently had access to

its certificate private key. If freshness tokens are not required by

@@ -370,25 +361,27 @@ client and are sent by the KDC when the client indicates support for

them. Because not all clients support freshness tokens yet, they are

not required by default. To check if freshness tokens are supported

by a realm’s clients, look in the KDC logs for the lines:

-<div class="highlight-default"><div class="highlight"><pre>PKINIT: freshness token received from <client principal>

+<div class="highlight-default notranslate"><div class="highlight"><pre>PKINIT: freshness token received from <client principal>

PKINIT: no freshness token received from <client principal>

</pre></div>

</div>

To require freshness tokens for all clients in a realm (except for

clients authenticating anonymously), set the

-pkinit_require_freshness variable to <code class="docutils literal">true</code> in the appropriate

+pkinit_require_freshness variable to <code class="docutils literal notranslate">true</code> in the appropriate

<a class="reference internal" href="conf_files/kdc_conf.html#kdc-realms">[realms]</a> subsection of the KDC’s <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5">kdc.conf</a> file. To

-test that this option is in effect, run <code class="docutils literal">kinit -X disable_freshness</code>

+test that this option is in effect, run <code class="docutils literal notranslate">kinit -X disable_freshness</code>

and verify that authentication is unsuccessful.

-</div>

+</section>

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

</div>

<ul>

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

@@ -457,6 +450,7 @@ and verify that authentication is unsuccessful.

</form>

</div>

</div>

@@ -464,8 +458,8 @@ and verify that authentication is unsuccessful.

- <div class="right" >Release: 1.21.2

+ <div class="right" >Release: 1.21.3

</div>