Silberfuchs1 commented on a change in pull request #8446: URL: https://github.com/apache/ignite/pull/8446#discussion_r540885363
########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. Review comment: How does a new cache start? Does it start by itself? ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. Review comment: You don't need 'the' here. ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this cache group (both stages). Review comment: '...for a cache group...' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. Review comment: The encryption key (as well as encryption key ID) is the same for all nodes in a cache group. ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. Review comment: 'View the cache group encryption key identifiers.' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. Review comment: '...re-encryption rate...' '...or CLI at runtime' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. +* Temporarily suspend re-encryption using CLI command. + +Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is 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 that is scanned during re-encryption under checkpoint lock. +|=== + +=== Using XML configuration to limit 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 + +The `control.sh|bat` script provides the ability to change the re-encryption rate, suspend and resume background re-encryption at runtime. Review comment: '...as well as suspend...' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. +* Temporarily suspend re-encryption using CLI command. + +Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is 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 that is scanned during re-encryption under checkpoint lock. +|=== + +=== Using XML configuration to limit 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 + +The `control.sh|bat` script provides the ability to change the re-encryption rate, suspend and resume background re-encryption at runtime. + +NOTE: After the node restarts, the suspended background re-encryption will continue automatically, and the rate limit will be set from the local XML configuration (if any) or set to unlimited rate (default). + +[source,shell] +---- +# View the re-encryption status of the cache group. Review comment: 'View the cache group re-encryption status.' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. Review comment: 'It allows users to change the cache group encryption key and re-encrypt existing data at runtime.' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. Review comment: 'See link:security/tde[Transparent Data Encryption] to learn more.' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. Review comment: 'So,...' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). Review comment: '...or if the crypto period (key validity period) has ended.' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: Review comment: 'consists of two stages, which are performed sequentially:' --> '...includes two sequential stages:' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. Review comment: 'By default, ...' Split the sentence like this: 'By default it is equal to zero. The identifier of the new key increases with each rotation.' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be kept to read the archived data. Review comment: Split the sentence like this: 'The second stage can take a long time. It depends on the amount of existing data.' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) on each server node and sets it to write new data. Review comment: 'Rotate cache group key, this process add...' --> 'Rotate cache group key. This process add...' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: Review comment: I'd say '...are used...' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `control.sh|bat` script, located in the `$IGNITE_HOME/bin` folder, that acts as a tool to manage the Review comment: 'Ignite shipment includes...' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: Review comment: '...can also be managed...' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. +* Temporarily suspend re-encryption using CLI command. + +Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is 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 that is scanned during re-encryption under checkpoint lock. +|=== + +=== Using XML configuration to limit 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 Review comment: re-encryption process or re-encryption rate? ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. +* Temporarily suspend re-encryption using CLI command. + +Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is 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 that is scanned during re-encryption under checkpoint lock. Review comment: '...pages scanned during...' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. +* Temporarily suspend re-encryption using CLI command. + +Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is 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 that is scanned during re-encryption under checkpoint lock. +|=== + +=== Using XML configuration to limit re-encryption rate Review comment: '...the re-encryption rate' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. +* Temporarily suspend re-encryption using CLI command. + +Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is 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 that is scanned during re-encryption under checkpoint lock. +|=== + +=== Using XML configuration to limit 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 + +The `control.sh|bat` script provides the ability to change the re-encryption rate, suspend and resume background re-encryption at runtime. + +NOTE: After the node restarts, the suspended background re-encryption will continue automatically, and the rate limit will be set from the local XML configuration (if any) or set to unlimited rate (default). Review comment: '...re-encryption will continue automatically' --> '...re-encryption will be continued automatically' '...and the rate limit will be set to 'unlimited' (by default), or taken from the local XML configuration (if any).' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. +* Temporarily suspend re-encryption using CLI command. + +Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is 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 that is scanned during re-encryption under checkpoint lock. +|=== + +=== Using XML configuration to limit 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 + +The `control.sh|bat` script provides the ability to change the re-encryption rate, suspend and resume background re-encryption at runtime. + +NOTE: After the node restarts, the suspended background re-encryption will continue automatically, and the rate limit will be set from the local XML configuration (if any) or set to unlimited rate (default). + +[source,shell] +---- +# View the re-encryption status of the cache group. +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 to an unlimited rate. +control.sh|bat --encryption reencryption_rate_limit 0 +---- + +The re-encryption status can also be obtained using JMX metrics, which are described in the link:monitoring-metrics/new-metrics#cache-groups[Cache group metrics] section. Review comment: '...using JMX metrics described in the link:monitoring-metrics/new-metrics#cache-groups[Cache group metrics] section.' ########## File path: docs/_docs/security/cache-encryption-key-rotation.adoc ########## @@ -0,0 +1,147 @@ +// 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 + +The cache group encryption key is used to encrypt cache data on disk. +When a new cache starts, a new encryption key is generated and propagated to all server nodes in the cluster. So each node for the same cache group has the same cache encryption key. +To learn more see the link:security/tde[Transparent Data Encryption] page. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the encryption key of the cache group and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or at the end of the crypto period (key validity period). + +The process of changing the cache encryption key consists of two stages, which are performed sequentially: + +1. Rotate cache group key, this process adds a new encryption key for the specified cache group(s) 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 long time, which depends on the amount of existing data. During this period the old key will be 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, with each rotation the identifier of the new key is increased. +The same cache group has the same encryption key (with the same encryption key ID) on all nodes. + +NOTE: Secondary rotation of the cache encryption key is possible only after a complete change of the encryption key for this 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 ships a `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 can be used with `control.sh|bat`: + +[source,shell] +---- +# View the encryption key identifiers of the cache group. +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 be managed programmatically: + +[tabs] +-- +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/TDE.java[tags=cache-group-key-rotation, indent=0] +---- +-- + +== Managing the re-encryption process + +Re-encrypting existing data can take a long time. 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 rate of re-encryption by using a configuration parameter or by using the CLI at runtime. +* Temporarily suspend re-encryption using CLI command. + +Ignite 2.10 introduces a new configuration section `EncryptionConfiguration`, that is 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 that is scanned during re-encryption under checkpoint lock. +|=== + +=== Using XML configuration to limit 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 + +The `control.sh|bat` script provides the ability to change the re-encryption rate, suspend and resume background re-encryption at runtime. + +NOTE: After the node restarts, the suspended background re-encryption will continue automatically, and the rate limit will be set from the local XML configuration (if any) or set to unlimited rate (default). + +[source,shell] +---- +# View the re-encryption status of the cache group. +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 to an unlimited rate. Review comment: 'Set re-encryption rate to 'unlimited' ('0').' ---------------------------------------------------------------- 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: [email protected]
