Skip to end of metadata
Go to start of metadata

SoftHSM is an implementation of a cryptographic store accessible through a PKCS#11 interface. You can use SoftHSM as an HSM for OpenDNSSEC.

On this Page

Useful references

If you are not familiar with HSMs or PKCS#11 you may find the following references helpful:



The code for SoftHSMv1 is now hosted on GitHub: 

git clone


SoftHSM depends on the Botan 1.8.0 or greater (a cryptographic library) and SQLite 3.3.9 or greater (a database library). But it is recommended to use Botan 1.8.5 or greater since there is a known issues on some OS which freezes the application when it tries to pull entropy. 

(lightbulb) If the packaged version for your distribution does not work try to compile the latest version from source (this will require a C++ compiler). They can be found at



1. Configure the installation/compilation scripts.

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


--with-botan=PATH       Specify prefix of path of Botan
--with-sqlite3=PATH     Specify prefix of path of SQLite3
--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.



3. Install the library

sudo make install


4. Configure and initialise the SoftHSM database

a. Specify the slots.

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

export SOFTHSM_CONF=/home/user/config.file

Open the config file and specify what slots will be used (note there should be no whitespace at the beginning of the lines):

> pico /home/user/config.file

# Comments can be added

The token databases do not exist at this stage. The given paths are just an indication to SoftHSM on where it should store the information for each slot/token.

Each token is now treated as uninitialized.

b. Initialize each of your tokens.

This stage creates the databases on disk that will be used to store the keys. Use either the softhsm tool or the PKCS#11 interface. 

For each token you will be asked to enter:

    • The SO PIN. This is the security officer PIN which can e.g. be used to re-initialize the token.
    • The user PIN. This is handed out to applications so the application can interact with the token (for example it is specified in the conf.xml file of OpenDNSSEC or (in v1.4 it can be entered via a command line option 'ods-hsmutil logon'). 
softhsm --init-token --slot 0 --label "OpenDNSSEC"

Type in SO PIN and user PIN.

softhsm --init-token --slot 4 --label "A token"

Type in SO PIN and user PIN.

When using SoftHSM with OpenDNSSEC the repository is identified by the following information in the OpenDNSSEC conf.xml file:

<Repository name="SoftHSM">


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

Key management

It is possible to export and import keys to libsofthsm.

1. Importing a key pair.

Use the PKCS#11 interface or the softhsm tool where you specify the path to the key file, slot number, label and ID of the new objects, and the user PIN.
The file must be in PKCS#8 format.

softhsm --import key1.pem --slot 1 --label "My key" --id A1B2 --pin 123456

Add, --file-pin <PIN>, if the key file is encrypted.
Use, softhsm --help, for more info.

2. Exporting a key pair.

All keys can be exported from the token database by using the softhsm tool. The file will be exported in PKCS#8 format.

softhsm --export key2.pem --slot 1 --id A1B2 --pin 123456

Add, --file-pin <PIN>, if you want to output an encrypted file.
Use, softhsm --help, for more info.

Converting keys to/from BIND

The softhsm-keyconv tool can convert keys between BIND .private-key format and PKCS#8 key file format.

1. Convert from BIND .private to PKCS#8

Keys used for DNSSEC in BIND can be converted over to PKCS#8. Thus possible to import them into SoftHSM.

softhsm-keyconv --topkcs8 --in --out rsa.pem

Add, --pin <PIN>, if you want an encrypted PKCS#8 file.
Use, softhsm-keyconv --help, for more info.

 2. Convert from PKCS#8 to BIND .private and .key

PKCS#8 files can be converted to key used for DNSSEC signing in BIND. The public key is also saved to file.

softhsm-keyconv --tobind --in rsa.pem --name --ttl 3600 \
                    --ksk --algorithm RSASHA1-NSEC3-SHA1

Add, --pin <PIN>, if you the PKCS#8 file is encrypted.
Use, softhsm-keyconv --help, for more info.

The following files will be created in this example:


A token can be backed up by issuing the command:

sqlite3 <PATH TO YOUR TOKEN> ".backup copy.db"

Copy the "copy.db" to a secure location. To restore the token, just copy the file back to the system and add it to a slot in the file softhsm.conf.

If you are using SQLite3 version < 3.6.11, then you have to use the command below. But it will not copy the "PRAGMA user_version", which is used by SoftHSM for versioning. So you have to do that manually. In this case the version number is 100.

sqlite3 <PATH TO YOUR TOKEN> .dump | sqlite3 copy.db
sqlite3 copy.db "PRAGMA user_version = 100;"

Some attributes in the PKSC#11 API are defined as CK_ULONG, unsigned long integer, where the length of the data depends on the architecture (32-bit, 64-bit). The attributes are stored directly in the database. The database can thus not be moved between two systems with different architectures.

  • No labels