svn commit: r1729754 - /mina/site/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.mdtext

[el...@apache.org]

Author: elecharny
Date: Thu Feb 11 00:42:49 2016
New Revision: 1729754

URL: http://svn.apache.org/viewvc?rev=1729754&view=rev
Log:
Added some info on teh SSL page

Modified:
    mina/site/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.mdtext

Modified: mina/site/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.mdtext?rev=1729754&r1=1729753&r2=1729754&view=diff
==============================================================================
--- mina/site/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.mdtext (original)
+++ mina/site/trunk/content/mina-project/userguide/ch11-ssl-filter/ch11-ssl-filter.mdtext Thu Feb 11 00:42:49 2016
@@ -24,13 +24,13 @@ Notice:    Licensed to the Apache Softwa
 
 # Chapter 11 - SSL Filter
 
-The **SslFilter** is the filter in charge of managing the ecnryption 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 **SslFilte** in your filter chain.
+The **SslFilter** is the filter in charge of managing the ecnryption 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 **SslFilter** in your filter chain.
 
 As any session can modify it's message filter chain at will, it allows for protocols like **startTLS** to be used on an opened connection.
 
 ## Basic usage
 
-If you want your application to support **/TLS**, just add the **SslFilter** in your chain :
+If you want your application to support **SSL/TLS**, just add the **SslFilter** in your chain :
 
     ...
     DefaultIoFilterChainBuilder chain = acceptor.getFilterChain();
@@ -57,6 +57,8 @@ This is up to you to provide the **KeyMa
 
 be sure to inject the **SslFilter** on teh first position in your chain !
 
+We will see later a detailed exemple on how to create a **SSLContext**.
+
 ## A bit of theory
 
 If you want to get a deeper understanding on how it all works, please read the following paragraphs...
@@ -78,3 +80,26 @@ It's enough to know that any secured exc
 
 ![](../images/TLS-protocol.png)
 
+As you can see in this picture, it's a 2 phases protocol : first the handshake, then when completed the client and the server will be able to exchange data that will be encrypted.
+
+#### The Handshake
+
+Basically, it's all about negociating many elements that are to be used to encrypt the data. The detail are not so interesting in the context of this document, enough said that many messages are going to be exchanged between the client and the server, and no data can be sent during this phase. 
+
+Actually, there are two conditions for the handshake to start :
+* The server must be waiting for some handshake message to arrive
+* The client must send a **ClientHello** message
+
+We do use the Java **SSLEngine** to manage the whole **SSL/TLS** protocol. What **MINA** should take care of is the current status of the session is such that it will be able to get and deal with the client **HelloClient** message. When you inject the **SslFilter** in your filter chain, a few things happen :
+
+* A **SslHandler** instance is created (we create one instance per session). This **SslHandler** instance is in charge of the whole processing (handshake and encryption/decryption)
+* This **SslHandler** creates a **SSLEngine** using the **SslContext** instance that has been attached to the **SslFilter**
+* The **SslEngine** instance is configured and initialized
+* The **SslHandler** instance is stored into the session
+* Unless required specifically, we initiate the Handshake (which has different meaning on client side and on server side : the client will then send the **ClientHello** message, while the server switch to a mode where it waits for some data to be unwrapped). Note that the handshake initialization can be done later on, if needed
+
+We are all set. The next few steps are pure **SSL/TLS** protocol exchange. If the *session.write()* method is called, the message will be enqueued waiting for the handshake to be completed. Any pending message at the time the **SslFilter** is added into the chain will cause the **SSL/TLS** handshake to fail, so be sure that you have a clean place when you want to inject it. We also won't receive any message that is not a **SSL/TLS** protocol message.
+
+This last point is important if you are to implement **StartTLS** : as it allows your application to switch from a pmain text exchabge to an encrypted exchange at any time, you have to be sure that thre are not pending messages on both side. Obviously, on the client side - the side that initiate **StartTLS** - will have sent every pending messages before the **StartTLS** message can be sent, but it has to block any other message that are not part of the following handshake, until the handshake is completed. On the server side, once the **StartTLS** message has been received, no message should be written to the remote peer.
+
+As a matter of fact, injecting the **SslFilter** in the chain should block any exchange that are not part of the handshake protocol until the handshake is completed.
\ No newline at end of file