If the directory/file paths specified in this guide do not exist in your WSO2 product, see Directory Structure of WSO2 Products to locate the paths applicable to your product.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated typo in "Enabling SSL protocols and ciphers in ThriftAuthenticationService" step1
Note

This page is currently being updated!

 Given Given below are the various transport-level security configurations that are required for WSO2 products. See the following topics for instructions.

Table of Contents
maxLevel43
minLevel3

Enabling TLS and disabling SSL support

The transport-level security protocol of the Tomcat server is configured in the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file. By default, "TLS" is configured as the SSL protocol for HTTPS communication , by setting the sslProtocol="TLS" attribute in the catalinathe catalina-server.xml filexml file. Specifying TLS as the SSL protocol means ensures that all TLS versions, as well as SSL protocol versions, are supported. However, due to the Poodle Attack, it is necessary to make sure that only TLS protocol versions are enabled.

Note that , in some WSO2 products, such as WSO2 Enterprise Integrator (ESB profile) and WSO2 API Manager, pass-thru transports are enabled. Therefore, to disable SSL in such products, the axis2.xml file stored in the <PRODUCT_HOME>/repository/conf/axis2/ directory should also be configured.

...

  1. Stop the server.

  2. Open the <PRODUCT_HOME>/repository/conf/axis2/axis2.xml file and add the specified parameter under the <transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener"> element as well as under the <transportSender name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender"> element. If you are using JDK 1.8, you can add the following parameter:

    Code Block
    <parameter name="HttpsProtocols">TLSv1,TLSv1.1,TLSv1.2</parameter> 
    Test the pass-through transport using the following command with the corresponding port
    Info
    • If you are using JDK 1.6, add the following parameter:

      Code Block
      <parameter name="HttpsProtocols">TLSv1</parameter> 
  3. Start the server.

    • If you are using JDK 1.7, add the following parameter:

      Code Block
    $ java -jar TestSSLServer.jar localhost 8243

...

    • <parameter name="HttpsProtocols">TLSv1,TLSv1.1

...

    • ,TLSv1.

...

    • 2</parameter> 
    • If you are using JDK 1.

...

The TLS protocol is set to TLSv1.0 (by default), in WSO2 products running on JDK 1.7. You cannot configure this using the catalina-server.xml file or the axis2.xml file as we do with products based on JDK 1.7. Therefore, you need to enable TLSv1.1 and TLSv1.2 globally, by setting a system property.

  1. Download the following JARs:
  2. Copy the wso2-ssl-socket-factory-provider-1.0.0.jar file to the <PRODUCT_HOME>/lib/endorsed directory.
  3. Copy the wso2-ssl-security file to the <PRODUCT_HOME>/repository/conf/ directory.
  4. Open the product startup script (wso2server.sh for Linux, or wso2server.bat for Windows), which is stored in the <PRODUCT_HOME>/bin directory.

  5. Add the following system properties to the script:

    Code Block
    -Djdk.tls.client.protocols="TLSv1.1,TLSv1.2" \
    -Djava.security.properties=$PRODUCT_HOME/repository/conf/wso2-ssl-security \
  6. Start the server.

Disabling weak ciphers

A cipher is an algorithm for performing encryption or decryption. When you set the sslprotocol of your server to TLS, the TLS and the default ciphers get enabled without considering the strength of the ciphers. This is a security risk as weak ciphers, also known as EXPORT ciphers, can make your system vulnerable to attacks such as the Logjam attack on Diffie-Hellman key exchange. The Logjam attack is also called the Man-in-the-Middle attack. It downgrades your connection's encryption to a less-secured level (e.g., 512 bit) that can be decrypted with sufficient processing power.

To prevent these types of security attacks, it is encouraged to disable the weak ciphers. You can enable only the ciphers that you want the server to support in a comma-separated list in the ciphers  attribute. Also, if you do not add this cipher attribute or keep it blank, the browser will support all the SSL ciphers by JSSE. This will enable the weak ciphers.

