...

• MK – MasterKey. Encrypts group keys. Master key is stored in some key storage. Master keys identified by String masterKeyName name.

Prerequisites

New master key should be available to EncryptionSPI for each server node. The cluster should be active.

Process management

Users can control the master key rotation process key via  some kind of user interface(CLI, JMX, Java API). 

• JAVA API:
  ignite.encryption().changeMasterKey(String masterKeyName)  - starts master key rotation process.
  String ignite.encryption().getMasterKeyName()  - gets current master key name.
  
  
• JMX:
  changeMasterKey(String masterKeyName)  - starts master key rotation process.
  String getMasterKeyName()   - gets current master key name.
  
  
• CLI:
  # Starts master key rotation.
  control.sh --encryption change_master_key newMasterKeyName
  
  # Displays cluster's current master key name.
  control.sh --encryption get_master_key_name
  

Process description

...

Master key change process consist of two phases:

1. Prepare master key change.
2. Perform master key change.

Each phase is a distributed process.

Prepare master key change

The goal is to verify that all server nodes have the same master key.

...

A server node starts prepare phase with the MasterKeyChangeRequest that contains:

1. New master
 
2. key
id
3. name.
 
5. New master key
hash
6. digest.
When 

Each server

...

node

...

executes following

...

actions

...

:

1. It

   obtain hash

   obtains a digest of a new master key. If the digest is unavailable then the process completes with the error.

2. Compares it with the one in message.
3. If it differs then error added to the messagethe process completes with the master key digest consistency check error.
4. Store locally master key id name and hash.
5. If on step1 there are some errors we log it and cancel process. Otherwise got to step3.
The MasterKeyChangeMessage  ack action message is sent by discovery as a custom event.Action message sould contain
6. digest.

The coordinator starts the perform phase when the prepare phase completed without errors.

Perform master key change

The coordinator node starts prepare phase with the MasterKeyChangeRequest that contains:

1. New master key
id
2. name.
3. New master key
hash
4. digest.
When 

Each server

...

node

...

executes following

...

actions

...

:

...

1. It checks that
there are no errors in
2. the
message and the
3. cluster is active (WAL should be available for a write to correctly log changes and survive cluster restarts). Otherwise,
cancel
4. the process completes with the error.
5. Checks that master key
id
6. name and
hash
7. digest is the same as it was taken from the
first message
8. prepare phase. Otherwice,
we
9. log it and cancel the process.
10. Blocks creation of encrypted cache key.
11. Reencrypt all cache group keys with new master key in a temporary datastructure. No changes in MetaStore.
12. Create WAL logical record (ChangeMasterKeyRecord ) that consist of:
    1. New master key
id
13. 1. name.
       
    2. Reenctyped cache group keys.
14. Write cache group keys to MetaStore .
15. Unblock creation of encrypted cache key. .

Distributed process

Distributed process is a cluster-wide process that accumulates single nodes results to finish itself.

The process consists of the following phases:

1. The initial request starts the process. The InitMessage sent via discovery.
2. Each server node processes an initial request and sends the single node result to the coordinator. The SingleNodeMessage sent via communication.
3. The coordinator accumulate all single nodes results and finish process. The FullMessage sent via discovery.

Several processes of one type can be started at the same time.

Process completion

Process The process completes when all nodes in cluster will process action messagethe perform phase completed (all nodes was re-encrypts their keys).

Corner cases

Node was down during key rotation. MasterKeyChangeRecord was not found.

...

To update this node user should run ignite with system property (IGNITE_MASTER_KEY_NAME_TO_CHANGE_BEFORE_STARTUP=newMasterKeyIdnewMasterKeyName)

The node will re-encrypt cache keys with new MK and try to join to cluster.

...

Cache keys must not be created during the master key rotation process. So, a node will throw an exception if a user will start cache during the key rotation process. Moreover, if group keys were generated before the master key change the cache start will be rejected (case of client node starts the cache).

A node was unable to do the perform phase.

The node will process the critical error failure. Failure handler must stop the node to prevent inconsistent keys in the cluster.

Public java API changes

EncryptionSpi

...