SSLIOSession

java.lang.Object
- org.apache.http.nio.reactor.ssl.SSLIOSession

All Implemented Interfaces:: IOSession, SessionBufferStatus, SocketAccessor

Direct Known Subclasses:: SSLIOSession

@Contract(threading=SAFE_CONDITIONAL)
public class SSLIOSession
extends java.lang.Object
implements IOSession, SessionBufferStatus, SocketAccessor

SSLIOSession is a decorator class intended to transparently extend an IOSession with transport layer security capabilities based on the SSL/TLS protocol.

The resultant instance of SSLIOSession must be added to the original I/O session as an attribute with the SESSION_KEY key.

  SSLContext sslContext = SSLContext.getInstance("SSL");
  sslContext.init(null, null, null);
  SSLIOSession sslsession = new SSLIOSession(
      iosession, SSLMode.CLIENT, sslContext, null);
  iosession.setAttribute(SSLIOSession.SESSION_KEY, sslsession);

Since:: 4.2

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

private class SSLIOSession.InternalByteChannel

Nested Classes
Modifier and Type	Class and Description
`private class`	`SSLIOSession.InternalByteChannel`

Field Summary

Fields
Modifier and Type	Field and Description
`private SessionBufferStatus`	`appBufferStatus`
`private int`	`appEventMask`
`private SSLIOSession.InternalByteChannel`	`channel`
`private static java.nio.ByteBuffer`	`EMPTY_BUFFER`
`private boolean`	`endOfStream`
`private SSLSetupHandler`	`handler`
`private SSLBuffer`	`inEncrypted`
`private boolean`	`initialized`
`private SSLBuffer`	`inPlain`
`private SSLBuffer`	`outEncrypted`
`private IOSession`	`session`
`static java.lang.String`	`SESSION_KEY` Name of the context attribute key, which can be used to obtain the SSL session.
`private javax.net.ssl.SSLEngine`	`sslEngine`
`private SSLMode`	`sslMode`
`private int`	`status`

Fields inherited from interface org.apache.http.nio.reactor.IOSession
ACTIVE, ATTACHMENT_KEY, CLOSED, CLOSING

Constructor Summary

