SecureNioChannel (Apache Tomcat 11.0.24 API Documentation)
Description: declaration: package: org.apache.tomcat.util.net, class: SecureNioChannel

# Class SecureNioChannel

java.lang.Object
org.apache.tomcat.util.net.NioChannel
org.apache.tomcat.util.net.SecureNioChannel

All Implemented Interfaces:
  `Closeable, AutoCloseable, ByteChannel, Channel, GatheringByteChannel, ReadableByteChannel, ScatteringByteChannel, WritableByteChannel`

public class SecureNioChannel extends NioChannel
Implementation of a secure socket channel

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected boolean`
  `closed`
  True when the channel is closed
  `protected boolean`
  `closing`
  True when the channel is in the process of closing
  `protected boolean`
  `handshakeComplete`
  True when the SSL handshake is complete
  `protected SSLEngineResult.HandshakeStatus`
  `handshakeStatus`
  Current handshake status, updated during handshake processing
  `protected boolean`
  `needHandshakeWrap`
  True when a handshake wrap is pending
  `protected ByteBuffer`
  `netInBuffer`
  Network input buffer for encrypted data
  `protected ByteBuffer`
  `netOutBuffer`
  Network output buffer for encrypted data
  `protected boolean`
  `sniComplete`
  True when SNI processing is complete
  `protected SSLEngine`
  `sslEngine`
  SSL engine for this channel

  ### Fields inherited from class NioChannel

  `bufHandler, emptyBuf, sc, socketWrapper`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SecureNioChannel(SocketBufferHandler bufHandler, NioEndpoint endpoint)`
  Creates a new secure NIO channel.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Sends an SSL close message, will not physically close the connection here.
  `void`
  `close(boolean force)`
  Close the connection.
  `protected void`
  `createSSLEngine(String hostName, List<Cipher> clientRequestedCiphers, List<String> clientRequestedApplicationProtocols, List<String> clientRequestedProtocols, List<Group> clientSupportedGroups, List<SignatureScheme> clientSignatureSchemes)`
  Creates and initializes the SSL engine for this channel.
  `protected boolean`
  `flush(ByteBuffer buf)`
  Flushes the buffer to the network, non-blocking
  `boolean`
  `flushOutbound()`
  Return true if the buffer wrote data.
  `void`
  `free()`
  Free the channel memory
  `ByteBuffer`
  `getEmptyBuf()`
  Returns an empty byte buffer used for SSL wrap operations.
  `int`
  `getOutboundRemaining()`
  Returns the number of bytes remaining in the outbound buffer.
  `SSLEngine`
  `getSslEngine()`
  Returns the SSL engine for this channel.
  `SSLSupport`
  `getSSLSupport()`
  Returns the SSL support object for this channel, or `null` if the SSL engine has not been initialized.
  `int`
  `handshake(boolean read, boolean write)`
  Performs SSL handshake, non-blocking, but performs NEED_TASK on the same thread.
  `protected SSLEngineResult`
  `handshakeUnwrap(boolean doread)`
  Perform handshake unwrap
  `protected SSLEngineResult`
  `handshakeWrap(boolean doWrite)`
  Performs the WRAP function
  `boolean`
  `isClosing()`
  Indicates whether the channel is in the process of closing.
  `boolean`
  `isHandshakeComplete()`
  Indicates whether the SSL handshake is complete.
  `protected int`
  `processSNI()`
  Peeks at the initial network bytes to determine if the SNI extension is present and, if it is, what host name has been requested.
  `int`
  `read(ByteBuffer dst)`
  Reads a sequence of bytes from this channel into the given buffer.
  `long`
  `read(ByteBuffer[] dsts, int offset, int length)`
  `void`
  `rehandshake(long timeout)`
  Force a blocking handshake to take place for this key.
  `void`
  `reset(SocketChannel channel, NioEndpoint.NioSocketWrapper socketWrapper)`
  Reset the channel
  `protected SSLEngineResult.HandshakeStatus`
  `tasks()`
  Executes all the tasks needed on the same thread.
  `int`
  `write(ByteBuffer src)`
  Writes a sequence of bytes to this channel from the given buffer.
  `long`
  `write(ByteBuffer[] srcs, int offset, int length)`

  ### Methods inherited from class NioChannel

  `checkInterruptStatus, getAppReadBufHandler, getBufHandler, getIOChannel, isOpen, read, setAppReadBufHandler, toString, write`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### netInBuffer

    protected ByteBuffer netInBuffer
    Network input buffer for encrypted data

  - ### netOutBuffer

    protected ByteBuffer netOutBuffer
    Network output buffer for encrypted data

  - ### sslEngine

    protected SSLEngine sslEngine
    SSL engine for this channel

  - ### sniComplete

    protected boolean sniComplete
    True when SNI processing is complete

  - ### handshakeComplete

    protected boolean handshakeComplete
    True when the SSL handshake is complete

  - ### needHandshakeWrap

    protected boolean needHandshakeWrap
    True when a handshake wrap is pending

  - ### handshakeStatus

    protected SSLEngineResult.HandshakeStatus handshakeStatus
    Current handshake status, updated during handshake processing

  - ### closed

    protected boolean closed
    True when the channel is closed

  - ### closing

    protected boolean closing
    True when the channel is in the process of closing