Disabling weak ciphers for the Tomcat transport

  1. Open the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file.
  2. Make a backup of the catalina-server.xml  file and stop the WSO2 product server.
  3. Add the cipher  attribute to the existing configuration in the catalina-server.xml file by adding the list of ciphers that you want your server to support as follows: ciphers="<cipher-name>,<cipher-name>". See the example given below.

    Code Block
    For Tomcat version 7.0.59 and JDK version 1.7:
    ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA"  
    
    For Tomcat version 7.0.59 and JDK version 1.8:
    ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256"

    See the list of supported cipher suites.

  4. Start the server.
  5. To verify that the configurations are all set correctly, download and run the TestSSLServer.jar.

    Code Block
    $ java -jar TestSSLServer.jar localhost 9443
    Note

    Note the following when you run TestSSLServer.jar:

    • The "Supported cipher suites" section in the output does not contain any EXPORT ciphers.

    • When you use the supported cipher suites listed here, the BEAST attack status will be shown as vulnerable. Note that this is a client-side vulnerability caused by the TLSv1 protocol. You can make the BEAST status protected by removing TLSv1, which will make clients with TLSv1 unusable. Therefore, it is recommended tofixed this from the client side.

Disables weak ciphers for the PassThrough transport

Remove any weak ciphers from the PassThrough transport and ensure that the server does not accept connections using those weak ciphers. The PassThrough transport is configured using the axis2.xml file (stored in the <PRODUCT_HOME>/repository/conf/axis2/ directory). 

  1. Open the <PRODUCT_HOME>/repository/conf/axis2/axis2.xml file.
  2. Make a backup of the axis2.xml  file and stop the WSO2 product server.
  3. You need to add the PreferredCiphers parameter under the "Transport Ins (Listeners)" section along with the list of relevant cipher suites.

    Code Block
    <parameter name="PreferredCiphers">TLS_ECDHE_RSA_WITH_3DES_EDE
    • 8, add the following parameter:

      Code Block
      <parameter name="HttpsProtocols">TLSv1,TLSv1.1,TLSv1.2</parameter> 
  4. Start the server.

  5. Test the pass-through transport using the following command with the corresponding port:

    Code Block
    $ java -jar TestSSLServer.jar localhost 8243

Enabling SSL protocols and ciphers in ThriftAuthenticationService

Do the following to enable SSL protocols and ciphers in the ThriftAuthenticationService.

  1. Add the following configurations in the <CARBON_SERVER>/repository/conf/identity/thrift-authentication.xml file as sub-elements of the root <Server> element.

    Code Block
    <SSLEnabledProtocols>TLSv1,TLSv1.1,TLSv1.2</SSLEnabledProtocols>
    <Ciphers>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</Ciphers>
    Tip

    Tip: You can also add the following additional cipher suites to the <Ciphers> property if JCE Unlimited Strength Jurisdiction Policy is enabled in Java.

    Code Block
    TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_DHE_RSA_WIT

    If you wish to remove TLSv1 or TLSv1.1, you can do so by removing them as values from the <SSLEnabledProtocols> property.

  2. Restart the server. 

Enabling TLSv1.1/TLSv1.2 for products with JDK 1.7

The TLS protocol is set to TLSv1.0 (by default), in WSO2 products running on JDK 1.7. You cannot configure this using the catalina-server.xml file or the axis2.xml file as we do with products based on JDK 1.7. Therefore, you need to enable TLSv1.1 and TLSv1.2 globally by setting a system property.

  1. Download the following artifacts:
  2. Copy the wso2-ssl-socket-factory-provider-1.0.0.jar file to the <PRODUCT_HOME>/lib/endorsed directory.
  3. Copy the wso2-ssl-security file to the <PRODUCT_HOME>/repository/conf/ directory.
  4. Open the product startup script (wso2server.sh for Linux, or wso2server.bat for Windows), which is stored in the <PRODUCT_HOME>/bin directory.

  5. Add the following system properties to the script:

    Code Block
    -Djdk.tls.client.protocols="TLSv1.1,TLSv1.2" \
    -Djava.security.properties="$CARBON_HOME/repository/conf/wso2-ssl-security" \
  6. Start the server.

Anchor
disablingweakciphers
disablingweakciphers
Disabling weak ciphers

A cipher is an algorithm for performing encryption or decryption. When you set the sslprotocol of your server to TLS, the TLS and the default ciphers get enabled without considering the strength of the ciphers. This is a security risk as weak ciphers, also known as EXPORT ciphers, can make your system vulnerable to attacks such as the Logjam attack on Diffie-Hellman key exchange. The Logjam attack is also called the Man-in-the-Middle attack. It downgrades your connection's encryption to a less-secured level (e.g., 512 bit) that can be decrypted with sufficient processing power.

To prevent these types of security attacks, it is encouraged to disable the weak ciphers. You can enable only the ciphers that you want the server to support in a comma-separated list in the ciphers  attribute. Also, if you do not add this cipher attribute or keep it blank, the browser will support all the SSL ciphers by JSSE. This will enable the weak ciphers.

