InfoCenter Home >
5: Securing applications -- special topics >
5.7: The Secure Association Service (SAS) >
5.7.3: ORB SSL Configuration

5.7.3: ORB SSL Configuration

The SSL implementation used by the application server is the IBM JSSE (Java Secure Sockets Extension). Configuring JSSE is very similar to configuring most other SSL implementations (for example, GSKit); however, a few differences are worth noting.

JSSE allows both signer and personal certificates to be stored in a SSL key file, but it also allows a separate file to be specified called a trust file. A trust file can contain only signer certificates. Therefore, you could put all of your personal certificates in an SSL key file and your signer certificates in a trust file. This may be desirable, for example, if an inexpensive hardware device used as the key file which has only enough memory to hold a single personal certificate. All of the signer certificates are then held in a trust file on disk.

JSSE does not recognize the proprietary SSL key file format that is used by the plug-in (i.e. .kdb files); instead, it recognizes standard file formats such as JKS (Java Key Store). As such, SSL key files cannot be shared between the plug-in and application server, and a different implementation of the key management utility (IKeyMan) must be used in order to manage application server key and trust files. IKeyMan can be started on Windows systems from the WebSphere Start menu.

Configuring SSL through an SSL Settings panel

The administrative model in WebSphere allows the SSL settings for each of the WebSphere components to be both centrally or individually managed. SSL settings are centrally managed through the default SSL Settings panel. Furthermore, any of the default settings can be overridden for an individual component by using the HTTPS, ORB, and LDAPS SSL settings panels.

The default SSL settings can be used to configure the various components using SSL. ORB SSL settings can be specified, in addition, to override the default SSL settings specifically for the ORB.

To configure server SSL by using the Default SSL Configuration panel, do the following:

  1. Start the administrative console.
  2. Select Security Center.
  3. Select Default SSL Configuration.
  4. Modify the following SSL properties:
    • Key file name: c:\WebSphere\AppServer\etc\DummyServerKeyFile.jks
    • Key file password: WebAS
    • Confirm password: WebAS
    • Key file format: JKS
    • Trust file name: c:\WebSphere\AppServer\etc\DummyServerTrustFile.jks
    • Trust file password: WebAS
    • Confirm Password: WebAS
    • Security Level: high (128 bit encryption)

    If you choose to use the same file for key and trust, you can specify the same file for both properties:

    • Key file name: c:\WebSphere\AppServer\etc\DummyServerKeyFile.jks
    • Trust file name: c:\WebSphere\AppServer\etc\DummyServerKeyFile.jks

    If you only specify a Key file name, the Trust file name automatically is set to the same name as the Key file name.

Next, modify the following lines in the sas.client.props file to configure client SSL:

  • com.ibm.ssl.keyStore=DummyClientKeyFile.jks
  • com.ibm.ssl.keyStorePassword=WebAS
  • com.ibm.ssl.keyStoreType=JKS
  • com.ibm.ssl.trustStore=DummyClientTrustFile.jks
  • com.ibm.ssl.trustStorePassword=WebAS
  • com.ibm.ssl.trustStoreType=JKS
  • com.ibm.ssl.protocol=SSLv3
  • com.ibm.CORBA.standardPerformQOPModels=high (128 bit encryption)

The ORB uses these settings in the following way.

Key store file name
The path of the SSL key store file. This file is typically used to store personal certificates, including private keys. Default client and server key store files (DummyServerKeyFile.jks and DummyClientKeyFile.jks) are automatically configured and are located in the product_installation_root/etc directory. These files are included to simplify test and development environments. For production environments, generate new SSL key store files using iKeyMan (located in the product_installation_root/bin directory). A self-signed certificate can be generated or a CA can be used to create a personal certificate trusted by most clients.

On the server, the SSL configuration is configured in the administrative console through the Security Center. For pure Java clients, the key file name is configured in the sas.client.props file through the property com.ibm.ssl.keyStore.

Key store password
The password for the SSL key store file.

On the server, the key file password is configured in the administrative console through the Security Center. On a pure Java client, the key file password is configured in the sas.client.props file through the property com.ibm.ssl.keyStorePassword.

Note   The password is automatically encoded whenever the server starts. To change the password on the server side, re-enter it in the Security Center. To change the password on the client side (in the sas.client.props file), overwrite the encoded password. The next time the client starts, the new password is encoded.

