jdk/src/share/classes/java/security/cert/PKIXParameters.java
changeset 18551 882a3948c6e6
parent 14342 8435a30053c1
child 24969 afa6934dd8e8
equal deleted inserted replaced
18550:6d0f51c99930 18551:882a3948c6e6
     1 /*
     1 /*
     2  * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
     2  * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
     4  *
     4  *
     5  * This code is free software; you can redistribute it and/or modify it
     5  * This code is free software; you can redistribute it and/or modify it
     6  * under the terms of the GNU General Public License version 2 only, as
     6  * under the terms of the GNU General Public License version 2 only, as
     7  * published by the Free Software Foundation.  Oracle designates this
     7  * published by the Free Software Foundation.  Oracle designates this
    36 import java.util.Iterator;
    36 import java.util.Iterator;
    37 import java.util.List;
    37 import java.util.List;
    38 import java.util.Set;
    38 import java.util.Set;
    39 
    39 
    40 /**
    40 /**
    41  * Parameters used as input for the PKIX <code>CertPathValidator</code>
    41  * Parameters used as input for the PKIX {@code CertPathValidator}
    42  * algorithm.
    42  * algorithm.
    43  * <p>
    43  * <p>
    44  * A PKIX <code>CertPathValidator</code> uses these parameters to
    44  * A PKIX {@code CertPathValidator} uses these parameters to
    45  * validate a <code>CertPath</code> according to the PKIX certification path
    45  * validate a {@code CertPath} according to the PKIX certification path
    46  * validation algorithm.
    46  * validation algorithm.
    47  *
    47  *
    48  * <p>To instantiate a <code>PKIXParameters</code> object, an
    48  * <p>To instantiate a {@code PKIXParameters} object, an
    49  * application must specify one or more <i>most-trusted CAs</i> as defined by
    49  * application must specify one or more <i>most-trusted CAs</i> as defined by
    50  * the PKIX certification path validation algorithm. The most-trusted CAs
    50  * the PKIX certification path validation algorithm. The most-trusted CAs
    51  * can be specified using one of two constructors. An application
    51  * can be specified using one of two constructors. An application
    52  * can call {@link #PKIXParameters(Set) PKIXParameters(Set)},
    52  * can call {@link #PKIXParameters(Set) PKIXParameters(Set)},
    53  * specifying a <code>Set</code> of <code>TrustAnchor</code> objects, each
    53  * specifying a {@code Set} of {@code TrustAnchor} objects, each
    54  * of which identify a most-trusted CA. Alternatively, an application can call
    54  * of which identify a most-trusted CA. Alternatively, an application can call
    55  * {@link #PKIXParameters(KeyStore) PKIXParameters(KeyStore)}, specifying a
    55  * {@link #PKIXParameters(KeyStore) PKIXParameters(KeyStore)}, specifying a
    56  * <code>KeyStore</code> instance containing trusted certificate entries, each
    56  * {@code KeyStore} instance containing trusted certificate entries, each
    57  * of which will be considered as a most-trusted CA.
    57  * of which will be considered as a most-trusted CA.
    58  * <p>
    58  * <p>
    59  * Once a <code>PKIXParameters</code> object has been created, other parameters
    59  * Once a {@code PKIXParameters} object has been created, other parameters
    60  * can be specified (by calling {@link #setInitialPolicies setInitialPolicies}
    60  * can be specified (by calling {@link #setInitialPolicies setInitialPolicies}
    61  * or {@link #setDate setDate}, for instance) and then the
    61  * or {@link #setDate setDate}, for instance) and then the
    62  * <code>PKIXParameters</code> is passed along with the <code>CertPath</code>
    62  * {@code PKIXParameters} is passed along with the {@code CertPath}
    63  * to be validated to {@link CertPathValidator#validate
    63  * to be validated to {@link CertPathValidator#validate
    64  * CertPathValidator.validate}.
    64  * CertPathValidator.validate}.
    65  * <p>
    65  * <p>
    66  * Any parameter that is not set (or is set to <code>null</code>) will
    66  * Any parameter that is not set (or is set to {@code null}) will
    67  * be set to the default value for that parameter. The default value for the
    67  * be set to the default value for that parameter. The default value for the
    68  * <code>date</code> parameter is <code>null</code>, which indicates
    68  * {@code date} parameter is {@code null}, which indicates
    69  * the current time when the path is validated. The default for the
    69  * the current time when the path is validated. The default for the
    70  * remaining parameters is the least constrained.
    70  * remaining parameters is the least constrained.
    71  * <p>
    71  * <p>
    72  * <b>Concurrent Access</b>
    72  * <b>Concurrent Access</b>
    73  * <p>
    73  * <p>
    97     private boolean policyQualifiersRejected = true;
    97     private boolean policyQualifiersRejected = true;
    98     private List<CertStore> certStores;
    98     private List<CertStore> certStores;
    99     private CertSelector certSelector;
    99     private CertSelector certSelector;
   100 
   100 
   101     /**
   101     /**
   102      * Creates an instance of <code>PKIXParameters</code> with the specified
   102      * Creates an instance of {@code PKIXParameters} with the specified
   103      * <code>Set</code> of most-trusted CAs. Each element of the
   103      * {@code Set} of most-trusted CAs. Each element of the
   104      * set is a {@link TrustAnchor TrustAnchor}.
   104      * set is a {@link TrustAnchor TrustAnchor}.
   105      * <p>
   105      * <p>
   106      * Note that the <code>Set</code> is copied to protect against
   106      * Note that the {@code Set} is copied to protect against
   107      * subsequent modifications.
   107      * subsequent modifications.
   108      *
   108      *
   109      * @param trustAnchors a <code>Set</code> of <code>TrustAnchor</code>s
   109      * @param trustAnchors a {@code Set} of {@code TrustAnchor}s
   110      * @throws InvalidAlgorithmParameterException if the specified
   110      * @throws InvalidAlgorithmParameterException if the specified
   111      * <code>Set</code> is empty <code>(trustAnchors.isEmpty() == true)</code>
   111      * {@code Set} is empty {@code (trustAnchors.isEmpty() == true)}
   112      * @throws NullPointerException if the specified <code>Set</code> is
   112      * @throws NullPointerException if the specified {@code Set} is
   113      * <code>null</code>
   113      * {@code null}
   114      * @throws ClassCastException if any of the elements in the <code>Set</code>
   114      * @throws ClassCastException if any of the elements in the {@code Set}
   115      * are not of type <code>java.security.cert.TrustAnchor</code>
   115      * are not of type {@code java.security.cert.TrustAnchor}
   116      */
   116      */
   117     public PKIXParameters(Set<TrustAnchor> trustAnchors)
   117     public PKIXParameters(Set<TrustAnchor> trustAnchors)
   118         throws InvalidAlgorithmParameterException
   118         throws InvalidAlgorithmParameterException
   119     {
   119     {
   120         setTrustAnchors(trustAnchors);
   120         setTrustAnchors(trustAnchors);
   123         this.certPathCheckers = new ArrayList<PKIXCertPathChecker>();
   123         this.certPathCheckers = new ArrayList<PKIXCertPathChecker>();
   124         this.certStores = new ArrayList<CertStore>();
   124         this.certStores = new ArrayList<CertStore>();
   125     }
   125     }
   126 
   126 
   127     /**
   127     /**
   128      * Creates an instance of <code>PKIXParameters</code> that
   128      * Creates an instance of {@code PKIXParameters} that
   129      * populates the set of most-trusted CAs from the trusted
   129      * populates the set of most-trusted CAs from the trusted
   130      * certificate entries contained in the specified <code>KeyStore</code>.
   130      * certificate entries contained in the specified {@code KeyStore}.
   131      * Only keystore entries that contain trusted <code>X509Certificates</code>
   131      * Only keystore entries that contain trusted {@code X509Certificates}
   132      * are considered; all other certificate types are ignored.
   132      * are considered; all other certificate types are ignored.
   133      *
   133      *
   134      * @param keystore a <code>KeyStore</code> from which the set of
   134      * @param keystore a {@code KeyStore} from which the set of
   135      * most-trusted CAs will be populated
   135      * most-trusted CAs will be populated
   136      * @throws KeyStoreException if the keystore has not been initialized
   136      * @throws KeyStoreException if the keystore has not been initialized
   137      * @throws InvalidAlgorithmParameterException if the keystore does
   137      * @throws InvalidAlgorithmParameterException if the keystore does
   138      * not contain at least one trusted certificate entry
   138      * not contain at least one trusted certificate entry
   139      * @throws NullPointerException if the keystore is <code>null</code>
   139      * @throws NullPointerException if the keystore is {@code null}
   140      */
   140      */
   141     public PKIXParameters(KeyStore keystore)
   141     public PKIXParameters(KeyStore keystore)
   142         throws KeyStoreException, InvalidAlgorithmParameterException
   142         throws KeyStoreException, InvalidAlgorithmParameterException
   143     {
   143     {
   144         if (keystore == null)
   144         if (keystore == null)
   159         this.certPathCheckers = new ArrayList<PKIXCertPathChecker>();
   159         this.certPathCheckers = new ArrayList<PKIXCertPathChecker>();
   160         this.certStores = new ArrayList<CertStore>();
   160         this.certStores = new ArrayList<CertStore>();
   161     }
   161     }
   162 
   162 
   163     /**
   163     /**
   164      * Returns an immutable <code>Set</code> of the most-trusted
   164      * Returns an immutable {@code Set} of the most-trusted
   165      * CAs.
   165      * CAs.
   166      *
   166      *
   167      * @return an immutable <code>Set</code> of <code>TrustAnchor</code>s
   167      * @return an immutable {@code Set} of {@code TrustAnchor}s
   168      * (never <code>null</code>)
   168      * (never {@code null})
   169      *
   169      *
   170      * @see #setTrustAnchors
   170      * @see #setTrustAnchors
   171      */
   171      */
   172     public Set<TrustAnchor> getTrustAnchors() {
   172     public Set<TrustAnchor> getTrustAnchors() {
   173         return this.unmodTrustAnchors;
   173         return this.unmodTrustAnchors;
   174     }
   174     }
   175 
   175 
   176     /**
   176     /**
   177      * Sets the <code>Set</code> of most-trusted CAs.
   177      * Sets the {@code Set} of most-trusted CAs.
   178      * <p>
   178      * <p>
   179      * Note that the <code>Set</code> is copied to protect against
   179      * Note that the {@code Set} is copied to protect against
   180      * subsequent modifications.
   180      * subsequent modifications.
   181      *
   181      *
   182      * @param trustAnchors a <code>Set</code> of <code>TrustAnchor</code>s
   182      * @param trustAnchors a {@code Set} of {@code TrustAnchor}s
   183      * @throws InvalidAlgorithmParameterException if the specified
   183      * @throws InvalidAlgorithmParameterException if the specified
   184      * <code>Set</code> is empty <code>(trustAnchors.isEmpty() == true)</code>
   184      * {@code Set} is empty {@code (trustAnchors.isEmpty() == true)}
   185      * @throws NullPointerException if the specified <code>Set</code> is
   185      * @throws NullPointerException if the specified {@code Set} is
   186      * <code>null</code>
   186      * {@code null}
   187      * @throws ClassCastException if any of the elements in the set
   187      * @throws ClassCastException if any of the elements in the set
   188      * are not of type <code>java.security.cert.TrustAnchor</code>
   188      * are not of type {@code java.security.cert.TrustAnchor}
   189      *
   189      *
   190      * @see #getTrustAnchors
   190      * @see #getTrustAnchors
   191      */
   191      */
   192     public void setTrustAnchors(Set<TrustAnchor> trustAnchors)
   192     public void setTrustAnchors(Set<TrustAnchor> trustAnchors)
   193         throws InvalidAlgorithmParameterException
   193         throws InvalidAlgorithmParameterException
   209         this.unmodTrustAnchors = Collections.unmodifiableSet
   209         this.unmodTrustAnchors = Collections.unmodifiableSet
   210                 (new HashSet<TrustAnchor>(trustAnchors));
   210                 (new HashSet<TrustAnchor>(trustAnchors));
   211     }
   211     }
   212 
   212 
   213     /**
   213     /**
   214      * Returns an immutable <code>Set</code> of initial
   214      * Returns an immutable {@code Set} of initial
   215      * policy identifiers (OID strings), indicating that any one of these
   215      * policy identifiers (OID strings), indicating that any one of these
   216      * policies would be acceptable to the certificate user for the purposes of
   216      * policies would be acceptable to the certificate user for the purposes of
   217      * certification path processing. The default return value is an empty
   217      * certification path processing. The default return value is an empty
   218      * <code>Set</code>, which is interpreted as meaning that any policy would
   218      * {@code Set}, which is interpreted as meaning that any policy would
   219      * be acceptable.
   219      * be acceptable.
   220      *
   220      *
   221      * @return an immutable <code>Set</code> of initial policy OIDs in
   221      * @return an immutable {@code Set} of initial policy OIDs in
   222      * <code>String</code> format, or an empty <code>Set</code> (implying any
   222      * {@code String} format, or an empty {@code Set} (implying any
   223      * policy is acceptable). Never returns <code>null</code>.
   223      * policy is acceptable). Never returns {@code null}.
   224      *
   224      *
   225      * @see #setInitialPolicies
   225      * @see #setInitialPolicies
   226      */
   226      */
   227     public Set<String> getInitialPolicies() {
   227     public Set<String> getInitialPolicies() {
   228         return this.unmodInitialPolicies;
   228         return this.unmodInitialPolicies;
   229     }
   229     }
   230 
   230 
   231     /**
   231     /**
   232      * Sets the <code>Set</code> of initial policy identifiers
   232      * Sets the {@code Set} of initial policy identifiers
   233      * (OID strings), indicating that any one of these
   233      * (OID strings), indicating that any one of these
   234      * policies would be acceptable to the certificate user for the purposes of
   234      * policies would be acceptable to the certificate user for the purposes of
   235      * certification path processing. By default, any policy is acceptable
   235      * certification path processing. By default, any policy is acceptable
   236      * (i.e. all policies), so a user that wants to allow any policy as
   236      * (i.e. all policies), so a user that wants to allow any policy as
   237      * acceptable does not need to call this method, or can call it
   237      * acceptable does not need to call this method, or can call it
   238      * with an empty <code>Set</code> (or <code>null</code>).
   238      * with an empty {@code Set} (or {@code null}).
   239      * <p>
   239      * <p>
   240      * Note that the <code>Set</code> is copied to protect against
   240      * Note that the {@code Set} is copied to protect against
   241      * subsequent modifications.
   241      * subsequent modifications.
   242      *
   242      *
   243      * @param initialPolicies a <code>Set</code> of initial policy
   243      * @param initialPolicies a {@code Set} of initial policy
   244      * OIDs in <code>String</code> format (or <code>null</code>)
   244      * OIDs in {@code String} format (or {@code null})
   245      * @throws ClassCastException if any of the elements in the set are
   245      * @throws ClassCastException if any of the elements in the set are
   246      * not of type <code>String</code>
   246      * not of type {@code String}
   247      *
   247      *
   248      * @see #getInitialPolicies
   248      * @see #getInitialPolicies
   249      */
   249      */
   250     public void setInitialPolicies(Set<String> initialPolicies) {
   250     public void setInitialPolicies(Set<String> initialPolicies) {
   251         if (initialPolicies != null) {
   251         if (initialPolicies != null) {
   260         } else
   260         } else
   261             this.unmodInitialPolicies = Collections.<String>emptySet();
   261             this.unmodInitialPolicies = Collections.<String>emptySet();
   262     }
   262     }
   263 
   263 
   264     /**
   264     /**
   265      * Sets the list of <code>CertStore</code>s to be used in finding
   265      * Sets the list of {@code CertStore}s to be used in finding
   266      * certificates and CRLs. May be <code>null</code>, in which case
   266      * certificates and CRLs. May be {@code null}, in which case
   267      * no <code>CertStore</code>s will be used. The first
   267      * no {@code CertStore}s will be used. The first
   268      * <code>CertStore</code>s in the list may be preferred to those that
   268      * {@code CertStore}s in the list may be preferred to those that
   269      * appear later.
   269      * appear later.
   270      * <p>
   270      * <p>
   271      * Note that the <code>List</code> is copied to protect against
   271      * Note that the {@code List} is copied to protect against
   272      * subsequent modifications.
   272      * subsequent modifications.
   273      *
   273      *
   274      * @param stores a <code>List</code> of <code>CertStore</code>s (or
   274      * @param stores a {@code List} of {@code CertStore}s (or
   275      * <code>null</code>)
   275      * {@code null})
   276      * @throws ClassCastException if any of the elements in the list are
   276      * @throws ClassCastException if any of the elements in the list are
   277      * not of type <code>java.security.cert.CertStore</code>
   277      * not of type {@code java.security.cert.CertStore}
   278      *
   278      *
   279      * @see #getCertStores
   279      * @see #getCertStores
   280      */
   280      */
   281     public void setCertStores(List<CertStore> stores) {
   281     public void setCertStores(List<CertStore> stores) {
   282         if (stores == null) {
   282         if (stores == null) {
   291             this.certStores = new ArrayList<CertStore>(stores);
   291             this.certStores = new ArrayList<CertStore>(stores);
   292         }
   292         }
   293     }
   293     }
   294 
   294 
   295     /**
   295     /**
   296      * Adds a <code>CertStore</code> to the end of the list of
   296      * Adds a {@code CertStore} to the end of the list of
   297      * <code>CertStore</code>s used in finding certificates and CRLs.
   297      * {@code CertStore}s used in finding certificates and CRLs.
   298      *
   298      *
   299      * @param store the <code>CertStore</code> to add. If <code>null</code>,
   299      * @param store the {@code CertStore} to add. If {@code null},
   300      * the store is ignored (not added to list).
   300      * the store is ignored (not added to list).
   301      */
   301      */
   302     public void addCertStore(CertStore store) {
   302     public void addCertStore(CertStore store) {
   303         if (store != null) {
   303         if (store != null) {
   304             this.certStores.add(store);
   304             this.certStores.add(store);
   305         }
   305         }
   306     }
   306     }
   307 
   307 
   308     /**
   308     /**
   309      * Returns an immutable <code>List</code> of <code>CertStore</code>s that
   309      * Returns an immutable {@code List} of {@code CertStore}s that
   310      * are used to find certificates and CRLs.
   310      * are used to find certificates and CRLs.
   311      *
   311      *
   312      * @return an immutable <code>List</code> of <code>CertStore</code>s
   312      * @return an immutable {@code List} of {@code CertStore}s
   313      * (may be empty, but never <code>null</code>)
   313      * (may be empty, but never {@code null})
   314      *
   314      *
   315      * @see #setCertStores
   315      * @see #setCertStores
   316      */
   316      */
   317     public List<CertStore> getCertStores() {
   317     public List<CertStore> getCertStores() {
   318         return Collections.unmodifiableList
   318         return Collections.unmodifiableList
   323      * Sets the RevocationEnabled flag. If this flag is true, the default
   323      * Sets the RevocationEnabled flag. If this flag is true, the default
   324      * revocation checking mechanism of the underlying PKIX service provider
   324      * revocation checking mechanism of the underlying PKIX service provider
   325      * will be used. If this flag is false, the default revocation checking
   325      * will be used. If this flag is false, the default revocation checking
   326      * mechanism will be disabled (not used).
   326      * mechanism will be disabled (not used).
   327      * <p>
   327      * <p>
   328      * When a <code>PKIXParameters</code> object is created, this flag is set
   328      * When a {@code PKIXParameters} object is created, this flag is set
   329      * to true. This setting reflects the most common strategy for checking
   329      * to true. This setting reflects the most common strategy for checking
   330      * revocation, since each service provider must support revocation
   330      * revocation, since each service provider must support revocation
   331      * checking to be PKIX compliant. Sophisticated applications should set
   331      * checking to be PKIX compliant. Sophisticated applications should set
   332      * this flag to false when it is not practical to use a PKIX service
   332      * this flag to false when it is not practical to use a PKIX service
   333      * provider's default revocation checking mechanism or when an alternative
   333      * provider's default revocation checking mechanism or when an alternative
   358     /**
   358     /**
   359      * Sets the ExplicitPolicyRequired flag. If this flag is true, an
   359      * Sets the ExplicitPolicyRequired flag. If this flag is true, an
   360      * acceptable policy needs to be explicitly identified in every certificate.
   360      * acceptable policy needs to be explicitly identified in every certificate.
   361      * By default, the ExplicitPolicyRequired flag is false.
   361      * By default, the ExplicitPolicyRequired flag is false.
   362      *
   362      *
   363      * @param val <code>true</code> if explicit policy is to be required,
   363      * @param val {@code true} if explicit policy is to be required,
   364      * <code>false</code> otherwise
   364      * {@code false} otherwise
   365      */
   365      */
   366     public void setExplicitPolicyRequired(boolean val) {
   366     public void setExplicitPolicyRequired(boolean val) {
   367         explicitPolicyRequired = val;
   367         explicitPolicyRequired = val;
   368     }
   368     }
   369 
   369 
   370     /**
   370     /**
   371      * Checks if explicit policy is required. If this flag is true, an
   371      * Checks if explicit policy is required. If this flag is true, an
   372      * acceptable policy needs to be explicitly identified in every certificate.
   372      * acceptable policy needs to be explicitly identified in every certificate.
   373      * By default, the ExplicitPolicyRequired flag is false.
   373      * By default, the ExplicitPolicyRequired flag is false.
   374      *
   374      *
   375      * @return <code>true</code> if explicit policy is required,
   375      * @return {@code true} if explicit policy is required,
   376      * <code>false</code> otherwise
   376      * {@code false} otherwise
   377      */
   377      */
   378     public boolean isExplicitPolicyRequired() {
   378     public boolean isExplicitPolicyRequired() {
   379         return explicitPolicyRequired;
   379         return explicitPolicyRequired;
   380     }
   380     }
   381 
   381 
   382     /**
   382     /**
   383      * Sets the PolicyMappingInhibited flag. If this flag is true, policy
   383      * Sets the PolicyMappingInhibited flag. If this flag is true, policy
   384      * mapping is inhibited. By default, policy mapping is not inhibited (the
   384      * mapping is inhibited. By default, policy mapping is not inhibited (the
   385      * flag is false).
   385      * flag is false).
   386      *
   386      *
   387      * @param val <code>true</code> if policy mapping is to be inhibited,
   387      * @param val {@code true} if policy mapping is to be inhibited,
   388      * <code>false</code> otherwise
   388      * {@code false} otherwise
   389      */
   389      */
   390     public void setPolicyMappingInhibited(boolean val) {
   390     public void setPolicyMappingInhibited(boolean val) {
   391         policyMappingInhibited = val;
   391         policyMappingInhibited = val;
   392     }
   392     }
   393 
   393 
   404 
   404 
   405     /**
   405     /**
   406      * Sets state to determine if the any policy OID should be processed
   406      * Sets state to determine if the any policy OID should be processed
   407      * if it is included in a certificate. By default, the any policy OID
   407      * if it is included in a certificate. By default, the any policy OID
   408      * is not inhibited ({@link #isAnyPolicyInhibited isAnyPolicyInhibited()}
   408      * is not inhibited ({@link #isAnyPolicyInhibited isAnyPolicyInhibited()}
   409      * returns <code>false</code>).
   409      * returns {@code false}).
   410      *
   410      *
   411      * @param val <code>true</code> if the any policy OID is to be
   411      * @param val {@code true} if the any policy OID is to be
   412      * inhibited, <code>false</code> otherwise
   412      * inhibited, {@code false} otherwise
   413      */
   413      */
   414     public void setAnyPolicyInhibited(boolean val) {
   414     public void setAnyPolicyInhibited(boolean val) {
   415         anyPolicyInhibited = val;
   415         anyPolicyInhibited = val;
   416     }
   416     }
   417 
   417 
   418     /**
   418     /**
   419      * Checks whether the any policy OID should be processed if it
   419      * Checks whether the any policy OID should be processed if it
   420      * is included in a certificate.
   420      * is included in a certificate.
   421      *
   421      *
   422      * @return <code>true</code> if the any policy OID is inhibited,
   422      * @return {@code true} if the any policy OID is inhibited,
   423      * <code>false</code> otherwise
   423      * {@code false} otherwise
   424      */
   424      */
   425     public boolean isAnyPolicyInhibited() {
   425     public boolean isAnyPolicyInhibited() {
   426         return anyPolicyInhibited;
   426         return anyPolicyInhibited;
   427     }
   427     }
   428 
   428 
   430      * Sets the PolicyQualifiersRejected flag. If this flag is true,
   430      * Sets the PolicyQualifiersRejected flag. If this flag is true,
   431      * certificates that include policy qualifiers in a certificate
   431      * certificates that include policy qualifiers in a certificate
   432      * policies extension that is marked critical are rejected.
   432      * policies extension that is marked critical are rejected.
   433      * If the flag is false, certificates are not rejected on this basis.
   433      * If the flag is false, certificates are not rejected on this basis.
   434      *
   434      *
   435      * <p> When a <code>PKIXParameters</code> object is created, this flag is
   435      * <p> When a {@code PKIXParameters} object is created, this flag is
   436      * set to true. This setting reflects the most common (and simplest)
   436      * set to true. This setting reflects the most common (and simplest)
   437      * strategy for processing policy qualifiers. Applications that want to use
   437      * strategy for processing policy qualifiers. Applications that want to use
   438      * a more sophisticated policy must set this flag to false.
   438      * a more sophisticated policy must set this flag to false.
   439      * <p>
   439      * <p>
   440      * Note that the PKIX certification path validation algorithm specifies
   440      * Note that the PKIX certification path validation algorithm specifies
   457      * Gets the PolicyQualifiersRejected flag. If this flag is true,
   457      * Gets the PolicyQualifiersRejected flag. If this flag is true,
   458      * certificates that include policy qualifiers in a certificate policies
   458      * certificates that include policy qualifiers in a certificate policies
   459      * extension that is marked critical are rejected.
   459      * extension that is marked critical are rejected.
   460      * If the flag is false, certificates are not rejected on this basis.
   460      * If the flag is false, certificates are not rejected on this basis.
   461      *
   461      *
   462      * <p> When a <code>PKIXParameters</code> object is created, this flag is
   462      * <p> When a {@code PKIXParameters} object is created, this flag is
   463      * set to true. This setting reflects the most common (and simplest)
   463      * set to true. This setting reflects the most common (and simplest)
   464      * strategy for processing policy qualifiers. Applications that want to use
   464      * strategy for processing policy qualifiers. Applications that want to use
   465      * a more sophisticated policy must set this flag to false.
   465      * a more sophisticated policy must set this flag to false.
   466      *
   466      *
   467      * @return the current value of the PolicyQualifiersRejected flag
   467      * @return the current value of the PolicyQualifiersRejected flag
   471         return policyQualifiersRejected;
   471         return policyQualifiersRejected;
   472     }
   472     }
   473 
   473 
   474     /**
   474     /**
   475      * Returns the time for which the validity of the certification path
   475      * Returns the time for which the validity of the certification path
   476      * should be determined. If <code>null</code>, the current time is used.
   476      * should be determined. If {@code null}, the current time is used.
   477      * <p>
   477      * <p>
   478      * Note that the <code>Date</code> returned is copied to protect against
   478      * Note that the {@code Date} returned is copied to protect against
   479      * subsequent modifications.
   479      * subsequent modifications.
   480      *
   480      *
   481      * @return the <code>Date</code>, or <code>null</code> if not set
   481      * @return the {@code Date}, or {@code null} if not set
   482      * @see #setDate
   482      * @see #setDate
   483      */
   483      */
   484     public Date getDate() {
   484     public Date getDate() {
   485         if (date == null)
   485         if (date == null)
   486             return null;
   486             return null;
   488             return (Date) this.date.clone();
   488             return (Date) this.date.clone();
   489     }
   489     }
   490 
   490 
   491     /**
   491     /**
   492      * Sets the time for which the validity of the certification path
   492      * Sets the time for which the validity of the certification path
   493      * should be determined. If <code>null</code>, the current time is used.
   493      * should be determined. If {@code null}, the current time is used.
   494      * <p>
   494      * <p>
   495      * Note that the <code>Date</code> supplied here is copied to protect
   495      * Note that the {@code Date} supplied here is copied to protect
   496      * against subsequent modifications.
   496      * against subsequent modifications.
   497      *
   497      *
   498      * @param date the <code>Date</code>, or <code>null</code> for the
   498      * @param date the {@code Date}, or {@code null} for the
   499      * current time
   499      * current time
   500      * @see #getDate
   500      * @see #getDate
   501      */
   501      */
   502     public void setDate(Date date) {
   502     public void setDate(Date date) {
   503         if (date != null)
   503         if (date != null)
   505         else
   505         else
   506             date = null;
   506             date = null;
   507     }
   507     }
   508 
   508 
   509     /**
   509     /**
   510      * Sets a <code>List</code> of additional certification path checkers. If
   510      * Sets a {@code List} of additional certification path checkers. If
   511      * the specified <code>List</code> contains an object that is not a
   511      * the specified {@code List} contains an object that is not a
   512      * <code>PKIXCertPathChecker</code>, it is ignored.
   512      * {@code PKIXCertPathChecker}, it is ignored.
   513      * <p>
   513      * <p>
   514      * Each <code>PKIXCertPathChecker</code> specified implements
   514      * Each {@code PKIXCertPathChecker} specified implements
   515      * additional checks on a certificate. Typically, these are checks to
   515      * additional checks on a certificate. Typically, these are checks to
   516      * process and verify private extensions contained in certificates.
   516      * process and verify private extensions contained in certificates.
   517      * Each <code>PKIXCertPathChecker</code> should be instantiated with any
   517      * Each {@code PKIXCertPathChecker} should be instantiated with any
   518      * initialization parameters needed to execute the check.
   518      * initialization parameters needed to execute the check.
   519      * <p>
   519      * <p>
   520      * This method allows sophisticated applications to extend a PKIX
   520      * This method allows sophisticated applications to extend a PKIX
   521      * <code>CertPathValidator</code> or <code>CertPathBuilder</code>.
   521      * {@code CertPathValidator} or {@code CertPathBuilder}.
   522      * Each of the specified <code>PKIXCertPathChecker</code>s will be called,
   522      * Each of the specified {@code PKIXCertPathChecker}s will be called,
   523      * in turn, by a PKIX <code>CertPathValidator</code> or
   523      * in turn, by a PKIX {@code CertPathValidator} or
   524      * <code>CertPathBuilder</code> for each certificate processed or
   524      * {@code CertPathBuilder} for each certificate processed or
   525      * validated.
   525      * validated.
   526      * <p>
   526      * <p>
   527      * Regardless of whether these additional <code>PKIXCertPathChecker</code>s
   527      * Regardless of whether these additional {@code PKIXCertPathChecker}s
   528      * are set, a PKIX <code>CertPathValidator</code> or
   528      * are set, a PKIX {@code CertPathValidator} or
   529      * <code>CertPathBuilder</code> must perform all of the required PKIX
   529      * {@code CertPathBuilder} must perform all of the required PKIX
   530      * checks on each certificate. The one exception to this rule is if the
   530      * checks on each certificate. The one exception to this rule is if the
   531      * RevocationEnabled flag is set to false (see the {@link
   531      * RevocationEnabled flag is set to false (see the {@link
   532      * #setRevocationEnabled setRevocationEnabled} method).
   532      * #setRevocationEnabled setRevocationEnabled} method).
   533      * <p>
   533      * <p>
   534      * Note that the <code>List</code> supplied here is copied and each
   534      * Note that the {@code List} supplied here is copied and each
   535      * <code>PKIXCertPathChecker</code> in the list is cloned to protect
   535      * {@code PKIXCertPathChecker} in the list is cloned to protect
   536      * against subsequent modifications.
   536      * against subsequent modifications.
   537      *
   537      *
   538      * @param checkers a <code>List</code> of <code>PKIXCertPathChecker</code>s.
   538      * @param checkers a {@code List} of {@code PKIXCertPathChecker}s.
   539      * May be <code>null</code>, in which case no additional checkers will be
   539      * May be {@code null}, in which case no additional checkers will be
   540      * used.
   540      * used.
   541      * @throws ClassCastException if any of the elements in the list
   541      * @throws ClassCastException if any of the elements in the list
   542      * are not of type <code>java.security.cert.PKIXCertPathChecker</code>
   542      * are not of type {@code java.security.cert.PKIXCertPathChecker}
   543      * @see #getCertPathCheckers
   543      * @see #getCertPathCheckers
   544      */
   544      */
   545     public void setCertPathCheckers(List<PKIXCertPathChecker> checkers) {
   545     public void setCertPathCheckers(List<PKIXCertPathChecker> checkers) {
   546         if (checkers != null) {
   546         if (checkers != null) {
   547             List<PKIXCertPathChecker> tmpList =
   547             List<PKIXCertPathChecker> tmpList =
   554             this.certPathCheckers = new ArrayList<PKIXCertPathChecker>();
   554             this.certPathCheckers = new ArrayList<PKIXCertPathChecker>();
   555         }
   555         }
   556     }
   556     }
   557 
   557 
   558     /**
   558     /**
   559      * Returns the <code>List</code> of certification path checkers.
   559      * Returns the {@code List} of certification path checkers.
   560      * The returned <code>List</code> is immutable, and each
   560      * The returned {@code List} is immutable, and each
   561      * <code>PKIXCertPathChecker</code> in the <code>List</code> is cloned
   561      * {@code PKIXCertPathChecker} in the {@code List} is cloned
   562      * to protect against subsequent modifications.
   562      * to protect against subsequent modifications.
   563      *
   563      *
   564      * @return an immutable <code>List</code> of
   564      * @return an immutable {@code List} of
   565      * <code>PKIXCertPathChecker</code>s (may be empty, but not
   565      * {@code PKIXCertPathChecker}s (may be empty, but not
   566      * <code>null</code>)
   566      * {@code null})
   567      * @see #setCertPathCheckers
   567      * @see #setCertPathCheckers
   568      */
   568      */
   569     public List<PKIXCertPathChecker> getCertPathCheckers() {
   569     public List<PKIXCertPathChecker> getCertPathCheckers() {
   570         List<PKIXCertPathChecker> tmpList = new ArrayList<PKIXCertPathChecker>();
   570         List<PKIXCertPathChecker> tmpList = new ArrayList<PKIXCertPathChecker>();
   571         for (PKIXCertPathChecker ck : certPathCheckers) {
   571         for (PKIXCertPathChecker ck : certPathCheckers) {
   573         }
   573         }
   574         return Collections.unmodifiableList(tmpList);
   574         return Collections.unmodifiableList(tmpList);
   575     }
   575     }
   576 
   576 
   577     /**
   577     /**
   578      * Adds a <code>PKIXCertPathChecker</code> to the list of certification
   578      * Adds a {@code PKIXCertPathChecker} to the list of certification
   579      * path checkers. See the {@link #setCertPathCheckers setCertPathCheckers}
   579      * path checkers. See the {@link #setCertPathCheckers setCertPathCheckers}
   580      * method for more details.
   580      * method for more details.
   581      * <p>
   581      * <p>
   582      * Note that the <code>PKIXCertPathChecker</code> is cloned to protect
   582      * Note that the {@code PKIXCertPathChecker} is cloned to protect
   583      * against subsequent modifications.
   583      * against subsequent modifications.
   584      *
   584      *
   585      * @param checker a <code>PKIXCertPathChecker</code> to add to the list of
   585      * @param checker a {@code PKIXCertPathChecker} to add to the list of
   586      * checks. If <code>null</code>, the checker is ignored (not added to list).
   586      * checks. If {@code null}, the checker is ignored (not added to list).
   587      */
   587      */
   588     public void addCertPathChecker(PKIXCertPathChecker checker) {
   588     public void addCertPathChecker(PKIXCertPathChecker checker) {
   589         if (checker != null) {
   589         if (checker != null) {
   590             certPathCheckers.add((PKIXCertPathChecker)checker.clone());
   590             certPathCheckers.add((PKIXCertPathChecker)checker.clone());
   591         }
   591         }
   592     }
   592     }
   593 
   593 
   594     /**
   594     /**
   595      * Returns the signature provider's name, or <code>null</code>
   595      * Returns the signature provider's name, or {@code null}
   596      * if not set.
   596      * if not set.
   597      *
   597      *
   598      * @return the signature provider's name (or <code>null</code>)
   598      * @return the signature provider's name (or {@code null})
   599      * @see #setSigProvider
   599      * @see #setSigProvider
   600      */
   600      */
   601     public String getSigProvider() {
   601     public String getSigProvider() {
   602         return this.sigProvider;
   602         return this.sigProvider;
   603     }
   603     }
   604 
   604 
   605     /**
   605     /**
   606      * Sets the signature provider's name. The specified provider will be
   606      * Sets the signature provider's name. The specified provider will be
   607      * preferred when creating {@link java.security.Signature Signature}
   607      * preferred when creating {@link java.security.Signature Signature}
   608      * objects. If <code>null</code> or not set, the first provider found
   608      * objects. If {@code null} or not set, the first provider found
   609      * supporting the algorithm will be used.
   609      * supporting the algorithm will be used.
   610      *
   610      *
   611      * @param sigProvider the signature provider's name (or <code>null</code>)
   611      * @param sigProvider the signature provider's name (or {@code null})
   612      * @see #getSigProvider
   612      * @see #getSigProvider
   613     */
   613     */
   614     public void setSigProvider(String sigProvider) {
   614     public void setSigProvider(String sigProvider) {
   615         this.sigProvider = sigProvider;
   615         this.sigProvider = sigProvider;
   616     }
   616     }
   617 
   617 
   618     /**
   618     /**
   619      * Returns the required constraints on the target certificate.
   619      * Returns the required constraints on the target certificate.
   620      * The constraints are returned as an instance of <code>CertSelector</code>.
   620      * The constraints are returned as an instance of {@code CertSelector}.
   621      * If <code>null</code>, no constraints are defined.
   621      * If {@code null}, no constraints are defined.
   622      *
   622      *
   623      * <p>Note that the <code>CertSelector</code> returned is cloned
   623      * <p>Note that the {@code CertSelector} returned is cloned
   624      * to protect against subsequent modifications.
   624      * to protect against subsequent modifications.
   625      *
   625      *
   626      * @return a <code>CertSelector</code> specifying the constraints
   626      * @return a {@code CertSelector} specifying the constraints
   627      * on the target certificate (or <code>null</code>)
   627      * on the target certificate (or {@code null})
   628      * @see #setTargetCertConstraints
   628      * @see #setTargetCertConstraints
   629      */
   629      */
   630     public CertSelector getTargetCertConstraints() {
   630     public CertSelector getTargetCertConstraints() {
   631         if (certSelector != null) {
   631         if (certSelector != null) {
   632             return (CertSelector) certSelector.clone();
   632             return (CertSelector) certSelector.clone();
   636     }
   636     }
   637 
   637 
   638     /**
   638     /**
   639      * Sets the required constraints on the target certificate.
   639      * Sets the required constraints on the target certificate.
   640      * The constraints are specified as an instance of
   640      * The constraints are specified as an instance of
   641      * <code>CertSelector</code>. If <code>null</code>, no constraints are
   641      * {@code CertSelector}. If {@code null}, no constraints are
   642      * defined.
   642      * defined.
   643      *
   643      *
   644      * <p>Note that the <code>CertSelector</code> specified is cloned
   644      * <p>Note that the {@code CertSelector} specified is cloned
   645      * to protect against subsequent modifications.
   645      * to protect against subsequent modifications.
   646      *
   646      *
   647      * @param selector a <code>CertSelector</code> specifying the constraints
   647      * @param selector a {@code CertSelector} specifying the constraints
   648      * on the target certificate (or <code>null</code>)
   648      * on the target certificate (or {@code null})
   649      * @see #getTargetCertConstraints
   649      * @see #getTargetCertConstraints
   650      */
   650      */
   651     public void setTargetCertConstraints(CertSelector selector) {
   651     public void setTargetCertConstraints(CertSelector selector) {
   652         if (selector != null)
   652         if (selector != null)
   653             certSelector = (CertSelector) selector.clone();
   653             certSelector = (CertSelector) selector.clone();
   654         else
   654         else
   655             certSelector = null;
   655             certSelector = null;
   656     }
   656     }
   657 
   657 
   658     /**
   658     /**
   659      * Makes a copy of this <code>PKIXParameters</code> object. Changes
   659      * Makes a copy of this {@code PKIXParameters} object. Changes
   660      * to the copy will not affect the original and vice versa.
   660      * to the copy will not affect the original and vice versa.
   661      *
   661      *
   662      * @return a copy of this <code>PKIXParameters</code> object
   662      * @return a copy of this {@code PKIXParameters} object
   663      */
   663      */
   664     public Object clone() {
   664     public Object clone() {
   665         try {
   665         try {
   666             PKIXParameters copy = (PKIXParameters)super.clone();
   666             PKIXParameters copy = (PKIXParameters)super.clone();
   667 
   667