Next: , Previous: (dir), Up: (dir)


This manual is last updated $Date: 2008-09-13 10:53:55 +0200 (Sat, 13 Sep 2008) $ for version 1.2.99 of hx509.

--- The Detailed Node Listing ---

Setting up a CA

CMS signing and encryption

Certificate matching

Software PKCS 11 module

Next: , Previous: Top, Up: Top

1 Introduction

The goals of a PKI infrastructure (as defined in <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet the needs of deterministic, automated identification, authentication, access control, and authorization.

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:

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.

Next: , Previous: Introduction, Up: Top

2 What is X.509, PKIX, PKCS7 and CMS ?

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 with the IETF in a rather complicated dance.

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.

2.1 Type of certificates

There are several flavors of certificate in X.509.

2.2 Building a path

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.

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.

Next: , Previous: What is X.509 ?, Up: Top

3 Setting up a CA

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: see Creating a CA certificate).

Creating a CA certificate should be more the just creating a 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 things simple, it's not very hard to run a Certificate authority and the process to get new certificates should be simple.

You may find it helpful to answer the following policy questions for your organization at a later stage:

Next: , Previous: Setting up a CA, Up: Top

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 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 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 can be used to generate a self-signed CA certificate.

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

3.1.3 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 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's lifetime by 10 years. 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 \

3.1.4 Subordinate CA

This example below creates 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" \

Next: , Previous: Creating a CA certificate, Up: Top

3.2 Issuing certificates

First you'll create a CA certificate, after that you have to deal with your users and servers and issue certificates to them.

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

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

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:

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.

Next: , Previous: Issuing certificates, Up: Top

3.3 Issuing CRLs

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

     hxtool crl-sign \
     	--crl-file=crl.der \

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

Next: , Previous: Issuing CRLs, Up: Top

3.4 Application requirements

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.

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 way is in the subject distinguished name, this should not be used. The new way is using a Subject Alternative Name (SAN).

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

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:

     hxtool issue-certificate \
             --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" \

How to create a certificate for a user.

     hxtool issue-certificate \
             --type="pkinit-client" \
             --pk-init-principal="user@TEST.H5L.SE" \
             --ca-certificate="FILE:ca.pem,ca.key" \
             --generate-key=rsa \
             --subject="cn=Test User" \

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

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 (

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

Next: , Previous: Application requirements, Up: Top

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.

Next: , Previous: CMS signing and encryption, Up: Top

4.1 CMS background

Next: , Previous: CMS background, Up: Top

5 Certificate matching

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

Next: , Previous: Certificate matching, Up: Top

5.1 Matching syntax

This is the language definitions somewhat slopply descriped:

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

Next: , Previous: Matching syntax, Up: Top

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.

Previous: Software PKCS 11 module, Up: Top

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
     $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@EXAMPLE.ORG

Table of Contents