From 2d019efdf5362d56d594744d910b06c8a5985885 Mon Sep 17 00:00:00 2001 From: mmattel Date: Tue, 22 Jun 2021 18:42:38 +0200 Subject: [PATCH 1/4] fix hsmdeamon --- .../server/security/hsmdaemon/index.adoc | 208 ++++++++---------- 1 file changed, 88 insertions(+), 120 deletions(-) diff --git a/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc b/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc index 365e8cccc2..8b1b024e6c 100644 --- a/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc +++ b/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc @@ -12,38 +12,30 @@ :pkcs11-tool-url: https://linux.die.net/man/1/pkcs11-tool :softhsm2-url: https://www.opendnssec.org/softhsm/ :unix-sockets-url: http://beej.us/guide/bgipc/html/multi/unixsock.html +:opendnssec-url: https://www.opendnssec.org/softhsm/ == Introduction -The hsmdaemon is a daemon, provided by ownCloud, to delegate encryption to an {hsm-url}[HSM (Hardware Security Module)]. -This can be necessary, as PHP cannot, directly, interface with {pkcs11-url}[a PKCS11 stack]; neither with an API wrapper, because one does not exist, nor via the OpenSSL bindings. -Because of this, a separate process is needed to decrypt anything with the private key stored in an HSM. +The `hsmdaemon` is a daemon provided by ownCloud to delegate encryption to an {hsm-url}[HSM (Hardware Security Module)]. This can be necessary as PHP cannot directly interface with {pkcs11-url}[a PKCS11 stack], neither with an API wrapper because none exists, nor via the OpenSSL bindings. Therefore a separate process is needed to decrypt anything with the private key stored in an HSM. -NOTE: When using hsmdaemon with an HSM, the keys _may_ still be stored on the same physical machine as ownCloud. +NOTE: When using `hsmdaemon` with an HSM, the keys _may_ still be stored on the same physical machine as ownCloud. -NOTE: For hsmdaemon support, you need ownCloud Enterprise Edition >= 10.2. -We recommend consulting with us when deploying storage encryption with an HSM. +NOTE: For hsmdaemon support, you need ownCloud Enterprise Edition >= 10.2. We recommend consulting with us when deploying storage encryption with an HSM. -Running {php-exec-function-url}[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. +Running {php-exec-function-url}[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 happens via {unix-sockets-url}[UNIX sockets] or {network-sockets-url}[TCP sockets] and is authorized by a shared token that the daemon stores in the ownCloud database via a REST/JSON route. +This daemon will be used by ownCloud to decrypt the current master key upon request. The communication happens via {unix-sockets-url}[UNIX sockets] or {network-sockets-url}[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 encrypts the ownCloud master key with a key from the HSM. +ownCloud internally uses OpenSSL to encrypt and decrypt keys and needs to be extended to support en-/decrypt operations via the new daemon. The current solution encrypts the ownCloud master key with a key from the HSM. -NOTE: From the technical point of view the `Crypt` class is extended to handle the key generation in the HSM device and also to get the key from HSM. -For the read/write operation on a file, the request goes to the HSM and then, based on the keys fetched from HSM, the files are encrypted or decrypted. -The keys are not replaced. +NOTE: From the technical point of view the `Crypt` class is extended to handle the key generation in the HSM device and also to get the key from HSM. For the read/write operation on a file, the request goes to the HSM and then, based on the keys fetched from HSM, the files are encrypted or decrypted. The keys are not replaced. == 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): +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. +. 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. @@ -54,15 +46,15 @@ Doing so ensures that an evil admin will need to wiretap the communication betwe HSM support consists of two core parts: . An actual HSM PKCS11 module. -. An hsmdaemon that provides a {jwt-url}[JWT]-protected web API for the PKCS11 stack to generate key pairs and decrypt data. +. A `hsmdaemon` that provides a {jwt-url}[JWT] - protected web API for the PKCS11 stack to generate key pairs and decrypt data. == Deployment Recommendation -We recommend running hsmdaemon on every web server to reduce latency. +We recommend running `hsmdaemon` on every web server to reduce latency. == Installation -Integrating the hsmdaemon with ownCloud requires 3 steps; these are: +Integrating the `hsmdaemon` with ownCloud requires 3 steps; these are: . xref:install-a-pkcs11-module[Install a PKCS11 Module] . xref:install-and-configure-the-hsmdaemon[Install and Configure the hsmdaemon] @@ -78,9 +70,7 @@ If you are using a different operating system or distribution, please adjust the ==== Install Using a Preconfigured PKCS11 Module -At least one PKCS11 library is necessary. -This is typically provided by an HSM vendor. -If a PKCS11 library is not available, you can xref:configuration/server/security/hsmdaemon/softhsm2.adoc[use the software HSM, _SoftHSM2_]. +At least one PKCS11 library is necessary. This is typically provided by an HSM vendor. If a PKCS11 library is not available, you can xref:configuration/server/security/hsmdaemon/softhsm2.adoc[use the software HSM - _SoftHSM2_]. ==== Initialise the Token @@ -88,11 +78,10 @@ Now we can initialize the token: [source,console] ---- -softhsm2-util --init-token --slot 0 --label "My token 1" +sudo softhsm2-util --init-token --slot 0 --label "My token 1" ---- -It will ask for two PINs, an SO and a User pin. -See https://www.opendnssec.org/softhsm/, for more information. +It will ask for two PINs, an SO and a User pin. See {opendnssec-url}[opendnssec] for more information. The SO PIN can e.g. be used to re-initialize the token and the user PIN is handed out to the application so it can interact with the token. ==== Install PKCS11 CLI tools (optional) @@ -117,7 +106,7 @@ To install OpenSC on openSUSE and SUSE Linux Enterprise Server, run the followin [source,console] ---- -sudo sudo zypper install -y --auto-agree-with-licenses opensc +sudo zypper install -y --auto-agree-with-licenses opensc ---- ===== Initialise on Fedora and Red Hat Enterprise Linux and Centos @@ -131,7 +120,7 @@ sudo yum install --assumeyes opensc ==== List Tokens -You can list the available tokens using {pkcs11-tool-url}[pkcs11-tool], by running the following command. +You can list available tokens using the {pkcs11-tool-url}[pkcs11-tool] by running the following command: [source,console] ---- @@ -140,23 +129,28 @@ sudo pkcs11-tool --module -l --pin -O ===== The Module Parameter -The module parameter is either the library provided by the HSM vendor, or `libsofthsm2` which was installed with SoftHSM 2. -If you are using `libsofthsm2`, the path to `libsofthsm2.so` for each of the supported distributions is available below. +The module parameter is either the library provided by the HSM vendor or `libsofthsm2` which was installed with SoftHSM 2. If you are using `libsofthsm2`, the path to `libsofthsm2.so` for each of the supported distributions is available below. [options="headers",cols="2"] |=== -|Distribution |Path -|Debian and Ubuntu |`/usr/lib/softhsm/libsofthsm2.so` -|openSUSE and SUSE Linux Enterprise Server |`/usr/lib64/pkcs11/libsofthsm2.so` -|Fedora and Red Hat Enterprise Linux and Centos |`/usr/lib64/pkcs11/libsofthsm2.so` +|Distribution +| Path + +|Debian and Ubuntu +| `/usr/lib/softhsm/libsofthsm2.so` + +|openSUSE and SUSE Linux Enterprise Server +| `/usr/lib64/pkcs11/libsofthsm2.so` + +|Fedora and Red Hat Enterprise Linux and Centos +| `/usr/lib64/pkcs11/libsofthsm2.so` |=== TIP: See the {opensc-wiki-url}[OpenSC Wiki] for more information. === Install and Configure the hsmdaemon -Installing hsmdaemon requires several steps. -These are: +Installing hsmdaemon requires several steps. These are: . xref:install-the-hsmdaemon-binary[Install the hsmdaemon Binary] . xref:copy-the-config-file[Copy the Config File] @@ -168,63 +162,41 @@ These are: ==== Install the hsmdaemon Binary -After you've obtained the hsmdaemon from ownCloud, you need to: - -. Move the hsmdaemon binary to a directory located in your system path. -. Make the hsmdaemon binary Executable -. xref:copy-the-config-file[Copy the Config File] - -[TIP] -==== -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: +After you have obtained the `hsmdaemon` from ownCloud, you need to move the `hsmdaemon` binary to a directory located in your system path and make the binary executable: [source,console] ---- -/usr/local/sbin -/usr/local/bin -/usr/sbin -/usr/bin -/sbin -/bin +sudo install -m 755 ./hsmdaemon /usr/local/bin/hsmdaemon ---- -==== ==== Copy the Config File -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 provided package, run the following commands. +The default location where `hsmdaemon` looks for its config file is `/etc/hsmdaemon/hsmdaemon.toml`. To create it from the example config file available in the provided package, 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 +# Create the hsmdaemon configuration directory +sudo mkdir /etc/hsmdaemon + +# Copy the example config file +# Allow only root and users in the root group to read & write the configuration file +sudo install -m 640 ./hsmdaemon.toml /etc/hsmdaemon/hsmdaemon.toml ---- ==== Install the System Service -Now that the binary is available and the configuration file is in place, hsmdaemon must be installed as a system service. -To do this, run it with the `install` option, as in the example below. +Now that the binary is available and the configuration file is in place, `hsmdaemon` must be installed as a system service. To do so, run it with the `install` option as in the example below. [source,console] ---- -./hsmdaemon install +sudo /usr/local/bin/hsmdaemon install +sudo service hsmdaemon start ---- -If it installs successfully, then you should see the following console output: +If it installs successfully, you should see the following console output: ---- -Install HSM Daemon: [ OK ] +Install HSM Daemon: [ OK ] ---- It should now be running and set to start automatically at boot time. @@ -235,7 +207,7 @@ The daemon is managed using the following three commands: * `sudo service hsmdaemon start` * `sudo service hsmdaemon stop` and -* `sudo service hsmdaemon status`. +* `sudo service hsmdaemon status` ==== ==== Configure the PKCS11 Module Path @@ -244,7 +216,8 @@ To set the path to the PKCS11 module, update the line below in `/etc/hsmdaemon/h ---- [pkcs11] -module = "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so" # softhsm v2 +# softhsm v2 +module = "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so" ---- ==== List Available Slots @@ -253,7 +226,8 @@ This command lists the available slots. [source,console] ---- -hsmdaemon listslots +sudo hsmdaemon listslots + {"level":"debug","ts":"2019-02-14T09:27:02.068+0100","caller":"hsmdaemon/keymanager.go:27","msg":"initialize pkcs11 module","module":"/usr/lib/softhsm/libsofthsm2.so"} {"level":"info","ts":"2019-02-14T09:27:02.087+0100","caller":"hsmdaemon/keymanager.go:65","msg":"Slots found","slotIds":[550099622,1989683358,2]} Available slots: @@ -298,14 +272,17 @@ TIP: See the {opensc-wiki-url}[OpenSC Wiki] for more information. ==== Configure the Slot and Pin -Ask the customer which slot to use and if a PIN is needed. -Update `/etc/hsmdaemon/hsmdaemon.toml` with the information that the customer provides, in the `pkcs11` section, as in the example below. +Define which slot to use and if a PIN is needed. Update `/etc/hsmdaemon/hsmdaemon.toml` with the information gathered in the `pkcs11` section as in the example below. ---- [pkcs11] -module = "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so" # softhsm v2 -pin = "1234" # The user pin supplied when running softhsm2-util --init-token, comment it out , or leave empty if no pin is necessary -slot = 1989683358 # Find your slot id with `sudo hsmdaemon listslots` +# softhsm v2 +module = "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so" +# The user pin supplied when running softhsm2-util --init-token, comment it out +# or leave empty if no pin is necessary +pin = "1234" +# Find your slot id with `sudo hsmdaemon listslots` +slot = 1989683358 ---- === Testing @@ -314,16 +291,17 @@ slot = 1989683358 # Find your slot id with `sudo hsmdaemon listslots` [NOTE] ==== -If no PIN is supplied, generating a new key might be protected by an operator card that has to be inserted in the HSM. -In this case, coordinate testing and final master key generation with your HSM team. +If no PIN is supplied, generating a new key might be protected by an operator card that has to be inserted in the HSM. In this case, coordinate testing and final master key generation with your HSM team. ==== -For testing key generation, run the command `hsmdaemon genkey test`, as in the following example. +For testing the key generation, run the following example command: [source,console] ---- -hsmdaemon genkey test +sudo hsmdaemon genkey test + Id: 9bac3719-2b8d-11e9-aeab-0242b5ece4c3, label: test + -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAl1BO4vsI+xDk+x0nccl7 HQhMR/hwfa0+N8fyYNI8yzTTmYDqz9aaF20qG48+mjC0AUEt2kfKo94xM3UeEw4c @@ -337,18 +315,19 @@ jwIDAQAB ==== Test Data Encryption -For testing data encryption, run the `hsmdaemon encrypt` command, as in the following example. +For testing data encryption, run the the following example command: [source,console] ---- -# The first argument is the "Id:" value from running the genkey command above. -# The second is the base64-encoded data to be encrypted. +# The first argument is the `Id:` value from running the genkey command above. +# The second is the `base64-encoded data` to be encrypted. + sudo hsmdaemon encrypt 9bac3719-2b8d-11e9-aeab-0242b5ece4c3 Zm9vYmFy ---- -If successful, you should see output similar to the below example. +If successful, you should see output similar to the example below: -[source,console] +[source,console,options="nowrap"] ---- {"level":"debug","ts":"2019-03-20T12:43:40.540+0100","caller":"hsmdaemon/keymanager.go:27","msg":"initialize pkcs11 module","module":"/usr/lib/softhsm/libsofthsm2.so"} {"level":"debug","ts":"2019-03-20T12:43:40.545+0100","caller":"hsmdaemon/keymanager.go:205","msg":"openHSMSession","slotID":858597139} @@ -359,7 +338,7 @@ WcezVb2N6bF8wlDooKZcmFn3tZgoIpoFGx6wQetx9sp1nK7JW2Y4OKt7P+0VKKlFO7yXaffVDD2Q6jZZ ==== Test Showing Keys -To show an existing key, use the `showkey` command with the key's id, as in the following example. +To show an existing key, use the `showkey` command with the key's id as in the following example. [source,console] ---- @@ -382,12 +361,12 @@ For more options see the self-documented default config file `hsmdaemon.toml`. [TIP] ==== -During ownCloud config you might want to run the hsmdaemon service in the foreground to see what is going on. -You can do so, using the following command (which also shows example console output, formatted for readability). +During ownCloud config, you might want to run the hsmdaemon service in the foreground to see what is going on. You can do so using the following command (which also shows example console output, formatted for readability): [source,console] ---- -./hsmdaemon +sudo hsmdaemon + { "level": "info", "ts": "2019-02-14T09:32:59.081+0100", @@ -403,13 +382,12 @@ You can do so, using the following command (which also shows example console out === Configure ownCloud -[TIP] +[IMPORTANT] ==== -If anyone accesses ownCloud while encryption is enabled, it will automatically generate the keys. -To prevent this, shut down the web server until encryption is appropriately configured. +If anyone accesses ownCloud while encryption is enabled, it will automatically generate the keys. To prevent this shut down the web server until encryption is appropriately configured. ==== -To configure ownCloud to work with the hsmdaemon requires the following steps: +Configuring ownCloud to work with the `hsmdaemon` requires the following steps: * xref:generate-a-secret-for-the-hsmdaemon-rest-api[Generate a Secret for the hsmdaemon REST API] * xref:configure-hsm-based-encryption[Configure HSM-based Encryption] @@ -417,7 +395,7 @@ To configure ownCloud to work with the hsmdaemon requires the following steps: ==== Generate a Secret for the hsmdaemon REST API -Generate a shared secret to use for the hsmdaemon. +Generate a shared secret to use for the `hsmdaemon`. [source,console] ---- @@ -436,9 +414,7 @@ Set the generated secret for ownCloud: [source,console,subs="attributes+"] ---- -{occ-command-example-prefix} config:app:set \ - encryption hsm.jwt.secret \ - --value '7a7d1826-b514-4d9f-afc7-a7485084e8de' +{occ-command-example-prefix} config:app:set encryption hsm.jwt.secret --value '7a7d1826-b514-4d9f-afc7-a7485084e8de' ---- If the command succeeds, you should see the following console output: @@ -450,35 +426,30 @@ Config value hsm.jwt.secret for app encryption set to 7a7d1826-b514-4d9f-afc7-a7 ==== Configure HSM-based Encryption -Enable HSM mode and enable encryption by running the commands in the following example. +Enable the HSM mode and enable encryption by running the commands in the following example: -[source,console] +[source,console,subs="attributes+"] ---- -occ config:app:set encryption hsm.url --value 'http://localhost:8513' -occ app:enable encryption -occ encryption:enable +{occ-command-example-prefix} app:enable encryption +{occ-command-example-prefix} config:app:set encryption hsm.url --value 'http://localhost:8513' +{occ-command-example-prefix} encryption:select-encryption-type masterkey +{occ-command-example-prefix} encryption:enable ---- If the commands are successful, you should see the following console output: [source,console] ---- +encryption enabled + Config value hsm.url for app encryption set to http://localhost:8513 -encryption enabled +Master key successfully enabled. Encryption enabled - Default module: OC_DEFAULT_MODULE ---- -If you want to use a single master key run - -[source,console] ----- -occ encryption:select-encryption-type masterkey ----- - //// ==== Configure Authorization @@ -487,10 +458,7 @@ TBW. ==== Initialize and Check Generated Keys -Now start your web server, and log in with any user to initialize the keys, have a look at the output of the hsmdaemon to see key generation and decryption requests. -Check that the private key `/path/to/data/files_encryption/OC_DEFAULT_MODULE/` is less than *1000 bytes*. -If it is not, then something is not configured correctly. -You have to wipe all keys and reset the database flags for encryption to get a clean start for the ownCloud setup. +Now start your web server and log in with any user to initialize the keys, have a look at the output of the `hsmdaemon` to see key generation and decryption requests. Check that the private key `/path/to/data/files_encryption/OC_DEFAULT_MODULE/` is less than *1000 bytes*. If it is not, then something is not configured correctly. You have to wipe all keys and reset the database flags for encryption to get a clean start for the ownCloud setup. //// TODO From 3eb4ba7196706f436b8a81cd6ff9195d6eee3fb3 Mon Sep 17 00:00:00 2001 From: mmattel Date: Wed, 23 Jun 2021 09:41:50 +0200 Subject: [PATCH 2/4] updated and testing section --- .../server/security/hsmdaemon/index.adoc | 109 ++++++++++++++---- 1 file changed, 87 insertions(+), 22 deletions(-) diff --git a/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc b/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc index 8b1b024e6c..ae069c5ef1 100644 --- a/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc +++ b/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc @@ -20,7 +20,9 @@ The `hsmdaemon` is a daemon provided by ownCloud to delegate encryption to an {h NOTE: When using `hsmdaemon` with an HSM, the keys _may_ still be stored on the same physical machine as ownCloud. -NOTE: For hsmdaemon support, you need ownCloud Enterprise Edition >= 10.2. We recommend consulting with us when deploying storage encryption with an HSM. +NOTE: For `hsmdaemon` support, you need ownCloud Enterprise Edition >= 10.2. We recommend consulting with us when deploying storage encryption with an HSM. + +NOTE: Starting with the Encryption App version 1.5.1, HSM can now work with both `binary` and `base64` encoding/decoding. If not otherwise configured, `binary` is the default. Running {php-exec-function-url}[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. @@ -156,9 +158,9 @@ Installing hsmdaemon requires several steps. These are: . xref:copy-the-config-file[Copy the Config File] . xref:install-the-system-service[Install the System Service] . 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:configure-the-slot-and-pin[Configure Slot and Pin] +. xref:test-the-hsmdaemon[Test the hsmdaemon] +. xref:configure-other-options-optional[Configure Other Options] ==== Install the hsmdaemon Binary @@ -282,12 +284,12 @@ module = "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so" # or leave empty if no pin is necessary pin = "1234" # Find your slot id with `sudo hsmdaemon listslots` -slot = 1989683358 +slot = 550099622 ---- -=== Testing +== Test the hsmdaemon -==== Test Key Generation +=== Test Key Generation [NOTE] ==== @@ -313,9 +315,18 @@ jwIDAQAB -----END PUBLIC KEY----- ---- -==== Test Data Encryption +=== Test Showing Keys + +To show an existing key, use the `hsmdaemon showkey` command with the key's id as in the following example. + +[source,console] +---- +sudo hsmdaemon showkey 9bac3719-2b8d-11e9-aeab-0242b5ece4c3 +---- + +=== Test Data Encryption -For testing data encryption, run the the following example command: +For testing data encryption, run the the following example commands: [source,console] ---- @@ -336,26 +347,79 @@ If successful, you should see output similar to the example below: WcezVb2N6bF8wlDooKZcmFn3tZgoIpoFGx6wQetx9sp1nK7JW2Y4OKt7P+0VKKlFO7yXaffVDD2Q6jZZCQukQVRV1zJrwbI9xU3YlOAwJFPP+WM/dZ1vdUwi7L05wq8UpL13LJWlMkvd1eIqKJS7apMnFk2hbnxXP6UKZmI++1tXvqbAc6fwhcB5J+JG6lmS4RwnD+eJC3dq5t00zzdI6vuIM/y3UT7ESklmHl5bKl+N+d6yk6qLxnFnIJweL+M3Tf13+XPNAh5JxZpheJPvN3oL28uX76aizy4BCLnRgQ/ryUQeDF+a4zNF22sMwBh4Pt46KrYGNDZAnQpVzmkrZQ== ---- -==== Test Showing Keys +=== Test Data Decryption -To show an existing key, use the `showkey` command with the key's id as in the following example. +For testing data decryption, run the the following example commands: [source,console] ---- -sudo hsmdaemon showkey 9bac3719-2b8d-11e9-aeab-0242b5ece4c3 +sudo grep "generated keypair" /var/log/hsm.log ---- -//// -==== Testing Data Decryption +You should see output similar to the example below: -TODO. +[source,console,options="nowrap"] +---- +{"level":"debug","ts":"2021-06-19T03:10:01.562+0200","msg":"generated keypair","tokenID":"1262668f-d09b-11eb-b283-960000c05f34"} +{"level":"debug","ts":"2021-06-19T03:10:03.043+0200","msg":"generated keypair","tokenID":"1374447f-d09b-11eb-83c8-960000c05f34"} +{"level":"debug","ts":"2021-06-19T03:10:03.710+0200","msg":"generated keypair","tokenID":"13cd3f95-d09b-11eb-83c8-960000c05f34"} +---- + +[source,console] +---- +key_id=$(sudo grep "generated keypair" /var/log/hsm.log | head -1 | jq .tokenID -r) + +hello="Hello, world!" + +echo "$hello" | base64 + +SGVsbG8sIHdvcmxkIQo= +---- + +[source,console] +---- +test_enc=$(sudo ./hsmdaemon encrypt $key_id $(echo "$hello" | base64) | tee /dev/stderr) +---- + +[source,console,options="nowrap"] +---- +ep6Y1aAVAYpAesZ1+sQzzUepjO82o34kjmm63Drmz+6KED4oIBARQkXeW/OoxgUg6kQhQK1thA/3Ww33aaRxIESzVQF598qjXhhEXQ/OGL6BC+3tPclC7ujUZaA7CG1NDkMneLFDd2+Tbax4OM+/w0zhfTMPgT0I1NrH/03owVglbWHjgLZmN/vxpPZKm/lyAV9tI2HW36UjVLEMD2qtPFXqjLU4YjZOVnMdETxQNSCWIVauFw0+VQQ/RiAqiXzRXEgO6YKxOBk0n9IMT6XEH4MkMQTgb9pB12jrNSa9aMHbCvCneEmhd0CHBxPX499EkxxwtoEnXe6PATXsOg3VRA== +---- -==== Testing Key Deletion +[source,console,subs="attributes+"] +---- +{occ-command-example-prefix} encryption:hsmdaemon:decrypt --keyId $key_id "$test_enc" + +decrypted string (base64 encoded): 'SGVsbG8sIHdvcmxkIQo=' +---- + +[source,console] +---- +sudo tail -5 /var/log/hsm.log +---- + +[source,console,options="nowrap"] +---- +{"level":"debug","ts":"2021-06-20T23:46:11.958+0200","msg":"openHSMSession","slotID":757826573} +{"level":"debug","ts":"2021-06-20T23:46:11.960+0200","msg":"created new session"} +{"level":"debug","ts":"2021-06-20T23:46:11.960+0200","msg":"Got uuid","string":"1262668f-d09b-11eb-b283-960000c05f34"} +{"level":"debug","ts":"2021-06-20T23:46:11.962+0200","msg":"found object","id":"\u0012bf\ufffdЛ\u0011벃\ufffd\u0000\u0000\ufffd_4"} +{"level":"debug","ts":"2021-06-20T23:46:11.963+0200","msg":"Decrypted"} +---- + +**Results** + +* [x] The base64 encoded string matches before encryption and after decryption. +* [x] The key-id seen in the log with "generated keypair" causes no errors during encryption. +* [x] The key-id re-appears in the log during decryption ("Got uuid") + +//// +=== Testing Key Deletion TODO. //// -=== Configure Other Options (optional) +== Configure Other Options (optional) For more options see the self-documented default config file `hsmdaemon.toml`. @@ -380,7 +444,7 @@ sudo hsmdaemon ---- ==== -=== Configure ownCloud +== Configure ownCloud [IMPORTANT] ==== @@ -393,17 +457,18 @@ Configuring ownCloud to work with the `hsmdaemon` requires the following steps: * xref:configure-hsm-based-encryption[Configure HSM-based Encryption] * xref:initialize-and-check-generated-keys[Initialize and Check Generated Keys] -==== Generate a Secret for the hsmdaemon REST API +=== Generate a Secret for the hsmdaemon REST API Generate a shared secret to use for the `hsmdaemon`. [source,console] ---- cat /proc/sys/kernel/random/uuid + 7a7d1826-b514-4d9f-afc7-a7485084e8de ---- -Use this secret for hsmdaemon in `/etc/hsmdaemon/hsmdaemon.toml` +Use this generated secret for hsmdaemon in `/etc/hsmdaemon/hsmdaemon.toml` ---- [jwt] @@ -424,7 +489,7 @@ If the command succeeds, you should see the following console output: Config value hsm.jwt.secret for app encryption set to 7a7d1826-b514-4d9f-afc7-a7485084e8de ---- -==== Configure HSM-based Encryption +=== Configure HSM-based Encryption Enable the HSM mode and enable encryption by running the commands in the following example: @@ -456,7 +521,7 @@ Default module: OC_DEFAULT_MODULE TBW. //// -==== Initialize and Check Generated Keys +=== Initialize and Check Generated Keys Now start your web server and log in with any user to initialize the keys, have a look at the output of the `hsmdaemon` to see key generation and decryption requests. Check that the private key `/path/to/data/files_encryption/OC_DEFAULT_MODULE/` is less than *1000 bytes*. If it is not, then something is not configured correctly. You have to wipe all keys and reset the database flags for encryption to get a clean start for the ownCloud setup. From e778faddd12afa0d227621d3b1cf2548feb5e6eb Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 23 Jun 2021 10:01:22 +0200 Subject: [PATCH 3/4] Update modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc Co-authored-by: Phil Davis --- .../pages/configuration/server/security/hsmdaemon/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc b/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc index ae069c5ef1..39051f84a2 100644 --- a/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc +++ b/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc @@ -326,7 +326,7 @@ sudo hsmdaemon showkey 9bac3719-2b8d-11e9-aeab-0242b5ece4c3 === Test Data Encryption -For testing data encryption, run the the following example commands: +For testing data encryption, run the following example commands: [source,console] ---- From 09e95c154cd15fbdca3a3e68dd5183ab6c48ce52 Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 23 Jun 2021 10:01:36 +0200 Subject: [PATCH 4/4] Update modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc Co-authored-by: Phil Davis --- .../pages/configuration/server/security/hsmdaemon/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc b/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc index 39051f84a2..89f31a20e6 100644 --- a/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc +++ b/modules/admin_manual/pages/configuration/server/security/hsmdaemon/index.adoc @@ -28,7 +28,7 @@ Running {php-exec-function-url}[exec()] to decrypt the key with a command line c This daemon will be used by ownCloud to decrypt the current master key upon request. The communication happens via {unix-sockets-url}[UNIX sockets] or {network-sockets-url}[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 encrypt and decrypt keys and needs to be extended to support en-/decrypt operations via the new daemon. The current solution encrypts the ownCloud master key with a key from the HSM. +ownCloud internally uses OpenSSL to encrypt and decrypt keys and that is extended to support en-/decrypt operations via the new daemon. The current solution encrypts the ownCloud master key with a key from the HSM. NOTE: From the technical point of view the `Crypt` class is extended to handle the key generation in the HSM device and also to get the key from HSM. For the read/write operation on a file, the request goes to the HSM and then, based on the keys fetched from HSM, the files are encrypted or decrypted. The keys are not replaced.