Skip Headers
Oracle® Fusion Middleware Securing Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24422-04
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

12 Configuring SSL

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:

SSL: An Introduction

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.

One-Way and Two-Way SSL

SSL can be configured one-way or two-way:

Java Secure Socket Extension (JSSE) SSL Implementation Supported

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://download.oracle.com/javase/6/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 .

Setting Up SSL: Main Steps

To set up SSL:

  1. 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.

  2. 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.

  3. 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 Help.

  4. 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 Help.

    Note:

    FIPS mode is supported for JSSE via the RSA JSSE provider.

    To enable FIPS in JSSE, follow these steps:

    1. 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).

    2. 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:

Using Host Name Verification

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.

Using the Default WebLogic Server Host Name Verifier

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 Help:

Using the Wildcarded Host Name Verifier

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

How the Wildcarded Host Name Verifier Works

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.

Configuring the Wildcarded Host Name Verifier

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 Help.

Using a Custom Host Name Verifier

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 Help.

Specifying a Client Certificate for an Outbound Two-Way SSL Connection

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:

  1. 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:

    1. 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.

    2. 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.

    3. 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.

  2. To initiate an outbound two-way SSL connection using the client certificate, create a WLST script that does the following:

    1. Connects to the WebLogic Server instance.

    2. Sets the SSLMBean.UseServerCerts attribute to true, which establishes the server identity for the outbound connection.

    3. Switches to the identity of the client certificate by setting the SSLMBean.UseClientCertForOutbound attribute to true.

    4. 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="weblogic1"
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:

SSL Debugging

SSL debugging provides more detailed information about the SSL events that occurred during an SSL handshake. The SSL debug trace displays information about:

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:

Command-Line Properties for Enabling SSL Debugging

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://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug

SSL Session Behavior

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.

Configuring RMI over IIOP with SSL

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:

  1. Configure WebLogic Server to use SSL.

  2. Configure the client Object Request Broker (ORB) to use SSL. Refer to the product documentation for your client ORB for information about configuring SSL.

  3. 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.

  4. 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 Programming RMI for Oracle WebLogic Server.

SSL Certificate Validation

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.

Controlling the Level of Certificate Validation

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

strong or true

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 strong option, described in the preceding row, with the additional constraint that X509 version 1 CA certificates are rejected.

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 strict option, described in the preceding row, with the additional constraint that X509 version 1 CA certificates are rejected.

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.


Accepting Certificate Policies in Certificates

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:

The weblogic.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.

Checking Certificate Chains

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

Using Certificate Lookup and Validation Providers

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.

How SSL Certificate Validation Works in 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 Oracle WebLogic Server MBean Reference

  • "Set Up SSL" in the Oracle WebLogic Server Administration Console Help

Troubleshooting Problems with Certificate Validation

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.

Using the nCipher JCE Provider with WebLogic Server

Note:

Java Cryptography Extension (JCE) providers are written using the application programming interfaces (APIs) in the JCE available in JDK 6.0. This type of provider is different from the providers written using the WebLogic Security Service Provider Interfaces (SSPIs). WebLogic Server does not provide a JCE provider by default.

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.

WebLogic Server supports the use of the following JCE providers:

To install the nCipher JCE provider:

  1. Install and configure the hardware for the nCipher JCE provider according to the product's documentation.

  2. 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:

      MW_HOME/jdk160_14/jre/lib/ext
      
    • Install files in the CLASSPATH of the server.

  3. 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
    
  4. Boot WebLogic Server.

  5. To ensure the nCipher JCE provider is working properly, enable debugging according to the nCipher product documentation.

Specifying the Version of the SSL Protocol

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:

Note the following regarding SSL protocol support in WebLogic Server:

The following sections explain how to use these two system properties:

Using the weblogic.security.SSL.protocolVersion 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 6, see http://docs.oracle.com/javase/6/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 the TLS1 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.

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:

  • x is an integer between 1 and 9, inclusive

  • y is an integer between 0 and 9, inclusive

For example, TLSv1.2.


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 following section identifies these protocols for each SSL implementation available in WebLogic Server:

Protocols Enabled with the JSSE-Based SSL Implementation

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:

Note:

To enable support for the TLS V1.1 and TLS V1.2 protocols, WebLogic Server must be running with JDK 7.

  • 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
    

Using the JSSE-Based SSL Implementation

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.

The following topics explain how to use the JSSE-based SSL implementation and describe key differences with the Certicom-based implementation:

