This chapter describes how to configure SSL. Configuring SSL is an optional step; however, Oracle recommends SSL for production environments.
Note:
The following sections apply to WebLogic Server deployments that use the security features in this release of WebLogic Server as well as deployments that use Compatibility Security.All machines must be kept up to date with the current set of recommended patches from the operating system vendors.
This chapter includes the following sections:
Java Secure Socket Extension (JSSE) SSL Implementation Supported
Specifying a Client Certificate for an Outbound Two-Way SSL Connection
Secure Sockets Layer (SSL) provides secure connections by allowing two applications connecting over a network to authenticate each other's identity and by encrypting the data exchanged between the applications. Authentication allows a server and optionally a client to verify the identity of the application on the other end of a network connection. Encryption makes data transmitted over the network intelligible only to the intended recipient.
SSL in WebLogic Server is an implementation of the SSL 3.0 and Transport Layer Security (TLS) 1.0 specifications.
Note:
WebLogic Server does not support SSL 2.0.WebLogic Server supports SSL on a dedicated listen port which defaults to 7002. To establish an SSL connection over HTTP, a Web browser connects to WebLogic Server by supplying the SSL listen port and the HTTPs protocol in the connection URL, for example, https://myserver:7002.
Using SSL is compute intensive and adds overhead to a connection. Avoid using SSL in development environments when it is not necessary. However, always use SSL in a production environment.
SSL can be configured one-way or two-way:
With one-way SSL, the server must present a certificate to the client, but the client is not required to present a certificate to the server. The client must authenticate the server, but the server accepts a connection from any client. One-way SSL is common on the Internet where customers want to create secure connections before they share personal data. Often, clients will also use SSL to log on in order that the server can authenticate them.
With two-way SSL (SSL with client authentication), the server presents a certificate to the client and the client presents a certificate to the server. WebLogic Server can be configured to require clients to submit valid and trusted certificates before completing the SSL connection.
This release of WebLogic Server uses an SSL implementation based on Java Secure Socket Extension (JSSE). JSSE is the Java standard framework for SSL and TLS and includes both blocking-IO and non-blocking-IO APIs, and a reference implementation including several commonly-trusted CAs.
The JSSE-based SSL implementation interoperates over SSL with instances of Weblogic Server version 8.1 and later that use the Certicom SSL implementation. That is, when WebLogic Server with JSSE SSL is used as either an SSL client or as the SSL server, it can communicate via SSL with instances of WebLogic Server (version 8.1 and later) that use the Certicom SSL implementation.
See Using the JSSE-Based SSL Implementation for information about using JSSE.
See the Java Secure Socket Extension (JSSE) Reference Guide (http://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.html) for complete information on JSSE.
Note:
As of WebLogic Server version 12.1.1, JSSE is the only SSL implementation that is supported. The Certicom-based SSL implementation is removed and is no longer supported in WebLogic Server.To set up SSL:
Obtain an identity (private key and digital certificates) and trust (certificates of trusted certificate authorities) for WebLogic Server. Use the digital certificates, private keys, and trusted CA certificates provided by WebLogic Server, the CertGen utility, the keytool utility, or a reputable vendor such as Entrust or Verisign to perform this step.
Note:
If you use the CertGen utility to generate certificates, see Limitation on CertGen Usage for information about limitations on its use. Certificates generated by CertGen are for demo purposes only and should not be used in a production environment.Store the identity and trust. Private keys and trusted CA certificates which specify identity and trust are stored in keystores.
Note:
This release of WebLogic Server supports private keys and trusted CA certificates stored in files, or in the WebLogic Keystore provider for the purpose of backward compatibility only.Configure the identity and trust keystores for WebLogic Server in the WebLogic Server Administration Console. See "Configure keystores" in the Oracle WebLogic Server Administration Console Online Help.
Set SSL configuration options for the private key alias and password in the WebLogic Server Administration Console. Optionally, set configuration options that require the presentation of client certificates (for two-way SSL). See "Servers: Configuration: SSL" and "Configure two-way SSL" in the Oracle WebLogic Server Administration Console Online Help.
Note:
FIPS mode is supported for JSSE via the RSA JSSE provider.To enable FIPS in JSSE, follow these steps:
Put the cryptojFIPS.jar jar (WL_HOME/server/lib/cryptojFIPS.jar) in the classpath, ahead of cryptoj.jar. For example, you could add cryptojFIPS.jar to the PRE_CLASSPATH variable in the server start script, typically startWebLogic.cmd/sh).
Enable the RSA JSSE provider, as described in Using the RSA JSSE Provider in WebLogic Server.
FIPS 140-2 is a standard that describes U.S. Federal government requirements for sensitive, but unclassified use.
For information about configuring identity and trust for WebLogic Server, see the following sections:
A host name verifier ensures the host name in the URL to which the client connects matches the host name in the digital certificate that the server sends back as part of the SSL connection. A host name verifier is useful when an SSL client (for example, WebLogic Server acting as an SSL client) connects to an application server on a remote host. It helps to prevent man-in-the-middle attacks.
WebLogic Server includes two host name verifiers, described in the following sections:
As an alternative to the host name verifiers available from WebLogic Server, you can use a custom host name verifier. For information, see Using a Custom Host Name Verifier.
The default WebLogic Server host name verifier is enabled by default.
As a function of the SSL handshake, WebLogic Server compares the common name in the SubjectDN in the SSL server's digital certificate with the host name of the SSL server used to accept the SSL connection. If these names do not match exactly, the SSL connection is dropped. The SSL client is the actual party that drops the SSL connection if the names do not match.
If anything other than the default behavior is desired, either turn off host name verification or configure a custom host name verifier. Turning off host name verification leaves WebLogic Server vulnerable to man-in-the-middle attacks. Oracle recommends leaving host name verification on in production environments.
If you are using the default WebLogic Server host name verifier, host name verification passes if both of the following conditions exist:
The host name in the certificate matches the local machine's host name.
The URL specifies localhost, 127.0.01, or the default IP address of the local machine.
Note:
If you are using the demo identity certificates in a multi-server domain, Managed Server instances will fail to boot if they are started using the fully-qualified DNS name of the Administration Server. For information about this limitation and suggested workarounds, see Limitation on CertGen Usage.The default host name verifier is configured by default. No action is needed to use it.
For more information, see the following topics in Oracle WebLogic Server Administration Console Online Help:
If WebLogic Server is installed on a Mac OS X platform that is running in a network in which the DHCP server assigns host names, by default Mac OS X dynamically overrides the host name set on your machine, using the one assigned by DHCP. Consequently, if you have generated demo identity certificates, host name verification may fail if the host name in your certificate does not match the one that has been dynamically reassigned to your machine. This host name reassignment can occur frequently, such as whenever the network is restarted.
To use demo identity certificates with WebLogic Server on Mac OS X platforms, do one of the following:
Disable host name verification (not recommended if operating in a production environment).
Prior to installing WebLogic Server, set a fixed host name on your machine. Depending on your environment, you may be able to do this by changing the value of the HOSTNAME property in /etc/hostconfig from -AUTOMATIC- to the name you wish to assign. For example:
HOSTNAME=mymachine.mydomain.com
In addition, you may also verify that your desired host name is set in the file /Library/Preferences/SystemConfiguration/preferences.plist. For more information, consult the Mac OS X documentation for your platform.
In addition to the default WebLogic Server host name verifier, WebLogic Server includes an alternative host name verifier called the wildcarded host name verifier. The wildcarded host name verifier works the same as the default WebLogic Server host name verifier; however, the wildcarded host name verifier also accepts the following additional SSL session certificates:
Certificates that contain the asterisk wildcard character (*) in the host name that is obtained from the certificate's Subject CommonName attribute (that is, the CN domain)
SubjectAlternativeName dnsName (SAN) certificates
If the host name in the SSL session certificate contains a wildcard character that meets the following criteria, the certificate is accepted by the wildcarded host name verifier:
The host name contains at least two dot (.) characters.
The host name begins with an asterisk (*) and does not contain any additional asterisks.
When the asterisk (*) is stripped from the CN string, the remaining string must:
Represent the domain.
Include a leading dot (.) character .
Be identical to the ending string of the incoming request domain.
Not include an additional dot (.) character. (This prevents the wildcard from representing subdomains.
If the host name in the SSL session certificate does not exactly match the expected server name attribute, and the host name also cannot successfully be validated in accordance with the wildcard acceptance criteria, the wildcarded host name verifier attempts to validate the SAN extensions.
The SAN extensions are obtained from the SSL session certificate. The SAN extension values are iterated using a case-insensitive match. For any iterated value, if the dnsName attribute in the certificate matches the request URL, host name verification succeeds.
The wildcarded host name verifier class name is weblogic.security.utils.SSLWLSWildcardHostnameVerifier. To configure the wildcarded host name verifier, specify this class as a custom host name verifier in the Servers: Configuration: SSL page of the Administration Console. The wildcarded host name verifier has no parameters with which it must be configured. For more information, see "Configure a custom host name verifier" in the Oracle WebLogic Server Administration Console Online Help.
The class that implements the custom host name verifier must be specified in the CLASSPATH of WebLogic Server (when acting as an SSL client) or a standalone SSL client.
For more information, see "Configure a custom host name verifier" in Oracle WebLogic Server Administration Console Online Help.
When making an outbound two-way SSL connection, WebLogic Server by default uses its server certificate to establish its identity as a client. However, you can alternatively specify a separate client certificate to establish identity instead. This capability is particularly useful when WebLogic Server is acting as a client making two-way SSL connection.
Note:
Switching WebLogic Server's identity to a client certificate is supported only when making an outbound two-way SSL connection. For inbound SSL connections, where Weblogic Server is acting as an SSL server, the server certificate is always used for identity.To use this capability, do the following:
Add a client certificate to WebLogic Server's identity keystore and note the name of the alias under which the private key and public certificate are stored. This needs to be done only once. After completing the following steps, the ability to use a client identity for making an outbound two-way SSL connection is always available for the current WebLogic Server instance.
To add a client certificate to the identity keystore, complete the following steps:
Create a client key pair (a public key and associated private key) and an alias for the private key and store it the WebLogic Server identity keystore. You can do this using the keytool utility.
Generate a Certificate Signing Request (CSR) and submit it to a certificate authority (CA), who returns the CA-signed client certificate. Oracle recommends using the same CA as for the server certificate so that both certificates have the same trusted root CA.
Store the CA-signed client certificate in the identity keystore. (If the client certificate is signed by the same CA as the server certificate, you can skip the step of storing the root CA certificate in the trust keystore because it is already there.
To initiate an outbound two-way SSL connection using the client certificate, create a WLST script that does the following:
Connects to the WebLogic Server instance.
Sets the SSLMBean.UseServerCerts attribute to true, which establishes the server identity for the outbound connection.
Switches to the identity of the client certificate by setting the SSLMBean.UseClientCertForOutbound attribute to true.
Specifies the client certificate private key passphrase, using the SSLMBean.ClientCertPrivateKeyPassPhrase attribute, and the client certificate keystore alias, using the SSLMBean.ClientCertAlias attribute.
See Example 12-1 for an example of this WLST script.
Example 12-1 Sample WLST Script that Initiates an Outbound Two-Way SSL Connection Using a Client Identity
url="t3://localhost:7001" adminUsername="weblogic" adminPassword="password" connect(adminUsername, adminPassword, url) edit() server=cmo.lookupServer('myserver') cd('Servers') cd('myserver') startEdit() cd('SSL') cd('myserver') ssl = server.getSSL() ssl.setUseServerCerts(true) ssl.setUseClientCertForOutbound(true) ssl.setClientCertAlias("myClientCert") ssl.setClientCertPrivateKeyPassPhrase("myClientCertPrivateKeyPassPhrase") save() activate() disconnect() exit()
To restore use of the server identity certificate for outbound SSL connections, enter a WLST command that sets the SSLMBean.UseClientCertForOutbound attribute to false.
Note the following:
Note that the values of the SSLMBean.ClientCertPrivateKeyPassPhrase and SSLMBean.ClientCertAlias attributes are persisted and are used the next time an outbound two-way SSL connection using a client identity is made (that is, the next time the SSLMBean.UseClientCertForOutbound attribute is set to true).
The SSLMBean attributes used for specifying a client certificate for outbound SSL connections are not available from the WebLogic Server Administration Console.
SSL debugging provides more detailed information about the SSL events that occurred during an SSL handshake. The SSL debug trace displays information about:
Trusted certificate authorities
SSL server configuration information
Server identity (private key and digital certificate)
The encryption strength that is allowed
Enabled ciphers
SSL records that were passed during the SSL handshake
SSL failures detected by WebLogic Server (for example, trust and validity checks and the default host name verifier)
I/O related information
SSL debugging dumps a stack trace whenever an ALERT is created in the SSL process. The types and severity of the ALERTS are defined by the Transport Layer Security (TLS) specification.
The stack trace dumps information into the log file where the ALERT originated. Therefore, when tracking an SSL problem, you may need to enable debugging on both sides of the SSL connection (on both the SSL client or the SSL server). The log file contains detailed information about where the failure occurred. To determine where the ALERT occurred, confirm whether there is a trace message after the ALERT. An ALERT received after the trace message indicates the failure occurred on the peer. To determine the problem, you need to enable SSL debugging on the peer in the SSL connection.
When tracking an SSL problem, review the information in the log file to ensure:
The correct config.xml file was loaded
The setting for domestic, or export, is correct
The trusted certificate authority was valid and correct for this server.
The host name check was successful
The certificate validation was successful
Note:
Sev 1 type 0 is a normal close ALERT, not a problem.Use the following command-line properties to enable SSL debugging:
-Djavax.net.debug=all -Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true
Note the following:
The -Djavax.net.debug=all property enables debug logging within the JSSE-based SSL implementation.
The -Dssl.debug=true and -Dweblogic.StdoutDebugEnabled=true command-line properties enable debug logging of the SSL calling code within Weblogic Server.
You can include SSL debugging properties in the start script of the SSL server, the SSL client, and the Node Manager. For a Managed Server started by the Node Manager, specify this command-line argument on the Remote Start page for the Managed Server.
For information about using WebLogic logging properties with the JSSE SSL logging system, see Using Debugging with JSSE SSL.
For information about debugging utilities available for JSSE, see "Debugging Utilities" in the Java™ Secure Socket Extension (JSSE) Reference Guide, available at the following URL:
http://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug
WebLogic Server allows SSL sessions to be cached. Those sessions live for the life of the server.
Clients that use SSL sockets directly can control the SSL session cache behavior. The SSL session cache is specific to each SSL context. All SSL sockets created by SSL socket factory instances returned by a particular SSL context can share the SSL sessions.
Clients default to resuming sessions at the same IP address and port. Multiple SSL sockets that use the same host and port share SSL sessions by default, assuming the SSL sockets are using the same underlying SSL context.
Clients that are not configured to use SSL sessions must call setEnableSessionCreation(false) on the SSL socket to ensure that no SSL sessions are cached. This setting only controls whether an SSL session is added to the cache; it does not stop an SSL socket from finding an SSL session that was already cached. For example, SSL socket 1 caches the session, SSL socket 2 sets setEnableSessionCreation to false but it can still reuse the SSL session from SSL socket 1 because that session was put in the cache.
SSL sessions exist for the lifetime of the SSL context; they are not controlled by the lifetime of the SSL socket. Therefore, creating a new SSL socket and connecting to the same host and port used by a previous session can resume a previous session as long as you create the SSL socket using an SSL socket factory from the SSL context that has the SSL session in its cache.
By default, clients that use HTTPS URLs get a new SSL session for each URL because each URL uses a different SSL context and therefore SSL sessions can not be shared or reused. You can retrieve the SSL session by using the weblogic.net.http.HttpsClient class or the weblogic.net.http.HttpsURLConnection class. Clients can also resume URLs by sharing a SSLSocket Factory between them.
Session caching is maintained by the SSL context, which can be shared by threads. A single thread has access to the entire session cache, not just one SSL session, so multiple SSL sessions can be used and shared in a single (or multiple) thread.
You can use the weblogic.security.SSL.sessionCache.ttl command-line argument to modify the default server-session time-to-live for SSL session caching. For information, see "SSL" in Command Reference for Oracle WebLogic Server. Note that the weblogic.security.SSL.sessionCache.size command-line argument is ignored.
Use SSL to protect Internet Interop-Orb-Protocol (IIOP) connections to Remote Method Invocation (RMI) remote objects. SSL secures connections through authentication and encrypts the data exchanged between objects.
To use SSL to protect RMI over IIOP connections:
Configure WebLogic Server to use SSL.
Configure the client Object Request Broker (ORB) to use SSL. Refer to the product documentation for your client ORB for information about configuring SSL.
Use the host2ior utility to print the WebLogic Server IOR to the console. The host2ior utility prints two versions of the interoperable object reference (IOR), one for SSL connections and one for non-SSL connections. The header of the IOR specifies whether or not the IOR can be used for SSL connections.
Use the SSL IOR when obtaining the initial reference to the CosNaming service that accesses the WebLogic Server JNDI tree.
For more information about using RMI over IIOP, see Developing RMI Applications for Oracle WebLogic Server.
WebLogic Server ensures that each certificate in a certificate chain was issued by a certificate authority. All X509 V3 CA certificates used with WebLogic Server must have the Basic Constraint extension defined as CA, thus ensuring that all certificates in a certificate chain were issued by a certificate authority. By default, any certificates for certificate authorities not meeting this criteria are rejected. This section describes the command-line argument that controls the level of certificate validation.
Notes:
Note the following:Weblogic Server uses RSA Cert-J 3.1 for certain certificate processing.
If WebLogic Server is booted with a certificate chain that will not pass the certificate validation, an information message is logged noting that clients could reject it.
By default WebLogic Server rejects any certificates in a certificate chain that do not have the Basic Constraint extension defined as CA. However, you may be using certificates that do not meet this requirement or you may want to increase the level of security to conform to the IETF RFC 2459 standard. Use the following command-line argument to control the level of certificate validation performed by WebLogic Server:
-Dweblogic.security.SSL.enforceConstraints=option
Table 12-1 describes the options for the command-line argument.
Table 12-1 Options for -Dweblogic.security.SSL.enforceConstraints
| Option | Description |
|---|---|
|
|
Use this option to ensure that the Basic Constraints extension on the CA certificate is defined as CA. For example: -Dweblogic.security.SSL.enforceConstraints=strong or -Dweblogic.security.SSL.enforceConstraints=true By default, WebLogic Server performs this level of certificate validation. |
strong_nov1cas |
Functions the same as the For example: -Dweblogic.security.SSL.enforceConstraints=strong_nov1cas |
strict |
Use this option to ensure the Basic Constraints extension on the CA certificate is defined as CA and set to critical. This option enforces the IETF RFC 2459 standard. For example: -Dweblogic.security.SSL.enforceConstraints=strict This option is not the default because a number of commercially available CA certificates do not conform to the IETF RFC 2459 standard. |
strict_nov1cas |
Functions the same as the For example: -Dweblogic.security.SSL.enforceConstraints=strict_nov1cas |
off |
Use this option to turn off checking for the Basic Constraints extension. The rest of the certificate is still validated. For example: -Dweblogic.security.SSL.enforceConstraints=off Oracle does not recommend using this option in a production environment. Instead, purchase new CA certificates that comply with the IETF RFC 2459 standard. CA certificates from most commercial certificate authorities should work with the default strong option. |
WebLogic Server offers limited support for Certificate Policy Extensions in X.509 certificates. Use the weblogic.security.SSL.allowedcertificatepolicyids argument to provide a comma separated list of Certificate Policy IDs. When WebLogic Server receives a certificate with a critical Certificate Policies Extension, it verifies whether any Certificate Policy is on the list of allowed certificate policies and whether there are any unsupported policy qualifiers. This release of WebLogic Server supports Certification Practice Statement (CPS) Policy qualifiers and does not support User Notice qualifiers. A certificate is also accepted if it contains a special policy anyPolicy with the ID 2.5.29.32.0, which indicates that the CA does not wish to limit the set of policies for this certificate.
Note:
Theweblogic.security.SSL.allowedcertificatepolicyids argument is currently not supported in WebLogic Server when the JSSE-based SSL implementation is enabled.To enable acceptance of Certificate Policies, start WebLogic Server with the following argument:
-Dweblogic.security.SSL.allowedcertificatepolicyids <identifier1>,<identifier2>,...
This argument should contain a comma-separated list of Certificate Policy identifiers for all the certificates with critical extensions that might be present in the certificate chain, back to the root certificate, in order for WebLogic Server to accept such a certificate chain.
Use the WebLogic Server ValidateCertChain command-line utility to confirm whether an existing certificate chain will be rejected by WebLogic Server. The utility validates certificate chains from PEM files, PKCS-12 files, PKCS-12 keystores, and JKS keystores. A complete certificate chain must be used with the utility. The following is the syntax for the ValidateCertChain command-line utility:
java utils.ValidateCertChain -file pemcertificatefilename java utils.ValidateCertChain -pem pemcertificatefilename java utils.ValidateCertChain -pkcs12store pkcs12storefilename java utils.ValidateCertChain -pkcs12file pkcs12filename password java utils.ValidateCertChain -jks alias storefilename [storePass]
Example of valid certificate chain:
java utils.ValidateCertChain -pem zippychain.pem Cert[0]: CN=zippy,OU=FOR TESTING ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US Cert[1]: CN=CertGenCAB,OU=FOR TESTING ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US Certificate chain appears valid
Example of invalid certificate chain:
java utils.ValidateCertChain -jks mykey mykeystore Cert[0]: CN=corba1,OU=FOR TESTING ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US CA cert not marked with critical BasicConstraint indicating it is a CA Cert[1]: CN=CACERT,OU=FOR TESTING ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US Certificate chain is invalid
WebLogic Server SSL has built-in certificate validation. Given a set of trusted CAs, this validation:
Verifies that the last certificate in the chain is either a trusted CA or is issued by a trusted CA.
Completes the certificate chain with trusted CAs.
Verifies the signatures in the chain.
Ensures that the chain has not expired.
You can use certificate lookup and validation (CLV) providers to perform additional validation on the certificate chain. WebLogic Server includes two CLV providers:
WebLogic CertPath Provider—Completes certificate paths and validates certificates using the trusted CA configured for a particular server instance, providing the same functionality as the built-in SSL certificate validation. This is configured by default.
Certificate Registry—The system administrator makes a list of trusted CA certificates that are allowed access to the server; a certificate is valid if the end certificate is in the registry. The administrator revokes a certificate by removing it from the certificate registry, which is an inexpensive mechanism for performing revocation checking. This is not configured by default.
Alternatively, you can write a custom CertPathValidator to provide additional validation on the certificate chain. See "CertPath Providers" in Developing Security Providers for Oracle WebLogic Server.
Outbound SSL and two-way inbound SSL in a WebLogic Server instance receive certificate chains during the SSL handshake that must be validated. An example of two-way inbound SSL is a browser connecting to a Web application over HTTPS where the browser sends the client's certificate chain to the Web application. The inbound certificate validation setting is used for all two-way client certificate validation in the server.
Examples of WebLogic Server using outbound SSL (that is, acting as an SSL client) include:
Connecting to the Node Manager
Connecting to another WebLogic Server instance over the Administration port
Connecting to an external LDAP server, such as the LDAPAuthenticator
Using the Administration Console or WLST, you can independently configure inbound and outbound SSL certificate validation using these SSLMBean attributes: InboundCertificateValidation and OutboundCertificateValidation.
Legal values for both attributes are:
BUILTIN_SSL_VALIDATION: Use the built-in SSL certificate validation code to complete and validate the certificate chain. That is, configure SSL to work as it has in previous releases. This is the default behavior.
BUILTIN_SSL_VALIDATION_AND_CERT_PATH_VALIDATORS: Use the built-in trusted CA-based validation and the configured CertPathValidator providers to perform additional validation. That is, configure SSL to work as it has in previous releases and to do extra validation.
See:
"SSLMBean" in the MBean Reference for Oracle WebLogic Server
"Set Up SSL" in the Oracle WebLogic Server Administration Console Online Help
If SSL communications that worked properly in a previous release of WebLogic Server start failing unexpectedly, the likely problem is that the certificate chain is failing the validation.
Determine where the certificate chain is being rejected, and decide whether to update the certificate chain with one that will be accepted, or change the setting of the -Dweblogic.security.SSL.enforceConstraints command-line argument.
To troubleshoot problems with certificates, use one of the following methods:
If you know where the certificate chains for the processes using SSL communication are located, use the ValidateCertChain command-line utility to check whether the certificate chains will be accepted.
Turn on SSL debug tracing on the processes using SSL communication. The syntax for SSL debug tracing is:
-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true
Note:
Additional detailed debug logging may be enabled using the following command-line property:-Djavax.net.debug=all
For more information, see Command-Line Properties for Enabling SSL Debugging.
The following message indicates the SSL failure results from problems in the certificate chain:
<CA certificate rejected. The basic constraints for a CA certificate were not marked for being a CA, or were not marked as critical>
When you use one-way SSL, look for this error in the client log. With two-way SSL, look for this error in the client and server logs.
Note:
Java Cryptography Extension (JCE) providers are written using the application programming interfaces (APIs) in the JCE. This type of provider is different from the providers written using the WebLogic Security Service Provider Interfaces (SSPIs).WebLogic Server supports the use of the following JCE providers:
The RSA JCE Provider. As of WebLogic Server version 12.1.2, the RSA JCE provider is included with WebLogic Server. The RSA JCE provider (Crypto-J 5.0) is located in cryptoj.jar, which is in the WebLogic Server classpath by default.
The RSA CryptoJ documentation describes three ways to use the RSA's JCE Provider:
Static registration (for example, by editing java.security).
security.provider.1=com.rsa.jsafe.provider.JsafeJCE
Dynamic registration at runtime.
// Create a Provider object Provider jceProvider = new com.rsa.jsafe.provider.JsafeJCE(); // Add the JCE Provider class to the current list of providers available on the system. Security.insertProviderAt (jceProvider, 1);
Use the RSA's JCE provider directly without registration.
// Create a Provider object.
Provider jceProvider = new com.rsa.jsafe.provider.JsafeJCE();
// Pass the provider into the getInstance call.
Cipher cipher = Cipher.getInstance("AES", jceProvider);
The JDK JCE provider (SunJCE). For more information about the features in SunJCE, see the Java™ Cryptography Architecture (JCA) Reference Guide at http://docs.oracle.com/javase/7/docs/technotes/guides/security/crypto/CryptoSpec.html.
The JCA framework includes an ability to enforce restrictions regarding the cryptographic algorithms and maximum cryptographic strengths available to applets/applications in different jurisdiction contexts (locations). Any such restrictions are specified in "jurisdiction policy files". For more information, see the Java™ Cryptography Architecture (JCA) Reference Guide.
WebLogic Server will continue to control the strength of the cryptography used by the WebLogic Server Application Programming Interfaces (APIs). Client code without the appropriate domestic strength cryptography setting will only be able to use the Java SE export strength default cryptography. On the server, WebLogic Server will enable either export or domestic strength cryptography.
The nCipher JCE provider. See http://www.ncipher.com.
SSL is a key component in the protection of resources available in Web servers. However, heavy SSL traffic can cause bottlenecks that affect the performance of Web servers. JCE providers like nCipher that use a hardware card for encryption offload SSL processing from Web servers, which frees the servers to process more transactions. They also provide strong encryption and cryptographic processes to preserve the integrity and secrecy of keys.
To install the nCipher JCE provider:
Install and configure the hardware for the nCipher JCE provider according to the product's documentation.
Install the files for the nCipher JCE provider. The following files are required:
Jurisdiction policy files—The JDK installs these files by default but they are of limited export strength.
Certificate that signed the JAR file
Note:
This step may have been performed as part of installing the hardware for nCipher JCE provider. In that case, verify that the files are correctly installed.The JCE provider JAR files
Choose an installation method for the files:
Install files as an extension. Copy the files to one of the following locations:
JAVA_HOME/jre/lib/ext
For example:
ORACLE_HOME/jdk7_10/jre/lib/ext
Install files in the CLASSPATH of the server.
Edit the Java security properties file (java.security) to add the nCipher JCE provider to the list of approved JCE providers for WebLogic Server. The Java security properties file is located in:
JAVA_HOME/jre/lib/security/java.security
Specify the nCipher JCE provider as:
security.provider.n=com.ncipher.provider.km.mCipherKM
where n specifies the preference order that determines the order in which providers are searched for requested algorithms when no specific provider is requested. The order is 1-based; 1 is the most preferred, followed by 2, and so on.
The nCipher JCE provider must follow the RSA JCA provider in the security properties file. For example:
security.provider.1=sun.security.provider.Sun security.provider.2=sun.security.rsa.SunRsaSign security.provider.3=com.ncipher.provider.km.mCipherKM
Boot WebLogic Server.
To ensure the nCipher JCE provider is working properly, enable debugging according to the nCipher product documentation.
At the start of the SSL handshake, the SSL peers determine the highest protocol version both peers support. However, you can configure Weblogic Server to limit the lowest supported versions of SSL and TLS that are enabled for SSL connections.
To specify the SSL and TLS versions enabled for the SSL handshake, you can set either of the following system properties in the command-line argument that starts WebLogic Server:
weblogic.security.SSL.protocolVersion
weblogic.security.SSL.minimumProtocolVersion
Note the following regarding SSL protocol support in WebLogic Server:
When the JSSE-based SSL implementation is enabled (see Using the JSSE-Based SSL Implementation), SSL protocol support is dependent on the JSSE provider that is installed.
When WebLogic Server is acting as an SSL server, the protocol that the client specifies as preferred in its client hello message is used, if supported.
WebLogic Server does not support SSL V2.0.
The following sections explain how to use these two system properties:
Using the weblogic.security.SSL.protocolVersion System Property
Using the weblogic.security.SSL.minimumProtocolVersion System Property
While in most cases the most recent version of the SSL or TLS protocol is desirable, peers may not support it. You may want to specify the enabled SSL or TLS protocol based on circumstances (compatibility, SSL performance, and environments with maximum security requirements) that make the TLS V1 protocol more desirable for enabling acceptable SSL and TLS protocols. Specifying the weblogic.security.SSL.protocolVersion system property in a command-line argument that starts WebLogic Server lets you specify the protocol that is used for SSL connections.
The following command-line arguments can be specified so that WebLogic Server supports only SSL V3.0 or TLS connection.
-Dweblogic.security.SSL.protocolVersion=SSL3—Only SSL V3.0 messages are sent and accepted. Attempts by clients to establish connections with a prior SSL version will be denied by WebLogic Server, with a denial message returned to the client.
-Dweblogic.security.SSL.protocolVersion=TLS1— This property value enables any protocol starting with "TLS" for messages that are sent and accepted; for example, TLS V1.0, TLS V1.1, and TLS V1.2.
-Dweblogic.security.SSL.protocolVersion=ALL—This is the default behavior. If ALL is selected, the default depends on the JSSE provider and JDK version. For the supported protocol version table for Sun JSSE, see http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider.
Note the following:
The SSL V3.0 and TLS V1 protocols can not be interchanged. Use only the TLS V1 protocol if you are certain all desired SSL clients are capable of using the protocol.
The SSL version SSLv2Hello is one of the protocols enabled by default and is enabled only under the following conditions:
You do not explicitly set any values for the weblogic.security.SSL.protocolVersion or weblogic.security.SSL.minimumProtocolVersion system properties.
You set the weblogic.security.SSL.protocolVersion=ALL system property.
Not setting the weblogic.security.SSL.protocolVersion system property enables the SSLv2Hello, SSLv3, and TLSv1 protocols. In addition, for JSSE, all versions starting with "TLS" are also enabled.
If you set valid, supported protocols for the weblogic.security.SSL.minimumProtocolVersion system property, the protocol value you set for weblogic.security.SSL.protocolVersion is ignored.
Caution:
If you specify theTLS1 or ALL value in this system property, all versions of TLS V1 supported by the SSL provider are enabled for use in SSL connections. The JSSE-based implementation supports TLS V1.0, TLS V1.1, and TLS V1.2. Oracle recommends the use of TLS V1.1 or later in a production environment, which is available by using the weblogic.security.SSL.minimumProtocolVersion system property. For more information, see Using the weblogic.security.SSL.minimumProtocolVersion System Property.In a production environment, Oracle recommends TLS V1.1, or later, for sending and receiving messages in an SSL connection:
To control the minimum versions of SSL V3.0 and TLS V1 that are enabled for SSL connections, set the weblogic.security.SSL.minimumProtocolVersion=protocol system property as an option in the command line that starts WebLogic Server. This system property accepts one of the following values for protocol:
| Value | Description |
|---|---|
SSLv3 |
Specifies SSL V3.0 as the minimum protocol version enabled in SSL connections. |
TLSv1 |
Specifies TLS V1.0 as the minimum protocol version enabled in SSL connections. |
TLSvx.y
|
Specifies TLS Vx.y as the minimum protocol version enabled in SSL connections, where:
For example, |
The specific protocols that are enabled by each of the values you can specify for the weblogic.security.SSL.minimumProtocolVersion system property depend upon the SSL implementation with which WebLogic Server is configured. The next section identifies these protocols for the JSSE-based SSL implementation available in WebLogic Server
When WebLogic Server is configured to use the JSSE-based SSL implementation and you specify a minimum protocol version using the weblogic.security.SSL.minimumProtocolVersion system property, the specific SSL and TLS protocols that are enabled depend on the protocols that are supported in the SSL implementation, as follows:
If the particular minimum protocol version you specify is supported, WebLogic Server enables that protocol version and all later protocol versions that are supported.
For example:
| If you specify . . . | . . . and the JSSE-based SSL implementation supports . . . | . . . the following protocols are enabled |
|---|---|---|
TLSv1 |
SSLv2HelloFoot 1 SSLv3 TLSv1 TLSv1.1 TLSv1.2 |
TLSv1 TLSv1.1 TLSv1.2 |
Footnote 1 The SSLv2Hello protocol is never enabled in the JSSE-based SSL implementation when using the weblogic.security.SSL.minimumProtocolVersion system property, even though it may be supported.
If the particular minimum protocol version you specify is not supported, Weblogic Server enables the next lower protocol and all later protocols that are supported. Note that the lowest protocol will be limited to SSLv3. That is, SSLv2Hello will not be enabled, even though it may be the next lowest protocol.
For example:
| If you specify . . . | . . . and the JSSE-based SSL implementation supports . . . | . . . the following protocols are enabled |
|---|---|---|
TLSv1 |
SSLv2HelloFootref 1 SSLv3 TLSv1.1 TLSv1.2 |
SSLv3 TLSv1.1 TLSv1.2 |
If the exact minimum protocol you specify is not supported, and no older (lower) protocol is supported that is SSLv3 or higher, WebLogic Server enables all newer (higher) supported versions. This case usually applies when SSLv3 is set as the minimum; SSLv2Hello is not valid as the next lowest protocol, so only the available later protocols are enabled.
For example:
| If you specify . . . | . . . and the JSSE-based SSL implementation supports . . . | . . . the following protocols are enabled |
|---|---|---|
SSLv3 |
SSLv2HelloFootref 1 TLSv1 TLSv1.1 TLSv1.2 |
TLSv1 TLSv1.1 TLSv1.2 |
If the particular minimum protocol you specify is invalid, WebLogic Server enables SSLv3 and all later protocol versions that are supported.
For example:
| If you specify . . . | . . . and the JSSE-based SSL implementation supports . . . | . . . the following protocols are enabled |
|---|---|---|
TSLv0 |
SSLv2HelloFootref 1 SSLv3 TLSv1 TLSv1.1 TLSv1.2 |
SSLv3 TLSv1 TLSv1.1 TLSv1.2 |
The JSSE-based SSL implementation is enabled by default in Weblogic Server.
Notes:
Note the following:As of WebLogic Server version 12.1.1, JSSE is the only SSL implementation that is supported. The Certicom-based SSL implementation is removed and is no longer supported in WebLogic Server.
SHA-2 signed certificates are supported in the JSSE SSL implementation provided in WebLogic Server.
Although JSSE supports Server Name Indication (SNI) in its SSL implementation, WebLogic Server does not support SNI.
The following topics explain how to use the JSSE-based SSL implementation and describe key differences with the Certicom-based implementation:
Table 12-2 shows the differences in how the JSSE-based SSL implementation handles the WebLogic system properties.
Table 12-2 System Properties Differences
| System Property | JSSE Applicability | Description |
|---|---|---|
weblogic.security.SSL.ignoreHostnameVerification |
This property continues to work and is not affected by the JSSE integration. |
Does not verify the hostname in the URL to the hostname in the certificate. |
weblogic.ReverseDNSAllowed |
This property continues to work and is not affected by the JSSE integration. |
If set to true then use reverse DNS lookup to figure out if |
weblogic.security.SSL.trustedCAKeyStore |
This property continues to work and is not affected by the JSSE integration. |
Loads the trusted CA certificates from that keystore. |
weblogic.security.SSL.verbose |
Use this property in combination with |
For additional SSL debugging when |
ssl.debug=true |
Use this property in combination with |
Displays SSL debug information to the console or logs. This property is for the calling WebLogic code. The JSSE-based SSL implementation has its own logging system, which is activated by the Note: You can set JSSE logging ( |
weblogic.security.SSL.disableJsseCipherSuiteAliases=true|false |
The default is |
Disables the conversion of Certicom cipher suite names to For a list of Certicom cipher suite names and their |
weblogic.security.SSL.ignoreHostnameVerify |
This property continues to work and is not affected by the JSSE integration. |
See |
weblogic.security.SSL.HostnameVerifier=classname
|
This property continues to work and is not affected by the JSSE integration. |
Specifies the class name of a custom hostname verification class. |
weblogic.security.SSL.protocolVersion=protocol
|
This property continues to work and is not affected by the JSSE integration. The supported protocol values are mapped to the corresponding protocols supported by JSSE. |
|
|
One of the following:
|
If this setting is enabled, these two null ciphers are added to the cipher list. |
By default, this control is not set and the use of a null cipher is not allowed on the server. In such a configuration, if the SSL clients want to use the null cipher suite (by indicating If you set this control, the null cipher suite (for example, Caution: Do not set this control in a production environment unless you are aware of the implications and consequences of doing so. |
weblogic.security.SSL.enforceConstraints=option
|
|
Ensures that the Basic Constraints extension on the CA certificate is defined as CA. See Controlling the Level of Certificate Validation. |
weblogic.security.SSL.allowedcertificatepolicyids |
Not supported. |
WebLogic Server offers limited support for Certificate Policy Extensions in X.509 certificates. See Accepting Certificate Policies in Certificates. |
weblogic.security.SSL.nojce |
Not supported. |
Footnote 1 This WebLogic system property is applicable to both the Certicom and JSSE-based SSL implementations. However, for JSSE, this property affects only the SSL calling code, not the JSSE-based implementation. For more information about the javax.net.debug system property and debugging the JSSE-based SSL implementation, see "Debugging Utilities" in the Java Secure Socket Extension (JSSE) Reference Guide at http://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug.
When WebLogic Server is configured with JDK 7, you may find that the out-of-the-box SSL performance slower than in previous WebLogic Server releases. This performance change is due to the stronger cipher and MAC algorithm used by default when JDK 7 is used with the JSSE-based SSL provider in WebLogic Server. Specifically, AES is used for encryption, and SHA1 is used for hashes. (This cipher combination is typically designated as AES + SHA1 here; that is, cipher + MAC algorithm.)
Previous versions of WebLogic Server used the RC4 and MD5 cipher combination (RC4 + MD5) for SSL connections. In terms of performance, AES + SHA1 is slower than RC4 + MD5. Although AES + SHA1 is recommended, you can configure WebLogic Server to restrict the stronger ciphers and cause RC4 + MD5 to be used instead for SSL. Although RC4 + MD5 is less secure than AES + SHA1, it may be acceptable depending on the security requirements of a particular WebLogic Server environment.
Note:
Oracle strongly recommends the stronger security provided by AES + SHA1 for SSL connections.To configure WebLogic Server to use RC4 + MD5, add the following property to the file JAVA_HOME/jre/lib/security/java.security:
jdk.tls.disabledAlgorithms=AES, DESede, DES, SHA1, SHA
The preceding property disables the stronger ciphers that are used by default for SSL connections and allows RC4 + MD5 to be used instead. For more information about cipher combination priorities in JDK 7, see http://bugs.sun.com/view_bug.do?bug_id=6996365.
This topic includes the following sections:
The set of cipher suites supported by the JDK default JSSE provider, SunJSSE, is available at the following URL:
http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider
For backward compatibility, the JSSE-based SSL implementation accepts Certicom cipher suite names for cipher suites that are compatible with SunJSSE. (See "Cipher Suites" in Understanding Security for Oracle WebLogic Server for a list of Certicom cipher suites.) The Certicom cipher suite names are converted for you to SunJSSE equivalents, usually replacing the "TLS_" prefix with "SSL_", as shown in Table 12-3.
Please keep the following in mind as you consider backward compatibility with Certicom cipher suites:
With JSSE, the cipher suites selected by default are stronger as compared to Certicom SSL and have slower performance. The security policies in your environment typically set the requirements for the cipher suites that must be used. However, for highly secure environments, using the strongest available cipher that provides acceptable performance is recommended.
For operations where enabled or supported cipher suites are returned, both the Certicom and SunJSSE names of the cipher suites are returned. (Note that the weblogic.security.SSL.disableJsseCipherSuiteAliases=true property, described in Table 12-2, disables this behavior.)
For operations where you specify enabled cipher suites, you can use either the equivalent Certicom cipher suite names, or the SunJSSE names. The Certicom cipher suites, and their SunJSSE equivalents, are listed in Table 12-3. (Oracle does not encourage future use of Certicom cipher suite names.)
The _DSS_ cipher suites requires certificates signed with DSS, the Digital Signature Standard defined by NIST FIPS Pub 186. DSA is the key generation scheme as described in FIPS 186.
The _anon_ cipher suites are disabled by default, and cannot be managed from the WebLogic Server Administration Console. You must use WLST instead, as described in Setting Cipher Suites Using WLST: An Example.
To use the Kerberos cipher suites TLS_KRB5_***, you must have KDC accounts set up. See the Java Secure Socket Extension (JSSE) Reference Guide (http://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.html#KRB) for more details on the Kerberos requirements.
The following anonymous ciphers are not supported out-of-the-box in the JSSE-based WebLogic SSL implementation in WebLogic Server:
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA
TLS_DH_anon_WITH_RC4_128_MD5
TLS_DH_anon_WITH_DES_CBC_SHA
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
However, if you want to enable any of the preceding anonymous ciphers, include the following argument in the Java command that starts WebLogic Server:
-Dweblogic.security.SSL.AllowAnonymousCipher=true
In most cases, enabling anonymous ciphers is required when WebLogic Server, or its deployed application, acts as a SSL client that is making an outbound connection to an SSL server (for example, an LDAP server or RDBMS system) that is configured to use anonymous ciphers only. A typical use case is connecting to an Oracle Internet Directory instance that is configured in no-auth mode.
Note:
Oracle does not recommend the use of anonymous ciphers in production environments.By default, Certicom cipher suite names are converted to SunJSSE cipher suite names when WebLogic Server is configured to use the JSSE-based SSL implementation. Table 12-3 lists each cipher suite supported in the (removed) WebLogic Server Certicom SSL implementation and its SunJSSE equivalent. The TLS_ name is the Certicom cipher suite name; the SSL_ name is the equivalent SunJSSE provider cipher suite name.
Table 12-3 Cipher Suite Name Equivalence
| Certicom Cipher Suite | SunJSSE Equivalent Cipher Suite |
|---|---|
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA |
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA |
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA |
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA |
TLS_DHE_DSS_WITH_DES_CBC_SHA |
SSL_DHE_DSS_WITH_DES_CBC_SHA |
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA |
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA |
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA |
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA |
TLS_DHE_RSA_WITH_DES_CBC_SHA |
SSL_DHE_RSA_WITH_DES_CBC_SHA |
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA |
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA |
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 |
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 |
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA |
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA |
TLS_DH_anon_WITH_DES_CBC_SHA |
SSL_DH_anon_WITH_DES_CBC_SHA |
TLS_DH_anon_WITH_RC4_128_MD5 |
SSL_DH_anon_WITH_RC4_128_MD5 |
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA |
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA |
TLS_RSA_EXPORT_WITH_RC4_40_MD5 |
SSL_RSA_EXPORT_WITH_RC4_40_MD5 |
TLS_RSA_WITH_3DES_EDE_CBC_SHA |
SSL_RSA_WITH_3DES_EDE_CBC_SHA |
TLS_RSA_WITH_DES_CBC_SHA |
SSL_RSA_WITH_DES_CBC_SHA |
TLS_RSA_WITH_RC4_128_MD5 |
SSL_RSA_WITH_RC4_128_MD5 |
TLS_RSA_WITH_RC4_128_SHA |
SSL_RSA_WITH_RC4_128_SHA |
The following example shows using a WLST script that sets the cipher suites SSL_RSA_WITH_RC4_128_MD5, SSL_RSA_WITH_RC4_128_SHA, and SSL_RSA_WITH_3DES_EDE_CBC_SHA. After this script is run, the cipher suites are set in the domain configuration (that is, the config.xml file) and the SSL listeners are restarted with the new cipher suite settings.
url="t3://localhost:7001" adminUsername="weblogic" adminPassword="password" connect(adminUsername, adminPassword, url) edit() server=cmo.lookupServer('myserver') cd('Servers') cd('myserver') startEdit() cd('SSL') cd('myserver') ssl = server.getSSL() ciphers = ['SSL_RSA_WITH_RC4_128_MD5', 'SSL_RSA_WITH_RC4_128_SHA', 'SSL_RSA_WITH_3DES_EDE_CBC_SHA'] ssl.setCiphersuites(ciphers) save() activate() disconnect() exit()
As described in SSL Debugging, SSL debugging provides more detailed information about the SSL events that occurred during an SSL handshake and other operations.
If you debug SSL when the JSSE-based SSL implementation is enabled, you can use the logging properties listed and described in Table 12-2. However, some properties affect only the SSL calling code and not the JSSE implementation. The JSSE-based SSL implementation has its own logging system, which is activated by the javax.net.debug property. The javax.net.debug property provides multiple levels of control over the amount of output and can be used independently of WebLogic SSL logging (ssl.debug).
See the "Debugging Utilities" section of the Java Secure Socket Extension (JSSE) Reference Guide, available at the following URL, for more details about the javax.net.debug property:
http://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug
RSA JSSE is a third-party JSSE provider that can be statically registered in the JVM if you wish to use it. To install and configure the RSA JSSE provider, complete the following steps:
Using the following URL, download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files that correspond to the version of your JDK.
http://www.oracle.com/technetwork/java/javase/downloads/index.html
Using a text editor, modify the file JAVA_HOME/jre/lib/security/java.security by making the RSA JSSE provider, com.rsa.jsse.JsseProvider, as the first provider in the list.
For example, before making this update, the list of providers might appear as follows:
# # List of providers and their preference orders (see above): # security.provider.1=sun.security.provider.Sun security.provider.2=sun.security.rsa.SunRsaSign security.provider.3=com.sun.net.ssl.internal.ssl.Provider security.provider.4=com.sun.crypto.provider.SunJCE security.provider.5=sun.security.jgss.SunProvider security.provider.6=com.sun.security.sasl.Provider security.provider.7=org.jcp.xml.dsig.internal.dom.XMLDSigRI security.provider.8=sun.security.smartcardio.SunPCSC security.provider.9=sun.security.mscapi.SunMSCAPI
After you add the RSA JSSE provider, the list might appear as follows:
# # List of providers and their preference orders (see above): # security.provider.1=com.rsa.jsse.JsseProvider security.provider.2=sun.security.provider.Sun security.provider.3=sun.security.rsa.SunRsaSign security.provider.4=com.sun.net.ssl.internal.ssl.Provider security.provider.5=com.sun.crypto.provider.SunJCE security.provider.6=sun.security.jgss.SunProvider security.provider.7=com.sun.security.sasl.Provider security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI security.provider.9=sun.security.smartcardio.SunPCSC security.provider.10=sun.security.mscapi.SunMSCAPI
That is, you need to update the sequence number of each subsequent provider. For example, security.provider.1=sun.security.provider.Sun is changed to security.provider.2=sun.security.provider.Sun (change shown in bold).
Add the SSL-J jar WL_HOME/server/lib/sslj.jar to the Classpath.
Restart WebLogic Server for the change to the RSA JSEE provider to take effect.
WebLogic Server's JSSE implementation supports X.509 certificate revocation (CR) checking, which checks a certificate's revocation status as part of the SSL certificate path validation process. CR checking improves the security of certificate usage by ensuring that received certificates have not been revoked by the issuing certificate authority.
The following sections describe WebLogic Server support for X.509 certificate revocation checking:
Choosing the CR Checking Methods to Be Used by WebLogic Server
Failing SSL Certificate Path Validation if Revocation Status Cannot Be Determined
In WebLogic Server, CR checking can be used for several purposes, including the following:
Inbound SSL — validating client certificates
Outbound SSL — validating server certificates
WebLogic Server's CR checking mechanism includes the following features:
Support for the following certificate revocation methods:
Online Certificate Status Protocol (OCSP)
Certificate revocation lists (CRLs)
You can configure CR checking on a domain-wide basis for all certificate authorities (CAs). And optionally, you can also configure certificate authority overrides for specific CAs.
A certificate authority override contains changes to the domain-wide CR checking configuration that you want to have in effect for certificates that have been issued by a specific CA. For example, you can configure a particular OCSP responder URL to be used, or require SSL certificate path validation to fail if certificate revocation status cannot be determined. Each certificate authority override you create applies to only one specific CA.
CR checking is disabled by default in WebLogic Server. But using either the WebLogic Server Administration Console or WLST, you can enable CR checking and configure the properties described in the sections that follow.
Note:
CR checking is available for a WebLogic Server instance only when JSSE is enabled.In WebLogic Server, CR checking is disabled by default. However, when you enable CR checking, WebLogic Server provides, on a domain-wide basis, a comprehensive set of mechanisms to obtain current revocation status of each certificates it validates. This topic describes the default behavior WebLogic Server provides when you enable CR checking. The subsequent sections explain customizations you can make that can be applied domain-wide or, selectively, to specific certificate authorities.
When the default CR checking configuration is enabled, WebLogic Server automatically does the following when performing SSL certificate path validation:
Checks the OCSP response local cache to obtain certificate revocation status. The OCSP response local cache is an in-memory cache that holds the latest certificate status that is provided by OCSP responders.
Certificate status in OCSP has a specific validity period. If the certificate status has expired, WebLogic Server does the following:
Obtains the OCSP responder URI from the certificate. This URI is included in the Authority Information Access (AIA) value in the certificate, which indicates how to access information and services from the issuer of the certificate.
Submits an OCSP request to the OCSP responder.
The OCSP responder returns an OCSP response, which includes a certificate status of good, revoked, or unknown.
Updates the OCSP response local cache with the OCSP response.
For certificates that have a valid, non-expired entry in the OCSP response local cache, WebLogic Server can obtain its revocation status from the cache instead of requesting a fresh OCSP response. This provides improved performance and reduced use of network bandwidth.
Notes:
Note the following:Cached entries expire based on the OCSP validity period, but the cache behavior can be customized.
The local OCSP response cache is never used when OCSP nonce is enabled. This ensures the freshest response.
If the certificate has an OCSP status of unknown, WebLogic Server checks the CRL local cache for valid CRLs to determine whether the certificate has been revoked. (If either a revoked or not revoked status is determined by OCSP, CRL is not used for the certificate.)
By default, the CRL local cache is a file-based store that is maintained on each server instance in a WebLogic domain and that is updated on demand from CRL distribution points. A CRL distribution point is a network-accessible server that provides CRLs for download.
If no valid CRLs are available in the CRL local cache, WebLogic Server does the following:
Obtains the CRL distribution point URL, which is included in the CRLDistributionPoints extension in the certificate.
Using the CRL distribution point URL, downloads a fresh CRL and adds it to the cache.
Searches the CRL for an entry that corresponds to the certificate.
If the certificate serial number is not found in the CRL from the issuer, the certificate status is set to not revoked.
Note the following:
If the certificate has an OCSP status of revoked, or is included in a valid CRL, WebLogic Server automatically fails SSL certificate path validation.
If the revocation status is unknown or cannot be determined after using OCSP and checking the available CRLs, certificate path validation by default is not failed.
Enabling the default CR checking capability in a WebLogic domain is available through the following MBean attribute:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocMBean.CheckingEnabled |
Specifies whether CR checking is enabled domain-wide. |
False |
For information about how to use the WebLogic Server Administration Console to enable CR checking in a WebLogic domain, see "Enable certificate revocation checking in a domain" in the Oracle WebLogic Server Administration Console Online Help.
You can configure a CA override for this MBean attribute. For information, see Configuring Certificate Authority Overrides.
The default CR checking behavior in WebLogic Server is appropriate for deployment environments in which CR checking is desired, but not required. Depending on your environment, you might require CR checking, or need to enforce behaviors that are specific to particular certificate authorities. Table 12-4 lists and summarizes the types of customizations you can make to CR checking in WebLogic Server and provides links to the sections in which they are explained.
Table 12-4 Customizations You Can Make to the CR Checking Configuration
| Customization | Description |
|---|---|
|
CR checking method order |
Specifies the order in which the supported CR checking methods are used; that is, OCSP and CRLs. Optionally, you can choose to use only OCSP, or only CRLs. See Choosing the CR Checking Methods to Be Used by WebLogic Server. |
|
Require certificate revocation status |
Specifies that SSL certificate path validation must fail if a certificate's revocation status is unknown or cannot be determined. See Failing SSL Certificate Path Validation if Revocation Status Cannot Be Determined . |
|
Domain-wide OCSP settings |
Customize, domain-wide, one or more of the following OCSP features or behaviors:
For information, see Using the Online Certificate Status Protocol. |
|
Domain-wide CRL protocol settings |
Customize, domain-wide, one or more of the following CRL features or behaviors:
For information, see Using Certificate Revocation Lists. |
|
Certificate authority overrides |
Customize the CR checking behavior for certificates issued by a particular CA. For example:
A certificate authority override always takes precedence over domain-wide settings that are in place. For more information, see Configuring Certificate Authority Overrides. |
By default, when checking a certificate's revocation status, WebLogic Server first uses OCSP. If OCSP returns the certificate's status as "unknown," WebLogic Server then uses CRLs. However, you can change the CR checking method used, or the sequence in which the methods are used, to one of the following:
OCSP only
CRLs only
OCSP then CRLs — If the OCSP status for a certificate is returned as unknown, CRLs are checked for certificate status.
CRLs then OCSP — If a certificate's revocation status cannot be determined by checking available CRLs, its OCSP status is checked.
Configuring the CR checking method and order in a WebLogic domain is available through the following MBean attribute:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocMBean.MethodOrder |
Specifies the domain-wide CR checking method. |
OCSP_THEN_CRL |
You can configure a CA override for this MBean attribute. For information, see Configuring Certificate Authority Overrides.
For information about how to use the WebLogic Server Administration Console to configure the CR checking method and order for a WebLogic domain, see "Enable certificate revocation checking in a domain" in the Oracle WebLogic Server Administration Console Online Help.
By default, if an X.509 certificate's revocation status cannot be determined by any of the selected checking methods, the certificate can still be accepted if the SSL certificate path validation is otherwise successful. However, for certificates whose revocation status cannot be determined, you can optionally configure WebLogic Server to fail certificate path validation.
Configuring a WebLogic domain to fail SSL certificate path validation when the revocation status cannot be determined is available through the following MBean attribute:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocMBean.FailOnUnknownRevocStatus |
Specifies on a domain-wide basis whether a certificate's path validation should fail if its revocation status cannot be determined. |
False |
You can configure a CA override for this MBean attribute. For information, see Configuring Certificate Authority Overrides.
For information about how to configure this MBean attribute using the WebLogic Server Administration Console, see "Enable certificate revocation checking in a domain" in the Oracle WebLogic Server Administration Console Online Help.
The Online Certificate Status Protocol (OCSP) is an automated certificate checking network protocol that is defined in RFC 2560. As part of certificate validation, WebLogic Server queries the revocation status of a certificate by issuing an OCSP request to an OCSP responder. Certificate status is maintained by the OCSP responder. Acceptance of the certificate is suspended until the responder returns an OCSP response, indicating whether the certificate is still trusted by the CA that issued it.
OCSP may be used to satisfy some of the operational requirements of providing more timely revocation information than is possible with CRLs and may also be used to obtain additional status information. For more information about OCSP, see the description of RFC 2560 at http://www.ietf.org/rfc/rfc2560.txt.
The following sections describe how to configure OCSP in WebLogic Server:
A nonce is a random number that, when included in an OCSP request, forces a fresh response; pre-signed responses are rejected. The use of nonces can prevent replay attacks. By default, WebLogic Server does not include nonces in OCSP requests.
However, when WebLogic Server is configured to use nonces in OCSP:
WebLogic Server generates a nonce for each OCSP request, and includes it in an extension in the request.
The signed OCSP response must include the same nonce, which is included in an extension in the response.
You can configure the use of OCSP nonces in a WebLogic domain using the following MBean attribute:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocMBean.OcspNonceEnabled |
Specifies whether nonces are generated for OCSP requests. This setting is domain-wide. |
false |
You can also configure CA overrides for this MBean attribute. For information, see Configuring OCSP Properties in a Certificate Authority Override.
For information about how to use the WebLogic Server Administration Console to configure OCSP nonces, see "Configure domain-wide OCSP settings" in the Oracle WebLogic Server Administration Console Online Help.
The response timeout interval limits the wait time for OCSP responses. Setting a timeout interval helps minimize blocked threads and also reduces the system's vulnerability to denial of service attacks. In addition to setting a response timeout interval, you can configure a time tolerance value for handling clock-skew differences between WebLogic Server and OCSP responders.
The default response timeout interval is 10 seconds, with a zero time tolerance. The response timeout interval and time tolerance value can be set domain-wide and, optionally, set specific to one or more CAs.
You can configure the OCSP response timeout interval and time tolerance value for a WebLogic domain using the following MBean attributes:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocMBean.OcspResponseTimeout |
Specifies the domain-wide timeout interval, in seconds, for OCSP responses. The valid range is between 1 and 300, inclusive. |
10 |
CertRevocMBean.OcspTimeTolerance |
Specifies the domain-wide OCSP time tolerance value, in seconds, for OCSP responses. |
0 |
You can also configure CA overrides for these MBean attributes. For information, see Configuring OCSP Properties in a Certificate Authority Override.
For information about how to use the WebLogic Server Administration Console to configure OCSP response timeout interval and time tolerance values, see "Configure domain-wide OCSP settings" in the Oracle WebLogic Server Administration Console Online Help.
To optimize performance and reduce network bandwidth, WebLogic Server's OCSP implementation is configured by default to use a local in-memory cache for holding OCSP responses, called the OCSP response local cache. Cached entries automatically expire based on the OCSP validity period and other criteria, such as entries least accessed. If nonces are enabled, OCSP responses obtained using a nonce are not cached. This ensures the freshest response is always used with nonces.
You can configure the OCSP response local cache in a WebLogic domain using the following MBean attributes:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocMBean.OcspResponseCacheEnabled |
Specifies whether the OCSP response local cache is enabled domain-wide. |
true |
CertRevocMBean.OcspResponseCacheCapacity |
Specifies the maximum number of entries supported by the OCSP response local cache. |
1024 |
CertRevocMBean.OcspResponseCacheRefreshPeriodPercent |
Specifies the refresh period for the OCSP response local cache, expressed as a percentage of the validity period of the response. For example, for a validity period of 10 hours, a value of 10% specifies that after one hour, the cached response expires and a fresh response is required. |
100 |
You can also configure CA overrides for this MBean attribute. For information, see Configuring OCSP Properties in a Certificate Authority Override.
For information about how to use the WebLogic Server Administration Console to configure the OCSP response local cache, see "Configure domain-wide OCSP settings" in the Oracle WebLogic Server Administration Console Online Help.
A certificate revocation list (CRL) is a time-stamped list of digital certificates that have been revoked by the certificate authority (CA) that issued them. Each CRL is signed by a CA and made available in a public repository.
The CRL implementation in WebLogic Server includes support for the following:
CRL local cache, which enables efficient access for CR checking.
Automatic import of user supplied CRL files into the CRL cache.
Use of distribution points from which the CRL cache can optionally be populated and refreshed.
The following sections explain how to configure CRL usage in WebLogic Server:
Updating CRLs from distribution points is enabled by default. If the appropriate CRL for a certificate being validated does not already exist in the local cache, the CRL is downloaded from an available distribution point.
WebLogic Server also allows you to configure a timeout interval for the CRL download from a distribution point. This timeout interval limits the wait time for CRL downloads, and also minimizes the risk of blocked threads and vulnerability to denial of service attacks. Note that if the CRL download times out, the CRL method reports that the revocation status is unknown; however, the CRL download continues in a separate thread until complete and the CRL becomes available for future CRL checking.
You can configure CRL distribution points for a WebLogic domain using the following MBean attributes:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocMBean.CrlDpEnabled |
Specifies whether CRL distribution points are enabled domain-wide. |
true |
CertRevocMBean.CrlDpDownloadTimeout |
Specifies the overall timeout interval, domain-wide, for the distribution point CRL download, expressed in seconds. The valid range is between 1 and 300, inclusive. |
10 |
You can also configure CA overrides for these MBean attributes. For information, see Configuring CRL Properties in a Certificate Authority Override.
For information about how to use the WebLogic Server Administration Console to configure CRL distribution points for a WebLogic domain, see "Configure domain-wide CRL settings" in the Oracle WebLogic Server Administration Console Online Help.
The CRL local cache is automatically enabled in WebLogic Server. Because obtaining CRLs is a time-consuming process, CRLs can be stored, while valid, in local files. In addition, WebLogic Server allows you to configure the refresh interval for the local cache, expressed as a percentage of the validity period of the CRL.
You may supply CRL files to be used by copying them into the following CRL import directory, where server-name represents the name of the WebLogic Server instance:
WL_HOME/servers/server-name/security/certrevocation/crlcache/import
The CRL files are automatically imported and internally cached. This directory is automatically created, if it does not already exist, when CR checking is enabled and an SSL connection is attempted.
Notes:
Note the following:After WebLogic Server is started, the import of the CRL file starts automatically when CR checking is enabled and at least one attempt to check a certificate's revocation status has occurred. This minimizes resource usage until necessary.
After you import CRL files, they are automatically deleted from the import directory.
The CRL local cache configuration settings are domain-wide. You cannot configure a certificate authority override for the CRL local cache.
You can configure the CRL local cache for a WebLogic domain using the following MBean attributes:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocMBean.CrlCacheRefreshPeriodPercent |
Specifies the refresh period for the CRL local cache, expressed as a percentage of the validity period of the CRL. |
100 |
For information about how to use the WebLogic Server Administration Console to configure the CRL local cache for a WebLogic domain, see "Configure domain-wide CRL settings" in the Oracle WebLogic Server Administration Console Online Help.
Configuring certificate authority overrides allows you to specify CR checking behavior that is enforced for certificates issued by a particular CA. A certificate authority override always supersedes the domain-wide CR checking configuration that is enabled. The following sections explain how to configure CR checking CA overrides:
Configuring OCSP Properties in a Certificate Authority Override
Configuring CRL Properties in a Certificate Authority Override
To create a certificate authority override for a specific CA, complete the following steps:
Identify the CA by its distinguished name. This must be the complete issuer distinguished name (defined in RFC 2253) of the certificates for which this override applies.
For example, the distinguished name of the WebLogic Server DemoTrust CA is CN=CertGenCAB, OU=FOR TESTING ONLY, O=MyOrganization, L=MyTown, ST=MyState, C=US.
Specify whether CR checking is enabled for certificates issued by this CA, if necessary.
Specify the CR checking methods and order performed for certificates issued by this CA.
Specify whether SSL certificate path validation should fail if the revocation status of certificates issued by this CA cannot be determined.
Optionally, specify additional OCSP or CRL customizations, as explained in the following sections:
You can configure general certificate authority overrides for a CA by using the following MBean attributes:
| MBean Attribute | Description | Default Value |
|---|---|---|
CertRevocCaMBean.DistinguishedName |
Specifies the distinguished name (DN) of the CA subject. | None (required field) |
CertRevocCaMBean.CheckingDisabled |
For this CA, specifies whether CR checking is disabled. |
false |
CertRevocCaMBean.FailOnUnknownRevocStatus |
For this CA, specifies whether SSL certificate path checking should fail if the certificate revocation status cannot be determined from any of the available methods. | Same as current setting of CertRevocMBean.FailOnUnknownRevocStatus. |
CertRevocCaMBean.MethodOrder |
Specifies the certificate revocation checking method order when checking certificates issued by this CA. | Same as current setting of CertRevocMBean.MethodOrder. |
For information about how to use the WebLogic Server Administration Console to configure certificate authority overrides, see "Configure certificate authority overrides" in the Oracle WebLogic Server Administration Console Online Help
WebLogic Server tries the following trust models in its OCSP implementation:
Delegated Trust Model (DTM) — The OCSP response is signed by an OCSP responder that has been delegated by the CA to sign responses on its behalf.
Explicit Trust Model (ETM) — If neither the CA nor an authority to which OCSP responsibilities have been delegated has signed the OCSP response, an explicitly trusted signer may be specified. ETM is used when you can supply an additional trusted certificate that may be used to verify the OCSP response signature. This can be any certificate, including one unrelated to the CA corresponding to the override. ETM may be used for OCSP responders which are trusted, but are not authorized to sign OCSP responses on behalf of issuers. Explicitly trusted public certificates for OCSP responders may be suitable if the OCSP server is internally maintained within your enterprise.
CA-signed Trust Model — The OCSP response is presumed to be signed by the same CA that issued the certificate for which the revocation status is being requested.
When you create a certificate authority override, WebLogic Server allows you to configure the OCSP properties that are described in Table 12-5. This table also identifies the MBean attributes you can use to configure these override properties.
Table 12-5 OCSP Properties That Can Be Specified in a Certificate Authority Override
| Override | Description | MBean Attribute |
|---|---|---|
|
OCSP responder URL |
Specifies the URL to be used for either:
For more information, see Identifying the OCSP Responder URL. |
CertRevocCaMBean.OcspResponderUrl The default value is none. |
|
How the OCSP responder URL is used |
Specifies how the OCSP responder URL is to be used: for failover or override. |
CertRevocCaMBean.OcspResponderUrlUsage The default value is |
|
OCSP responder certificate subject name |
For this CA, specifies the explicitly trusted OCSP responder certificate subject name. For example, In cases where the subject name alone is not sufficient to uniquely identify the certificate, both the |
CertRevocCaMBean.OcspResponderCertSubjectName The default value is |
|
OCSP responder certificate issuer name |
For this CA, specifies the explicitly trusted OCSP responder certificate issuer name. For example, When this attribute is set, the |
CertRevocCaMBean.OcspResponderCertIssuerName The default value is |
|
OCSP responder certificate serial number |
For this CA, specifies the explicitly trusted OCSP responder certificate serial number. For example, When this attribute is set, the |
CertRevocCaMBean.OcspResponderCertSerialNumber The default value is |
|
OCSP responder Explicit Trust Method |
For this CA, specifies whether the OCSP Explicit Trust model is enabled and how a trusted certificate in the Weblogic Server trust keystore is specified. The following values can be specified:
|
CertRevocCaMBean.OcspResponderExplicitTrustMethod The default value is |
|
Nonce enabled |
For this CA, specifies whether nonces are sent with OCSP requests, which forces a fresh (not pre-signed) response. |
CertRevocCaMBean.OcspNonceEnabled The default value is the same as the current setting for |
|
OCSP response local cache |
For this CA, specifies whether the OCSP response local cache is enabled. |
CertRevocCaMBean.OcspResponseCacheEnabled The default value is the same as the current setting for |
|
OCSP response timeout |
For this CA, specifies the timeout interval for the OCSP response, expressed in seconds. The valid range is between 1 and 300, inclusive. For more information, see Setting the Response Timeout Interval. |
CertRevocCaMBean.OcspResponseTimeout The default value is the same as the current setting for |
|
OCSP time tolerance |
For this CA, specifies the time tolerance value for handling clock-skew differences between WebLogic Server and responders, expressed in seconds. The valid range is between 0 and 900, inclusive. The validity period of the response is extended both into the future and into the past by the specified amount of time, effectively widening the validity interval. |
CertRevocCaMBean.OcspTimeTolerance The default value is the same as the current setting for |
For information about how use the WebLogic Server Administration Console to configure OCSP settings in a certificate authority override, see "Configure certificate authority overrides" in the Oracle WebLogic Server Administration Console Online Help.
To validate a certificate using an OCSP responder lookup, WebLogic Server uses the following methods to determine the OCSP responder URL:
Authority Information Access (AIA) value in the certificate, which indicates how to access information and services for the issuer of the certificate. For example, the AIA contains the URI for the OCSP responder.
Default OCSP responder failover or override — If the OCSP responder URI is not available from the certificate AIA value, or is not acceptable, a default OCSP responder URL can be configured on a per-CA basis.
Additionally, the default OCSP responder URL per CA can be specified selectively for either failover, or for override. When specified for override, this URL always overrides the value obtained from the certificate AIA extension.
For information about how to use the WebLogic Server Administration Console to set the OCSP responder URL in a certificate authority override, see "Configure certificate authority overrides" in the Oracle WebLogic Server Administration Console Online Help.
When you configure a certificate authority override, WebLogic Server allows you to configure the CRL properties listed and described in Table 12-6. This table also identifies the MBean attributes you can use to configure these properties.
Table 12-6 CRL Properties That Can Be Specified in a Certificate Authority Override
| Override | Description | MBean Attribute |
|---|---|---|
|
Use of distribution point to update local CRL cache |
For this CA, specifies whether CRL distribution point processing to update the local CRL cache is enabled. |
CertRevocCaMBean.CrlDpEnabled The default value is the same as the current setting for |
|
Distribution point URL |
For this CA, specifies the CRL distribution point URL to be used for either:
|
CertRevocCaMBean.CrlDpUrl The default value is |
|
How the distribution point URL is used |
Specifies how the distribution point URL is to be used: for failover or override. |
CertRevocCaMBean.CrlDpUrlUsage The default value is |
|
Distribution point CRL download timeout |
For this CA, specifies the overall timeout interval for the distribution point CRL download, expressed in seconds. The valid range is between 1 and 300, inclusive. |
CertRevocCaMBean.CrlDpDownloadTimeout The default value is the same as the current setting for |
For information about how to use the WebLogic Server Administration Console to customize the CRL settings in a certificate authority override, see "Configure certificate authority overrides" in the Oracle WebLogic Server Administration Console Online Help.