IDB/HDB encryption management¶

This page explains how to view and manage IDB/HDB encryption status using maintenance console commands.

The following commands throughout this section can be executed from a maintenance console.

View encryption status of the database¶

The encryption status of the database can be viewed by means of the state command. It shows two columns (Unencrypted and Encrypted) for each type of file. The column with the non-zero value indicates the current file counts for that type of file as well as its current status (unencrypted or encrypted).

If selective encryption is performed for individual tables, table columns, table categories, or storage tiers, a "fully encrypted" database shows non-zero values in both the unencrypted and encrypted columns. Use the kdb+ command -21! to check the encryption status of individual files manually.

Note

The state command should not run during write-down or database migration (DBM) and may exit prior to completion reporting an error.

Syntax	.maint.encrypt`state
Requires Arming?	No
Optional	N/A
Requires Confirmation?	No

q).maint.encrypt`state
                          |Unencrypted Encrypted
--------------------------|------------------------
IDB column files          |2           130
Basic table snapshots     |0           22
Snapshot column files     |4           428
Seqlog column files       |2           125
Sym files                 |0           2
Internal tables and .d files|289       0
HDB column files          |1350        1310
Migrated column files     |0           0

File Type	Encryption Status
IDB column files	Normal EOI/EOD Encryption
Basic table snapshots	Normal EOI/EOD Encryption
Snapshot column files	Normal EOI/EOD Encryption
Seqlog column files	Normal EOI/EOD Encryption
Sym files	Normal EOI/EOD Encryption
Internal tables and .d files	No Encryption
HDB column files	Normal EOI/EOD Encryption
Migrated column files	Encryption by DBM

Activate and deactivate encryption¶

Encryption can be activated by setting dbEncrEnabled in systemParams.yaml to true and setting up an encryption master key and password. At the next EOI or EOD, all newly ingested data is encrypted; existing on-disk IDB or HDB data is encrypted after EOD by DBM.

Encryption can be deactivated by setting dbEncrEnabled in systemParams.yaml to false. At the next EOI or EOD, all newly ingested data is written down in unencrypted form; existing on-disk encrypted data in the IDB or HDB is de-encrypted after EOD by DBM.

Change the password of an encryption master key¶

There are two different methods to change password depending on which version of OpenSSL is installed on the KXS server:

If …	then …
OpenSSL v1.1.1 or higher	The `changePassword` command can be used to change your password.
Earlier version of OpenSSL	Launch OpenSSL v1.1.1 or higher on another non-KXS server and change the password in OpenSSL. Copy the key and password to the KXS server. Use the `importKey` command to import the updated key/password into KXS.

OpenSSL v1.1.1 or higher¶

The password can be changed through the changePassword command. The updated password can be either a manually entered user-defined password or a password retrieved from a text file.

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

Earlier version of OpenSSL¶

Enter the following command on a system with OpenSSL v1.1.1 or higher:
```
# Prompts for current password
key=`openssl aes-256-cbc -md SHA256 -d -iter 50000 -in test.key`

# Prompts for new password
echo $key | openssl aes-256-cbc -md SHA256 -salt -pbkdf2 -iter 50000 -out updtest.key

# Remove the raw key from the environment
unset key
```
In the above example, the encryption master key test.key is unlocked by providing the password as user input and then piped into an OpenSSL command to create updtest.key. OpenSSL then prompts for a new password.

Delete an encryption master key and password¶

Deleting an encryption master key and password by means of the removeKey command is required if you wish to de-encrypt a KXS database or replace an existing encryption master key.

Syntax	.maint.encrypt`removeKey
Requires Arming?	Yes
Optional	N/A
Requires Confirmation?	Yes

De-encrypting a KXS database¶

Depending on the volume of sensor data, de-encrypting the database could take multiple days. A full de-encryption requires at least two EODs to take effect: on the first EOD, de-encrypted migrated copies of the files are "staged", and on the second EOD, they are merged into HDB.

Disable encryption by setting dbEncrEnabled to false in systemParams.yaml. The other encryption parameters encrTblCats, symEncrypted, idbEncrypted, and hdbEncrypted are ignored and not required for deactivation.
Wait for DBW/DBM to decrypt all data contained in the database. This can be verified by using the state command.
Run the command removeKey to remove the existing encryption master key from the KXS environment.

Replace an encryption key¶

Replacing an encryption key is a manual process that requires a complete de-encryption of the KXS database followed by a full re-encryption using the updated encryption key.

De-encrypt the database following the instructions outlined in the previous section.
Create a new key using the generateKey command or import an updated key generated elsewhere by using the importKey command.
Enable encryption again by setting dbEncrEnabled to true.
Wait for DBM to re-encrypt all the data. Once this is complete, the encryption key has been successfully replaced.