You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by mm...@apache.org on 2021/01/18 12:48:22 UTC
[ignite] branch master updated: IGNITE-13659 Add documentation for
cache encryption key rotation (#8446)
This is an automated email from the ASF dual-hosted git repository.
mmuzaf pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/master by this push:
new 24ec908 IGNITE-13659 Add documentation for cache encryption key rotation (#8446)
24ec908 is described below
commit 24ec90853e4fd6541730f526e3fc178ca73088b2
Author: Pavel Pereslegin <xx...@gmail.com>
AuthorDate: Mon Jan 18 15:48:07 2021 +0300
IGNITE-13659 Add documentation for cache encryption key rotation (#8446)
---
docs/_data/toc.yaml | 2 +
.../main/java/org/apache/ignite/snippets/TDE.java | 7 +
docs/_docs/code-snippets/xml/tde.xml | 15 ++-
docs/_docs/monitoring-metrics/new-metrics.adoc | 2 +
.../security/cache-encryption-key-rotation.adoc | 145 +++++++++++++++++++++
docs/_docs/security/master-key-rotation.adoc | 2 +-
docs/_docs/security/tde.adoc | 1 -
docs/assets/css/docs.scss | 4 +-
docs/assets/css/styles.scss | 4 +-
9 files changed, 175 insertions(+), 7 deletions(-)
diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml
index 45cf6df..53eb7f1 100644
--- a/docs/_data/toc.yaml
+++ b/docs/_data/toc.yaml
@@ -475,6 +475,8 @@
url: security/tde
- title: Master key rotation
url: security/master-key-rotation
+ - title: Cache encryption key rotation
+ url: security/cache-encryption-key-rotation
- title: Sandbox
url: security/sandbox
- title: Extensions and Integrations
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 c973dcd..d0da946 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
@@ -58,6 +58,13 @@ public class TDE {
IgniteFuture<Void> future = ignite.encryption().changeMasterKey("newMasterKeyName");
//end::master-key-rotation[]
+ //tag::cache-group-key-rotation[]
+ // Starts cache group encryption key change process.
+ // This future will be completed when the new encryption key is set for writing on
+ // all nodes in the cluster and re-encryption of existing cache data is initiated.
+ IgniteFuture<Void> fut = ignite.encryption().changeCacheGroupKey(Collections.singleton("encrypted-cache"));
+ //end::cache-group-key-rotation[]
+
ignite.close();
}
}
diff --git a/docs/_docs/code-snippets/xml/tde.xml b/docs/_docs/code-snippets/xml/tde.xml
index 46a457f..70d1fdb 100644
--- a/docs/_docs/code-snippets/xml/tde.xml
+++ b/docs/_docs/code-snippets/xml/tde.xml
@@ -18,6 +18,7 @@
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:util="http://www.springframework.org/schema/util" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
<!-- tag::ignite-config[] -->
<bean class="org.apache.ignite.configuration.IgniteConfiguration">
+ <!-- tag::encryption[] -->
<!-- We need to configure EncryptionSpi to enable encryption feature. -->
<property name="encryptionSpi">
<!-- Using EncryptionSpi implementation based on java keystore. -->
@@ -32,6 +33,7 @@
<property name="keySize" value="256"/>
</bean>
</property>
+ <!-- end::encryption[] -->
<!-- tag::cache[] -->
<property name="cacheConfiguration">
<bean class="org.apache.ignite.configuration.CacheConfiguration">
@@ -40,7 +42,6 @@
</bean>
</property>
<!-- end::cache[] -->
-
<!-- tag::discovery[] -->
<property name="discoverySpi">
<bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi">
@@ -56,6 +57,18 @@
</bean>
</property>
<!-- end::discovery[] -->
+ <!-- tag::reencryption[] -->
+ <property name="dataStorageConfiguration">
+ <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
+ <property name="encryptionConfiguration">
+ <bean class="org.apache.ignite.configuration.EncryptionConfiguration">
+ <!-- Set re-encryption rate limit to 10.3 MB/s. -->
+ <property name="reencryptionRateLimit" value="10.3"/>
+ </bean>
+ </property>
+ </bean>
+ </property>
+ <!-- end::reencryption[] -->
</bean>
<!-- end::ignite-config[] -->
</beans>
diff --git a/docs/_docs/monitoring-metrics/new-metrics.adoc b/docs/_docs/monitoring-metrics/new-metrics.adoc
index d7e89f7..75ae9a1 100644
--- a/docs/_docs/monitoring-metrics/new-metrics.adoc
+++ b/docs/_docs/monitoring-metrics/new-metrics.adoc
@@ -135,6 +135,8 @@ Register name: `cacheGroups.{group_name}`
|StorageSize |long| Storage space allocated for group, in bytes.
|TotalAllocatedPages |long| Cache group total allocated pages.
|TotalAllocatedSize |long| Total size of memory allocated for group, in bytes.
+|ReencryptionBytesLeft |long| The number of bytes left for re-encryption.
+|ReencryptionFinished |boolean| The flag indicates whether re-encryption is finished or not.
|===
diff --git a/docs/_docs/security/cache-encryption-key-rotation.adoc b/docs/_docs/security/cache-encryption-key-rotation.adoc
new file mode 100644
index 0000000..2ebcd5c
--- /dev/null
+++ b/docs/_docs/security/cache-encryption-key-rotation.adoc
@@ -0,0 +1,145 @@
+// 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.
+= Cache encryption key rotation
+
+== Overview
+
+Cache group encryption key is used to encrypt cache data on the disk.
+When a user creates a new encrypted cache, a new encryption key is generated and propagated to all server nodes in the cluster. So, each node has the same cache encryption key for the same cache group.
+See link:security/tde[Transparent Data Encryption] for more detail.
+
+Ignite 2.10 introduces a feature for changing the cache encryption key.
+It allows to change the cache group encryption key and re-encrypt existing data at runtime.
+
+Rotation of the cache encryption key is required when the key is compromised or the crypto period (key validity period) is ended.
+
+The process of changing the cache encryption key includes two sequential stages:
+
+1. Rotate cache group key. This process adds a new encryption key for the specified cache group or groups on each server node and sets it to write new data.
+
+ Node join during this stage is prohibited and will be rejected.
+
+2. Re-encrypt existing (archived) cache data with the new encryption key.
+
+The second stage can take a while. It depends on the amount of existing data. During this period, the old key is kept to read the archived data.
+To understand what key the data is encrypted with, each encryption key has an _identifier_. By default, it is equal to zero. The identifier value of the new key increases with each new rotation.
+The encryption key (as well as encryption key ID) is the same for all nodes in a cache group.
+
+NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for a cache group (both stages).
+
+== Prerequisites
+
+The cluster should be active.
+
+== Changing the Encryption Key
+
+Ignite provides the ability to change the cache encryption key using the following interfaces:
+
+- link:#command-line-tool[command line tool]
+- link:#jmx[JMX]
+- link:#from-code[from code]
+
+=== Command Line Tool
+
+Ignite shipment includes `control.sh|bat` script, located in the `$IGNITE_HOME/bin` folder, that acts as a tool to manage the
+cache encryption key change process from the command line. The following commands are used with `control.sh|bat`:
+
+[source,shell]
+----
+# View the cache group encryption key identifiers.
+control.sh|bat --encryption cache_key_ids cacheGroupName
+
+# Change the cache encryption key.
+control.sh|bat --encryption change_cache_key cacheGroupName
+----
+
+=== JMX
+
+You can also change the cache encryption key via the `EncryptionMXBean` interface:
+
+[cols="1,1",opts="header"]
+|===
+|Method | Description
+|changeCacheGroupKey(String cacheOrGrpName) | Starts cache encryption key change process.
+|===
+
+=== From Code
+
+The cache encryption key change process can also be managed directly in the code:
+
+[tabs]
+--
+tab:Java[]
+
+[source, java]
+----
+include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0]
+----
+--
+
+== Managing Re-encryption
+
+Re-encrypting existing data can take a while. This is a fault-tolerant operation that automatically continues after a node restart.
+The previous encryption key is automatically removed when all local partitions are encrypted with the new key, and the last link:persistence/native-persistence#write-ahead-log[Write-Ahead Log] segment, which may contain entries encrypted with the previous key, is removed from disk.
+
+NOTE: Re-encryption uses link:persistence/native-persistence#write-ahead-log[Write-Ahead Log] for physical recovery and may affect performance of cache operations.
+
+There are several options to manage the performance impact of re-encryption:
+
+* Limit the re-encryption rate using a configuration parameter or CLI at runtime.
+* Temporarily suspend re-encryption using CLI command.
+
+Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is a part of `DatastorageConfiguration`.
+[cols="1,1,1",opts="header"]
+|===
+|Property | Default value | Description
+|reencryptionRateLimit | 0 (unlimited) | Re-encryption rate limit in megabytes per second.
+|reencryptionBatchSize | 100 | The number of pages scanned during re-encryption under checkpoint lock.
+|===
+
+=== Using XML Configuration to Limit the Re-encryption Rate
+[source, xml]
+----
+include::code-snippets/xml/tde.xml[tags=ignite-config;!discovery;!encryption;!cache;!discovery, indent=0]
+----
+
+=== Using CLI to Control Re-encryption Process
+
+The `control.sh|bat` script provides the ability to change the re-encryption rate as well as suspend and resume background re-encryption at runtime.
+
+NOTE: After the node restarts, the suspended background re-encryption is continued automatically, and the rate limit is set to 'unlimited' (by default), or taken from the local XML configuration (if any).
+
+[source,shell]
+----
+# View the cache group re-encryption status.
+control.sh|bat --encryption reencryption_status cacheGroupName
+
+# Suspend re-encryption of the cache group.
+control.sh|bat --encryption suspend_reencryption cacheGroupName
+
+# Resume (suspended) re-encryption of the cache group.
+control.sh|bat --encryption resume_reencryption cacheGroupName
+
+# View the re-encryption rate limit.
+control.sh|bat --encryption reencryption_rate_limit
+
+# Set the re-encryption rate limit to 2.5 MB/s.
+control.sh|bat --encryption reencryption_rate_limit 2.5
+
+# Set re-encryption rate to 'unlimited' ('0').
+control.sh|bat --encryption reencryption_rate_limit 0
+----
+
+The re-encryption status can be also obtained using JMX metrics described in the link:monitoring-metrics/new-metrics#cache-groups[Cache group metrics] section.
diff --git a/docs/_docs/security/master-key-rotation.adoc b/docs/_docs/security/master-key-rotation.adoc
index 53e06f0..016e1f3 100644
--- a/docs/_docs/security/master-key-rotation.adoc
+++ b/docs/_docs/security/master-key-rotation.adoc
@@ -36,7 +36,7 @@ Nodes save the master key name to the disk (local `MetaStorage`) on the first cl
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:
+Ignite provides the ability to change the master key from the following interfaces:
- link:#command-line-tool[command line tool]
- link:#jmx[JMX]
diff --git a/docs/_docs/security/tde.adoc b/docs/_docs/security/tde.adoc
index 3f8250f..5d3ce1e 100644
--- a/docs/_docs/security/tde.adoc
+++ b/docs/_docs/security/tde.adoc
@@ -39,7 +39,6 @@ Transparent Data Encryption has some limitations that you should be aware of bef
*Encryption*
-* No option to change the encryption key at runtime.
* No option to encrypt/decrypt existing caches/tables.
*Snapshots and Recovery*
diff --git a/docs/assets/css/docs.scss b/docs/assets/css/docs.scss
index 2e05a98..a3379e7 100644
--- a/docs/assets/css/docs.scss
+++ b/docs/assets/css/docs.scss
@@ -1,3 +1,5 @@
+---
+---
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
@@ -14,8 +16,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
----
----
// Docs-specific global styles
body {
}
diff --git a/docs/assets/css/styles.scss b/docs/assets/css/styles.scss
index f23e704..dcc18bd 100644
--- a/docs/assets/css/styles.scss
+++ b/docs/assets/css/styles.scss
@@ -1,3 +1,5 @@
+---
+---
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
@@ -14,8 +16,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
----
----
@import "variables";
@import "header";
@import "code";