Skip navigation.
Downloads | Product Documentation | Support

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
- CertPath Validation
- Instantiate a CertPathSelector
- Instantiate a CertPathBuilderParameters
- Use the JDK CertPathBuilder Interface
- Instantiate a CertPathValidatorParameters
- Use the JDK CertPathValidator Interface

# CertPath Building

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

1. Instantiate a CertPathSelector
2. Instantiate a CertPathBuilderParameters
3. 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:

1. 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
2. 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.
3. 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.
4. 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:

1. Instantiate a CertPathValidatorParameters
2. 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.

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

1. 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.
2. 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.
3. If successful, the result is returned in an object that implements the CertPathValidatorResult interface.
4. 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);