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,
+----
