| <!DOCTYPE html>
|
|
|
| <html lang="en">
|
| <head>
|
| <title>MINA 2.2.x vs MINA 2.1.x — Apache MINA</title>
|
|
|
| <link href="/assets/css/common.css" rel="stylesheet" type="text/css"/>
|
| <link href="/assets/css/mina.css" rel="stylesheet" type="text/css"/>
|
| </head>
|
| <body>
|
| <script src="https://www.apachecon.com/event-images/snippet.js"></script>
|
| <div id="container">
|
| <div id="header">
|
| <div id="subProjectsNavBar">
|
| <a href="/">
|
|
|
| Apache MINA Project
|
|
|
| </a>
|
| |
|
| <a href="/mina-project/">
|
|
|
| <strong>MINA</strong>
|
|
|
| </a>
|
| |
|
| <a href="/asyncweb-project/">
|
|
|
| AsyncWeb
|
|
|
| </a>
|
| |
|
| <a href="/ftpserver-project/">
|
|
|
| FtpServer
|
|
|
| </a>
|
| |
|
| <a href="/sshd-project/">
|
|
|
| SSHD
|
|
|
| </a>
|
| |
|
| <a href="/vysper-project/">
|
|
|
| Vysper
|
|
|
| </a>
|
| </div>
|
| </div>
|
|
|
|
|
| <div id="content">
|
| <div id="leftColumn">
|
| <div id="navigation">
|
| <a class="acevent" data-format="wide" data-width="170"></a>
|
| <h5>Social Networks</h5>
|
| <ul>
|
| <li><a href="https://fosstodon.org/@apachemina">Apache MINA Mastodon</a></li>
|
| </ul>
|
| <h5>Latest Downloads</h5>
|
| <ul>
|
| <li><a href="/mina-project/downloads_2_0.html">Mina 2.0.25</a></li>
|
| <li><a href="/mina-project/downloads_2_1.html">Mina 2.1.8</a></li>
|
| <li><a href="/mina-project/downloads_2_2.html">Mina 2.2.3</a></li>
|
| <li><a href="/mina-project/downloads_old.html">Mina old versions</a></li>
|
| </ul>
|
| <h5>Documentation</h5>
|
| <ul>
|
| <li><a href="/mina-project/documentation.html" class="external-link" rel="nofollow">Base documentation</a></li>
|
| <li><a href="/mina-project/userguide/user-guide-toc.html" class="external-link" rel="nofollow">User guide</a></li>
|
| <li><a href="/mina-project/2.2-vs-2.1.html" class="external-link" rel="nofollow">2.2 vs 2.1</a></li>
|
| <li><a href="/mina-project/2.1-vs-2.0.html" class="external-link" rel="nofollow">2.1 vs 2.0</a></li>
|
| <li><a href="/mina-project/features.html" class="external-link" rel="nofollow">Features</a></li>
|
| <li><a href="/mina-project/road-map.html" class="external-link" rel="nofollow">Road Map</a></li>
|
| <li><a href="/mina-project/quick-start-guide.html" class="external-link" rel="nofollow">Quick Start Guide</a></li>
|
| <li><a href="/mina-project/faq.html" class="external-link" rel="nofollow">FAQ</a></li>
|
| </ul>
|
| <h5>Resources</h5>
|
| <ul>
|
| <li><a href="/mina-project/mailing-lists.html" class="external-link" rel="nofollow">Mailing lists & IRC</a></li>
|
| <li><a href="/mina-project/issue-tracking.html" class="external-link" rel="nofollow">Issue tracking</a></li>
|
| <li><a href="/mina-project/sources.html" class="external-link" rel="nofollow">Sources</a></li>
|
| <li><a href="/mina-project/gen-docs/latest-2.0/apidocs/index.html" class="external-link" rel="nofollow">API Javadoc 2.0.25</a></li>
|
| <li><a href="/mina-project/gen-docs/latest-2.1/apidocs/index.html" class="external-link" rel="nofollow">API Javadoc 2.1.8</a></li>
|
| <li><a href="/mina-project/gen-docs/latest-2.2/apidocs/index.html" class="external-link" rel="nofollow">API Javadoc 2.2.3</a></li>
|
| <li><a href="/mina-project/gen-docs/latest-2.0/xref/index.html" class="external-link" rel="nofollow">API xref 2.0.25</a></li>
|
| <li><a href="/mina-project/gen-docs/latest-2.1/xref/index.html" class="external-link" rel="nofollow">API xref 2.1.8</a></li>
|
| <li><a href="/mina-project/gen-docs/latest-2.2/xref/index.html" class="external-link" rel="nofollow">API xref 2.2.3</a></li>
|
| <li><a href="/mina-project/performances.html" class="external-link" rel="nofollow">Performances</a></li>
|
| <li><a href="/mina-project/testimonials.html" class="external-link" rel="nofollow">Testimonials</a></li>
|
| <li><a href="/mina-project/conferences.html" class="external-link" rel="nofollow">Conferences</a></li>
|
| <li><a href="/mina-project/developer-guide.html" class="external-link" rel="nofollow">Developers Guide</a></li>
|
| <li><a href="/mina-project/related-projects.html" class="external-link" rel="nofollow">Related Projects</a></li>
|
| <li><a href="https://people.apache.org/~vgritsenko/stats/projects/mina.html" class="external-link" rel="nofollow">Statistics</a></li>
|
| </ul>
|
|
|
| <h5>Community</h5>
|
| <ul>
|
| <li><a href="https://www.apache.org/foundation/contributing.html" class="external-link" rel="nofollow">Contributing</a></li>
|
| <li><a href="/contributors.html" class="external-link" rel="nofollow">Team</a></li>
|
| <li><a href="/special-thanks.html" class="external-link" rel="nofollow">Special Thanks</a></li>
|
| <li><a href="https://www.apache.org/security/" class="external-link" rel="nofollow">Security</a></li>
|
| </ul>
|
|
|
| <h5>About Apache</h5>
|
| <ul>
|
| <li><a href="https://www.apache.org" class="external-link" rel="nofollow">Apache main site</a></li>
|
| <li><a href="https://www.apache.org/licenses/" class="external-link" rel="nofollow">License</a></li>
|
| <li><a href="https://www.apache.org/foundation/sponsorship.html" title="The ASF sponsorship program" class="external-link" rel="nofollow">Sponsorship program</a></li>
|
| <li><a href="https://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</a></li>
|
| </ul>
|
|
|
| <h3><a name="Navigation-Upcoming"></a>Upcoming</h3>
|
| <ul>
|
| <li>No event</li>
|
| </ul>
|
| </div>
|
| </div>
|
| <div id="rightColumn">
|
|
|
|
|
| |
| <h1 id="22x-vs-21x-differences">2.2.x vs 2.1.x differences</h1> |
| <p>The <strong>SSL/TLS</strong> handling has been totally rewritten in <strong>MINA 2.2</strong>. This has an impact in many areas.</p> |
| <h2 id="removal-of-the-sslfilterdisable_encryption_once-attribute">Removal of the SslFilter.DISABLE_ENCRYPTION_ONCE attribute</h2> |
| <p>This attribute was used in previous <strong>MINA</strong> versions to insure that we can send a clear text message to the remote peer while establishing the TLS connection when using the <strong>startTLS</strong> command.</p> |
| <p>The idea is that the <strong>startTLS</strong> command is sent by an application (an <strong>LDAP</strong> client, for instance), which tells the server it should establish the <strong>SSL/TLS</strong> layer. The problem is that the server should be able to inform the client that the <strong>SSL/TLS</strong> layer is up and running, in clear text, which is not possible as the <strong>SSL/TLS</strong> layer is already fonctionning…</p> |
| <p>This kind of chicken and egg problem was solved by giving the opportunity to the <strong>SSL/TLS</strong> layer to send back the <strong>startTLS</strong> response to the client in clear text, assuming it’s the server’s first message. A bit of a hack.</p> |
| <p>In <strong>MINA 2.2</strong>, this attribute has been removed and replaced by either a filter to be added, or by encapsulating the message that should not be encrypted into an instance that implements the <strong>DisableEncryptWriteRequest</strong> interface.</p> |
| <p>Typically, in <strong>Apache Directory</strong>, we use this filter:</p> |
| <div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"><span style="color:#a2f;font-weight:bold">public</span> <span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">StartTlsFilter</span> <span style="color:#a2f;font-weight:bold">extends</span> IoFilterAdapter |
| <span style="color:#666">{</span> |
| <span style="color:#080;font-style:italic">/** |
| </span><span style="color:#080;font-style:italic"> * {@inheritDoc} |
| </span><span style="color:#080;font-style:italic"> */</span> |
| <span style="color:#a2f">@Override</span> |
| <span style="color:#a2f;font-weight:bold">public</span> <span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">filterWrite</span><span style="color:#666">(</span> NextFilter nextFilter<span style="color:#666">,</span> IoSession session<span style="color:#666">,</span> WriteRequest writeRequest <span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">throws</span> Exception |
| <span style="color:#666">{</span> |
| <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> writeRequest<span style="color:#666">.</span><span style="color:#b44">getOriginalMessage</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#a2f;font-weight:bold">instanceof</span> StartTlsResponse <span style="color:#666">)</span> |
| <span style="color:#666">{</span> |
| <span style="color:#080;font-style:italic">// We need to bypass the SslFilter |
| </span><span style="color:#080;font-style:italic"></span> IoFilterChain chain <span style="color:#666">=</span> session<span style="color:#666">.</span><span style="color:#b44">getFilterChain</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span> |
| |
| <span style="color:#a2f;font-weight:bold">for</span> <span style="color:#666">(</span> IoFilterChain<span style="color:#666">.</span><span style="color:#b44">Entry</span> entry <span style="color:#666">:</span> chain<span style="color:#666">.</span><span style="color:#b44">getAll</span><span style="color:#666">(</span><span style="color:#666">)</span> <span style="color:#666">)</span> |
| <span style="color:#666">{</span> |
| IoFilter filter <span style="color:#666">=</span> entry<span style="color:#666">.</span><span style="color:#b44">getFilter</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">;</span> |
| |
| <span style="color:#a2f;font-weight:bold">if</span> <span style="color:#666">(</span> filter <span style="color:#a2f;font-weight:bold">instanceof</span> SslFilter <span style="color:#666">)</span> |
| <span style="color:#666">{</span> |
| entry<span style="color:#666">.</span><span style="color:#b44">getNextFilter</span><span style="color:#666">(</span><span style="color:#666">)</span><span style="color:#666">.</span><span style="color:#b44">filterWrite</span><span style="color:#666">(</span> session<span style="color:#666">,</span> writeRequest <span style="color:#666">)</span><span style="color:#666">;</span> |
| <span style="color:#666">}</span> |
| <span style="color:#666">}</span> |
| <span style="color:#666">}</span> |
| <span style="color:#a2f;font-weight:bold">else</span> |
| <span style="color:#666">{</span> |
| nextFilter<span style="color:#666">.</span><span style="color:#b44">filterWrite</span><span style="color:#666">(</span> session<span style="color:#666">,</span> writeRequest <span style="color:#666">)</span><span style="color:#666">;</span> |
| <span style="color:#666">}</span> |
| <span style="color:#666">}</span> |
| <span style="color:#666">}</span> |
| |
| </code></pre></div><p>As you can see in the code above, we check if the message is a <strong>startTLS</strong> response, and if so, we bypass the <strong>SSLFilter</strong>, which leads to the message to be sent in clear text.</p> |
| <h2 id="addition-of-the-iosessionisserver-method">Addition of the IoSession.isServer() method</h2> |
| <p>This method tells if the underlaying service is an <em>IoAcceptor</em> or not. It’s useful to quickly find out if we have to set the <strong>Tls</strong> flag to client or server when initializing the <strong>SslEngine</strong> instance, we also use it for the <strong>SslFilter</strong> logs.</p> |
| <h2 id="removal-of-the-sslfiltergetsslsession-method">Removal of the SslFilter.getSslSession() method</h2> |
| <p>This method is not used. Would you like to get the <strong>SSLSession</strong> instance, it’s a matter of calling the <em>IoSession.getAttribute()</em> method with <strong>SslFilter.SSL_SECURED</strong> as a parameter:</p> |
| <div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"><span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span> |
| SSLSession sslSession <span style="color:#666">=</span> SSLSession<span style="color:#666">.</span><span style="color:#b44">class</span><span style="color:#666">.</span><span style="color:#b44">cast</span><span style="color:#666">(</span>getAttribute<span style="color:#666">(</span>SslFilter<span style="color:#666">.</span><span style="color:#b44">SSL_SECURED</span><span style="color:#666">)</span><span style="color:#666">)</span><span style="color:#666">;</span> |
| <span style="color:#666">.</span><span style="color:#666">.</span><span style="color:#666">.</span> |
| </code></pre></div><h2 id="why-is-it-api-incompatible-">Why is it API incompatible ?</h2> |
| <p>The removal of the <strong>SslFilter.DISABLE_ENCRYPTION_ONCE</strong> attribute makes it impossible for application that leverage the <strong>startTLS</strong> command to work, without some code change.</p> |
| <h2 id="migration">Migration</h2> |
| <p>This is pretty straightforward :</p> |
| <ul> |
| <li>Create a filter that bypasses the message that should not be encrypted, or encapsulate it into an instance that implements the <strong>DisableEncryptWriteRequest</strong> interface.</li> |
| </ul> |
| <p>and that’s it !</p> |
| |
|
|
|
|
|
|
| </div>
|
| <div id="endContent"></div>
|
| </div>
|
|
|
| <div id="footer">
|
| © 2003-2024, <a href="https://www.apache.org">The Apache Software Foundation</a> - <a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy Policy</a><br />
|
| Apache MINA, MINA, Apache Vysper, Vysper, Apache SSHd, SSHd, Apache FtpServer, FtpServer, Apache AsyncWeb, AsyncWeb,
|
| Apache, the Apache feather logo, and the Apache Mina project logos are trademarks of The Apache Software Foundation.
|
| </div>
|
|
|
| </div>
|
|
|
| </body>
|
|
|
| </html>
|
