krb5 commit [krb5-1.11]: Improve PKINIT certificate documentation
Tom Yu
tlyu at mit.edu
Fri Feb 6 18:11:48 EST 2015
https://github.com/krb5/krb5/commit/7f5e091247e242bcc3085bcffbcab6023899c59e
commit 7f5e091247e242bcc3085bcffbcab6023899c59e
Author: Greg Hudson <ghudson at mit.edu>
Date: Fri Jun 6 17:41:51 2014 -0400
Improve PKINIT certificate documentation
Describe how to use a commercially-issued server certificate for
anonymous PKINIT. Separate the KDC and client configuration
instructions so that the steps necessary for anonymous PKINIT are not
combined with the additional steps necessary for regular PKINIT.
Describe kpServerAuth as the EKU used in commercially issued server
certificates, not as the value used by Microsoft (which does not
appear to be true according to [MS-PKCA]).
(cherry picked from commit 677c7753923e5efa078074611d4474fbcc10f6a1)
ticket: 8105 (new)
version_fixed: 1.11.6
status: resolved
doc/admin/conf_files/krb5_conf.rst | 3 +-
doc/admin/pkinit.rst | 117 ++++++++++++++++++++++++++----------
2 files changed, 86 insertions(+), 34 deletions(-)
diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
index fdc1f62..417373a 100644
--- a/doc/admin/conf_files/krb5_conf.rst
+++ b/doc/admin/conf_files/krb5_conf.rst
@@ -918,7 +918,8 @@ PKINIT krb5.conf options
**kpServerAuth**
If **kpServerAuth** is specified, a KDC certificate with the
- id-kp-serverAuth EKU as used by Microsoft will be accepted.
+ id-kp-serverAuth EKU will be accepted. This key usage value
+ is used in most commercially issued server certificates.
**none**
If **none** is specified, then the KDC certificate will not be
diff --git a/doc/admin/pkinit.rst b/doc/admin/pkinit.rst
index 9ab680e..694fed0 100644
--- a/doc/admin/pkinit.rst
+++ b/doc/admin/pkinit.rst
@@ -7,16 +7,25 @@ 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.
-Configuring PKINIT requires establishing a certificate authority (or
-using an existing one), and using the authority to sign certificates
-for the KDC and for each client principal. These instructions will
-describe how to generate the necessary certificates using OpenSSL, and
-then explain how to configure the KDC and clients once the
-certificates are in hand.
+
+Creating certificates
+---------------------
+
+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.
+
+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.
Generating a certificate authority certificate
-----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can establish a new certificate authority (CA) for use with a
PKINIT deployment with the commands::
@@ -41,7 +50,7 @@ certificates.
Generating a KDC certificate
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A KDC certificate for use with PKINIT is required to have some unusual
fields, which makes generating them with OpenSSL somewhat complicated.
@@ -89,9 +98,15 @@ 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 ``openssl x509 -in kdc.pem
+-text -noout``, OpenSSL will not know how to display the KDC principal
+name in the Subject Alternative Name extension, so it will appear as
+``othername:<unsupported>``. This is normal and does not mean
+anything is wrong with the KDC certificate.
+
Generating client certificates
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PKINIT client certificates also must have some unusual certificate
fields. To generate a client certificate with OpenSSL, you will need
@@ -143,22 +158,31 @@ 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 ``othername:<unsupported>`` in the Subject Alternative Name
+extension of a PKINIT client certificate.
+
Configuring the KDC
-------------------
-The KDC must have filesystem access to the CA certificate
-(cacert.pem), the KDC certificate (kdc.pem), and the KDC private key
-(kdckey.pem). Configure the following relations in the KDC's
-:ref:`kdc.conf(5)` file, either in the :ref:`kdcdefaults` section or
-in a :ref:`kdc_realms` subsection::
+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 :ref:`kdc.conf(5)` file, either in the
+:ref:`kdcdefaults` section or in a :ref:`kdc_realms` subsection (with
+appropriate pathnames)::
pkinit_identity = FILE:/var/lib/krb5kdc/kdc.pem,/var/lib/krb5kdc/kdckey.pem
+
+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)::
+
pkinit_anchors = FILE:/var/lib/krb5kdc/cacert.pem
-Adjust the pathnames to match the paths of the three files. Because
-of the larger size of requests and responses using PKINIT, you may
-also need to allow TCP access to the KDC::
+Because of the larger size of requests and responses using PKINIT, you
+may also need to allow TCP access to the KDC::
kdc_tcp_ports = 88
@@ -186,16 +210,42 @@ time as follows::
Configuring the clients
-----------------------
-To perform PKINIT authentication, a client host must have filesystem
-access to the CA certificate (cacert.pem), the client certificate
-(client.pem), and the client private key (clientkey.pem). Configure
-the following relations in the client host's :ref:`krb5.conf(5)` file
-in the appropriate :ref:`realms` subsection::
+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 :ref:`krb5.conf(5)` in the
+appropriate :ref:`realms` subsection (with appropriate pathnames)::
pkinit_anchors = FILE:/etc/krb5/cacert.pem
- pkinit_identities = FILE:/etc/krb5/client.pem,/etc/krb5/clientkey.pem
-Adjust the pathnames to match the paths of the three files.
+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::
+
+ pkinit_anchors = DIR:/etc/ssl/certs
+
+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::
+
+ pkinit_eku_checking = kpServerAuth
+ pkinit_kdc_hostname = hostname.of.kdc.certificate
+
+Multiple **pkinit_kdc_hostname** relations can be configured to
+recognize multiple KDC certificates. If the KDC is an Active
+Directory domain controller, setting **pkinit_kdc_hostname** is
+necessary, but it should not be necessary to set
+**pkinit_eku_checking**.
+
+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
+:ref:`krb5.conf(5)` file in the appropriate :ref:`realms` subsection
+(with appropriate pathnames)::
+
+ pkinit_identities = FILE:/etc/krb5/client.pem,/etc/krb5/clientkey.pem
If the KDC and client are properly configured, it should now be
possible to run ``kinit username`` without entering a password.
@@ -211,15 +261,16 @@ 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.
-To configure anonymity support, you must follow the steps above for
-generating a KDC certificate and configuring the KDC host, but you do
-not need to generate any client certificates. On the KDC, you must
-set the **pkinit_identity** variable to provide the KDC certificate,
-but do not need to set the **pkinit_anchors** variable or store the
-cacert.pem file if you won't have any client certificates to verify.
-On client hosts, you must store the cacert.pem file and set the
-**pkinit_anchors** variable in order to verify the KDC certificate,
-but do not need to set the **pkinit_identities** variable.
+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
+**pkinit_identity** variable to provide the KDC certificate, but do
+not need to set the **pkinit_anchors** variable or store the issuing
+certificate if you won't have any client certificates to verify. On
+client hosts, you must set the **pkinit_anchors** variable (and
+possibly **pkinit_kdc_hostname** and **pkinit_eku_checking**) in order
+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 ``WELLKNOWN/ANONYMOUS`` using the command::
More information about the cvs-krb5
mailing list