$Id$

SoftHSM is part of the OpenDNSSEC project.
Read more at www.opendnssec.org

INTRODUCTION

The DNSSEC Signer, part of the OpenDNSSEC project, handles and stores its 
cryptographic keys via the PKCS#11 interface. This interface specifies how 
to communicate with cryptographic devices such as HSM:s (Hardware Security 
Modules) and smart cards. The purpose of these devices is, among others, 
to generate cryptographic keys and sign information without revealing 
private-key material to the outside world. They are often designed to 
perform well on these specific tasks compared to ordinary processes in a 
normal computer.

A potential problem with the use of the PKCS#11 interface is that it might 
limit the wide spread use of the DNSSEC Signer, since a potential user 
might not be willing to invest in a new hardware device. To counter this 
effect, OpenDNSSEC is providing a software implementation of a generic 
cryptographic device with a PKCS#11 interface, the SoftHSM. SoftHSM is 
designed to meet the requirements of the DNSSEC Signer, but can also work 
together with other cryptographic products because of the PKCS#11 
interface.

DEPENDENCIES

SoftHSM depends on the Botan 1.8.1 or greater (a cryptographic library) 
and SQLite 3.4.2 or greater (a database library). They can be found at:
  http://botan.randombit.net
and
  http://www.sqlite.org

INSTALLING

1. Configure the installation/compilation scripts.

  ./configure

  Options:

    --with-botan-lib=DIR    The location of the Botan crypto library 
                            (default DIR=/usr/local/lib)
    --with-botan-inc=DIR    The location of the Botan crypto library 
                            include files (default DIR=/usr/local/include)
    --with-sqlite3-lib=DIR  The location of the SQLite3 library 
                            (default DIR=/usr/lib)
    --with-sqlite3-inc=DIR  The location of the SQLite3 library include 
                            files (default DIR=/usr/include)
    --enable-64bit          Compile a 64-bit version
    --with-loglevel=INT     The log level. 0=No log 1=Error 2=Warning 
                            3=Info 4=Debug (default INT=3)
    --prefix=DIR            The installation directory
                            (default DIR=/usr/local)

  For more options:

  ./configure --help

2. Compile the source code.

  make

3. Install the library

  sudo make install

4. Create your tokens

  softhsm --init-token /home/user/my.db --label "My token 1"

   Type in SO and user PIN.

  softhsm --init-token /home/user/token.database --label "A token"
 
   Type in SO and user PIN.

5. Add the tokens to the slots:

  The default location of the config file is /etc/softhsm.conf
  This location can be change by setting the environment variable.

    export SOFTHSM_CONF=/home/user/config.file

  Open the config file and add the slots

    sudo pico /etc/softhsm.conf

      0:/home/user/my.db
      1:/etc/softhsm/non.existing.token
      4:/home/user/token.database

  (Slot 1 will be empty since that database does not exist)

6. Link to this library and use the PKCS#11 interface