Constructors
Constructor and Description
`SSLIOSession(IOSession session, SSLMode sslMode, HttpHost host, javax.net.ssl.SSLContext sslContext, SSLSetupHandler handler)` Creates new instance of `SSLIOSession` class.
`SSLIOSession(IOSession session, SSLMode sslMode, HttpHost host, javax.net.ssl.SSLContext sslContext, SSLSetupHandler handler, SSLBufferManagementStrategy bufferManagementStrategy)` Creates new instance of `SSLIOSession` class.
`SSLIOSession(IOSession session, SSLMode sslMode, javax.net.ssl.SSLContext sslContext, SSLSetupHandler handler)` Creates new instance of `SSLIOSession` class.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`java.nio.channels.ByteChannel`	`channel()` Returns the underlying I/O channel associated with this session.
`void`	`clearEvent(int op)` Clears interest in a particular I/O event type by updating the event mask associated with the session.
`void`	`close()` Terminates the session gracefully and closes the underlying I/O channel.
`private javax.net.ssl.SSLException`	`convert(java.lang.RuntimeException ex)`
`private boolean`	`decryptData()`
`private void`	`doHandshake()`
`private void`	`doRunTask()`
`private javax.net.ssl.SSLEngineResult`	`doUnwrap(java.nio.ByteBuffer src, java.nio.ByteBuffer dst)`
`private javax.net.ssl.SSLEngineResult`	`doWrap(java.nio.ByteBuffer src, java.nio.ByteBuffer dst)`
`private static void`	`formatOps(java.lang.StringBuilder buffer, int ops)`
`java.lang.Object`	`getAttribute(java.lang.String name)` Returns the value of the attribute with the given name.
`int`	`getEventMask()` Returns mask of I/O evens this session declared interest in.
`java.net.SocketAddress`	`getLocalAddress()` Returns local address.
`java.net.SocketAddress`	`getRemoteAddress()` Returns address of the remote peer.
`java.net.Socket`	`getSocket()` Return the underlying socket
`int`	`getSocketTimeout()` Returns value of the socket timeout in milliseconds.
`javax.net.ssl.SSLSession`	`getSSLSession()`
`protected SSLSetupHandler`	`getSSLSetupHandler()`
`int`	`getStatus()` Returns status of the session:
`boolean`	`hasBufferedInput()` Determines if the input buffer associated with the session contains data.
`boolean`	`hasBufferedOutput()` Determines if the output buffer associated with the session contains data.
`void`	`inboundTransport()` Executes inbound SSL transport operations.
`void`	`initialize()` Initializes the session.
`void`	`initialize(SSLMode sslMode)` Deprecated. (4.3) SSL mode must be set at construction time.
`boolean`	`isAppInputReady()` Reads encrypted data and returns whether the channel associated with this session has any decrypted inbound data available for reading.
`boolean`	`isAppOutputReady()` Returns whether the channel associated with this session is ready to accept outbound unecrypted data for writing.
`boolean`	`isClosed()` Determines if the session has been terminated.
`boolean`	`isInboundDone()` Returns whether the session will produce any more inbound data.
`boolean`	`isInitialized()` Returns `true` is the session has been fully initialized, `false` otherwise.
`boolean`	`isOutboundDone()` Returns whether the session will accept any more outbound data.
`void`	`outboundTransport()` Sends encrypted data and executes outbound SSL transport operations.
`private int`	`readPlain(java.nio.ByteBuffer dst)`
`private int`	`receiveEncryptedData()`
`java.lang.Object`	`removeAttribute(java.lang.String name)` Removes attribute with the given name.
`private int`	`sendEncryptedData()`
`void`	`setAttribute(java.lang.String name, java.lang.Object obj)` This method can be used to associate a particular object with the session by the given attribute name.
`void`	`setBufferStatus(SessionBufferStatus status)` Quite often I/O sessions need to maintain internal I/O buffers in order to transform input / output data prior to returning it to the consumer or writing it to the underlying channel.
`void`	`setEvent(int op)` Declares interest in a particular I/O event type by updating the event mask associated with the session.
`void`	`setEventMask(int ops)` Declares interest in I/O event notifications by setting the event mask associated with the session
`void`	`setSocketTimeout(int timeout)` Sets value of the socket timeout in milliseconds.
`void`	`shutdown()` Terminates the session by shutting down the underlying I/O channel.
`java.lang.String`	`toString()`
`private void`	`updateEventMask()`
`private int`	`writePlain(java.nio.ByteBuffer src)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - SESSION_KEY
```
public static final java.lang.String SESSION_KEY
```
    Name of the context attribute key, which can be used to obtain the SSL session.
    
    See Also:
    
    Constant Field Values
  - EMPTY_BUFFER
```
private static final java.nio.ByteBuffer EMPTY_BUFFER
```
  - session
```
private final IOSession session
```
  - sslEngine
```
private final javax.net.ssl.SSLEngine sslEngine
```
  - inEncrypted
```
private final SSLBuffer inEncrypted
```
  - outEncrypted
```
private final SSLBuffer outEncrypted
```
  - inPlain
```
private final SSLBuffer inPlain
```
  - channel
```
private final SSLIOSession.InternalByteChannel channel
```
  - handler
```
private final SSLSetupHandler handler
```
  - appEventMask
```
private int appEventMask
```
  - appBufferStatus
```
private SessionBufferStatus appBufferStatus
```
  - endOfStream
```
private boolean endOfStream
```
  - sslMode
```
private volatile SSLMode sslMode
```
  - status
```
private volatile int status
```
  - initialized
```
private volatile boolean initialized
```
- Constructor Detail
  - SSLIOSession
```
public SSLIOSession(IOSession session,
                    SSLMode sslMode,
                    HttpHost host,
                    javax.net.ssl.SSLContext sslContext,
                    SSLSetupHandler handler)
```
    Creates new instance of SSLIOSession class. The instances created uses a PermanentSSLBufferManagementStrategy to manage its buffers.
    
    Parameters:
    
    session - I/O session to be decorated with the TLS/SSL capabilities.
    
    sslMode - SSL mode (client or server)
    
    host - original host (applicable in client mode only)
    
    sslContext - SSL context to use for this I/O session.
    
    handler - optional SSL setup handler. May be null.
    
    Since:
    
    4.4
  - SSLIOSession
```
public SSLIOSession(IOSession session,
                    SSLMode sslMode,
                    HttpHost host,
                    javax.net.ssl.SSLContext sslContext,
                    SSLSetupHandler handler,
                    SSLBufferManagementStrategy bufferManagementStrategy)
