[GitHub] [ignite] NSAmelchev commented on a change in pull request #8143: IGNITE-12492 TDE - Phase-2. Documentation.

[GitBox <gi...@apache.org>]

NSAmelchev commented on a change in pull request #8143:
URL: https://github.com/apache/ignite/pull/8143#discussion_r469081523



##########
File path: docs/_docs/security/master-key-rotation.adoc
##########
@@ -0,0 +1,119 @@
+= 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:
+
+[{table_opts}]
+|===
+|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:
+
+[source,java]

Review comment:
       Moved.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org