Generated by
JDiff

java.security Documentation Differences

This file contains all the changes in documentation in the package java.security as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class AccessControlContext, constructor AccessControlContext(AccessControlContext, DomainCombiner)

Create a new AccessControlContext with the given AccessControlContext and DomainCombiner. This constructor associates the provided DomainCombiner with the provided AccessControlContext.

@param acc the AccessControlContext associated with the provided DomainCombiner.

@param combiner the DomainCombiner to be associated with the provided AccessControlContext. @exception NullPointerException if either the provided context or the provided combiner areis null.

@exception SecurityException if the caller does not have permission to invoke this constructor.


Class AccessControlException

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. @version 1.9 0210 12/0203/0001 @author Li Gong @author Roland Schemers


Class AccessController

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

More specifically the AccessController class is used for three purposes:

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:

 i = m; while (i > 0) { 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) return; } i = i - 1; }; // 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 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.

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() { public Object 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 that returns an Object. 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 = (String) AccessController.doPrivileged( new PrivilegedAction() { public Object 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 = (FileInputStream) AccessController.doPrivileged( new PrivilegedExceptionAction() { public Object 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.

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:

 somemethod() { AccessController.doPrivileged(new PrivilegedAction() { public Object run() { // Code goes here. Any permission checks fromwithin this // pointrun method forwardwill require boththat the current context andintersection of the // callers protection domain and the snapshot's context// tocontext have the desired permission. } } acc); ...normal code here... } 
@see AccessControlContext @version 1.4751 0001/0212/0203 @author Li Gong @author Roland Schemers
Class AccessController, Object doPrivileged(PrivilegedExceptionAction)

Performs the specified PrivilegedExceptionAction with privileges enabled. The action is performed with all of the permissions possessed by the caller's protection domain.

If the action's run method throws an unchecked exception it will propagate through this method. @param action the action to be performed. @return the value returned by the action's run method. @throws PrivilgedActionExceptionPrivilegedActionException if the specified action's run method threw a checked exception. @see #doPrivileged(PrivilegedExceptionAction AccessControlContextPrivilegedAction) @see #doPrivileged(PrivilegedActionPrivilegedExceptionAction AccessControlContext)

Class AccessController, Object doPrivileged(PrivilegedExceptionAction, AccessControlContext)

Performs the specified PrivilegedExceptionAction with privileges enabled and restricted by the specified AccessControlContext. The action is performed with the intersection of the the permissions possessed by the caller's protection domain and those possessed by the domains represented by the specified AccessControlContext.

If the action's run method throws an unchecked exception it will propagate through this method. @param action the action to be performed. @param context an access control context representing the restriction to be applied to the caller's domain's privileges before performing the specified action. @return the value returned by the action's run method. @throws PrivilegedActionException if the specified action's run method threw a checked exception. @see #doPrivileged(PrivilegedAction) @see #doPrivileged(PrivilegedExceptionAction AccessControlContext)


Class AlgorithmParameterGenerator

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:

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. @author Jan Luehe @version 1.36 0238 12/0203/0001 @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @since 1.2


Class AlgorithmParameterGeneratorSpi

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. @author Jan Luehe @version 1.11 0212 12/0203/0001 @see AlgorithmParameterGenerator @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @since 1.2


Class AlgorithmParameters

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).

There are two ways to request such an implementation: by specifying either just an algorithm name or both an algorithm name and a package provider.

Once an AlgorithmParameters object is returned 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. @author Jan Luehe @version 1.19 0221 12/0203/0001 @see java.security.spec.AlgorithmParameterSpec @see java.security.spec.DSAParameterSpec @see KeyPairGenerator @since 1.2


Class AlgorithmParametersSpi

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. @author Jan Luehe @version 1.8 029 12/0203/0001 @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @see java.security.spec.DSAParameterSpec @since 1.2


Class AllPermission

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. @see java.security.Permission @see java.security.AccessController @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.15 0001/0412/0603 @author Roland Schemers @serial exclude


Class BasicPermission

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 at the end of the name followingby itself or if immediately preceded by a "." ormay byappear itselfat the end of the name to signify a wildcard match. For example: "java.*" orand "java.*" isare valid while "*java" or "a*b" isand "java*" are not valid.

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.

@see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.RuntimePermission @see java.security.SecurityPermission @see java.util.PropertyPermission @see java.awt.AWTPermission @see java.net.NetPermission @see java.lang.SecurityManager @version 1.26 0032 01/0212/0203 @author Marianne Mueller @author Roland Schemers @serial exclude

Class BasicPermission, constructor BasicPermission(String)

Creates a new BasicPermission with the specified name. Name is the symbolic name of the permission such as "setFactory" "print.queueJob" or "topLevelWindow" etc. An asterisk may appear at the end of the name following a "." or by itself to signify a wildcard match. @param name the name of the BasicPermission. @throws NullPointerException if name is null. @throws IllegalArgumentException if name is empty.

Class Certificate

This is an interface of abstract methods for managing a variety of identity certificates. An identity certificate is a guarantee by a principal that a public key is that of another principal. (A principal represents an entity such as an individual user a group or a corporation.)

In particular this interface is intended to be a common abstraction for constructs that have different formats but important common uses. For example different types of certificates such as X.509 certificates and PGP certificates share general certificate functionality (the need to encode and decode certificates) and some types of information such as a public key the principal whose key it is and the guarantor guaranteeing that the public key is that of the specified principal. So an implementation of X.509 certificates and an implementation of PGP certificates can both utilize the Certificate interface even though their formats and additional types and amounts of information stored are different.

Important: This interface is useful for cataloging and grouping objects sharing certain common uses. It does not have any semantics of its own. In particular a Certificate object does not make any statement as to the validity of the binding. It is the duty of the application implementing this interface to verify the certificate and satisfy itself of its validity. @version 1.31 0234 12/0203/0001 @author Benjamin Renaud @deprecated A new certificate handling package is created in the Java 2 platform. This Certificate interface is entirely deprecated and is here to allow for a smooth transition to the new package. @see java.security.cert.Certificate

Class Certificate, String toString(boolean)

Returns a string that represents the contents of the certificate. @param detailed whether or not to give detailed information about the certificate. @return a string representing the contents of the certificate

Class CodeSource

This class extends the concept of a codebase to encapsulate not only the location (URL) but also the certificate(s) that were used to verify signed code originating from that location. @version 1.28 0231 12/0203/0001 @author Li Gong @author Roland Schemers

Class CodeSource, boolean implies(CodeSource)

Returns true if this CodeSource object "implies" the specified CodeSource.

More specifically this method makes the following checks in order. If any fail it returns false. If they all succeed it returns true.

  1. codesource must not be null.
  2. If this object's certificates are not null then all of this object's certificates must be present in codesource's certificates.
  3. If this object's location (getLocation()) is not null then the following checks are made against this object's location and codesource's:

    1. codesource's location must not be null.
    2. If this object's location equals codesource's location then return true.
    3. This object's protocol (getLocation().getProtocol()) must be equal to codesource's protocol.
    4. If this object's host (getLocation().getHost()) is not null then the SocketPermission constructed with this object's host must imply the SocketPermission constructed with codesource's host.
    5. If this object's port (getLocation().getPort()) is not equal to -1 (that is if a port is specified) it must equal codesource's port.
    6. If this object's file (getLocation().getFile()) doesn't equal codesource's file then the following checks are made: If this object's file ends with "/-" then codesource's file must start with this object's file (exclusive the trailing "-"). If this object's file ends with a "/*" then codesource's file must start with this object's file and must not have any further "/" separators. If this object's file doesn't end with a "/" then codesource's file must match this object's file with a '/' appended.
    7. If this object's reference (getLocation().getRef()) is not null it must equal codesource's reference.

For example the codesource objects with the following locations and null certificates all imply the codesource with the location "http://java.sun.com/classes/foo.jar" and null certificates:

 http: http://*.sun.com/classes/* http://java.sun.com/classes/- http://java.sun.com/classes/foo.jar 
Note that if this CodeSource has a null location and a null certificate chain then it implies every other CodeSource. @param codesource CodeSource to compare against. @return true if the specified codesource is implied by this codesource false if not.

Class DigestException

This is the generic Message Digest exception. @version 1.12 0013 01/0212/0203 @author Benjamin Renaud

Class DigestInputStream

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 s 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. @see MessageDigest @see DigestOutputStream @version 1.34 0035 01/0212/0203 @author Benjamin Renaud


Class DigestOutputStream

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 ouput 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. @see MessageDigest @see DigestInputStream @version 1.28 0029 01/0212/0203 @author Benjamin Renaud


Class DomainCombiner

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 onfrom the current execution Thread since the most recent call to AccessController.doPrivileged. getIf passedno call to doPrivileged was made then the first argument inwill contain all the ProtectionDomains from the current execution Thread. The second argument represents an array. If no callof inherited ProtectionDomains towhich may be doPrivilegednull. was made then all theProtectionDomains may be inherited from ProtectionDomainsa parent Thread or from the currenta privileged executioncontext. Thread get passedIf no call to doPrivileged was made then the firstsecond argument. Thewill contain the ProtectionDomains inherited from the parent Thread. getIf passedone or more calls to the second argument unlessdoPrivileged were made and athe most recent call was to doPrivileged(...action context) hadthen occurred.the In thatsecond argument casewill contain the ProtectionDomains from the privileged context are. If passedthe 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. @see AccessController @see AccessControlContext @version 1.3 025 12/0203/0001

Class DomainCombiner, ProtectionDomain[] combine(ProtectionDomain[], ProtectionDomain[])

Modify or update the provided ProtectionDomains. ProtectionDomains may be added to or removed from the given ProtectionDomains. The ProtectionDomains may be re-ordered. Individual ProtectionDomains may be may be modified (with a new set of Permissions for example).

@param currentDomains the ProtectionDomains associated with the current execution Thread up to the most recent privileged ProtectionDomain. The ProtectionDomains are are listed in order of execution with the most recently executing ProtectionDomain residing at the beginning of the array. This parameter may be null if the current execution Thread has no associated ProtectionDomains.

@param assignedDomains thean array of inherited ProtectionDomains. ProtectionDomains may be inherited from thea parent Thread or the ProtectionDomains from the privileged context if a call toprivileged AccessController.doPrivileged(..AccessControlContext. context) had occurred This parameter may be null if there wereare no ProtectionDomains inherited from the parent Thread or from the privileged contextProtectionDomains. @return a new array consisting of the updated ProtectionDomains or null.


Class GeneralSecurityException

This is the general security exception class which serves to group all the exception classes of the java.security package that extend from it. (Exceptions

The exceptions to this grouping are:

@version 1.9 0011 01/0212/0203 @author Jan Luehe

Class Guard

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. @see GuardedObject @version 1.9 0010 01/0212/0203 @author Roland Schemers @author Li Gong


Class GuardedObject

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. @see Guard @see Permission @version 1.11 0012 01/0212/0203 @author Roland Schemers @author Li Gong


Class Identity

This class represents identities: real-world objects such as people companies or organizations whose identities can be authenticated using their public keys. Identities may also be more abstract (or concrete) constructs such as daemon threads or smart cards.

All Identity objects have a name and a public key. Names are immutable. Identities may also be scoped. That is if an Identity is specified to have a particular scope then the name and public key of the Identity are unique within that scope.

An Identity also has a set of certificates (all certifying its own public key). The Principal names specified in these certificates need not be the same only the key.

An Identity can be subclassed to include postal and email addresses telephone numbers images of faces and logos and so on. @see IdentityScope @see Signer @see Principal @version 1.5658 @author Benjamin Renaud @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.

Class Identity, PublicKey getPublicKey()

Returns this identity's public key. @return the public key for this identity. @see #setPublicKey
Class Identity, void setPublicKey(PublicKey)

Sets this identity's public key. The old key and all of this identity's certificates are removed by this operation.

First if there is a security manager its checkSecurityAccess method is called with "setIdentityPublicKey" as its argument to see if it's ok to set the public key. @param key the public key for this identity. @exception KeyManagementException if another identity in the identity's scope has the same public key or if another exception occurs. @exception SecurityException if a security manager exists and its checkSecurityAccess method doesn't allow setting the public key. @see #getPublicKey @see SecurityManager#checkSecurityAccess


Class IdentityScope

This class represents a scope for identities. It is an Identity itself and therefore has a name and can have a scope. It can also optionally have a public key and associated certificates.

An IdentityScope can contain Identity objects of all kinds including Signers. All types of Identity objects can be retrieved added and removed using the same methods. Note that it is possible and in fact expected that different types of identity scopes will apply different policies for their various operations on the various types of Identities.

There is a one-to-one mapping between keys and identities and there can only be one copy of one key per scope. For example suppose Acme Software Inc is a software publisher known to a user. Suppose it is an Identity that is it has a public key and a set of associated certificates. It is named in the scope using the name "Acme Software". No other named Identity in the scope has the same public key. Of course none has the same name as well. @see Identity @see Signer @see Principal @see Key @version 1.46 0048 01/0212/0203 @author Benjamin Renaud @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.

Class IdentityScope, IdentityScope getSystemScope()

Returns the system's identity scope. @return the system's identity scope. @see #setSystemScope
Class IdentityScope, void setSystemScope(IdentityScope)

Sets the system's identity scope.

First if there is a security manager its checkSecurityAccess method is called with "setSystemScope" as its argument to see if it's ok to set the identity scope. @param scope the scope to set. @exception SecurityException if a security manager exists and its checkSecurityAccess method doesn't allow setting the identity scope. @see #getSystemScope @see SecurityManager#checkSecurityAccess


Class InvalidAlgorithmParameterException

This is the exception for invalid or inappropriate algorithm parameters. @author Jan Luehe @version 1.9 0210 12/0203/0001 @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @since 1.2

Class InvalidKeyException

This is the exception for invalid Keys (invalid encoding wrong length uninitialized etc). @version 1.11 0212 12/0203/0001 @author Benjamin Renaud

Class InvalidParameterException

This exception designed for use by the JCA/JCE engine classes is thrown when an invalid parameter is passed to a method. @author Benjamin Renaud @version 1.15 0017 01/0212/0203

Class Key

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: 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 @se PublicKey @see PrivateKey @see KeyPair @see KeyPairGenerator @see KeyFactory @see java.security.spec.KeySpec @see Identity @see Signer @version 1.47 0051 01/0212/0203 @author Benjamin Renaud

Class KeyException

This is the basic key exception. @see Key @see InvalidKeyException @see KeyManagementException @version 1.14 0015 01/0212/0203 @author Benjamin Renaud

Class KeyFactory

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); 
@author Jan Luehe @version 1.24 0226 12/0203/0001 @see Key @see PublicKey @see PrivateKey @see java.security.spec.KeySpec @see java.security.spec.DSAPublicKeySpec @see java.security.spec.X509EncodedKeySpec @since 1.2

Class KeyFactorySpi

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. @author Jan Luehe @version 1.8 029 12/0203/0001 @see KeyFactory @see Key @see PublicKey @see PrivateKey @see java.security.spec.KeySpec @see java.security.spec.DSAPublicKeySpec @see java.security.spec.X509EncodedKeySpec @since 1.2


Class KeyManagementException

This is the general key management exception for all operations dealing with key management. SubclassesExamples of subclasses of KeyManagementException that developers might create for giving more detailed information could include: @version 1.1114 0001/0212/0203 @author Benjamin Renaud @see Key @see KeyException

Class KeyPair

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. @see PublicKey @see PrivateKey @version 1.11 0012 01/0212/0203 @author Benjamin Renaud

Class KeyPairGenerator

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:

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. @author Benjamin Renaud @version 1.49 0251 12/0203/0001 @see java.security.spec.AlgorithmParameterSpec


Class KeyPairGeneratorSpi

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. @author Benjamin Renaud @version 1.11 0212 12/0203/0001 @see KeyPairGenerator @see java.security.spec.AlgorithmParameterSpec


Class KeyStore

This class represents an in-memory collection of keys and certificates. It manages two types of entries:

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 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).

There are two ways to request a KeyStore object: by specifying either just a keystore type or both a keystore type and a package provider.

Before a keystore can be accessed it must be char[] loaded}. In order to create an empty keystore you pass null as the InputStream argument to the load method. @author Jan Luehe @version 1.29 0231 12/0203/0001 @see java.security.PrivateKey @see java.security.cert.Certificate @since 1.2


Class KeyStoreException

This is the generic KeyStore exception. @author Jan Luehe @version 1.7 028 12/0203/0001 @since 1.2

Class KeyStoreSpi

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. @author Jan Luehe @version 1.9 0210 12/0203/0001 @see KeyStore @since 1.2

Class MessageDigest

This MessageDigest class provides applications 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.

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"); 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. @author Benjamin Renaud @version 1.71 0273 12/0203/0001 @see DigestInputStream @see DigestOutputStream


Class MessageDigestSpi

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. @author Benjamin Renaud @version 1.11 0212 12/0203/0001 @see MessageDigest


Class NoSuchAlgorithmException

This exception is thrown when a particular cryptographic algorithm is requested but is not available in the environment. @version 1.20 0021 01/0212/0203 @author Benjamin Renaud

Class NoSuchProviderException

This exception is thrown when a particular security provider is requested but is not available in the environment. @version 1.16 0017 01/0212/0203 @author Benjamin Renaud

Class Permission

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. @see Permissions @see PermissionCollection @version 1.35 0036 01/0212/0203 @author Marianne Mueller @author Roland Schemers


Class PermissionCollection

Abstract class representing a collection of Permission objects.

With a PermissionCollection you can:

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 heterogenous. 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 Hastable 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. @see Permission @see Permissions @version 1.26 0028 01/0212/0203 @author Roland Schemers


Class Permissions

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. @see Permission @see PermissionCollection @see AllPermission @version 1.46 0049 01/0212/0203 @author Marianne Mueller @author Roland Schemers @serial exclude


Class Policy

This is an abstract class for representing the system security policy for a Java application environment (specifying which permissions are available for code from various sources). That is the security policy is represented by a Policy subclass providing an implementation of the abstract methods in this Policy class.

There is only one Policy object in effect at any given time.

The Policy object is typically consulted by objects such as the byte[ int int CodeSource) SecureClassLoader} when a loader needs to determine the permissions to assign to a particular protection domain. The SecureClassLoader executes code such as the following to ask the currently installed Policy object to populate a PermissionCollection object: policy = Policy.getPolicy(); PermissionCollection perms = policy.getPermissions(MyCodeSource) The SecureClassLoader object passes in a CodeSource object which encapsulates the codebase (URL) and public key certificates of the classes being loaded. The Policy object consults its policy specification and returns an appropriate Permissions object enumerating the permissions allowed for code from the specified code source. The source location for the policy information utilized by the Policy object is up to the Policy implementation. The policy configuration may be stored for example as a flat ASCII file as a serialized binary file of the Policy class or as a database.

The currently-installed Policy object can be obtained by calling the getPolicy method and it can be changed by a call to the setPolicy method (by code with permission to reset the Policy).

The refresh method causes the policy object to refresh/reload its current configuration.

This is implementation-dependent. For example if the policy object stores its policy in configuration files calling refresh will cause it to re-read the configuration policy files. The refreshed policy may not have an effect on classes loaded fromin a given CodeSourceparticular ProtectionDomain. This is dependent on the ProtectionDomainPolicy cachingprovider's strategyimplementation of the ClassLoader.Permission Forimplies} example themethod and SecureClassLoaderthe caches protection domainsPermissionCollection caching strategy.

The default Policy implementation can be changed by setting the value of the "policy.provider" security property (in the Java security properties file) to the fully qualified name of the desired Policy implementation class. The Java security properties file is located in the file named <JAVA_HOME>/lib/security/java.security where <JAVA_HOME> refers to the directory where the SDK was installed. @author Roland Schemers @author Gary Ellison @version 1.68 0287 12/0203/0001 @see java.security.CodeSource @see java.security.PermissionCollection @see java.security.SecureClassLoader

Class Policy, PermissionCollection getPermissions(CodeSource)

Evaluates the global policy and returns a PermissionCollection object specifying the set of permissions allowed for code from the specified code source. @param codesource the CodeSource associated with the caller. This encapsulates the original location of the code (where the code came from) and the public key(s) of its signer. @return the set of permissions allowed for code from codesource according to the policy.The @exceptionreturned java.lang.SecurityExceptionset if the current thread does not have permission to callof permissions must be a new mutable instance and it getPermissionsmust on the policy objectsupport heterogeneous Permission types.
Class Policy, Policy getPolicy()

Returns the installed Policy object. This value should not be cached as it may be changed by a call to setPolicy. This method first calls SecurityManager.checkPermission with a SecurityPermission("getPolicy") permission to ensure it's ok to get the Policy object.. @return the installed Policy. @throws SecurityException if a security manager exists and its checkPermission method doesn't allow getting the Policy object. @see SecurityManager#checkPermission(SecurityPermissionPermission) @see #setPolicy(java.security.Policy)
Class Policy, void refresh()

Refreshes/reloads the policy configuration. The behavior of this method depends on the implementation. For example calling refresh on a file-based policy will cause the file to be re-read. @exception java.lang.SecurityException if the current thread does not have permission to refresh this Policy object.
Class Policy, void setPolicy(Policy)

Sets the system-wide Policy object. This method first calls SecurityManager.checkPermission with a SecurityPermission("setPolicy") permission to ensure it's ok to set the Policy. @param policy the new system Policy object. @throws SecurityException if a security manager exists and its checkPermission method doesn't allow setting the Policy. @see SecurityManager#checkPermission(SecurityPermissionPermission) @see #getPolicy()

Class Principal

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. @see java.security.cert.X509Certificate @version 1.19 0020 01/0212/0203 @author Li Gong

Class PrivateKey

A private key. This interface contains no methods or constants. It merely serves 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. @see Key @see PublicKey @see Certificate @see Signature#initVerify @see java.security.interfaces.DSAPrivateKey @see java.security.interfaces.RSAPrivateKey @see java.security.interfaces.RSAPrivateCrtKey @version 1.25 0027 01/0212/0203 @author Benjamin Renaud @author Josh Bloch


Class PrivilegedActionException

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." @see PrivilegedExceptionAction @see AccessController#doPrivileged(PrivilegedExceptionAction) @see AccessController#doPrivileged(PrivilegedExceptionAction AccessControlContext)

Class PrivilegedActionException, Exception getException()

Returns the exception thrown by the privileged computation that resulted in this PrivilegedActionException.

This method predates the general-purpose exception chaining facility. The Throwable#getCause() method is now the preferred means of obtaining this information. @return the exception thrown by the privileged computation that resulted in this PrivilegedActionException. @see PrivilegedExceptionAction @see AccessController#doPrivileged(PrivilegedExceptionAction) @see AccessController#doPrivileged(PrivilegedExceptionAction AccessControlContext)


Class ProtectionDomain

This ProtectionDomain class encapulatesencapsulates the characteristics of a domain which encloses a set of classes whose instances are granted the samea set of permissions. Inwhen addition to a setbeing executed on behalf of permissions a domain isgiven comprisedset of a CodeSourcePrincipals. which is a

A static set of PublicKeyspermissions together with a codebasecan be bound to (ina the form of aProtectionDomain when it is URL).constructed; Thussuch classespermissions are signed bygranted to the same keysdomain and fromregardless of the samePolicy URLin areforce. placed in the sameHowever to support dynamic domain.security Classes that have the same permissions but are from different code sources belongpolicies a ProtectionDomain can also be constructed such that it is dynamically mapped to differenta domains.set Aof permissions classby the belongs to one and only one ProtectionDomaincurrent Policy whenever a permission is checked.

@version 1.26 0239 12/0203/0001 @author Li Gong @author Roland Schemers @author Gary Ellison

Class ProtectionDomain, constructor ProtectionDomain(CodeSource, PermissionCollection)

Creates a new ProtectionDomain with the given CodeSource and Permissions. If the permissions object is not null then setReadOnly()) will be called on the passed in Permissions object. The only permissions granted to this domain are the ones specified; the current Policy will not be consulted. @param codesource the codesource associated with this domain @param permissions the permissions granted to this domain
Class ProtectionDomain, CodeSource getCodeSource()

Returns the CodeSource of this domain. @return the CodeSource of this domain which may be null. @since 1.2
Class ProtectionDomain, PermissionCollection getPermissions()

Returns the static permissions ofgranted to this domain. @return the permissionsstatic set of permissions for this domain which may be null. @see Policy#refresh @see Policy#getPermissions(ProtectionDomain)
Class ProtectionDomain, boolean implies(Permission)

Check and see if this ProtectionDomain implies the permissions expressed in the Permission object.

The set of permissions evaluated is a function of whether the ProtectionDomain was constructed with a static set of permissions or it was bound to a dynamically mapped set of permissions.

If the ProtectionDomain was constructed to a PermissionCollection statically bound} PermissionCollection then the permission will only be checked against the PermissionCollection supplied at construction.

However if the ProtectionDomain was constructed with the constructor variant which supports PermissionCollectio ClassLoader java.security.Principal[]) dynamically binding} permissions then the permission will be checked against the combination of the PermissionCollection supplied at construction and the current Policy binding.

@param permission the Permission object to check. @return true if "permission" is a proper subset of a permissionimplicit into this ProtectionDomain false if not.


Class Provider

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

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. @version 1.48 0250 12/0203/0001 @author Benjamin Renaud


Class ProviderException

A runtime exception for Provider exceptions (such as misconfiguration errors) which may be subclassed by Providers to throw specialized provider-specific runtime errors. @version 1.10 0011 01/0212/0203 @author Benjamin Renaud

Class PublicKey

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. @see Key @see PrivateKey @see Certificate @see Signature#initVerify @see java.security.interfaces.DSAPublicKey @see java.security.interfaces.RSAPublicKey @version 1.28 0030 01/0212/0203


Class SecureClassLoader

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. @version 1.73 0281 12/0203/0001 @author Li Gong @author Roland Schemers
Class SecureClassLoader, Class defineClass(String, byte[], int, int, CodeSource)

Converts an array of bytes into an instance of class Class with an optional CodeSource. Before the class can be used it must be resolved.

If a non-null CodeSource is supplied and a Policy provider is installed Policy.getPermissions()ProtectionDomain is invoked in order to associateconstructed a ProtectionDomainand associated with the class being defined.

@param name the expected name of the class or null if not known using '.' and not '/' as the separator and without a trailing ".class" suffix. @param b the bytes that make up the class data. The bytes in positions off through off+len-1 should have the format of a valid class file as defined by the Java Virtual Machine Specification. @param off the start offset in b of the class bytesdata @param len the length of the class bytesdata @param cs the associated CodeSource or null if none @return the Class object created from the data and optional CodeSource. @exception ClassFormatError if the data did not contain a valid class @exception IndexOutOfBoundsException if either off or len is negative or if off+len is greater than b.length. @exception SecurityException if an attempt is made to add this class to a package that contains classes that were signed by a different set of certificates than this class or if the class name begins with "java.".

Class SecureClassLoader, PermissionCollection getPermissions(CodeSource)

Returns the permissions for the given CodeSource object. The default implementation of this method invokes the java.security.Policy.getPermissions method to get the permissions granted by the policy to the specified CodeSource.

This method is invoked by the defineClass method which takes a CodeSource as an argument when it is constructing the ProtectionDomain for the class being defined.

The constructed ProtectionDomain is cached by the SecureClassLoader. The contents of the cache persist for the lifetime of the SecureClassLoader instance. This persistence inhibits Policy.refresh() from influencing the protection domains already in the cache for a given CodeSource. @param codesource the codesource. @return the permissions granted to the codesource.


Class SecureRandom

This class provides a cryptographically strong pseudo-random number generator (PRNG). A cryptographically strong pseudo-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 and therefore it is required that the seed material be unpredictable and that output of SecureRandom be cryptographically strong sequences as described in RFC 1750: Randomness Recommendations for Security.

Like other algorithm-based classes in Java Security SecureRandom provides implementation-independent algorithms whereby a caller (application code) requests a particular PRNG algorithm and is handed back a SecureRandom object for that algorithm. It is also possible if desired to request a particular algorithm from a particular provider. See the getInstance methods.

Thus there are two ways to request a SecureRandom object: by specifying either just an algorithm name or both an algorithm name and a package provider.

The SecureRandom implementation attempts to completely randomize the internal state of the generator itself unless the caller follows the call to a getInstance method with a call to the setSeed method:

 SecureRandom random = SecureRandom.getInstance("SHA1PRNG"); random.setSeed(seed); 

After the caller obtains the SecureRandom object from the getInstance call it can call nextBytes to generate random bytes:

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

The caller 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); 
@see java.security.SecureRandomSpi @see java.util.Random @version 1.36 0241 12/0203/0001 @author Benjamin Renaud @author Josh Bloch
Class SecureRandom, byte[] getSeed(int)

