Abstract class for managing a variety of identity certificates.
An identity certificate is a binding of a principal to a public key which
is vouched for by another principal.  (A principal represents
an entity such as an individual user, a group, or a corporation.)

This class is an abstraction for certificates that have different
formats but important common uses.  For example, different types of
certificates, such as X.509 and PGP, share general certificate
functionality (like encoding and verifying) and
some types of information (like a public key).

X.509, PGP, and SDSI certificates can all be implemented by
subclassing the Certificate class, even though they contain different
sets of information, and they store and retrieve the information in
different ways.

Alternate Certificate class for serialization.

Certificate Encoding Exception. This is thrown whenever an error
occurs while attempting to encode a certificate.

This exception indicates one of a variety of certificate problems.

Certificate Expired Exception. This is thrown whenever the current
Date or the specified Date is after the
notAfter date/time specified in the validity period
of the certificate.

This class defines the functionality of a certificate factory, which is
used to generate certificate, certification path (CertPath)
and certificate revocation list (CRL) objects from their encodings.

For encodings consisting of multiple certificates, use
generateCertificates when you want to
parse a collection of possibly unrelated certificates. Otherwise,
use generateCertPath when you want to generate
a CertPath (a certificate chain) and subsequently
validate it with a CertPathValidator.

A certificate factory for X.509 must return certificates that are an
instance of java.security.cert.X509Certificate, and CRLs
that are an instance of java.security.cert.X509CRL.

The following example reads a file with Base64 encoded certificates,
which are each bounded at the beginning by -----BEGIN CERTIFICATE-----, and
bounded at the end by -----END CERTIFICATE-----. We convert the
FileInputStream (which does not support mark
and reset) to a BufferedInputStream (which
supports those methods), so that each call to
generateCertificate consumes only one certificate, and the
read position of the input stream is positioned to the next certificate in
the file:



FileInputStream fis = new FileInputStream(filename);
BufferedInputStream bis = new BufferedInputStream(fis);

CertificateFactory cf = CertificateFactory.getInstance("X.509");

while (bis.available() > 0) {
   Certificate cert = cf.generateCertificate(bis);
   System.out.println(cert.toString());
}

The following example parses a PKCS#7-formatted certificate reply stored
in a file and extracts all the certificates from it:



FileInputStream fis = new FileInputStream(filename);
CertificateFactory cf = CertificateFactory.getInstance("X.509");
Collection c = cf.generateCertificates(fis);
Iterator i = c.iterator();
while (i.hasNext()) {
   Certificate cert = (Certificate)i.next();
   System.out.println(cert);
}

 Every implementation of the Java platform is required to support the
following standard CertificateFactory type:

X.509

and the following standard CertPath encodings:

PKCS7
PkiPath

The type and encodings are described in the
CertificateFactory section and the
CertPath Encodings section of the
Java Cryptography Architecture Standard Algorithm Name Documentation.
Consult the release documentation for your implementation to see if any
other types or encodings are supported.

This class defines the Service Provider Interface (SPI)
for the CertificateFactory class.
All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a certificate factory for a particular certificate type, e.g., X.509.

Certificate factories are used to generate certificate, certification path
(CertPath) and certificate revocation list (CRL) objects from
their encodings.

A certificate factory for X.509 must return certificates that are an
instance of java.security.cert.X509Certificate, and CRLs
that are an instance of java.security.cert.X509CRL.

Certificate is not yet valid exception. This is thrown whenever
the current Date or the specified Date
is before the notBefore date/time in the Certificate
validity period.

Certificate Parsing Exception. This is thrown whenever an
invalid DER-encoded certificate is parsed or unsupported DER features
are found in the Certificate.

An exception that indicates an X.509 certificate is revoked. A
CertificateRevokedException contains additional information
about the revoked certificate, such as the date on which the
certificate was revoked and the reason it was revoked.

An immutable sequence of certificates (a certification path).

This is an abstract class that defines the methods common to all
CertPaths. Subclasses can handle different kinds of
certificates (X.509, PGP, etc.).

All CertPath objects have a type, a list of
Certificates, and one or more supported encodings. Because the
CertPath class is immutable, a CertPath cannot
change in any externally visible way after being constructed. This
stipulation applies to all public fields and methods of this class and any
added or overridden by subclasses.

