Rephrase the PKINIT setup instructions

Rephrase and reword the PKINIT setup documentation to be in somewhat
more idiomatic English.  There should be no changes to the substance
of the documentation.

Signed-off-by: Love Hornquist Astrand <lha@h5l.org>

doc/setup.texi

@@ -1208,18 +1208,19 @@ service@@host$ kinit --cache=/var/run/service_krb5_cache \
 @node Setting up PK-INIT, Debugging Kerberos problems, Providing Kerberos credentials to servers and programs, Setting up a realm
 @section Setting up PK-INIT
 
-PK-INIT is levering the existing PKI infrastructure to use
+PK-INIT leverages an existing PKI (public key infrastructure), using
-certificates to get the initial ticket, that is usually the krbtgt.
+certificates to get the initial ticket (usually the krbtgt
+ticket-granting ticket).
 
-To use PK-INIT you must first have a PKI, so if you don't have one,
+To use PK-INIT you must first have a PKI. If you don't have one, it is
-it is time to create it. Note that you should read the whole chapter
+time to create it. You should first read the whole chapter of the
-of the document to see the requirements on the CA software.
+document to see the requirements imposed on the CA software.
 
-There needs to exist a mapping between the certificate and what
+A mapping between the PKI certificate and what principals that
-principals that certificate is allowed to use. There are several ways
+certificate is allowed to use must exist. There are several ways to do
-to do this. The administrator can use a configuration file, storing
+this. The administrator can use a configuration file, store the
-the principal in the SubjectAltName extension of the certificate, or store the
+principal in the SubjectAltName extension of the certificate, or store
-mapping in the principals entry in the kerberos database.
+the mapping in the principals entry in the kerberos database.
 
 @section Certificates
 
@@ -1229,27 +1230,28 @@ extention.
 
 @subsection KDC certificate
 
-The certificate for the KDC have serveral requirements.
+The certificate for the KDC has serveral requirements.
 
-First the certificate should have an Extended Key Usage (EKU)
+First, the certificate should have an Extended Key Usage (EKU)
-id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second there must be a
+id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second, there must be a
-subjectAltName otherName using oid id-pkinit-san (1.3.6.1.5.2.2) in
+subjectAltName otherName using OID id-pkinit-san (1.3.6.1.5.2.2) in
 the type field and a DER encoded KRB5PrincipalName that matches the
-name of the TGS of the target realm.
+name of the TGS of the target realm.  Also, if the certificate has a
+nameConstraints extention with a Generalname with dNSName or iPAdress,
+it must match the hostname or adress of the KDC.
 
-Both of these two requirements are not required by the standard to be
+The client is not required by the standard to check the server
-checked by the client if it have external information what the
+certificate for this information if the client has external
-certificate the KDC is supposed to be used. So it's in the interest of
+information confirming which certificate the KDC is supposed to be
-minimum amount of configuration on the clients they should be included.
+using. However, adding this information to the KDC certificate removes
+the need to specially configure the client to recognize the KDC
+certificate.
 
 Remember that if the client would accept any certificate as the KDC's
 certificate, the client could be fooled into trusting something that
 isn't a KDC and thus expose the user to giving away information (like
-password or other private information) that it is supposed to secret.
+a password or other private information) that it is supposed to keep
-
+secret.
-Also, if the certificate has a nameConstraints extention with a
-Generalname with dNSName or iPAdress it must match the hostname or
-adress of the KDC.
 
 @subsection Client certificate
 
@@ -1267,15 +1269,16 @@ This behavior is controlled by KDC configuration option:
 	pkinit_principal_in_certificate = yes
 @end example
 
-
 @subsubsection Using KRB5PrincipalName in id-pkinit-san
 
-OtherName extention in the GeneralName is used to do the
+The OtherName extention in the GeneralName is used to do the mapping
-mapping between certifiate and principal in the certifiate or storing
+between certificate and principal.  For the KDC certificate, this
-the krbtgt principal in the KDC certificate.
+stores the krbtgt principal name for that KDC.  For the client
+certificate, this stores the principal for which that certificate is
+allowed to get tickets.
 
 The principal is stored in a SubjectAltName in the certificate using
-OtherName. The oid in the type is id-pkinit-san.
+OtherName. The OID in the type is id-pkinit-san.
 
 @example
 id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6)
@@ -1292,32 +1295,32 @@ KRB5PrincipalName ::= SEQUENCE @{
 @}
 @end example
 
