Programming WebLogic Security

Using CertPath Building and Validation

The WebLogic Security service provides the Certificate Lookup and Validation (CLV) API that finds and validates X509 certificate chains.

A CertPath is a JDK class that stores a certificate chain in memory. The term CertPath is also used to refer to the JDK architecture and framework that is used to locate and validate certificate chains. The CLV framework extends and completes the JDK CertPath functionality. CertPath providers rely on a tightly-coupled integration of WebLogic and JDK interfaces.

Your application code can use the default CertPath providers provided by WebLogic Server to build and validate certificate chains, or any custom CertPath providers.

The following topics are covered in this section:

CertPath Building

To use a CertPath Builder in your application, follow these steps:

Instantiate a CertPathSelector

Instantiate a CertPathBuilderParameters

Use the JDK CertPathBuilder Interface

Instantiate a CertPathSelector

The CertPathSelector interface (weblogic.security.pk.CertPathSelector) contains the selection criteria for locating and validating a certification path. Because there are many ways to look up certification paths, a derived class is implemented for each type of selection criteria.

Each selector class has one or more methods to retrieve the selection data and a constructor.

The classes in weblogic.security.pk that implement the CertPathSelector interface, one for each supported type of certificate chain lookup, are as follows:

EndCertificateSelector - used to find and validate a certificate chain given its end certificate.
IssuerDNSerialNumberSelector - used to find and validate a certificate chain from its end certificate's issuer DN and serial number.
SubjectDNSelector - used to find and validate a certificate chain from its end certificate's subject DN.
SubjectKeyIdentifierSelector - used to find and validate a certificate chain from its end certificate's subject key identifier (an optional field in X509 certificates).

Notes: The selectors that are supported depend on the configured CertPath providers. The configured CertPath providers are determined by the administrator.

The WebLogic CertPath provider uses only the EndCertificateSelector selector.

Listing 10-1 shows an example of choosing a selector.

Listing 10-1 Make a certificate chain selector

// you already have the end certificate
// and want to use it to lookup and
// validate the corresponding chain
X509Certificate endCertificate = ...

// make a cert chain selector
CertPathSelector selector = new EndCertificateSelector(endCertificate);

Instantiate a CertPathBuilderParameters

You pass an instance of CertPathBuilderParameters as the CertPathParameters object to the JDK's CertPathBuilder.build() method.

The following constructor and method are provided:

CertPathBuilderParameters

public CertPathBuilderParameters(String realmName,

CertPathSelector selector,

X509Certificate[] trustedCAs,

ContextHandler context)

Constructs a CertPathBuilderParameters.

You must provide the realm name. To do this, get the domain's SecurityConfigurationMBean. Then, get the SecurityConfigurationMBean's default realm attribute, which is a realm MBean. Finally, get the realm MBean's name attribute. You must use the runtime JMX MBean server to get the realm name.

You must provide the selector. You use one of the weblogic.security.pk.CertPathSelector interfaces derived classes, described in Instantiate a CertPathSelector to specify the selection criteria for locating and validating a certification path.

Specify trusted CAs if you have them. Otherwise, the server's trusted CAs are used. These are just a hint to the configured CertPath builder and CertPath validators which, depending on their lookup/validation algorithm, may or may not use these trusted CAs.

ContextHandler is used to pass in an optional list of name/value pairs that the configured CertPathBuilder and CertPathValidators may use to look up and validate the chain. It is symmetrical with the context handler passed to other types of security providers. Setting context to null indicates that there are no context parameters.

clone

Object clone()

This interface is not cloneable.

Listing 10-2 shows an example of passing an instance of CertPathBuilderParameters.

Listing 10-2 Pass An Instance of CertPathBuilderParameters

// make a cert chain selector
CertPathSelector selector = new EndCertificateSelector(endCertificate);

String realm = _;

// create and populate a context handler if desired, or null
ContextHandler context = _;

// pass in a list of trusted CAs if desired, or null
X509Certificate[] trustedCAs = _;

// make the params

CertPathBuilderParams params =
new CertPathBuilderParameters(realm, selector, context, trustedCAs);

Use the JDK CertPathBuilder Interface

The java.security.cert.CertPathBuilder interface is the API for the CertPathBuilder class. To use the JDK CertPathBuilder interface, do the following:

Call the static CertPathBuilder.getInstance method to retrieve the CLV framework's CertPathBuilder. You must specify "WLSCertPathBuilder" as the algorithm name that's passed to the call

Once the CertPathBuilder object has been obtained, call the "build" method on the returned CertPathBuilder. This method takes one argument - a CertPathParameters that indicates which chain to find and how it should be validated.

You must pass an instance of weblogic.security.pk.CertPathBuilderParameters as the CertPathParameters object to the JDK's CertPathBuilder.build() method, as described in Instantiate a CertPathBuilderParameters.

If successful, the result (including the CertPath that was built) is returned in an object that implements the CertPathBuilderResult interface. The builder determines how much of the CertPath is returned.

If not successful, the CertPathBuilder build method throws InvalidAlgorithmParameterException if the params is not a WebLogic CertPathBuilderParameters, if the configured CertPathBuilder does not support the selector, or if the realm name does not match the realm name of the default realm from when the server was booted.

The CertPathBuilder build method throws CertPathBuilderException if the cert path could not be located or if the located cert path is not valid

