This chapter includes the following sections:
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.
Note:
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.
The following topics explain how to configure and customize 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 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 39-1 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 39-1 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.
Note:
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:
To create a certificate authority override for a specific CA, complete the following steps:
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 |
CertRevocCaMBean.MethodOrder |
Specifies the certificate revocation checking method order when checking certificates issued by this CA. |
Same as current setting of |
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 39-2. This table also identifies the MBean attributes you can use to configure these override properties.
Table 39-2 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.
The following topic explains how to identify 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 Online Help.
When you configure a certificate authority override, WebLogic Server allows you to configure the CRL properties listed and described in Table 39-3. This table also identifies the MBean attributes you can use to configure these properties.
Table 39-3 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.