Key file format
The format of the SSL key store file. Possible values are JKS (the default), PKCS12, and JCEK. The property that controls the key file format for both the client and server is com.ibm.ssl.keyStoreType.
Trust file name
The path of the SSL trust file. The trust file is typically used to store signer certificates, which specify whether the signer of the server's certificate is trusted. The trust file helps to manage which signers an organization allows connections to. This enables clients and servers to store their personal certificates in the key store file and all of their signers in the trust store file.

On the server, the trust file name is configured in the administrative console through the Security Center. On a pure java client, the trust file name is configured in the sas.client.props file through the property com.ibm.ssl.trustStore.

Trust file password
The password for the SSL trust store file. On the server, the trust file password is configured in the administrative console through the Security Center. On a pure client, the trust file password is configured in the sas.client.props file through the property com.ibm.ssl.trustStorePassword.

Note   The password is automatically encoded whenever the server starts. To change the password on the server side, retype it in the Security Center. To change the password on the client side (in the sas.client.props file), overwrite the encoded password. The next time the client starts, the new password is encoded.

Client Authentication
The WebSphere Application Server ORB does not currently support SSL client authentication (that is, SSL mutual authentication) using digital certificates. However, it does support basicauth client authentication, where the user is prompted for a userid and password. Protected methods require basicauth credentials from the user before they can be invoked at the server. These credentials are sent to the server and are authenticated using the LocalOS user registry.
Quality of Protection (Security Level)
Two properties must be configured for SSL to determine the strength of the connection.
  • For clients (including servers acting as clients), specify the security level or quality of protection by setting the following property in the sas.client.props file:
    com.ibm.CORBA.standardPerformQOPModels=level
    where level can be low, medium or high (the default).
  • For servers, specify the security level or quality of protection by setting the following property in the sas.server.props file:
    com.ibm.CORBA.standardClaimQOPModels=level
    where level can be low, medium or high (the default). This value is added to the IOR to let the client know what quality of protection is required.

Regardless of the values specified on standardPerformQOPModels, clients always make a connection at least as strong as the value specified on the server for standardClaimQOPModels. If the client standardPerformQOPModels is stronger than the server standardClaimQOPModels, the higher value is honored.

If the security level is high and either a server or client SSL configuration is enabled, the selected cipher suites are as follows. These suites are 128 bit ciphers.

SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_ RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA

If the security level is medium and either a server or client SSL configuration is enabled, the selected cipher suites are as follows. These suites are 40 bit ciphers.

SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA

If the security level is low and a server SSL configuration is enabled, the selected cipher suites are as follows. These suites do not encrypt messages, but do perform integrity checks to ensure that the message is not modified while being sent over the wire.

SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_DH_anon_WITH_RC4_128_MD5
SSL_DH_anon_WITH_DES_CBC_SHA
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA

If the security level is low and a client SSL configuration is enabled, the selected cipher suites are as follows. These seuites do not encrypt messages, but do perform integrity checks to ensure that the message is not modified while being sent over the wire.

SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
Enable Crypto Token Support
A crypto token is a hardware or software device with a built-in key store implementation. If this option is selected, the values on the Crypto Token panel are used. To display this panel, click on Crypto Token under Advanced Settings in the administrative console Security Center. See the documentation for the crypto token device for the values for the following fields.
  • Token Type. The type of built-in key store that is implemented in the crypto token. The default is PKCS#12.
  • Library File. The DLL or shared object that implements the interface to the crypto token device.
  • Password. The password for the crypto token device.
The supported crypto devices include the following:
  • Devices that are usable by SSL clients:
    • IBM Security Kit Smartcard
    • GemPlus Smartcards
    • Rainbow iKey 1000/2000 (USB smartcard device)
  • Devices that are usable by SSL clients and servers:
    • IBM 4758-23
    • nCipher nForce
    • Rainbow Cryptoswift

Dynamic Properties

Dynamic properties allow configuration of less frequently-used JSSE properties. The name, possible values, default value, and a brief description of each property follows.

com.ibm.ssl.protocol
The SSL protocol to be used, including the version. The possible values and the versions of SSL that each supports are as follows:
  • SSL. Supports some version of SSLv31; may support other versions.
  • SSLv2. Supports SSLv20.
  • SSLv3 (the default). Supports SSLv30.
  • TLS. Supports SSLv31.
  • TLSv1. Supports SSLv31.

The default value of SSLv3 is compatible with earlier WebSphere Application Server releases.

Note   TLS does not interoperate with the previous WebSphere Application Server SSL implementation. The previous implementation only supports SSLv30 handshakes and cannot interoperate with an implementation that supports only SSLv31.

