Merge documentation update from Mustafa Hashmi.

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@23522 ec53bebd-3082-4978-b11e-865c3cabbd6b

doc/hx509.texi

@@ -220,32 +220,55 @@ Software PKCS 11 module
 @node Introduction, What is X.509 ?, Top, Top
 @chapter Introduction
 
-hx509 is a somewhat complete X.509 stack that can handle CMS messages
+The goals of a PKI infrastructure (as defined in 
-(crypto system used in S/MIME and Kerberos PK-INIT) and basic
+<a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet 
-certificate processing tasks, path construction, path validation, OCSP
+@emph{the needs of deterministic, automated identification, authentication, access control, and authorization}.
-and CRL validation, PKCS10 message construction, CMS Encrypted (shared
-secret encrypted), CMS SignedData (certificate signed), and CMS
-EnvelopedData (certificate encrypted).
 
-hx509 can use PKCS11 tokens, PKCS12 files, PEM files, DER encoded files.
+
+The administrator should be aware of certain terminologies as explained by the aforementioned
+RFC before attemping to put in place a PKI infrastructure. Briefly, these are: 
+
+@itemize @bullet
+@item CA
+Certificate Authority
+@item RA
+Registration Authority, i.e., an optional system to which a CA delegates certain management functions.
+@item CRL Issuer
+An optional system to which a CA delegates the publication of certificate revocation lists.
+@item Repository
+A system or collection of distributed systems that stores certificates and CRLs 
+and serves as a means of distributing these certificates and CRLs to end entities
+@end itemize
+
+hx509 (Heimdal x509 support) is a near complete X.509 stack that can
+handle CMS messages (crypto system used in S/MIME and Kerberos PK-INIT)
+and basic certificate processing tasks, path construction, path
+validation, OCSP and CRL validation, PKCS10 message construction, CMS
+Encrypted (shared secret encrypted), CMS SignedData (certificate
+signed), and CMS EnvelopedData (certificate encrypted).
+
+hx509 can use PKCS11 tokens, PKCS12 files, PEM files, and/or DER encoded
+files.
 
 @node What is X.509 ?, Setting up a CA, Introduction, Top
 @chapter What is X.509, PKIX, PKCS7 and CMS ? 
 
-X.509 is from the beginning created by CCITT (later ITU) for the X.500
+X.509 was created by CCITT (later ITU) for the X.500 directory
-directory service. But today when people are talking about X.509 they
+service. Today, X.509 discussions and implementations commonly reference
-are commonly referring to IETF's PKIX Certificate and CRL Profile of the
+the IETF's PKIX Certificate and CRL Profile of the X.509 v3 certificate
-X.509 v3 certificate standard, as specified in RFC 3280.
+standard, as specified in RFC 3280.
 
-ITU continues to develop the X.509 standard together in a complicated
+ITU continues to develop the X.509 standard together with the IETF in a 
-dance with IETF.
+rather complicated dance.
 
-X.509 is public key based security system that have associated data
+X.509 is a public key based security system that has associated data
-stored within a so called certificate. From the beginning X.509 was a
+stored within a so called certificate. Initially, X.509 was a strict
-strict hierarchical system with one root. This didn't not work so over
+hierarchical system with one root. However, ever evolving requiments and
-time X.509 got support for multiple policy roots, bridges, and mesh
+technology advancements saw the inclusion of multiple policy roots,
-solutions. You can even use it as a peer to peer system, but this is not
+bridges and mesh solutions.
-very common.
+
+x.509 can also be used as a peer to peer system, though often seen as a
+common scenario.
 
 @section Type of certificates
 
@@ -255,36 +278,36 @@ There are several flavors of certificate in X.509.
 
 @item Trust anchors
 
-Trust anchors are strictly not certificate, but commonly stored in
+Trust anchors are strictly not certificates, but commonly stored in a
-certificate since they are easier to handle then. Trust anchor are the
+certificate format as they become easier to manage. Trust anchors are
-keys that you trust to validate other certificate. This is done by
+the keys that an end entity would trust to validate other certificates.
-building a path from the certificate you wan to validate to to any of
+This is done by building a path from the certificate you want to
-the trust anchors you have.
+validate to to any of the trust anchors you have.
 
 @item End Entity (EE) certificates
 
-End entity certificates is the most common type of certificate. End
+End entity certificates are the most common types of certificates. End
-entity certificates can't issue certificate them-self and is used to
+entity certificates cannot issue (sign) certificate themselves and are generally
-authenticate and authorize user and services.
+used to authenticate and authorize users and services.
 
 @item Certification Authority (CA) certificates
 
-Certificate authority are certificates that have the right to issue
+Certificate authority certificates have the right to issue additional
-other certificate, they may be End entity certificates or Certificate
+certificates (be it sub-ordinate CA certificates to build an trust anchors
-Authority certificates. There is no limit to how many certificates a CA
+or end entity certificates). There is no limit to how many certificates a CA
 may issue, but there might other restrictions, like the maximum path
 depth.
 
 @item Proxy certificates
 
-Remember that End Entity can't issue certificates by them own, it's not
+Remember the statement "End Entity certificates cannot issue
-really true. There there is an extension called proxy certificates,
+certificates"?  Well that statement is not entirely true. There is an
-defined in RFC3820, that allows certificates to be issued by end entity
+extension called proxy certificates defined in RFC3820, that allows
-certificates. The service that receives the proxy certificates must have
+certificates to be issued by end entity certificates. The service that
-explicitly turned on support for proxy certificates, so their use is
+receives the proxy certificates must have explicitly turned on support
-somewhat limited.
+for proxy certificates, so their use is somewhat limited.
 
-Proxy certificates can be limited by policy stored in the certificate to
+Proxy certificates can be limited by policies stored in the certificate to
 what they can be used for. This allows users to delegate the proxy
 certificate to services (by sending over the certificate and private
 key) so the service can access services on behalf of the user.
@@ -294,59 +317,52 @@ large job in the middle of the night when the printer isn't used that
 much, so the user creates a proxy certificate with the policy that it
 can only be used to access files related to this print job, creates the
 print job description and send both the description and proxy
-certificate with key over to print service. Later at night will the
+certificate with key over to print service. Later at night when the
-print service, without the help of the user, access the files for the
+print service initializes (without any user intervention), access to the files 
-the print job using the proxy certificate and print the job. Because of
+for the print job is granted via the proxy certificate. As a result of (in-place) 
-the policy (limitation) in the proxy certificate, it can't be used for
+policy limitations, the certificate cannot be used for any other purposes.
-any other purposes.
 
 @end itemize
 
 @section Building a path
 
-Before validating a path the path must be constructed. Given a
+Before validating a certificate path (or chain), the path needs to be
-certificate (EE, CA, Proxy, or any other type), the path construction
+constructed.  Given a certificate (EE, CA, Proxy, or any other type),
-algorithm will try to find a path to one of the trust anchors.
+the path construction algorithm will try to find a path to one of the
+trust anchors.
 
-It start with looking at whom issued the certificate, by name or Key
+The process starts by looking at the issuing CA of the certificate, by
-Identifier, and tries to find that certificate while at the same time
+Name or Key Identifier, and tries to find that certificate while at the
-evaluates the policy.
+same time evaluting any policies in-place.
 
 @node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top
 @chapter Setting up a CA
 
-Do not let this chapter scare you off, it's just to give you an idea how
+Do not let information overload scare you off! If you are simply testing
-to complicated setting up a CA can be. If you are just playing around,
+or getting started with a PKI infrastructure, skip all this and go to
-skip all this and go to the next chapter, @pxref{Creating a CA
+the next chapter (see: @pxref{Creating a CA certificate}).
-certificate}.
 
 Creating a CA certificate should be more the just creating a
-certificate, there is the policy of the CA. If it's just you and your
+certificate, CA's should define a policy. Again, if you are simply
-friend that is playing around then it probably doesn't matter what the
+testing a PKI, policies do not matter so much. However, when it comes to
-policy is. But then it comes to trust in an organisation, it will
+trust in an organisation, it will probably matter more whom your users
-probably matter more whom your users and sysadmins will find it
+and sysadmins will find it acceptable to trust.
-acceptable to trust.
 
-At the same time, try to keep thing simple, it's not very hard to run a
+At the same time, try to keep things simple, it's not very hard to run a
-Certificate authority and the process to get new certificates should
+Certificate authority and the process to get new certificates should be simple.
-simple.
 
-Fill all this in later.
+You may find it helpful to answer the following policy questions for
+your organization at a later stage:
 
-How do you trust your CA.
+@itemize @bullet
-
+@item How do you trust your CA.
-What is the CA responsibility.
+@item What is the CA responsibility.
-
+@item Review of CA activity.
-Review of CA activity.
+@item How much process should it be to issue certificate.
-
+@item Who is allowed to issue certificates.
-How much process should it be to issue certificate.
+@item Who is allowed to requests certificates.
-
+@item How to handle certificate revocation, issuing CRLs and maintain OCSP services.
-Who is allowed to issue certificates.
+@end itemize
-
-Who is allowed to requests certificates.
-
-How to handle certificate revocation, issuing CRLs and maintain OCSP
-services.
 
 @node Creating a CA certificate, Issuing certificates, Setting up a CA, Top
 @section Creating a CA certificate
@@ -357,10 +373,10 @@ about.
 @subsection Lifetime CA certificate
 
 You probably want to create a CA certificate with a long lifetime, 10
-years at the shortest. This because you don't want to push out the
+years at the very minimum. This is because you don't want to push out the
-certificate (as a trust anchor) to all you users once again when the old
+certificate (as a trust anchor) to all you users again when the old
-one just expired. A trust anchor can't really expire, but not all
+CA certificate expires. Although a trust anchor can't really expire, not all
-software works that way.
+software works in accordance with published standards.
 
 Keep in mind the security requirements might be different 10-20 years
 into the future. For example, SHA1 is going to be withdrawn in 2010, so
@@ -369,7 +385,7 @@ algorithms, signature algorithms and key lengths.
 
 @subsection Create a CA certificate
 
-This command below will create a CA certificate in the file ca.pem.
+This command below can be used to generate a self-signed CA certificate.
 
 @example
 hxtool issue-certificate \
@@ -381,14 +397,14 @@ hxtool issue-certificate \
     --certificate="FILE:ca.pem"
 @end example
 
-@subsection Extending lifetime of a CA certificate
+@subsection Extending the lifetime of a CA certificate
 
 You just realised that your CA certificate is going to expire soon and
-that you need replace it with something else, the easiest way to do that
+that you need replace it with a new CA. The easiest way to do that
-is to extend the lifetime of your CA certificate.
+is to extend the lifetime of your existing CA certificate.
 
-The example below will extend the CA certificate 10 years into the
+The example below will extend the CA certificate's lifetime by 10 years. 
-future. You should compare this new certificate if it contains all the
+You should compare this new certificate if it contains all the
 special tweaks as the old certificate had.
 
 @example
@@ -404,7 +420,7 @@ hxtool issue-certificate \
 
 @subsection Subordinate CA
 
-This example create a new subordinate certificate authority.
+This example below creates a new subordinate certificate authority.
 
 @example
 hxtool issue-certificate \
@@ -420,17 +436,34 @@ hxtool issue-certificate \
 @section Issuing certificates
 
 First you'll create a CA certificate, after that you have to deal with
-your users and servers and issue certificate to them.
+your users and servers and issue certificates to them.
 
-CA can generate the key for the user.
+@c I think this section needs a bit of clarity. Can I add a separate
+@c section which explains CSRs as well?
 
-Can receive PKCS10 certificate requests from the users. PKCS10 is a
+
-request for a certificate. The user can specified what DN the user wants
+@itemize @bullet
-and what public key. To prove the user have the key, the whole request
+
-is signed by the private key of the user.
+@item Do all the work themself
+
+Generate the key for the user. This has the problme that the the CA
+knows the private key of the user. For a paranoid user this might leave
+feeling of disconfort.
+
+@item Have the user do part of the work
+
+Receive PKCS10 certificate requests fromusers. PKCS10 is a request for a
+certificate.  The user may specify what DN they want as well as provide
+a certificate signing request (CSR).  To prove the user have the key,
+the whole request is signed by the private key of the user.
+
+@end itemize
 
 @subsection Name space management
 
+@c The explanation given below is slightly unclear. I will re-read the
+@c RFC and document accordingly
+
 What people might want to see.
 
 Re-issue certificates just because people moved within the organization.
@@ -441,22 +474,43 @@ Using Sub-component name (+ notation).
 
 @subsection Certificate Revocation, CRL and OCSP
 
-Sonetimes people loose smartcard or computers and certificates have to
+Certificates that a CA issues may need to be revoked at some stage. As
-be make not valid any more, this is called revoking certificates. There
+an example, an employee leaves the organization and does not bother
-are two main protocols for doing this Certificate Revocations Lists
+handing in his smart card (or even if the smart card is handed back --
-(CRL) and Online Certificate Status Protocol (OCSP).
+the certificate on it must no longer be acceptable to services; the
+employee has left).
 
-If you know that the certificate is destroyed then there is no need to
+You may also want to revoke a certificate for a service which is no
-revoke the certificate because it can not be used by someone else.
+longer being offered on your network. Overlooking these scenarios can
+lead to security holes which will quickly become a nightmare to deal
+with.
+
+There are two primary protocols for dealing with certificate
+revokation. Namely:
+
+@itemize @bullet
+@item Certificate Revocation List (CRL)
+@item Online Certificate Status Protocol (OCSP)
+@end itemize
+
+If however the certificate in qeustion has been destroyed, there is no
+need to revoke the certificate because it can not be used by someone
+else. This matter since for each certificate you add to CRL, the
+download time and processing time for clients are longer.
+
+CRLs and OCSP responders however greatly help manage compatible services
+which may authenticate and authorize users (or services) on an on-going
+basis. As an example, VPN connectivity established via certificates for
+connecting clients would require your VPN software to make use of a CRL
+or an OCSP service to ensure revoked certificates belonging to former
+clients are not allowed access to (formerly subscribed) network
+services.
 
-The main reason you as a CA administrator have to deal with CRLs however
-will be that some software require there to be CRLs. Example of this is
-Windows, so you have to deal with this somehow.
 
 @node Issuing CRLs, Application requirements, Issuing certificates, Top
 @section Issuing CRLs
 
-Create an empty CRL with not certificates revoked. Default expiration
+Create an empty CRL with no certificates revoked. Default expiration
 value is one year from now.
 
 @example
@@ -480,7 +534,7 @@ hxtool crl-sign \
 @node Application requirements, CMS signing and encryption, Issuing CRLs, Top
 @section Application requirements
 
-Application have different requirements on certificates. This section
+Application place different requirements on certificates. This section
 tries to expand what they are and how to use hxtool to generate
 certificates for those services.
 
@@ -513,14 +567,14 @@ The email address format used in S/MIME certificates is defined in
 RFC2822, section 3.4.1 and it should be an ``addr-spec''.
 
 There are two ways to specifify email address in certificates. The old
-ways is in the subject distinguished name, this should not be used. The
+way is in the subject distinguished name, @emph{this should not be used}. The
 new way is using a Subject Alternative Name (SAN).
 
-But even though email address is stored in certificates, they don't need
+Even though the email address is stored in certificates, they don't need
-to, email reader programs are required to accept certificates that
+to be, email reader programs are required to accept certificates that
-doesn't have either of the two methods of storing email in certificates.
+doesn't have either of the two methods of storing email in certificates
-In that case, they try to protect the user by printing the name of the
+-- in which case, the email client will try to protect the user by
-certificate instead.
+printing the name of the certificate instead.
 
 S/MIME certificate can be used in another special way. They can be
 issued with a NULL subject distinguished name plus the email in SAN,
@@ -553,26 +607,51 @@ hxtool issue-certificate \
 
 @subsection PK-INIT
 
-How to create a certificate for a KDC.
+A PK-INIT infrastructure allows users and services to pick up kerberos
+credentials (tickets) based on their certificate. This, for example,
+allows users to authenticate to their desktops using smartcards while
+acquiring kerberos tickets in the process.
+
+As an example, an office network which offers centrally controlled
+desktop logins, mail, messaging (xmpp) and openafs would give users
+single sign-on facilities via smartcard based logins.  Once the kerberos
+ticket has been acquired, all kerberized services would immediately
+become accessible based on deployed security policies.
+
+Let's go over the process of initializing a demo PK-INIT framework:
 
 @example
 hxtool issue-certificate \
-    --type="pkinit-kdc" \
+        --type="pkinit-kdc" \
-    --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
+        --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
-    --hostname kerberos.test.h5l.se \
+        --hostname=kerberos.test.h5l.se \
-    --hostname pal.test.h5l.se \
+        --ca-certificate="FILE:ca.pem,ca.key" \
-    ...
+        --generate-key=rsa \
+        --certificate="FILE:kdc.pem" \
+        --subject="cn=kdc"
 @end example
 
 How to create a certificate for a user.
 
 @example
 hxtool issue-certificate \
-    --type="pkinit-client" \
+        --type="pkinit-client" \
-    --pk-init-principal="user@@TEST.H5L.SE" \
+        --pk-init-principal="user@@TEST.H5L.SE" \
-    ...
+        --ca-certificate="FILE:ca.pem,ca.key" \
+        --generate-key=rsa \
+        --subject="cn=Test User" \
+        --certificate="FILE:user.pem"
 @end example
 
+The --type field can be specified multiple times. The same certificate
+can hence house extensions for both pkinit-client as well as S/MIME.
+
+To use the PKCS11 module, please see the section:
+@pxref{How to use the PKCS11 module}.
+
+More about how to configure the KDC, see the documentation in the
+Heimdal manual to set up the KDC.
+
 @subsection XMPP/Jabber
 
 The jabber server certificate should have a dNSname that is the same as