December 2019 Copyright © 2019 Dell Inc. or its subsidiaries. All rights reserved. 1
Troubleshooting Guide
13.11.19
RSA BSAFE
®
SSL-J 6.2.6 Troubleshooting Guide
This document provides information and instructions for troubleshooting common
issues for RSA BSAFE SSL-J 6.2.6 (SSL-J) on all released platforms.
Contents:
JCE Unlimited Strength Jurisdiction Policy Files ......................................... 2
Use SSL-J in FIPS-140 Mode in Compliance with FIPS 140-2
Requirements ................................................................................................... 3
Decrease the Time Taken for Cryptographic Operations ........................... 3
Convert Oracle JKS Keystore to PKCS #12 format .................................... 4
Errors when Running a Java Web Start Application ................................... 4
Use SSL-J with J2EE Applications and Application Servers ..................... 5
Static Registration ..................................................................................... 5
Dynamic Registration ............................................................................... 5
Explicit use of Provider Instances ........................................................... 6
How to Use a Cipher Suite That is Not in the Default List .......................... 7
SSL-J JSSE Provider ............................................................................... 7
SSLJ API .................................................................................................... 8
Inter-operability Issue with OpenSSL Server when using PSK ................. 9
2 JCE Unlimited Strength Jurisdiction Policy Files
RSA BSAFE SSL-J 6.2.6 Troubleshooting Guide
JCE Unlimited Strength Jurisdiction Policy Files
The JCE framework requires that Unlimited Strength Jurisdiction Policy Files are
downloaded and installed in order to use some algorithms and key strengths using the
JCE API.
The following algorithms require these policy files:
• AES with key sizes greater than 128 bits
• RC2 with key sizes greater than 128 bits
• RC4 with key sizes greater than 128 bits
• RC5 with key sizes greater than 128 bits
• RSA Encryption.
These algorithms are used by:
• Some PKCS #12 KeyStore files
• The following TLS cipher suites:
–
_AES_256_ cipher suites
–
TLS_RSA_ cipher suites
–
SSL_RSA_ cipher suites.
To successfully use the relevant algorithms and run all of the samples, the Unlimited
Jurisdiction Policy Files must be downloaded and installed. The JDK version installed
determines the Jurisdiction Policy File to download.
For details about the JDK versions, the corresponding locations and installation
instructions, see the RSA BSAFE SSL-J Installation Guide.
Use SSL-J in FIPS-140 Mode in Compliance with FIPS 140-2 Requirements 3
RSA BSAFE SSL-J 6.2.6 Troubleshooting Guide
Use SSL-J in FIPS-140 Mode in Compliance with FIPS
140-2 Requirements
To ensure that SSL-J is used in the FIPS 140 mode in compliance with FIPS 140-2
requirements, complete the following:
• Use the correct jar file:
– For non-Android environments, use the
jcmFIPS-6.2.5.jar file
– For Android environments, use the
jcmandroidfips-6.2.5.jar file.
• Set the initial FIPS-140 mode of operation security property
com.rsa.cryptoj.fips140initialmode to FIPS140_SSL_MODE.
For more information about using SSL-J on Android in FIPS-140 mode, see
Introduction to SSL-J > Android in the RSA BSAFE SSL-J Developer Guide.
Decrease the Time Taken for Cryptographic Operations
SSL-J relies on the operating system to provide the entropy needed for seeding the
SecureRandom object used for cryptographic operations. These operations can take
an unusually long time if the operating system is unable to provide sufficient entropy.
RSA recommends using a Hardware Security Module with SSL-J for generating the
entropy.
Refer to the Welcome to the Crypto-J Toolkit > Introduction to Crypto-J >
Hardware Operations section of the RSA BSAFE SSL-J Developers Guide.
4 Convert Oracle JKS Keystore to PKCS #12 format
RSA BSAFE SSL-J 6.2.6 Troubleshooting Guide
Convert Oracle JKS Keystore to PKCS #12 format
The keytool utility has an importkeystore option, for JDK1.6.x onwards, which
can be used to convert a JKS keystore to PKCS #12 format:
jdk_install_dir/bin/keytool
-importkeystore
-srckeystore src_jks_keystore
-destkeystore destination_p12_keystore
-srcstoretype JKS
-deststoretype PKCS12
-srcstorepass src_keystore_password
-deststorepass destination_keystore_password
-srckeypass src_keys_password
-destkeypass destination_keys_password
-noprompt
Note: The ciphers used to encrypt the PKCS #12 keystore are the same used
in the JKS keystore. These may include a Non-FIPS 140 cipher, for example
RC2. To convert these into a FIPS 140 approved cipher, for example
Triple-DES, write a simple java class to import the PKCS #12 file and then
export it back out to a file. By default SSL-J always uses FIPS 140 approved
algorithms when exporting PKCS #12 files. Refer to the “JCE Samples”
section of the RSA BSAFE SSL-J Developers Guide for information on how to
load and export PKCS #12 keystores.
Errors when Running a Java Web Start Application
The following errors can occur when running a Java Web Start application on the
client side:
•
Failed to validate signing of launch file. The signed
version does not match the downloaded version
.
In addition to signing all jar files, the Java Network Launch Protocol (JNLP) file
must be signed. Refer to the following link for more details.
http://docs.oracle.com/javase/7/docs/technotes/guides/web/secur
ity/signedJNLP.html
• The application launch for a Java Web Start application is blocked by a security
warning on the client side.
In addition to signing the JNLP file and all jar files using the same trusted
certificate, the application provider must follow the security guidelines from Java
Web Start. Refer to the document provided by Oracle at
http://docs.oracle.com/javase/tutorial/deployment/webstart/index/
html.
Use SSL-J with J2EE Applications and Application Servers 5
RSA BSAFE SSL-J 6.2.6 Troubleshooting Guide
Use SSL-J with J2EE Applications and Application
Servers
Java Application Servers use a hierarchy of class loaders to isolate the applications in
the Web and Enterprise JavaBeans containers. The use of class loaders affects how
SSL-J can be used in this environment.
Static Registration
SSL-J can be statically registered and successfully used in most Application Server
environments. Static registration allows the Application Server to take advantage of
SSL-J, however there are some disadvantages to using this approach.
• All applications must use the statically registered SSL-J. For static registration,
SSL-J jars must be installed in the
ext directory of the Java runtime so that they
appear in the class path of all applications.
The existence of multiple instances of the SSL-J jars in the class path is an
unsupported configuration, so no application can have a private copy of SSL-J
within its EAR file.
• All applications must use the same version of SSL-J, so if SSL-J is updated then
all applications should be tested with the new version. Note that some Application
Servers may provide additional controls over isolation. Configuration options may
enable the installation of SSL-J so that it is visible only to the Application Server
and not to the applications in the containers.
• It is necessary to shut down the entire Application Server in order to upgrade
SSL-J.
Dynamic Registration
The use of dynamic registration can lead to a number of problems. The provider list is
maintained by the
java.security.Security class, which is in the Java Runtime
Library. As a result, any dynamically registered provider instance is available to all
applications.
Dynamic registration can work successfully if:
• The SSL-J jars are installed in
ext directory of the JRE, not in any application’s
EAR file.
• Before registration, the applications checks if the RsaJsse provider has already
been registered by another application.
This approach has the same disadvantages as static registration.
It is not recommended for applications that contain SSL-J jars in their EAR file to
register their own instance of the RsaJsse provider, as that instance would be visible to
other applications.
6 Use SSL-J with J2EE Applications and Application Servers
RSA BSAFE SSL-J 6.2.6 Troubleshooting Guide
Where applications have their own copies of SSL-J, it is possible for one application
to use a combination of classes from its own SSL-J jars along with those from an
RsaJsse instance registered by a different application. Problems such as unexpected
ClassCastExceptions and unrecognized AlgorithmParameters can result.
This can even occur with a single application as it is being upgraded as there may
briefly be two instances of the same application. If applications are using different
versions of SSL-J then the problems can be more severe.
Explicit use of Provider Instances
SSL-J can be used as a library bundled within the EAR file of each application that
uses it. This provides all the usual advantages of an Application Server environment
such as allowing different applications to use different versions of SSL-J, however
there are some restrictions:
• SSL-J jars should not be loaded by a parent class loader and visible to the
application in addition to the private jars bundled in the EAR file.
– SSL-J jars should not be installed in the
ext directory of the Java runtime.
– SSL-J jars should not be added to the Application Server’s class path unless
the Application Server provides a mechanism to isolate this from applications.
• Applications must be written to exclusively use the
getInstance methods that
take a provider instance. To reduce the number of RsaJsse instances created, they
could:
– Pass around the RsaJsse instance
– Place the RsaJsse instance as a static field on an application class.
• Applications should not register the RsaJsse instance as that can interfere with
other applications.
How to Use a Cipher Suite That is Not in the Default List 7
RSA BSAFE SSL-J 6.2.6 Troubleshooting Guide
How to Use a Cipher Suite That is Not in the Default List
As weaknesses are found in cryptographic algorithms, such as RC4, and as computers
get faster and algorithms no longer support keys of sufficient strength, such as DES,
some cipher suites that have previously been commonly used are no longer considered
secure. These cipher suites are, by default, not enabled in recent versions SSL-J.
It may be necessary to enable a cipher suite that is not enabled by default in order to
interoperate with legacy systems or to accept connections from legacy clients, such as
devices that are not able to be updated. The JSSE and SSLJ APIs both allow the set of
enabled cipher suites to be changed by specifying the complete list of enabled cipher
suites; all other cipher suites are disabled.
The following examples demonstrate how to change the enabled cipher suites by
selecting two, and only two, cipher suites to be enabled.
SSL-J JSSE Provider
If using the SSL-J JSSE provider, invoke setEnabledCipherSuites() on each
newly created
SSLSocket, SSLServerSocket, or SSLEngine object, specifying
the required cipher suites.
For example, after creating and initializing
ctx, an SSLContext:
// Get the SocketFactory from the SSLContext.
SSLSocketFactory factory = ctx.getSocketFactory();
// Create an SSLSocket and connect it to the server.
socket = (SSLSocket) factory.createSocket(HOSTNAME, PORT);
// Set the enabled cipher suites.
String[] cipherSuites = {
"TLS_ECDHE_RSA_WITH_RC4_128_SHA",
"TLS_ECDHE_ECDSA_WITH_RC4_128_SHA"
};
socket.setEnabledCipherSuites(cipherSuites);
// Use the Socket.
InputStream in = socket.getInputStream();
OutputStream out = socket.getOutputStream();
For more information, see the following JSSE cipher suite and TLS protocol server
samples:
• jsse/client/CipherSuiteAndProtocol.java
• jsse/server/CipherSuiteAndProtocol.java
To view these samples in the RSA BSAFE SSL-J Developers Guide, go to
Welcome to the SSL-J Toolkit > JSSE Samples > Client Server Configuration and
select the required sample.
8 How to Use a Cipher Suite That is Not in the Default List
RSA BSAFE SSL-J 6.2.6 Troubleshooting Guide
SSLJ API
If using the SSLJ API, invoke setCipherSuites() on the SSLParams instance
before passing it as a parameter to the
com.rsa.ssl.SSLSocket or
com.rsa.ssl.SSLServerSocket constructor.
For example:
SSLParams params = new SSLParams();
// Set the enabled cipher suites.
CipherSuite[] cipherSuites = {
ECDHE_RSA_With_RC4_128_SHA.INSTANCE,
ECDHE_ECDSA_With_RC4_128_SHA.INSTANCE
};
params.setCipherSuites(cipherSuites);
loadTrustAnchors(params);
// Create an SSLSocket and connect it to the server.
SSLSocket socket = new SSLSocket(HOSTNAME, PORT, params);
// Use the Socket.
InputStream in = socket.getInputStream();
OutputStream out = socket.getOutputStream();
For more information, see the following SSLJ cipher suite and TLS protocol server
samples:
• sslj/client/CipherSuiteAndProtocol.java
• sslj/server/CipherSuiteAndProtocol.java
To view these samples in the RSA BSAFE SSL-J Developers Guide, go to
Welcome to the SSL-J Toolkit > SSLJ Samples > Client Server Configuration and
select the required sample.
Inter-operability Issue with OpenSSL Server when using PSK 9
RSA BSAFE SSL-J 6.2.6 Troubleshooting Guide
Inter-operability Issue with OpenSSL Server when using
PSK
When using the pre-shared key (PSK) method and the -psk_hint option to connect
to an OpenSSL server, the secure negotiations may fail with the following error on the
server:
PSK error: client identity not found
(got <supplied client-id> expected 'Client_identity')
The OpenSSL server always uses the default value, Client_identity, for the
–psk_hint.
To avoid this issue, set the SSL-J
client-id to the value Client_identity.
/
