How to Configure and Enable HSM

ZigiOps uses its internal encryption mechanism by default. To enable the HSM, you should stop the ZigiOps Service, and all initial account and credential information should be removed by following the steps below:

  1. Stop the ZigiWave ZigiOps service.

  2. Navigate to <ZigiOps>\conf\settings and remove the accounts, credentials, and users folders.

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. 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>\conf folder. Open the file in any text editor and add the following parameters at the end of the file:

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
TEXT

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 (admin/admin) to log in to the ZigiOps instance.

How to Disable HSM

Once the HSM is enabled and configured, it will handle all encryption and decryption, including the login credentials and information from the integrated systems in ZigiOps. Suppose at any point the HSM is stopped/disabled. In that case, users will no longer log in to ZigiOps. All system information will not be decrypted, which ceases all integration activity. Restoring access to the HSM will allow ZigiOps to resume its normal working state, and all integration activity will resume after a service restart.

In case the host system is jeopardized or a different key has been generated, you will need to restore your access to the ZigiOps UI by following the initial setup steps:

  1. Stop the ZigiWave ZigiOps service.

  2. Navigate to the <ZigiOps>\conf\settings folder and remove the accounts, credentials, and users folders.

Note that ZigiOps will still initialize the integrated systems. Nevertheless, you will need to retype their passwords and save them again from the Connected-Systems menu, so the newly generated key can handle them.