Motivation

Master key(MK)Key rotation required in case of it compromising or at the end of crypto period(key validity period). 

...

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

Goal: 

.

...

New processes: 

Master 

...

Key rotation

...

Master

...

New administrator commands: 

1. Master keys view: node -> master key hash 

2. Cache group keys view: node -> group name -> encryption key hash 

...

keys will be identified by String keyId.

Process start

...

Administrator initiates key rotation via  some kind of user interface(CLI,  Visor, Web Console, JMX,JMX, Java API,  etc). 

JAVA API:
ignite.encryption().changeMasterKey(String keyId) - starts master key rotation process.
String ignite.encryption().getMasterKeyId() - gets current master key id.

JMX:
changeMasterKey(String keyId)
String getMasterKeyId()

CLI:
control.sh

Process description

...

1. Initiating message is sent by discovery.A node creates the ChangeMasterKeyMessage 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 hash id. 
      2. New master key idhash.
   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.
2. If on step1 there are some errors we log it and cancel process. Otherwise got to step3.
3. Action The ChangeMasterKeyFinishMessage action message is sent by discovery as a custom event.
   1. Action message sould contain:New master key hash. 
      
      1. New master key id.
   2. When server node processed message following actions are executed: 
      1. Blocks creation of encrypted cache key. Encrypt cache group keys with new master key. Unblock creation of encrypted cache key. 
      2. EncryptionSPI executes keys rotation (implementation specific).

...

1. 1. 2. Reencrypt all cache group keys with new master key in a temporary datastructure.
   
   
   1. 1. No changes in MetaStore.
      2. Create WAL logical record (
   MasterKeyChangeRecord
2. If during node recovery with logical records we found MasterKeyChangeRecord it passed to EncryptionManager.
3. When MetaStore becomes available for write, EncryptionManager writes new cache group keys to it.
   1. 1. ChangeMasterKeyRecord) that consist of:
         1. New master key
      hash
      1. 1. id
         2. Reenctyped cache group keys.
      2. Write cache group keys to MetaStore.

Node recovery:

1. 1. 1. Unblock creation of encrypted cache key. 

Process completion: 

Process completes when all nodes in cluster will process action message.

Master key rotation recovery start

Corner cases

Node left during key rotation process(was not starting re-encrypt cache keys)

...

:

If some node was unavailable during master key rotation process it will unable to join to the cluster because it has old master key has.

To update this node design introduce master key recovery start option.

Process start:

Administartor initiates process by providing startup option.

Process description:

Node should execute following steps before join to the cluster:

1. Obtain old master key by id
2. Obtain new master key by id
3. Reencrypt cache group keys with new master key and store it to metastore.
4. EncryptionSPI executes keys rotation (implementation specific).

New commands: 

• Master key hashes. 

  • Input: nothing 

  • Output: 

    • List of Tuples3 

      • Node ID 

      • Current key hash 

      • Previous key hash or null. 

• Cache key hashes. 

  • Input: cache id. 

  • Output: 

process:

Option 1 (auto). Cluster send to joining node his master key id. The joining node re-encrypt cache keys and tries to join to cluster.

Option 2 (manual). Administrator change master key id in the configuration. When the node starts it reads master key id from meta storage. If keys differ node will re-encrypt cache keys and tries to join to cluster.

Node left during key rotation process(was starting re-encrypt cache keys):

1. If during node recovery with logical records we found ChangeMasterKeyRecord it passed to EncryptionManager.
2. When MetaStore becomes available for write, EncryptionManager writes new cache group keys to it.

Node join during key rotation process:

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:

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.

Code changes

EncryptionSpi

byte[] masterKeyDigest();

byte[] masterKeyDigest(String masterKeyId);

byte[] encryptKey(Serializable key);

byte[] encryptKey(Serializable key, String masterKeyId);

Serializable decryptKey(byte[] key);

Serializable decryptKey(byte[] key, String masterKeyId);

where masterKeyId - master key id. If null the default key will be used for compatibility reason.

IgniteConfiguration

Add new methods:

public IgniteConfiguration setEncryptionMasterKeyId(String keyId) - sets master key id.

public String getEncryptionMasterKeyId()

MetaStorage

MetaStorage will store master key id.

Node attribute

Currently joining node send hash MK for validation in attributes. Attributes can't be modified at runtime. So joining node will send hash MK in JoiningNodeDiscoveryData.

List of Tuples3 

...

Node ID 

...

Current key hash 

...