krb5 commit [krb5-1.15]: Document multi-component PKINIT client certs

https://github.com/krb5/krb5/commit/55ad97d03c9581cf8c6a868e9151702e53071a62
commit 55ad97d03c9581cf8c6a868e9151702e53071a62
Author: Greg Hudson <[email protected]>
Date:   Mon Jan 30 12:30:51 2017 -0500

    Document multi-component PKINIT client certs
    
    In pkinit.rst, note that the extensions.client file only works for
    single-component client principals, and describe how to modify it for
    multi-component principals.
    
    (cherry picked from commit 8abbb9b805e457849e9e414bd2ef610ad9fc4f06)
    
    ticket: 7940
    version_fixed: 1.15.1

 doc/admin/pkinit.rst |   21 ++++++++++++++++++---
 1 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/doc/admin/pkinit.rst b/doc/admin/pkinit.rst
index deb2d1e..460d75d 100644
--- a/doc/admin/pkinit.rst
+++ b/doc/admin/pkinit.rst
@@ -111,9 +111,9 @@ Generating client certificates
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 PKINIT client certificates also must have some unusual certificate
-fields.  To generate a client certificate with OpenSSL, you will need
-an extensions file (different from the KDC extensions file above)
-containing::
+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::
 
     [client_cert]
     basicConstraints=CA:FALSE
@@ -164,6 +164,21 @@ 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.
 
+If the client principal name contains more than one component
+(e.g. ``host/example.com@REALM``), the ``[principals]`` section of
+``extensions.client`` must be altered to contain multiple entries.
+(Simply setting ``CLIENT`` to ``host/example.com`` would generate a
+certificate for ``host\/example.com@REALM`` which would not match the
+multi-component principal name.)  For a two-component principal, the
+section should read::
+
+    [principals]
+    princ1=GeneralString:${ENV::CLIENT1}
+    princ2=GeneralString:${ENV::CLIENT2}
+
+The environment variables ``CLIENT1`` and ``CLIENT2`` must then be set
+to the first and second components when running ``openssl x509``.
+
 
 Configuring the KDC
 -------------------