Returns the given number of seed bytes computed using the seed generation algorithm that this class uses to seed itself. This call may be used to seed other random number generators.

This method is only included for backwards compatibility. The caller is encouraged to use one of the alternative getInstance methods to obtain a SecureRandom object and then call the generateSeed method to obtain seed bytes from that object. @param numBytes the number of seed bytes to generate. @return the seed bytes. @see #setSeed

Class SecureRandom, void setSeed(byte[])

Reseeds this random object. The given seed supplements rather than replaces the existing seed. Thus repeated calls are guaranteed never to reduce randomness. @param seed the seed. @see #getSeed
Class SecureRandom, void setSeed(long)

Reseeds this random object using the eight bytes contained in the given long seed. The given seed supplements rather than replaces the existing seed. Thus repeated calls are guaranteed never to reduce randomness.

This method is defined for compatibility with java.util.Random. @param seed the seed. @see #getSeed


Class SecureRandomSpi

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. @version 1.7 028 12/0203/0001 @see SecureRandom @since 1.2

Class Security

This class centralizes all security properties and common security methods. One of its primary uses is to manage providers. @author Benjamin Renaud @version 1.101 08114 12/1020/0001

Class Security, String getProperty(String)

Gets a security property value.

First if there is a security manager its checkPermission method is called with a java.security.SecurityPermission("getProperty."+key) permission to see if it's ok to retrieve the specified security property value.. @param key the key of the property being retrieved. @return the value of the security property corresponding to key. @throws SecurityException if a security manager exists and its {@link java.lang.SecurityManager#checkPermission} method denies access to retrieve the specified security property value @see #setProperty @see java.security.SecurityPermission

