The PKIXBuilderParameters Class

This class (which extends the PKIXParameters class) specifies the set of parameters to be used with the CertPathBuilder objects that build certification paths validated against the PKIX certification path validation algorithm.

A PKIXBuilderParameters object is passed as an argument to the build method of a CertPathBuilder instance implementing the PKIX algorithm. All PKIX CertPathBuilders must return certification paths which have been validated according to the PKIX certification path validation algorithm.

Note that the mechanism that a PKIX CertPathBuilder uses to validate a constructed path is an implementation detail. For example, an implementation might attempt to first build a path with minimal validation and then fully validate it using an instance of a PKIX CertPathValidator, whereas a more efficient implementation might validate more of the path as it is building it, and backtrack to previous stages if it encounters validation failures or dead-ends.

Creating a PKIXBuilderParameters Object

Creating a PKIXBuilderParameters object is similar to creating a PKIXParameters object. However, a caller must specify constraints on the target or end-entity certificate when creating a PKIXBuilderParameters object. These constraints should provide the CertPathBuilder with enough information to find the target certificate. The constraints are specified as a CertSelector object. Use one of the following constructors to create a PKIXBuilderParameters object:

public PKIXBuilderParameters(Set trustAnchors,
       CertSelector targetConstraints)
       throws InvalidAlgorithmParameterException

public PKIXBuilderParameters(KeyStore keystore,
       CertSelector targetConstraints)
       throws KeyStoreException, InvalidAlgorithmParameterException

Getting or Setting Parameter Values

The PKIXBuilderParameters class inherits all of the parameters that can be set in the PKIXParameters class. In addition, the setMaxPathLength method can be called to place a limit on the maximum number of certificates in a certification path:

public void setMaxPathLength(int maxPathLength)

The maxPathLength parameter specifies the maximum number of non-self-issued intermediate certificates that may exist in a certification path. A CertPathBuilder instance that implements the PKIX algorithm must not build paths longer than the length specified. If the value is 0, the path can contain only a single certificate. If the value is -1, the path length is unconstrained (that is, there is no maximum). The default maximum path length, if not specified, is 5. This method is useful to prevent the CertPathBuilder from spending resources and time constructing long paths that may or may not meet the caller's requirements.

If any of the CA certificates in the path contain a Basic Constraints extension, the value of the pathLenConstraint component of the extension overrides the value of the maxPathLength parameter whenever the result is a certification path of smaller length. There is also a corresponding getMaxPathLength method for retrieving this parameter:

public int getMaxPathLength()

Also, the setCertStores method (inherited from the PKIXParameters class) is typically used by a PKIX implementation of CertPathBuilder to find Certificates for path construction as well as finding CRLs for path validation. This method provides an extensible mechanism for specifying where to locate Certificates and CRLs.