| // Licensed to the Apache Software Foundation (ASF) under one or more |
| // contributor license agreements. See the NOTICE file distributed with |
| // this work for additional information regarding copyright ownership. |
| // The ASF licenses this file to You under the Apache License, Version 2.0 |
| // (the "License"); you may not use this file except in compliance with |
| // the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| = Master key rotation |
| |
| == Overview |
| |
| Master key encrypts cache keys. Encrypted cache keys are stored on the disk. To learn more see the link:security/tde[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 link:security/tde#configuration[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 provide the ability to change the master key from the following interfaces: |
| |
| - link:#command-line-tool[command line tool] |
| - link:#jmx[JMX] |
| - link:#from-code[from code] |
| |
| === 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`: |
| |
| [source,shell] |
| ---- |
| # 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: |
| |
| [cols="1,1",opts="header"] |
| |=== |
| |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: |
| |
| [tabs] |
| -- |
| tab:Java[] |
| |
| [source, java] |
| ---- |
| include::{javaCodeDir}/TDE.java[tags=master-key-rotation, indent=0] |
| ---- |
| -- |
| |
| == 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 link:security/tde#master-key-generation-example[keystore master key generation example]. An additional master key can be generated using the `keytool` as follows: |
| |
| [source,shell] |
| ---- |
| 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, |
| ---- |
