Hardware Security Module (HSM)

How to Configure and Enable HSM

By default, ZigiOps uses its internal encryption mechanism. To enable the HSM, stop the ZigiOps services, and then remove all initial account and credential information by following the steps outlined below:

Stop the ZigiOps services.
Navigate to <ZigiOps>\conf\platform\settings and remove the accounts, credentials, and users folders.
Start the ZigiOps services.

This procedure will reset the login credentials for the default Admin user to their default values and allow the JCA to begin handling the credentials after the next launch. Before we start the ZigiOps service, we need to configure several runtime parameters in the config.properties file. The properties file will enable us to enable the JCA and set the provider, Keystore type, and several other parameters. You can find the config.properties file in the <ZigiOps>\platform\conf folder. Open the file in any text editor and add the following parameters at the end of the file:

TEXT

zigiwave.jca.provider=CryptoServer
zigiwave.jca.keystore.type=CryptoServer
zigiwave.jca.algorithm=DES/CBC/PKCS5Padding
zigiwave.jca.keysize=1024
zigiwave.jca.keystore.password=MTIzNDU2
zigiwave.jca.keystore.alias=test1234

Note that we are using a simulator in this example, so you will need to provide your hardware security module for these parameters instead.

HSM Parameters Summary

Note that these parameters are not present in the config.properties file by default.

Parameter	Details	Default Value
zigiwave.jca.provider	The provider string.	SunJCE
zigiwave.jca.algorithm	the type of algorithm used for encoding.	AES
zigiwave.jca.keysize	The key size.	1024
zigiwave.jca.keystore.type	The Keystore type.	JCEKS
zigiwave.jca.keystore.alias	Alias in the Keystore that will store the secret key.	zigiwave-credential-secret-key
zigiwave.jca.keystore.file	Location in the Keystore's file system is not needed for external vendors.	conf/credstore
zigiwave.jca.keystore.password	The password to access the Keystore may or may not be required by an external vendor; it's encoded in Base64 so as not to be too obvious.

Once you have configured the parameters for your use case, you can save the config.properties file and start the ZigiOps service.

Note that since we have reset the user and the credential information, you should use the default credentials to log in to the ZigiOps instance.

How to Disable HSM

Once the HSM is enabled and configured, it will manage all encryption and decryption tasks, including login credentials and data from integrated systems in ZigiOps. If the HSM is stopped or disabled at any point, users will no longer be able to log in to ZigiOps, and system data will remain encrypted, halting all integration activities. Restoring access to the HSM will allow ZigiOps to return to its normal operational state, and integration activities will resume after a service restart.

If the host system is compromised or a new key has been generated, you will need to restore access to the ZigiOps UI by following the initial setup steps:

Stop the ZigiOps services.
Navigate to the <ZigiOps>\platform\conf\settings folder and remove the accounts, credentials, and users folders.
Start the ZigiOps services.

Please note that ZigiOps will still initialize the integrated systems. However, you will need to re-enter their passwords and save them again from the Connected Systems menu to ensure the newly generated key can handle them.