- ## Constructor Details

  - ### SecureNioChannel

    public SecureNioChannel(SocketBufferHandler bufHandler, NioEndpoint endpoint)
    Creates a new secure NIO channel.
    Parameters:
      `bufHandler` - Buffer handler for the application buffers
      `endpoint` - The NIO endpoint managing this channel

- ## Method Details

  - ### reset

    public void reset(SocketChannel channel, NioEndpoint.NioSocketWrapper socketWrapper) throws IOException
    Description copied from class: `NioChannel`
    Reset the channel
    Overrides:
      `reset` in class `NioChannel`
    Parameters:
      `channel` - the socket channel
      `socketWrapper` - the socket wrapper
    Throws:
      `IOException` - If a problem was encountered resetting the channel

  - ### free

    public void free()
    Description copied from class: `NioChannel`
    Free the channel memory
    Overrides:
      `free` in class `NioChannel`

  - ### flush

    protected boolean flush(ByteBuffer buf) throws IOException
    Flushes the buffer to the network, non-blocking
    Parameters:
      `buf` - ByteBuffer
    Returns:
      boolean true if the buffer has been emptied out, false otherwise
    Throws:
      `IOException` - An IO error occurred writing data

  - ### handshake

    public int handshake(boolean read, boolean write) throws IOException
    Performs SSL handshake, non-blocking, but performs NEED_TASK on the same thread. Hence, you should never call this method using your Acceptor thread, as you would slow down your system significantly. If the return value from this method is positive, the selection key should be registered interestOps given by the return value.
    Overrides:
      `handshake` in class `NioChannel`
    Parameters:
      `read` - boolean - true if the underlying channel is readable
      `write` - boolean - true if the underlying channel is writable
    Returns:
      0 if handshake is complete, -1 if an error (other than an IOException) occurred, otherwise it returns a SelectionKey interestOps value
    Throws:
      `IOException` - If an I/O error occurs during the handshake or if the handshake fails during wrapping or unwrapping

  - ### processSNI

    protected int processSNI() throws IOException
    Peeks at the initial network bytes to determine if the SNI extension is present and, if it is, what host name has been requested. Based on the provided host name, configure the SSLEngine for this connection.
    Returns:
      0 if SNI processing is complete, -1 if an error (other than an IOException) occurred, otherwise it returns a SelectionKey interestOps value
    Throws:
      `IOException` - If an I/O error occurs during the SNI processing

  - ### rehandshake

    public void rehandshake(long timeout) throws IOException
    Force a blocking handshake to take place for this key. This requires that both network and application buffers have been emptied out prior to this call taking place, or a IOException will be thrown.
    Parameters:
      `timeout` - - timeout in milliseconds for each socket operation
    Throws:
      `IOException` - - if an IO exception occurs or if application or network buffers contain data
      `SocketTimeoutException` - - if a socket operation timed out

  - ### tasks

    protected SSLEngineResult.HandshakeStatus tasks()
    Executes all the tasks needed on the same thread.
    Returns:
      the status

  - ### handshakeWrap

    protected SSLEngineResult handshakeWrap(boolean doWrite) throws IOException
    Performs the WRAP function
    Parameters:
      `doWrite` - boolean
    Returns:
      the result
    Throws:
      `IOException` - An IO error occurred

  - ### handshakeUnwrap

    protected SSLEngineResult handshakeUnwrap(boolean doread) throws IOException
    Perform handshake unwrap
    Parameters:
      `doread` - boolean
    Returns:
      the result
    Throws:
      `IOException` - An IO error occurred

  - ### getSSLSupport

    public SSLSupport getSSLSupport()
    Returns the SSL support object for this channel, or `null` if the SSL engine has not been initialized.
    Returns:
      the SSL support object, or `null`

  - ### close

    public void close() throws IOException
    Sends an SSL close message, will not physically close the connection here.
    To close the connection, you could do something like

          close();
          while (isOpen() && !myTimeoutFunction()) Thread.sleep(25);
          if ( isOpen() ) close(true); //forces a close if you timed out

    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Channel`
    Specified by:
      `close` in interface `Closeable`
    Overrides:
      `close` in class `NioChannel`
    Throws:
      `IOException` - if an I/O error occurs
      `IOException` - if there is data on the outgoing network buffer, and we are unable to flush it

  - ### close

    public void close(boolean force) throws IOException
    Description copied from class: `NioChannel`
    Close the connection.
    Overrides:
      `close` in class `NioChannel`
    Parameters:
      `force` - Should the underlying socket be forcibly closed?
    Throws:
      `IOException` - If closing the secure channel fails.

  - ### read

    public int read(ByteBuffer dst) throws IOException
    Reads a sequence of bytes from this channel into the given buffer.
    Specified by:
      `read` in interface `ReadableByteChannel`
    Overrides:
      `read` in class `NioChannel`
    Parameters:
      `dst` - The buffer into which bytes are to be transferred
    Returns:
      The number of bytes read, possibly zero, or `-1` if the channel has reached end-of-stream
    Throws:
      `IOException` - If some other I/O error occurs
      `IllegalStateException` - if the handshake was not completed

  - ### read

    public long read(ByteBuffer[] dsts, int offset, int length) throws IOException
    Specified by:
      `read` in interface `ScatteringByteChannel`
    Overrides:
      `read` in class `NioChannel`
    Throws:
      `IOException`

  - ### write

    public int write(ByteBuffer src) throws IOException
    Writes a sequence of bytes to this channel from the given buffer.
    Specified by:
      `write` in interface `WritableByteChannel`
    Overrides:
      `write` in class `NioChannel`
    Parameters:
      `src` - The buffer from which bytes are to be retrieved
    Returns:
      The number of bytes written, possibly zero
    Throws:
      `IOException` - If some other I/O error occurs

  - ### write

    public long write(ByteBuffer[] srcs, int offset, int length) throws IOException
    Specified by:
      `write` in interface `GatheringByteChannel`
    Overrides:
      `write` in class `NioChannel`
    Throws:
      `IOException`

  - ### getOutboundRemaining

    public int getOutboundRemaining()
    Description copied from class: `NioChannel`
    Returns the number of bytes remaining in the outbound buffer.
    Overrides:
      `getOutboundRemaining` in class `NioChannel`
    Returns:
      Always returns 0 for non-secure channels

  - ### flushOutbound

    public boolean flushOutbound() throws IOException
    Description copied from class: `NioChannel`
    Return true if the buffer wrote data. NO-OP for non-secure channel.
    Overrides:
      `flushOutbound` in class `NioChannel`
    Returns:
      Always returns `false` for non-secure channel
    Throws:
      `IOException` - Never for non-secure channel

  - ### isHandshakeComplete

    public boolean isHandshakeComplete()
    Description copied from class: `NioChannel`
    Indicates whether the SSL handshake is complete.
    Overrides:
      `isHandshakeComplete` in class `NioChannel`
    Returns:
      `true` for non-secure channels (no handshake required)

  - ### isClosing

    public boolean isClosing()
    Description copied from class: `NioChannel`
    Indicates whether the channel is in the process of closing.
    Overrides:
      `isClosing` in class `NioChannel`
    Returns:
      `false` for non-secure channels

  - ### getSslEngine

    public SSLEngine getSslEngine()
    Returns the SSL engine for this channel.
    Returns:
      the SSL engine, or `null` if not yet created

  - ### getEmptyBuf

    public ByteBuffer getEmptyBuf()
    Returns an empty byte buffer used for SSL wrap operations.
    Returns:
      an empty byte buffer

  - ### createSSLEngine

    protected void createSSLEngine(String hostName, List<Cipher> clientRequestedCiphers, List<String> clientRequestedApplicationProtocols, List<String> clientRequestedProtocols, List<Group> clientSupportedGroups, List<SignatureScheme> clientSignatureSchemes)
    Creates and initializes the SSL engine for this channel.
    Parameters:
      `hostName` - The SNI host name
      `clientRequestedCiphers` - List of ciphers requested by the client
      `clientRequestedApplicationProtocols` - List of application protocols requested by the client
      `clientRequestedProtocols` - List of protocol versions requested by the client
      `clientSupportedGroups` - List of supported groups from the client
      `clientSignatureSchemes` - List of signature schemes from the client