You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by bu...@apache.org on 2016/02/13 12:50:08 UTC
svn commit: r980309 - in /websites/staging/mina/trunk/content: ./
mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.html
mina-project/userguide/images/TLS-unwrap.graphml
mina-project/userguide/images/TLS-unwrap.png
Author: buildbot
Date: Sat Feb 13 11:50:08 2016
New Revision: 980309
Log:
Staging update by buildbot for mina
Added:
websites/staging/mina/trunk/content/mina-project/userguide/images/TLS-unwrap.graphml (with props)
websites/staging/mina/trunk/content/mina-project/userguide/images/TLS-unwrap.png (with props)
Modified:
websites/staging/mina/trunk/content/ (props changed)
websites/staging/mina/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.html
Propchange: websites/staging/mina/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sat Feb 13 11:50:08 2016
@@ -1 +1 @@
-1730187
+1730188
Modified: websites/staging/mina/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.html
==============================================================================
--- websites/staging/mina/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.html (original)
+++ websites/staging/mina/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.html Sat Feb 13 11:50:08 2016
@@ -184,6 +184,12 @@ h2:hover > .headerlink, h3:hover > .head
<h1 id="chapter-11-ssl-filter">Chapter 11 - SSL Filter<a class="headerlink" href="#chapter-11-ssl-filter" title="Permanent link">¶</a></h1>
<p>The <strong>SslFilter</strong> is the filter in charge of managing the encryption and decryption of data sent through a secured connection. Whenever you need to establish a secured connection, or to transform an existing connection to make it secure, you have to add the <strong>SslFilter</strong> in your filter chain.</p>
<p>As any session can modify it's message filter chain at will, it allows for protocols like <strong>startTLS</strong> to be used on an opened connection.</p>
+<DIV class="note" markdown="1">
+Please note that although the name include <strong>SSL</strong>, <strong>SslFilter</strong> supports <strong>TLS</strong>.
+
+Actually, <strong>TLS</strong> is supposed to have replaced <strong>SSL</strong>, but for historical reason, <strong>SSL</strong> remains widely used.
+</DIV>
+
<h2 id="basic-usage">Basic usage<a class="headerlink" href="#basic-usage" title="Permanent link">¶</a></h2>
<p>If you want your application to support <strong>SSL/TLS</strong>, just add the <strong>SslFilter</strong> in your chain :</p>
<div class="codehilite"><pre><span class="p">...</span>
@@ -219,7 +225,6 @@ h2:hover > .headerlink, h3:hover > .head
<p>We are not going to explain how <strong>SSL</strong> works, there are very <a href="http://www.amazon.com/SSL-TLS-Designing-Building-Systems/dp/0201615983">good books</a> outhere. We will just give a quick introduction on how it works and how it is implemented in MINA.</p>
<p>First of all, you have to understand that <strong>SSL/TLS</strong> is a protocol defined in <strong>RFCs</strong> : <a href="https://www.rfc-editor.org/rfc/rfc2246.txt">TLS 1.0</a>, <a href="https://www.rfc-editor.org/rfc/rfc4346.txt">TLS 1.1</a> and <a href="https://www.rfc-editor.org/rfc/rfc5246.txt">TLS 1.2</a>. There is a <a href="https://tlswg.github.io/tls13-spec/">TLS 1.3</a> draft being worked on...</p>
<p>It was initially developed by <strong>Netscape</strong>, and named <strong>SSL</strong> (from 1.0 to 3.0), before becoming <strong>TLS</strong>. Nowadays, <strong><em>SSL 2.0</em>* and </strong>SSL 3.0** have been deprecated and should not be used.</p>
-<p>Please note that although the name include SSL, <strong>SslFilter</strong> supports TLS.</p>
<h3 id="the-ssltls-protocol">The SSL/TLS protocol<a class="headerlink" href="#the-ssltls-protocol" title="Permanent link">¶</a></h3>
<p>As it's a protocol, it requires some dialog between a client and a server. This is all what <strong>SSL/TLS</strong> is about : describing this dialog. </p>
<p>It's enough to know that any secured exchange is precluded by a negociation phase, called the <strong>Handshake</strong>, which role is to come to an agreement between the client and the server on what will be the encryption method to use. A basic <strong>SSL/TLS</strong> session will be something that looks like :</p>
@@ -258,6 +263,89 @@ h2:hover > .headerlink, h3:hover > .head
<img src="../images/TLS-inMessage.png" alt="Incoming message"/>
</DIV>
+<DIV class="note" markdown="1">
+What is important here is that the <strong>SslHander<strong> can't process more than one message at a time.
+</DIV
+
+## SSL/TLS in MINA 2
+
+Now, we will dive a bit deeper into **MINA** code. We will cover all the filter operations:
+* Management
+** init()
+** destroy()
+** onPreAdd(IoFilterChain, String, NextFilter)
+** onPostAdd(IoFilterChain, String, NextFilter)
+** onPreRemove(IoFilterChain, String, NextFilter)
+** onPostRemove(IoFilterChain, String, NextFilter)
+* Session events
+** sessionCreated(NextFilter, IoSession)
+** sessionOpened(NextFilter, IoSession)
+** sessionClosed(NextFilter, IoSession)
+** sessionIdle(NextFilter, IoSession, IdleStatus)
+** exceptionCaught(NextFilter, IoSession, Throwable)
+** filterClose(NextFilter, IoSession)
+** inputClosed(NextFilter, IoSession)
+* Messages events
+** messageReceived(NextFilter, IoSession, Object)
+** filterWrite(NextFilter, IoSession, WriteRequest)
+** messageSent(NextFilter, IoSession, WriteRequest)
+
+
+### messageReceived event
+
+This event is received when we read some data from the socket. We have to take care of a few corner cases :
+* The handshake has been completed
+* The handshake has been started but is not completed
+* No handshake has started, and the **SslHandler** is not yet initialized
+
+Those three use cases are listed by order of frequency. Let's see what is going to happen for each of those use cases.
+
+#### The handshake has been completed
+
+Good ! That means every incoming message is encapsulated in a **SSL/TLS** envelop, and should be decrypted. Now, we are talking about messages, but we actually receive bytes, that may need to be aggregated to form a full message (at least in **TCP**). If a message is fragmented, we will receive many buffers, and we will be able to decrypt it fully when we will receive the last piece. Remember that we are blocked during all the process, which can block the **SslHandler** instance for this session for quite some time...
+
+In any case, every block of data is processed by the **SslHandler**, which delegates to the **SslEngine** the decryption of the bytes it received.
+
+Here is the basic algorithm we have implemented in *messageReceived()* :
+
+ get the session's sslHandler
+
+ syncrhonized on sshHandler {
+ if handshake completed
+ then
+ get the sslHandler decrypting the data
+ if the application buffer is completed, push it into the message to forward to the IoHandler
+ else
+ enqueue the incoming data
+ }
+
+ flush the messages if any
+
+The important part here is that the **SslHandler** will cumulate the data until it has a complete message to push into the chain. This may take a while, and many socket reads. The reason is that the **SSLEngine** cannot process a message unless it has all the bytes deended to decode the message fully.
+
+<DIV class="note" markdown="1">
+<strong>Tip</strong> : increase the transmission buffer size to limit the number of round trips necessary to send a big message.
+</DIV>
+
+#### The handshake has not been completed
+
+The means the received message is part of the Handshake protocol. Nothing will be propagated to the **IoHandler**, the message will be consumed by the **SslHandler**.
+
+Until the full handshake is completed, every incoming data will be considered as a Handshake protocl message.
+
+At the same time, messages that the **IoHandler** will be enqueued, waiting for the Handshake to be completed.
+
+Here is a schema representing the full process when the data are received in two round-trips :
+
+<DIV align="center">
+ <img src="../images/TLS-unwrap.png" alt="Unwrapping message"/>
+</DIV>
+
+
+### filterwWrite event
+
+This event is processed when the **IoSession.write()** method is called.
+
<div class="nav">
<div class="nav_prev">
Added: websites/staging/mina/trunk/content/mina-project/userguide/images/TLS-unwrap.graphml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/mina/trunk/content/mina-project/userguide/images/TLS-unwrap.graphml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/mina/trunk/content/mina-project/userguide/images/TLS-unwrap.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/mina/trunk/content/mina-project/userguide/images/TLS-unwrap.png
------------------------------------------------------------------------------
svn:mime-type = image/png