Package org.apache.ignite.internal.managers.encryption

## Class GridEncryptionManager

- java.lang.Object
- - org.apache.ignite.internal.managers.GridManagerAdapter<EncryptionSpi>
  - - org.apache.ignite.internal.managers.encryption.GridEncryptionManager

All Implemented Interfaces:
  `IgniteEncryption`, `GridComponent`, `EncryptionCacheKeyProvider`, `GridManager`, `PartitionsExchangeAware`, `MetastorageLifecycleListener`, `IgniteChangeGlobalStateSupport`

    public class GridEncryptionManager
    extends GridManagerAdapter<EncryptionSpi>
    implements EncryptionCacheKeyProvider, MetastorageLifecycleListener, IgniteChangeGlobalStateSupport, IgniteEncryption, PartitionsExchangeAware

Manages cache keys and `EncryptionSpi` instances. NOTE: Following protocol applied to statically configured caches. For dynamically created caches key generated in request creation. Group keys generation protocol:

- Joining node:
  - 1. Collects and send all stored group keys to coordinator.
  - 2. Generate(but doesn't store locally!) and send keys for all statically configured groups in case the not presented in metastore.
  - 3. Store all keys received from coordinator to local store.
- Coordinator:
  - 1. Checks master key digest are equal to local. If not join is rejected.
  - 2. Checks all stored keys from joining node are equal to stored keys. If not join is rejected.
  - 3. Collects all stored keys and sends it to joining node.
- All nodes:
  - 1. If new key for group doesn't exists locally it added to local store.
  - 2. If new key for group exists locally, then received key skipped.
  - 3. If a cache group is encrypted with a different (previous) encryption key, then background re-encryption of this group with a new key is started.

Master key change process:

1. The initiator starts the process.
2. Each server node compares the master key digest. If not equals - the process finishes with error.
3. Each server node changes the master key: creates WAL record and re-encrypts group keys in MetaStore.
4. The initiator gets the result when all server nodes completed the master key change.

See Also:
  `prepareMKChangeProc`, `performMKChangeProc`

### Nested Class Summary

Nested Classes
`protected static class` `GridEncryptionManager.EmptyResult`
`protected static class` `GridEncryptionManager.KeyChangeFuture` Key change future.
`protected static class` `GridEncryptionManager.NodeEncryptionKeys`

### Nested classes/interfaces inherited from interface org.apache.ignite.internal.GridComponent

`GridComponent.DiscoveryDataExchangeType`

### Field Summary

Fields
`static String` `ENCRYPTION_KEYS_PREFIX` Prefix for a encryption group key in meta store, which contains encryption keys with identifiers.
`static int` `INITIAL_KEY_ID` Initial identifier for cache group encryption key.
`static String` `MASTER_KEY_NAME_PREFIX` Prefix for a master key name.

### Fields inherited from class org.apache.ignite.internal.managers.GridManagerAdapter

`ctx, log`

### Constructor Summary

Constructors
`GridEncryptionManager​(GridKernalContext ctx)`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `applyKeys​(MasterKeyChangeRecordV2 rec)` Apply keys from WAL record during the recovery phase.
`void` `applyReencryptionStartRecord​(ReencryptionStartRecord rec)` Start reencryption using logical WAL record.
`IgniteFuture<Void>` `changeCacheGroupKey​(Collection<String> cacheOrGrpNames)` Starts cache group encryption key change process.
`protected void` `changeCacheGroupKeyLocal​(int[] grpIds, byte[] keyIds, byte[][] keys)`
`IgniteFuture<Void>` `changeMasterKey​(String masterKeyName)` Starts master key change process.
`void` `checkEncryptedCacheSupported()` Checks cache encryption supported by all nodes in cluster.
`void` `collectGridNodeData​(DiscoveryDataBag dataBag)` Collects discovery data on nodes already in grid on receiving `TcpDiscoveryNodeAddedMessage`.
`void` `collectJoiningNodeData​(DiscoveryDataBag dataBag)` Collects discovery data on joining node before sending `TcpDiscoveryJoinRequestMessage` request.
`GridComponent.DiscoveryDataExchangeType` `discoveryDataType()` Gets unique component type to distinguish components providing discovery data.
`IgniteInternalFuture<T2<Collection<byte[]>,​byte[]>>` `generateKeys​(int keyCnt)`
`@Nullable GroupKey` `getActiveKey​(int grpId)` Returns group encryption key, that was set for writing.
`long` `getBytesLeftForReencryption​(int grpId)`
`long` `getEncryptionState​(int grpId, int partId)` Get reencryption status for partition.
`String` `getMasterKeyName()` Gets the current master key name.
`double` `getReencryptionRate()`
`@Nullable GroupKey` `groupKey​(int grpId, int keyId)` Returns group encryption key with specified ID.
`@Nullable List<Integer>` `groupKeyIds​(int grpId)` Gets the existing encryption key IDs for the specified cache group.
`boolean` `isMasterKeyChangeInProgress()`
`@org.jetbrains.annotations.Nullable byte[]` `masterKeyDigest()` Digest of last changed master key or `null` if master key was not changed.
`void` `onActivate​(GridKernalContext kctx)` Called when cluster performing activation.
`void` `onCacheGroupDestroyed​(int grpId)` Callback for cache group destroy event.
`void` `onCacheGroupStop​(int grpId)` Callback is called before invalidate page memory.
`void` `onCancelDestroyPartitionStore​(CacheGroupContext grp, int partId)`
`void` `onDeActivate​(GridKernalContext kctx)` Called when cluster performing deactivation.
`void` `onDestroyPartitionStore​(CacheGroupContext grp, int partId)`
`void` `onDisconnected​(IgniteFuture<?> reconnectFut)` Client disconnected callback.
`void` `onDoneAfterTopologyUnlock​(GridDhtPartitionsExchangeFuture fut)` Callback from exchange process completion; called after topology is unlocked.
`void` `onGridDataReceived​(DiscoveryDataBag.GridDiscoveryData data)` Receives discovery data object from remote nodes (called on new node during discovery process).
`void` `onJoiningNodeDataReceived​(DiscoveryDataBag.JoiningNodeDiscoveryData data)` Method is called on nodes that are already in grid (not on joining node).
`protected void` `onKernalStart0()`
`protected void` `onKernalStop0​(boolean cancel)`
`void` `onLocalJoin()` Callback for local join.
`void` `onReadyForRead​(ReadOnlyMetastorage metastorage)` Is called when metastorage is made ready for read-only operations very early on node startup phase.
`void` `onReadyForReadWrite​(ReadWriteMetastorage metaStorage)` Fully functional metastore capable of performing reading and writing operations.
`IgniteInternalFuture<?>` `onReconnected​(boolean clusterRestarted)` Client reconnected callback.
`void` `onWalSegmentRemoved​(long segmentIdx)` Callback when WAL segment is removed.
`IgniteInternalFuture<Void>` `reencryptionFuture​(int grpId)`
`boolean` `reencryptionInProgress()`
`boolean` `reencryptionInProgress​(int grpId)`
`boolean` `resumeReencryption​(int grpId)` Forces re-encryption of the cache group.
`void` `setEncryptionState​(CacheGroupContext grp, int partId, int idx, int total)` Set reencryption status for partition.
`void` `setInitialGroupKey​(int grpId, @org.jetbrains.annotations.Nullable byte[] encKey, @Nullable Integer encKeyId)` Sets new initial group key if key is not null.
`void` `setReencryptionRate​(double rate)`
`void` `start()` Starts grid component.
`void` `stop​(boolean cancel)` Stops grid component.
`boolean` `suspendReencryption​(int grpId)` Suspend re-encryption of the cache group.
`@Nullable IgniteNodeValidationResult` `validateNode​(ClusterNode node, DiscoveryDataBag.JoiningNodeDiscoveryData discoData)` Validates that new node can join grid topology, this method is called on coordinator node before new node joins topology.

### Methods inherited from class org.apache.ignite.internal.managers.GridManagerAdapter

`assertParameter, enabled, getSpi, getSpi, getSpis, inject, onAfterSpiStart, onBeforeSpiStart, onKernalStart, onKernalStop, printMemoryStats, startInfo, startSpi, stopInfo, stopSpi, toString, validateNode`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface org.apache.ignite.internal.processors.cache.distributed.dht.preloader.PartitionsExchangeAware

`onDoneBeforeTopologyUnlock, onInitAfterTopologyLock, onInitBeforeTopologyLock`

### Field Detail

#### MASTER_KEY_NAME_PREFIX

    public static final String MASTER_KEY_NAME_PREFIX

Prefix for a master key name.

See Also:
  Constant Field Values

#### ENCRYPTION_KEYS_PREFIX

    public static final String ENCRYPTION_KEYS_PREFIX

Prefix for a encryption group key in meta store, which contains encryption keys with identifiers.

See Also:
  Constant Field Values

#### INITIAL_KEY_ID

    public static final int INITIAL_KEY_ID

Initial identifier for cache group encryption key.

See Also:
  Constant Field Values

### Constructor Detail

#### GridEncryptionManager

    public GridEncryptionManager​(GridKernalContext ctx)

Parameters:
  `ctx` - Kernel context.

### Method Detail

#### start

    public void start()
               throws IgniteCheckedException

Starts grid component.

Specified by:
  `start` in interface `GridComponent`
Throws:
  `IgniteCheckedException` - Throws in case of any errors.

#### stop

    public void stop​(boolean cancel)
              throws IgniteCheckedException

Stops grid component.

Specified by:
  `stop` in interface `GridComponent`
Parameters:
  `cancel` - If `true`, then all ongoing tasks or jobs for relevant components need to be cancelled.
Throws:
  `IgniteCheckedException` - Thrown in case of any errors.

#### onKernalStart0

    protected void onKernalStart0()

Overrides:
  `onKernalStart0` in class `GridManagerAdapter<EncryptionSpi>`

#### onKernalStop0

    protected void onKernalStop0​(boolean cancel)

Overrides:
  `onKernalStop0` in class `GridManagerAdapter<EncryptionSpi>`
Parameters:
  `cancel` - Cancel flag.

#### onDisconnected

    public void onDisconnected​(IgniteFuture<?> reconnectFut)

Client disconnected callback.

Specified by:
  `onDisconnected` in interface `GridComponent`
Overrides:
  `onDisconnected` in class `GridManagerAdapter<EncryptionSpi>`
Parameters:
  `reconnectFut` - Reconnect future.

#### onReconnected

    public IgniteInternalFuture<?> onReconnected​(boolean clusterRestarted)

Client reconnected callback.

Specified by:
  `onReconnected` in interface `GridComponent`
Overrides:
  `onReconnected` in class `GridManagerAdapter<EncryptionSpi>`
Parameters:
  `clusterRestarted` - Cluster restarted flag.
Returns:
  Future to wait before completing reconnect future.

#### onLocalJoin

    public void onLocalJoin()

Callback for local join.

#### validateNode

    @Nullable
    public @Nullable IgniteNodeValidationResult validateNode​(ClusterNode node,
                                                             DiscoveryDataBag.JoiningNodeDiscoveryData discoData)

Validates that new node can join grid topology, this method is called on coordinator node before new node joins topology.

Specified by:
  `validateNode` in interface `GridComponent`
Overrides:
  `validateNode` in class `GridManagerAdapter<EncryptionSpi>`
Parameters:
  `node` - Joining node.
  `discoData` - Joining node discovery data.
Returns:
  Validation result or `null` in case of success.

#### collectJoiningNodeData

    public void collectJoiningNodeData​(DiscoveryDataBag dataBag)

Collects discovery data on joining node before sending `TcpDiscoveryJoinRequestMessage` request.

Specified by:
  `collectJoiningNodeData` in interface `GridComponent`
Overrides:
  `collectJoiningNodeData` in class `GridManagerAdapter<EncryptionSpi>`
Parameters:
  `dataBag` - container object to store discovery data in.

#### onJoiningNodeDataReceived

    public void onJoiningNodeDataReceived​(DiscoveryDataBag.JoiningNodeDiscoveryData data)

Method is called on nodes that are already in grid (not on joining node). It receives discovery data from joining node.

Specified by:
  `onJoiningNodeDataReceived` in interface `GridComponent`
Overrides:
  `onJoiningNodeDataReceived` in class `GridManagerAdapter<EncryptionSpi>`
Parameters:
  `data` - `DiscoveryDataBag.JoiningNodeDiscoveryData` interface to retrieve discovery data of joining node.

#### collectGridNodeData

    public void collectGridNodeData​(DiscoveryDataBag dataBag)

Collects discovery data on nodes already in grid on receiving `TcpDiscoveryNodeAddedMessage`.

Specified by:
  `collectGridNodeData` in interface `GridComponent`
Overrides:
  `collectGridNodeData` in class `GridManagerAdapter<EncryptionSpi>`
Parameters:
  `dataBag` - container object to store discovery data in.

#### onGridDataReceived

    public void onGridDataReceived​(DiscoveryDataBag.GridDiscoveryData data)

Receives discovery data object from remote nodes (called on new node during discovery process).

Specified by:
  `onGridDataReceived` in interface `GridComponent`
Overrides:
  `onGridDataReceived` in class `GridManagerAdapter<EncryptionSpi>`
Parameters:
  `data` - `DiscoveryDataBag.GridDiscoveryData` interface to retrieve discovery data collected on remote nodes (data common for all nodes in grid and specific for each node).

#### getActiveKey

    @Nullable
    public @Nullable GroupKey getActiveKey​(int grpId)

Returns group encryption key, that was set for writing.

Specified by:
  `getActiveKey` in interface `EncryptionCacheKeyProvider`
Parameters:
  `grpId` - Cache group ID.
Returns:
  Group encryption key with ID, that was set for writing.

#### groupKey

    @Nullable
    public @Nullable GroupKey groupKey​(int grpId,
                                       int keyId)

Returns group encryption key with specified ID.

Specified by:
  `groupKey` in interface `EncryptionCacheKeyProvider`
Parameters:
  `grpId` - Cache group ID.
  `keyId` - Encryption key ID.
Returns:
  Group encryption key.

#### groupKeyIds

    @Nullable
    public @Nullable List<Integer> groupKeyIds​(int grpId)

Gets the existing encryption key IDs for the specified cache group.

Parameters:
  `grpId` - Cache group ID.
Returns:
  List of the key identifiers.

#### changeMasterKey

    public IgniteFuture<Void> changeMasterKey​(String masterKeyName)

Starts master key change process.

Each node will re-encrypt group keys stored on the disk.

NOTE: The new master key should be available to `EncryptionSpi` for each server node. Cache start and node join during the key change process is prohibited and will be rejected.

If some node was unavailable during a master key change process it won't be able to join to cluster with the old master key. The node should re-encrypt group keys during recovery on startup. The actual master key name should be set via `IgniteSystemProperties.IGNITE_MASTER_KEY_NAME_TO_CHANGE_BEFORE_STARTUP`.

Specified by:
  `changeMasterKey` in interface `IgniteEncryption`
Parameters:
  `masterKeyName` - Name of the master key.
Returns:
  Future for this operation.

#### getMasterKeyName

    public String getMasterKeyName()

Gets the current master key name.

Specified by:
  `getMasterKeyName` in interface `IgniteEncryption`
Returns:
  Master key name.

#### changeCacheGroupKey

    public IgniteFuture<Void> changeCacheGroupKey​(Collection<String> cacheOrGrpNames)

Starts cache group encryption key change process.

NOTE: Node join is rejected during rotation of cache group encryption key. Background re-encryption of existing data in the specified cache group(s) begins after the encryption key(s) is changed. During re-encryption, node join is not rejected, the cluster remains fully functional, it is fault-tolerant operation that automatically continues after restart. Secondary rotation of the encryption key of a cache group is only possible after background re-encryption of existing data in this cache group is completed.

Specified by:
  `changeCacheGroupKey` in interface `IgniteEncryption`
Parameters:
  `cacheOrGrpNames` - Cache or group names.
Returns:
  Future which will be completed when new encryption key(s) are set for writing on all nodes in the cluster and re-encryption of existing cache data is initiated.

#### changeCacheGroupKeyLocal

    protected void changeCacheGroupKeyLocal​(int[] grpIds,
                                            byte[] keyIds,
                                            byte[][] keys)
                                     throws IgniteCheckedException

Parameters:
  `grpIds` - Cache group IDs.
  `keyIds` - Encryption key IDs.
  `keys` - Encryption keys.
Throws:
  `IgniteCheckedException` - If failed.

#### reencryptionFuture

    public IgniteInternalFuture<Void> reencryptionFuture​(int grpId)

Parameters:
  `grpId` - Cache group ID.
Returns:
  Future that will be completed when reencryption of the specified group is finished.

#### reencryptionInProgress

    public boolean reencryptionInProgress​(int grpId)

Parameters:
  `grpId` - Cache group ID.
Returns:
  `True` If the specified cache group is currently being re-encrypted.

#### reencryptionInProgress

    public boolean reencryptionInProgress()

Returns:
  `True` If reencryption is active in the cluster.

#### getReencryptionRate

    public double getReencryptionRate()

Returns:
  Re-encryption rate limit in megabytes per second (`0` - unlimited).

#### setReencryptionRate

    public void setReencryptionRate​(double rate)

Parameters:
  `rate` - Re-encryption rate limit in megabytes per second (`0` - unlimited).

#### setInitialGroupKey

    public void setInitialGroupKey​(int grpId,
                                   @Nullable
                                   @org.jetbrains.annotations.Nullable byte[] encKey,
                                   @Nullable
                                   @Nullable Integer encKeyId)

Sets new initial group key if key is not null.

Parameters:
  `grpId` - Cache group ID.
  `encKey` - Encryption key
  `encKeyId` - Key id to use. If `null`, `INITIAL_KEY_ID` is used.

#### onCacheGroupStop

    public void onCacheGroupStop​(int grpId)

Callback is called before invalidate page memory.

Parameters:
  `grpId` - Cache group ID.

#### onCacheGroupDestroyed

    public void onCacheGroupDestroyed​(int grpId)

Callback for cache group destroy event.

Parameters:
  `grpId` - Cache group ID.

#### onDestroyPartitionStore

    public void onDestroyPartitionStore​(CacheGroupContext grp,
                                        int partId)

Parameters:
  `grp` - Cache group.
  `partId` - Partition ID.

#### onCancelDestroyPartitionStore

    public void onCancelDestroyPartitionStore​(CacheGroupContext grp,
                                              int partId)

Parameters:
  `grp` - Cache group.
  `partId` - Partition ID.

#### onWalSegmentRemoved

    public void onWalSegmentRemoved​(long segmentIdx)

Callback when WAL segment is removed.

Parameters:
  `segmentIdx` - WAL segment index.

#### onReadyForRead

    public void onReadyForRead​(ReadOnlyMetastorage metastorage)

Is called when metastorage is made ready for read-only operations very early on node startup phase. Reference for read-only metastorage should be used only within this method and shouldn't be stored to any field.

Specified by:
  `onReadyForRead` in interface `MetastorageLifecycleListener`
Parameters:
  `metastorage` - Read-only meta storage.

#### onReadyForReadWrite

    public void onReadyForReadWrite​(ReadWriteMetastorage metaStorage)
                             throws IgniteCheckedException

Fully functional metastore capable of performing reading and writing operations. Components interested in using metastore are allowed to keep reference passed into the method in their fields.

Specified by:
  `onReadyForReadWrite` in interface `MetastorageLifecycleListener`
Parameters:
  `metaStorage` - Fully functional meta storage.
Throws:
  `IgniteCheckedException`

#### onActivate

    public void onActivate​(GridKernalContext kctx)
                    throws IgniteCheckedException

Called when cluster performing activation.

Specified by:
  `onActivate` in interface `IgniteChangeGlobalStateSupport`
Parameters:
  `kctx` - Kernal context.
Throws:
  `IgniteCheckedException` - If failed.

#### onDeActivate

    public void onDeActivate​(GridKernalContext kctx)

Called when cluster performing deactivation.

Specified by:
  `onDeActivate` in interface `IgniteChangeGlobalStateSupport`
Parameters:
  `kctx` - Kernal context.

#### onDoneAfterTopologyUnlock

    public void onDoneAfterTopologyUnlock​(GridDhtPartitionsExchangeFuture fut)

Callback from exchange process completion; called after topology is unlocked.

Specified by:
  `onDoneAfterTopologyUnlock` in interface `PartitionsExchangeAware`
Parameters:
  `fut` - Partition map exchange future.

#### setEncryptionState

    public void setEncryptionState​(CacheGroupContext grp,
                                   int partId,
                                   int idx,
                                   int total)

Set reencryption status for partition.

Parameters:
  `grp` - Cache group.
  `partId` - Partition ID.
  `idx` - Index of the last reencrypted page.
  `total` - Total pages to be reencrypted.

#### getEncryptionState

    public long getEncryptionState​(int grpId,
                                   int partId)

Get reencryption status for partition.

Parameters:
  `grpId` - Cache group ID.
  `partId` - Parttiion ID.
Returns:
  Index and count of pages to be reencrypted.

#### getBytesLeftForReencryption

    public long getBytesLeftForReencryption​(int grpId)

Parameters:
  `grpId` - Cache group ID.
Returns:
  The number of bytes left for re-ecryption.

#### generateKeys

    public IgniteInternalFuture<T2<Collection<byte[]>,​byte[]>> generateKeys​(int keyCnt)

Parameters:
  `keyCnt` - Count of keys to generate.
Returns:
  Future that will contain results of generation.

#### suspendReencryption

    public boolean suspendReencryption​(int grpId)
                                throws IgniteCheckedException

Suspend re-encryption of the cache group.

Parameters:
  `grpId` - Cache group ID.
Throws:
  `IgniteCheckedException`

#### resumeReencryption

    public boolean resumeReencryption​(int grpId)
                               throws IgniteCheckedException

Forces re-encryption of the cache group.

Parameters:
  `grpId` - Cache group ID.
Throws:
  `IgniteCheckedException`

#### checkEncryptedCacheSupported

    public void checkEncryptedCacheSupported()
                                      throws IgniteCheckedException

Checks cache encryption supported by all nodes in cluster.

Throws:
  `IgniteCheckedException` - If check fails.

#### discoveryDataType

    public GridComponent.DiscoveryDataExchangeType discoveryDataType()

Gets unique component type to distinguish components providing discovery data. Must return non-null value if component implements any of methods `GridComponent.collectJoiningNodeData(DiscoveryDataBag)` or `GridComponent.collectGridNodeData(DiscoveryDataBag)`.

Specified by:
  `discoveryDataType` in interface `GridComponent`
Overrides:
  `discoveryDataType` in class `GridManagerAdapter<EncryptionSpi>`
Returns:
  Unique component type for discovery data exchange.

#### applyKeys

    public void applyKeys​(MasterKeyChangeRecordV2 rec)

Apply keys from WAL record during the recovery phase.

Parameters:
  `rec` - Record.

#### applyReencryptionStartRecord

    public void applyReencryptionStartRecord​(ReencryptionStartRecord rec)

Start reencryption using logical WAL record.

Parameters:
  `rec` - Reencryption start logical record.

#### isMasterKeyChangeInProgress

    public boolean isMasterKeyChangeInProgress()

Returns:
  `True` if the master key change process in progress.

#### masterKeyDigest

    @Nullable
    public @org.jetbrains.annotations.Nullable byte[] masterKeyDigest()

Digest of last changed master key or `null` if master key was not changed.

Used to verify the digest on a client node in case of cache start after master key change.

Returns:
  Digest of last changed master key or `null` if master key was not changed.