From e352de80516bcfaa2ca001238c1eec46268ac886 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Fri, 22 Mar 2019 13:19:25 +0100 Subject: [PATCH 01/15] Document the HSM Daemon This fixes #586. --- modules/admin_manual/nav.adoc | 1 + .../server/security/hsmdaemon.adoc | 514 ++++++++++++++++++ 2 files changed, 515 insertions(+) create mode 100644 modules/admin_manual/pages/configuration/server/security/hsmdaemon.adoc diff --git a/modules/admin_manual/nav.adoc b/modules/admin_manual/nav.adoc index d40d665620..48956eecea 100644 --- a/modules/admin_manual/nav.adoc +++ b/modules/admin_manual/nav.adoc @@ -64,6 +64,7 @@ **** Security ***** xref:configuration/server/security/password_policy.adoc[Password policy] ***** xref:configuration/server/security/oauth2.adoc[OAuth2] +***** xref:configuration/server/security/hsmdaemon.adoc[The HSM Daemon] **** xref:configuration/server/activity_configuration.adoc[Activity Configuration] **** xref:configuration/server/antivirus_configuration.adoc[Antivirus Configuration] **** xref:configuration/server/automatic_configuration.adoc[Automatic Configuration] diff --git a/modules/admin_manual/pages/configuration/server/security/hsmdaemon.adoc b/modules/admin_manual/pages/configuration/server/security/hsmdaemon.adoc new file mode 100644 index 0000000000..59b6727ed1 --- /dev/null +++ b/modules/admin_manual/pages/configuration/server/security/hsmdaemon.adoc @@ -0,0 +1,514 @@ += The HSM Daemon (hsmdaemon) +:hsm-url: https://en.wikipedia.org/wiki/Hardware_security_module +:base64-encoding-url: https://en.wikipedia.org/wiki/Base64 +:pkcs11-url: https://en.wikipedia.org/wiki/PKCS_11 + +The hsmdaemon is a daemon to delegate encryption to an {hsm-url}[HSM (Hardware Security Module)]. +It can be necessary, as PHP cannot directly interface with {pkcs11-url}[a PKCS11 stack]; neither by an API wrapper, because one does not exist, yet, nor via the OpenSSL bindings +Because of this, a separate process is needed to decrypt anything with the private key stored in an HSM. + +Running exec() to decrypt the key with a command line command to do the encryption might leak the HSM credentials if the admin lists the currently running processes. +To prevent that an "HSM" daemon will be used that can open a session to the HSM upon startup. +This daemon will be used by ownCloud to decrypt the current master key upon request. +The communication will happen via UNIX or TCP sockets and is authorized by a shared token that the daemon stores in the ownCloud database via a REST/JSON route. + +ownCloud internally uses OpenSSL to en-/decrypt keys and needs to be extended to support en-/decrypt operations via the new daemon. +The current solution would be to encrypt the current ownCloud master key with a key from the HSM. +Doing so only requires patching `KeyManagers` `getMasterKeyPassword()` and `getSystemPrivateKey()` methods to decrypt the key read from disk. + +== How The HSM Daemon Interacts with ownCloud + +Upon startup, the daemon will generate a token and send it to ownCloud via a new REST/JSON route. +After connecting with the HSM daemon, an unsophisticated, line-based, protocol is used (every line ends with CRLF): + +. ownCloud sends the token read from database. +. The daemon compares the received token with its token and returns an `"OK"` line. +. ownCloud then sends the data it wants to decrypt as a {base64-encoding-url}[Base64-encoded], one-line string. +. The daemon returns the decrypted data as a Base64-encoded one-line string. + +Doing so ensures that an evil admin will need to wiretap the communication between either the database or the HSM daemon and ownCloud. + +== Installation + +=== Overview + +HSM support consists of three main parts: + +. An actual HSM PKCS11 module +. The hsmdaemon that provides a JWT protected web API for the PKCS11 stack to generate key pairs and decrypt data +. A patch to the ownCloud encryption app + +All commands are assumed to be executed as root unless stated otherwise. + +=== Deployment and Resource Usage + +We recommend running hsmdaemon on every Apache server to reduce latency. +The daemon uses few resources: + +[source,console] +---- +$ ps aux --sort -rss | head -1 +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +$ ps aux --sort -rss | grep hsm | grep -v grep +root 19568 0.0 0.0 231052 2608 ? Ssl Feb08 0:00 /home/jfd/Repositories/hsmdaemon/hsmdaemon +---- + +=== Installing a PKCS11 Module + +==== Using a Preconfigured PKCS11 Module + +At least one PKCS11 library is necessary. Ask the customer for the path to a fully configured PKCS11 module. +The HSM vendor typically provides the PKCS11 module, e.g., `/opt/nfast/toolkits/pkcs11/libcknfast.so` for Thales nShield. + +If none is available, you can follow the below optional steps to install a software HSM. + +==== [optional] Installing SoftHSM 2 + +On Debian, two packages are available: `softhsm` and `softhsm2`. +Install `softhsm2` with + +[source,console] +---- +apt install softhsm2 +---- + +Installing them also installs `/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so`, which is a module that we will need later, for interaction with the PKCS11 API. +The Debian location of the config file is `/etc/softhsm/softhsm2.conf`: + +[source,ini] +.... +# SoftHSM v2 configuration file + +directories.tokendir = /var/lib/softhsm/tokens/ +objectstore.backend = file + +# ERROR, WARNING, INFO, DEBUG +log.level = INFO +.... + +Make sure the `directories.tokendir` exists. +Now we can initialize the token: + +[source,console] +---- +softhsm2-util --init-token --slot 0 --label "My token 1" +---- + +It will ask for two PINs, a user and SO pin. +See https://www.opendnssec.org/softhsm/, for more information. + +==== [optional] Installing PKCS11 CLI tools + +To use the PKCS11 API on the CLI, we install `opensc` with: + +[source,console] +---- +apt install opensc +---- + +Now we can list the tokens with + +[source,console] +---- +pkcs11-tool --module /usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so -l --pin 1234 -O +---- + +The module parameter is the library provided by the HSM vendor; in this case, it was installed with SoftHSM 2. +See https://github.com/OpenSC/OpenSC/wiki for more information. + +=== Installing the hsmdaemon + +Installing hsmdaemon requires several steps. +These are: + +. xref:install-the-binary[Install the Binary] +. xref:install-the-system-service[Install the System Service] +. xref:copy-the-config-file[Copy the Config File] +. xref:configure-the-pkcs11-module-path[Configure the PKCS 11 Module Path] +. xref:configure-slot-and-pin[Configure Slot and Pin] +. xref:test-key-generation[Test Key Generation] +. xref:configure-other-options[Configure Other Options] +. xref:owncloud-setup[ownCloud Setup] + +==== Install the Binary + +To install the hsmdaemon, you first need to install the package’s dependencies, stored in `go.mod`. To install them, run `go get`. +The command should not show any console output and take no more than a few minutes. + +Once the package dependencies are installed, you next need to compile hsmdaemon. +To do this, use the command: `make install`, which creates the hsmdaemon binary in the `bin` directory of your `$GOPATH`, naming it `hsmdaemon`. +After compilation, you need to make the file executable and move it to a directory located in your system path. + +If you are not sure which directories are in your system path, run the following script to see a complete list: + +[source,console] +---- +OFS=$IFS && IFS=':' +for i in $(echo $PATH); do echo $i; done; +IFS=$OFS; +---- + +You should see a list similar to the following: + +[source,console] +---- +/usr/local/sbin +/usr/local/bin +/usr/sbin +/usr/bin +/sbin +/bin +---- + +===== Installation Example + +To save time, copy and paste the commands below to compile the hsmdaemon. + +[source,console] +---- +# Install hsmdaemon's dependencies +go get + +# Compile hsmdaemon +make install + +# Make the file executable +chmod +x hsmdaemon +---- + +==== Install the System Service + +Now that the binary is available, hsmdaemon must be installed as a system service. +To do this, run it with the `install` option, as in the example below. + +[source,console] +---- +$ ./hsmdaemon install +---- + +If it installs successfully, then you should see the following console output: + +.... +Install HSM Daemon: [ OK ] +.... + +==== Copy the Config File + +Now that the hsmdaemon is ready, its config file needs to be prepared. +The default location that hsmdaemon looks for its config file is `/etc/hsmdaemon/hsmdaemon.toml`. +To create it from the example config file available in the cloned repository, run the following commands. + +[source,console] +---- +$ mkdir /etc/hsmdaemon # Create the hsmdaemon configuration directory +$ cp hsmdaemon.toml /etc/hsmdaemon/hsmdaemon.toml # Copy the example config file +$ chown root /etc/hsmdaemon/hsmdaemon.toml # Set the owner of the file to root +$ chmod 750 /etc/hsmdaemon/hsmdaemon.toml # Allow only the root and users in the root group to read & write the configuration file +---- + +Have a look at the options of the executable: + +[source,console] +---- +$ hsmdaemon help +Usage: hsmdaemon install | remove | start | stop | status | listslots | genkey