Configuring Data Protection

This article will provide a step-by-step procedure to configuring Data Protection (encrypting sensible data in Cassandra Database).

The configuration for Data Protection can be done by accessing the Advanced section in Admin Dashboard and navigating to Settings → Advanced → config.json

Data protection fields

Field	Default value	JCEKS config	HSM config	Description
keystorePassword	empty string	autogenerated	empty string	The password of the JCEKS keystore
masterKeyPassword	empty string	autogenerated	User input	The password of the master key
masterKeyAlias	empty string	autogenerated	User input	The alias of the master key
keystore	empty string	autogenerated	empty string	The BASE64 encoded keystore that contains the master key
enabled	false	true	true	Is Data protection enabled or disabled
keyProtection	empty string	JCEKS	HSM	The location where the master key is located: in HSM in Zookeeper (Stored within a JCEKS keystore)
encodedSecret	empty string	autogenerated	autogenerated	The encrypted value of the key used for securing data inside of the Database.

The fields that need to be modified by the administrator in order to enable data protection are:

Enabled = true
keyProtection = JCEKS or HSM

The field “keyProtection” must have one of the following values: JCEKS or HSM.

The data will be encrypted from the moment the protection is enabled. The data stored before enabling the protection will remain unencrypted for now.

1) Configuring JCEKS Data Protection

To configure JCEKS Data Protection, access the Admin Dashboard and navigate to Settings → Advanced → config.json

Search for the dataProtection section and set the following values for the enabled and keyProtection fields:

JSON

    "dataProtection": {
        "keystorePassword": "",
        "masterKeyPassword": "",
        "masterKeyAlias": "",
        "keystore": "",
        "enabled": true,
        "keyProtection": "JCEKS",
        "encodedSecret": ""
    }

After setting dataProtection as above, click on Save.

This will generate automatically the master key and encryption key that will be used for protecting the data present in the Cassandra database.

2) Configuring HSM Data Protection

To configure HSM Data Protection an AES-128-CBC key must be created as the master key.

Access the Admin Dashboard and navigate to Settings → Advanced → config.json, search for the dataProtection section and set the following:

JSON

    "dataProtection": {
        "keystorePassword": "",
        "masterKeyPassword": "<PASSWORD>",
        "masterKeyAlias": "<ALIAS>",
        "keystore": "",
        "enabled": true,
        "keyProtection": "HSM",
        "encodedSecret": ""
    }

Where:

<ALIAS> is the value of the alias of the master key withing the HSM
<PASSWORD> is the password of the master key

After setting the values click on Save. This will generate automatically the encryption key.

3) Disabling Data Protection

To disable Data Protection, access the Admin Dashboard and navigate to Settings → Advanced → config.json and set the following:

JSON

    "dataProtection": {
        "keystorePassword": "",
        "masterKeyPassword": "",
        "masterKeyAlias": "",
        "keystore": "",
        "enabled": false,
        "keyProtection": "",
        "encodedSecret": ""
    }

After setting the values click on Save.

4) Encrypted data

The table bellow presents the entities from db and the fields which are secured:

Entity	Fields	Update event
AuthenticationValidationCode	seed	Authentication with SMS
AuthenticationSession	identityTokenSignature, identityTokenJWT, externalValues, ntKey	Authentication Session updates
Biometric	biometricVector	During authentication using Vface or 4F with adaptive enrollment
Credential	credentials	ephemeral syncrhonization object. never updated, disposed after usage
Device	certPassword, pushServiceID, otpSeed (deprecated)	OS version, app version, locale change. Authenticator re-enroll done from mobile (PIN, TouchID) Unblock device.
DormantDevice	pushServiceId	dormant status change
EnrollmentCode	salt	ephemeral data
EnrolTracker	salt, externalValues, serverSideSecretValues	ephemeral data
LostModeCode	code, seed	Creation. Ephemeral data
Otp	seed	successful authentication
Pin	salt, plainValue	re-enroll
PushNotification	deviceId	ephemeral data
Secret (used with CP offline auth)	credentials	never
TOTP	seed	successful authentication
TotpDesktop	seed	successful authentication
YubicoOtp	secretKey	successful authentication

Example

With the Data protection option disabled, the field “seed” is unencrypted in the table authentication_validation_code used for SMS authentication method:

After enabling the Data encryption and performing at least one SMS authentication the “seed” field is encrypted: