Master key rotation | Ignite Documentation

Ignite Summit 2025 – Call for Speakers Now Open – Learn more 

Edit

Master key rotation

Overview

Master key encrypts cache keys. Encrypted cache keys are stored on the disk. To learn more see the Transparent Data Encryption page.

Ignite 2.9 introduces the master key change process. It allows users to switch Ignite to the new master key with re-encrypting cache keys.

Master key rotation is required if it has been compromised or at the end of the crypto period (key validity period).

Prerequisites

A new master key should be available to EncryptionSpi for each server node. The cluster should be active.

Configuration

Master keys are identified by name. When the cluster starts for the first time, the master key name from the configuration will be used. See TDE Configuration.

Nodes save the master key name to the disk (local MetaStorage) on the first cluster activation and each master key change. If some node restarts, it will use the master key name from the local MetaStorage.

Changing master key

Note
Cache start and node join during the key change process is prohibited and will be rejected.

Ignite provides the ability to change the master key from the following interfaces:

Command line tool

Ignite ships a control.sh|bat script, located in the $IGNITE_HOME/bin folder, that acts like a tool to manage the master key change process from the command line. The following commands can be used with control.sh|bat:

# Print the current master key name.
control.sh|bat --encryption get_master_key_name

# Change the master key.
control.sh|bat --encryption change_master_key newMasterKeyName

JMX

You can also manage the master key change process via the EncryptionMXBean interface:

Method Description

getMasterKeyName()

Gets the current master key name.

changeMasterKey(String masterKeyName)

Starts master key change process.

From code

The master key change process can be managed programmatically:

// Gets the current master key name.
String name = ignite.encryption().getMasterKeyName();

// Starts master key change process.
IgniteFuture<Void> future = ignite.encryption().changeMasterKey("newMasterKeyName");

Recovery of the master key on failing node

If some node is unavailable during a master key change process it won’t be able to join to the cluster with the old master key. The node should re-encrypt local group keys during recovery on startup. The actual master key name should be set via IGNITE_MASTER_KEY_NAME_TO_CHANGE_BEFORE_STARTUP system property before the node starts. The node saves the key name to the local MetaStorage when the cluster is active.

Note
It is recommended to delete system property after a successful recovery. Otherwise, the invalid master key name can be used when the node restarts.

Additional master key generation example

Ignite comes with the KeystoreEncryptionSpi based on JDK provided cipher algorithm implementations. See keystore master key generation example. An additional master key can be generated using the keytool as follows:

user:~/tmp:[]$ keytool \
-storepass mypassw0rd \
-storetype PKCS12 \
-keystore ./ignite_keystore.jks \
-list

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 1 entry

ignite.master.key, 15.01.2019, SecretKeyEntry,


user:~/tmp:[]$ keytool -genseckey \
-alias ignite.master.key2 \
-keystore ./ignite_keystore.jks \
-storetype PKCS12 \
-keyalg aes \
-storepass mypassw0rd \
-keysize 256


user:~/tmp:[]$ keytool \
-storepass mypassw0rd \
-storetype PKCS12 \
-keystore ./ignite_keystore.jks \
-list

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 2 entries

ignite.master.key, 15.01.2019, SecretKeyEntry,
ignite.master.key2, 15.01.2019, SecretKeyEntry,