Cache encryption key rotation | Ignite Documentation

Ignite Summit 2025 – Call for Speakers Now Open – Learn more 

Apache Ignite logo
Edit

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 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:

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:

# 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:

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:

// 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"));

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 Write-Ahead Log segment, which may contain entries encrypted with the previous key, is removed from disk.

Note
 Re-encryption uses 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.

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

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <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>
</bean>

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). 
# 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 Cache group metrics section.

© 2024 The Apache Software Foundation.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.