How to enable HSM with encryption

[sharidas]

This ticket is regarding documentation for integrating HSM with encryption reference owncloud/encryption#90. From the UI point of view its enabling HSM and adding the JWT secret and mentioning the URL in the text box. But there are other changes required to be made in the instance where oC is running.

Configuring host machine running oC instance

I am using Ubuntu 18.04 ( Neon KDE )

• Install softhsm2
• After installation of softhsm2 we would see 2 additional packages installed libsofthsm2 and softhsm2-common
• Now we can configure file /etc/softhsm/softhsm2.conf. I have configured as shown below in my machine:

# SoftHSM v2 configuration file

directories.tokendir = /var/lib/softhsm/tokens/
objectstore.backend = file

# ERROR, WARNING, INFO, DEBUG
log.level = INFO

• Not the line directories.tokendir = /var/lib/softhsm/tokens/. If this directory is not there then please do create in your machine. In my machine the permissions for this directory is as shown below

drwxr-sr-x 3 root softhsm 4096 Jan 17 20:40 /var/lib/softhsm/tokens/

• Now we need to initialize tokens in softhsm
  1. Inorder to initialize the token execute command:

sudo softhsm2-util --init-token --slot 0 --label "My token 1"

  2. This would ask for pin number. Enter a value, say `1234` and kindly note it down.
  3. Next it would ask for the secret value. Enter `secret`

• Now install opensc, which is a command line tool to use pkcs11

sudo apt install opensc

• In the command line you may try with

sudo pkcs11-tool --module /usr/lib/softhsm/libsofthsm2 -l --pin 1234 -O

• Now try to build the hsmdaemon. There is a makefile for the same.
• Run make in the hsmdaemon folder
• An executable hsmdaemon would be created.
• Create a file /etc/hsmdaemon/hsmdaemon.toml with contents as shown below:

# This is a .ini like TOML document. See https://github.com/toml-lang/toml#example for detailed synax

#debug = "*"

[server]
#hostname = "localhost"
#hostname = "" # to listen on all interfaces
#port = 8513

[jwt]
secret = "secret"

[pkcs11]
module = "/usr/lib/softhsm/libsofthsm2.so" # softhsm v1
# module = "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so" # softhsm v2
# module = "/opt/nfast/toolkits/pkcs11/libcknfast.so" # Thales nShield

pin = "1234"
slot = 615007925
#slot = 11110 # find your slot id with `hsmdaemon listslots`

persistent-connection = false

• For testing you may run with DEBUG="*" sudo -E ./hsmdaemon on terminal

Now time to run occ commands

For masterkey encryption

Follow the commands mentioned below to encrypt the oC instance with masterkey encryption:

sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ a:e encryption
Cannot load Xdebug - it was already loaded
encryption enabled
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ config:app:set encryption hsm.jwt.secret --value 'secret'
Cannot load Xdebug - it was already loaded
Config value hsm.jwt.secret for app encryption set to secret
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ config:app:set encryption hsm.url --value 'http://localhost:8513'
Cannot load Xdebug - it was already loaded
Config value hsm.url for app encryption set to http://localhost:8513
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ encryption:enable
Cannot load Xdebug - it was already loaded
Encryption enabled

Default module: OC_DEFAULT_MODULE
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ encryption:select-encryption-type masterkey -y
Cannot load Xdebug - it was already loaded
Master key successfully enabled.
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ls -lth data/files_encryption/OC_DEFAULT_MODULE
total 16K
-rw-r--r-- 1 sujith sujith 189 Feb 15 13:13 master_a77c3abf.privateKey
-rw-r--r-- 1 sujith sujith 451 Feb 15 13:13 master_a77c3abf.publicKey
-rw-rw-r-- 1 sujith sujith 189 Feb 15 13:12 pubShare_a77c3abf.privateKey
-rw-rw-r-- 1 sujith sujith 451 Feb 15 13:12 pubShare_a77c3abf.publicKey
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset 

For user-keys encryption

Follow the commands mentioned below to encrypt the oC instance with user-keys encryption:

 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ a:e encryption
Cannot load Xdebug - it was already loaded
encryption enabled
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ config:app:set encryption hsm.jwt.secret --value 'secret'
Cannot load Xdebug - it was already loaded
Config value hsm.jwt.secret for app encryption set to secret
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ config:app:set encryption hsm.url --value 'http://localhost:8513'
Cannot load Xdebug - it was already loaded
Config value hsm.url for app encryption set to http://localhost:8513
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ encryption:enable
Cannot load Xdebug - it was already loaded
Encryption enabled

Default module: OC_DEFAULT_MODULE
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ./occ encryption:select-encryption-type user-keys -y
Cannot load Xdebug - it was already loaded
User key successfully enabled.
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ls -lh data/files_encryption/OC_DEFAULT_MODULE 
total 8.0K
-rw-rw-r-- 1 sujith sujith 189 Feb 15 13:21 pubShare_e0f72b11.privateKey
-rw-rw-r-- 1 sujith sujith 451 Feb 15 13:21 pubShare_e0f72b11.publicKey
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset  ls -lth data/admin/files_encryption/OC_DEFAULT_MODULE      
total 8.0K
-rw-r--r-- 1 sujith sujith 189 Feb 15 13:21 admin.privateKey
-rw-r--r-- 1 sujith sujith 451 Feb 15 13:21 admin.publicKey
 sujith@sujith-ownCloud  ~/test/owncloud3   retype-password-reset 

What Needs to be Documented?

Where Does This Need To Be Documented?

Why Should This Change Be Made? (Optional)

What Type Of Content Change Is This? (Optional)

• New Content Addition
• Old Content Deprecation
• Existing Content Simplification
• Bug Fix to Existing Content

Which Manual Does This Relate To? (Optional)

• Admin Manual
• Developer Manual
• User Manual
• Android
• iOS
• Branded Clients
• Desktop Client
• Other

[settermjd]

Where do I find the hsmdaemon?

[individual-it]

Where do I find the hsmdaemon?

https://gitea.int.owncloud.com/consulting/hsmdaemon

[settermjd]

I've made a good start on this, but have encountered a number of points that needed to be worked around or corrected. I should have it finished by the end of the week.

[PVince81]

@settermjd close to completion now ?