The type is a String that identifies the type of
Certificates in the certification path. For each
certificate cert in a certification path certPath,
cert.getType().equals(certPath.getType()) must be
true.

The list of Certificates is an ordered List of
zero or more Certificates. This List and all
of the Certificates contained in it must be immutable.

Each CertPath object must support one or more encodings
so that the object can be translated into a byte array for storage or
transmission to other parties. Preferably, these encodings should be
well-documented standards (such as PKCS#7). One of the encodings supported
by a CertPath is considered the default encoding. This
encoding is used if no encoding is explicitly requested (for the
getEncoded() method, for instance).

All CertPath objects are also Serializable.
CertPath objects are resolved into an alternate
CertPathRep object during serialization. This allows
a CertPath object to be serialized into an equivalent
representation regardless of its underlying implementation.

CertPath objects can be created with a
CertificateFactory or they can be returned by other classes,
such as a CertPathBuilder.

By convention, X.509 CertPaths (consisting of
X509Certificates), are ordered starting with the target
certificate and ending with a certificate issued by the trust anchor. That
is, the issuer of one certificate is the subject of the following one. The
certificate representing the TrustAnchor should not be
included in the certification path. Unvalidated X.509 CertPaths
may not follow these conventions. PKIX CertPathValidators will
detect any departure from these conventions that cause the certification
path to be invalid and throw a CertPathValidatorException.

 Every implementation of the Java platform is required to support the
following standard CertPath encodings:

PKCS7
PkiPath

These encodings are described in the
CertPath Encodings section of the
Java Cryptography Architecture Standard Algorithm Name Documentation.
Consult the release documentation for your implementation to see if any
other encodings are supported.

Concurrent Access

All CertPath objects must be thread-safe. That is, multiple
threads may concurrently invoke the methods defined in this class on a
single CertPath object (or more than one) with no
ill effects. This is also true for the List returned by
CertPath.getCertificates.

Requiring CertPath objects to be immutable and thread-safe
allows them to be passed around to various pieces of code without worrying
about coordinating access.  Providing this thread-safety is
generally not difficult, since the CertPath and
List objects in question are immutable.

Alternate CertPath class for serialization.

A class for building certification paths (also known as certificate chains).

This class uses a provider-based architecture.
To create a CertPathBuilder, call
one of the static getInstance methods, passing in the
algorithm name of the CertPathBuilder desired and optionally
the name of the provider desired.

Once a CertPathBuilder object has been created, certification
paths can be constructed by calling the build method and
passing it an algorithm-specific set of parameters. If successful, the
result (including the CertPath that was built) is returned
in an object that implements the CertPathBuilderResult
interface.

The getRevocationChecker() method allows an application to specify
additional algorithm-specific parameters and options used by the
CertPathBuilder when checking the revocation status of certificates.
Here is an example demonstrating how it is used with the PKIX algorithm:



CertPathBuilder cpb = CertPathBuilder.getInstance("PKIX");
PKIXRevocationChecker rc = (PKIXRevocationChecker)cpb.getRevocationChecker();
rc.setOptions(EnumSet.of(Option.PREFER_CRLS));
params.addCertPathChecker(rc);
CertPathBuilderResult cpbr = cpb.build(params);

Every implementation of the Java platform is required to support the
following standard CertPathBuilder algorithm:

PKIX

This algorithm is described in the
CertPathBuilder section of the
Java Cryptography Architecture Standard Algorithm Name Documentation.
Consult the release documentation for your implementation to see if any
other algorithms are supported.


Concurrent Access

The static methods of this class are guaranteed to be thread-safe.
Multiple threads may concurrently invoke the static methods defined in
this class with no ill effects.

However, this is not true for the non-static methods defined by this class.
Unless otherwise documented by a specific provider, threads that need to
access a single CertPathBuilder instance concurrently should
synchronize amongst themselves and provide the necessary locking. Multiple
threads each manipulating a different CertPathBuilder instance
need not synchronize.

An exception indicating one of a variety of problems encountered when
building a certification path with a CertPathBuilder.

A CertPathBuilderException provides support for wrapping
exceptions. The getCause method returns the throwable,
if any, that caused this exception to be thrown.

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.

A specification of the result of a certification path builder algorithm.
All results returned by the CertPathBuilder.build method must implement this interface.

At a minimum, a CertPathBuilderResult contains the
CertPath built by the CertPathBuilder instance.
Implementations of this interface may add methods to return implementation
or algorithm specific information, such as debugging information or
certification path validation results.

Concurrent Access

Unless otherwise specified, the methods defined in this interface 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.

The Service Provider Interface (SPI)
for the CertPathBuilder class. All
CertPathBuilder implementations must include a class (the
SPI class) that extends this class (CertPathBuilderSpi) and
implements all of its methods. In general, instances of this class should
only be accessed through the CertPathBuilder class. For
details, see the Java Cryptography Architecture.

Concurrent Access

Instances of this class need not be protected against concurrent
access from multiple threads. Threads that need to access a single
CertPathBuilderSpi instance concurrently should synchronize
amongst themselves and provide the necessary locking before calling the
wrapping CertPathBuilder object.

However, implementations of CertPathBuilderSpi may still
encounter concurrency issues, since multiple threads each
manipulating a different CertPathBuilderSpi instance need not
synchronize.

Performs one or more checks on each Certificate of a
CertPath.

A CertPathChecker implementation is typically created to extend
a certification path validation algorithm. For example, an implementation
may check for and process a critical private extension of each certificate
in a certification path.

A specification of certification path algorithm parameters.
The purpose of this interface is to group (and provide type safety for)
all CertPath parameter specifications. All
CertPath parameter specifications must implement this
interface.

A class for validating certification paths (also known as certificate
chains).

This class uses a provider-based architecture.
To create a CertPathValidator,
call one of the static getInstance methods, passing in the
algorithm name of the CertPathValidator desired and
optionally the name of the provider desired.

Once a CertPathValidator object has been created, it can
be used to validate certification paths by calling the validate method and passing it the CertPath to be validated
and an algorithm-specific set of parameters. If successful, the result is
returned in an object that implements the
CertPathValidatorResult interface.

The getRevocationChecker() method allows an application to specify
additional algorithm-specific parameters and options used by the
CertPathValidator when checking the revocation status of
certificates. Here is an example demonstrating how it is used with the PKIX
algorithm:



CertPathValidator cpv = CertPathValidator.getInstance("PKIX");
PKIXRevocationChecker rc = (PKIXRevocationChecker)cpv.getRevocationChecker();
rc.setOptions(EnumSet.of(Option.SOFT_FAIL));
params.addCertPathChecker(rc);
CertPathValidatorResult cpvr = cpv.validate(path, params);

Every implementation of the Java platform is required to support the
following standard CertPathValidator algorithm:

PKIX

This algorithm is described in the
CertPathValidator section of the
Java Cryptography Architecture Standard Algorithm Name Documentation.
Consult the release documentation for your implementation to see if any
other algorithms are supported.


Concurrent Access

The static methods of this class are guaranteed to be thread-safe.
Multiple threads may concurrently invoke the static methods defined in
this class with no ill effects.

However, this is not true for the non-static methods defined by this class.
Unless otherwise documented by a specific provider, threads that need to
access a single CertPathValidator instance concurrently should
synchronize amongst themselves and provide the necessary locking. Multiple
threads each manipulating a different CertPathValidator
instance need not synchronize.

An exception indicating one of a variety of problems encountered when
validating a certification path.

A CertPathValidatorException provides support for wrapping
exceptions. The getCause method returns the throwable,
if any, that caused this exception to be thrown.

A CertPathValidatorException may also include the
certification path that was being validated when the exception was thrown,
the index of the certificate in the certification path that caused the
exception to be thrown, and the reason that caused the failure. Use the
getCertPath, getIndex, and
getReason methods to retrieve this information.


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.

The reason the validation algorithm failed.

A specification of the result of a certification path validator algorithm.

The purpose of this interface is to group (and provide type safety
for) all certification path validator results. All results returned
by the CertPathValidator.validate
method must implement this interface.

The Service Provider Interface (SPI)
for the CertPathValidator class. All
CertPathValidator implementations must include a class (the
SPI class) that extends this class (CertPathValidatorSpi)
and implements all of its methods. In general, instances of this class
should only be accessed through the CertPathValidator class.
For details, see the Java Cryptography Architecture.

Concurrent Access

Instances of this class need not be protected against concurrent
access from multiple threads. Threads that need to access a single
CertPathValidatorSpi instance concurrently should synchronize
amongst themselves and provide the necessary locking before calling the
wrapping CertPathValidator object.

However, implementations of CertPathValidatorSpi may still
encounter concurrency issues, since multiple threads each
manipulating a different CertPathValidatorSpi instance need not
synchronize.

A selector that defines a set of criteria for selecting
Certificates. Classes that implement this interface
are often used to specify which Certificates should
be retrieved from a CertStore.

Concurrent Access

Unless otherwise specified, the methods defined in this interface 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.

A class for retrieving Certificates and CRLs
from a repository.

This class uses a provider-based architecture.
To create a CertStore, call one of the static
getInstance methods, passing in the type of
CertStore desired, any applicable initialization parameters
and optionally the name of the provider desired.

Once the CertStore has been created, it can be used to
retrieve Certificates and CRLs by calling its
getCertificates and
getCRLs methods.

Unlike a KeyStore, which provides access
to a cache of private keys and trusted certificates, a
CertStore is designed to provide access to a potentially
vast repository of untrusted certificates and CRLs. For example, an LDAP
implementation of CertStore provides access to certificates
and CRLs stored in one or more directories using the LDAP protocol and the
schema as defined in the RFC service attribute.

 Every implementation of the Java platform is required to support the
following standard CertStore type:

Collection

This type is described in the
CertStore section of the
Java Cryptography Architecture Standard Algorithm Name Documentation.
Consult the release documentation for your implementation to see if any
other types are supported.


Concurrent Access

All public methods of CertStore objects must be thread-safe.
That is, multiple threads may concurrently invoke these methods on a
single CertStore object (or more than one) with no
ill effects. This allows a CertPathBuilder to search for a
CRL while simultaneously searching for further certificates, for instance.

The static methods of this class are also guaranteed to be thread-safe.
Multiple threads may concurrently invoke the static methods defined in
this class with no ill effects.

An exception indicating one of a variety of problems retrieving
certificates and CRLs from a CertStore.

A CertStoreException provides support for wrapping
exceptions. The getCause method returns the throwable,
if any, that caused this exception to be thrown.

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.

A specification of CertStore parameters.

The purpose of this interface is to group (and provide type safety for)
all CertStore parameter specifications. All
CertStore parameter specifications must implement this
interface.

Typically, a CertStoreParameters object is passed as a parameter
to one of the CertStore.getInstance methods.
The getInstance method returns a CertStore that
is used for retrieving Certificates and CRLs. The
CertStore that is returned is initialized with the specified
parameters. The type of parameters needed may vary between different types
of CertStores.

The Service Provider Interface (SPI)
for the CertStore class. All CertStore
implementations must include a class (the SPI class) that extends
this class (CertStoreSpi), provides a constructor with
a single argument of type CertStoreParameters, and implements
all of its methods. In general, instances of this class should only be
accessed through the CertStore class.
For details, see the Java Cryptography Architecture.

Concurrent Access

The public methods of all CertStoreSpi objects must be
thread-safe. That is, multiple threads may concurrently invoke these
methods on a single CertStoreSpi object (or more than one)
with no ill effects. This allows a CertPathBuilder to search
for a CRL while simultaneously searching for further certificates, for
instance.

Simple CertStoreSpi implementations will probably ensure
thread safety by adding a synchronized keyword to their
engineGetCertificates and engineGetCRLs methods.
More sophisticated ones may allow truly concurrent access.

Parameters used as input for the Collection CertStore
algorithm.

This class is used to provide necessary configuration parameters
to implementations of the Collection CertStore
algorithm. The only parameter included in this class is the
Collection from which the CertStore will
retrieve certificates and CRLs.

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.

This class is an abstraction of certificate revocation lists (CRLs) that
have different formats but important common uses. For example, all CRLs
share the functionality of listing revoked certificates, and can be queried
on whether or not they list a given certificate.

Specialized CRL types can be defined by subclassing off of this abstract
class.

CRL (Certificate Revocation List) Exception.

A selector that defines a set of criteria for selecting CRLs.
Classes that implement this interface are often used to specify
which CRLs should be retrieved from a CertStore.

Concurrent Access

Unless otherwise specified, the methods defined in this interface 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.

Extension ::= SEQUENCE {
    extnId        OBJECT IDENTIFIER,
    critical      BOOLEAN DEFAULT FALSE,
    extnValue     OCTET STRING
            -- contains a DER encoding of a value
            -- of the type registered for use with
            -- the extnId object identifier value
}

This interface represents an X.509 extension.


Extensions provide a means of associating additional attributes with users
or public keys and for managing a certification hierarchy.  The extension
format also allows communities to define private extensions to carry
information unique to those communities.


Each extension contains an object identifier, a criticality setting
indicating whether it is a critical or a non-critical extension, and
and an ASN.1 DER-encoded value. Its ASN.1 definition is:



    Extension ::= SEQUENCE {
        extnId        OBJECT IDENTIFIER,
        critical      BOOLEAN DEFAULT FALSE,
        extnValue     OCTET STRING
                -- contains a DER encoding of a value
                -- of the type registered for use with
                -- the extnId object identifier value
    }


This interface is designed to provide access to a single extension,
unlike X509Extension which is more suitable
for accessing a set of extensions.

Parameters used as input for the LDAP CertStore algorithm.

This class is used to provide necessary configuration parameters (server
name and port number) to implementations of the LDAP CertStore
algorithm.

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.

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.

This class represents the successful result of the PKIX certification
path builder algorithm. All certification paths that are built and
returned using this algorithm are also validated according to the PKIX
certification path validation algorithm.

Instances of PKIXCertPathBuilderResult are returned by
the build method of CertPathBuilder
objects implementing the PKIX algorithm.

All PKIXCertPathBuilderResult objects contain the
certification path constructed by the build algorithm, the
valid policy tree and subject public key resulting from the build
algorithm, and a TrustAnchor describing the certification
authority (CA) that served as a trust anchor for the certification path.

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.

An abstract class that performs one or more checks on an
X509Certificate.

A concrete implementation of the PKIXCertPathChecker class
can be created to extend the PKIX certification path validation algorithm.
For example, an implementation may check for and process a critical private
extension of each certificate in a certification path.

Instances of PKIXCertPathChecker are passed as parameters
using the setCertPathCheckers
or addCertPathChecker methods
of the PKIXParameters and PKIXBuilderParameters
class. Each of the PKIXCertPathCheckers check
methods will be called, in turn, for each certificate processed by a PKIX
CertPathValidator or CertPathBuilder
implementation.

A PKIXCertPathChecker may be called multiple times on
successive certificates in a certification path. Concrete subclasses
are expected to maintain any internal state that may be necessary to
check successive certificates. The init method is used
to initialize the internal state of the checker so that the certificates
of a new certification path may be checked. A stateful implementation
must override the clone method if necessary in
order to allow a PKIX CertPathBuilder to efficiently
backtrack and try other paths. In these situations, the
CertPathBuilder is able to restore prior path validation
states by restoring the cloned PKIXCertPathCheckers.

The order in which the certificates are presented to the
PKIXCertPathChecker may be either in the forward direction
(from target to most-trusted CA) or in the reverse direction (from
most-trusted CA to target). A PKIXCertPathChecker implementation
must support reverse checking (the ability to perform its checks when
it is presented with certificates in the reverse direction) and may
support forward checking (the ability to perform its checks when it is
presented with certificates in the forward direction). The
isForwardCheckingSupported method
indicates whether forward checking is supported.

Additional input parameters required for executing the check may be
specified through constructors of concrete implementations of this class.

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.

This class represents the successful result of the PKIX certification
path validation algorithm.

Instances of PKIXCertPathValidatorResult are returned by the
validate method of
CertPathValidator objects implementing the PKIX algorithm.

 All PKIXCertPathValidatorResult objects contain the
valid policy tree and subject public key resulting from the
validation algorithm, as well as a TrustAnchor describing
the certification authority (CA) that served as a trust anchor for the
certification path.

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.

Parameters used as input for the PKIX CertPathValidator
algorithm.

A PKIX CertPathValidator uses these parameters to
validate a CertPath according to the PKIX certification path
validation algorithm.

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

Once a PKIXParameters object has been created, other parameters
can be specified (by calling setInitialPolicies
or setDate, for instance) and then the
PKIXParameters is passed along with the CertPath
to be validated to CertPathValidator.validate.

Any parameter that is not set (or is set to null) will
be set to the default value for that parameter. The default value for the
date parameter is null, which indicates
the current time when the path is validated. The default for the
remaining parameters is the least constrained.

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.

A PKIXCertPathChecker for checking the revocation status of
certificates with the PKIX algorithm.

A PKIXRevocationChecker checks the revocation status of
certificates with the Online Certificate Status Protocol (OCSP) or
Certificate Revocation Lists (CRLs). OCSP is described in RFC 2560 and
is a network protocol for determining the status of a certificate. A CRL
is a time-stamped list identifying revoked certificates, and RFC 5280
describes an algorithm for determining the revocation status of certificates
using CRLs.

Each PKIXRevocationChecker must be able to check the revocation
status of certificates with OCSP and CRLs. By default, OCSP is the
preferred mechanism for checking revocation status, with CRLs as the
fallback mechanism. However, this preference can be switched to CRLs with
the PREFER_CRLS option. In addition, the fallback
mechanism can be disabled with the NO_FALLBACK
option.

A PKIXRevocationChecker is obtained by calling the
getRevocationChecker method
of a PKIX CertPathValidator. Additional parameters and options
specific to revocation can be set (by calling the
setOcspResponder method for instance). The
PKIXRevocationChecker is added to a PKIXParameters object
using the addCertPathChecker
or setCertPathCheckers method,
and then the PKIXParameters is passed along with the CertPath
to be validated to the validate method
of a PKIX CertPathValidator. When supplying a revocation checker in
this manner, it will be used to check revocation irrespective of the setting
of the RevocationEnabled flag.
Similarly, a PKIXRevocationChecker may be added to a
PKIXBuilderParameters object for use with a PKIX
CertPathBuilder.

Note that when a PKIXRevocationChecker is added to
PKIXParameters, it clones the PKIXRevocationChecker;
thus any subsequent modifications to the PKIXRevocationChecker
have no effect.

Any parameter that is not set (or is set to null) will be set to
the default value for that parameter.

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.

An immutable valid policy tree node as defined by the PKIX certification
path validation algorithm.

One of the outputs of the PKIX certification path validation
algorithm is a valid policy tree, which includes the policies that
were determined to be valid, how this determination was reached,
and any policy qualifiers encountered. This tree is of depth
n, where n is the length of the certification
path that has been validated.

Most applications will not need to examine the valid policy tree.
They can achieve their policy processing goals by setting the
policy-related parameters in PKIXParameters. However,
the valid policy tree is available for more sophisticated applications,
especially those that process policy qualifiers.

PKIXCertPathValidatorResult.getPolicyTree returns the root node of the
valid policy tree. The tree can be traversed using the
getChildren and getParent methods.
Data about a particular node can be retrieved using other methods of
PolicyNode.

Concurrent Access
All PolicyNode objects must be immutable and
thread-safe. Multiple threads may concurrently invoke the methods defined
in this class on a single PolicyNode object (or more than one)
with no ill effects. This stipulation applies to all public fields and
methods of this class and any added or overridden by subclasses.

An immutable policy qualifier represented by the ASN.1 PolicyQualifierInfo
structure.

The ASN.1 definition is as follows:


  PolicyQualifierInfo ::= SEQUENCE {
       policyQualifierId       PolicyQualifierId,
       qualifier               ANY DEFINED BY policyQualifierId }

A certificate policies extension, if present in an X.509 version 3
certificate, contains a sequence of one or more policy information terms,
each of which consists of an object identifier (OID) and optional
qualifiers. In an end-entity certificate, these policy information terms
indicate the policy under which the certificate has been issued and the
purposes for which the certificate may be used. In a CA certificate, these
policy information terms limit the set of policies for certification paths
which include this certificate.

A Set of PolicyQualifierInfo objects are returned
by the PolicyNode.getPolicyQualifiers
method. This allows applications with specific policy requirements to
process and validate each policy qualifier. Applications that need to
process policy qualifiers should explicitly set the
policyQualifiersRejected flag to false (by calling the
PKIXParameters.setPolicyQualifiersRejected method) before validating
a certification path.

Note that the PKIX certification path validation algorithm specifies
that any policy qualifier in a certificate policies extension that is
marked critical must be processed and validated. Otherwise the
certification path must be rejected. If the
policyQualifiersRejected flag is set to false, it is up to
the application to validate all policy qualifiers in this manner in order
to be PKIX compliant.

Concurrent Access

All PolicyQualifierInfo objects must be immutable and
thread-safe. That is, multiple threads may concurrently invoke the
methods defined in this class on a single PolicyQualifierInfo
object (or more than one) with no ill effects. Requiring
PolicyQualifierInfo objects to be immutable and thread-safe
allows them to be passed around to various pieces of code without
worrying about coordinating access.

A trust anchor or most-trusted Certification Authority (CA).

This class represents a "most-trusted CA", which is used as a trust anchor
for validating X.509 certification paths. A most-trusted CA includes the
public key of the CA, the CA's name, and any constraints upon the set of
paths which may be validated using this key. These parameters can be
specified in the form of a trusted X509Certificate or as
individual parameters.

Concurrent Access
All TrustAnchor objects must be immutable and
thread-safe. That is, multiple threads may concurrently invoke the
methods defined in this class on a single TrustAnchor
object (or more than one) with no ill effects. Requiring
TrustAnchor objects to be immutable and thread-safe
allows them to be passed around to various pieces of code without
worrying about coordinating access. This stipulation applies to all
public fields and methods of this class and any added or overridden
by subclasses.

 Abstract class for X.509 certificates. This provides a standard
way to access all the attributes of an X.509 certificate.

In June of 1996, the basic X.509 v3 format was completed by
ISO/IEC and ANSI X9, which is described below in ASN.1:


Certificate  ::=  SEQUENCE  {
    tbsCertificate       TBSCertificate,
    signatureAlgorithm   AlgorithmIdentifier,
    signature            BIT STRING  }

These certificates are widely used to support authentication and
other functionality in Internet security systems. Common applications
include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL),
code signing for trusted software distribution, and Secure Electronic
Transactions (SET).

