Apache Mina的SSL连接API

在网上找了N久也没找到有关Mina建立SSL安全连接的细节部分，连官方网站用户手册都说.......即将到来.......实在是不耐烦了，就自己去看了一下源代码，翻译了一下，翻译的比较渣。。。不过能看懂就行了！希望能够造福社会。

Mina安全连接：org.apache.mina.filter.ssl包API：

  这是一个提供SSL功能的 IoFilter类实现。

      其中包含四个类：

---

BogusTrustManagerFactory：提供虚假的TrustManagerFactory，它会产生信任任何事物的X509TrustManager对象。

构造器:  Public BogusTrustManagerFactory()

        继承了TrustManagerFactory（javax.net.ssl.TrustManagerFactory)

---

KeyStoreFactory:提供并配置一个新KeyStore实例的工厂类。

构造器：public KeyStoreFactory()

存在方法：

public KeyStore newInstance()  throws KeyStoreException, NoSuchProviderException,NoSuchAlgorithmException, CertificateException, IOException

     用于产生一个新的KeyStore，当Spring用这个Bean工厂产生Bean时，它将会产生 一个基类(base class)

返回：KeyStore实例

public void setType(String type)

       用于设置将要产生的KeyStore的类型，默认产生一个JKS的KeyStore

   参数：type：KeyStore类型

public void setPassword(String password)

     用于设置KeyStore的密码。如果值为空，则将不会有密码用于这个KeyStore

     参数：password：密码。

public void setProvider(String provider)

     设置KeyStore provider的名字，默认为平台默认provider。（这里我理解为算法提供者）

     参数：provider：提供者的名称，例如SUN

public void setData(byte[] data)

     包含一个KeyStore的byte数组

   参数：data：包含KeyStore的byte数组