Disabling weak ciphers for the Tomcat transport

  1. Open the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml  file.
  2. Make a backup of the catalina-server.xml  file and stop the WSO2 product server.
  3. Add the cipher  attribute to the existing configuration in the catalina-server.xml  file by adding the list of ciphers that you want your server to support as follows: ciphers="<cipher-name>,<cipher-name>". See the example given below.

    Code Block
    For Tomcat version 7.0.59 and JDK version 1.7:
    ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHACBC_SHA"  
    
    For Tomcat version 7.0.59 and JDK version 1.8:
    ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHASHA256,TLS_ECDHEDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</parameter>
  4. Start the server.
  5. Test the pass-through transport using the following command with the corresponding port:

    Code Block
    $ java -jar TestSSLServer.jar localhost 8243

...

iconfalse

From Firefox 39.0 onwards, the browser does not allow to access Web sites that support DHE with keys less than 1023 bits (not just DHE_EXPORT). 768/1024 bits are considered to be too small and vulnerable to attacks if the hacker has enough computing resources. 

Tip
iconfalse

To use AES-256, the Java JCE Unlimited Strength Jurisdiction Policy files need to be installed. Download them from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

...

iconfalse

...

Changing the server name in HTTP response headers

...

  1. CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256"

    See the list of supported cipher suites.

  2. Start the server.
  3. To verify that the configurations are all set correctly, download and run the TestSSLServer.jar.

    Code Block
    $ java -jar TestSSLServer.jar localhost 9443
    Note

    Note the following when you run TestSSLServer.jar:

    • The "Supported cipher suites" section in the output does not contain any EXPORT ciphers.

    • When you use the supported cipher suites listed here, the BEAST attack status will be shown as vulnerable. Note that this is a client-side vulnerability caused by the TLSv1 protocol. You can make the BEAST status protected by removing TLSv1, which will make clients with TLSv1 unusable. Therefore, it is recommended tofixed this from the client side.

Disables weak ciphers for the PassThrough transport

Remove any weak ciphers from the PassThrough transport and ensure that the server does not accept connections using those weak ciphers. The PassThrough transport is configured using the axis2.xml file (stored in the <PRODUCT_HOME>/repository/conf/axis2/  directory). 

  1. Open the <PRODUCT_HOME>/repository/conf/tomcataxis2/catalina-serveraxis2.xml  file.
  2. Add a new server name using the server property (under the relevant Tomcat connector configuration):

    Code Block
    server="WSO2 Carbon Server"

Enabling HTTP Strict Transport Security (HSTS) Headers

Enable "HTTP Strict Transport Security headers" (HSTS) for the applications deployed in your server, to confirm that the relevant headers are present in the HTTP response. HSTS is not enabled for applications in WSO2 products by default. 

Note

Note that, HSTS should NOT be enabled in development environments because transport security validations can interrupt the development processes by validating signatures of self-signed certificates.

For the management console

If the HttpHeaderSecurityFilter element is available in the web.xml file (stored in the <PRODUCT_HOME>/repository/conf/tomcat/carbon/WEB-INF/ directory) as shown below, it implies that security headers are by default configured for the management consoles of all of your profiles. However, in a production deployment, ‘Strict-Transport-Security’ needs to be explicitly enabled by replacing the default <init-param> values of the HttpHeaderSecurityFilter filter.

Shown below is the default filter configuration.

Code Block
<!-- Tomcat http header security filter -->
<filter>
        <filter-name>HttpHeaderSecurityFilter</filter-name>
        <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
        <init-param>
            <param-name>hstsEnabled</param-name>
            <param-value>false</param-value>
        </init-param>
</filter>

Shown below is how you should explicitly enable HSTS.

Code Block
<!-- Tomcat http header security filter -->

<filter>
        <filter-name>HttpHeaderSecurityFilter</filter-name>
        <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
        <init-param>
            <param-name>hstsMaxAgeSeconds</param-name>
            <param-value>15768000</param-value>
        </init-param>
</filter>

For web applications

Similar to the management console, check whether the HttpHeaderSecurityFilter (stored in the <PRODUCT_HOME>/repository/deployment/server/webapps/ directory) is available in the web.xml file of that particular web application. If the filter is available, enable HSTS as shown below.

Code Block
<filter>
	<filter-name>HttpHeaderSecurityFilter</filter-name>        
	<filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class> 