These certificates are managed and vouched for by Certificate
Authorities (CAs). CAs are services which create certificates by
placing data in the X.509 standard format and then digitally signing
that data. CAs act as trusted third parties, making introductions
between principals who have no direct knowledge of each other.
CA certificates are either signed by themselves, or by some other
CA such as a "root" CA.

More information can be found in
RFC 3280: Internet X.509
Public Key Infrastructure Certificate and CRL Profile.

The ASN.1 definition of tbsCertificate is:


TBSCertificate  ::=  SEQUENCE  {
    version         [0]  EXPLICIT Version DEFAULT v1,
    serialNumber         CertificateSerialNumber,
    signature            AlgorithmIdentifier,
    issuer               Name,
    validity             Validity,
    subject              Name,
    subjectPublicKeyInfo SubjectPublicKeyInfo,
    issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
                         -- If present, version must be v2 or v3
    subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
                         -- If present, version must be v2 or v3
    extensions      [3]  EXPLICIT Extensions OPTIONAL
                         -- If present, version must be v3
    }

Certificates are instantiated using a certificate factory. The following is
an example of how to instantiate an X.509 certificate:


try (InputStream inStream = new FileInputStream("fileName-of-cert")) {
    CertificateFactory cf = CertificateFactory.getInstance("X.509");
    X509Certificate cert = (X509Certificate)cf.generateCertificate(inStream);
}

