Merge documentation update from Mustafa Hashmi.
git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@23522 ec53bebd-3082-4978-b11e-865c3cabbd6b
This commit is contained in:
315
doc/hx509.texi
315
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
|
||||
(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).
|
||||
The goals of a PKI infrastructure (as defined in
|
||||
<a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet
|
||||
@emph{the needs of deterministic, automated identification, authentication, access control, and authorization}.
|
||||
|
||||
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
|
||||
directory service. But today when people are talking about X.509 they
|
||||
are commonly referring to IETF's PKIX Certificate and CRL Profile of the
|
||||
X.509 v3 certificate standard, as specified in RFC 3280.
|
||||
X.509 was created by CCITT (later ITU) for the X.500 directory
|
||||
service. Today, X.509 discussions and implementations commonly reference
|
||||
the IETF's PKIX Certificate and CRL Profile of the X.509 v3 certificate
|
||||
standard, as specified in RFC 3280.
|
||||
|
||||
ITU continues to develop the X.509 standard together in a complicated
|
||||
dance with IETF.
|
||||
ITU continues to develop the X.509 standard together with the IETF in a
|
||||
rather complicated dance.
|
||||
|
||||
X.509 is public key based security system that have associated data
|
||||
stored within a so called certificate. From the beginning X.509 was a
|
||||
strict hierarchical system with one root. This didn't not work so over
|
||||
time X.509 got support for multiple policy roots, bridges, and mesh
|
||||
solutions. You can even use it as a peer to peer system, but this is not
|
||||
very common.
|
||||
X.509 is a public key based security system that has associated data
|
||||
stored within a so called certificate. Initially, X.509 was a strict
|
||||
hierarchical system with one root. However, ever evolving requiments and
|
||||
technology advancements saw the inclusion of multiple policy roots,
|
||||
bridges and mesh solutions.
|
||||
|
||||
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
|
||||
certificate since they are easier to handle then. Trust anchor are the
|
||||
keys that you trust to validate other certificate. This is done by
|
||||
building a path from the certificate you wan to validate to to any of
|
||||
the trust anchors you have.
|
||||
Trust anchors are strictly not certificates, but commonly stored in a
|
||||
certificate format as they become easier to manage. Trust anchors are
|
||||
the keys that an end entity would trust to validate other certificates.
|
||||
This is done by building a path from the certificate you want to
|
||||
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
|
||||
entity certificates can't issue certificate them-self and is used to
|
||||
authenticate and authorize user and services.
|
||||
End entity certificates are the most common types of certificates. End
|
||||
entity certificates cannot issue (sign) certificate themselves and are generally
|
||||
used to authenticate and authorize users and services.
|
||||
|
||||
@item Certification Authority (CA) certificates
|
||||
|
||||
Certificate authority are certificates that have the right to issue
|
||||
other certificate, they may be End entity certificates or Certificate
|
||||
Authority certificates. There is no limit to how many certificates a CA
|
||||
Certificate authority certificates have the right to issue additional
|
||||
certificates (be it sub-ordinate CA certificates to build an trust anchors
|
||||
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
|
||||
really true. There there is an extension called proxy certificates,
|
||||
defined in RFC3820, that allows certificates to be issued by end entity
|
||||
certificates. The service that receives the proxy certificates must have
|
||||
explicitly turned on support for proxy certificates, so their use is
|
||||
somewhat limited.
|
||||
Remember the statement "End Entity certificates cannot issue
|
||||
certificates"? Well that statement is not entirely true. There is an
|
||||
extension called proxy certificates defined in RFC3820, that allows
|
||||
certificates to be issued by end entity certificates. The service that
|
||||
receives the proxy certificates must have explicitly turned on support
|
||||
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
|
||||
print service, without the help of the user, access the files for the
|
||||
the print job using the proxy certificate and print the job. Because of
|
||||
the policy (limitation) in the proxy certificate, it can't be used for
|
||||
any other purposes.
|
||||
certificate with key over to print service. Later at night when the
|
||||
print service initializes (without any user intervention), access to the files
|
||||
for the print job is granted via the proxy certificate. As a result of (in-place)
|
||||
policy limitations, the certificate cannot be used for any other purposes.
|
||||
|
||||
@end itemize
|
||||
|
||||
@section Building a path
|
||||
|
||||
Before validating a path the path must be constructed. Given a
|
||||
certificate (EE, CA, Proxy, or any other type), the path construction
|
||||
algorithm will try to find a path to one of the trust anchors.
|
||||
Before validating a certificate path (or chain), the path needs to be
|
||||
constructed. Given a certificate (EE, CA, Proxy, or any other type),
|
||||
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
|
||||
Identifier, and tries to find that certificate while at the same time
|
||||
evaluates the policy.
|
||||
The process starts by looking at the issuing CA of the certificate, by
|
||||
Name or Key Identifier, and tries to find that certificate while at the
|
||||
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
|
||||
to complicated setting up a CA can be. If you are just playing around,
|
||||
skip all this and go to the next chapter, @pxref{Creating a CA
|
||||
certificate}.
|
||||
Do not let information overload scare you off! If you are simply testing
|
||||
or getting started with a PKI infrastructure, skip all this and go to
|
||||
the next chapter (see: @pxref{Creating a CA 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
|
||||
friend that is playing around then it probably doesn't matter what the
|
||||
policy is. But then it comes to trust in an organisation, it will
|
||||
probably matter more whom your users and sysadmins will find it
|
||||
acceptable to trust.
|
||||
certificate, CA's should define a policy. Again, if you are simply
|
||||
testing a PKI, policies do not matter so much. However, when it comes to
|
||||
trust in an organisation, it will probably matter more whom your users
|
||||
and sysadmins will find it acceptable to trust.
|
||||
|
||||
At the same time, try to keep thing simple, it's not very hard to run a
|
||||
Certificate authority and the process to get new certificates should
|
||||
simple.
|
||||
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 be 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.
|
||||
|
||||
What is the CA responsibility.
|
||||
|
||||
Review of CA activity.
|
||||
|
||||
How much process should it be to issue certificate.
|
||||
|
||||
Who is allowed to issue certificates.
|
||||
|
||||
Who is allowed to requests certificates.
|
||||
|
||||
How to handle certificate revocation, issuing CRLs and maintain OCSP
|
||||
services.
|
||||
@itemize @bullet
|
||||
@item How do you trust your CA.
|
||||
@item What is the CA responsibility.
|
||||
@item Review of CA activity.
|
||||
@item How much process should it be to issue certificate.
|
||||
@item Who is allowed to issue certificates.
|
||||
@item Who is allowed to requests certificates.
|
||||
@item How to handle certificate revocation, issuing CRLs and maintain OCSP services.
|
||||
@end itemize
|
||||
|
||||
@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
|
||||
certificate (as a trust anchor) to all you users once again when the old
|
||||
one just expired. A trust anchor can't really expire, but not all
|
||||
software works that way.
|
||||
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 again when the old
|
||||
CA certificate expires. Although a trust anchor can't really expire, not all
|
||||
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
|
||||
is to extend the lifetime of your CA certificate.
|
||||
that you need replace it with a new CA. The easiest way to do that
|
||||
is to extend the lifetime of your existing CA certificate.
|
||||
|
||||
The example below will extend the CA certificate 10 years into the
|
||||
future. You should compare this new certificate if it contains all the
|
||||
The example below will extend the CA certificate's lifetime by 10 years.
|
||||
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
|
||||
and what public key. To prove the user have the key, the whole request
|
||||
is signed by the private key of the user.
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@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
|
||||
be make not valid any more, this is called revoking certificates. There
|
||||
are two main protocols for doing this Certificate Revocations Lists
|
||||
(CRL) and Online Certificate Status Protocol (OCSP).
|
||||
Certificates that a CA issues may need to be revoked at some stage. As
|
||||
an example, an employee leaves the organization and does not bother
|
||||
handing in his smart card (or even if the smart card is handed back --
|
||||
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
|
||||
revoke the certificate because it can not be used by someone else.
|
||||
You may also want to revoke a certificate for a service which is no
|
||||
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
|
||||
to, email reader programs are required to accept certificates that
|
||||
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
|
||||
certificate instead.
|
||||
Even though the email address is stored in certificates, they don't need
|
||||
to be, email reader programs are required to accept certificates that
|
||||
doesn't have either of the two methods of storing email in certificates
|
||||
-- in which case, the email client will try to protect the user by
|
||||
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" \
|
||||
--pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
|
||||
--hostname kerberos.test.h5l.se \
|
||||
--hostname pal.test.h5l.se \
|
||||
...
|
||||
--type="pkinit-kdc" \
|
||||
--pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
|
||||
--hostname=kerberos.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" \
|
||||
--pk-init-principal="user@@TEST.H5L.SE" \
|
||||
...
|
||||
--type="pkinit-client" \
|
||||
--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
|
||||
|
Reference in New Issue
Block a user