SoftHSMv2/OSX-NOTES.md

   1 # Building SoftHSMv2 on macOS 10.12.3 (Sierra)
   2
   3 This document contains instructions for building SoftHSMv2 from the command
   4 line on macOS 10.12.3.
   5
   6 This may work for other versions of OS X/macOS, but this has not been verified.
   7
   8 ## Command Line Tools
   9
  10 We assume that XCode has been installed. To find out where Xcode keeps the C++
  11 compiler type the following at the command line:
  12
  13         $ xcode-select --print-path
  14         /Applications/Xcode.app/Contents/Developer
  15
  16 The gcc compiler in this case can be found at
  17 /Applications/Xcode.app/Contents/Developer/usr/bin/gcc
  18
  19 Alternatively if you don't want to install XCode you could install command line
  20 tools for macOS that can be downloaded from Apple.
  21
  22 e.g. currently the following package for the Sierra release of macOS is
  23 available for download.
  24
  25         Command_Line_Tools_macOS_10.12_for_Xcode_8.2.dmg
  26
  27 This dmg file is ~150MB but it is at least orders of magnitude smaller than
  28 installing all of XCode.
  29
  30 ## Homebrew
  31
  32 The libraries that come as part of macOS are rather old. We need to use more
  33 recent versions of these libraries to avoid unexpected failures during building
  34 and running.
  35
  36 There is a community supported command line package manager for installing the
  37 dependencies we need. It's called homebrew. First we'll need to install it as
  38 follows:
  39
  40         $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  41
  42 Now we need to install some dependencies
  43
  44         $ brew install automake
  45         $ brew install pkg-config
  46         $ brew install openssl
  47         $ brew install sqlite
  48         $ brew install cppunit
  49         $ brew install libtool
  50
  51 openssl, sqlite, and libtool are pre-installed on the system. The versions downloaded
  52 by brew are stored in an alternative location under /usr/local
  53
  54 The only brew warning of note is for libtool:
  55
  56         ==> Caveats
  57         In order to prevent conflicts with Apple's own libtool we have prepended a "g"
  58         so, you have instead: glibtool and glibtoolize.
  59
  60 Note: gblitoolize seems to be found in the configuration step below just fine. It's unclear
  61 if glibtool is used since autogen.sh generates its own libtool script that is used by make.
  62
  63 During configure, the paths to the newly installed libraries need to be passed
  64 in so configure can actually find the libraries. We'll show how to do that
  65 later.
  66
  67 ## Cloning SoftHSMv2
  68
  69 We now need to clone SoftHSMv2 from github.
  70
  71         $ git clone https://github.com/opendnssec/SoftHSMv2.git
  72         $ cd SoftHSMv2
  73
  74 ## Configuring the build
  75
  76 Start by installing autoconf in the source directory by executing the
  77 autogen.sh script.
  78
  79         $ sh ./autogen.sh
  80
  81 If all went well a configure script should have been generated. To find out the
  82 options available for building issue the following command:
  83
  84         $ ./configure --help
  85
  86 In the example below I will enable the optional token object store database
  87 backend.
  88
  89         $ ./configure --with-objectstore-backend-db \
  90                 --with-openssl=/usr/local/opt/openssl \
  91                 --with-sqlite3=/usr/local/opt/sqlite
  92
  93 Now if for some reason the compilers are not found, do the following at the
  94 command line.
  95
  96         $ export CC="xcrun gcc"
  97         $ export CPP="xcrun cpp"
  98         $ export CXX="xcrun g++"
  99         $ ./configure --with-objectstore-backend-db \
 100                 --with-openssl=/usr/local/opt/openssl \
 101                 --with-sqlite3=/usr/local/opt/sqlite
 102
 103 By exporting these environment variables we are instructing configure to use
 104 the compilers stored inside the installed XCode.app.
 105
 106 ## Building and Testing SoftHSMv2
 107
 108 Now we can build SoftHSMv2 by just executing make.
 109
 110         $ make
 111
 112 And we can check that it works by running all tests.
 113
 114         $ make check
 115
 116 To try a specific test, e.g. to check just the PKCS#11 test cases use the
 117 following make command:
 118
 119         $ make -C src/lib/test check
 120
 121 Then change src/lib/test/softhsm2.conf so it contains the following lines.
 122
 123         # SoftHSM v2 configuration file
 124         directories.tokendir = ./tokens
 125         objectstore.backend = db
 126         log.level = INFO
 127         slots.removable = false
 128
 129 Then change src/lib/test/softhsm2-alt.conf so it contains the following lines.
 130
 131         # SoftHSM v2 configuration file
 132         directories.tokendir = ./tokens
 133         objectstore.backend = db
 134         log.level = INFO
 135         slots.removable = true
 136
 137 We are now ready to run the tests again.
 138
 139         $ make -C src/lib/test check
 140
 141 Because the object store backend was changed from file to db we have used
 142 sqlite for storing the token objects. Verify this by looking in the sub-folders
 143 of src/lib/test/tokens There you should find a database file named sqlite3.db
 144
 145 ## Performance
 146
 147 The file backend currently exhibits the best performance. It is normally at
 148 least twice as fast as the database backend.
 149
 150 The idea behind storing token objects in a database is that it has advantages
 151 when a large number (> 100K) of keys are stored in a token. A database allows
 152 for selectively querying and loading in only a subset of the keys into memory.
 153 The file based storage backend reads in the complete contents of the token.
 154 Also because the database is only a single file, we should not hit any system
 155 limitations w.r.t. the number of files that can be stored in a file system.
 156
 157 The database backend uses transactions to write changes to the token database.
 158 For modifiable attributes this will require a round trip to the database every
 159 time an attribute has been read as another process may have modified the given
 160 attribute.
 161
 162 The database backend uses approximately 20% less memory because it will only
 163 load in object attributes on demand. For non-mutable attributes that is not a
 164 problem because once an object with its attributes is created those attributes
 165 won't change. On the other hand the mutable attributes of the object are always
 166 read when the object is accessed, making it slower because this will require a
 167 roundtrip to the database for every mutable attribute. Note that most
 168 attributes are non-mutable and especially the key material is non-mutable. So
 169 once this (encrypted !) material has been read into memory it will remain
 170 cached (encrypted !).
 171
 172 Currently the query functionality for only retrieving a subset of the objects
 173 is not yet implemented. Therefore the database solution has no advantages
 174 w.r.t. the file based solution for large number of files other than the 20%
 175 less memory usage mentioned before.
 176
 177 For applications that need the highest speed possible and only read/use the
 178 token, a solution would be to copy the whole of the token database to a
 179 ramdisk. This should only be used when the application doesn't modify the
 180 token, because a power-cycle of the host will wipe out the ramdisk.
 181
 182 3-January-2017