Skip to content

Activate IDB/HDB encryption in the maintenance console

This page explains how to control IDB/HDB encryption using the .maint.encrypt interface in the maintenance console.

IDB/HDB encryption can be controlled through a set of maintenance console commands using the .maint.encrypt interface. The encryption commands along with their arguments can be viewed by means of the help command.

These commands do not apply to TLS in-transit encryption.

Syntax .maint.encrypt`help
Requires Arming? No
Optional N/A
Requires Confirmation? No 
q).maint.encrypt`help

<encrypt> is used to manage master key and password usage for on-disk database encryption.  This utility is
used in combination with the system parameter <dbEncrEnabled> to enable/disable encryption in a KX Sensors
environment.  Further granularity is provided to the user through the parameters <hdbEncrypted>, <idbEncrypted>,
<symEncrypted> and HDB tier configuration.

Usage:  encrypt`command  or  encrypt[`command;`param1;`param2;`param3]

Commands:
  `help                                                                Displays this command summary
  `state                                                                Displays encryption state of the database
  `generateKey;(`<input|file>;(`<passwordFile>))                        Generates an encryption master key with the given password via the specified input mode*^
  `removeKey                                                            Removes the current encryption master key if all data has been decrypted*+
  `changePassword;(`<input|file>;(`<passwordFile>))                     Changes the password of the existing encryption master key to the given password via the specified input mode*^
  `importKey;(`<masterKeyFile>;`<input|file>;(`<passwordFile>))         Imports an encryption master key and password from the given files*

Arguments in parentheses are optional

* These commands require arming
+ These commands require user confirmation
^ These commands require OpenSSL 1.1.1 or higher

About arming

Certain encryption commands such as importKey, generateKey and removeKey require arming. Arming provides an extra layer of security to discourage casual or accidental use of these commands. Commands that show the state of the system do not require arming.

.maint.arm`encrypt

Set up an encryption master key and password

There are two different setup options for encryption master keys/passwords depending on which version of OpenSSL is installed on the KXS server:

If … then …
OpenSSL v1.1.1 or higher The generateKey command can be used to generate a master key and protect it with a password
Earlier version of OpenSSL Launch OpenSSL v1.1.1 or higher on another non-KXS server and generate a key and password in OpenSSL. Copy the key and password to the KXS server. Use the importKey command to import the key/password into KXS

generateKey command

This command generates an encryption master key and password using a user-defined password that may be either manually entered or retrieved from a text file.

Syntax .maint.encrypt[`generateKey;`\<input|file>]
Requires Arming? Yes
Optional passwordFile
Requires Confirmation? No

Example Usage:

.maint.encrypt[`generateKey;`input] / User prompted for password
.maint.encrypt[`generateKey;`file;`$"/path/to/password"] / Password from file

importKey command

This command imports an encryption master key and password that was previously generated using OpenSSL. The password can be specified either manually or retrieved from a text file.

Syntax .maint.encrypt[`importKey;`\<masterKeyFile>;`\<input|file>]
Requires Arming? Yes
Optional passwordFile
Requires Confirmation? No

Example Usage:

  1. Generate an encryption master key using the following command on a system with OpenSSL v1.1.1 or higher:

    openssl rand 32 | openssl aes-256-cbc -md SHA256 -salt -pbkdf2 -iter 50000 -out test.key # Prompts for password

    In this example, the master key generated is called test.key.

  2. Enter a password for the encryption master key if required.

  3. Copy the key and password to the system running KXS with a lower OpenSSL version than 1.1.1.
  4. Use the importKey command on the system running KXS with a lower OpenSSL version than 1.1.1 to import the new encryption master key into KXS. If a password was not manually entered in OpenSSL, use the passwordFile parameter in .maint.encrypt to import the password.

Protect the password

If the password is retrieved from a text file, the password file is automatically deleted after importing/generating the new encryption master key.

If the password is manually entered in a Windows environment, the password is displayed in the console. Therefore, to avoid revealing the password to unauthorized users, remember to close the terminal window immediately after generating the new encryption master key.

Next steps