An AccessControlContext is used to make system resource access decisions
based on the context it encapsulates.

More specifically, it encapsulates a context and
has a single method, checkPermission,
that is equivalent to the checkPermission method
in the AccessController class, with one difference: The AccessControlContext
checkPermission method makes access decisions based on the
context it encapsulates,
rather than that of the current execution thread.

Thus, the purpose of AccessControlContext is for those situations where
a security check that should be made within a given context
actually needs to be done from within a
different context (for example, from within a worker thread).

 An AccessControlContext is created by calling the
AccessController.getContext method.
The getContext method takes a "snapshot"
of the current calling context, and places
it in an AccessControlContext object, which it returns. A sample call is
the following:



  AccessControlContext acc = AccessController.getContext()


Code within a different context can subsequently call the
checkPermission method on the
previously-saved AccessControlContext object. A sample call is the
following:



  acc.checkPermission(permission)

 This exception is thrown by the AccessController to indicate
that a requested access (to a critical system resource such as the
file system or the network) is denied.

 The reason to deny access can vary.  For example, the requested
permission might be of an incorrect type,  contain an invalid
value, or request access that is not allowed according to the
security policy.  Such information should be given whenever
possible at the time the exception is thrown.

if (caller i's domain does not have the permission)
    throw AccessControlException

else if (caller i is marked as privileged) {
    if (a context was specified in the call to doPrivileged)
        context.checkPermission(permission)
    if (limited permissions were specified in the call to doPrivileged) {
        for (each limited permission) {
            if (the limited permission implies the requested permission)
                return;
        }
    } else
        return;
}

 The AccessController class is used for access control operations
and decisions.

 More specifically, the AccessController class is used for
three purposes:


 to decide whether an access to a critical system
resource is to be allowed or denied, based on the security policy
currently in effect,
to mark code as being "privileged", thus affecting subsequent
access determinations, and
to obtain a "snapshot" of the current calling context so
access-control decisions from a different context can be made with
respect to the saved context.

 The checkPermission method
determines whether the access request indicated by a specified
permission should be granted or denied. A sample call appears
below. In this example, checkPermission will determine
whether or not to grant "read" access to the file named "testFile" in
the "/temp" directory.



FilePermission perm = new FilePermission("/temp/testFile", "read");
AccessController.checkPermission(perm);

 If a requested access is allowed,
checkPermission returns quietly. If denied, an
AccessControlException is
thrown. AccessControlException can also be thrown if the requested
permission is of an incorrect type or contains an invalid value.
Such information is given whenever possible.

Suppose the current thread traversed m callers, in the order of caller 1
to caller 2 to caller m. Then caller m invoked the
checkPermission method.
The checkPermission method determines whether access
is granted or denied based on the following algorithm:



for (int i = m; i > 0; i--) {

    if (caller i's domain does not have the permission)
        throw AccessControlException

    else if (caller i is marked as privileged) {
        if (a context was specified in the call to doPrivileged)
            context.checkPermission(permission)
        if (limited permissions were specified in the call to doPrivileged) {
            for (each limited permission) {
                if (the limited permission implies the requested permission)
                    return;
            }
        } else
            return;
    }
}

// Next, check the context inherited when the thread was created.
// Whenever a new thread is created, the AccessControlContext at
// that time is stored and associated with the new thread, as the
// "inherited" context.

inheritedContext.checkPermission(permission);

 A caller can be marked as being "privileged"
(see doPrivileged and below).
When making access control decisions, the checkPermission
method stops checking if it reaches a caller that
was marked as "privileged" via a doPrivileged
call without a context argument (see below for information about a
context argument). If that caller's domain has the
specified permission and at least one limiting permission argument (if any)
implies the requested permission, no further checking is done and
checkPermission
returns quietly, indicating that the requested access is allowed.
If that domain does not have the specified permission, an exception
is thrown, as usual. If the caller's domain had the specified permission
but it was not implied by any limiting permission arguments given in the call
to doPrivileged then the permission checking continues
until there are no more callers or another doPrivileged
call matches the requested permission and returns normally.

 The normal use of the "privileged" feature is as follows. If you
don't need to return a value from within the "privileged" block, do
the following:



somemethod() {
    ...normal code here...
    AccessController.doPrivileged(new PrivilegedAction<Void>() {
        public Void run() {
            // privileged code goes here, for example:
            System.loadLibrary("awt");
            return null; // nothing to return
        }
    });
    ...normal code here...
}


PrivilegedAction is an interface with a single method, named
run.
The above example shows creation of an implementation
of that interface; a concrete implementation of the
run method is supplied.
When the call to doPrivileged is made, an
instance of the PrivilegedAction implementation is passed
to it. The doPrivileged method calls the
run method from the PrivilegedAction
implementation after enabling privileges, and returns the
run method's return value as the
doPrivileged return value (which is
ignored in this example).

 If you need to return a value, you can do something like the following:



somemethod() {
    ...normal code here...
    String user = AccessController.doPrivileged(
        new PrivilegedAction<String>() {
        public String run() {
            return System.getProperty("user.name");
            }
        });
    ...normal code here...
}

If the action performed in your run method could
throw a "checked" exception (those listed in the throws clause
of a method), then you need to use the
PrivilegedExceptionAction interface instead of the
PrivilegedAction interface:



somemethod() throws FileNotFoundException {
    ...normal code here...
    try {
        FileInputStream fis = AccessController.doPrivileged(
        new PrivilegedExceptionAction<FileInputStream>() {
            public FileInputStream run() throws FileNotFoundException {
                return new FileInputStream("someFile");
            }
        });
    } catch (PrivilegedActionException e) {
        // e.getException() should be an instance of FileNotFoundException,
        // as only "checked" exceptions will be "wrapped" in a
        // PrivilegedActionException.
        throw (FileNotFoundException) e.getException();
    }
    ...normal code here...
 }

 Be *very* careful in your use of the "privileged" construct, and
always remember to make the privileged code section as small as possible.
You can pass Permission arguments to further limit the
scope of the "privilege" (see below).


 Note that checkPermission always performs security checks
within the context of the currently executing thread.
Sometimes a security check that should be made within a given context
will actually need to be done from within a
different context (for example, from within a worker thread).
The getContext method and
AccessControlContext class are provided
for this situation. The getContext method takes a "snapshot"
of the current calling context, and places
it in an AccessControlContext object, which it returns. A sample call is
the following:



AccessControlContext acc = AccessController.getContext()


AccessControlContext itself has a checkPermission method
that makes access decisions based on the context it encapsulates,
rather than that of the current execution thread.
Code within a different context can thus call that method on the
previously-saved AccessControlContext object. A sample call is the
following:



acc.checkPermission(permission)

 There are also times where you don't know a priori which permissions
to check the context against. In these cases you can use the
doPrivileged method that takes a context. You can also limit the scope
of the privileged code by passing additional Permission
parameters.



somemethod() {
    AccessController.doPrivileged(new PrivilegedAction<Object>() {
        public Object run() {
            // Code goes here. Any permission checks within this
            // run method will require that the intersection of the
            // caller's protection domain and the snapshot's
            // context have the desired permission. If a requested
            // permission is not implied by the limiting FilePermission
            // argument then checking of the thread continues beyond the
            // caller of doPrivileged.
        }
    }, acc, new FilePermission("/temp/*", read));
    ...normal code here...
}
 Passing a limiting Permission argument of an instance of
AllPermission is equivalent to calling the equivalent
doPrivileged method without limiting Permission
arguments. Passing a zero length array of Permission disables
the code privileges so that checking always continues beyond the caller of
that doPrivileged method.

Interface representing an Access Control List (ACL).  An Access
Control List is a data structure used to guard access to
resources.

An ACL can be thought of as a data structure with multiple ACL
entries.  Each ACL entry, of interface type AclEntry, contains a
set of permissions associated with a particular principal. (A
principal represents an entity such as an individual user or a
group). Additionally, each ACL entry is specified as being either
positive or negative. If positive, the permissions are to be
granted to the associated principal. If negative, the permissions
are to be denied.

The ACL Entries in each ACL observe the following rules:

 Each principal can have at most one positive ACL entry and
one negative entry; that is, multiple positive or negative ACL
entries are not allowed for any principal.  Each entry specifies
the set of permissions that are to be granted (if positive) or
denied (if negative).

If there is no entry for a particular principal, then the
principal is considered to have a null (empty) permission set.

If there is a positive entry that grants a principal a
particular permission, and a negative entry that denies the
principal the same permission, the result is as though the
permission was never granted or denied.

Individual permissions always override permissions of the
group(s) to which the individual belongs. That is, individual
negative permissions (specific denial of permissions) override the
groups' positive permissions. And individual positive permissions
override the groups' negative permissions.



The java.security.acl  package provides the
interfaces to the ACL and related data structures (ACL entries,
groups, permissions, etc.), and the sun.security.acl
classes provide a default implementation of the interfaces. For
example, java.security.acl.Acl  provides the
interface to an ACL and the sun.security.acl.AclImpl
class provides the default implementation of the interface.

The java.security.acl.Acl  interface extends the
java.security.acl.Owner  interface. The Owner
interface is used to maintain a list of owners for each ACL.  Only
owners are allowed to modify an ACL. For example, only an owner can
call the ACL's addEntry method to add a new ACL entry
to the ACL.

This is the interface used for representing one entry in an Access
Control List (ACL).

An ACL can be thought of as a data structure with multiple ACL entry
objects. Each ACL entry object contains a set of permissions associated
with a particular principal. (A principal represents an entity such as
an individual user or a group). Additionally, each ACL entry is specified
as being either positive or negative. If positive, the permissions are
to be granted to the associated principal. If negative, the permissions
are to be denied. Each principal can have at most one positive ACL entry
and one negative entry; that is, multiple positive or negative ACL
entries are not allowed for any principal.

Note: ACL entries are by default positive. An entry becomes a
negative entry only if the
setNegativePermissions
method is called on it.

This is an exception that is thrown whenever a reference is made to a
non-existent ACL (Access Control List).

This interface is used to represent a group of principals. (A principal
represents an entity such as an individual user or a company).

Note that Group extends Principal. Thus, either a Principal or a Group can
be passed as an argument to methods containing a Principal parameter. For
example, you can add either a Principal or a Group to a Group object by
calling the object's addMember method, passing it the
Principal or Group.

This is an exception that is thrown whenever an attempt is made to delete
the last owner of an Access Control List.

This is an exception that is thrown whenever the modification of an object
(such as an Access Control List) is only allowed to be done by an owner of
the object, but the Principal attempting the modification is not an owner.

Interface for managing owners of Access Control Lists (ACLs) or ACL
configurations. (Note that the Acl interface in the
java.security.acl package extends this Owner
interface.) The initial owner Principal should be specified as an
argument to the constructor of the class implementing this interface.

This interface represents a permission, such as that used to grant
a particular type of access to a resource.

This interface specifies constraints for cryptographic algorithms,
keys (key sizes), and other algorithm parameters.

AlgorithmConstraints objects are immutable.  An implementation
of this interface should not provide methods that can change the state
of an instance once it has been created.

Note that AlgorithmConstraints can be used to represent the
restrictions described by the security properties
jdk.certpath.disabledAlgorithms and
jdk.tls.disabledAlgorithms, or could be used by a
concrete PKIXCertPathChecker to check whether a specified
certificate in the certification path contains the required algorithm
constraints.

The AlgorithmParameterGenerator class is used to generate a
set of
parameters to be used with a certain algorithm. Parameter generators
are constructed using the getInstance factory methods
(static methods that return instances of a given class).

The object that will generate the parameters can be initialized
in two different ways: in an algorithm-independent manner, or in an
algorithm-specific manner:


The algorithm-independent approach uses the fact that all parameter
generators share the concept of a "size" and a
source of randomness. The measure of size is universally shared
by all algorithm parameters, though it is interpreted differently
for different algorithms. For example, in the case of parameters for
the DSA algorithm, "size" corresponds to the size
of the prime modulus (in bits).
When using this approach, algorithm-specific parameter generation
values - if any - default to some standard values, unless they can be
derived from the specified size.

The other approach initializes a parameter generator object
using algorithm-specific semantics, which are represented by a set of
algorithm-specific parameter generation values. To generate
Diffie-Hellman system parameters, for example, the parameter generation
values usually
consist of the size of the prime modulus and the size of the
random exponent, both specified in number of bits.


In case the client does not explicitly initialize the
AlgorithmParameterGenerator
(via a call to an init method), each provider must supply (and
document) a default initialization. For example, the Sun provider uses a
default modulus prime size of 1024 bits for the generation of DSA
parameters.

 Every implementation of the Java platform is required to support the
following standard AlgorithmParameterGenerator algorithms and
keysizes in parentheses:

DiffieHellman (1024)
DSA (1024)

These algorithms are described in the
AlgorithmParameterGenerator 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.

This class defines the Service Provider Interface (SPI)
for the AlgorithmParameterGenerator class, which
is used to generate a set of parameters to be used with a certain algorithm.

 All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a parameter generator for a particular algorithm.

 In case the client does not explicitly initialize the
AlgorithmParameterGenerator (via a call to an engineInit
method), each provider must supply (and document) a default initialization.
For example, the Sun provider uses a default modulus prime size of 1024
bits for the generation of DSA parameters.

This class is used as an opaque representation of cryptographic parameters.

An AlgorithmParameters object for managing the parameters
for a particular algorithm can be obtained by
calling one of the getInstance factory methods
(static methods that return instances of a given class).

Once an AlgorithmParameters object is obtained, it must be
initialized via a call to init, using an appropriate parameter
specification or parameter encoding.

A transparent parameter specification is obtained from an
AlgorithmParameters object via a call to
getParameterSpec, and a byte encoding of the parameters is
obtained via a call to getEncoded.

 Every implementation of the Java platform is required to support the
following standard AlgorithmParameters algorithms:

AES
DES
DESede
DiffieHellman
DSA

These algorithms are described in the
AlgorithmParameters 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.

This class defines the Service Provider Interface (SPI)
for the AlgorithmParameters class, which is used to manage
algorithm parameters.

 All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply parameter management
for a particular algorithm.

The AllPermission is a permission that implies all other permissions.

Note: Granting AllPermission should be done with extreme care,
as it implies all other permissions. Thus, it grants code the ability
to run with security
disabled.  Extreme caution should be taken before granting such
a permission to code.  This permission should be used only during testing,
or in extremely rare cases where an application or applet is
completely trusted and adding the necessary permissions to the policy
is prohibitively cumbersome.

This class defines login and logout methods for a provider.

 While callers may invoke login directly,
the provider may also invoke login on behalf of callers
if it determines that a login must be performed
prior to certain operations.

The BasicPermission class extends the Permission class, and
can be used as the base class for permissions that want to
follow the same naming convention as BasicPermission.

The name for a BasicPermission is the name of the given permission
(for example, "exit",
"setFactory", "print.queueJob", etc). The naming
convention follows the  hierarchical property naming convention.
An asterisk may appear by itself, or if immediately preceded by a "."
may appear at the end of the name, to signify a wildcard match.
For example, "*" and "java.*" signify a wildcard match, while "*java", "a*b",
and "java*" do not.

The action string (inherited from Permission) is unused.
Thus, BasicPermission is commonly used as the base class for
"named" permissions
(ones that contain a name but no actions list; you either have the
named permission or you don't.)
Subclasses may implement actions on top of BasicPermission,
if desired.

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.

Deprecated.
A new certificate handling package is created in the Java platform.
             This Certificate interface is entirely deprecated and
             is here to allow for a smooth transition to the new
             package.

This class encapsulates information about a code signer.
It is immutable.

This class extends the concept of a codebase to
encapsulate not only the location (URL) but also the certificate chains
that were used to verify signed code originating from that location.

This is the generic Message Digest exception.

A transparent stream that updates the associated message digest using
the bits going through the stream.

To complete the message digest computation, call one of the
digest methods on the associated message
digest after your calls to one of this digest input stream's
read methods.

It is possible to turn this stream on or off (see
on). When it is on, a call to one of the
read methods
results in an update on the message digest.  But when it is off,
the message digest is not updated. The default is for the stream
to be on.

Note that digest objects can compute only one digest (see
MessageDigest),
so that in order to compute intermediate digests, a caller should
retain a handle onto the digest object, and clone it for each
digest to be computed, leaving the orginal digest untouched.

A transparent stream that updates the associated message digest using
the bits going through the stream.

To complete the message digest computation, call one of the
digest methods on the associated message
digest after your calls to one of this digest output stream's
write methods.

It is possible to turn this stream on or off (see
on). When it is on, a call to one of the
write methods results in
an update on the message digest.  But when it is off, the message
digest is not updated. The default is for the stream to be on.

A DomainCombiner provides a means to dynamically
update the ProtectionDomains associated with the current
AccessControlContext.

 A DomainCombiner is passed as a parameter to the
appropriate constructor for AccessControlContext.
The newly constructed context is then passed to the
AccessController.doPrivileged(..., context) method
to bind the provided context (and associated DomainCombiner)
with the current execution Thread.  Subsequent calls to
AccessController.getContext or
AccessController.checkPermission
cause the DomainCombiner.combine to get invoked.

 The combine method takes two arguments.  The first argument represents
an array of ProtectionDomains from the current execution Thread,
since the most recent call to AccessController.doPrivileged.
If no call to doPrivileged was made, then the first argument will contain
all the ProtectionDomains from the current execution Thread.
The second argument represents an array of inherited ProtectionDomains,
which may be null.  ProtectionDomains may be inherited
from a parent Thread, or from a privileged context.  If no call to
doPrivileged was made, then the second argument will contain the
ProtectionDomains inherited from the parent Thread.  If one or more calls
to doPrivileged were made, and the most recent call was to
doPrivileged(action, context), then the second argument will contain the
ProtectionDomains from the privileged context.  If the most recent call
was to doPrivileged(action), then there is no privileged context,
and the second argument will be null.

 The combine method investigates the two input arrays
of ProtectionDomains and returns a single array containing the updated
ProtectionDomains.  In the simplest case, the combine
method merges the two stacks into one.  In more complex cases,
the combine method returns a modified
stack of ProtectionDomains.  The modification may have added new
ProtectionDomains, removed certain ProtectionDomains, or simply
updated existing ProtectionDomains.  Re-ordering and other optimizations
to the ProtectionDomains are also permitted.  Typically the
combine method bases its updates on the information
encapsulated in the DomainCombiner.

 After the AccessController.getContext method
receives the combined stack of ProtectionDomains back from
the DomainCombiner, it returns a new
AccessControlContext that has both the combined ProtectionDomains
as well as the DomainCombiner.

domain <domainName> [<property> ...] {
    keystore <keystoreName> [<property> ...] ;
    ...
};
...

keystore system-truststore
    keystoreURI="${java.home}/lib/security/cacerts";

keystore app1-keystore
    keystoreType="PKCS12"
    keystoreURI="file:///app1/etc/keystore.p12";

Configuration data that specifies the keystores in a keystore domain.
A keystore domain is a collection of keystores that are presented as a
single logical keystore. The configuration data is used during
KeyStore
load and
store operations.

The following syntax is supported for configuration data:


    domain <domainName> [<property> ...] {
        keystore <keystoreName> [<property> ...] ;
        ...
    };
    ...
where domainName and keystoreName are identifiers
and property is a key/value pairing. The key and value are
separated by an 'equals' symbol and the value is enclosed in double
quotes. A property value may be either a printable string or a binary
string of colon-separated pairs of hexadecimal digits. Multi-valued
properties are represented as a comma-separated list of values,
enclosed in square brackets.
See Arrays.toString(java.lang.Object[]).

To ensure that keystore entries are uniquely identified, each
entry's alias is prefixed by its keystoreName followed
by the entry name separator and each keystoreName must be
unique within its domain. Entry name prefixes are omitted when
storing a keystore.

Properties are context-sensitive: properties that apply to
all the keystores in a domain are located in the domain clause,
and properties that apply only to a specific keystore are located
in that keystore's clause.
Unless otherwise specified, a property in a keystore clause overrides
a property of the same name in the domain clause. All property names
are case-insensitive. The following properties are supported:

 keystoreType="<type>"
     The keystore type.
 keystoreURI="<url>"
     The keystore location.
 keystoreProviderName="<name>"
     The name of the keystore's JCE provider.
 keystorePasswordEnv="<environment-variable>"
     The environment variable that stores a keystore password.
         Alternatively, passwords may be supplied to the constructor
         method in a Map<String, ProtectionParameter>.
 entryNameSeparator="<separator>"
     The separator between a keystore name prefix and an entry name.
         When specified, it applies to all the entries in a domain.
         Its default value is a space.


For example, configuration data for a simple keystore domain
comprising three keystores is shown below:


domain app1 {
    keystore app1-truststore
        keystoreURI="file:///app1/etc/truststore.jks";

    keystore system-truststore
        keystoreURI="${java.home}/lib/security/cacerts";

    keystore app1-keystore
        keystoreType="PKCS12"
        keystoreURI="file:///app1/etc/keystore.p12";
};

The GeneralSecurityException class is a generic
security exception class that provides type safety for all the
security-related exception classes that extend from it.

 This interface represents a guard, which is an object that is used
to protect access to another object.

This interface contains a single method, checkGuard,
with a single object argument. checkGuard is
invoked (by the GuardedObject getObject method)
to determine whether or not to allow access to the object.

A GuardedObject is an object that is used to protect access to
another object.

A GuardedObject encapsulates a target object and a Guard object,
such that access to the target object is possible
only if the Guard object allows it.
Once an object is encapsulated by a GuardedObject,
access to that object is controlled by the getObject
method, which invokes the
checkGuard method on the Guard object that is
guarding access. If access is not allowed,
an exception is thrown.

Deprecated.
This class is no longer used. Its functionality has been
 replaced by java.security.KeyStore, the
 java.security.cert package, and
 java.security.Principal.

Deprecated.
This class is no longer used. Its functionality has been
 replaced by java.security.KeyStore, the
 java.security.cert package, and
 java.security.Principal.

The interface to a DSA public or private key. DSA (Digital Signature
Algorithm) is defined in NIST's FIPS-186.

An interface to an object capable of generating DSA key pairs.

The initialize methods may each be called any number
of times. If no initialize method is called on a
DSAKeyPairGenerator, the default is to generate 1024-bit keys, using
precomputed p, q and g parameters and an instance of SecureRandom as
the random bit source.

Users wishing to indicate DSA-specific parameters, and to generate a key
pair suitable for use with the DSA algorithm typically



Get a key pair generator for the DSA algorithm by calling the
KeyPairGenerator getInstance method with "DSA"
as its argument.

Initialize the generator by casting the result to a DSAKeyPairGenerator
and calling one of the
initialize methods from this DSAKeyPairGenerator interface.

Generate a key pair by calling the generateKeyPair
method from the KeyPairGenerator class.



Note: it is not always necessary to do do algorithm-specific
initialization for a DSA key pair generator. That is, it is not always
necessary to call an initialize method in this interface.
Algorithm-independent initialization using the initialize method
in the KeyPairGenerator
interface is all that is needed when you accept defaults for algorithm-specific
parameters.

Note: Some earlier implementations of this interface may not support
larger sizes of DSA parameters such as 2048 and 3072-bit.

Interface to a DSA-specific set of key parameters, which defines a
DSA key family. DSA (Digital Signature Algorithm) is defined
in NIST's FIPS-186.

The standard interface to a DSA private key. DSA (Digital Signature
Algorithm) is defined in NIST's FIPS-186.

The interface to a DSA public key. DSA (Digital Signature Algorithm)
is defined in NIST's FIPS-186.

The interface to an elliptic curve (EC) key.

The interface to an elliptic curve (EC) private key.

The interface to an elliptic curve (EC) public key.

The interface to an RSA public or private key.

The interface to an RSA multi-prime private key, as defined in the
PKCS#1 v2.1, using the Chinese Remainder Theorem
(CRT) information values.

The interface to an RSA private key, as defined in the PKCS#1 standard,
using the Chinese Remainder Theorem (CRT) information values.

The interface to an RSA private key.

The interface to an RSA public key.

This is the exception for invalid or inappropriate algorithm parameters.

This is the exception for invalid Keys (invalid encoding, wrong
length, uninitialized, etc).

This exception, designed for use by the JCA/JCE engine classes,
is thrown when an invalid parameter is passed
to a method.

The Key interface is the top-level interface for all keys. It
defines the functionality shared by all key objects. All keys
have three characteristics:



An Algorithm

This is the key algorithm for that key. The key algorithm is usually
an encryption or asymmetric operation algorithm (such as DSA or
RSA), which will work with those algorithms and with related
algorithms (such as MD5 with RSA, SHA-1 with RSA, Raw DSA, etc.)
The name of the algorithm of a key is obtained using the
getAlgorithm method.

An Encoded Form

This is an external encoded form for the key used when a standard
representation of the key is needed outside the Java Virtual Machine,
as when transmitting the key to some other party. The key
is encoded according to a standard format (such as
X.509 SubjectPublicKeyInfo or PKCS#8), and
is returned using the getEncoded method.
Note: The syntax of the ASN.1 type SubjectPublicKeyInfo
is defined as follows:



SubjectPublicKeyInfo ::= SEQUENCE {
  algorithm AlgorithmIdentifier,
  subjectPublicKey BIT STRING }

AlgorithmIdentifier ::= SEQUENCE {
  algorithm OBJECT IDENTIFIER,
  parameters ANY DEFINED BY algorithm OPTIONAL }

For more information, see
RFC 3280:
Internet X.509 Public Key Infrastructure Certificate and CRL Profile.

A Format

This is the name of the format of the encoded key. It is returned
by the getFormat method.



Keys are generally obtained through key generators, certificates,
or various Identity classes used to manage keys.
Keys may also be obtained from key specifications (transparent
representations of the underlying key material) through the use of a key
factory (see KeyFactory).

 A Key should use KeyRep as its serialized representation.
Note that a serialized Key may contain sensitive information
which should not be exposed in untrusted environments.  See the

Security Appendix
of the Serialization Specification for more information.

This is the basic key exception.

Key factories are used to convert keys (opaque
cryptographic keys of type Key) into key specifications
(transparent representations of the underlying key material), and vice
versa.

 Key factories are bi-directional. That is, they allow you to build an
opaque key object from a given key specification (key material), or to
retrieve the underlying key material of a key object in a suitable format.

 Multiple compatible key specifications may exist for the same key.
For example, a DSA public key may be specified using
DSAPublicKeySpec or
X509EncodedKeySpec. A key factory can be used to translate
between compatible key specifications.

 The following is an example of how to use a key factory in order to
instantiate a DSA public key from its encoding.
Assume Alice has received a digital signature from Bob.
Bob also sent her his public key (in encoded format) to verify
his signature. Alice then performs the following actions:



X509EncodedKeySpec bobPubKeySpec = new X509EncodedKeySpec(bobEncodedPubKey);
KeyFactory keyFactory = KeyFactory.getInstance("DSA");
PublicKey bobPubKey = keyFactory.generatePublic(bobPubKeySpec);
Signature sig = Signature.getInstance("DSA");
sig.initVerify(bobPubKey);
sig.update(data);
sig.verify(signature);

 Every implementation of the Java platform is required to support the
following standard KeyFactory algorithms:

DiffieHellman
DSA
RSA

These algorithms are described in the
KeyFactory 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.

This class defines the Service Provider Interface (SPI)
for the KeyFactory class.
All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a key factory for a particular algorithm.

 Key factories are used to convert keys (opaque
cryptographic keys of type Key) into key specifications
(transparent representations of the underlying key material), and vice
versa.

 Key factories are bi-directional. That is, they allow you to build an
opaque key object from a given key specification (key material), or to
retrieve the underlying key material of a key object in a suitable format.

 Multiple compatible key specifications may exist for the same key.
For example, a DSA public key may be specified using
DSAPublicKeySpec or
X509EncodedKeySpec. A key factory can be used to translate
between compatible key specifications.

 A provider should document all the key specifications supported by its
key factory.

This is the general key management exception for all operations
dealing with key management. Examples of subclasses of
KeyManagementException that developers might create for
giving more detailed information could include:


KeyIDConflictException
KeyAuthorizationFailureException
ExpiredKeyException

This class is a simple holder for a key pair (a public key and a
private key). It does not enforce any security, and, when initialized,
should be treated like a PrivateKey.

The KeyPairGenerator class is used to generate pairs of
public and private keys. Key pair generators are constructed using the
getInstance factory methods (static methods that
return instances of a given class).

A Key pair generator for a particular algorithm creates a public/private
key pair that can be used with this algorithm. It also associates
algorithm-specific parameters with each of the generated keys.

There are two ways to generate a key pair: in an algorithm-independent
manner, and in an algorithm-specific manner.
The only difference between the two is the initialization of the object:


Algorithm-Independent Initialization
All key pair generators share the concepts of a keysize and a
source of randomness. The keysize is interpreted differently for different
algorithms (e.g., in the case of the DSA algorithm, the keysize
corresponds to the length of the modulus).
There is an
initialize
method in this KeyPairGenerator class that takes these two universally
shared types of arguments. There is also one that takes just a
keysize argument, and uses the SecureRandom
implementation of the highest-priority installed provider as the source
of randomness. (If none of the installed providers supply an implementation
of SecureRandom, a system-provided source of randomness is
used.)

Since no other parameters are specified when you call the above
algorithm-independent initialize methods, it is up to the
provider what to do about the algorithm-specific parameters (if any) to be
associated with each of the keys.

If the algorithm is the DSA algorithm, and the keysize (modulus
size) is 512, 768, or 1024, then the Sun provider uses a set of
precomputed values for the p, q, and
g parameters. If the modulus size is not one of the above
values, the Sun provider creates a new set of parameters. Other
providers might have precomputed parameter sets for more than just the
three modulus sizes mentioned above. Still others might not have a list of
precomputed parameters at all and instead always create new parameter sets.

Algorithm-Specific Initialization
For situations where a set of algorithm-specific parameters already
exists (e.g., so-called community parameters in DSA), there are two
initialize methods that have an AlgorithmParameterSpec
argument. One also has a SecureRandom argument, while the
the other uses the SecureRandom
implementation of the highest-priority installed provider as the source
of randomness. (If none of the installed providers supply an implementation
of SecureRandom, a system-provided source of randomness is
used.)


In case the client does not explicitly initialize the KeyPairGenerator
(via a call to an initialize method), each provider must
supply (and document) a default initialization.
For example, the Sun provider uses a default modulus size (keysize)
of 1024 bits.

Note that this class is abstract and extends from
KeyPairGeneratorSpi for historical reasons.
Application developers should only take notice of the methods defined in
this KeyPairGenerator class; all the methods in
the superclass are intended for cryptographic service providers who wish to
supply their own implementations of key pair generators.

 Every implementation of the Java platform is required to support the
following standard KeyPairGenerator algorithms and keysizes in
parentheses:

DiffieHellman (1024)
DSA (1024)
RSA (1024, 2048)

These algorithms are described in the
KeyPairGenerator 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.

 This class defines the Service Provider Interface (SPI)
for the KeyPairGenerator class, which is used to generate
pairs of public and private keys.

 All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a key pair generator for a particular algorithm.

 In case the client does not explicitly initialize the KeyPairGenerator
(via a call to an initialize method), each provider must
supply (and document) a default initialization.
For example, the Sun provider uses a default modulus size (keysize)
of 1024 bits.

Standardized representation for serialized Key objects.



Note that a serialized Key may contain sensitive information
which should not be exposed in untrusted environments.  See the

Security Appendix
of the Serialization Specification for more information.

 KeyStore ks = KeyStore.getInstance("JKS");

This class represents a storage facility for cryptographic
keys and certificates.

 A KeyStore manages different types of entries.
Each type of entry implements the KeyStore.Entry interface.
Three basic KeyStore.Entry implementations are provided:


KeyStore.PrivateKeyEntry
 This type of entry holds a cryptographic PrivateKey,
which is optionally stored in a protected format to prevent
unauthorized access.  It is also accompanied by a certificate chain
for the corresponding public key.

 Private keys and certificate chains are used by a given entity for
self-authentication. Applications for this authentication include software
distribution organizations which sign JAR files as part of releasing
and/or licensing software.

KeyStore.SecretKeyEntry
 This type of entry holds a cryptographic SecretKey,
which is optionally stored in a protected format to prevent
unauthorized access.

KeyStore.TrustedCertificateEntry
 This type of entry contains a single public key Certificate
belonging to another party. It is called a trusted certificate
because the keystore owner trusts that the public key in the certificate
indeed belongs to the identity identified by the subject (owner)
of the certificate.

This type of entry can be used to authenticate other parties.


 Each entry in a keystore is identified by an "alias" string. In the
case of private keys and their associated certificate chains, these strings
distinguish among the different ways in which the entity may authenticate
itself. For example, the entity may authenticate itself using different
certificate authorities, or using different public key algorithms.

 Whether aliases are case sensitive is implementation dependent. In order
to avoid problems, it is recommended not to use aliases in a KeyStore that
only differ in case.

 Whether keystores are persistent, and the mechanisms used by the
keystore if it is persistent, are not specified here. This allows
use of a variety of techniques for protecting sensitive (e.g., private or
secret) keys. Smart cards or other integrated cryptographic engines
(SafeKeyper) are one option, and simpler mechanisms such as files may also
be used (in a variety of formats).

 Typical ways to request a KeyStore object include
relying on the default type and providing a specific keystore type.


To rely on the default type:


   KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
The system will return a keystore implementation for the default type.

To provide a specific keystore type:


     KeyStore ks = KeyStore.getInstance("JKS");
The system will return the most preferred implementation of the
specified keystore type available in the environment.


 Before a keystore can be accessed, it must be
loaded.


   KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());

   // get user password and file input stream
   char[] password = getPassword();

   try (FileInputStream fis = new FileInputStream("keyStoreName")) {
       ks.load(fis, password);
   }

To create an empty keystore using the above load method,
pass null as the InputStream argument.

 Once the keystore has been loaded, it is possible
to read existing entries from the keystore, or to write new entries
into the keystore:


   KeyStore.ProtectionParameter protParam =
       new KeyStore.PasswordProtection(password);

   // get my private key
   KeyStore.PrivateKeyEntry pkEntry = (KeyStore.PrivateKeyEntry)
       ks.getEntry("privateKeyAlias", protParam);
   PrivateKey myPrivateKey = pkEntry.getPrivateKey();

   // save my secret key
   javax.crypto.SecretKey mySecretKey;
   KeyStore.SecretKeyEntry skEntry =
       new KeyStore.SecretKeyEntry(mySecretKey);
   ks.setEntry("secretKeyAlias", skEntry, protParam);

   // store away the keystore
   try (FileOutputStream fos = new FileOutputStream("newKeyStoreName")) {
       ks.store(fos, password);
   }

Note that although the same password may be used to
load the keystore, to protect the private key entry,
to protect the secret key entry, and to store the keystore
(as is shown in the sample code above),
different passwords or other protection parameters
may also be used.

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

PKCS12

This type is described in the
KeyStore 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.

A description of a to-be-instantiated KeyStore object.

An instance of this class encapsulates the information needed to
instantiate and initialize a KeyStore object. That process is
triggered when the getKeyStore() method is called.

This makes it possible to decouple configuration from KeyStore
object creation and e.g. delay a password prompt until it is
needed.

A ProtectionParameter encapsulating a CallbackHandler.

A marker interface for KeyStore entry types.

An attribute associated with a keystore entry.
It comprises a name and one or more values.

A marker interface for KeyStore
load
and
store
parameters.

A password-based implementation of ProtectionParameter.

A KeyStore entry that holds a PrivateKey
and corresponding certificate chain.

A marker interface for keystore protection parameters.

 The information stored in a ProtectionParameter
object protects the contents of a keystore.
For example, protection parameters may be used to check
the integrity of keystore data, or to protect the
confidentiality of sensitive keystore data
(such as a PrivateKey).

A KeyStore entry that holds a SecretKey.

A KeyStore entry that holds a trusted
Certificate.

This is the generic KeyStore exception.

This class defines the Service Provider Interface (SPI)
for the KeyStore class.
All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a keystore for a particular keystore type.

This MessageDigest class provides applications the functionality of a
message digest algorithm, such as SHA-1 or SHA-256.
Message digests are secure one-way hash functions that take arbitrary-sized
data and output a fixed-length hash value.

A MessageDigest object starts out initialized. The data is
processed through it using the update
methods. At any point reset can be called
to reset the digest. Once all the data to be updated has been
updated, one of the digest methods should
be called to complete the hash computation.

The digest method can be called once for a given number
of updates. After digest has been called, the MessageDigest
object is reset to its initialized state.

Implementations are free to implement the Cloneable interface.
Client applications can test cloneability by attempting cloning
and catching the CloneNotSupportedException:



MessageDigest md = MessageDigest.getInstance("SHA-256");

try {
    md.update(toChapter1);
    MessageDigest tc1 = md.clone();
    byte[] toChapter1Digest = tc1.digest();
    md.update(toChapter2);
    ...etc.
} catch (CloneNotSupportedException cnse) {
    throw new DigestException("couldn't make digest of partial content");
}

Note that if a given implementation is not cloneable, it is
still possible to compute intermediate digests by instantiating
several instances, if the number of digests is known in advance.

Note that this class is abstract and extends from
MessageDigestSpi for historical reasons.
Application developers should only take notice of the methods defined in
this MessageDigest class; all the methods in
the superclass are intended for cryptographic service providers who wish to
supply their own implementations of message digest algorithms.

 Every implementation of the Java platform is required to support
the following standard MessageDigest algorithms:

MD5
SHA-1
SHA-256

These algorithms are described in the
MessageDigest 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.

This class defines the Service Provider Interface (SPI)
for the MessageDigest class, which provides the functionality
of a message digest algorithm, such as MD5 or SHA. Message digests are
secure one-way hash functions that take arbitrary-sized data and output a
fixed-length hash value.

 All the abstract methods in this class must be implemented by a
cryptographic service provider who wishes to supply the implementation
of a particular message digest algorithm.

 Implementations are free to implement the Cloneable interface.

This exception is thrown when a particular cryptographic algorithm is
requested but is not available in the environment.

This exception is thrown when a particular security provider is
requested but is not available in the environment.

Abstract class for representing access to a system resource.
All permissions have a name (whose interpretation depends on the subclass),
as well as abstract functions for defining the semantics of the
particular Permission subclass.

Most Permission objects also include an "actions" list that tells the actions
that are permitted for the object.  For example,
for a java.io.FilePermission object, the permission name is
the pathname of a file (or directory), and the actions list
(such as "read, write") specifies which actions are granted for the
specified file (or for files in the specified directory).
The actions list is optional for Permission objects, such as
java.lang.RuntimePermission,
that don't need such a list; you either have the named permission (such
as "system.exit") or you don't.

An important method that must be implemented by each subclass is
the implies method to compare Permissions. Basically,
"permission p1 implies permission p2" means that
if one is granted permission p1, one is naturally granted permission p2.
Thus, this is not an equality test, but rather more of a
subset test.

 Permission objects are similar to String objects in that they
are immutable once they have been created. Subclasses should not
provide methods that can change the state of a permission
once it has been created.

Abstract class representing a collection of Permission objects.

With a PermissionCollection, you can:

 add a permission to the collection using the add method.
 check to see if a particular permission is implied in the
     collection, using the implies method.
 enumerate all the permissions, using the elements method.


When it is desirable to group together a number of Permission objects
of the same type, the newPermissionCollection method on that
particular type of Permission object should first be called. The default
behavior (from the Permission class) is to simply return null.
Subclasses of class Permission override the method if they need to store
their permissions in a particular PermissionCollection object in order
to provide the correct semantics when the
PermissionCollection.implies method is called.
If a non-null value is returned, that PermissionCollection must be used.
If null is returned, then the caller of newPermissionCollection
is free to store permissions of the
given type in any PermissionCollection they choose
(one that uses a Hashtable, one that uses a Vector, etc).

The PermissionCollection returned by the
Permission.newPermissionCollection
method is a homogeneous collection, which stores only Permission objects
for a given Permission type.  A PermissionCollection may also be
heterogeneous.  For example, Permissions is a PermissionCollection
subclass that represents a collection of PermissionCollections.
That is, its members are each a homogeneous PermissionCollection.
For example, a Permissions object might have a FilePermissionCollection
for all the FilePermission objects, a SocketPermissionCollection for all the
SocketPermission objects, and so on. Its add method adds a
permission to the appropriate collection.

Whenever a permission is added to a heterogeneous PermissionCollection
such as Permissions, and the PermissionCollection doesn't yet contain a
PermissionCollection of the specified permission's type, the
PermissionCollection should call
the newPermissionCollection method on the permission's class
to see if it requires a special PermissionCollection. If
newPermissionCollection
returns null, the PermissionCollection
is free to store the permission in any type of PermissionCollection it
desires (one using a Hashtable, one using a Vector, etc.). For example,
the Permissions object uses a default PermissionCollection implementation
that stores the permission objects in a Hashtable.

 Subclass implementations of PermissionCollection should assume
that they may be called simultaneously from multiple threads,
and therefore should be synchronized properly.  Furthermore,
Enumerations returned via the elements method are
not fail-fast.  Modifications to a collection should not be
performed while enumerating over that collection.

This class represents a heterogeneous collection of Permissions. That is,
it contains different types of Permission objects, organized into
PermissionCollections. For example, if any
java.io.FilePermission objects are added to an instance of
this class, they are all stored in a single
PermissionCollection. It is the PermissionCollection returned by a call to
the newPermissionCollection method in the FilePermission class.
Similarly, any java.lang.RuntimePermission objects are
stored in the PermissionCollection returned by a call to the
newPermissionCollection method in the
RuntimePermission class. Thus, this class represents a collection of
PermissionCollections.

When the add method is called to add a Permission, the
Permission is stored in the appropriate PermissionCollection. If no such
collection exists yet, the Permission object's class is determined and the
newPermissionCollection method is called on that class to create
the PermissionCollection and add it to the Permissions object. If
newPermissionCollection returns null, then a default
PermissionCollection that uses a hashtable will be created and used. Each
hashtable entry stores a Permission object as both the key and the value.

 Enumerations returned via the elements method are
not fail-fast.  Modifications to a collection should not be
performed while enumerating over that collection.

An attribute associated with a PKCS12 keystore entry.
The attribute name is an ASN.1 Object Identifier and the attribute
value is a set of ASN.1 types.

A Policy object is responsible for determining whether code executing
in the Java runtime environment has permission to perform a
security-sensitive operation.

 There is only one Policy object installed in the runtime at any
given time.  A Policy object can be installed by calling the
setPolicy method.  The installed Policy object can be
obtained by calling the getPolicy method.

 If no Policy object has been installed in the runtime, a call to
getPolicy installs an instance of the default Policy
implementation (a default subclass implementation of this abstract class).
The default Policy implementation can be changed by setting the value
of the policy.provider security property to the fully qualified
name of the desired Policy subclass implementation.

 Application code can directly subclass Policy to provide a custom
implementation.  In addition, an instance of a Policy object can be
constructed by invoking one of the getInstance factory methods
with a standard type.  The default policy type is "JavaPolicy".

 Once a Policy instance has been installed (either by default, or by
calling setPolicy), the Java runtime invokes its
implies method when it needs to
determine whether executing code (encapsulated in a ProtectionDomain)
can perform SecurityManager-protected operations.  How a Policy object
retrieves its policy data is up to the Policy implementation itself.
The policy data may be stored, for example, in a flat ASCII file,
in a serialized binary file of the Policy class, or in a database.

 The refresh method causes the policy object to
refresh/reload its data.  This operation is implementation-dependent.
For example, if the policy object stores its data in configuration files,
calling refresh will cause it to re-read the configuration
policy files.  If a refresh operation is not supported, this method does
nothing.  Note that refreshed policy may not have an effect on classes
in a particular ProtectionDomain. This is dependent on the Policy
provider's implementation of the implies
method and its PermissionCollection caching strategy.

This represents a marker interface for Policy parameters.

This class defines the Service Provider Interface (SPI)
for the Policy class.
All the abstract methods in this class must be implemented by each
service provider who wishes to supply a Policy implementation.

 Subclass implementations of this abstract class must provide
a public constructor that takes a Policy.Parameters
object as an input parameter.  This constructor also must throw
an IllegalArgumentException if it does not understand the
Policy.Parameters input.

This interface represents the abstract notion of a principal, which
can be used to represent any entity, such as an individual, a
corporation, and a login id.

A private key.
The purpose of this interface is to group (and provide type safety
for) all private key interfaces.

Note: The specialized private key interfaces extend this interface.
See, for example, the DSAPrivateKey interface in
java.security.interfaces.

Implementations should override the default destroy and
isDestroyed methods from the
Destroyable interface to enable
sensitive key information to be destroyed, cleared, or in the case
where such information is immutable, unreferenced.
Finally, since PrivateKey is Serializable, implementations
should also override
ObjectOutputStream.writeObject(java.lang.Object)
to prevent keys that have been destroyed from being serialized.

A computation to be performed with privileges enabled.  The computation is
performed by invoking AccessController.doPrivileged on the
PrivilegedAction object.  This interface is used only for
computations that do not throw checked exceptions; computations that
throw checked exceptions must use PrivilegedExceptionAction
instead.

This exception is thrown by
doPrivileged(PrivilegedExceptionAction) and
doPrivileged(PrivilegedExceptionAction,
AccessControlContext context) to indicate
that the action being performed threw a checked exception.  The exception
thrown by the action can be obtained by calling the
getException method.  In effect, an
PrivilegedActionException is a "wrapper"
for an exception thrown by a privileged action.

As of release 1.4, this exception has been retrofitted to conform to
the general purpose exception-chaining mechanism.  The "exception thrown
by the privileged computation" that is provided at construction time and
accessed via the getException() method is now known as the
cause, and may be accessed via the Throwable.getCause()
method, as well as the aforementioned "legacy method."

A computation to be performed with privileges enabled, that throws one or
more checked exceptions.  The computation is performed by invoking
AccessController.doPrivileged on the
PrivilegedExceptionAction object.  This interface is
used only for computations that throw checked exceptions;
computations that do not throw
checked exceptions should use PrivilegedAction instead.

The ProtectionDomain class encapsulates the characteristics of a domain,
which encloses a set of classes whose instances are granted a set
of permissions when being executed on behalf of a given set of Principals.

A static set of permissions can be bound to a ProtectionDomain when it is
constructed; such permissions are granted to the domain regardless of the
Policy in force. However, to support dynamic security policies, a
ProtectionDomain can also be constructed such that it is dynamically
mapped to a set of permissions by the current Policy whenever a permission
is checked.

This class represents a "provider" for the
Java Security API, where a provider implements some or all parts of
Java Security. Services that a provider may implement include:



Algorithms (such as DSA, RSA, MD5 or SHA-1).

Key generation, conversion, and management facilities (such as for
algorithm-specific keys).



Each provider has a name and a version number, and is configured
in each runtime it is installed in.

See The Provider Class
in the "Java Cryptography Architecture API Specification & Reference"
for information about how a particular type of provider, the
cryptographic service provider, works and is installed. However,
please note that a provider can be used to implement any security
service in Java that uses a pluggable architecture with a choice
of implementations that fit underneath.

Some provider implementations may encounter unrecoverable internal
errors during their operation, for example a failure to communicate with a
security token. A ProviderException should be used to indicate
such errors.

The service type Provider is reserved for use by the
security framework. Services of this type cannot be added, removed,
or modified by applications.
The following attributes are automatically placed in each Provider object:

Attributes Automatically Placed in a Provider Object
NameValue
Provider.id name
   String.valueOf(provider.getName())
Provider.id version
    String.valueOf(provider.getVersion())
Provider.id info
      String.valueOf(provider.getInfo())
Provider.id className
    provider.getClass().getName()

The description of a security service. It encapsulates the properties
of a service and contains a factory method to obtain new implementation
instances of this service.

Each service has a provider that offers the service, a type,
an algorithm name, and the name of the class that implements the
service. Optionally, it also includes a list of alternate algorithm
names for this service (aliases) and attributes, which are a map of
(name, value) String pairs.

This class defines the methods supportsParameter() and newInstance()
which are used by the Java security framework when it searches for
suitable services and instantiates them. The valid arguments to those
methods depend on the type of service. For the service types defined
within Java SE, see the

Java Cryptography Architecture API Specification & Reference
for the valid values.
Note that components outside of Java SE can define additional types of
services and their behavior.

Instances of this class are immutable.

A runtime exception for Provider exceptions (such as
misconfiguration errors or unrecoverable internal errors),
which may be subclassed by Providers to
throw specialized, provider-specific runtime errors.

A public key. This interface contains no methods or constants.
It merely serves to group (and provide type safety for) all public key
interfaces.

Note: The specialized public key interfaces extend this interface.
See, for example, the DSAPublicKey interface in
java.security.interfaces.

This class extends ClassLoader with additional support for defining
classes with an associated code source and permissions which are
retrieved by the system policy by default.

 SecureRandom random = new SecureRandom();

 SecureRandom random = new SecureRandom();
 byte bytes[] = new byte[20];
 random.nextBytes(bytes);

 byte seed[] = random.generateSeed(20);

This class provides a cryptographically strong random number
generator (RNG).

A cryptographically strong random number
minimally complies with the statistical random number generator tests
specified in
FIPS 140-2, Security Requirements for Cryptographic Modules,
section 4.9.1.
Additionally, SecureRandom must produce non-deterministic output.
Therefore any seed material passed to a SecureRandom object must be
unpredictable, and all SecureRandom output sequences must be
cryptographically strong, as described in

RFC 1750: Randomness Recommendations for Security.

A caller obtains a SecureRandom instance via the
no-argument constructor or one of the getInstance methods:



     SecureRandom random = new SecureRandom();

 Many SecureRandom implementations are in the form of a pseudo-random
number generator (PRNG), which means they use a deterministic algorithm
to produce a pseudo-random sequence from a true random seed.
Other implementations may produce true random numbers,
and yet others may use a combination of both techniques.

 Typical callers of SecureRandom invoke the following methods
to retrieve random bytes:



     SecureRandom random = new SecureRandom();
     byte bytes[] = new byte[20];
     random.nextBytes(bytes);

 Callers may also invoke the generateSeed method
to generate a given number of seed bytes (to seed other random number
generators, for example):


     byte seed[] = random.generateSeed(20);

Note: Depending on the implementation, the generateSeed and
nextBytes methods may block as entropy is being gathered,
for example, if they need to read from /dev/random on various Unix-like
operating systems.

This class defines the Service Provider Interface (SPI)
for the SecureRandom class.
All the abstract methods in this class must be implemented by each
service provider who wishes to supply the implementation
of a cryptographically strong pseudo-random number generator.

This class centralizes all security properties and common security
methods. One of its primary uses is to manage providers.

The default values of security properties are read from an
implementation-specific location, which is typically the properties file
lib/security/java.security in the Java installation directory.

This class is for security permissions.
A SecurityPermission contains a name (also referred to as a "target name")
but no actions list; you either have the named permission
or you don't.

The target name is the name of a security configuration parameter (see below).
Currently the SecurityPermission object is used to guard access
to the Policy, Security, Provider, Signer, and Identity
objects.

The following table lists all the possible SecurityPermission target names,
and for each provides a description of what the permission allows
and a discussion of the risks of granting code the permission.



Permission Target Name
What the Permission Allows
Risks of Allowing this Permission



  createAccessControlContext
  Creation of an AccessControlContext
  This allows someone to instantiate an AccessControlContext
with a DomainCombiner.  Extreme care must be taken when
granting this permission. Malicious code could create a DomainCombiner
that augments the set of permissions granted to code, and even grant the
code AllPermission.



  getDomainCombiner
  Retrieval of an AccessControlContext's DomainCombiner
  This allows someone to retrieve an AccessControlContext's
DomainCombiner.  Since DomainCombiners may contain
sensitive information, this could potentially lead to a privacy leak.



  getPolicy
  Retrieval of the system-wide security policy (specifically, of the
currently-installed Policy object)
  This allows someone to query the policy via the
getPermissions call,
which discloses which permissions would be granted to a given CodeSource.
While revealing the policy does not compromise the security of
the system, it does provide malicious code with additional information
which it may use to better aim an attack. It is wise
not to divulge more information than necessary.



  setPolicy
  Setting of the system-wide security policy (specifically,
the Policy object)
  Granting this permission is extremely dangerous, as malicious
code may grant itself all the necessary permissions it needs
to successfully mount an attack on the system.



  createPolicy.{policy type}
  Getting an instance of a Policy implementation from a provider
  Granting this permission enables code to obtain a Policy object.
Malicious code may query the Policy object to determine what permissions
have been granted to code other than itself.



  getProperty.{key}
  Retrieval of the security property with the specified key
  Depending on the particular key for which access has
been granted, the code may have access to the list of security
providers, as well as the location of the system-wide and user
security policies.  while revealing this information does not
compromise the security of the system, it does provide malicious
code with additional information which it may use to better aim
an attack.




  setProperty.{key}
  Setting of the security property with the specified key
  This could include setting a security provider or defining
the location of the system-wide security policy.  Malicious
code that has permission to set a new security provider may
set a rogue provider that steals confidential information such
as cryptographic private keys. In addition, malicious code with
permission to set the location of the system-wide security policy
may point it to a security policy that grants the attacker
all the necessary permissions it requires to successfully mount
an attack on the system.




  insertProvider
  Addition of a new provider
  This would allow somebody to introduce a possibly
malicious provider (e.g., one that discloses the private keys passed
to it) as the highest-priority provider. This would be possible
because the Security object (which manages the installed providers)
currently does not check the integrity or authenticity of a provider
before attaching it. The "insertProvider" permission subsumes the
"insertProvider.{provider name}" permission (see the section below for
more information).




  removeProvider.{provider name}
  Removal of the specified provider
  This may change the behavior or disable execution of other
parts of the program. If a provider subsequently requested by the
program has been removed, execution may fail. Also, if the removed
provider is not explicitly requested by the rest of the program, but
it would normally be the provider chosen when a cryptography service
is requested (due to its previous order in the list of providers),
a different provider will be chosen instead, or no suitable provider
will be found, thereby resulting in program failure.



  clearProviderProperties.{provider name}
  "Clearing" of a Provider so that it no longer contains the properties
used to look up services implemented by the provider
  This disables the lookup of services implemented by the provider.
This may thus change the behavior or disable execution of other
parts of the program that would normally utilize the Provider, as
described under the "removeProvider.{provider name}" permission.



  putProviderProperty.{provider name}
  Setting of properties for the specified Provider
  The provider properties each specify the name and location
of a particular service implemented by the provider. By granting
this permission, you let code replace the service specification
with another one, thereby specifying a different implementation.



  removeProviderProperty.{provider name}
  Removal of properties from the specified Provider
  This disables the lookup of services implemented by the
provider. They are no longer accessible due to removal of the properties
specifying their names and locations. This
may change the behavior or disable execution of other
parts of the program that would normally utilize the Provider, as
described under the "removeProvider.{provider name}" permission.





The following permissions have been superseded by newer permissions or are
associated with classes that have been deprecated: Identity,
IdentityScope, Signer. Use of them is discouraged. See the
applicable classes for more information.



Permission Target Name
What the Permission Allows
Risks of Allowing this Permission



  insertProvider.{provider name}
  Addition of a new provider, with the specified name
  Use of this permission is discouraged from further use because it is
possible to circumvent the name restrictions by overriding the
Provider.getName() method. Also, there is an equivalent
level of risk associated with granting code permission to insert a provider
with a specific name, or any name it chooses. Users should use the
"insertProvider" permission instead.
This would allow somebody to introduce a possibly
malicious provider (e.g., one that discloses the private keys passed
to it) as the highest-priority provider. This would be possible
because the Security object (which manages the installed providers)
currently does not check the integrity or authenticity of a provider
before attaching it.



  setSystemScope
  Setting of the system identity scope
  This would allow an attacker to configure the system identity scope with
certificates that should not be trusted, thereby granting applet or
application code signed with those certificates privileges that
would have been denied by the system's original identity scope.



  setIdentityPublicKey
  Setting of the public key for an Identity
  If the identity is marked as "trusted", this allows an attacker to
introduce a different public key (e.g., its own) that is not trusted
by the system's identity scope, thereby granting applet or
application code signed with that public key privileges that
would have been denied otherwise.



  setIdentityInfo
  Setting of a general information string for an Identity
  This allows attackers to set the general description for
an identity.  This may trick applications into using a different
identity than intended or may prevent applications from finding a
particular identity.



  addIdentityCertificate
  Addition of a certificate for an Identity
  This allows attackers to set a certificate for
an identity's public key.  This is dangerous because it affects
the trust relationship across the system. This public key suddenly
becomes trusted to a wider audience than it otherwise would be.



  removeIdentityCertificate
  Removal of a certificate for an Identity
  This allows attackers to remove a certificate for
an identity's public key. This is dangerous because it affects
the trust relationship across the system. This public key suddenly
becomes considered less trustworthy than it otherwise would be.



 printIdentity
 Viewing the name of a principal
and optionally the scope in which it is used, and whether
or not it is considered "trusted" in that scope
 The scope that is printed out may be a filename, in which case
it may convey local system information. For example, here's a sample
printout of an identity named "carol", who is
marked not trusted in the user's identity database:
  carol[/home/luehe/identitydb.obj][not trusted]



  getSignerPrivateKey
  Retrieval of a Signer's private key
  It is very dangerous to allow access to a private key; private
keys are supposed to be kept secret. Otherwise, code can use the
private key to sign various files and claim the signature came from
the Signer.



  setSignerKeyPair
  Setting of the key pair (public key and private key) for a Signer
  This would allow an attacker to replace somebody else's (the "target's")
keypair with a possibly weaker keypair (e.g., a keypair of a smaller
keysize).  This also would allow the attacker to listen in on encrypted
communication between the target and its peers. The target's peers
might wrap an encryption session key under the target's "new" public
key, which would allow the attacker (who possesses the corresponding
private key) to unwrap the session key and decipher the communication
data encrypted under that session key.

a public key, which initializes the signature for
verification (see initVerify), or

a private key (and optionally a Secure Random Number Generator),
which initializes the signature for signing
(see initSign(PrivateKey)
and initSign(PrivateKey, SecureRandom)).

The Signature class is used to provide applications the functionality
of a digital signature algorithm. Digital signatures are used for
authentication and integrity assurance of digital data.

 The signature algorithm can be, among others, the NIST standard
DSA, using DSA and SHA-256. The DSA algorithm using the
SHA-256 message digest algorithm can be specified as SHA256withDSA.
In the case of RSA the signing algorithm could be specified as, for example,
SHA256withRSA.
The algorithm name must be specified, as there is no default.

 A Signature object can be used to generate and verify digital
signatures.

 There are three phases to the use of a Signature object for
either signing data or verifying a signature:

Initialization, with either



    a public key, which initializes the signature for
    verification (see initVerify), or

    a private key (and optionally a Secure Random Number Generator),
    which initializes the signature for signing
    (see initSign(PrivateKey)
    and initSign(PrivateKey, SecureRandom)).



Updating

Depending on the type of initialization, this will update the
bytes to be signed or verified. See the
update methods.

Signing or Verifying a signature on all updated bytes. See the
sign methods and the verify
method.



Note that this class is abstract and extends from
SignatureSpi for historical reasons.
Application developers should only take notice of the methods defined in
this Signature class; all the methods in
the superclass are intended for cryptographic service providers who wish to
supply their own implementations of digital signature algorithms.

 Every implementation of the Java platform is required to support the
following standard Signature algorithms:

SHA1withDSA
SHA1withRSA
SHA256withRSA

These algorithms are described in the
Signature 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.

This is the generic Signature exception.

This class defines the Service Provider Interface (SPI)
 for the Signature class, which is used to provide the
 functionality of a digital signature algorithm. Digital signatures are used
 for authentication and integrity assurance of digital data.
.
  All the abstract methods in this class must be implemented by each
 cryptographic service provider who wishes to supply the implementation
 of a particular signature algorithm.

 SignedObject is a class for the purpose of creating authentic
runtime objects whose integrity cannot be compromised without being
detected.

 More specifically, a SignedObject contains another Serializable
object, the (to-be-)signed object and its signature.

 The signed object is a "deep copy" (in serialized form) of an
original object.  Once the copy is made, further manipulation of
the original object has no side effect on the copy.

 The underlying signing algorithm is designated by the Signature
object passed to the constructor and the verify method.
A typical usage for signing is the following:



Signature signingEngine = Signature.getInstance(algorithm,
                                                provider);
SignedObject so = new SignedObject(myobject, signingKey,
                                   signingEngine);

 A typical usage for verification is the following (having
received SignedObject so):



Signature verificationEngine =
    Signature.getInstance(algorithm, provider);
if (so.verify(publickey, verificationEngine))
    try {
        Object myobj = so.getObject();
    } catch (java.lang.ClassNotFoundException e) {};

 Several points are worth noting.  First, there is no need to
initialize the signing or verification engine, as it will be
re-initialized inside the constructor and the verify
method. Secondly, for verification to succeed, the specified
public key must be the public key corresponding to the private key
used to generate the SignedObject.

 More importantly, for flexibility reasons, the
constructor and verify method allow for
customized signature engines, which can implement signature
algorithms that are not installed formally as part of a crypto
provider.  However, it is crucial that the programmer writing the
verifier code be aware what Signature engine is being
used, as its own implementation of the verify method
is invoked to verify a signature.  In other words, a malicious
Signature may choose to always return true on
verification in an attempt to bypass a security check.

 The signature algorithm can be, among others, the NIST standard
DSA, using DSA and SHA-256.  The algorithm is specified using the
same convention as that for signatures. The DSA algorithm using the
SHA-256 message digest algorithm can be specified, for example, as
"SHA256withDSA".  In the case of
RSA the signing algorithm could be specified as, for example,
"SHA256withRSA".  The algorithm name must be
specified, as there is no default.

 The name of the Cryptography Package Provider is designated
also by the Signature parameter to the constructor and the
verify method.  If the provider is not
specified, the default provider is used.  Each installation can
be configured to use a particular provider as default.

 Potential applications of SignedObject include:

 It can be used
internally to any Java runtime as an unforgeable authorization
token -- one that can be passed around without the fear that the
token can be maliciously modified without being detected.
 It
can be used to sign and serialize data/object for storage outside
the Java runtime (e.g., storing critical access control data on
disk).
 Nested SignedObjects can be used to construct a logical
sequence of signatures, resembling a chain of authorization and
delegation.

Deprecated.
This class is no longer used. Its functionality has been
 replaced by java.security.KeyStore, the
 java.security.cert package, and
 java.security.Principal.

A (transparent) specification of cryptographic parameters.

 This interface contains no methods or constants. Its only purpose
is to group (and provide type safety for) all parameter specifications.
All parameter specifications must implement this interface.

This immutable class specifies the set of parameters used for
generating DSA parameters as specified in
FIPS 186-3 Digital Signature Standard (DSS).

This class specifies the set of parameters used with the DSA algorithm.

This class specifies a DSA private key with its associated parameters.

This class specifies a DSA public key with its associated parameters.

This interface represents an elliptic curve (EC) finite field.
All specialized EC fields must implements this interface.

This immutable class defines an elliptic curve (EC)
characteristic 2 finite field.

This immutable class defines an elliptic curve (EC) prime
finite field.

This immutable class specifies the set of parameters used for
generating elliptic curve (EC) domain parameters.

This immutable class specifies the set of domain parameters
used with elliptic curve cryptography (ECC).

This immutable class represents a point on an elliptic curve (EC)
in affine coordinates. Other coordinate systems can
extend this class to represent this point in other
coordinates.

This immutable class specifies an elliptic curve private key with
its associated parameters.

This immutable class specifies an elliptic curve public key with
its associated parameters.

This immutable class holds the necessary values needed to represent
an elliptic curve.

This class represents a public or private key in encoded format.

This is the exception for invalid key specifications.

This is the exception for invalid parameter specifications.

A (transparent) specification of the key material
that constitutes a cryptographic key.

If the key is stored on a hardware device, its
specification may contain information that helps identify the key on the
device.

 A key may be specified in an algorithm-specific way, or in an
algorithm-independent encoding format (such as ASN.1).
For example, a DSA private key may be specified by its components
x, p, q, and g
(see DSAPrivateKeySpec), or it may be
specified using its DER encoding
(see PKCS8EncodedKeySpec).

 This interface contains no methods or constants. Its only purpose
is to group (and provide type safety for) all key specifications.
All key specifications must implement this interface.

This class specifies the set of parameters used with mask generation
function MGF1 in OAEP Padding and RSA-PSS signature scheme, as
defined in the
PKCS #1 v2.1
standard.

Its ASN.1 definition in PKCS#1 standard is described below:


MGF1Parameters ::= OAEP-PSSDigestAlgorthms
where


OAEP-PSSDigestAlgorithms    ALGORITHM-IDENTIFIER ::= {
  { OID id-sha1 PARAMETERS NULL   }|
  { OID id-sha224 PARAMETERS NULL   }|
  { OID id-sha256 PARAMETERS NULL }|
  { OID id-sha384 PARAMETERS NULL }|
  { OID id-sha512 PARAMETERS NULL },
  ...  -- Allows for future expansion --
}

This class represents the ASN.1 encoding of a private key,
encoded according to the ASN.1 type PrivateKeyInfo.
The PrivateKeyInfo syntax is defined in the PKCS#8 standard
as follows:



PrivateKeyInfo ::= SEQUENCE {
  version Version,
  privateKeyAlgorithm PrivateKeyAlgorithmIdentifier,
  privateKey PrivateKey,
  attributes [0] IMPLICIT Attributes OPTIONAL }

Version ::= INTEGER

PrivateKeyAlgorithmIdentifier ::= AlgorithmIdentifier

PrivateKey ::= OCTET STRING

Attributes ::= SET OF Attribute

This class specifies a parameter spec for RSA-PSS signature scheme,
as defined in the
PKCS#1 v2.1
standard.

Its ASN.1 definition in PKCS#1 standard is described below:


RSASSA-PSS-params ::= SEQUENCE {
  hashAlgorithm      [0] OAEP-PSSDigestAlgorithms  DEFAULT sha1,
  maskGenAlgorithm   [1] PKCS1MGFAlgorithms  DEFAULT mgf1SHA1,
  saltLength         [2] INTEGER  DEFAULT 20,
  trailerField       [3] INTEGER  DEFAULT 1
}
where


OAEP-PSSDigestAlgorithms    ALGORITHM-IDENTIFIER ::= {
  { OID id-sha1 PARAMETERS NULL   }|
  { OID id-sha224 PARAMETERS NULL   }|
  { OID id-sha256 PARAMETERS NULL }|
  { OID id-sha384 PARAMETERS NULL }|
  { OID id-sha512 PARAMETERS NULL },
  ...  -- Allows for future expansion --
}

PKCS1MGFAlgorithms    ALGORITHM-IDENTIFIER ::= {
  { OID id-mgf1 PARAMETERS OAEP-PSSDigestAlgorithms },
  ...  -- Allows for future expansion --
}
Note: the PSSParameterSpec.DEFAULT uses the following:
    message digest  -- "SHA-1"
    mask generation function (mgf) -- "MGF1"
    parameters for mgf -- MGF1ParameterSpec.SHA1
    SaltLength   -- 20
    TrailerField -- 1

This class specifies the set of parameters used to generate an RSA
key pair.

This class specifies an RSA multi-prime private key, as defined in the
PKCS#1 v2.1, using the Chinese Remainder Theorem (CRT) information
values for efficiency.

This class represents the triplet (prime, exponent, and coefficient)
inside RSA's OtherPrimeInfo structure, as defined in the PKCS#1 v2.1.
The ASN.1 syntax of RSA's OtherPrimeInfo is as follows:



OtherPrimeInfo ::= SEQUENCE {
  prime INTEGER,
  exponent INTEGER,
  coefficient INTEGER
  }

This class specifies an RSA private key, as defined in the PKCS#1
standard, using the Chinese Remainder Theorem (CRT) information values for
efficiency.

This class specifies an RSA private key.

This class specifies an RSA public key.

This class represents the ASN.1 encoding of a public key,
encoded according to the ASN.1 type SubjectPublicKeyInfo.
The SubjectPublicKeyInfo syntax is defined in the X.509
standard as follows:



SubjectPublicKeyInfo ::= SEQUENCE {
  algorithm AlgorithmIdentifier,
  subjectPublicKey BIT STRING }

This class encapsulates information about a signed timestamp.
It is immutable.
It includes the timestamp's date and time as well as information about the
Timestamping Authority (TSA) which generated and signed the timestamp.

This exception is thrown if an entry in the keystore cannot be recovered.

This exception is thrown if a key in the keystore cannot be recovered.

The UnresolvedPermission class is used to hold Permissions that
were "unresolved" when the Policy was initialized.
An unresolved permission is one whose actual Permission class
does not yet exist at the time the Policy is initialized (see below).

The policy for a Java runtime (specifying
which permissions are available for code from various principals)
is represented by a Policy object.
Whenever a Policy is initialized or refreshed, Permission objects of
appropriate classes are created for all permissions
allowed by the Policy.

Many permission class types
referenced by the policy configuration are ones that exist
locally (i.e., ones that can be found on CLASSPATH).
Objects for such permissions can be instantiated during
Policy initialization. For example, it is always possible
to instantiate a java.io.FilePermission, since the
FilePermission class is found on the CLASSPATH.

Other permission classes may not yet exist during Policy
initialization. For example, a referenced permission class may
be in a JAR file that will later be loaded.
For each such class, an UnresolvedPermission is instantiated.
Thus, an UnresolvedPermission is essentially a "placeholder"
containing information about the permission.

Later, when code calls AccessController.checkPermission
on a permission of a type that was previously unresolved,
but whose class has since been loaded, previously-unresolved
permissions of that type are "resolved". That is,
for each such UnresolvedPermission, a new object of
the appropriate class type is instantiated, based on the
information in the UnresolvedPermission.

 To instantiate the new class, UnresolvedPermission assumes
the class provides a zero, one, and/or two-argument constructor.
The zero-argument constructor would be used to instantiate
a permission without a name and without actions.
A one-arg constructor is assumed to take a String
name as input, and a two-arg constructor is assumed to take a
String name and String actions
as input.  UnresolvedPermission may invoke a
constructor with a null name and/or actions.
If an appropriate permission constructor is not available,
the UnresolvedPermission is ignored and the relevant permission
will not be granted to executing code.

 The newly created permission object replaces the
UnresolvedPermission, which is removed.

 Note that the getName method for an
UnresolvedPermission returns the
type (class name) for the underlying permission
that has not been resolved.

A parameter that contains a URI pointing to data intended for a
PolicySpi or ConfigurationSpi implementation.