Nikita-tech-writer commented on a change in pull request #8446: URL: https://github.com/apache/ignite/pull/8446#discussion_r556671194
########## 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 + +Cache group encryption key is used to encrypt cache data on 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 for the same cache group has the same cache encryption key. +See link:security/tde[Transparent Data Encryption] to learn more. + +Ignite 2.10 introduces a feature for changing the cache encryption key. +It allows users to change the cache group encryption key and re-encrypt existing data at runtime. + +Rotation of the cache encryption key is required if this key has been compromised or if the crypto period (key validity period) has 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(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. It 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. The identifier of the new key increases with each 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 Review comment: ```suggestion === From Code ``` ---------------------------------------------------------------- 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]
