It makes use of the JSSE framework, and specifically the SSLEngine logic, which is
described by Oracle as "an advanced API, not appropriate for casual use", since it requires the
user to implement much of the communication establishment procedure himself. More information
about it can be found here: http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#SSLEngine
SSLSocketChannel implements the handshake protocol, required to establish a connection
between two peers, which is common for both client and server and provides the abstract SSLSocketChannel#read(ByteBuffer) and SSLSocketChannel#write(ByteBuffer) (String)}
methods, that need to be implemented by the specific SSL/TLS peer that is going to extend this
class.
Modified by marci4 to allow the usage as a ByteChannel
Permission for usage received at May 25, 2017 by Alex Karnezis
| Modifier and Type | Field and Description |
|---|---|
| private final SSLEngine | engine
The engine which will be used for un-/wrapping of buffers |
| private ExecutorService | executor
Will be used to execute tasks that may emerge during handshake in parallel with the server's main thread. |
| private final Logger | log
Logger instance |
| private ByteBuffer | myAppData
Will contain this peer's application data in plaintext, that will be later encrypted using
|
| private ByteBuffer | myNetData
Will contain this peer's encrypted data, that will be generated after |
| private ByteBuffer | peerAppData
Will contain the other peer's (decrypted) application data. |
| private ByteBuffer | peerNetData
Will contain the other peer's encrypted data. |
| private final SocketChannel | socketChannel
The underlying socket channel |
| Access | Constructor and Description |
|---|---|
| public | SSLSocketChannel(SocketChannel inputSocketChannel, SSLEngine inputEngine, ExecutorService inputExecutor, SelectionKey key)
|
| Modifier and Type | Method and Description |
|---|---|
| public void | |
| private void | closeConnection()
This method should be called when this peer wants to explicitly close the connection or when a close message has arrived from the other peer, in order to provide an orderly shutdown. |
| private boolean | Returns: True if the connection handshake was successful or false if an error occurred.Implements the handshake protocol between two peers, required for the establishment of the SSL/TLS connection. |
| private ByteBuffer | Returns: the enlarged bufferthe buffer to enlarge buffer)Enlarging a packet buffer (peerAppData or myAppData) |
| private ByteBuffer | Returns: A new buffer with a larger capacity.- the buffer to be enlarged. buffer, int - the minimum size of the new buffer, proposed by sessionProposedCapacity)SSLSession.Compares sessionProposedCapacity with buffer's capacity. |
| private ByteBuffer | Returns: the enlarged bufferthe buffer to enlarge buffer)Enlarging a packet buffer (peerNetData or myNetData) |
| public SSLEngine | getSSLEngine()
Implements org. Get the ssl engine used for the de- and encryption of the communication. |
| private ByteBuffer | Returns: The same buffer if there is no space problem or a new buffer with the same data but more space.- will always be peerNetData buffer. buffer) |
| private void | handleEndOfStream()
In addition to orderly shutdowns, an unorderly shutdown may occur, when the transport link (socket channel) is severed before close messages are exchanged. |
| public boolean | isBlocking()
Implements org. This function returns the blocking state of the channel |
| public boolean | isNeedRead()
Implements org. returns whether readMore should be called to fetch data which has been decoded but not yet been returned. |
| public boolean | isNeedWrite()
Implements org. returns whether writeMore should be called write additional data. |
| public boolean | |
| public synchronized int | read(ByteBuffer dst)
Implements java. Reads a sequence of bytes from this channel into the given buffer. |
| public int | readMore(ByteBuffer dst)
Implements org. This function does not read data from the underlying channel at all. |
| public synchronized int | write(ByteBuffer output)
Implements java. Writes a sequence of bytes to this channel from the given buffer. |
| public void | writeMore()
Implements org. Gets called when |
| engine | back to summary |
|---|---|
| private final SSLEngine engine The engine which will be used for un-/wrapping of buffers | |
| executor | back to summary |
|---|---|
| private ExecutorService executor Will be used to execute tasks that may emerge during handshake in parallel with the server's main thread. | |
| log | back to summary |
|---|---|
| private final Logger log Logger instance
| |
| myAppData | back to summary |
|---|---|
| private ByteBuffer myAppData Will contain this peer's application data in plaintext, that will be later encrypted using
| |
| myNetData | back to summary |
|---|---|
| private ByteBuffer myNetData Will contain this peer's encrypted data, that will be generated after | |
| peerAppData | back to summary |
|---|---|
| private ByteBuffer peerAppData Will contain the other peer's (decrypted) application data. It must be large enough to hold the
application data from any peer. Can be initialized with | |
| peerNetData | back to summary |
|---|---|
| private ByteBuffer peerNetData Will contain the other peer's encrypted data. The SSL/TLS protocols specify that
implementations should produce packets containing at most 16 KB of plaintext, so a buffer sized
to this value should normally cause no capacity problems. However, some implementations violate
the specification and generate large records up to 32 KB. If the | |
| socketChannel | back to summary |
|---|---|
| private final SocketChannel socketChannel The underlying socket channel | |
| SSLSocketChannel | back to summary |
|---|---|
| public SSLSocketChannel(SocketChannel inputSocketChannel, SSLEngine inputEngine, ExecutorService inputExecutor, SelectionKey key) throws IOException | |
| close | back to summary |
|---|---|
| public void close() throws IOException Implements java. Doc from java. Closes this channel. After a channel is closed, any further attempt to invoke I/O
operations upon it will cause a If this channel is already closed then invoking this method has no effect. This method may be invoked at any time. If some other thread has already invoked it, however, then another invocation will block until the first invocation is complete, after which it will return without effect.
| |
| closeConnection | back to summary |
|---|---|
| private void closeConnection() throws IOException This method should be called when this peer wants to explicitly close the connection or when a close message has arrived from the other peer, in order to provide an orderly shutdown.
It first calls
| |
| doHandshake | back to summary |
|---|---|
| private boolean doHandshake() throws IOException Implements the handshake protocol between two peers, required for the establishment of the SSL/TLS connection. During the handshake, encryption configuration information - such as the list of available cipher suites - will be exchanged and if the handshake is successful will lead to an established SSL/TLS session.
A typical handshake will usually contain the following steps:
Handshake is also used during the end of the session, in order to properly close the connection between the two peers. A proper connection close will typically include the one peer sending a CLOSE message to another, and then wait for the other's CLOSE message to close the transport link. The other peer from his perspective would read a CLOSE message from his peer and then enter the handshake procedure to send his own CLOSE message as well.
| |
| enlargeApplicationBuffer | back to summary |
|---|---|
| private ByteBuffer enlargeApplicationBuffer(ByteBuffer buffer) Enlarging a packet buffer (peerAppData or myAppData)
| |
| enlargeBuffer | back to summary |
|---|---|
| private ByteBuffer enlargeBuffer(ByteBuffer buffer, int sessionProposedCapacity) Compares sessionProposedCapacity with buffer's capacity. If buffer's capacity is smaller, returns a buffer with the proposed capacity. If it's equal or larger, returns a buffer with capacity twice the size of the initial one.
| |
| enlargePacketBuffer | back to summary |
|---|---|
| private ByteBuffer enlargePacketBuffer(ByteBuffer buffer) Enlarging a packet buffer (peerNetData or myNetData)
| |
| getSSLEngine | back to summary |
|---|---|
| public SSLEngine getSSLEngine() Implements org. Doc from org. Get the ssl engine used for the de- and encryption of the communication.
| |
| handleBufferUnderflow | back to summary |
|---|---|
| private ByteBuffer handleBufferUnderflow(ByteBuffer buffer) Handles
| |
| handleEndOfStream | back to summary |
|---|---|
| private void handleEndOfStream() throws IOException In addition to orderly shutdowns, an unorderly shutdown may occur, when the transport link
(socket channel) is severed before close messages are exchanged. This may happen by getting an
-1 or
| |
| isBlocking | back to summary |
|---|---|
| public boolean isBlocking() Implements org. Doc from org. This function returns the blocking state of the channel
| |
| isNeedRead | back to summary |
|---|---|
| public boolean isNeedRead() Implements org. Doc from org. returns whether readMore should be called to fetch data which has been decoded but not yet been returned.
| |
| isNeedWrite | back to summary |
|---|---|
| public boolean isNeedWrite() Implements org. Doc from org. returns whether writeMore should be called write additional data.
| |
| isOpen | back to summary |
|---|---|
| public boolean isOpen() Implements java. Doc from java. Tells whether or not this channel is open.
| |
| read | back to summary |
|---|---|
| public synchronized int read(ByteBuffer dst) throws IOException Implements java. Doc from java. Reads a sequence of bytes from this channel into the given buffer. An attempt is made to read up to r bytes from the channel,
where r is the number of bytes remaining in the buffer, that is,
Suppose that a byte sequence of length n is read, where
A read operation might not fill the buffer, and in fact it might not read any bytes at all. Whether or not it does so depends upon the nature and state of the channel. A socket channel in non-blocking mode, for example, cannot read any more bytes than are immediately available from the socket's input buffer; similarly, a file channel cannot read any more bytes than remain in the file. It is guaranteed, however, that if a channel is in blocking mode and there is at least one byte remaining in the buffer then this method will block until at least one byte is read. This method may be invoked at any time. If another thread has already initiated a read operation upon this channel, however, then an invocation of this method will block until the first operation is complete.
| |
| readMore | back to summary |
|---|---|
| public int readMore(ByteBuffer dst) throws IOException Implements org. Doc from org. This function does not read data from the underlying channel at all. It is just a way to fetch
data which has already be received or decoded but was but was not yet returned to the user.
This could be the case when the decoded data did not fit into the buffer the user passed to
| |
| write | back to summary |
|---|---|
| public synchronized int write(ByteBuffer output) throws IOException Implements java. Doc from java. Writes a sequence of bytes to this channel from the given buffer. An attempt is made to write up to r bytes to the channel,
where r is the number of bytes remaining in the buffer, that is,
Suppose that a byte sequence of length n is written, where
Unless otherwise specified, a write operation will return only after writing all of the r requested bytes. Some types of channels, depending upon their state, may write only some of the bytes or possibly none at all. A socket channel in non-blocking mode, for example, cannot write any more bytes than are free in the socket's output buffer. This method may be invoked at any time. If another thread has already initiated a write operation upon this channel, however, then an invocation of this method will block until the first operation is complete.
| |
| writeMore | back to summary |
|---|---|
| public void writeMore() throws IOException Implements org. Doc from org. Gets called when
| |