path: root/doc/hx509.info

Detta är hx509.info, skapad av makeinfo version 4.8 från hx509.texi.

INFO-DIR-SECTION Security
START-INFO-DIR-ENTRY
* hx509: (hx509).               The X.509 distribution from KTH
END-INFO-DIR-ENTRY


File: hx509.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Heimdal
*******

This manual is for version 1.5 of hx509.

* Menu:

* Introduction::
* What is X.509 ?::
* Setting up a CA::
* CMS signing and encryption::
* Certificate matching::
* Software PKCS 11 module::

 --- The Detailed Node Listing ---

Setting up a CA

* Creating a CA certificate::
* Issuing certificates::
* Issuing CRLs::
* Application requirements::

CMS signing and encryption

* CMS background::

Certificate matching

* Matching syntax::

Software PKCS 11 module

* How to use the PKCS11 module::


File: hx509.info,  Node: Introduction,  Next: What is X.509 ?,  Prev: 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:

   * CA Certificate Authority

   * RA Registration Authority, i.e., an optional system to which a CA
     delegates certain management functions.

   * CRL Issuer An optional system to which a CA delegates the
     publication of certificate revocation lists.

   * 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

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.


File: hx509.info,  Node: What is X.509 ?,  Next: Setting up a CA,  Prev: 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.

   * Trust anchors

     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.

   * End Entity (EE) certificates

     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.

   * Certification Authority (CA) certificates

     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.

   * Proxy certificates

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

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


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.


File: hx509.info,  Node: Setting up a CA,  Next: Creating a CA certificate,  Prev: 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: *note 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:

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


File: hx509.info,  Node: Creating a CA certificate,  Next: Issuing certificates,  Prev: 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 \
         --certificate="FILE:ca.pem"

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 \
         --certificate="FILE:new-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" \
         --certificate="FILE:dev-ca.pem"


File: hx509.info,  Node: Issuing certificates,  Next: Issuing CRLs,  Prev: 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.

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

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


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:

   * Certificate Revocation List (CRL)

   * Online Certificate Status Protocol (OCSP)

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.


File: hx509.info,  Node: Issuing CRLs,  Next: Application requirements,  Prev: 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 \
     	--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


File: hx509.info,  Node: Application requirements,  Next: CMS signing and encryption,  Prev: 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" \
             --subject="cn=kdc"

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" \
             --certificate="FILE:user.pem"

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: *note 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 (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" \
               ...


File: hx509.info,  Node: CMS signing and encryption,  Next: CMS background,  Prev: 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.


File: hx509.info,  Node: CMS background,  Next: Certificate matching,  Prev: CMS signing and encryption,  Up: Top

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


File: hx509.info,  Node: Certificate matching,  Next: Matching syntax,  Prev: CMS background,  Up: Top

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

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


File: hx509.info,  Node: Matching syntax,  Next: Software PKCS 11 module,  Prev: Certificate matching,  Up: Top

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}


File: hx509.info,  Node: Software PKCS 11 module,  Next: How to use the PKCS11 module,  Prev: 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.


File: hx509.info,  Node: How to use the PKCS11 module,  Prev: 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
     EOF
     $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@EXAMPLE.ORG



Tag Table:
Node: Top203
Node: Introduction797
Node: What is X.509 ?2246
Node: Setting up a CA6204
Node: Creating a CA certificate7474
Node: Issuing certificates9915
Node: Issuing CRLs12458
Node: Application requirements13085
Node: CMS signing and encryption18446
Node: CMS background18797
Node: Certificate matching18953
Node: Matching syntax19207
Node: Software PKCS 11 module19764
Node: How to use the PKCS11 module20283

End Tag Table