...

Design assumes that administrator will provide ability to get new master key by EncryptionSPI from underlying storage.

Definitions

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

Prerequisites

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

Process management

...

• JAVA API:
  ignite.encryption().changeMasterKey(String masterKeyIdmasterKeyName)  - starts master key rotation process.
  String ignite.encryption().getMasterKeyIdgetMasterKeyName()  - gets current master key idname.
  
  
• JMX:
  changeMasterKey(String masterKeyIdmasterKeyName)  - starts master key rotation process.
  String getMasterKeyIdgetMasterKeyName()   - gets current master key idname.
  
  
• CLI:
  # Starts master key rotation.
  control.sh --encryption change_master_key newMasterKeyId newMasterKeyName
  
  # Displays cluster's current master key idname.
  control.sh --encryption get_master_key 
  # Starts ignite with MK recovery process. See details.
  ignite.sh --change-master-key newMasterKeyId _name
  

Process description

1. A node creates the MasterKeyChangeMessage  message and sent it by discovery as a custom event. The goal is to verify that all nodes have the same master key. 
   
   1. Initiating message should contain: 
      1. New master key id. 
      2. New master key hash.
   2. When server node processed message following actions are executed:
      
      1. It obtain hash of new master key.
      2. Compares it with the one in message
      3. If it differs then error added to the message.
      4. Store locally master key id and hash.
2. If on step1 there are some errors we log it and cancel process. Otherwise got to step3.
3. The MasterKeyChangeMessage  ack action message is sent by discovery as a custom event.
   1. Action message sould contain:
      
      1. New master key id.
      2. New master key hash.
   2. When server node processed message following actions are executed: 
      1. It checks that there are no errors in the message and the cluster is active (WAL should be available for a write to correctly log changes and survive cluster restarts). Otherwise, cancel process with error.
      2. Checks that master key id and hash is the same as it was taken from the first message. Otherwice, we log it and cancel process.
      3. Blocks creation of encrypted cache key.
      4. Reencrypt all cache group keys with new master key in a temporary datastructure. No changes in MetaStore.
      5. Create WAL logical record (ChangeMasterKeyRecord ) that consist of:
         1. New master key id
         2. Reenctyped cache group keys.
      6. Write cache group keys to MetaStore .
      7. Unblock creation of encrypted cache key. 

...

To update this node user should run ignite with system property (IGNITE_MASTER_KEY_IDNAME_TO_CHANGE_ONBEFORE_STARTUP=newMasterKeyId) or with command to change master key before join:

ignite.sh --change-master-key newMasterKeyId 

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

...

Reject node join. It may lead to inconsistent master keys in cluster. (Or if it possible to delay until key rotation process ends)

Cache start during key rotation process

...

New methods will be introduced:

• setMasterKeyIdsetMasterKeyName(String masterKeyIdmasterKeyName)  // Sets "current" master key idname
• String getMasterKeyIdgetMasterKeyName()  // Gets "current" master key idname

Follow methods will work with master key that setted by previous method:

...

Meta storage will store master key idname. Key id name from meta storage has a higher priority to key id name from EncryptionSpi .

Node attribute

...