EncryptInterceptor (Apache Tomcat 10.1.57 API Documentation)
Description: declaration: package: org.apache.catalina.tribes.group.interceptors, class: EncryptInterceptor

# Class EncryptInterceptor

java.lang.Object
org.apache.catalina.tribes.group.ChannelInterceptorBase
org.apache.catalina.tribes.group.interceptors.EncryptInterceptor

All Implemented Interfaces:
  `ChannelInterceptor, EncryptInterceptorMBean, Heartbeat, MembershipListener`

public class EncryptInterceptor extends ChannelInterceptorBase implements EncryptInterceptorMBean
Adds encryption using a pre-shared key. The length of the key (in bytes) must be acceptable for the encryption algorithm being used. For example, for AES, you must use a key of either 16 bytes (128 bits, 24 bytes 192 bits), or 32 bytes (256 bits). You can supply the raw key bytes by calling `setEncryptionKey(byte[])` or the hex-encoded binary bytes by calling `setEncryptionKey(String)`.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface ChannelInterceptor

  `ChannelInterceptor.InterceptorEvent`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final StringManager`
  `sm`
  String manager for internationalized messages.

  ### Fields inherited from class ChannelInterceptorBase

  `optionFlag`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EncryptInterceptor()`
  Creates a new encryption interceptor with default settings.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getEncryptionAlgorithm()`
  Gets the encryption algorithm being used to encrypt and decrypt channel messages.
  `byte[]`
  `getEncryptionKey()`
  Gets the encryption key being used for encryption and decryption.
  `String`
  `getEncryptionKeyString()`
  Returns the hex-encoded encryption key string.
  `String`
  `getProviderName()`
  Gets the JCA provider name used for cryptographic activities.
  `int`
  `getReplayWindowMessageCount()`
  Returns the maximum number of replay entries to retain.
  `long`
  `getReplayWindowTime()`
  Returns the time-based replay window in milliseconds.
  `void`
  `messageReceived(ChannelMessage msg)`
  The `messageReceived` is invoked when a message is received.
  `void`
  `sendMessage(Member[] destination, ChannelMessage msg, InterceptorPayload payload)`
  The `sendMessage` method is called when a message is being sent to one more destinations.
  `void`
  `setEncryptionAlgorithm(String algorithm)`
  Sets the encryption algorithm to be used for encrypting and decrypting channel messages.
  `void`
  `setEncryptionKey(byte[] key)`
  Sets the encryption key for encryption and decryption.
  `void`
  `setEncryptionKey(String keyBytes)`
  Sets the encryption key using a hex-encoded string.
  `void`
  `setEncryptionKeyString(String encryptionKeyString)`
  Sets the hex-encoded encryption key string.
  `void`
  `setProviderName(String provider)`
  Sets the JCA provider name used for cryptographic activities.
  `void`
  `setReplayWindowMessageCount(int replayWindowMessageCount)`
  Sets the maximum number of replay entries to retain.
  `void`
  `setReplayWindowTime(long replayWindowTime)`
  Sets the time-based replay window in milliseconds.
  `void`
  `start(int svc)`
  Starts up the channel.
  `void`
  `stop(int svc)`
  Shuts down the channel.

  ### Methods inherited from class ChannelInterceptorBase

  `fireInterceptorEvent, getChannel, getLocalMember, getMember, getMembers, getNext, getOptionFlag, getPrevious, hasMembers, heartbeat, memberAdded, memberDisappeared, okToProcess, setChannel, setNext, setOptionFlag, setPrevious`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface EncryptInterceptorMBean

  `getOptionFlag, setOptionFlag`

- ## Field Details

  - ### sm

    protected static final StringManager sm
    String manager for internationalized messages.

- ## Constructor Details

  - ### EncryptInterceptor

    public EncryptInterceptor()
    Creates a new encryption interceptor with default settings.

- ## Method Details

  - ### start

    public void start(int svc) throws ChannelException
    Description copied from interface: `ChannelInterceptor`
    Starts up the channel. This can be called multiple times for individual services to start The svc parameter can be the logical or value of any constants
    Specified by:
      `start` in interface `ChannelInterceptor`
    Overrides:
      `start` in class `ChannelInterceptorBase`
    Parameters:
      `svc` - one of:
      - Channel.DEFAULT - will start all services
      - Channel.MBR_RX_SEQ - starts the membership receiver
      - Channel.MBR_TX_SEQ - starts the membership broadcaster
      - Channel.SND_TX_SEQ - starts the replication transmitter
      - Channel.SND_RX_SEQ - starts the replication receiver
    Throws:
      `ChannelException` - if a startup error occurs or the service is already started.
    See Also:
      - `Channel`

  - ### stop

    public void stop(int svc) throws ChannelException
    Description copied from interface: `ChannelInterceptor`
    Shuts down the channel. This can be called multiple times for individual services to shut down. The svc parameter can be the logical or value of any constants
    Specified by:
      `stop` in interface `ChannelInterceptor`
    Overrides:
      `stop` in class `ChannelInterceptorBase`
    Parameters:
      `svc` - one of:
      - Channel.DEFAULT - will shut down all services
      - Channel.MBR_RX_SEQ - stops the membership receiver
      - Channel.MBR_TX_SEQ - stops the membership broadcaster
      - Channel.SND_TX_SEQ - stops the replication transmitter
      - Channel.SND_RX_SEQ - stops the replication receiver
    Throws:
      `ChannelException` - if a startup error occurs or the service is already started.
    See Also:
      - `Channel`

  - ### sendMessage

    public void sendMessage(Member[] destination, ChannelMessage msg, InterceptorPayload payload) throws ChannelException
    Description copied from interface: `ChannelInterceptor`
    The `sendMessage` method is called when a message is being sent to one more destinations. The interceptor can modify any of the parameters and then pass on the message down the stack by invoking `getNext().sendMessage(destination,msg,payload)`.

    Alternatively the interceptor can stop the message from being sent by not invoking `getNext().sendMessage(destination,msg,payload)`.

    If the message is to be sent asynchronous the application can be notified of completion and errors by passing in an error handler attached to a payload object.

    The ChannelMessage.getAddress contains Channel.getLocalMember, and can be overwritten to simulate a message sent from another node.

    Specified by:
      `sendMessage` in interface `ChannelInterceptor`
    Overrides:
      `sendMessage` in class `ChannelInterceptorBase`
    Parameters:
      `destination` - Member[] - the destination for this message
      `msg` - ChannelMessage - the message to be sent
      `payload` - InterceptorPayload - the payload, carrying an error handler and future useful data, can be null
    Throws:
      `ChannelException` - if a serialization error happens.
    See Also:
      - `ErrorHandler`
      - `InterceptorPayload`

  - ### messageReceived

    public void messageReceived(ChannelMessage msg)
    Description copied from interface: `ChannelInterceptor`
    The `messageReceived` is invoked when a message is received. `ChannelMessage.getAddress()` is the sender, or the reply-to address if it has been overwritten.
    Specified by:
      `messageReceived` in interface `ChannelInterceptor`
    Overrides:
      `messageReceived` in class `ChannelInterceptorBase`
    Parameters:
      `msg` - ChannelMessage

  - ### setEncryptionAlgorithm

    public void setEncryptionAlgorithm(String algorithm)
    Sets the encryption algorithm to be used for encrypting and decrypting channel messages. You must specify the `algorithm/mode/padding`. Information on standard algorithm names may be found in the Java documentation. Default is `AES/CBC/PKCS5Padding` for backwards compatibility but it is recommended that `AES/GCM/NoPadding` is used.
    Specified by:
      `setEncryptionAlgorithm` in interface `EncryptInterceptorMBean`
    Parameters:
      `algorithm` - The algorithm to use.

  - ### getEncryptionAlgorithm

    public String getEncryptionAlgorithm()
    Gets the encryption algorithm being used to encrypt and decrypt channel messages.
    Specified by:
      `getEncryptionAlgorithm` in interface `EncryptInterceptorMBean`
    Returns:
      The algorithm being used, including the algorithm mode and padding.

  - ### setEncryptionKey

    public void setEncryptionKey(byte[] key)
    Sets the encryption key for encryption and decryption. The length of the key must be appropriate for the algorithm being used.
    Specified by:
      `setEncryptionKey` in interface `EncryptInterceptorMBean`
    Parameters:
      `key` - The encryption key.

  - ### setEncryptionKey

    public void setEncryptionKey(String keyBytes)
    Sets the encryption key using a hex-encoded string. Each pair of hex characters represents one byte of the key.
    Parameters:
      `keyBytes` - The hex-encoded encryption key.

  - ### getEncryptionKey

    public byte[] getEncryptionKey()
    Gets the encryption key being used for encryption and decryption.
    Specified by:
      `getEncryptionKey` in interface `EncryptInterceptorMBean`
    Returns:
      The encryption key.

  - ### getEncryptionKeyString

    public String getEncryptionKeyString()
    Returns the hex-encoded encryption key string.
    Returns:
      the hex-encoded encryption key, or `null` if not set

  - ### setEncryptionKeyString

    public void setEncryptionKeyString(String encryptionKeyString)
    Sets the hex-encoded encryption key string.
    Parameters:
      `encryptionKeyString` - the hex-encoded encryption key

  - ### setProviderName

    public void setProviderName(String provider)
    Sets the JCA provider name used for cryptographic activities. Default is the JVM platform default.
    Specified by:
      `setProviderName` in interface `EncryptInterceptorMBean`
    Parameters:
      `provider` - The name of the JCA provider.

  - ### getProviderName

    public String getProviderName()
    Gets the JCA provider name used for cryptographic activities. Default is the JVM platform default.
    Specified by:
      `getProviderName` in interface `EncryptInterceptorMBean`
    Returns:
      The name of the JCA provider.

  - ### getReplayWindowTime

    public long getReplayWindowTime()
    Returns the time-based replay window in milliseconds.
    Specified by:
      `getReplayWindowTime` in interface `EncryptInterceptorMBean`
    Returns:
      The replay window time

  - ### setReplayWindowTime

    public void setReplayWindowTime(long replayWindowTime)
    Sets the time-based replay window in milliseconds.
    Specified by:
      `setReplayWindowTime` in interface `EncryptInterceptorMBean`
    Parameters:
      `replayWindowTime` - The replay window time

  - ### getReplayWindowMessageCount

    public int getReplayWindowMessageCount()
    Returns the maximum number of replay entries to retain.
    Specified by:
      `getReplayWindowMessageCount` in interface `EncryptInterceptorMBean`
    Returns:
      The replay window message count

  - ### setReplayWindowMessageCount

    public void setReplayWindowMessageCount(int replayWindowMessageCount)
    Sets the maximum number of replay entries to retain.
    Specified by:
      `setReplayWindowMessageCount` in interface `EncryptInterceptorMBean`
    Parameters:
      `replayWindowMessageCount` - The replay window message count