public void setDataFile(File dataFile）   throws IOException

     包含KeyStore的数据路径。

   参数：dataFile：包含KeyStore的文件路径

public void setDataUrl(URL dataUrl)    throws IOException

     包含KeyStore的URL路径。

       参数：dataUrl：包含keyStore的URL路径

SslContextFactory：提供并配置一个新的SSLContext的工厂类。

构造器：public  SslContextFactory ()

存在方法：

public SSLContext newInstance() throws Exception

           用于产生一个新的SSLContext实例。

public void setProvider(String provider)

          设置 SSLContext provider的名字，默认为平台默认provider。（这里我理解为算法提供者）

          参数：provider：提供者的名称，例如SUN

public void setProtocol(String protocol)

          设置SSLContext 所采用协议类型，默认为TLS协议。

          参数:protocol：协议类型

public void setKeyManagerFactoryAlgorithmUseDefault(boolean useDefault)

          当它值为true的时候，如果没有用setKeyManagerFactory(KeyManagerFactory)和 setKeyManagerFactoryAlgorithm(String)设置KeyManagerFactory和它的算法参数，将会调用KeyManagerFactory.getDefaultAlgorithm() 来生成默认算法。这个属性值默认为ture.

          参数：useDefault：是否采用默认算法

public void setKeyManagerFactory(KeyManagerFactory factory)

          设置将要使用的KeyManagerFactory ，如果这个属性被设定，那么这个工厂bean用来产生KeyManagerFactory 的属性将会全部忽略，例如下面的算法。

          参数：factory

public void setKeyManagerFactoryAlgorithm(String algorithm）

          设置这个属性将会在KeyManagerFactory.getInstance(java.lang.String) orKeyManagerFactory.getInstance(java.lang.String, java.lang.String).生成KeyManagerFactory 时确定所用算法。      如果KeyManagerFactory 被设置的话，这个属性将会被忽略。 如果没有KeyManagerFactory 设置，但是 setKeyManagerFactoryAlgorithmUseDefault()被设置的话，这个属性也将被忽略。

          参数：algorithm:算法

public void setKeyManagerFactoryProvider(String provider)

          设置KeyStoreManagerFactory provider的名字，默认为平台默认provider。如果KeyManagerFactory 被设置的话，这个属性将会被忽略。 如果没有KeyManagerFactory 设置，但是 setKeyManagerFactoryAlgorithmUseDefault()被设置的话，这个属性也将被忽略。

          参数：provider 提供者的名字

public void setKeyManagerFactoryKeyStorePassword(String password)

          设置当使用KeyManagerFactory.init(java.security.KeyStore, char[])来产生SSLContext时的密码。

          参数：password：密码，为空时不设密码。

public void setTrustManagerFactory(TrustManagerFactory factory）

          设置将要使用的TrustManagerFactory ，如果这个属性被设定，那么这个工厂bean用来产生TrusManagerFactory的属性将会全部忽略，例如下面的配置算法。

          参数：factory

public void setTrustManagerFactoryAlgorithm(String algorithm）

          设置这个属性将会在TrustManagerFactory.getInstance(java.lang.String)orTrustManagerFactory.getInstance(java.lang.String, java.lang.String).生成 TrustManagerFactory 时确定所用算法。      如果 TrustManagerFactory被设置的话，这个属性将会被忽略。 如果没有 TrustManagerFactory设置，但是 setTrustManagerFactoryAlgorithmUseDefault()被设置的话，这个属性也将被忽略。

         参数：algorithm:算法

 public void setTrustManagerFactoryProvider(String provider)

         设置TrustStoreManagerFactory provider的名字，默认为平台默认provider。如果TrustManagerFactory  被设置的话，这个属性将会被忽略。 如果没有TrustManagerFactory  设置，将会使用setTrustManagerFactory(TrustManagerFactory)来产生TrustManagerFactory

         参数：provider 提供者的名字

public void setSecureRandom(SecureRandom secureRandom)

         设置真随机数来初始化SSLContext。如果没有设置的话，将会使用JVM默认值。

          参数：secureRandom 真随机或者空的话使用JVM默认配置。

public void setClientSessionCacheSize(int size)

设置SSLsession的缓冲区大小，当SSLSessionContext被用于客户端模式时。

参数：size：新session缓冲区大小，如果为0则为不设置

 public void setClientSessionTimeout(int seconds)

          设置SSLSession，当SSLSessionContext被用在客户端模式时的时间限制。

          参数：seconds:时间

public void setServerSessionCacheSize(int size)

          设置SSLsession的缓冲区大小，当SSLSessionContext被用于客户端模式时。

          参数：size：新session缓冲区大小，如果为0则为不设置

public void setServerSessionTimeout(int seconds)

          设置SSLSession，当SSLSessionContext被用在客户端模式时的时间限制。

          参数：seconds:时间

---

SslFilter：当数据在session中交换时的SSL过滤器。添加这个过滤器，SSL协议中握手过程将会立即通过发送‘hello’消息来实现，所以，不用调用startSsl(IoSession)，除非你想要实现StartTLS。如果你不想立即开始握手，可以将构造器中的autoStart参数设置为false来实现。这个过滤器实现了SSLEngina，所以只能在java5以上运行，并且过滤器仅仅能用在TCP/IP连接。

                    可以通过DISABLE_ENCRYPTION_ONCE 来完成StartTLS，例如：

   public void messageReceived(IoSession session, Object message) {

    if (message instanceof MyStartTLSRequest) {

        // Insert SSLFilter to get ready for handshaking

        session.getFilterChain().addFirst(sslFilter);

        // Disable encryption temporarilly.

        // This attribute will be removed by SSLFilter

        // inside the Session.write() call below.

        session.setAttribute(SSLFilter.DISABLE_ENCRYPTION_ONCE, Boolean.TRUE);

        // Write StartTLSResponse which won't be encrypted.               用于一段消息不加密

        session.write(new MyStartTLSResponse(OK));

        // Now DISABLE_ENCRYPTION_ONCE attribute is cleared.

        assert session.getAttribute(SSLFilter.DISABLE_ENCRYPTION_ONCE) == null;

    }

}

域：

public static final AttributeKey SSL_SESSION

        每个SSLsession中储存的key.

public static final AttributeKey DISABLE_ENCRYPTION_ONCE

        A 事务 AttirbuteKey 将会在下一次的写操作中不加密，但是如果另外一次写操作被唤醒，此属性会被重置，这是一个标记属性，不论值是真假都会使用，但是建议为真，使用方法如上。

public static final AttributeKey USE_NOTIFICATION

        A 事务 AttirbuteKey  将会使过滤器发出一个 IoHandler.messageReceived(IoSession, Object) 事件，通过(SESSION_SECURED orSESSION_UNSECURED)消息标记，这是一个标记属性，不论值是真假都会使用，但是建议为真，当与SSLsession流控制相关时，过滤器将不会发出任何事件。

public static final AttributeKey PEER_ADDRESS

        A 事务 AttirbuteKey 应当被用于设置一个InetSocketAddress，设置这个属性将会使 SSLContext.createSSLEngine(String, int)越过InetSocketAddress 的hostname和端口被直接调用，生成一个SSLengine实例。如果不设置 SSLContext.createSSLEngine() ，使用这个特殊的SSLsession将会在客户端模式被缓冲并复用。

public static final SslFilter.SslFilterMessage SESSION_SECURED

       这是一个发出给 IoHandler.messageReceived(IoSession, Object)的特殊的消息对象，用于当SESSION被担保并且USE_NOTIFICATION被设置。

public static final SslFilter.SslFilterMessage SESSION_UNSECURED

       这是一个发出给 IoHandler.messageReceived(IoSession, Object)的特殊的消息对象，用于当SESSION被担保并且USE_NOTIFICATION被设置。

构造器：

public SslFilter(SSLContext sslContext)

       创造一个新的SSL过滤器用特殊的SSLContext，将立即开始握手。

public SslFilter(SSLContext sslContext，boolean autoStart)

        创造一个新的SSL过滤器用特殊的SSLContext，是否开始握手看标记。

方法：

public SSLSession getSslSession(IoSession session)

          返回一个 SSLSession 由特殊session生成。

public boolean startSsl(IoSession session) throws SSLException

          开始一个SSLsession，如果这个Session没有开始，但是需要注意的是SSLsession自动开始，我们并不需要调用。、

          返回值：是否开始

public boolean isSslStarted(IoSession session)

          返回这个特殊线程是否通过SSL/TLS加密。

public WriteFuture stopSsl(IoSession session)  throws SSLException

          停止SSL session，通过发送TLS close_notify 消息来通知TLS关闭。

          参数：session：Iosession 开始通知TLS关闭。

public boolean isUseClientMode()

          当engine被设置为客户模式时，返回真。

public void setUseClientMode(boolean clientMode)

          配置engine客户模式或者服务器模式（握手时）。

public boolean isNeedClientAuth()

          如果需要客户证明的时候，返回真。

public void setNeedClientAuth(boolean needClientAuth)

          配置engine是否需要客户证明，只有当server模式时才可以配置。

public boolean isWantClientAuth()

          如果engeie将会请求客户证明，返回真，只有当服务器模式时才可以配置。

public void setWantClientAuth(boolean wantClientAuth)

            配置engine是否需要请求客户证明，只有当server模式时才可以配置。

public String[] getEnabledCipherSuites()

          返回密码将要被使用的密码方式列表，当SSLEngine被初始化时。

          返回：null意味着默认值。

public String[] setEnabledCipherSuites()

          配置密码将要被使用的密码方式列表，当SSLEngine被初始化时。

          属性：null意味着默认值。

public String[] getEnabledProtocols()

           返回密码将要被使用的协议列表，当SSLEngine被初始化时。

          返回：null意味着默认值。

public void setEnabledProtocols(String[] protocols)

           配置密码将要被使用的协议列表，当SSLEngine被初始化时。

          属性：null意味着默认值

public void onPreAdd(IoFilterChain parent,   String name,IoFilter.NextFilter nextFilter) throws SSLException

          在过滤器被添加到规则链之前，我们可以做：检查我们在前面是否使用SSL过滤器，我们升级下一个过滤器，创造SSL handler helper class，将它储存进事务状态。

     这是一个重写方法。

          参数：parent：调用这个方法的成员，这个过滤器的名字，下一个过滤器。

public void onPostAdd(IoFilterChain parent,String name,   IoFilter.NextFilter nextFilter) throws SSLException

          在过滤器被添加到规则链之后调用，这个方法并不会被调用多次。

     这是一个重写方法。

          参数：parent：调用这个方法的成员，这个过滤器的名字，下一个过滤器。

public void onPreRemove(IoFilterChain parent,String name,IoFilter.NextFilter nextFilter) throws SSLException

           在过滤器从规则链删除之前调用，这个方法并不会被调用多次。

     这是一个重写方法。

          参数：parent：调用这个方法的成员，这个过滤器的名字，下一个过滤器。

public void sessionClosed(IoFilter.NextFilter nextFilter,   IoSession session) throws SSLException

         过滤器唤醒IoHandler.sessionClosed(IoSession)事件。

public void messageRecerived(IoFilter.NextFilter nextFilter,   IoSession session) throws SSLException

         过滤器唤醒IoHandler.messageReceived(IoSession,Object)事件。

public void messageSent (IoFilter.NextFilter nextFilter,   IoSession session) throws SSLException

         过滤器唤醒 IoHandler.messageSent(IoSession,Object)事件。

public void exceptionCaught(IoFilter.NextFilter nextFilter,   IoSession session) throws SSLException

         过滤器唤醒  IoHandler.exceptionCaught(IoSession,Throwable)事件。

public void filterWrite(IoFilter.NextFilter nextFilter,   IoSession session) throws SSLException

         过滤器唤醒 IoSession.write(Object) 事件。

public void filterClose(IoFilter.NextFilter nextFilter,   IoSession session) throws SSLException

          过滤器唤醒IoSession.close() 事件。

---

SslFilter.SslFilterMessage：被SslFilter发送的消息，这个消息不论连接是否安全或者不安全。