|
Generated by JDiff |
||||||||
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES |
This file contains all the changes in documentation in the packagejava.security
as colored differences. Deletions are shownlike 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.
Create a newAccessControlContext
with the givenAccessControlContext
andDomainCombiner
. This constructor associates the providedDomainCombiner
with the providedAccessControlContext
.@param acc the
AccessControlContext
associated with the providedDomainCombiner
.@param combiner the
DomainCombiner
to be associated with the providedAccessControlContext
. @exception NullPointerException ifeitherthe providedcontext
or the provided combiner areisnull
.@exception SecurityException if the caller does not have permission to invoke this constructor.
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, Object doPrivileged(PrivilegedExceptionAction)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 thecheckPermission
method. ThecheckPermission
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 adoPrivileged
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 andcheckPermission
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 therun
method is supplied. When the call todoPrivileged
is made an instance of the PrivilegedAction implementation is passed to it. ThedoPrivileged
method calls therun
method from the PrivilegedAction implementation after enabling privileges and returns therun
method's return value as thedoPrivileged
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 thethrows
clause of a method) then you need to use thePrivilegedExceptionAction
interface instead of thePrivilegedAction
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. ThegetContext
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@see AccessControlContext @version 1.fromwithin this //pointrun methodforwardwill requireboththat thecurrent context andintersection of the // callers protection domain and the snapshot'scontext//tocontext have the desired permission. } } acc); ...normal code here... }47510001/0212/0203 @author Li Gong @author Roland Schemers
Performs the specifiedClass AccessController, Object doPrivileged(PrivilegedExceptionAction, AccessControlContext)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'srun
method.@throwsPrivilgedActionExceptionPrivilegedActionException if the specified action'srun
method threw a checked exception.@see #doPrivileged(PrivilegedExceptionAction AccessControlContextPrivilegedAction) @see #doPrivileged(PrivilegedActionPrivilegedExceptionAction AccessControlContext)
Performs the specifiedPrivilegedExceptionAction
with privileges enabled and restricted by the specifiedAccessControlContext
. 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 specifiedAccessControlContext
.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'srun
method.@throws PrivilegedActionException if the specified action'srun
method threw a checked exception.@see #doPrivileged(PrivilegedAction) @see #doPrivileged(PrivilegedExceptionAction AccessControlContext)
TheAlgorithmParameterGenerator
class is used to generate a set of parameters to be used with a certain algorithm. Parameter generators are constructed using thegetInstance
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. @author Jan Luehe @version 1.36 0238 12/0203/0001 @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @since 1.2
This class defines the Service Provider Interface (SPI) for theAlgorithmParameterGenerator
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
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 thegetInstance
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.
- If just an algorithm name is specified the system will determine if there is an AlgorithmParameters implementation for the algorithm requested available in the environment and if there is more than one if there is a preferred one.
- If both an algorithm name and a package provider are specified the system will determine if there is an implementation in the package requested and throw an exception if there is not.
Once an
AlgorithmParameters
object is returned it must be initialized via a call toinit
using an appropriate parameter specification or parameter encoding.A transparent parameter specification is obtained from an
AlgorithmParameters
object via a call togetParameterSpec
and a byte encoding of the parameters is obtained via a call togetEncoded
. @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
This class defines the Service Provider Interface (SPI) for theAlgorithmParameters
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
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
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.Class BasicPermission, constructor BasicPermission(String)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 "."ormaybyappearitselfat 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
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 ifname
isnull
. @throws IllegalArgumentException ifname
is empty.
Class Certificate, String toString(boolean)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
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, boolean implies(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
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.
- codesource must not be null.
- If this object's certificates are not null then all of this object's certificates must be present in codesource's certificates.
- If this object's location (getLocation()) is not null then the following checks are made against this object's location and codesource's:
- codesource's location must not be null.
- If this object's location equals codesource's location then return true.
- This object's protocol (getLocation().getProtocol()) must be equal to codesource's protocol.
- 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.
- 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.
- 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.
- 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.jarNote 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.
This is the generic Message Digest exception. @version 1.12 0013 01/0212/0203 @author Benjamin Renaud
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
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
AClass DomainCombiner, ProtectionDomain[] combine(ProtectionDomain[], ProtectionDomain[])DomainCombiner
provides a means to dynamically update the ProtectionDomains associated with the currentAccessControlContext
.A
DomainCombiner
is passed as a parameter to the appropriate constructor forAccessControlContext
. The newly constructed context is then passed to theAccessController.doPrivileged(... context)
method to bind the provided context (and associatedDomainCombiner
) with the current execution Thread. Subsequent calls toAccessController.getContext
orAccessController.checkPermission
cause theDomainCombiner.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 toAccessController.doPrivileged
.getIfpassedno call to doPrivileged was made then the first argumentinwill contain all the ProtectionDomains from the current execution Thread. The second argument represents an array.If no callof inherited ProtectionDomainstowhich may be.
doPrivilegednullwas made then all theProtectionDomains may be inherited fromProtectionDomainsa parent Thread or fromthe currenta privilegedexecutioncontext.Thread get passedIf no call to doPrivileged was made then thefirstsecond argument.Thewill contain the ProtectionDomains inherited from the parent Thread.getIfpassedone or more calls tothe second argument unlessdoPrivileged were made andathe most recent call was to doPrivileged(...action context)hadthenoccurred.theIn thatsecond argumentcasewill contain the ProtectionDomains from the privileged contextare. Ifpassedthe most recent call was to doPrivileged(action) then there is no privileged context and the second argument will benull
.The
combine
method investigates the two input arrays of ProtectionDomains and returns a single array containing the updated ProtectionDomains. In the simplest case thecombine
method merges the two stacks into one. In more complex cases thecombine
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 thecombine
method bases its updates on the information encapsulated in theDomainCombiner
.After the
AccessController.getContext
method receives the combined stack of ProtectionDomains back from theDomainCombiner
it returns a new AccessControlContext that has both the combined ProtectionDomains as well as theDomainCombiner
. @see AccessController @see AccessControlContext @version 1.3 025 12/0203/0001
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 executingProtectionDomain
residing at the beginning of the array. This parameter may benull
if the current execution Thread has no associated ProtectionDomains.@param assignedDomains
thean array of inherited ProtectionDomains. ProtectionDomains may be inherited fromthea parent Thread orthe ProtectionDomainsfromthe privileged context ifacall toprivilegedAccessController.doPrivileged(..AccessControlContext
.context) had occurredThis parameter may benull
if therewereare noProtectionDomainsinheritedfrom the parent Thread or from the privileged contextProtectionDomains. @return a new array consisting of the updated ProtectionDomains ornull
.
This is the general security exception class which serves to group all the exception classes of thejava.security
package that extend from it.(ExceptionsThe exceptions to this grouping are:
AccessControlException and
@version 1.CertificateExceptionRMISecurityException which subclassfromjava.lang.SecurityExceptionand- ProviderException
andwhich subclasses java.lang.RuntimeException InvalidParameterException whichsubclass fromsubclasses java.lang.RuntimeException.)IllegalArgumentException9 0011 01/0212/0203 @author Jan Luehe
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 singleobject
argument.checkGuard
is invoked (by the GuardedObjectgetObject
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
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 thecheckGuard
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, PublicKey getPublicKey()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 byjava.security.KeyStore
thejava.security.cert
package andjava.security.Principal
.
Returns this identity's public key. @return the public key for this identity. @see #setPublicKeyClass 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 itscheckSecurityAccess
method doesn't allow setting the public key. @see #getPublicKey @see SecurityManager#checkSecurityAccess
Class IdentityScope, IdentityScope getSystemScope()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 byjava.security.KeyStore
thejava.security.cert
package andjava.security.Principal
.
Returns the system's identity scope. @return the system's identity scope. @see #setSystemScopeClass 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 itscheckSecurityAccess
method doesn't allow setting the identity scope. @see #getSystemScope @see SecurityManager#checkSecurityAccess
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
This is the exception for invalid Keys (invalid encoding wrong length uninitialized etc). @version 1.11 0212 12/0203/0001 @author Benjamin Renaud
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
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.
- 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 typeSubjectPublicKeyInfo
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 2459: 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.
47 0051 01/0212/0203 @author Benjamin Renaud
This is the basic key exception. @see Key @see InvalidKeyException @see KeyManagementException @version 1.14 0015 01/0212/0203 @author Benjamin Renaud
Key factories are used to convert keys (opaque cryptographic keys of typeKey
) 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
orX509EncodedKeySpec
. 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
This class defines the Service Provider Interface (SPI) for theKeyFactory
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
orX509EncodedKeySpec
. 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
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.
KeyIDConflictKeyIDConflictException- KeyAuthorizationFailureException
- ExpiredKeyException
11140001/0212/0203 @author Benjamin Renaud @see Key @see KeyException
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
The KeyPairGenerator class is used to generate pairs of public and private keys. Key pair generators are constructed using thegetInstance
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 java.security.SecureRandom 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 theSecureRandom
implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation ofSecureRandom
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
andg
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 aSecureRandom
argument while the the other uses theSecureRandom
implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation ofSecureRandom
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 thisKeyPairGenerator
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
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
This class represents an in-memory collection of keys and certificates. It manages two types of entries:
- Key Entry
This type of keystore entry holds very sensitive cryptographic key information which is stored in a protected format to prevent unauthorized access.
Typically a key stored in this type of entry is a secret key or a private key accompanied by the 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.
- Trusted Certificate Entry
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 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.
- If just a keystore type is specified:
KeyStore ks = KeyStore.getInstance("JKS");the system will determine if there is an implementation of the keystore type requested available in the environment and if there is more than one if there is a preferred one.
- If both a keystore type and a package provider are specified:
KeyStore ks = KeyStore.getInstance("JKS" "SUN");the system will determine if there is an implementation of the keystore type in the package requested and throw an exception if there is not.Before a keystore can be accessed it must be char[] loaded}. In order to create an empty keystore you pass
null
as theInputStream
argument to theload
method. @author Jan Luehe @version 1.29 0231 12/0203/0001 @see java.security.PrivateKey @see java.security.cert.Certificate @since 1.2
This is the generic KeyStore exception. @author Jan Luehe @version 1.7 028 12/0203/0001 @since 1.2
This class defines the Service Provider Interface (SPI) for theKeyStore
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
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. Afterdigest
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 thisMessageDigest
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
This class defines the Service Provider Interface (SPI) for theMessageDigest
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
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
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
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 asjava.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
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 thePermissionCollection.implies
method is called. If a non-null value is returned that PermissionCollection must be used. If null is returned then the caller ofnewPermissionCollection
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. Itsadd
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. IfnewPermissionCollection
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
This class represents a heterogeneous collection of Permissions. That is it contains different types of Permission objects organized into PermissionCollections. For example if anyjava.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 thenewPermissionCollection
method in the FilePermission class. Similarly anyjava.lang.RuntimePermission
objects are stored in the PermissionCollection returned by a call to thenewPermissionCollection
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 thenewPermissionCollection
method is called on that class to create the PermissionCollection and add it to the Permissions object. IfnewPermissionCollection
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
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.Class Policy, PermissionCollection getPermissions(CodeSource)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. Thesource 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 thesetPolicy
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 classesloaded fromin agiven CodeSourceparticular ProtectionDomain. This is dependent on theProtectionDomainPolicycachingprovider'sstrategyimplementation of theClassLoader.PermissionForimplies}example themethod andSecureClassLoaderthecaches 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
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.TheClass Policy, Policy getPolicy()@exceptionreturnedjava.lang.SecurityExceptionsetif the current thread does not have permission to callof permissions must be a new mutable instance and itgetPermissionsmuston the policy objectsupport heterogeneous Permission types.
Returns the installed Policy object. This value should not be cached as it may be changed by a call toClass Policy, void refresh()setPolicy
. This method first callsSecurityManager.checkPermission
with aSecurityPermission("getPolicy")
permission to ensure it's ok to get the Policy object.. @return the installed Policy. @throws SecurityException if a security manager exists and itscheckPermission
method doesn't allow getting the Policy object. @see SecurityManager#checkPermission(SecurityPermissionPermission) @see #setPolicy(java.security.Policy)
Refreshes/reloads the policy configuration. The behavior of this method depends on the implementation. For example callingClass Policy, void setPolicy(Policy)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.
Sets the system-wide Policy object. This method first callsSecurityManager.checkPermission
with aSecurityPermission("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 itscheckPermission
method doesn't allow setting the Policy. @see SecurityManager#checkPermission(SecurityPermissionPermission) @see #getPolicy()
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
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
This exception is thrown byClass PrivilegedActionException, Exception getException()doPrivileged(PrivilegedExceptionAction)
anddoPrivileged(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 thegetException
method. In effect anPrivilegedActionException
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)
Returns the exception thrown by the privileged computation that resulted in thisPrivilegedActionException
.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, constructor ProtectionDomain(CodeSource, PermissionCollection)This ProtectionDomain class
encapulatesencapsulates the characteristics of a domain which encloses a set of classes whose instances are grantedthe samea set of permissions.Inwhenaddition to a setbeing executed on behalf ofpermissionsadomain isgivencomprisedset ofa CodeSourcePrincipals.which is aA static set of
PublicKeyspermissionstogether with a codebasecan be bound to(inathe form of aProtectionDomain when it isURL).constructed;Thussuchclassespermissions aresigned bygranted to thesame keysdomainand fromregardless of thesamePolicyURLinareforce.placed in the sameHowever to support dynamicdomain.securityClasses that have the same permissions but are from different code sources belongpolicies a ProtectionDomain can also be constructed such that it is dynamically mapped todifferentadomains.setAof permissionsclassby thebelongs 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
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.2Class ProtectionDomain, PermissionCollection getPermissions()
Returns the static permissionsClass ProtectionDomain, boolean implies(Permission)ofgranted to this domain. @return thepermissionsstatic set of permissions for this domain which may be null. @see Policy#refresh @see Policy#getPermissions(ProtectionDomain)
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 permissionimplicitinto this ProtectionDomainfalse if not.
This class represents a "provider" for the Java Security API where a provider implements some or all parts of Java Security. Services that aincludingprovider 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. @version 1.
48 0250 12/0203/0001 @author Benjamin Renaud
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
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
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.Class SecureClassLoader, Class defineClass(String, byte[], int, int, CodeSource)73 0281 12/0203/0001 @author Li Gong @author Roland Schemers
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.Class SecureClassLoader, PermissionCollection getPermissions(CodeSource)If a non-null CodeSource is supplied
andaPolicy provider is installed Policy.getPermissions()ProtectionDomain isinvoked in order to associateconstructeda 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 positionsoff
throughoff+len-1
should have the format of a valid class file as defined by the Java Virtual Machine Specification. @param off the start offset inb
of the classbytesdata @param len the length of the classbytesdata @param cs the associated CodeSource ornull
if none @return theClass
object created from the data and optional CodeSource. @exception ClassFormatError if the data did not contain a valid class @exception IndexOutOfBoundsException if eitheroff
orlen
is negative or ifoff+len
is greater thanb.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.".
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, byte[] getSeed(int)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.
- If just an algorithm name is specified as in:
SecureRandom random = SecureRandom.getInstance("SHA1PRNG");the system will determine if there is an implementation of the algorithm requested available in the environment and if there is more than one if there is a preferred one.
- If both an algorithm name and a package provider are specified as in:
SecureRandom random = SecureRandom.getInstance("SHA1PRNG" "SUN");the system will determine if there is an implementation of the algorithm in the package requested and throw an exception if there is not.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 thesetSeed
method:SecureRandom random = SecureRandom.getInstance("SHA1PRNG"); random.setSeed(seed);After the caller obtains the SecureRandom object from the
getInstance
call it can callnextBytes
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
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.Class SecureRandom, void setSeed(byte[])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 thegenerateSeed
method to obtain seed bytes from that object. @param numBytes the number of seed bytes to generate. @return the seed bytes. @see #setSeed
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 #getSeedClass SecureRandom, void setSeed(long)
Reseeds this random object using the eight bytes contained in the givenlong 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
This class defines the Service Provider Interface (SPI) for theSecureRandom
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, String getProperty(String)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
Gets a security property value.Class Security, Provider getProvider(String)First if there is a security manager its
checkPermission
method is called with ajava.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
Returns the provider installed with the specified name if any. Returns null if no provider with theClass Security, void setProperty(String, String)speicifiedspecified name is installed. @param name the name of the provider to get. @return the provider of the specified name. @see #removeProvider @see #addProvider
Sets a security property value.First if there is a security manager its
checkPermission
method is called with ajava.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
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.
@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.
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. 21 0022 01/0212/0203 @author Marianne Mueller @author Roland Schemers
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.Class Signature, Object getParameter(String)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.
- If just an algorithm name is specified the system will determine if there is an implementation of the algorithm requested available in the environment and if there is more than one if there is a preferred one.
- If both an algorithm name and a package provider are specified the system will determine if there is an implementation of the algorithm in the package requested and throw an exception if there is not.
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 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 thisSignature
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
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 #getParametersClass 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
This is the generic Signature exception. @version 1.11 0212 12/0203/0001 @author Benjamin Renaud
This class defines the Service Provider Interface (SPI) for theClass SignatureSpi, void engineSetParameter(AlgorithmParameterSpec)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 engineUpdate(byte[], int, int)InitializesThis method is overridden by providers to initialize this signature engine with the specified parameter set.
This@paramconcrete method hasparams the parametersbeen@exceptionadded toUnsupportedOperationException if thispreviously-defined abstract class. (For backwards compatibility it cannot be abstract.) Itmethodmay beis not overridden by a providerto set the algorithm parameters using the specified params. Such an override is expected to throw an@exception InvalidAlgorithmParameterException ifa parameter is invalid. Ifthis method isnotoverriddenit always throws anbyUnsupportedOperationException.a@paramproviderparamsand theparameters @exception InvalidAlgorithmParameterException ifthe given parameters are inappropriate for this signature engine
Updates the data to be signed or verified using the specified array of bytes starting at the specified offset. @paramdatab 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.
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 whatSignature
engine is being used as its own implementation of theverify
method is invoked to verify a signature. In other words a maliciousSignature
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.
- 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.
37 0238 12/0203/0001 @author Li Gong
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 byjava.security.KeyStore
thejava.security.cert
package andjava.security.Principal
.
This exception is thrown if a key in the keystore cannot be recovered. @version 1.6 027 12/0203/0001 @since 1.2
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