# Class PKIXBuilderParameters

java.lang.Object
java.security.cert.PKIXParameters
java.security.cert.PKIXBuilderParameters

All Implemented Interfaces:
  `Cloneable, CertPathParameters`

public class PKIXBuilderParameters extends PKIXParameters
Parameters used as input for the PKIX `CertPathBuilder` algorithm.

A PKIX `CertPathBuilder` uses these parameters to `build` a `CertPath` which has been validated according to the PKIX certification path validation algorithm.

To instantiate a `PKIXBuilderParameters` object, an application must specify one or more most-trusted CAs as defined by the PKIX certification path validation algorithm. The most-trusted CA can be specified using one of two constructors. An application can call `PKIXBuilderParameters(Set, CertSelector)`, specifying a `Set` of `TrustAnchor` objects, each of which identifies a most-trusted CA. Alternatively, an application can call `PKIXBuilderParameters(KeyStore, CertSelector)`, specifying a `KeyStore` instance containing trusted certificate entries, each of which will be considered as a most-trusted CA.

In addition, an application must specify constraints on the target certificate that the `CertPathBuilder` will attempt to build a path to. The constraints are specified as a `CertSelector` object. These constraints should provide the `CertPathBuilder` with enough search criteria to find the target certificate. Minimal criteria for an `X509Certificate` usually include the subject name and/or one or more subject alternative names. If enough criteria is not specified, the `CertPathBuilder` may throw a `CertPathBuilderException`.

Concurrent Access

Unless otherwise specified, the methods defined in this class are not thread-safe. Multiple threads that need to access a single object concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating separate objects need not synchronize.

Since:
  1.4
