The PKIXRevocationChecker Class

Both the CertPathBuilder and CertPathValidator certificate path framework classes are updated to include the following method:

public final CertPathChecker getRevocationChecker()

Each invocation of this method returns a new CertPathChecker instance. A PKIX implementation returns objects of type PKIXRevocationChecker. Despite being an instance of the CertPathChecker class, the PKIXRevocationChecker class that is returned serves only as a vehicle for the certificate path application to specify additional parameters and options to be used by CertPathBuilder or CertPathValidator when checking the revocation status of certificates. Here is an example of the use of the PKIXRevocationChecker object:

PKIXRevocationChecker rc = (PKIXRevocationChecker)builder.getRevocationChecker();
    HashSet<PKIXRevocationChecker.Option> options = new HashSet<PKIXRevocationChecker.Option>();
    options.add(PKIXRevocationChecker.Option.ONLY_END_ENTITY);
    rc.setOptions(options);
    params.addCertPathChecker(rc);
    CertPathBuilderResult result = builder.build(params);

The following examples are available for specifying additional parameters and options within the PKIXRevocationChecker class:

• Setting the URI that identifies the location of the OCSP responder:

  /**
   * Sets the URI that identifies the location of the OCSP responder.
   * This setting overrides the "ocsp.responderURL" security property.
   *
   * uri is the responder URI
   */
  public void setOcspResponder(URI uri)

• Getting the URI that identifies the location of the OCSP responder:

  /**
   * Gets the URI from the PKIXRevocationChecker that identifies the location of the OCSP responder.
   *
   * Returns the responder URI, or null if not set.
   */
  public URI getOcspResponder()

• Setting the OCSP responder's certificate:

  /**
   * Sets the OCSP responder's certificate. This overrides the
   * ocsp.responderCertSubjectName,
   * ocsp.responderCertIssuerName,
   * and ocsp.responderCertSerialNumber security properties.
   *
   * cert is the responder's certificate.
   */
  public void setOcspResponderCert(X509Certificate cert)

• Getting the OCSP responder's certificate from the PKIXRevocationChecker:

  /**
   * Gets the OCSP responder's certificate from the PKIXRevocationChecker.
   *
   * Returns the responder's certificate, or null if not set.
   */
  public X509Certificate getOcspResponderCert()

• Setting the optional OCSP request extension:

  /**
   * Sets the optional OCSP request extensions.
   *
   * extensions is a list of OCSP request extensions.
   * The list is copied to protect against subsequent modification.
   * Currently only the nonce extension is supported.
   */
  public void setOcspExtensions(List<Extension> extensions)

• Getting the optional OCSP request extension from the PKIXRevocationChecker:

  /**
   * Gets the optional OCSP request extensions from the PKIXRevocationChecker.
   *
   * Returns an unmodifiable list of extensions.
   * Returns an empty list if no extensions have been specified.
   *
   */
  public List<Extension> getOcspExtensions()

• Setting the optional OCSP responses:

  /**
   * Sets the optional OCSP responses.
   * These are sometimes referred to as "stapled" OCSP responses.
   * These responses are used to determine the revocation status of the
   * the specified certificates when OCSP is used.
   *
   * responses is a map of OCSP responses. Each key is an
   * X509Certificate that maps to the corresponding
   * DER-encoded OCSP response for that certificate.
   * A copy of the map is made to protect against subsequent modification.
   */
  public void setOcspResponses(Map<X509Certificate> responses)

• Getting the optional OCSP responses from the PKIXRevocationChecker:

  /**
   * Gets the optional OCSP responses from the PKIXRevocationChecker.
   *
   * Returns a map of OCSP responses. Each key is an
   * X509Certificate that maps to the corresponding
   * DER-encoded OCSP response for that certificate.
   * A copy of the map is returned to protect against subsequent modification.
   * Returns an empty map if no responses have been specified.
   */
  public Map<X509Certificate> getOcspResponses()

• Setting the revocation options:

  /**
   * Sets the revocation options.
   *
   * options is a set of revocation options. The set is copied to protect
   * against subsequent modification.
   */
  public void setOptions(Set<Option> options)

• Getting the revocation options from the PKIXRevocationChecker:

  /**
   * Gets the revocation options from the PKIXRevocationChecker.
   *
   * Returns an unmodifiable set of revocation options, or an empty set if
   * none have been specified.
   */
  public Set<Option> getOptions()

• Revocation options:

  /**
   * These are the various revocation options that can be specified.
   */
  public enum Option {
      /**
       * Only check the revocation status of end-entity certificates.
       * If specified, this option will take precedence over the setting
       * of the "com.ibm.security.onlyCheckRevocationOfEECert" system property.
       */
      ONLY_END_ENTITY,
      /**
       * Prefer CRLs to OCSP. The default behavior is to prefer OCSP.
       * This option has meaning only if OCSP is enabled via the ocsp.enable
       * security property.
       */
      PREFER_CRLS,
      /**
       * Disable the revocation checking fallback mechanism.
       */
       NO_FALLBACK,
      /**
       * Ignore network failures. The default behavior is to consider it a
       * failure if the revocation status of a certificate cannot be obtained
       * due to a network error. This option applies to both OCSP and CRLs.
       */
      SOFT_FAIL
  }