Class Security, Provider getProvider(String)

Returns the provider installed with the specified name if any. Returns null if no provider with the speicifiedspecified name is installed. @param name the name of the provider to get. @return the provider of the specified name. @see #removeProvider @see #addProvider
Class Security, void setProperty(String, String)

Sets a security property value.

First if there is a security manager its checkPermission method is called with a java.security.SecurityPermission("setProperty."+key) permission to see if it's ok to set the specified security property value. @param key the name of the property to be set. @param datum the value of the property to be set. @throws SecurityException if a security manager exists and its {@link java.lang.SecurityManager#checkPermission} method denies access to set the specified security property value @see #getProperty @see java.security.SecurityPermission


Class SecurityPermission

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. Since DomainCombiners are given a reference to the ProtectionDomains currently on the stack this could potentially lead to a privacy leak if the DomainCombiner is malicious.
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.
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 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.{provider name} Addition of a new provider with the specified name 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.
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.
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]
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.
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.
@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.21 0022 01/0212/0203 @author Marianne Mueller @author Roland Schemers


Class Signature

This 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-1. The DSA algorithm using the SHA-1 message digest algorithm can be specified as SHA1withDSA. In the case of RSA there are multiple choices for the message digest algorithm so the signing algorithm could be specified as for example MD2withRSA MD5withRSA or SHA1withRSA. The algorithm name must be specified as there is no default.

