Fix issue: Softhsm-daemon leaks memory when certificate is stored
[keystone-linux/ti-softhsmv2.git] / README
1 $Id: README 6773 2012-10-24 16:21:48Z rb $
3   SoftHSM is part of the OpenDNSSEC project.
4   Read more at www.opendnssec.org
6 INTRODUCTION
8   OpenDNSSEC handles and stores its cryptographic keys via the PKCS#11 
9   interface. This interface specifies how to communicate with cryptographic 
10   devices such as HSM:s (Hardware Security Modules) and smart cards. The 
11   purpose of these devices is, among others, to generate cryptographic keys 
12   and sign information without revealing private-key material to the outside 
13   world. They are often designed to perform well on these specific tasks 
14   compared to ordinary processes in a normal computer.
16   A potential problem with the use of the PKCS#11 interface is that it might 
17   limit the wide spread use of OpenDNSSEC, since a potential user might not 
18   be willing to invest in a new hardware device. To counter this effect, 
19   OpenDNSSEC is providing a software implementation of a generic 
20   cryptographic device with a PKCS#11 interface, the SoftHSM. SoftHSM is 
21   designed to meet the requirements of OpenDNSSEC, but can also work together 
22   with other cryptographic products because of the PKCS#11 interface.
24 DEPENDENCIES
26   SoftHSM depends on a cryptographic library, Botan or OpenSSL.
27   Minimum required versions:
28   * Botan 1.10.0
29   * OpenSSL 0.9.8
31   There is a migration tool for converting token databases from SoftHSMv1
32   into the new type of tokens. If this tool is built, then SQLite3 is
33   required (>= 3.4.2).
35 INSTALLING
37   1. Configure the installation/compilation scripts.
39     ./configure
41     Options:
43       --disable-non-paged-memory
44                               Disable non-paged memory for secure storage
45                               (default enabled)
46       --with-crypto-backend   Select crypto backend (openssl|botan)
47       --with-openssl=PATH     Specify prefix of path of OpenSSL
48       --with-botan=PATH       Specify prefix of path of Botan
49       --with-loglevel=INT     The log level. 0=No log 1=Error 2=Warning 3=Info
50                               4=Debug (default INT=3)
51       --with-migrate          Build the migration tool. Used when migrating
52                               a SoftHSM v1 token database. Requires SQLite3.
53       --with-sqlite3=PATH     Specify prefix of path of SQLite3
55     For more options:
57     ./configure --help
59   2. Compile the source code.
61     make
63   3. Install the library.
65     sudo make install
67   4. Location of the configuration file.
69     The default location of the config file is /etc/softhsm2.conf
70     This location can be change by setting the environment variable.
72       export SOFTHSM2_CONF=/home/user/config.file
74     Details on the configuration can be found in "man softhsm2.conf".
76   5. Initialize your tokens.
78     Use either softhsm-util or the PKCS#11 interface. The SO PIN can e.g.
79     be used to re-initialize the token and the user PIN is handed out to the
80     application so it can interact with the token.
82       softhsm-util --init-token --slot 0 --label "My token 1"
84     Type in SO PIN and user PIN.
86     Once a token has been initialized, more slots will be added automatically
87     with a new uninitialized token.
89   6. Link to this library and use the PKCS#11 interface.
91 BACKUP
93   All of the tokens and their objects are stored in the location given by
94   softhsm2.conf. Backup can thus be done as a regular file copy.