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

[el...@apache.org]

Author: elecharny
Date: Sun Feb 14 23:45:14 2016
New Revision: 1730431

URL: http://svn.apache.org/viewvc?rev=1730431&view=rev
Log:
Added SSL doco

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=1730431&r1=1730430&r2=1730431&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 Sun Feb 14 23:45:14 2016
@@ -161,8 +161,53 @@ Now, we will dive a bit deeper into **MI
     * filterWrite(NextFilter, IoSession, WriteRequest)
     * messageSent(NextFilter, IoSession, WriteRequest)
 
+### Management
 
-### messageReceived event
+Here are the Filter's management methods :
+
+#### onPreAdd
+
+This is where we create the **SslHandler** instance, and initialize it. We also define the supported ciphers.
+
+The **SslHandler** instance will itself create an instanc eof **SSLEngine**, and configure it with all the parameters set in the **SslFilter**:
+
+* If this is client or a server side 
+* When it's server side, the flag that says we want or require the client authentication
+* The list of enabled ciphers
+* The list of enabled protocols
+
+When it's done, the reference to this instance is stored into the Session's attributes.
+
+#### onPostAdd
+
+This is where we start the handshake if it's not explicitely postponed. This is all what this method does. All the logic is implemented by the **SslHandler**
+
+#### onPreRemove
+
+Here, we stop the SSL session and we cleanup the session (removing the filter from the session's chain and the **SslHandler** instance from the session's attributes). The **Sslhandler** instance si also destroyed after having flushed any event that is not yet processed.
+
+### Session events
+
+Here are the events that are propagated across the filter's chain and processed by the **SslFilter** :
+
+#### sessionClosed
+
+We just destroy the **SslHandler** instance. 
+
+#### exceptionCaught
+
+We have one special task to proceed when the exception is due to a closed session : we have to gather all the messages that wer epending to add them to the exception that will be propagated.
+
+#### filterClose
+
+Here, if there is a SSL session started, we need to close it. In any case, we propagate the event into the chain to the next filter.
+
+
+### Messages events
+
+Last, not least, the three events relative to messages :
+
+#### 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
@@ -171,7 +216,7 @@ This event is received when we read some
 
 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
+##### 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...
 
@@ -198,7 +243,7 @@ The important part here is that the **Ss
 <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 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**.
 
@@ -213,6 +258,62 @@ Here is a schema representing the full p
 </DIV>
 
 
-### filterwWrite event
+#### filterwWrite event
+
+This event is processed when the **IoSession.write()** method is called. 
+
+If the SSL session is not started, we simply accumulate the message to write. It will be send later.
+
+<DIV class="note" markdown="1">
+There is one tricky parameter that comes into play here, for some very specific need. Typically, when implementing the <strong>startTLS</strong> protocol, where the server is switching from a non secured connection to a secured connection by the mean of an application message (and potentially a response), we need the response to be send back to the client <strong>before</strong> the <strong>SslFilter</strong> is installed (otherwise, the response will be blocked, and the etablishement of a secured connection will simply fail). This is the <strong>DISABLE_ENCRYPTION_ONCE</strong> Attribute. It does not matter what it contains (it can be just a boolean), it's enough for this parameter to be present in the session for the first message to bypasse the <strong>SslFilter</strong>.
+</DIV>
+
+We control the presence of the **DISABLE_ENCRYPTION_ONCE** flag in the session's attributes, and if present, we remove it from the session, and push the message uncrypted into the messages queue to be send.
+
+Otherwise, if the handshake is not yet completed, we keep the message in a queue, and if it's completed, we encrypt it and schedule it to be written.
+
+If some message has been scheduled for write, we flus them all.
+
+#### messageSent event
+
+Here, it's just a matter of getting back the unencrypted message to propagate it to the **IoHandler**
+
+## SSLContext initialisation
+
+We saw that in order to establish a **SSL** session, we need to create a **SSLContext**. Here is the code :
+
+
+    SSLContext sslContext;
+
+    try
+    {
+        // Initialize the SSLContext to work with our key managers.
+        sslContext = SSLContext.getInstance( "TLS" );
+        sslContext.init( ... ); // Provide the needed KeyManager[], TrustManager[] and SecureRandom instances
+    }
+    catch ( Exception e )
+    {
+        // Handle your exception
+    }
+
+What we have not exposed here is the constructor and the **init()** method. 
+
+The **SSLContext** can either be created explicitely - through its constructor -, or we ask the static factory to return an instance (this is what we have done in the previous code. teh second method is quite straightforward, and would fit most of the time. It's enough to pass it the name of the protocol to use, which is one of :
+
+* **SSL**
+* **SSLv2**
+* **SSLv3**
+* **TLS**
+* **TLSv1**
+* **TLSv1.1**
+* **TLSv1.2** (not supported in Java 6)
+
+It's strongly suggested to pick the higher algorithm (ie **TLSv1.2**) if your client supports it.
+
+The **init()** method takes 3 arguments :
+
+* a **KeyManager** (can be null)
+* a **TrustManager** (can be null)
+* a random generator (can be null)
 
-This event is processed when the **IoSession.write()** method is called. 
\ No newline at end of file
+If the parameters are set to null, the installed security provider will pick the highest priority implementation.