krb5 commit [krb5-1.11]: Discuss cert expiry, no-key princs in PKINIT docs

[Tom Yu]

https://github.com/krb5/krb5/commit/6d46afa0ea1283b7b85d1f0075ff274fa15aae60
commit 6d46afa0ea1283b7b85d1f0075ff274fa15aae60
Author: Greg Hudson <ghudson at mit.edu>
Date:   Mon Oct 14 18:14:00 2013 -0400

    Discuss cert expiry, no-key princs in PKINIT docs
    
    In pkinit.rst, add "-days" options to the example commands for
    creating certificate and briefly discuss the issue of expiration dates
    so that the administrator thinks about it.  In troubleshoot.rst, add
    an entry for the "certificate has expired" error which results from
    PKINIT (when linked with OpenSSL) when a certificate has expired.
    
    (cherry picked from commit f3977b6883f0172a2af9006522a1b35546f86749)
    
    ticket: 7727 (new)
    version_fixed: 1.11.4
    status: resolved

 doc/admin/pkinit.rst       |   32 ++++++++++++++++++++++++++------
 doc/admin/troubleshoot.rst |   20 ++++++++++++++++++++
 2 files changed, 46 insertions(+), 6 deletions(-)

diff --git a/doc/admin/pkinit.rst b/doc/admin/pkinit.rst
index 0ec8fb6..9ab680e 100644
--- a/doc/admin/pkinit.rst
+++ b/doc/admin/pkinit.rst
@@ -22,10 +22,15 @@ You can establish a new certificate authority (CA) for use with a
 PKINIT deployment with the commands::
 
     openssl genrsa -out cakey.pem 2048
-    openssl req -key cakey.pem -new -x509 -out cacert.pem
+    openssl req -key cakey.pem -new -x509 -out cacert.pem -days 3650
 
 The second command will ask for the values of several certificate
-fields.  These fields can be set to any values.
+fields.  These fields can be set to any values.  You can adjust the
+expiration time of the CA certificate by changing the number after
+``-days``.  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.
 
 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
@@ -69,13 +74,15 @@ and sign a KDC certificate with the following commands::
     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 \
+        -CAkey cakey.pem -CA cacert.pem -out kdc.pem -days 365 \
         -extfile extensions.kdc -extensions kdc_cert -CAcreateserial
     rm kdc.req
 
 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.
+KDC's realm name for YOUR_REALMNAME.  You can adjust the certificate's
+expiration date by changing the number after ``-days``.  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.
@@ -119,7 +126,7 @@ generate and sign a client certificate with the following commands::
     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 \
-        -out client.pem
+        -days 365 -out client.pem
     rm client.req
 
 Normally, the first two commands should be run on the client host, and
@@ -128,7 +135,8 @@ 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.
+YOUR_PRINCNAME.  You can adjust the certificate's expiration date by
+changing the number after ``-days``.
 
 The result of this operation will be two files, clientkey.pem and
 client.pem.  Both files must be present on the client's host;
@@ -162,6 +170,18 @@ require preauthentication.  Ensure this with the command::
 
     kadmin -q 'modprinc +requires_preauth YOUR_PRINCNAME'
 
+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::
+
+    kadmin -q 'purgekeys -all YOUR_PRINCNAME'
+
+These principal options can also be specified at principal creation
+time as follows::
+
+    kadmin -q 'add_principal +requires_preauth -nokey YOUR_PRINCNAME'
+
 
 Configuring the clients
 -----------------------
diff --git a/doc/admin/troubleshoot.rst b/doc/admin/troubleshoot.rst
index 3e1cbd6..f56a1d7 100644
--- a/doc/admin/troubleshoot.rst
+++ b/doc/admin/troubleshoot.rst
@@ -50,6 +50,26 @@ section of :ref:`krb5.conf(5)`.
 
 Seen in: clients
 
+.. error::
+
+    Cannot create cert chain: certificate has expired
+
+This error message indicates that PKINIT authentication failed because
+the client certificate, KDC certificate, or one of the certificates in
+the signing chain above them has expired.
+
+If the KDC certificate has expired, this message appears in the KDC
+log file, and the client will receive a "Preauthentication failed"
+error.  (Prior to release 1.11, the KDC log file message erroneously
+appears as "Out of memory".  Prior to release 1.12, the client will
+receive a "Generic error".)
+
+If the client or a signing certificate has expired, this message may
+appear in trace_logging_ output from :ref:`kinit(1)` or, starting in
+release 1.12, as an error message from kinit or another program which
+gets initial tickets.  The error message is more likely to appear
+properly on the client if the principal entry has no long-term keys.
+
 ----
 
 .. include:: ./install_kdc.rst