Heimdal
*******

This manual is last updated $Date: 2008-04-21 21:18:41 +1000 (Mon, 21
Apr 2008) $ for version 1.2.99-samba of hx509.

1 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).

hx509 can use PKCS11 tokens, PKCS12 files, PEM files, DER encoded files.

2 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.

ITU continues to develop the X.509 standard together in a complicated
dance with IETF.

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.

2.1 Type of certificates
========================

There are several flavors of certificate in X.509.

   * 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.

   * 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.

   * 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 may issue, but there might other restrictions,
     like the maximum path depth.

   * 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.

     Proxy certificates can be limited by policy 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.

     One example of this would be a print service. The user wants to
     print a 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.

2.2 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.

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.

3 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, see 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.

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.

Fill all this in later.

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.

3.1 Creating a CA certificate
=============================

This section describes how to create a CA certificate and what to think
about.

3.1.1 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.

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
make sure you have enough buffering in your choice of digest/hash
algorithms, signature algorithms and key lengths.

3.1.2 Create a CA certificate
-----------------------------

This command below will create a CA certificate in the file ca.pem.

     hxtool issue-certificate \
         --self-signed \
         --issue-ca \
         --generate-key=rsa \
         --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \
         --lifetime=10years \
         --certificate="FILE:ca.pem"

3.1.3 Extending 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.

The example below will extend the CA certificate 10 years into the
future. You should compare this new certificate if it contains all the
special tweaks as the old certificate had.

     hxtool issue-certificate \
         --self-signed \
         --issue-ca \
         --lifetime="10years" \
         --template-certificate="FILE:ca.pem" \
         --template-fields="serialNumber,notBefore,subject,SPKI" \
         --ca-private-key=FILE:ca.pem \
         --certificate="FILE:new-ca.pem"

3.1.4 Subordinate CA
--------------------

This example create a new subordinate certificate authority.

     hxtool issue-certificate \
         --ca-certificate=FILE:ca.pem \
         --issue-ca \
         --generate-key=rsa \
         --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \
         --certificate="FILE:dev-ca.pem"

3.2 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.

CA can generate the key for the user.

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.

3.2.1 Name space management
---------------------------

What people might want to see.

Re-issue certificates just because people moved within the organization.

Expose privacy information.

Using Sub-component name (+ notation).

3.2.2 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).

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.

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.

3.3 Issuing CRLs
================

Create an empty CRL with not certificates revoked. Default expiration
value is one year from now.

     hxtool crl-sign \
     	--crl-file=crl.der \
     	--signer=FILE:ca.pem

Create a CRL with all certificates in the directory
`/path/to/revoked/dir' included in the CRL as revoked.  Also make it
expire one month from now.

     hxtool crl-sign \
     	--crl-file=crl.der \
             --signer=FILE:ca.pem \
     	--lifetime='1 month' \
             DIR:/path/to/revoked/dir

3.4 Application requirements
============================

Application have different requirements on certificates. This section
tries to expand what they are and how to use hxtool to generate
certificates for those services.

3.4.1 HTTPS - server
--------------------

     hxtool issue-certificate \
     	  --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \
     	  --type="https-server" \
               --hostname="www.test.h5l.se" \
               --hostname="www2.test.h5l.se" \
               ...

3.4.2 HTTPS - client
--------------------

     hxtool issue-certificate \
     	  --subject="UID=testus,DC=test,DC=h5l,DC=se" \
     	  --type="https-client" \
               ...

3.4.3 S/MIME - email
--------------------

There are two things that should be set in S/MIME certificates, one or
more email addresses and an extended eku usage (EKU), emailProtection.

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
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.

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,
this is a valid certificate. This is used when you wont want to share
more information then you need to.

hx509 issue-certificate supports adding the email SAN to certificate by
using the -email option, -email also gives an implicit emailProtection
eku. If you want to create an certificate without an email address, the
option -type=email will add the emailProtection EKU.

     hxtool issue-certificate \
     	  --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \
     	  --type=email \
     	  --email="testus@test.h5l.se" \
               ...

An example of an certificate without and subject distinguished name with
an email address in a SAN.

     hxtool issue-certificate \
     	  --subject="" \
     	  --type=email \
     	  --email="testus@test.h5l.se" \
               ...

3.4.4 PK-INIT
-------------

How to create a certificate for a KDC.

     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 \
         ...

How to create a certificate for a user.

     hxtool issue-certificate \
         --type="pkinit-client" \
         --pk-init-principal="user@TEST.H5L.SE" \
         ...

3.4.5 XMPP/Jabber
-----------------

The jabber server certificate should have a dNSname that is the same as
the user entered into the application, not the same as the host name of
the machine.

     hxtool issue-certificate \
     	  --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \
               --hostname="xmpp1.test.h5l.se" \
               --hostname="test.h5l.se" \
               ...

The certificate may also contain a jabber identifier (JID) that, if the
receiver allows it, authorises the server or client to use that JID.

When storing a JID inside the certificate, both for server and client,
it's stored inside a UTF8String within an otherName entity inside the
subjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5).

To read more about the requirements, see RFC3920, Extensible Messaging
and Presence Protocol (XMPP): Core.

hxtool issue-certificate have support to add jid to the certificate
using the option `--jid'.

     hxtool issue-certificate \
     	  --subject="CN=Love,DC=test,DC=h5l,DC=se" \
               --jid="lha@test.h5l.se" \
               ...

4 CMS signing and encryption
****************************

CMS is the Cryptographic Message System that among other, is used by
S/MIME (secure email) and Kerberos PK-INIT. It's an extended version of
the RSA, Inc standard PKCS7.

4.1 CMS background
==================

5 Certificate matching
**********************

To match certificates hx509 have a special query language to match
certifictes in queries and ACLs.

5.1 Matching syntax
===================

This is the language definitions somewhat slopply descriped:

     expr = TRUE,
          FALSE,
          ! expr,
          expr AND expr,
          expr OR expr,
          ( expr )
          compare

     compare =
          word == word,
          word != word,
          word IN ( word [, word ...])
          word IN %{variable.subvariable}

     word =
          STRING,
          %{variable}

6 Software PKCS 11 module
*************************

PKCS11 is a standard created by RSA, Inc to support hardware and
software encryption modules. It can be used by smartcard to expose the
crypto primitives inside without exposing the crypto keys.

Hx509 includes a software implementation of PKCS11 that runs within the
memory space of the process and thus exposes the keys to the
application.

6.1 How to use the PKCS11 module
================================

     $ cat > ~/.soft-pkcs11.rc <<EOF
     mycert	cert	User certificate	FILE:/Users/lha/Private/pkinit.pem
     app-fatal	true
     EOF
     $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@EXAMPLE.ORG