System Property Differences Between the JSSE-Based and Certicom SSL Implementations

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 urlhostname is a loopback address (“localhost” or “127.0.0.1”, or the IPV6 equivalent.

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 javax.net.debug=all to get verbose debug output from the SSL calling code and the JSSE-based implementation.Foot 1 

For additional SSL debugging when -Dssl.debug=true is used.

ssl.debug=true

Use this property in combination with javax.net.debug=ssl to get debug output from the SSL calling code and the JSSE-based implementation.Footref 1

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 javax.net.debug property.

Note: You can set JSSE logging (javax.net.debug) independently of WebLogic SSL logging (ssl.debug).

weblogic.security.SSL.disableJsseCipherSuiteAliases=true|false

The default is false.

Disables the conversion of Certicom cipher suite names to SunJSSE cipher suite names, where applicable. By default, Certicom cipher suite names are converted to JSSE cipher suite names when JSSE is used for SSL.

For a list of Certicom cipher suite names and their SunJSSE equivalents, see Table 12-3.

weblogic.security.SSL.ignoreHostnameVerify

This property continues to work and is not affected by the JSSE integration.

See weblogic.security.SSL.ignoreHostnameVerification

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.

See Specifying the Version of the SSL Protocol.

One of the following:

  • weblogic.security.SSL.allowUnencryptedNullCipher

  • SSLMBean. SetAllowUnencryptedNullCipher(boolean)

  • weblogic.security.disableNullCipher

SunJSSE supports the following two null ciphers, but they are not enabled by default:

  • SSL_RSA_WITH_NULL_MD5

  • SSL_RSA_WITH_NULL_SHA

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 SSL_RSA_WITH_NULL_MD5 as the only supported cipher suite), the SSL handshake will fail.

If you set this control, the null cipher suite (for example, SSL_RSA_WITH_NULL_MD5) is added to the list of supported cipher suites by the server. The SSL connection has a chance to use the null cipher suite if the client wants to do so. If the null cipher suite is used, the message will be unencrypted.

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

Off is not supported, but other options are supported.

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.

See Setting Up SSL: Main Steps.


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://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug.

Cipher Suites

This topic includes the following sections:

List of Supported Cipher Suites

The sets of cipher suites supported by the JDK JSSE provider, SunJSSE, are available at the following URLs for JDK 6 and JDK 7, respectively:

http://docs.oracle.com/javase/6/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider

http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider

Backward Compatibility of Supported Cipher Suites

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. To enable one of these cipher suites, configure the <ciphersuite> element in the <ssl> element in the DOMAIN_HOME\server\config\config.xml file, as follows:

    <ssl>
    <name>examplesServer</name>
    <enabled>true</enabled>
    <listen-port>7002</listen-port>
    <ciphersuite>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</ciphersuite>
    ...
    
  • 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://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug) for more details on the Kerberos requirements.

Cipher Suite Name Equivalents

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

Setting Cipher Suites Using WLST: An Example

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="welcome1"
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()

Using Debugging with JSSE SSL

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://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug

Using the RSA JSSE Provider in WebLogic Server

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:

  1. 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
    
  2. 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).

  3. Add the SSL-J jar WL_HOME/server/lib/sslj.jar to the Classpath.

  4. Restart WebLogic Server for the change to the RSA JSEE provider to take effect.

X.509 Certificate Revocation Checking

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:

Certificate Revocation Checking Overview

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.

Enabling the Default CR Checking Configuration

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:

  1. 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:

    1. 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.

    2. 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.

    3. 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.

  2. 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:

    1. Obtains the CRL distribution point URL, which is included in the CRLDistributionPoints extension in the certificate.

    2. Using the CRL distribution point URL, downloads a fresh CRL and adds it to the cache.

    3. 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.

Configuring Default CR Checking

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 Help.

You can configure a CA override for this MBean attribute. For information, see Configuring Certificate Authority Overrides.

Customizing the CR Checking Configuration

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:

  • Use of nonces in OCSP requests and responses

  • OCSP response cache. For example, capacity or refresh period

  • OCSP response timeout interval settings

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:

  • Use of CRL distribution points

  • CRL cache refresh frequency

  • CRL distribution point download timeout interval settings

For information, see Using Certificate Revocation Lists.

Certificate authority overrides

Customize the CR checking behavior for certificates issued by a particular CA. For example:

  • Disable revocation checking for those certificates

  • Change the CR checking method order

  • Automatically fail certificate path validation if revocation status is unknown or unavailable

  • Customize OCSP or CRL settings (except for the CRL local cache settings)

  • Designate the OCSP responder URL to use

  • Designate the CRL distribution point URL to use

