diff --git a/doc/setup.texi b/doc/setup.texi index 34f5f972a..a95a200e5 100644 --- a/doc/setup.texi +++ b/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 -certificates to get the initial ticket, that is usually the krbtgt. +PK-INIT leverages an existing PKI (public key infrastructure), using +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, -it is time to create it. Note that you should read the whole chapter -of the document to see the requirements on the CA software. +To use PK-INIT you must first have a PKI. If you don't have one, it is +time to create it. You should first read the whole chapter of the +document to see the requirements imposed on the CA software. -There needs to exist a mapping between the certificate and what -principals that certificate is allowed to use. There are several ways -to do this. The administrator can use a configuration file, storing -the principal in the SubjectAltName extension of the certificate, or store the -mapping in the principals entry in the kerberos database. +A mapping between the PKI certificate and what principals that +certificate is allowed to use must exist. There are several ways to do +this. The administrator can use a configuration file, store the +principal in the SubjectAltName extension of the certificate, or store +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) -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 +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 +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 -checked by the client if it have external information what the -certificate the KDC is supposed to be used. So it's in the interest of -minimum amount of configuration on the clients they should be included. +The client is not required by the standard to check the server +certificate for this information if the client has external +information confirming which certificate the KDC is supposed to be +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. - -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. +a password or other private information) that it is supposed to keep +secret. @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 -mapping between certifiate and principal in the certifiate or storing -the krbtgt principal in the KDC certificate. +The OtherName extention in the GeneralName is used to do the mapping +between certificate and principal. For the KDC certificate, this +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 -formats the certificates are stored in and what formats they exist in. - -There are several formats that can be used, PEM, embedded into PKCS12 -files, embedded into PKCS11 devices and raw DER encoded certificates. -Below is a list of types to use. +certificates. hx509 supports several different syntaxes for specifying +certificate files or formats. Several formats may be used: PEM, +certificates embedded in PKCS#12 files, certificates embedded in +PKCS#11 devices, and raw DER encoded certificates. +Those formats may be specified as follows: @table @asis @item DIR: -DIR is reading all certificates in a directory that is DER or PEM -formatted. +DIR specifies a directory which contains certificates in the DER or +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 -avoid to store all certificates in memory. It's very useful for tests -that iterate over larger amount of certificates. +iterating over certificates. This allows applications, in some +situations, to avoid having to store all certificates in memory. It's +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 -private key. The file can be either a PEM (openssl) file or a raw DER -encoded certificate. If it's a PEM file it can contain several keys and +FILE: specifies a file that contains a certificate or private key. +The file can be either a PEM (openssl) file or a raw DER encoded +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 -soft-token, opensc, or muscle. The default is to use all slots on the -device/token. +PKCS11: is used to handle smartcards via PKCS#11 drivers, such as +soft-token, opensc, or muscle. The argument specifies a shared object +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 -extension pfx or p12. +PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have +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 -get yourself tickets. One example how that can look like is: +verify. See the subsections below for how to do that. Then, you can +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 - -Write about the kdc. +TODO: 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 -something appropriate, the CA certificate will be valid for 10 years. +First, you need to generate a CA certificate. This example creates a +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 -of the type ``pkinit-client''. The client doesn't need to have the PK-INIT -SubjectAltName set, you can have the Subject DN in the ACL file -(pki-mapping) instead. +The users also needs to have certificates. For your first client, +generate a certificate of type ``pkinit-client''. The client doesn't +need to have the PK-INIT SubjectAltName set; you can have the Subject +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 -rules from the PKIX document. These checks are not complete, but a good test -to check if you got all of the basic bits right in your certificates. +hxtool also contains a tool that will validate certificates according +to rules from the PKIX document. These checks are not complete, but +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 -clients should fake the reply from the KDC. To use this option you -have to apply a fix from Microsoft. +to be of the new, secure, type that binds the request to +reply. Before, clients could fake the reply from the KDC. To use this +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 -includes all information that will make a Windows KDC happy. +more extensive description of how set setup an external CA so that it +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 -2000 CA, you want to look at Microsoft Knowledge Base Article - -313274 ``HOW TO: Configure a Certification Authority to Issue -Smart Card Certificates in Windows''. +To enable Microsoft Smartcardlogin for certificates in your Windows +2000 CA, you want to look at Microsoft Knowledge Base Article - 313274 +``HOW TO: Configure a Certification Authority to Issue Smart Card +Certificates in Windows''. @node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm @section Debugging Kerberos problems