InfoCenter Home >
5: Securing applications -- special topics >
5.7: The Secure Association Service (SAS) >
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:
- Start the administrative console.
- Select Security Center.
- Select Default SSL Configuration.
- 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 .
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 .
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.
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.
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.
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:
- Enter the following in the JVM Arguments field of the
application server:
com.ibm.CORBA.Debug=true
com.ibm.CORBA.CommTrace=true
- 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.
|
|