Like other algorithm-based classes in Java Security Signature provides implementation-independent algorithms whereby a caller (application code) requests a particular signature algorithm and is handed back a properly initialized Signature object. It is also possible if desired to request a particular algorithm from a particular provider. See the getInstance methods.

Thus there are two ways to request a Signature algorithm object: by specifying either just an algorithm name or both an algorithm name and a package provider.

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:

  1. 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 SecureRandom)})

  2. Updating

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

  3. 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. @author Benjamin Renaud @version 1.85 0289 12/0203/0001

Class Signature, Object getParameter(String)

Gets the value of the specified algorithm parameter. This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm such as a parameter size or a source of random bits for signature generation (if appropriate) or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time. @param param the string name of the parameter. @return the object that represents the parameter value or null if there is none. @exception InvalidParameterException if param is an invalid parameter for this engine or another exception occurs while trying to get this parameter. @see #setParameter(String Object) @deprecated
Class Signature, void setParameter(AlgorithmParameterSpec)

Initializes this signature engine with the specified parameter set. @param params the parameters @exception InvalidAlgorithmParameterException if the given parameters are inappropriate for this signature engine @see #getParameters
Class Signature, void setParameter(String, Object)

Sets the specified algorithm parameter to the specified value. This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm such as a parameter size or a source of random bits for signature generation (if appropriate) or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time. @param param the string identifier of the parameter. @param value the parameter value. @exception InvalidParameterException if param is an invalid parameter for this signature algorithm engine the parameter is already set and cannot be set again a security exception occurs and so on. @see #getParameter @deprecated Use setParameter

