README
Download
Release:
- softhsm-1.1.3.tar.gz (2010-01-25)
SVN repository (Read the README.svn):
svn co http://svn.opendnssec.se/trunk/softHSM/
Dependencies
SoftHSM depends on the Botan 1.8.0 or greater (a cryptographic library)
and SQLite 3.4.2 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. If the packaged
version for your distribution does not work try to compile the latest
version from source They can be found at:
and
Installing
1. Configure the installation/compilation scripts.
tar -xzf libsofthsm-1.0.0.tar.gz cd libsofthsm-1.0.0 ./configure
Options:
--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.
make
3. Install the library
sudo make install
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
pico /home/user/config.file
0:/home/user/my.db
# Comments can be added
4:/home/user/token.database
NOTE:
The token databases does not exist at this stage. The given paths are just an
indication to SoftHSM on where it should store the information for each token.
Each token are now treated as uninitialized.
5. Initialize your tokens. Use either the softhsm tool or the PKCS#11 interface.
softhsm --init-token --slot 0 --label "My token 1" Type in SO PIN and user PIN.
softhsm --init-token --slot 4 --label "A token" Type in SO PIN and user PIN.
6. 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 Kexample.com.+007+05474.private --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 example.com. --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:
Kexample.com.+007+05474.private
Kexample.com.+007+05474.key
Backup
A token can be backed up by issuing the command:
sqlite3 <PATH TO TOKEN> .dump | sqlite3 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.