A certificate authority override always takes precedence over domain-wide settings that are in place. For more information, see Configuring Certificate Authority Overrides.


Choosing the CR Checking Methods to Be Used by WebLogic Server

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 Help.

Failing SSL Certificate Path Validation if Revocation Status Cannot Be Determined

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 Help.

Using the Online Certificate Status Protocol

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:

Using Nonces in OCSP Requests

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:

  1. WebLogic Server generates a nonce for each OCSP request, and includes it in an extension in the request.

  2. 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 Help.

Setting the Response Timeout Interval

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 Help.

Enabling and Configuring the OCSP Response Local Cache

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 Help.

Using Certificate Revocation Lists

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:

Enabling Updates from Distribution Points

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 Help.

Configuring the CRL Local Cache

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 Help.

Configuring Certificate Authority Overrides

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:

General Certificate Authority Overrides

To create a certificate authority override for a specific CA, complete the following steps:

  1. 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.

  2. Specify whether CR checking is enabled for certificates issued by this CA, if necessary.

  3. Specify the CR checking methods and order performed for certificates issued by this CA.

  4. Specify whether SSL certificate path validation should fail if the revocation status of certificates issued by this CA cannot be determined.

  5. 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 Help

Configuring OCSP Properties in a Certificate Authority Override

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:

  • Failover, if the OCSP responder URI from the certificate AIA value is not available or not acceptable

  • Override, to be always used as the responder URL instead of the responder URI from the certificate AIA.

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 FAILOVER.

OCSP responder certificate subject name

For this CA, specifies the explicitly trusted OCSP responder certificate subject name. For example, CN=OCSP Responder, O=XYZ Corp. This must correspond to the subject distinguished name of a certificate in the configured WebLogic Server trust keystore.

In cases where the subject name alone is not sufficient to uniquely identify the certificate, both the CertRevocCaMBean.OcspResponderCertIssuerName and CertRevocCaMBean.OcspResponderCertSerialNumber are used instead.

CertRevocCaMBean.OcspResponderCertSubjectName

The default value is NONE.

OCSP responder certificate issuer name

For this CA, specifies the explicitly trusted OCSP responder certificate issuer name. For example, CN=Enterprise CA, O=XYZ Corp. This must correspond to the issuer distinguished name of a certificate in the configured WebLogic Server trust keystore.

When this attribute is set, the CertRevocCaMBean.OcspResponderCertSerialNumber must also be set.

CertRevocCaMBean.OcspResponderCertIssuerName

The default value is NONE.

OCSP responder certificate serial number

For this CA, specifies the explicitly trusted OCSP responder certificate serial number. For example, 2A:FF:00. This must correspond to the serial number of a certificate in the configured WebLogic Server trust keystore.

When this attribute is set, the CertRevocCaMBean.OcspResponderCertIssuerName attribute must also be set.

CertRevocCaMBean.OcspResponderCertSerialNumber

The default value is NONE.

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:

  • NONE specifies that Explicit Trust is disabled.

  • USE_SUBJECT specifies that the trusted certificate is identified using the subject DN that is specified in the CertRevocCaMBean.OcspResponderCertSubjectName attribute.

  • USE_ISSUER_SERIAL_NUMBER specifies that the trusted certificate is identified using the issuer DN and certificate serial number that are specified in the CertRevocCaMBean.OcspResponderCertIssuerName and CertRevocCaMBean.OcspResponderCertSerialNumber attributes, respectively.

CertRevocCaMBean.OcspResponderExplicitTrustMethod

The default value is NONE.

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 CertRevocMBean.OcspNonceEnabled.

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 CertRevocMBean.OcspResponseCacheEnabled.

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 CertRevocMBean.OcspResponseTimeout.

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 CertRevocMBean.OcspTimeTolerance.


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 Help.

Identifying the OCSP Responder URL

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 Help.

Configuring CRL Properties in a Certificate Authority Override

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 CertRevocMBean.CrlDpEnabled.

Distribution point URL

For this CA, specifies the CRL distribution point URL to be used for either:

  • Failover, if the URL from the CRLDistributionPoints extension in the certificate is unavailable

  • Override, to be always used as the CRL distribution point URL instead of the CRLDistributionPoints extension in the certificate

CertRevocCaMBean.CrlDpUrl

The default value is null.

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 FAILOVER.

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 CertRevocMBean.CrlDpDownloadTimeout.


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 Help.