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:
To use a CertPath Builder in your application, follow these steps:
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.
Example 10-1 shows an example of choosing a selector.
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.
Example 10-2 shows an example of passing an instance of CertPathBuilderParameters.
Example 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);
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 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]);
To use a CertPath Validator in your application, follow these steps:
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.
Example 10-4 shows an example of passing an instance of CertPathValidatorParameters.
Example 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);
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 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);