Example Code Flow for Looking Up a Certificate Chain

Listing 10-3 Looking up a Certificate Chain

import weblogic.security.pk.CertPathBuilderParameters;
import weblogic.security.pk.CertPathSelector;
import weblogic.security.pk.EndCertificateSelector;
import weblogic.security.service.ContextHandler;
import java.security.cert.CertPath;
import java.security.cert.CertPathBuilder;
import java.security.cert.X509Certificate;

// you already have the end certificate
// and want to use it to lookup and
// validate the corresponding chain
X509Certificate endCertificate = ...

// make a cert chain selector
CertPathSelector selector = new EndCertificateSelector(endCertificate);

String realm = _;

// create and populate a context handler if desired
ContextHandler context = _;

// pass in a list of trusted CAs if desired
X509Certificate[] trustedCAs = _;

// make the params

CertPathBuilderParams params =
new CertPathBuilderParameters(realm, selector, context, trustedCAs);

// get the WLS CertPathBuilder

CertPathBuilder builder =
CertPathBuilder.getInstance("WLSCertPathBuilder");

// use it to look up and validate the chain
CertPath certpath = builder.build(params).getCertPath();
X509Certificate[] chain =
certpath.getCertificates().toArray(new X509Certificate[0]);

CertPath Validation

To use a CertPath Validator in your application, follow these steps:

Instantiate a CertPathValidatorParameters

Use the JDK CertPathValidator Interface

Instantiate a CertPathValidatorParameters

You pass an instance of CertPathValidatorParameters as the CertPathParameters object to the JDK's CertPathValidator.validate() method.

The following constructor and method are provided:

CertPathValidatorParameters

public CertPathValidatorParameters(String realmName,

X509Certificate[] trustedCAs,

ContextHandler context)

Constructs a CertPathValidatorParameters.

You must provide the realm name. To do this, get the domain's SecurityConfigurationMBean. Then, get the SecurityConfigurationMBean's default realm attribute, which is a realm MBean. Finally, get the realm MBean's name attribute. You must use the runtime JMX MBean server to get the realm name.

Specify trusted CAs if you have them. Otherwise, the server's trusted CAs are used. These are just a hint to the configured CertPath builder and CertPath validators which, depending on their lookup/validation algorithm, may or may not use these trusted CAs.

clone

Object clone()

This interface is not cloneable.

Listing 10-4 shows an example of passing an instance of CertPathValidatorParameters.

Listing 10-4 Pass an Instance of CertPathValidatorParameters

// get the WLS CertPathValidator
CertPathValidator validator =
CertPathValidator.getInstance("WLSCertPathValidator");

String realm = _;

// create and populate a context handler if desired, or null
ContextHandler context = _;

// pass in a list of trusted CAs if desired, or null
X509Certificate[] trustedCAs = _;

// make the params (for the default security realm)
CertPathValidatorParams params =
new CertPathValidatorParams(realm, context, trustedCAs);

Use the JDK CertPathValidator Interface

The java.security.cert.CertPathValidator interface is the API for the CertPathValidator class. To use the JDK CertPathValidator interface, do the following:

Call the static CertPathValidator.getInstance method to retrieve the CLV framework's CertPathValidator. You must specify "WLSCertPathValidator" as the algorithm name that's passed to the call.

Once the CertPathValidator object has been obtained, call the "validate" method on the returned CertPathValidator. This method takes one argument - a CertPathParameters that indicates how it should be validated.

You must pass an instance of weblogic.security.pk.CertPathValidatorParameters as the CertPathParameters object to the JDK's CertPathValidator.validate() method, as described in Instantiate a CertPathValidatorParameters.

If successful, the result is returned in an object that implements the CertPathValidatorResult interface.

If not successful, the CertPathValidator.validate() method throws InvalidAlgorithmParameterException if params is not a WebLogic CertPathValidatorParameters or if the realm name does not match the realm name of the default realm from when the server was booted.

The CertPathValidator validate method throws CertPathValidatorException if the certificates in the CertPath are not ordered (the end certificate must be the first cert) or if the CertPath is not valid.

Example Code Flow for Validating a Certificate Chain

Listing 10-5 Performing Extra Validation

import weblogic.security.pk.CertPathValidatorParams;
import weblogic.security.service.ContextHandler;
import java.security.cert.CertPath;
import java.security.cert.CertPathValidator;
import java.security.cert.X509Certificate;

// you already have an unvalidated X509 certificate chain
// and you want to get it validated
X509Certificate[] chain = ...

// convert the chain to a CertPath

CertPathFactory factory = CertPathFactory.getInstance("X509");
ArrayList list = new ArrayList(chain.length);
for (int i = 0; i < chain.length; i++) {
list.add(chain[i]);
}

CertPath certPath = factory.generateCertPath(list);

// get the WLS CertPathValidator
CertPathValidator validator =
CertPathValidator.getInstance("WLSCertPathValidator");

String realm = _;

// create and populate a context handler if desired, or null
ContextHandler context = _;

// pass in a list of trusted CAs if desired, or null
X509Certificate[] trustedCAs = _;

// make the params (for the default security realm)
CertPathValidatorParams params =
new CertPathValidatorParams(realm, context, trustedCAs);

// use it to validate the chain
validator.validate(certPath, params);