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 newMasterKeyNameJMX
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,Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.