```
    Creates new instance of SSLIOSession class.
    
    Parameters:
    
    session - I/O session to be decorated with the TLS/SSL capabilities.
    
    sslMode - SSL mode (client or server)
    
    host - original host (applicable in client mode only)
    
    sslContext - SSL context to use for this I/O session.
    
    handler - optional SSL setup handler. May be null.
    
    bufferManagementStrategy - buffer management strategy
  - SSLIOSession
```
public SSLIOSession(IOSession session,
                    SSLMode sslMode,
                    javax.net.ssl.SSLContext sslContext,
                    SSLSetupHandler handler)
```
    Creates new instance of SSLIOSession class.
    
    Parameters:
    
    session - I/O session to be decorated with the TLS/SSL capabilities.
    
    sslMode - SSL mode (client or server)
    
    sslContext - SSL context to use for this I/O session.
    
    handler - optional SSL setup handler. May be null.
- Method Detail
  - getSSLSetupHandler
```
protected SSLSetupHandler getSSLSetupHandler()
```
  - isInitialized
```
public boolean isInitialized()
```
    Returns true is the session has been fully initialized, false otherwise.
  - initialize
```
@Deprecated
public void initialize(SSLMode sslMode)
                            throws javax.net.ssl.SSLException
```
    Deprecated. (4.3) SSL mode must be set at construction time.
    
    Initializes the session in the given SSLMode. This method invokes the SSLSetupHandler.initalize(SSLEngine) callback if an instance of SSLSetupHandler was specified at the construction time.
    
    Throws:
    
    javax.net.ssl.SSLException
  - initialize
```
public void initialize()
                throws javax.net.ssl.SSLException
```
    Initializes the session. This method invokes the SSLSetupHandler.initalize(SSLEngine) callback if an instance of SSLSetupHandler was specified at the construction time.
    
    Throws:
    
    javax.net.ssl.SSLException - in case of a SSL protocol exception.
    
    java.lang.IllegalStateException - if the session has already been initialized.
  - getSSLSession
```
public javax.net.ssl.SSLSession getSSLSession()
```
  - convert
```
private javax.net.ssl.SSLException convert(java.lang.RuntimeException ex)
```
  - doWrap
```
private javax.net.ssl.SSLEngineResult doWrap(java.nio.ByteBuffer src,
                                             java.nio.ByteBuffer dst)
                                      throws javax.net.ssl.SSLException
```
    Throws:
    
    javax.net.ssl.SSLException
  - doUnwrap
```
private javax.net.ssl.SSLEngineResult doUnwrap(java.nio.ByteBuffer src,
                                               java.nio.ByteBuffer dst)
                                        throws javax.net.ssl.SSLException
```
    Throws:
    
    javax.net.ssl.SSLException
  - doRunTask
```
private void doRunTask()
                throws javax.net.ssl.SSLException
```
    Throws:
    
    javax.net.ssl.SSLException
  - doHandshake
```
private void doHandshake()
                  throws javax.net.ssl.SSLException
```
    Throws:
    
    javax.net.ssl.SSLException
  - updateEventMask
```
private void updateEventMask()
```
  - sendEncryptedData
```
private int sendEncryptedData()
                       throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - receiveEncryptedData
```
private int receiveEncryptedData()
                          throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - decryptData
```
private boolean decryptData()
                     throws javax.net.ssl.SSLException
```
    Throws:
    
    javax.net.ssl.SSLException
  - isAppInputReady
```
public boolean isAppInputReady()
                        throws java.io.IOException
```
    Reads encrypted data and returns whether the channel associated with this session has any decrypted inbound data available for reading.
    
    Throws:
    
    java.io.IOException - in case of an I/O error.
  - isAppOutputReady
```
public boolean isAppOutputReady()
                         throws java.io.IOException
```
    Returns whether the channel associated with this session is ready to accept outbound unecrypted data for writing.
    
    Throws:
    
    java.io.IOException - - not thrown currently
  - inboundTransport
```
public void inboundTransport()
                      throws java.io.IOException
```
    Executes inbound SSL transport operations.
    
    Throws:
    
    java.io.IOException - - not thrown currently
  - outboundTransport
```
public void outboundTransport()
                       throws java.io.IOException