A CertSelector that selects X509Certificates that
match all specified criteria. This class is particularly useful when
selecting certificates from a CertStore to build a
PKIX-compliant certification path.

When first constructed, an X509CertSelector has no criteria
enabled and each of the get methods return a default value
(null, or -1 for the getBasicConstraints method). Therefore, the match
method would return true for any X509Certificate.
Typically, several criteria are enabled (by calling
setIssuer or
setKeyUsage, for instance) and then the
X509CertSelector is passed to
CertStore.getCertificates or some similar
method.

Several criteria can be enabled (by calling setIssuer
and setSerialNumber,
for example) such that the match method
usually uniquely matches a single X509Certificate. We say
usually, since it is possible for two issuing CAs to have the same
distinguished name and each issue a certificate with the same serial
number. Other unique combinations include the issuer, subject,
subjectKeyIdentifier and/or the subjectPublicKey criteria.

Please refer to RFC 3280:
Internet X.509 Public Key Infrastructure Certificate and CRL Profile for
definitions of the X.509 certificate extensions mentioned below.

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.

 Abstract class for an X.509 Certificate Revocation List (CRL).
A CRL is a time-stamped list identifying revoked certificates.
It is signed by a Certificate Authority (CA) and made freely
available in a public repository.

Each revoked certificate is
identified in a CRL by its certificate serial number. When a
certificate-using system uses a certificate (e.g., for verifying a
remote user's digital signature), that system not only checks the
certificate signature and validity but also acquires a suitably-
recent CRL and checks that the certificate serial number is not on
that CRL.  The meaning of "suitably-recent" may vary with local
policy, but it usually means the most recently-issued CRL.  A CA
issues a new CRL on a regular periodic basis (e.g., hourly, daily, or
weekly).  Entries are added to CRLs as revocations occur, and an
entry may be removed when the certificate expiration date is reached.

The X.509 v2 CRL format is described below in ASN.1:


CertificateList  ::=  SEQUENCE  {
    tbsCertList          TBSCertList,
    signatureAlgorithm   AlgorithmIdentifier,
    signature            BIT STRING  }

More information can be found in
RFC 3280: Internet X.509
Public Key Infrastructure Certificate and CRL Profile.

The ASN.1 definition of tbsCertList is:


TBSCertList  ::=  SEQUENCE  {
    version                 Version OPTIONAL,
                            -- if present, must be v2
    signature               AlgorithmIdentifier,
    issuer                  Name,
    thisUpdate              ChoiceOfTime,
    nextUpdate              ChoiceOfTime OPTIONAL,
    revokedCertificates     SEQUENCE OF SEQUENCE  {
        userCertificate         CertificateSerialNumber,
        revocationDate          ChoiceOfTime,
        crlEntryExtensions      Extensions OPTIONAL
                                -- if present, must be v2
        }  OPTIONAL,
    crlExtensions           [0]  EXPLICIT Extensions OPTIONAL
                                 -- if present, must be v2
    }

CRLs are instantiated using a certificate factory. The following is an
example of how to instantiate an X.509 CRL:


try (InputStream inStream = new FileInputStream("fileName-of-crl")) {
    CertificateFactory cf = CertificateFactory.getInstance("X.509");
    X509CRL crl = (X509CRL)cf.generateCRL(inStream);
}

Abstract class for a revoked certificate in a CRL (Certificate
Revocation List).

The ASN.1 definition for revokedCertificates is:


revokedCertificates    SEQUENCE OF SEQUENCE  {
    userCertificate    CertificateSerialNumber,
    revocationDate     ChoiceOfTime,
    crlEntryExtensions Extensions OPTIONAL
                       -- if present, must be v2
}  OPTIONAL

CertificateSerialNumber  ::=  INTEGER

Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension

Extension  ::=  SEQUENCE  {
    extnId        OBJECT IDENTIFIER,
    critical      BOOLEAN DEFAULT FALSE,
    extnValue     OCTET STRING
                  -- contains a DER encoding of a value
                  -- of the type registered for use with
                  -- the extnId object identifier value
}

A CRLSelector that selects X509CRLs that
match all specified criteria. This class is particularly useful when
selecting CRLs from a CertStore to check revocation status
of a particular certificate.

When first constructed, an X509CRLSelector has no criteria
enabled and each of the get methods return a default
value (null). Therefore, the match method
would return true for any X509CRL. Typically,
several criteria are enabled (by calling setIssuers
or setDateAndTime, for instance) and then the
X509CRLSelector is passed to
CertStore.getCRLs or some similar
method.

Please refer to RFC 3280:
Internet X.509 Public Key Infrastructure Certificate and CRL Profile
for definitions of the X.509 CRL fields and extensions mentioned below.

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.

Interface for an X.509 extension.

The extensions defined for X.509 v3
Certificates and v2
CRLs (Certificate Revocation
Lists) provide methods
for associating additional attributes with users or public keys,
for managing the certification hierarchy, and for managing CRL
distribution. The X.509 extensions format also allows communities
to define private extensions to carry information unique to those
communities.

Each extension in a certificate/CRL may be designated as
critical or non-critical.  A certificate/CRL-using system (an application
validating a certificate/CRL) must reject the certificate/CRL if it
encounters a critical extension it does not recognize.  A non-critical
extension may be ignored if it is not recognized.

The ASN.1 definition for this is:


Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension

Extension  ::=  SEQUENCE  {
    extnId        OBJECT IDENTIFIER,
    critical      BOOLEAN DEFAULT FALSE,
    extnValue     OCTET STRING
                  -- contains a DER encoding of a value
                  -- of the type registered for use with
                  -- the extnId object identifier value
}
Since not all extensions are known, the getExtensionValue
method returns the DER-encoded OCTET STRING of the
extension value (i.e., the extnValue). This can then
be handled by a Class that understands the extension.