SoftHSMv2/README.md

   1 # SoftHSM version 2
   2
   3 SoftHSM is part of the OpenDNSSEC project. Read more at www.opendnssec.org.
   4
   5 [![Travis Build Status](https://api.travis-ci.org/opendnssec/SoftHSMv2.png)](https://travis-ci.org/opendnssec/SoftHSMv2)
   6 [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/opendnssec/SoftHSMv2?svg=true)](https://ci.appveyor.com/project/opendnssec/softhsmv2)
   7
   8 ## Introduction
   9
  10 OpenDNSSEC handles and stores its cryptographic keys via the PKCS#11 interface.
  11 This interface specifies how to communicate with cryptographic devices such as
  12 HSM:s (Hardware Security Modules) and smart cards. The purpose of these devices
  13 is, among others, to generate cryptographic keys and sign information without
  14 revealing private-key material to the outside world. They are often designed to
  15 perform well on these specific tasks compared to ordinary processes in a normal
  16 computer.
  17
  18 A potential problem with the use of the PKCS#11 interface is that it might
  19 limit the wide spread use of OpenDNSSEC, since a potential user might not be
  20 willing to invest in a new hardware device. To counter this effect, OpenDNSSEC
  21 is providing a software implementation of a generic cryptographic device with a
  22 PKCS#11 interface, the SoftHSM. SoftHSM is designed to meet the requirements of
  23 OpenDNSSEC, but can also work together with other cryptographic products
  24 because of the PKCS#11 interface.
  25
  26 ## Developers
  27
  28 - Rickard Bellgrim (Knowit Secure AB, www.knowitgroup.com)
  29 - Francis Dupont (ISC, www.isc.org)
  30 - René Post (XPT Software and Consulting, www.xpt.nl)
  31 - Roland van Rijswijk (SURFnet bv, www.surfnet.nl)
  32
  33 ## Dependencies
  34
  35 SoftHSM depends on a cryptographic library, Botan or OpenSSL.
  36 Minimum required versions:
  37
  38 - Botan 1.10.0
  39 - OpenSSL 1.0.0
  40
  41 If you are using Botan, make sure that it has support for GNU MP (--with-gnump).
  42 This will improve the performance when doing public key operations.
  43
  44 The GNU Autotools (Autoconf, Automake, Libtool) are also required for building
  45 the software. It is also recommended to install pkg-config so that the
  46 configure script can find the installed software.
  47
  48 There is a migration tool for converting token databases from SoftHSMv1 into
  49 the new type of tokens. If this tool is built (--with-migrate), then SQLite3
  50 is required (>= 3.4.2).
  51
  52 SQLite3 is also required if building with the database object store
  53 (--with-objectstore-backend-db).
  54
  55 To install SoftHSM as a PKCS#11 module on the system, please install
  56 libp11-kit-dev.
  57
  58 The unit tests requires CppUnit.
  59
  60 ## Installation
  61
  62 ### Configure
  63
  64 Configure the installation/compilation scripts:
  65
  66         sh ./autogen.sh
  67         ./configure
  68
  69 Options:
  70
  71         --disable-non-paged-memory
  72                                 Disable non-paged memory for secure storage
  73                                 (default enabled)
  74         --disable-ecc           Disable support for ECC (default enabled)
  75         --disable-eddsa         Disable support for EDDSA (default enabled)
  76         --disable-gost          Disable support for GOST (default enabled)
  77         --disable-visibility    Disable hidden visibilty link mode [enabled]
  78         --with-crypto-backend   Select crypto backend (openssl|botan)
  79         --with-openssl=PATH     Specify prefix of path of OpenSSL
  80         --with-botan=PATH       Specify prefix of path of Botan
  81         --with-migrate          Build the migration tool. Used when migrating
  82                                 a SoftHSM v1 token database. Requires SQLite3
  83         --with-objectstore-backend-db
  84                                 Build with database object store (SQLite3)
  85         --with-sqlite3=PATH     Specify prefix of path of SQLite3
  86         --disable-p11-kit       Disable p11-kit integration (default enabled)
  87         --with-p11-kit=PATH     Specify install path of the p11-kit module, will
  88                                 override path given by pkg-config
  89
  90 For more options:
  91
  92         ./configure --help
  93
  94
  95 ### Compile
  96
  97 Compile the source code using the following command:
  98
  99         make
 100
 101 ### Unit tests
 102
 103 Running the unit tests requires CppUnit.
 104
 105         make check
 106
 107 ### Install Library
 108
 109 Install the library using the follow command:
 110
 111         sudo make install
 112
 113 ### Configure
 114
 115 The default location of the config file is /etc/softhsm2.conf. This location
 116 can be change by setting the environment variable.
 117
 118         export SOFTHSM2_CONF=/home/user/config.file
 119
 120 Details on the configuration can be found in "man softhsm2.conf".
 121
 122 Create the token directory you defined in your config file:
 123
 124       mkdir <token_dir>
 125
 126 ### Initialize Tokens
 127
 128 Use either softhsm2-util or the PKCS#11 interface. The SO PIN can e.g. be used
 129 to re-initialize the token and the user PIN is handed out to the application so
 130 it can interact with the token.
 131
 132       softhsm2-util --init-token --slot 0 --label "My token 1"
 133
 134 Type in SO PIN and user PIN. Once a token has been initialized, more slots will
 135 be added automatically with a new uninitialized token.
 136
 137 Initialized tokens will be reassigned to another slot (based on the token
 138 serial number). It is recommended to find and interact with the token by
 139 searching for the token label or serial number in the slot list / token info.
 140
 141 ### Link
 142
 143 Link to this library and use the PKCS#11 interface.
 144
 145
 146 ## Backup
 147
 148 All of the tokens and their objects are stored in the location given by
 149 softhsm2.conf. Backup can thus be done as a regular file copy.
 150
 151
 152 ## Log information
 153
 154 Log information is sent to syslog or the Windows event log and the log
 155 level is set in the configuration file. Each log event is prepended with
 156 the source file name and line number.
 157
 158
 159 ## Building from the repository
 160
 161 If the code is downloaded directly from the code repository, you have to
 162 prepare the configuration scripts before continuing with the real README.
 163
 164 1. You need to install automake, autoconf, libtool, libtool-ltdl-devel (RHEL/CentOS), pkg-config.
 165 2. Run the command 'sh autogen.sh'
 166 3. Continue reading this README.