Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Jetty/Reference/SSL Connectors"

(port property goes on connector not context factory)
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Jetty Reference
 
{{Jetty Reference
 
| introduction =  
 
| introduction =  
There are 2 ssl connectors in jetty -- [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/ssl/SslSocketConnector.html SslSocketConnector] and the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/ssl/SslSelectChannelConnector.html SslSelectChannelConnector]. The SslSocketConnector is built on top of the Jetty SocketConnector which is Jetty's implementation of a blocking connector. It makes use of java's SslSocket to add the security layer. On the other hand, SslSelectChannelConnector is an extension of Jetty's SelectChannelConnector which makes use of non-blocking IO. For its security layer, it uses java nio SslEngine. Both Connectors can be configured in the same way. Only difference is in the implementation.
+
Jetty has two SSL connectors–the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/ssl/SslSocketConnector.html SslSocketConnector] and the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/ssl/SslSelectChannelConnector.html SslSelectChannelConnector]. The SslSocketConnector is built on top of the Jetty SocketConnector which is Jetty's implementation of a blocking connector. It uses Java's SslSocket to add the security layer. The SslSelectChannelConnector is an extension of Jetty's SelectChannelConnector which uses non-blocking IO. For its security layer, it uses java nio SslEngine. You can configure these two connectors similarly; the difference is in the implementation.
  
 
| body =
 
| body =
==Configuration==
+
==Configuring Jetty for SSL==
  
Starting in Jetty 7.3.1, the preferred way to configure the SSL parameters for the connector is by configuring the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/http/ssl/SslContextFactory.html SslContextFactory] object and passing it to the connector's constructor.
+
Beginning with Jetty 7.3.1, the preferred way to configure SSL parameters for the connector is by configuring the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/http/ssl/SslContextFactory.html SslContextFactory] object and passing it to the connector's constructor.
  
The following is an example of an SslSelectChannelConnector configuration. An SslSocketConnector may be configured the same way -- just change the value of class to "org.eclipse.jetty.server.ssl.SslSocketConnector".
+
The following is an example of an SslSelectChannelConnector configuration. You can configure an SslSocketConnector the same way–just change the value of the class to <tt>org.eclipse.jetty.server.ssl.SslSocketConnector</tt>.
  
<div class="code panel" style="border-width: 1px"><div class="codeContent panelContent">
+
<source lang="XML">
 
   <Call name="addConnector">
 
   <Call name="addConnector">
 
     <Arg>
 
     <Arg>
Line 16: Line 16:
 
         <Arg>
 
         <Arg>
 
           <New class="org.eclipse.jetty.http.ssl.SslContextFactory">
 
           <New class="org.eclipse.jetty.http.ssl.SslContextFactory">
            <Set name="port">8443</Set>
 
 
             <Set name="keyStore"><SystemProperty name="jetty.home" default="." />/etc/keystore</Set>
 
             <Set name="keyStore"><SystemProperty name="jetty.home" default="." />/etc/keystore</Set>
 
             <Set name="keyStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
 
             <Set name="keyStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
Line 23: Line 22:
 
             <Set name="trustStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
 
             <Set name="trustStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
 
           </New>
 
           </New>
         </Arg
+
         </Arg>
 +
        <Set name="port">8443</Set>
 
         <Set name="maxIdleTime">30000</Set>
 
         <Set name="maxIdleTime">30000</Set>
 
       </New>
 
       </New>
 
     </Arg>
 
     </Arg>
 
   </Call>
 
   </Call>
</div></div>
+
</source>
  
Other properties which can be set for SslContextFactory are:
+
Other properties that you can set for the SslContextFactory include:
  
* keyStoreType - default value: "JKS"
+
* certAlias–Alias of a certificate to use.
* keyStoreProvider - defaults to the SunJSSE provider  
+
* keyStoreType–Default value: "JKS."
* trustStoreType - default value: "JKS"
+
* keyStoreProvider–Default is the SunJSSE provider.
* trustStoreProvider - defaults to the SunJSSE provider  
+
* trustStoreType–Default value: "JKS".
* sslKeyManagerFactoryAlgorithm - set to the value of the "ssl.KeyManagerFactory.algorithm" system property. If there is no such property, this defaults to "SunX509"
+
* trustStoreProvider–Default is the SunJSSE provider.
* sslTrustManagerFactoryAlgorithm - set to the value of the "ssl.TrustManagerFactory.algorithm" system property. If there is no such property, this defaults to "SunX509"
+
* sslKeyManagerFactoryAlgorithm–Set to the value of the "ssl.KeyManagerFactory.algorithm" system property. If there is no such property, the default is "SunX509."
* secureRandomAlgorithm - default value is null
+
* sslTrustManagerFactoryAlgorithm–set to the value of the "ssl.TrustManagerFactory.algorithm" system property. If there is no such property, the default is "SunX509."
* protocol - default value is "TLS"
+
* secureRandomAlgorithm–Default value is null.
* provider - defaults to the first provider that supports protocol
+
* protocol–Default value is "TLS."
* includeCipherSuites - see [[Jetty/Howto/CipherSuites|How to configure SSL Cipher Suites]] page.
+
* provider–Default is the first provider that supports that protocol.
* excludeCipherSuites - see [[Jetty/Howto/CipherSuites|How to configure SSL Cipher Suites]] page.
+
* includeCipherSuites–See [[Jetty/Howto/CipherSuites|How to configure SSL Cipher Suites]].
* needClientAuth - defaults to false
+
* excludeCipherSuites–See [[Jetty/Howto/CipherSuites|How to configure SSL Cipher Suites]].
* wantClientAuth - defaults to false
+
* needClientAuth–Default is false
* validateCerts - defaults to false
+
* wantClientAuth–Defaults is false.
* allowRenegotiate - defaults to false
+
* validateCerts–Default is false.
* crlPath - path to certificate revocation list file for SSL certificate validation
+
* allowRenegotiate–Default is false.
* maxCertPathLengh - maximum allowed number of intermediate certificates, defaults to -1 (unlimited)
+
* crlPath–Path to certificate revocation list file for SSL certificate validation.
 +