-where Realm and PrincipalName is defined by the Kerberos ASN.1 specification.
+where Realm and PrincipalName is defined by the Kerberos ASN.1
+specification.
 
 @section Naming certificate using hx509
 
 hx509 is the X.509 software used in Heimdal to handle
-certificates. hx509 uses different syntaxes to specify the different
+certificates. hx509 supports several different syntaxes for specifying
-formats the certificates are stored in and what formats they exist in.
+certificate files or formats. Several formats may be used:  PEM,
-
+certificates embedded in PKCS#12 files, certificates embedded in
-There are several formats that can be used, PEM, embedded into PKCS12
+PKCS#11 devices, and raw DER encoded certificates.
-files, embedded into PKCS11 devices and raw DER encoded certificates.
-Below is a list of types to use.
 
+Those formats may be specified as follows:
 
 @table @asis
 
 @item DIR:
 
-DIR is reading all certificates in a directory that is DER or PEM
+DIR specifies a directory which contains certificates in the DER or
-formatted.
+PEM format.
 
 The main feature of DIR is that the directory is read on demand when
-iterating over certificates, that way applictions can for some cases
+iterating over certificates. This allows applications, in some
-avoid to store all certificates in memory. It's very useful for tests
+situations, to avoid having to store all certificates in memory.  It's
-that iterate over larger amount of certificates.
+very useful for tests that iterate over large numbers of certificates.
 
-Syntax is:
+The syntax is:
 
 @example
 DIR:/path/to/der/files
@@ -1325,15 +1328,16 @@ DIR:/path/to/der/files
 
 @item FILE:
 
-FILE: is used to have the lib pick up a certificate chain and a
+FILE: specifies a file that contains a certificate or private key.
-private key. The file can be either a PEM (openssl) file or a raw DER
+The file can be either a PEM (openssl) file or a raw DER encoded
-encoded certificate. If it's a PEM file it can contain several keys and
+certificate. If it's a PEM file, it can contain several keys and
 certificates and the code will try to match the private key and
-certificate together.
+certificate together. Multiple files may be specified, separated by
+commas.
 
-Its useful to have one PEM file that contains all the trust anchors.
+It's useful to have one PEM file that contains all the trust anchors.
 
-Syntax is:
+The syntax is:
 
 @example
 FILE:certificate.pem,private-key.key,other-cert.pem,....
@@ -1341,11 +1345,12 @@ FILE:certificate.pem,private-key.key,other-cert.pem,....
 
 @item PKCS11:
 
-PKCS11: is used to handle smartcards via PKCS11 drivers, for example
+PKCS11: is used to handle smartcards via PKCS#11 drivers, such as
-soft-token, opensc, or muscle. The default is to use all slots on the
+soft-token, opensc, or muscle. The argument specifies a shared object
-device/token.
+that implements the PKCS#11 API. The default is to use all slots on
+the device/token.
 
-Syntax is:
+The syntax is:
 
 @example
 PKCS11:shared-object.so
@@ -1353,10 +1358,10 @@ PKCS11:shared-object.so
 
 @item PKCS12:
 
-PKCS12: is used to handle PKCS12 files. PKCS12 files commonly have the
+PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have
-extension pfx or p12.
+the extension pfx or p12.
 
-Syntax is:
+The syntax is:
 
 @example
 PKCS12:/path/to/file.pfx
@@ -1367,8 +1372,8 @@ PKCS12:/path/to/file.pfx
 @section Configure the Kerberos software
 
 First configure the client's trust anchors and what parameters to
-verify, see subsection below how to do that. Now you can use kinit to
+verify. See the subsections below for how to do that. Then, you can
-get yourself tickets. One example how that can look like is:
+use kinit to get yourself tickets. For example:
 
 @example
 $ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG
@@ -1381,7 +1386,7 @@ Credentials cache: FILE:/tmp/krb5cc_19100a
 Apr 20 02:08:08  Apr 20 12:08:08  krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
 @end example
 
-Using PKCS11 it can look like this instead:
+Using PKCS#11 it can look like this instead:
 
 @example
 $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG
@@ -1394,8 +1399,7 @@ Credentials cache: API:4
 Mar 26 23:40:10  Mar 27 09:40:10  krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
 @end example
 
-
+TODO: Write about the KDC.
-Write about the kdc.
 
 @section Configure the client
 
@@ -1444,10 +1448,11 @@ lha@@EXAMPLE.ORG:CN=Love,UID=lha
 
 @subsection Generate certificates
 