```
    Sends encrypted data and executes outbound SSL transport operations.
    
    Throws:
    
    java.io.IOException - in case of an I/O error.
  - isInboundDone
```
public boolean isInboundDone()
```
    Returns whether the session will produce any more inbound data.
  - isOutboundDone
```
public boolean isOutboundDone()
```
    Returns whether the session will accept any more outbound data.
  - writePlain
```
private int writePlain(java.nio.ByteBuffer src)
                throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - readPlain
```
private int readPlain(java.nio.ByteBuffer dst)
```
  - close
```
public void close()
```
    Description copied from interface: IOSession
    
    Terminates the session gracefully and closes the underlying I/O channel. This method ensures that session termination handshake, such as the one used by the SSL/TLS protocol, is correctly carried out.
    
    Specified by:
    
    close in interface IOSession
  - shutdown
```
public void shutdown()
```
    Description copied from interface: IOSession
    
    Terminates the session by shutting down the underlying I/O channel.
    
    Specified by:
    
    shutdown in interface IOSession
  - getStatus
```
public int getStatus()
```
    Description copied from interface: IOSession
    
    Returns status of the session:
    IOSession.ACTIVE: session is active.
    IOSession.CLOSING: session is being closed.
    IOSession.CLOSED: session has been terminated.
    
    Specified by:
    
    getStatus in interface IOSession
    
    Returns:
    
    session status.
  - isClosed
```
public boolean isClosed()
```
    Description copied from interface: IOSession
    
    Determines if the session has been terminated.
    
    Specified by:
    
    isClosed in interface IOSession
    
    Returns:
    
    true if the session has been terminated, false otherwise.
  - channel
```
public java.nio.channels.ByteChannel channel()
```
    Description copied from interface: IOSession
    
    Returns the underlying I/O channel associated with this session.
    
    Specified by:
    
    channel in interface IOSession
    
    Returns:
    
    the I/O channel.
  - getLocalAddress
```
public java.net.SocketAddress getLocalAddress()
```
    Description copied from interface: IOSession
    
    Returns local address.
    
    Specified by:
    
    getLocalAddress in interface IOSession
    
    Returns:
    
    socket address.
  - getRemoteAddress
```
public java.net.SocketAddress getRemoteAddress()
```
    Description copied from interface: IOSession
    
    Returns address of the remote peer.
    
    Specified by:
    
    getRemoteAddress in interface IOSession
    
    Returns:
    
    socket address.
  - getEventMask
```
public int getEventMask()
```
    Description copied from interface: IOSession
    
    Returns mask of I/O evens this session declared interest in.
    
    Specified by:
    
    getEventMask in interface IOSession
    
    Returns:
    
    I/O event mask.
  - setEventMask
```
public void setEventMask(int ops)
```
    Description copied from interface: IOSession
    
    Declares interest in I/O event notifications by setting the event mask associated with the session
    
    Specified by:
    
    setEventMask in interface IOSession
    
    Parameters:
    
    ops - new I/O event mask.
  - setEvent
```
public void setEvent(int op)
```
    Description copied from interface: IOSession
    
    Declares interest in a particular I/O event type by updating the event mask associated with the session.
    
    Specified by:
    
    setEvent in interface IOSession
    
    Parameters:
    
    op - I/O event type.
  - clearEvent
```
public void clearEvent(int op)
```
    Description copied from interface: IOSession
    
    Clears interest in a particular I/O event type by updating the event mask associated with the session.
    
    Specified by:
    
    clearEvent in interface IOSession
    
    Parameters:
    
    op - I/O event type.
  - getSocketTimeout
```
public int getSocketTimeout()
```
    Description copied from interface: IOSession
    
    Returns value of the socket timeout in milliseconds. The value of 0 signifies the session cannot time out.
    
    Specified by:
    
    getSocketTimeout in interface IOSession
    
    Returns:
    
    socket timeout.
  - setSocketTimeout
```
public void setSocketTimeout(int timeout)
```
    Description copied from interface: IOSession
    
    Sets value of the socket timeout in milliseconds. The value of 0 signifies the session cannot time out.
    
    Specified by:
    
    setSocketTimeout in interface IOSession
    
    Parameters:
    
    timeout - socket timeout.
  - hasBufferedInput