Class SignatureException

This is the generic Signature exception. @version 1.11 0212 12/0203/0001 @author Benjamin Renaud

Class SignatureSpi

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. @author Benjamin Renaud @version 1.14 0219 12/0203/0001 @see Signature

Class SignatureSpi, void engineSetParameter(AlgorithmParameterSpec)

Initializes

This method is overridden by providers to initialize this signature engine with the specified parameter set. This@param concrete method hasparams the parameters been@exception added toUnsupportedOperationException if this previously-defined abstract class. (For backwards compatibility it cannot be abstract.) Itmethod may beis not overridden by a provider to set the algorithm parameters using the specified params. Such an override is expected to throw an@exception InvalidAlgorithmParameterException if a parameter is invalid. If this method is not overridden it always throws anby UnsupportedOperationException.a @paramprovider paramsand the parameters @exception InvalidAlgorithmParameterException if the given parameters are inappropriate for this signature engine

Class SignatureSpi, void engineUpdate(byte[], int, int)

Updates the data to be signed or verified using the specified array of bytes starting at the specified offset. @param datab the array of bytes. @param off the offset to start from in the array of bytes. @param len the number of bytes to use starting at offset. @exception SignatureException if the engine is not initialized properly.

Class SignedObject

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-1. The algorithm is specified using the same convention as that for signatures. The DSA algorithm using the SHA-1 message digest algorithm can be specified for example as "SHA/DSA" or "SHA-1/DSA" (they are equivalent). In the case of RSA there are multiple choices for the message digest algorithm so the signing algorithm could be specified as for example "MD2/RSA" "MD5/RSA" or "SHA-1/RSA". 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:

@see Signature @version 1.37 0238 12/0203/0001 @author Li Gong

Class Signer

This class is used to represent an Identity that can also digitally sign data.

The management of a signer's private keys is an important and sensitive issue that should be handled by subclasses as appropriate to their intended use. @see Identity @version 1.37 0038 01/0212/0203 @author Benjamin Renaud @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.


Class UnrecoverableKeyException

This exception is thrown if a key in the keystore cannot be recovered. @version 1.6 027 12/0203/0001 @since 1.2

Class UnresolvedPermission

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. This new object replaces the UnresolvedPermission which is removed. @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.security.Policy @version 1.17 0021 01/0212/0203 @author Roland Schemers