com.ibm.ssl.keyStoreProvider
The name of the key store provider. The default value is IBMJCE. Possible values are any of the security providers listed in your java.security file. Change the default value of this property only if you intend to use another SSL implementation.
com.ibm.ssl.keyManager
The name of the key management algorithm. The default value is IbmX509. Possible values are key management algorithms implemented by one of the providers listed in your java.security file. Change the value of this property only if you intend to use another SSL implementation.
com.ibm.ssl.trustStoreProvider
The name of the trust store provider. The default value is IBMJCE. Possible values are any valid trust store provider name. Change the value of this property only if you intend to use another JSSE implementation.
com.ibm.ssl.trustManager
The name of the trust management algorithm. The default value is IbmX509. Possible values are trust management algorithms implemented by one of the providers listed in your java.security file. Change the value of this property only if you intend to use another SSL implementation.
com.ibm.ssl.trustStoreType
The format of the trust store. Possible values are JKS, PKCS12, and JCEK.
com.ibm.ssl.enabledCipherSuites
A space-separated list of cipher suite names. If this property is set, it overrides the com.ibm.CORBA.standardPerformQOPModels property setting. Possible cipher suite names are:
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_DH_anon_WITH_RC4_128_MD5
SSL_DH_anon_WITH_DES_CBC_SHA
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA

SSL interoperability issues

Keep the following interoperability issues in mind when configuring SSL:

  • The client and the server must run at the same SSL protocol. Currently, WebSphere Advanced Edition 3.5 and WebSphere Enterprise Edition 3.5 both use SSL version 3.0. Make sure that WebSphere Advanced Edition 4.0 is running with com.ibm.ssl.protocol=SSLv3 or com.ibm.ssl.protocol=SSL (since TLS or SSL 3.1 is not supported in 3.5) when your target supports only SSL v3.0.
  • The client and the server must communicate with a compatible cipher suite at the same encyption level. In some cases, a server can only support 40 bit encryption. When 40 bit encryption can be considered high on one server, 128 bit encryption can be considered high on another server. If a server's high is 40 bit encryption and the server publishes high in the objects IOR, the client will try to connect at the high level. If the client supports 128 bit encryption for high, the connection fails due to the cipher suite mismatch. In this case, it is necessary to set the com.ibm.ssl.enabledCipherSuites property with 40 bit ciphers on the client side. This overrides the value specified by the server in the object's IOR and manually matches the ciphers on the server side.

    Note   Often, the best way to resolve SSL cipher incompatibilities is to add all of the ciphers above to the com.ibm.ssl.enabledCipherSuites property. This allows all possible combinations to be considered during the SSL handshake. The other property to consider changing is the com.ibm.ssl.protocol. First try the SSL protocol for the highest version support, then try the SSLv3 protocol to step down to SSLv3. The SSL selection interoperates most often with other SSL servers.

  • Remember to add the target server's public key or the root CA certificate to WebSphere Advanced Edition 4.0's TrustFile.

Debugging SSL Handshake Problems

Gathering ORB trace information is the first troubleshooting step. The trace information shows you the exception at which JSSE returns to the createSocket implementation.

To enable ORB trace at the administrative server, add the following lines to the admin.config file:

com.ibm.CORBA.Debug=true
com.ibm.CORBA.CommTrace=true
com.ibm.ejs.sm.adminServer.traceString="ORBRas=all=enabled"
com.ibm.ejs.sm.adminServer.traceOutput=c\:/your_trace_directory/adminorb.log

To enable ORB trace at the application server, do the following:

  1. Enter the following in the JVM Arguments field of the application server:
    com.ibm.CORBA.Debug=true
    com.ibm.CORBA.CommTrace=true
    
  2. Select Service > Trace Service Settings and enter the following:
    • Trace specification string: ORBRas=all=enabled
    • Trace output file: c:\your_trace_directory\apporb.log

Next, enable debugging support for JSSE by doing the following:

  • Ensure the JSSE debug module, ibmjsse-debug.jar, is located in the java/jre/lib/ext directory.
  • Enable debugging by adding the following property to the server's Java command line: -Djavax.net.debug=true

Debugging the server side is the best way to find the cause of a handshake failure. Typically, all you can see on the client side is the socket closing due to the server side refusing the connection.

Go to previous article: SAS on the server side Go to next article: SAS Trace

 

 
Go to previous article: SAS on the server side Go to next article: SAS Trace