-First you need to generate a CA certificate, change the --subject to
+First, you need to generate a CA certificate. This example creates a
-something appropriate, the CA certificate will be valid for 10 years.
+CA certificate that will be valid for 10 years.
 
-You need to change --subject in the command below.
+You need to change --subject in the command below to something
+appropriate for your site.
 
 @example
 hxtool issue-certificate \
@@ -1463,7 +1468,8 @@ The KDC needs to have a certificate, so generate a certificate of the
 type ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the
 name of the krbtgt of the realm.
 
-You need to change --subject and --pk-init-principal in the command below.
+You need to change --subject and --pk-init-principal in the command
+below to something appropriate for your site.
 
 @example
 hxtool issue-certificate \
@@ -1475,12 +1481,14 @@ hxtool issue-certificate \
     --certificate="FILE:kdc.pem"
 @end example
 
-The users also needs to have a certificate, so generate a certificate
+The users also needs to have certificates. For your first client,
-of the type ``pkinit-client''. The client doesn't need to have the PK-INIT
+generate a certificate of type ``pkinit-client''. The client doesn't
-SubjectAltName set, you can have the Subject DN in the ACL file
+need to have the PK-INIT SubjectAltName set; you can have the Subject
-(pki-mapping) instead.
+DN in the ACL file (pki-mapping) instead.
 
-You need to change --subject and --pk-init-principal in the command below.
+You need to change --subject and --pk-init-principal in the command
+below to something appropriate for your site. You can omit
+--pk-init-principal if you're going to use the ACL file instead.
 
 @example
 hxtool issue-certificate \
@@ -1494,9 +1502,10 @@ hxtool issue-certificate \
 
 @subsection Validate the certificate
 
-hxtool also contains a tool that will validate certificates according to
+hxtool also contains a tool that will validate certificates according
-rules from the PKIX document. These checks are not complete, but a good test
+to rules from the PKIX document. These checks are not complete, but
-to check if you got all of the basic bits right in your certificates.
+they provide a good test of whether you got all of the basic bits
+right in your certificates.
 
 @example
 hxtool validate FILE:user.pem
@@ -1509,7 +1518,7 @@ certificates using OpenSSL (or CA software based on OpenSSL).
 
 @subsection Using OpenSSL to create certificates with krb5PrincipalName
 
-To make OpenSSL create certificates with krb5PrincipalName use
+To make OpenSSL create certificates with krb5PrincipalName, use an
 @file{openssl.cnf} as described below. To see a complete example of
 creating client and KDC certificates, see the test-data generation
 script @file{lib/hx509/data/gen-req.sh} in the source-tree. The
@@ -1536,7 +1545,7 @@ princ1 = GeneralString:userid
 
 @end example
 
-Command usage
+Command usage:
 
 @example
 openssl x509 -extensions user_certificate
@@ -1566,9 +1575,9 @@ Clients using a Windows KDC with PK-INIT need configuration since
 windows uses pre-standard format and this can't be autodetected.
 
 The pkinit_win2k_require_binding option requires the reply for the KDC
-to be of the new, secure, type that binds the request to reply. Before
+to be of the new, secure, type that binds the request to
-clients should fake the reply from the KDC. To use this option you
+reply. Before, clients could fake the reply from the KDC. To use this
-have to apply a fix from Microsoft.
+option you have to apply a fix from Microsoft.
 
 @example
 [realms]
@@ -1581,19 +1590,19 @@ have to apply a fix from Microsoft.
 @subsection Certificates
 
 The client certificates need to have the extended keyusage ``Microsoft
-Smartcardlogin'' (openssl have the oid shortname msSmartcardLogin).
+Smartcardlogin'' (openssl has the OID shortname msSmartcardLogin).
 
 See Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling
 Smart Card Logon with Third-Party Certification Authorities'' for a
-more extensive description of how set setup an external CA to it
+more extensive description of how set setup an external CA so that it
-includes all information that will make a Windows KDC happy.
+includes all the information required to make a Windows KDC happy.
 
 @subsection Configure Windows 2000 CA
 
-To enable Microsoft Smartcardlogin> for certificates in your Windows
+To enable Microsoft Smartcardlogin for certificates in your Windows
-2000 CA, you want to look at Microsoft Knowledge Base Article -
+2000 CA, you want to look at Microsoft Knowledge Base Article - 313274
-313274 ``HOW TO: Configure a Certification Authority to Issue
+``HOW TO: Configure a Certification Authority to Issue Smart Card
-Smart Card Certificates in Windows''.
+Certificates in Windows''.
 
 @node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm
 @section Debugging Kerberos problems