</filter>
<filter-mapping>     
	<filter-name>HttpHeaderSecurityFilter</filter-name>     
	<url-pattern>*</url-pattern> 
</filter-mapping>

For Jaggery applications

For Jaggery applications, the HttpHeaderSecurityFilter element should be configured in the jaggery.conf file (stored in the <PRODUCT_HOME>/repository/deployment/server/jaggeryapps/ directory). This filter configuration is applicable to the /dashboard jaggery applications in this location. To enable HSTS for a Jaggery application, change the default filter configuration as shown below.

The default filter configuration:

Code Block
 "params" : [{"name" : "hstsEnabled", "value" : "false"}]

The filter configuration after enabling HSTS:

Code Block
"params" : [{"name" : "hstsMaxAgeSeconds", "value" : "15768000"}]
Note

NOTE: Returning HTTP security headers could also be achieved by configuring those headers from the Proxy/LB configuration.

Preventing browser caching

If there are dynamic pages in your application, which also include sensitive information, you need to prevent caching. This can be done by making sure that the applications return the following HTTP security headers in HTTP responses.

Panel

Expires:0
Pragma:no-cache
Cache-Control:no-store, no-cache, must-revalidate

The following topics explain how you can configure these security headers for different types of applications used in WSO2 products.

For the management console

You can enable these headers for the management console by adding the following configuration to the web.xml file (stored in the <PRODUCT_HOME>/repository/conf/tomcat/carbon/WEB-INF/ directory).

Code Block
<filter> 
	<filter-name>URLBasedCachePreventionFilter</filter-name> 
	<filter-class>org.wso2.carbon.ui.filters.cache.URLBasedCachePreventionFilter</filter-class>
</filter>
<filter-mapping> 
	<filter-name>URLBasedCachePreventionFilter</filter-name> 
	<url-pattern>*.jsp</url-pattern>
</filter-mapping>
For web applications

If your web application (stored in the <PRODUCT_HOME>/repository/deployment/server/webapps/ directory) serves dynamic pages/content, then make sure that either URLBasedCachePreventionFilter or ContentTypeBasedCachePreventionFilter is available in the web.xml file of the particular application. 

Note that the applications that are included in the /webapps directory by default in a WSO2 product do not serve sensitive content that requires cache prevention. However, if you are adding any new applications, you need to be mindful of this requirement.

For Jaggery applications

For Jaggery-based applications (stored in the <PRODUCT_HOME>/repository/deployment/server/jaggeryapps/ directory), either URLBasedCachePreventionFilter or ContentTypeBasedCachePreventionFilter should be available in the jaggery.conf file as shown below.

...

  1. Make a backup of the axis2.xml  file and stop the WSO2 product server.
  2. You need to add the PreferredCiphers parameter under the "Transport Ins (Listeners)" section along with the list of relevant cipher suites.

    Code Block
    <parameter name="PreferredCiphers">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</parameter>
  3. Start the server.
  4. Test the pass-through transport using the following command with the corresponding port:

    Code Block
    $ java -jar TestSSLServer.jar localhost 8243


Info
iconfalse

From Firefox 39.0 onwards, the browser does not allow to access Web sites that support DHE with keys less than 1023 bits (not just DHE_EXPORT). 768/1024 bits are considered to be too small and vulnerable to attacks if the hacker has enough computing resources. 

Tip
iconfalse

To use AES-256, the Java JCE Unlimited Strength Jurisdiction Policy files need to be installed. Download them from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Tip
iconfalse

From Java 7, you must set the jdk.certpath.disabledAlgorithms property in the <JAVA_HOME>/jre/lib/security/java.security file to jdk.certpath.disabledAlgorithms=MD2, DSA, RSA keySize < 2048. It rejects all algorithms that have key sizes less than 2048 for MD2, DSA and RSA.

Note: This tip is not applicable when you are disabling weak ciphers in WSO2 Identity Server.


Changing the server name in HTTP response headers

By default, all WSO2 products pass "WSO2 Carbon Server" as the server value in HTTP headers when sending HTTP responses. This means that information about the WSO2 product stack will be exposed through HTTP responses. It is recommended to change this by configuring the server name in the catalina-server.xml file.

  1. Open the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml  file.
  2. Add a new server name using the server property (under the relevant Tomcat connector configuration):

    Code Block
    server="WSO2 Carbon Server"
Info

See the Security Guidelines for Production Deployment for the full list of security-related recommendations for WSO2 products.