See Also:
  - `CertPathBuilder`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PKIXBuilderParameters(KeyStore keystore, CertSelector targetConstraints)`
  Creates an instance of `PKIXBuilderParameters` that populates the set of most-trusted CAs from the trusted certificate entries contained in the specified `KeyStore`.
  `PKIXBuilderParameters(Set<TrustAnchor> trustAnchors, CertSelector targetConstraints)`
  Creates an instance of `PKIXBuilderParameters` with the specified `Set` of most-trusted CAs.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `getMaxPathLength()`
  Returns the value of the maximum number of intermediate non-self-issued certificates that may exist in a certification path.
  `void`
  `setMaxPathLength(int maxPathLength)`
  Sets the value of the maximum number of non-self-issued intermediate certificates that may exist in a certification path.
  `String`
  `toString()`
  Returns a formatted string describing the parameters.

  ### Methods declared in class PKIXParameters

  `addCertPathChecker, addCertStore, clone, getCertPathCheckers, getCertStores, getDate, getInitialPolicies, getPolicyQualifiersRejected, getSigProvider, getTargetCertConstraints, getTrustAnchors, isAnyPolicyInhibited, isExplicitPolicyRequired, isPolicyMappingInhibited, isRevocationEnabled, setAnyPolicyInhibited, setCertPathCheckers, setCertStores, setDate, setExplicitPolicyRequired, setInitialPolicies, setPolicyMappingInhibited, setPolicyQualifiersRejected, setRevocationEnabled, setSigProvider, setTargetCertConstraints, setTrustAnchors`
  Modifier and Type
  Method
  Description
  `void`
  `addCertPathChecker(PKIXCertPathChecker checker)`
  Adds a `PKIXCertPathChecker` to the list of certification path checkers.
  `void`
  `addCertStore(CertStore store)`
  Adds a `CertStore` to the end of the list of `CertStore`s used in finding certificates and CRLs.
  `Object`
  `clone()`
  Makes a copy of this `PKIXParameters` object.
  `List<PKIXCertPathChecker>`
  `getCertPathCheckers()`
  Returns the `List` of certification path checkers.
  `List<CertStore>`
  `getCertStores()`
  Returns an immutable `List` of `CertStore`s that are used to find certificates and CRLs.
  `Date`
  `getDate()`
  Returns the time for which the validity of the certification path should be determined.
  `Set<String>`
  `getInitialPolicies()`
  Returns an immutable `Set` of initial policy identifiers (OID strings), indicating that any one of these policies would be acceptable to the certificate user for the purposes of certification path processing.
  `boolean`
  `getPolicyQualifiersRejected()`
  Gets the PolicyQualifiersRejected flag.
  `String`
  `getSigProvider()`
  Returns the signature provider's name, or `null` if not set.
  `CertSelector`
  `getTargetCertConstraints()`
  Returns the required constraints on the target certificate.
  `Set<TrustAnchor>`
  `getTrustAnchors()`
  Returns an immutable `Set` of the most-trusted CAs.
  `boolean`
  `isAnyPolicyInhibited()`
  Checks whether the any policy OID should be processed if it is included in a certificate.
  `boolean`
  `isExplicitPolicyRequired()`
  Checks if explicit policy is required.
  `boolean`
  `isPolicyMappingInhibited()`
  Checks if policy mapping is inhibited.
  `boolean`
  `isRevocationEnabled()`
  Checks the RevocationEnabled flag.
  `void`
  `setAnyPolicyInhibited(boolean val)`
  Sets state to determine if the any policy OID should be processed if it is included in a certificate.
  `void`
  `setCertPathCheckers(List<PKIXCertPathChecker> checkers)`
  Sets a `List` of additional certification path checkers.
  `void`
  `setCertStores(List<CertStore> stores)`
  Sets the list of `CertStore`s to be used in finding certificates and CRLs.
  `void`
  `setDate(Date date)`
  Sets the time for which the validity of the certification path should be determined.
  `void`
  `setExplicitPolicyRequired(boolean val)`
  Sets the ExplicitPolicyRequired flag.
  `void`
  `setInitialPolicies(Set<String> initialPolicies)`
  Sets the `Set` of initial policy identifiers (OID strings), indicating that any one of these policies would be acceptable to the certificate user for the purposes of certification path processing.
  `void`
  `setPolicyMappingInhibited(boolean val)`
  Sets the PolicyMappingInhibited flag.
  `void`
  `setPolicyQualifiersRejected(boolean qualifiersRejected)`
  Sets the PolicyQualifiersRejected flag.
  `void`
  `setRevocationEnabled(boolean val)`
  Sets the RevocationEnabled flag.
  `void`
  `setSigProvider(String sigProvider)`
  Sets the signature provider's name.
  `void`
  `setTargetCertConstraints(CertSelector selector)`
  Sets the required constraints on the target certificate.
  `void`
  `setTrustAnchors(Set<TrustAnchor> trustAnchors)`
  Sets the `Set` of most-trusted CAs.

  ### Methods declared in class Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### PKIXBuilderParameters

    public PKIXBuilderParameters(Set<TrustAnchor> trustAnchors, CertSelector targetConstraints) throws InvalidAlgorithmParameterException
    Creates an instance of `PKIXBuilderParameters` with the specified `Set` of most-trusted CAs. Each element of the set is a `TrustAnchor`.

    Note that the `Set` is copied to protect against subsequent modifications.

    Parameters:
      `trustAnchors` - a `Set` of `TrustAnchor`s
      `targetConstraints` - a `CertSelector` specifying the constraints on the target certificate
    Throws:
      `InvalidAlgorithmParameterException` - if `trustAnchors` is empty `(trustAnchors.isEmpty() == true)`
      `NullPointerException` - if `trustAnchors` is `null`
      `ClassCastException` - if any of the elements of `trustAnchors` are not of type `java.security.cert.TrustAnchor`

  - ### PKIXBuilderParameters

    public PKIXBuilderParameters(KeyStore keystore, CertSelector targetConstraints) throws KeyStoreException, InvalidAlgorithmParameterException
    Creates an instance of `PKIXBuilderParameters` that populates the set of most-trusted CAs from the trusted certificate entries contained in the specified `KeyStore`. Only keystore entries that contain trusted `X509Certificate`s are considered; all other certificate types are ignored.
    Parameters:
      `keystore` - a `KeyStore` from which the set of most-trusted CAs will be populated
      `targetConstraints` - a `CertSelector` specifying the constraints on the target certificate
    Throws:
      `KeyStoreException` - if `keystore` has not been initialized
      `InvalidAlgorithmParameterException` - if `keystore` does not contain at least one trusted certificate entry
      `NullPointerException` - if `keystore` is `null`

- ## Method Details

  - ### setMaxPathLength

    public void setMaxPathLength(int maxPathLength)
    Sets the value of the maximum number of non-self-issued intermediate certificates that may exist in a certification path. A certificate is self-issued if the DNs that appear in the subject and issuer fields are identical and are not empty. Note that the last certificate in a certification path is not an intermediate certificate, and is not included in this limit. Usually the last certificate is an end entity certificate, but it can be a CA certificate. A PKIX `CertPathBuilder` instance must not build paths longer than the length specified.

    A value of 0 implies that the path can only contain a single certificate. A value of -1 implies that the path length is unconstrained (i.e. there is no maximum). The default maximum path length, if not specified, is 5. Setting a value less than -1 will cause an exception to be thrown.

    If any of the CA certificates contain the `BasicConstraintsExtension`, the value of the `pathLenConstraint` field of the extension overrides the maximum path length parameter whenever the result is a certification path of smaller length.

    Parameters:
      `maxPathLength` - the maximum number of non-self-issued intermediate certificates that may exist in a certification path
    Throws:
      `InvalidParameterException` - if `maxPathLength` is set to a value less than -1
    See Also:
      - `getMaxPathLength()`

  - ### getMaxPathLength

    public int getMaxPathLength()
    Returns the value of the maximum number of intermediate non-self-issued certificates that may exist in a certification path. See the `setMaxPathLength(int)` method for more details.
    Returns:
      the maximum number of non-self-issued intermediate certificates that may exist in a certification path, or -1 if there is no limit
    See Also:
      - `setMaxPathLength(int)`

  - ### toString

    public String toString()
    Returns a formatted string describing the parameters.
    Overrides:
      `toString` in class `PKIXParameters`
    Returns:
      a formatted string describing the parameters