SoftHSM Documentation v2

Download

Release:

• Can be download on  https://www.opendnssec.org/download/

Git repository:

git clone https://github.com/opendnssec/SoftHSMv2.git

Dependencies

SoftHSM depends on a cryptographic library, Botan or OpenSSL. Minimum required versions:

• Botan 1.10.0
• OpenSSL 1.0.0

If you are using Botan, make sure that it has support for GNU MP (--with-gnump). This will improve the performance when doing public key operations.

There is a migration tool for converting token databases from SoftHSMv1 into the new type of tokens. If this tool is built, then SQLite3 is required (>= 3.4.2).

Building from the repository

If the code is downloaded directly from the code repository, you have to prepare the configuration scripts.

1. You need to install automake, autoconf, libtool, etc.
2. Run the command 'sh autogen.sh'
3. Continue with the instructions below.

Installing

1. Configure the installation/compilation scripts.

   tar -xzf softhsm-<version>.tar.gz
   cd softhsm-<version>
   ./configure
   

   Options:

   --disable-non-paged-memory
                           Disable non-paged memory for secure storage
                           (default enabled)
   --disable-ecc           Disable support for ECC (default enabled)
   --disable-gost          Disable support for GOST (default enabled)
   --enable-visibility     Enable -fvisibility=hidden GCC flags so
                           only the PKCS#11 C_* entry points are kept
   --with-crypto-backend   Select crypto backend (openssl|botan)
   --with-openssl=PATH     Specify prefix of path of OpenSSL
   --with-botan=PATH       Specify prefix of path of Botan
   --with-loglevel=INT     The log level. 0=No log 1=Error 2=Warning 3=Info
                           4=Debug (default INT=3)
   --with-migrate          Build the migration tool. Used when migrating
                           a SoftHSM v1 token database. Requires SQLite3.
   --with-objectstore-backend-db
                           Build with database object store (SQLite3)
   --with-sqlite3=PATH     Specify prefix of path of SQLite3

   For more options:

   ./configure --help
   

2. Compile the source code using the following command:

   make
   

3. Install the library using the follow command:

   sudo make install
   

4. Location of the configuration file.

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

   export SOFTHSM2_CONF=/home/user/config.file
   

   Details on the configuration can be found in "man softhsm2.conf".
    

5. Initialize your tokens.

   Use either softhsm-util or the PKCS#11 interface. The SO PIN can e.g. be used to re-initialize the token and the user PIN is handed out to the application so it can interact with the token.

   softhsm2-util --init-token --slot 0 --label "My token 1"
   

   Type in SO PIN and user PIN.

   Once a token has been initialized, more slots will be added automatically with a new uninitialized token.
    

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

Backup

All of the tokens and their objects are stored in the location given by softhsm2.conf. Backup can thus be done as a regular file copy.