This is an automated email from the ASF dual-hosted git repository. abudnikov pushed a commit to branch IGNITE-7595 in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/IGNITE-7595 by this push: new 5b20b05 IGNITE-12492 TDE - Phase-2. Documentation. (#8143) 5b20b05 is described below commit 5b20b051bac184d32cfca3eb35e56c206231d5ed Author: Nikita Amelchev <nsamelc...@gmail.com> AuthorDate: Wed Aug 12 13:33:18 2020 +0300 IGNITE-12492 TDE - Phase-2. Documentation. (#8143) * Add docs * Use snippets, fix table opts * Rename code tag --- docs/_data/toc.yaml | 6 +- .../main/java/org/apache/ignite/snippets/TDE.java | 11 +- docs/_docs/security/master-key-rotation.adoc | 117 +++++++++++++++++++++ 3 files changed, 132 insertions(+), 2 deletions(-) diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml index 6189540..950fe1d 100644 --- a/docs/_data/toc.yaml +++ b/docs/_data/toc.yaml @@ -183,7 +183,11 @@ - title: SSL/TLS url: /security/ssl-tls - title: Transparent Data Encryption - url: /security/tde + items: + - title: Introduction + url: /security/tde + - title: Master key rotation + url: /security/master-key-rotation - title: Thin Clients items: diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/TDE.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/TDE.java index 03b406c..b362137 100644 --- a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/TDE.java +++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/TDE.java @@ -4,6 +4,7 @@ import org.apache.ignite.Ignite; import org.apache.ignite.Ignition; import org.apache.ignite.configuration.CacheConfiguration; import org.apache.ignite.configuration.IgniteConfiguration; +import org.apache.ignite.lang.IgniteFuture; import org.apache.ignite.spi.encryption.keystore.KeystoreEncryptionSpi; public class TDE { @@ -30,7 +31,15 @@ public class TDE { ignite.createCache(ccfg); //end::cache[] - + + //tag::master-key-rotation[] + // Gets the current master key name. + String name = ignite.encryption().getMasterKeyName(); + + // Starts master key change process. + IgniteFuture<Void> future = ignite.encryption().changeMasterKey("newMasterKeyName"); + //end::master-key-rotation[] + ignite.close(); } } diff --git a/docs/_docs/security/master-key-rotation.adoc b/docs/_docs/security/master-key-rotation.adoc new file mode 100644 index 0000000..b2446d2 --- /dev/null +++ b/docs/_docs/security/master-key-rotation.adoc @@ -0,0 +1,117 @@ += 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, +----