```
public boolean hasBufferedInput()
```
    Description copied from interface: IOSession
    
    Determines if the input buffer associated with the session contains data.
    
    Specified by:
    
    hasBufferedInput in interface IOSession
    
    Specified by:
    
    hasBufferedInput in interface SessionBufferStatus
    
    Returns:
    
    true if the session input buffer contains data, false otherwise.
  - hasBufferedOutput
```
public boolean hasBufferedOutput()
```
    Description copied from interface: IOSession
    
    Determines if the output buffer associated with the session contains data.
    
    Specified by:
    
    hasBufferedOutput in interface IOSession
    
    Specified by:
    
    hasBufferedOutput in interface SessionBufferStatus
    
    Returns:
    
    true if the session output buffer contains data, false otherwise.
  - setBufferStatus
```
public void setBufferStatus(SessionBufferStatus status)
```
    Description copied from interface: IOSession
    
    Quite often I/O sessions need to maintain internal I/O buffers in order to transform input / output data prior to returning it to the consumer or writing it to the underlying channel. Memory management in HttpCore NIO is based on the fundamental principle that the data consumer can read only as much input data as it can process without having to allocate more memory. That means, quite often some input data may remain unread in one of the internal or external session buffers. The I/O reactor can query the status of these session buffers, and make sure the consumer gets notified correctly as more data gets stored in one of the session buffers, thus allowing the consumer to read the remaining data once it is able to process it
    I/O sessions can be made aware of the status of external session buffers using the SessionBufferStatus interface.
    
    Specified by:
    
    setBufferStatus in interface IOSession
  - getAttribute
```
public java.lang.Object getAttribute(java.lang.String name)
```
    Description copied from interface: IOSession
    
    Returns the value of the attribute with the given name. The value can be null if not set.
    The value of the session attachment object can be obtained using IOSession.ATTACHMENT_KEY name.
    
    Specified by:
    
    getAttribute in interface IOSession
    
    Parameters:
    
    name - name of the attribute.
    
    Returns:
    
    value of the attribute.
    
    See Also:
    
    IOSession.setAttribute(String, Object)
  - removeAttribute
```
public java.lang.Object removeAttribute(java.lang.String name)
```
    Description copied from interface: IOSession
    
    Removes attribute with the given name.
    
    Specified by:
    
    removeAttribute in interface IOSession
    
    Parameters:
    
    name - name of the attribute to be removed.
    
    Returns:
    
    value of the removed attribute.
    
    See Also:
    
    IOSession.setAttribute(String, Object)
  - setAttribute
```
public void setAttribute(java.lang.String name,
                         java.lang.Object obj)
```
    Description copied from interface: IOSession
    
    This method can be used to associate a particular object with the session by the given attribute name.
    I/O sessions are not bound to an execution thread, therefore one cannot use the context of the thread to store a session's state. All details about a particular session must be stored within the session itself.
    
    Specified by:
    
    setAttribute in interface IOSession
    
    Parameters:
    
    name - name of the attribute.
    
    obj - value of the attribute.
  - formatOps
```
private static void formatOps(java.lang.StringBuilder buffer,
                              int ops)
```
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - getSocket
```
public java.net.Socket getSocket()
```
    Description copied from interface: SocketAccessor
    
    Return the underlying socket
    
    Specified by:
    
    getSocket in interface SocketAccessor
    
    Returns:
    
    - the underlying Socket, may be null.

Class SSLIOSession

Nested Class Summary

Field Summary

Fields inherited from interface org.apache.http.nio.reactor.IOSession

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SESSION_KEY

EMPTY_BUFFER

session

sslEngine

inEncrypted

outEncrypted

inPlain

channel

handler

appEventMask

appBufferStatus

endOfStream

sslMode

status

initialized

Constructor Detail

SSLIOSession

SSLIOSession

SSLIOSession

Method Detail

getSSLSetupHandler

isInitialized

initialize

initialize

getSSLSession

convert

doWrap

doUnwrap

doRunTask

doHandshake

updateEventMask

sendEncryptedData

receiveEncryptedData

decryptData

isAppInputReady

isAppOutputReady

inboundTransport

outboundTransport

isInboundDone

isOutboundDone

writePlain

readPlain

close

shutdown

getStatus

isClosed

channel

getLocalAddress

getRemoteAddress

getEventMask

setEventMask

setEvent

clearEvent

getSocketTimeout

setSocketTimeout

hasBufferedInput

hasBufferedOutput

setBufferStatus

getAttribute

removeAttribute

setAttribute

formatOps

toString

getSocket