* maxCertPathLengh–Maximum allowed number of intermediate certificates, default is -1 (unlimited).
  
If there is no value for the "truststore", it will use the "keystore" value. Passwords can be obfuscated by using Jetty [[Jetty/Howto/Secure_Passwords|password utility]].
+
If there is no value for the ''truststore'', the system uses the ''keystore'' value. You can obfuscate passwords by using the Jetty [[Jetty/Howto/Secure_Passwords|password utility]].
  
==Deprecated methods==
+
==Using Deprecated Methods==
The methods of SslConnector that previously were being used to configure SSL parameters have been deprecated and will be removed in a future version of Jetty. Following is an example of configuring SslSelectChannelConnector connector in Jetty 7.3.0 and earlier.
+
The methods of SslConnector that Jetty previously used to configure SSL parameters have been deprecated and will be removed in a future version of Jetty. An example of configuring SslSelectChannelConnector connector in Jetty 7.3.0 and earlier follows.
  
<div class="code panel" style="border-width: 1px"><div class="codeContent panelContent">
+
<source lang="XML">>
 
   <Call name="addConnector">
 
   <Call name="addConnector">
 
     <Arg>
 
     <Arg>
Line 69: Line 70:
 
     </Arg>
 
     </Arg>
 
   </Call>
 
   </Call>
</div></div>
+
</source>
  
 
| more =  
 
| more =  
 
http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#SunJSSE
 
http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#SunJSSE
 
}}
 
}}

Revision as of 13:44, 9 June 2011



Introduction

Jetty has two SSL connectors–the SslSocketConnector and the SslSelectChannelConnector. The SslSocketConnector is built on top of the Jetty SocketConnector which is Jetty's implementation of a blocking connector. It uses Java's SslSocket to add the security layer. The SslSelectChannelConnector is an extension of Jetty's SelectChannelConnector which uses non-blocking IO. For its security layer, it uses java nio SslEngine. You can configure these two connectors similarly; the difference is in the implementation.

Configuring Jetty for SSL

Beginning with Jetty 7.3.1, the preferred way to configure SSL parameters for the connector is by configuring the SslContextFactory object and passing it to the connector's constructor.

The following is an example of an SslSelectChannelConnector configuration. You can configure an SslSocketConnector the same way–just change the value of the class to org.eclipse.jetty.server.ssl.SslSocketConnector.

   <Call name="addConnector">
     <Arg>
       <New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector">
         <Arg>
           <New class="org.eclipse.jetty.http.ssl.SslContextFactory">
             <Set name="keyStore"><SystemProperty name="jetty.home" default="." />/etc/keystore</Set>
             <Set name="keyStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
             <Set name="keyManagerPassword">OBF:1u2u1wml1z7s1z7a1wnl1u2g</Set>
             <Set name="trustStore"><SystemProperty name="jetty.home" default="." />/etc/keystore</Set>
             <Set name="trustStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
           </New>
         </Arg>
         <Set name="port">8443</Set>
         <Set name="maxIdleTime">30000</Set>
       </New>
     </Arg>
   </Call>

Other properties that you can set for the SslContextFactory include:

  • certAlias–Alias of a certificate to use.
  • keyStoreType–Default value: "JKS."
  • keyStoreProvider–Default is the SunJSSE provider.
  • trustStoreType–Default value: "JKS".
  • trustStoreProvider–Default is the SunJSSE provider.
  • sslKeyManagerFactoryAlgorithm–Set to the value of the "ssl.KeyManagerFactory.algorithm" system property. If there is no such property, the default is "SunX509."
  • sslTrustManagerFactoryAlgorithm–set to the value of the "ssl.TrustManagerFactory.algorithm" system property. If there is no such property, the default is "SunX509."
  • secureRandomAlgorithm–Default value is null.
  • protocol–Default value is "TLS."
  • provider–Default is the first provider that supports that protocol.
  • includeCipherSuites–See How to configure SSL Cipher Suites.
  • excludeCipherSuites–See How to configure SSL Cipher Suites.
  • needClientAuth–Default is false
  • wantClientAuth–Defaults is false.
  • validateCerts–Default is false.
  • allowRenegotiate–Default is false.
  • crlPath–Path to certificate revocation list file for SSL certificate validation.
  • maxCertPathLengh–Maximum allowed number of intermediate certificates, default is -1 (unlimited).

If there is no value for the truststore, the system uses the keystore value. You can obfuscate passwords by using the Jetty password utility.

Using Deprecated Methods

The methods of SslConnector that Jetty previously used to configure SSL parameters have been deprecated and will be removed in a future version of Jetty. An example of configuring SslSelectChannelConnector connector in Jetty 7.3.0 and earlier follows.

>
   <Call name="addConnector">
     <Arg>
       <New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector">
         <Set name="Port">8443</Set>
         <Set name="maxIdleTime">30000</Set>
         <Set name="keystore"><SystemProperty name="jetty.home" default="." />/etc/keystore</Set>
         <Set name="password">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
         <Set name="keyPassword">OBF:1u2u1wml1z7s1z7a1wnl1u2g</Set>
         <Set name="truststore"><SystemProperty name="jetty.home" default="." />/etc/keystore</Set>
         <Set name="trustPassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
       </New>
     </Arg>
   </Call>

Additional Resources

http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#SunJSSE

Back to the top