Generated by
JDiff

java.security Documentation Differences

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

Class AccessControlContext, void checkPermission(Permission)

Determines whether the access request indicated by the specified permission should be allowed or denied based on the security policy currently in effect and the context in this object.

This method quietly returns if the access request is permitted or throws a suitable AccessControlException otherwise. @param perm the requested permission. @exception AccessControlException if the specified permission is not permitted based on the current security policy and the context encapsulated by this object. @exception NullPointerException if the permission to check for is null.


Class AccessControlException

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

The reason to deny access can vary. For example the requested permission might be of an incorrect type contain an invalid value or request access that is not allowed according to the security policy. Such information should be given whenever possible at the time the exception is thrown. @version 1.7 099 02/2102/9800 @author Li Gong @author Roland Schemers


Class AccessController

The AccessController class is used for three purposes:

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

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

If a requested access is allowed checkPermission returns quietly. If denied an AccessControlException is thrown. AccessControlException can also be thrown if the requested permission is of an incorrect type or contains an invalid value. Such information is given whenever possible. Suppose the current thread traversed m callers in the order of caller 1 to caller 2 to caller m. Then caller m invoked the checkPermission method. The checkPermission method determines whether access is granted or denied based on the following algorithm:

 i = m; while (i > 0) { if (caller i's domain does not have the permission) throw AccessControlException else if (caller i is marked as privileged) { if (a context was specified in the call to doPrivileged) context.checkPermission(permission) return; } i = i - 1; }; // Next check the context inherited when // the thread was created. Whenever a new thread is created the // AccessControlContext at that time is // stored and associated with the new thread as the "inherited" // context. inheritedContext.checkPermission(permission); 

A caller can be marked as being "privileged" (see doPrivileged and below). When making access control decisions the checkPermission method stops checking if it reaches a caller that was marked as "privileged" via a doPrivileged call without a context argument (see below for information about a context argument). If that caller's domain has the specified permission no further checking is done and checkPermission returns quietly indicating that the requested access is allowed. If that domain does not have the specified permission an exception is thrown as usual.

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

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

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

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

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

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

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

Be *very* careful in your use of the "privileged" construct and always remember to make the privileged code section as small as possible.

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

 AccessControlContext acc = AccessController.getContext() 

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

 acc.checkPermission(permission) 

There are also times where you don't know a priori which permissions to check the context against. In these cases you can use the doPrivileged method that takes a context:

 somemethod() { AccessController.doPrivileged(new PrivilegedAction() { public Object run() { // Code goes here. Any permission checks from this // point forward require both the current context and // the snapshot's context to have the desired permission. } } acc); ...normal code here... } 
@see AccessControlContext @version 1.45 9847 00/0902/1102 @author Li Gong @author Roland Schemers

Class AlgorithmParameterGenerator

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

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

In case the client does not explicitly initialize the AlgorithmParameterGenerator (via a call to an init method) each provider must supply (and document) a default initialization. For example the Sun provider uses a default modulus prime size of 1024 bits for the generation of DSA parameters. @author Jan Luehe @version 1.31 9836 02/1202/0300 @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @since JDK11.2

Class AlgorithmParameterGenerator, constructor AlgorithmParameterGenerator(AlgorithmParameterGeneratorSpi, Provider, String)

Creates an AlgorithmParameterGenerator object. @param keyFacSpiparamGenSpi the delegate @param provider the provider @param algorithm the algorithm
Class AlgorithmParameterGenerator, void init(AlgorithmParameterSpec)

Initializes this parameter generator with a set of algorithm-specific parameter generation values. To generate the parameters the SecureRandom implementation of the highest-priority installed provider is used as the source of randomness. (If none of the installed providers supply an implementation of SecureRandom a system-provided source of randomness is used.) @param paramsgenParamSpec the set of algorithm-specific parameter generation values. @exception InvalidAlgorithmParameterException if the given parameter generation values are inappropriate for this parameter generator.
Class AlgorithmParameterGenerator, void init(AlgorithmParameterSpec, SecureRandom)

Initializes this parameter generator with a set of algorithm-specific parameter generation values. @param paramsgenParamSpec the set of algorithm-specific parameter generation values. @param random the source of randomness. @exception InvalidAlgorithmParameterException if the given parameter generation values are inappropriate for this parameter generator.

Class AlgorithmParameterGeneratorSpi

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

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

In case the client does not explicitly initialize the AlgorithmParameterGenerator (via a call to an engineInit method) each provider must supply (and document) a default initialization. For example the Sun provider uses a default modulus prime size of 1024 bits for the generation of DSA parameters. @author Jan Luehe @version 1.6 9811 02/1202/0300 @see AlgorithmParameterGenerator @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @since JDK11.2

Class AlgorithmParameterGeneratorSpi, void engineInit(AlgorithmParameterSpec, SecureRandom)

Initializes this parameter generator with a set of algorithm-specific parameter generation values. @param paramsgenParamSpec the set of algorithm-specific parameter generation values. @param random the source of randomness. @exception InvalidAlgorithmParameterException if the given parameter generation values are inappropriate for this parameter generator.

Class AlgorithmParameters

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

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

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

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

A transparent parameter specification is obtained from an AlgorithmParameters object via a call to getParameterSpec and a byte encoding of the parameters is obtained via a call to getEncoded. @author Jan Luehe @version 1.14 9819 02/1202/0300 @see java.security.spec.AlgorithmParameterSpec @see java.security.spec.DSAParameterSpec @see KeyPairGenerator @since JDK11.2

Class AlgorithmParameters, constructor AlgorithmParameters(AlgorithmParametersSpi, Provider, String)

Creates an AlgorithmParameters object. @param keyFacSpiparamSpi the delegate @param provider the provider @param algorithm the algorithm

Class AlgorithmParametersSpi

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

All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply parameter management for a particular algorithm. @author Jan Luehe @version 1.4 988 02/1202/0300 @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @see java.security.spec.DSAParameterSpec @since JDK11.2


Class AllPermission

The AllPermission is a permission that implies all other permissions.

Note: Granting AllPermission should be done with extreme care as it implies all other permissions. Thus it grants code the ability to run with security disabled. Extreme caution should be taken before granting such a permission to code. This permission should be used only during testing or in extremely rare cases where an application or applet is completely trusted and adding the necessary permissions to the policy is prohibitively cumbersome. @see java.security.Permission @see java.security.AccessController @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.5 9814 00/1202/0317 @author Roland Schemers @serial exclude


Class BasicPermission

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

The name for a BasicPermission is the name of the given permission (for example "exit" "setFactory" "print.queueJob" etc). The naming convention follows the hierarchical property naming convention. An asterisk may appear at the end of the name following a "." or by itself to signify a wildcard match. For example: "java.*" or "*" is valid "*java" or "a*b" is 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.18 9826 00/1202/1102 @author Marianne Mueller @author Roland Schemers @serial exclude

Class BasicPermission, constructor BasicPermission(String)

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

Creates a new BasicPermission object with the specified name. The name is the symbolic name of the BasicPermission and the actions String is currently unused. This constructor exists for use by the Policy object to instantiate new Permission objects. @param name the name of the BasicPermission. @param actions ignored. @throws NullPointerException if name is null. @throws IllegalArgumentException if name is empty.

Class Certificate

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

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

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


Class 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.26 0928 02/1502/9800 @author Li Gong @author Roland Schemers


Class DigestException

This is the generic Message Digest exception. @version 1.10 9812 00/1202/0302 @author Benjamin Renaud

Class DigestInputStream

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

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

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

Note that digest objects can compute only one digest (see s that in order to compute intermediate digests a caller should retain a handle onto the digest object and clone it for each digest to be computed leaving the orginal digest untouched. @see MessageDigest @see DigestOutputStream @version 1.30 9834 00/1202/0302 @author Benjamin Renaud

Class DigestInputStream, MessageDigest getMessageDigest()

Returns the message digest associated with this stream. @return the message digest associated with this stream. @see #setMessageDigest(java.security.MessageDigest)
Class DigestInputStream, int read()

Reads a byte and updates the message digest (if the digest function is on). That is this method reads a byte from the input stream blocking until the byte is actually read. If the digest function is on (see on this method will then call update on the message digest associated with this stream passing it the byte read. @return the byte read. @exception IOException if an I/O error occurs. @see MessageDigest#update(byte)
Class DigestInputStream, int read(byte[], int, int)

Reads into a byte array and updates the message digest (if the digest function is on). That is this method reads up to len bytes from the input stream into the array b starting at offset off. This method blocks until the data is actually read. If the digest function is on (see on this method will then call update on the message digest associated with this stream passing it the data. @param b the array into which the data is read. @param off the starting offset into b of where the data should be placed. @param len the maximum number of bytes to be read from the input stream into b starting at offset off. @return the actual number of bytes read. This is less than len if the end of the stream is reached prior to reading len bytes. -1 is returned if no bytes were read because the end of the stream had already been reached when the call was made. @exception IOException if an I/O error occurs. @see MessageDigest#update(byte[] int int)
Class DigestInputStream, void setMessageDigest(MessageDigest)

Associates the specified message digest with this stream. @param digest the message digest to be associated with this stream. @see #getMessageDigest()

Class DigestOutputStream

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

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

It is possible to turn this stream on or off (see on}) When it is on a call to one of the write methods results in an update on the message digest. But when it is off the message digest is not updated. The default is for the stream to be on. @see MessageDigest @see DigestInputStream @version 1.24 9828 00/1202/0302 @author Benjamin Renaud

Class DigestOutputStream, MessageDigest getMessageDigest()

Returns the message digest associated with this stream. @return the message digest associated with this stream. @see #setMessageDigest(java.security.MessageDigest)
Class DigestOutputStream, void setMessageDigest(MessageDigest)

Associates the specified message digest with this stream. @param digest the message digest to be associated with this stream. @see #getMessageDigest()
Class DigestOutputStream, void write(byte[], int, int)

Updates the message digest (if the digest function is on) using the specified subarray and in any case writes the subarray to the output stream. That is if the digest function is on (see on this method calls update on the message digest associated with this stream passing it the subarray specifications. This method then writes the subarray bytes to the output stream blocking until the bytes are actually written. @param b the array containing the subarray to be used for updating and writing to the output stream. @param off the offset into b of the first byte to be updated and written. @param len the number of bytes of data to be updated and written from b starting at offset off. @exception IOException if an I/O error occurs. @see MessageDigest#update(byte[] int int)
Class DigestOutputStream, void write(int)

Updates the message digest (if the digest function is on) using the specified byte and in any case writes the byte to the output stream. That is if the digest function is on (see on this method calls update on the message digest associated with this stream passing it the byte b. This method then writes the byte to the output stream blocking until the byte is actually written. @param b the byte to be used for updating and writing to the output stream. @exception IOException if an I/O error occurs. @see MessageDigest#update(byte)

Class GeneralSecurityException

This is the general security exception class which serves to group all the exception classes of the java.security package that extend from it. (Exceptions are AccessControlException and CertificateException which subclass from java.lang.SecurityException and ProviderException and InvalidParameterException which subclass from java.lang.RuntimeException.) @version 1.7 989 00/1202/0302 @author Jan Luehe

Class Guard

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

This interface contains a single method checkGuard with a single object argument. checkGuard is invoked (by the GuardedObject getObject method) to determine whether or not to allow access to the object. @see GuardedObject @version 1.7 989 00/1202/0302 @author Roland Schemers @author Li Gong


Class GuardedObject

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

A GuardedObject encapsulates a target object and a Guard object such that access to the target object is possible only if the Guard object allows it. Once an object is encapsulated by a GuardedObject access to that object is controlled by the getObject method which invokes the checkGuard method on the Guard object that is guarding access. If access is not allowed an exception is thrown. @see Guard @see Permission @version 1.9 9811 00/1202/0302 @author Roland Schemers @author Li Gong


Class Identity

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

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

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

An Identity can be subclassed to include postal and email addresses telephone numbers images of faces and logos and so on. @see IdentityScope @see Signer @see Principal @version 1.5156 @author Benjamin Renaud @deprecated This class is no longer used. Its functionality has been replaced by java.security.KeyStore the java.security.cert package and java.security.Principal.


Class IdentityScope

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.44 9846 00/1202/0302 @author Benjamin Renaud @deprecated This class is no longer used. Its functionality has been replaced by java.security.KeyStore the java.security.cert package and java.security.Principal.


Class InvalidAlgorithmParameterException

This is the exception for invalid or inappropriate algorithm parameters. @author Jan Luehe @version 1.5 099 02/2102/9800 @see AlgorithmParameters @see java.security.spec.AlgorithmParameterSpec @since JDK11.2

Class InvalidKeyException

This is the exception for invalid Keys (invalid encoding wrong length uninitialized etc). @version 1.6 0811 02/0102/9600 @author Benjamin Renaud

Class InvalidParameterException

This exception is thrown when an invalid parameter is passed to a method. @author Benjamin Renaud @version 1.13 9815 00/1202/0302

Class Key

The Key interface is the top-level interface for all keys. It defines the functionality shared by all key objects. All keys have three characteristics: Keys are generally obtained through key generators certificates or various Identity classes used to manage keys. Keys may also be obtained from key specifications (transparent representations of the underlying key material) through the use of a key factory (see @se PublicKey @see PrivateKey @see KeyPair @see KeyPairGenerator @see KeyFactory @see java.security.spec.KeySpec @see Identity @see Signer @version 1.4347 9800/1202/0302 @author Benjamin Renaud

Class KeyException

This is the basic key exception. @see Key @see InvalidKeyException @see KeyManagementException @version 1.12 9814 00/1202/0302 @author Benjamin Renaud

Class KeyFactory

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

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

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

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

 X509EncodedKeySpec bobPubKeySpec = new X509EncodedKeySpec(bobEncodedPubKey); KeyFactory keyFactory = KeyFactory.getInstance("DSA"); PublicKey bobPubKey = keyFactory.generatePublic(bobPubKeySpec); Signature sig = Signature.getInstance("DSA"); sig.initVerify(bobPubKey); sig.update(data); sig.verify(signature); 
@author Jan Luehe @version 1.19 9824 02/1202/0300 @see Key @see PublicKey @see PrivateKey @see java.security.spec.KeySpec @see java.security.spec.DSAPublicKeySpec @see java.security.spec.X509EncodedKeySpec @since JDK11.2
Class KeyFactory, constructor KeyFactory(KeyFactorySpi, Provider, String)

Creates a KeyFactory object. @param keyFacSpi the delegate @param provider the provider @param algorithm the name of the algorithm to associate with this KeyFactory
Class KeyFactory, String getAlgorithm()

ReturnsGets the name of the algorithm associated with this key factoryKeyFactory. @return the name of the algorithm associated with this KeyFactory

Class KeyFactorySpi

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

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

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

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

A provider should document all the key specifications supported by its key factory. @author Jan Luehe @version 1.4 988 02/1202/0300 @see KeyFactory @see Key @see PublicKey @see PrivateKey @see java.security.spec.KeySpec @see java.security.spec.DSAPublicKeySpec @see java.security.spec.X509EncodedKeySpec @since JDK11.2


Class KeyManagementException

This is the general key management exception for all operations dealing with key management. Subclasses could include: @version 1.9 9811 00/1202/0302 @author Benjamin Renaud @see Key @see KeyException

Class KeyPair

This class is a simple holder for a key pair (a public key and a private key). It does not enforce any security and when initialized should be treated like a PrivateKey. @see PublicKey @see PrivateKey @version 1.9 9811 00/1202/0302 @author Benjamin Renaud

Class KeyPairGenerator

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

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

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

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

Note that this class is abstract and extends from KeyPairGeneratorSpi for historical reasons. Application developers should only take notice of the methods defined in this KeyPairGenerator class; all the methods in the superclass are intended for cryptographic service providers who wish to supply their own implementations of key pair generators. @author Benjamin Renaud @version 1.4149 9802/1202/0300 @see java.security.spec.AlgorithmParameterSpec

Class KeyPairGenerator, KeyPair genKeyPair()

Generates a key pair. Unless

If anthis initialization method isKeyPairGenerator called using a KeyPairGenerator interface algorithmhas not been initialized explicitly provider-specific defaults will be used for the size and other (algorithm-specific) values of the generated keys.

This will generate a new key pair every time it is called.

This method is functionally equivalent to generateKeyPair @return the generated key pair @since JDK11.2

Class KeyPairGenerator, KeyPair generateKeyPair()

Generates a key pair. Unless

If anthis initialization method isKeyPairGenerator called using a KeyPairGenerator interface algorithmhas not been initialized explicitly provider-specific defaults will be used for the size and other (algorithm-specific) values of the generated keys.

This will generate a new key pair every time it is called.

This method is functionally equivalent to genKeyPair @return the generated key pair

Class KeyPairGenerator, void initialize(AlgorithmParameterSpec)

Initializes the key pair generator using the specified parameter set and the SecureRandom implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation of SecureRandom a system-provided source of randomness is used.).

This concrete method has been added to this previously-defined abstract class. This method calls the KeyPairGeneratorSpi initialize(java.security.spec.AlgorithmParameterSpe java.security.SecureRandom) initialize} method passing it params and a source of randomness (obtained from the highest-priority installed provider or system-provided if none of the installed providers supply one). That initialize method always throws an UnsupportedOperationException if it is not overridden by the provider. @param params the parameter set used to generate the keys. @exception InvalidAlgorithmParameterException if the given parameters are inappropriate for this key pair generator. @since JDK11.2

Class KeyPairGenerator, void initialize(AlgorithmParameterSpec, SecureRandom)

Initializes the key pair generator with the given parameter set and source of randomness.

This concrete method has been added to this previously-defined abstract class. This method calls the KeyPairGeneratorSpi initialize(java.security.spec.AlgorithmParameterSpe java.security.SecureRandom) initialize} method passing it params and random. That initialize method always throws an UnsupportedOperationException if it is not overridden by the provider. @param params the parameter set used to generate the keys. @param random the source of randomness. @exception InvalidAlgorithmParameterException if the given parameters are inappropriate for this key pair generator. @since JDK11.2

Class KeyPairGenerator, void initialize(int)

Initializes the key pair generator for a certain keysize using a default parameter set and the SecureRandom implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation of SecureRandom a system-provided source of randomness is used.) @param keysize the keysize. This is an algorithm-specific metric such as modulus length specified in number of bits. @exception InvalidParameterException if the keysize is not supported by this KeyPairGenerator object.
Class KeyPairGenerator, void initialize(int, SecureRandom)

Initializes the key pair generator for a certain keysize with the given source of randomness (and a default parameter set). @param keysize the keysize. This is an algorithm-specific metric such as modulus length specified in number of bits. @param random the source of randomness. @exception InvalidParameterException if the keysize is not supported by this KeyPairGenerator object. @since JDK11.2

Class KeyPairGeneratorSpi

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

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

In case the client does not explicitly initialize the KeyPairGenerator (via a call to an initialize method) each provider must supply (and document) a default initialization. For example the Sun provider uses a default modulus size (keysize) of 1024 bits. @author Benjamin Renaud @version 1.5 9811 02/1202/0300 @see KeyPairGenerator @see java.security.spec.AlgorithmParameterSpec

Class KeyPairGeneratorSpi, KeyPair generateKeyPair()

Generates a key pair. Unless an initialization method is called using a KeyPairGenerator interface algorithm-specific defaults will be used. This will generate a new key pair every time it is called. @return the newly generated KeyPair
Class KeyPairGeneratorSpi, void initialize(AlgorithmParameterSpec, SecureRandom)

Initializes the key pair generator using the specified parameter set and user-provided source of randomness.

This concrete method has been added to this previously-defined abstract class. (For backwards compatibility it cannot be abstract.) It may be overridden by a provider to initialize the key pair generator. Such an override is expected to throw an InvalidAlgorithmParameterException if a parameter is inappropriate for this key pair generator. If this method is not overridden it always throws an UnsupportedOperationException. @param params the parameter set used to generate the keys. @param random the source of randomness for this generator. @exception InvalidAlgorithmParameterException if the given parameters are inappropriate for this key pair generator. @since JDK11.2

Class KeyPairGeneratorSpi, void initialize(int, SecureRandom)

Initializes the key pair generator for a certain keysize using the default parameter set. @param keysize the keysize. This is an algorithm-specific metric such as modulus length specified in number of bits. @param random the source of randomness for this generator. @exception InvalidParameterException if the keysize is not supported by this KeyPairGeneratorSpi object.

Class KeyStore

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

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

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

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

Before a keystore can be accessed it must be char[] loaded}. In order to create an empty keystore you pass null as the InputStream argument to the load method. @author Jan Luehe @version 1.2129 0902/0402/9800 @see java.security.PrivateKey @see java.security.cert.Certificate @since JDK11.2

Class KeyStore, String getDefaultType()

Returns the default keystore type as specified in the Java security properties file or the string ""jks"" (acronym for ""Java keystore"") if no such property exists. 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 JDKSDK was installed.

The default keystore type can be used by applications that do not want to use a hard-coded keystore type when calling one of the getInstance methods and want to provide a default keystore type in case a user does not specify its own.

The default keystore type can be changed by setting the value of the "keystore.type" security property (in the Java security properties file) to the desired keystore type. @return the default keystore type as specified in the Java security properties file or the string "jks" if no such property exists.

Class KeyStore, boolean isCertificateEntry(String)

Returns true if the entry identified by the given alias is a trusted certificate entry and false otherwise. @param alias the alias for the keystore entry to be checked @return true if the entry identified by the given alias is a trusted certificate entry false otherwise. @exception KeyStoreException if the keystore has not been initialized (loaded).
Class KeyStore, boolean isKeyEntry(String)

Returns true if the entry identified by the given alias is a key entry and false otherwise. @param alias the alias for the keystore entry to be checked @return true if the entry identified by the given alias is a key entry false otherwise. @exception KeyStoreException if the keystore has not been initialized (loaded).

Class KeyStoreException

This is the generic KeyStore exception. @author Jan Luehe @version 1.3 097 02/2102/9800 @since JDK11.2

Class KeyStoreSpi

This class defines the Service Provider Interface (SPI) for the KeyStore class. All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a keystore for a particular keystore type. @author Jan Luehe @version 1.4 069 02/2902/9800 @see KeyStore @since JDK11.2
Class KeyStoreSpi, boolean engineIsCertificateEntry(String)

Returns true if the entry identified by the given alias is a trusted certificate entry and false otherwise. @param alias the alias for the keystore entry to be checked @return true if the entry identified by the given alias is a trusted certificate entry false otherwise.
Class KeyStoreSpi, boolean engineIsKeyEntry(String)

Returns true if the entry identified by the given alias is a key entry and false otherwise. @param alias the alias for the keystore entry to be checked @return true if the entry identified by the given alias is a key entry false otherwise.

Class MessageDigest

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

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

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

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

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

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

Note that this class is abstract and extends from MessageDigestSpi for historical reasons. Application developers should only take notice of the methods defined in this MessageDigest class; all the methods in the superclass are intended for cryptographic service providers who wish to supply their own implementations of message digest algorithms. @author Benjamin Renaud @version 1.63 9871 02/1202/0300 @see DigestInputStream @see DigestOutputStream

Class MessageDigest, byte[] digest(byte[])

Performs a final update on the digest using the specified array of bytes then completes the digest computation. That is this method first calls update(input) passing the input array to the update method then calls digest() @param input the input to be updated before the digest is completed. @return the array of bytes for the resulting hash value.
Class MessageDigest, String getAlgorithm()

Returns a string that identifies the algorithm independent of implementation details. The name should be a standard Java Security name (such as "SHA" "MD5" and so on). See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names. @return the name of the algorithm
Class MessageDigest, int getDigestLength()

Returns the length of the digest in bytes or 0 if this operation is not supported by the provider and the implementation is not cloneable. @return the digest length in bytes or 0 if this operation is not supported by the provider and the implementation is not cloneable. @since JDK11.2

Class MessageDigestSpi

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

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

Implementations are free to implement the Cloneable interface. @author Benjamin Renaud @version 1.6 9811 02/1202/0300 @see MessageDigest

Class MessageDigestSpi, byte[] engineDigest()

Completes the hash computation by performing final operations such as padding. Once engineDigest has been called the engine should be reset (see engineReset}) Resetting is the responsibility of the engine implementor. @return the array of bytes for the resulting hash value.
Class MessageDigestSpi, int engineDigest(byte[], int, int)

Completes the hash computation by performing final operations such as padding. Once engineDigest has been called the engine should be reset (see engineReset}) Resetting is the responsibility of the engine implementor. This method should be abstract but we leave it concrete for binary compatibility. Knowledgeable providers should override this method. @param buf the output buffer in which to store the digest @param offset offset to start from in the output buffer @param len number of bytes within buf allotted for the digest. Both this default implementation and the SUN provider do not return partial digests. The presence of this parameter is solely for consistency in our API's. If the value of this parameter is less than the actual digest length the method will throw a DigestException. This parameter is ignored if its value is greater than or equal to the actual digest length. @return the length of the digest stored in the output buffer. @exception DigestException if an error occurs. @since JDK11.2
Class MessageDigestSpi, int engineGetDigestLength()

Returns the digest length in bytes.

This concrete method has been added to this previously-defined abstract class. (For backwards compatibility it cannot be abstract.)

The default behavior is to return 0.

This method may be overridden by a provider to return the digest length. @return the digest length in bytes. @since JDK11.2


Class NoSuchAlgorithmException

This exception is thrown when a particular cryptographic algorithm is requested but is not available in the environment. @version 1.18 9820 00/1202/0302 @author Benjamin Renaud

Class NoSuchProviderException

This exception is thrown when a particular security provider is requested but is not available in the environment. @version 1.14 9816 00/1202/0302 @author Benjamin Renaud

Class Permission

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

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

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

Permission objects are similar to String objects in that they are immutable once they have been created. Subclasses should not provide methods that can change the state of a permission once it has been created. @see Permissions @see PermissionCollection @version 1.32 9835 00/1202/0302 @author Marianne Mueller @author Roland Schemers


Class PermissionCollection

Abstract class representing a collection of Permission objects.

With a PermissionCollection you can:

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

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

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

Class PermissionCollection, void add(Permission)

Adds a permission object to the current collection of permission objects. @param permission the Permission object to add. @exception SecurityException - if this PermissionCollection object has been marked readonly
Class PermissionCollection, boolean isReadOnly()

Returns true if this PermissionCollection object is marked as readonly. If it is readonly no new Permission objects can be added to it using addPermissionadd.

By default the object is not readonly. It can be set to readonly by a call to setReadOnly. @return true if this PermissionCollection object is marked as readonly false otherwise.

Class PermissionCollection, void setReadOnly()

Marks this PermissionCollection object as "readonly". After a PermissionCollection object is marked as readonly no new Permission objects can be added to it using addPermissionadd.

Class Permissions

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

When the add method is called to add a Permission the Permission is stored in the appropriate PermissionCollection. If no such collection exists yet the Permission object's class is determined and the newPermissionCollection method is called on that class to create the PermissionCollection and add it to the Permissions object. If newPermissionCollection returns null then a default PermissionCollection that uses a hashtable will be created and used. Each hashtable entry stores a Permission object as both the key and the value. @see Permission @see PermissionCollection @see AllPermission @version 1.39 9846 00/1202/0302 @author Marianne Mueller @author Roland Schemers @serial exclude

Class Permissions, void add(Permission)

Adds a permission object to the PermissionCollection for the class the permission belongs to. For example if permission is a FilePermission it is added to the FilePermissionCollection stored in this Permissions object. This method creates a new PermissionCollection object (and adds the permission to it) if an appropriate collection does not yet exist.

@param permission the Permission object to add. @exception SecurityException if this Permissions object is marked as readonly. @see PermissionCollection#isReadOnly()


Class Policy

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

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

The Policy object is typically consulted by aobjects ProtectionDomainsuch as the byte[ int int CodeSource) SecureClassLoader} when a loader needs to determine the permissions to assign to a particular protection domain. initializes its set ofThe SecureClassLoader executes code permissionssuch as the following to ask the currently installed Policy object to populate a PermissionCollection object:

 policy = Policy.getPolicy(); PermissionCollection perms = policy.getPermissions(MyCodeSource) 

The SecureClassLoader object passes in a CodeSource object which encapsulates the codebase (URL) and public key certificates of the classes being loaded. The Policy object consults its policy specification and returns an appropriate Permissions object enumerating the permissions allowed for code from the specified code source.

The source location for the policy information utilized by the Policy object is up to the Policy implementation. The policy configuration may be stored for example as a flat ASCII file as a serialized binary file of the Policy class or as a database.

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

The refresh method causes the policy object to refresh/reload its current configuration. This is implementation-dependent. For example if the policy object stores its policy in configuration files calling refresh will cause it to re-read the configuration policy files. When a protection domain needs to initialize its set of permissions it executes code such as the following to ask the currently installed Policy object to populate a PermissionCollection object with the appropriate permissions:The refreshed policy = Policy.getPolicy(); PermissionCollection permsmay =not policy.getPermissions(MyCodeSource)have an Theeffect protection domain passes inon classes loaded from a CodeSource object which encapsulates its codebase (URL) and public keygiven attributesCodeSource. TheThis Policy object evaluatesis dependent on the global policy and returns an appropriateProtectionDomain Permissions object specifyingcaching strategy of the permissions allowed forClassLoader. code fromFor example the specifiedSecureClassLoader codecaches sourceprotection domains.

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 JDKSDK was installed. @author Roland Schemers @version 1.5968 0902/2402/9800 @see java.security.CodeSource @see java.security.PermissionCollection @see java.security.SecureClassLoader

Class Policy, Policy getPolicy()

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

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

Class Principal

This interface represents the abstract notion of a principal which can be used to represent any entity such as an individual a corporation and a login id. @see java.security.cert.X509Certificate @version 1.17 9819 00/1202/0302 @author Li Gong

Class PrivateKey

A private key. This interface contains no methods or constants. It merely serves to group (and provide type safety for) all private key interfaces. Note: The specialized private key interfaces extend this interface. See for example the DSAPrivateKey interface in java.security.interfaces. @see Key @see PublicKey @see Certificate @see Signature#initVerify @see java.security.interfaces.DSAPrivateKey @see java.security.interfaces.RSAPrivateKey @see java.security.interfaces.RSAPrivateCrtKey @version 1.23 9825 00/1202/0302 @author Benjamin Renaud @author Josh Bloch


Class PrivilegedActionException, constructor PrivilegedActionException(Exception)

Constructs a new PrivilegedActionException ""wrapping"" the specific Exception. @param exception The exception thrown
Class PrivilegedActionException, String toString()

Returns a short description of this throwable object. If this Throwable object was created with an error message string then the result is the concatenation of three strings: The name of the actual class ofdescribing this objectexception ":including " (a colon and a space) The result of the #getMessage method for this object If this Throwable object was created with no error message string then the namedescription of the actual class of thisexception objectit is returnedwraps. @return a string representation of this ThrowablePrivilegedActionException.

Class ProtectionDomain

This ProtectionDomain class encapulates the characteristics of a domain which encloses a set of classes whose instances are granted the same set of permissions.

In addition to a set of permissions a domain is comprised of a CodeSource which is a set of PublicKeys together with a codebase (in the form of a URL). Thus classes signed by the same keys and from the same URL are placed in the same domain. Classes that have the same permissions but are from different code sources belong to different domains.

A class belongs to one and only one ProtectionDomain. @version 1.24 0526 02/1102/9800 @author Li Gong @author Roland Schemers


Class Provider

This class represents a "provider" for the Java Security API where a provider implements some or all parts of Java Security including:

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 providersa particular type of provider the cryptographic service provider workworks and howis installed. However please note that a provider can be used to installimplement any security service in Java that uses a pluggable architecture with a choice of implementations that fit themunderneath. @version 1.4148 9802/1202/0300 @author Benjamin Renaud

Class Provider, void clear()

Clears this provider so that it no longer contains the properties used to look up facilities implemented by the provider.

First if there is a security manager its checkSecurityAccess method is called with the string "clearProviderProperties."+name (where name is the provider name) to see if it's ok to clear this provider. If the default implementation of checkSecurityAccess is used (that is that method is not overriden) then this results in a call to the security manager's checkPermission method with a SecurityPermission("clearProviderProperties."+name) permission. @throws SecurityException if a security manager exists and its {@link java.lang.SecurityManager#checkSecurityAccess} method denies access to clear this provider @since JDK11.2

Class Provider, Set entrySet()

Returns an unmodifiable Set view of the property entries contained in this Provider. @see java.util.Map.Entry @since JDK11.2
Class Provider, Set keySet()

Returns an unmodifiable Set view of the property keys contained in this provider. @since JDK11.2
Class Provider, void load(InputStream)

Reads a property list (key and element pairs) from the input stream. @param ininStream the input stream. @exception IOException if an error occurred when reading from the input stream. @see java.util.Properties#load
Class Provider, Object put(Object, Object)

Sets the key property to have the specified value.

First if there is a security manager its checkSecurityAccess method is called with the string "putProviderProperty."+name where name is the provider name to see if it's ok to set this provider's property values. If the default implementation of checkSecurityAccess is used (that is that method is not overriden) then this results in a call to the security manager's checkPermission method with a SecurityPermission("putProviderProperty."+name) permission. @param key the property key. @param value the property value. @return the previous value of the specified property (key) or null if it did not have one. @throws SecurityException if a security manager exists and its {@link java.lang.SecurityManager#checkSecurityAccess} method denies access to set property values. @since JDK11.2

Class Provider, void putAll(Map)

Copies all of the mappings from the specified Map to this provider. These mappings will replace any properties that this provider had for any of the keys currently in the specified Map. @since JDK11.2
Class Provider, Object remove(Object)

Removes the key property (and its corresponding value).

First if there is a security manager its checkSecurityAccess method is called with the string ""removeProviderProperty."+name where name is the provider name to see if it's ok to remove this provider's properties. If the default implementation of checkSecurityAccess is used (that is that method is not overriden) then this results in a call to the security manager's checkPermission method with a SecurityPermission("removeProviderProperty."+name) permission. @param key the key for the property to be removed. @return the value to which the key had been mapped or null if the key did not have a mapping. @throws SecurityException if a security manager exists and its {@link java.lang.SecurityManager#checkSecurityAccess} method denies access to remove this provider's properties. @since JDK11.2


Class ProviderException

A runtime exception for Provider exceptions (such as misconfiguration errors) which may be subclassed by Providers to throw specialized provider-specific runtime errors. @version 1.8 9810 00/1202/0302 @author Benjamin Renaud

Class PublicKey

A public key. This interface contains no methods or constants. It merely serves to group (and provide type safety for) all public key interfaces. Note: The specialized public key interfaces extend this interface. See for example the DSAPublicKey interface in java.security.interfaces. @see Key @see PrivateKey @see Certificate @see Signature#initVerify @see java.security.interfaces.DSAPublicKey @see java.security.interfaces.RSAPublicKey @version 1.26 9828 00/1202/0302


Class SecureClassLoader

This class extends ClassLoader with additional support for defining classes with an associated code source and permissions which are retrieved by the system policy by default. @version 1.71 0373 02/0802/00 @author Li Gong @author Roland Schemers
Class SecureClassLoader, constructor SecureClassLoader(ClassLoader)

Creates a new SecureClassLoader using the specified parent class loader for delegation.

If there is a security manager this method first calls the security manager's checkCreateClassLoader method to ensure creation of a class loader is allowed.

@param parent the parent ClassLoader @exception SecurityException if a security manager exists and its checkCreateClassLoader method doesn't allow creation of a class loader. @see SecurityManager#checkCreateClassLoader

Class SecureClassLoader, Class defineClass(String, byte[], int, int, CodeSource)

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

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

@param name the name of the class @param b the class bytes @param off the start offset of the class bytes @param len the length of the class bytes @param cs the associated CodeSource or null if none @return the Class object created from the data and optional CodeSource.

Class SecureClassLoader, PermissionCollection getPermissions(CodeSource)

Returns the permissions for the given codesourceCodeSource 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 codesourceCodeSource.

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

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

@param codesource the codesource. @return the permissions granted to the codesource.


Class SecureRandom

This class provides a cryptographically strong pseudo-random number generator (PRNG).

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

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

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

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

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

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

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

 byte seed[] = random.generateSeed(20); 
@see java.security.SecureRandomSpi @see java.util.Random @version 1.31 9836 02/1202/0300 @author Benjamin Renaud @author Josh Bloch
Class SecureRandom, SecureRandom getInstance(String)

Generates a SecureRandom object that implements the specified Pseudo Random Number Generator (PRNG) algorithm. If the default provider package provides an implementation of the requested PRNG an instance of SecureRandom containing that implementation is returned. If the PRNG is not available in the default package other packages are searched.

Note that the returned instance of SecureRandom has not been seeded. A call to the setSeed method will seed the SecureRandom object. If a call is not made to setSeed the first call to the nextBytes method will force the SecureRandom object to seed itself. @param algorithm the name of the PRNG algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard PRNG algorithm names. @return the new SecureRandom object. @exception NoSuchAlgorithmException if the PRNG algorithm is not available in the caller's environment. @since JDK11.2

Class SecureRandom, SecureRandom getInstance(String, String)

Generates a SecureRandom object for the specified PRNG algorithm as supplied from the specified provider if such a PRNG implementation is available from the provider.

Note that the returned instance of SecureRandom has not been seeded. A call to the setSeed method will seed the SecureRandom object. If a call is not made to setSeed the first call to the nextBytes method will force the SecureRandom object to seed itself. @param algorithm the name of the PRNG algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard PRNG algorithm names. @param provider the name of the provider. @return the new SecureRandom object. @exception NoSuchAlgorithmException if the requested PRNG implementation is not available from the provider. @exception NoSuchProviderException if the provider has not been configured. @see Provider @since JDK11.2

Class SecureRandom, int next(int)

Generates an integer containing the user-specified number of pseudo-random bits (right justified with leading zeros). This method overrides a java.util.Random method and serves to provide a source of random bits to all of the methods inherited from that class (for example nextInt nextLong and nextFloat). @param numBits number of pseudo-random bits to be generated where 0 < numBits < 32. @return an int containing the user-specified number of pseudo-random bits (right justified with leading zeros).

Class SecureRandomSpi

This class defines the Service Provider Interface (SPI) for the SecureRandom class. All the abstract methods in this class must be implemented by each service provider who wishes to supply the implementation of a cryptographically strong pseudo-random number generator. @version 1.3 987 02/1202/0300 @see SecureRandom @since JDK11.2

Class Security

This class centralizes all security properties and common security methods. One of its primary uses is to manage providers. @author Benjamin Renaud @version 1.89 99/ 02/0308/00

Class Security, String getAlgorithmProperty(String, String)

Gets a specified property for an algorithm. The algorithm name should be a standard name. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names. One possible use is by specialized algorithm parsers which may map classes to algorithms which they understand (much like Key parsers do). @param algName the algorithm name. @param propName the name of the property to get. @return the value of the specified property. @deprecated This method used to return the value of a proprietary property in the master file of the "SUN" Cryptographic Service Provider in order to determine how to parse algorithm-specific parameters. Use the new provider-based and algorithm-independent AlgorithmParameters and KeyFactory engine classes (introduced in JDKthe 1.Java 2 platform) instead.

Class SecurityPermission

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

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

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

Permission Target Name What the Permission Allows Risks of Allowing this Permission
createAccessControlContext Creation of an AccessControlContext This allows someone to instantiate an AccessControlContext with a DomainCombiner. Since DomainCombiners are given a reference to the ProtectionDomains currently on the stack this could potentially lead to a privacy leak if the DomainCombiner is malicious.
getDomainCombiner Retrieval of an AccessControlContext's DomainCombiner This allows someone to retrieve an AccessControlContext's DomainCombiner. Since DomainCombiners may contain sensitive information this could potentially lead to a privacy leak.
getPolicy Retrieval of the system-wide security policy (specifically of the currently-installed Policy object) This allows someone to query the policy via the getPermissions call which discloses which permissions would be granted to a given CodeSource. While revealing the policy does not compromise the security of the system it does provide malicious code with additional information which it may use to better aim an attack. It is wise not to divulge more information than necessary.
setPolicy Setting of the system-wide security policy (specifically the Policy object) Granting this permission is extremely dangerous as malicious code may grant itself all the necessary permissions it needs to successfully mount an attack on the system.
getProperty.{key} Retrieval of the security property with the specified key Depending on the particular key for which access has been granted the code may have access to the list of security providers as well as the location of the system-wide and user security policies. while revealing this information does not compromise the security of the system it does provide malicious code with additional information which it may use to better aim an attack.
setProperty.{key} Setting of the security property with the specified key This could include setting a security provider or defining the location of the the system-wide security policy. Malicious code that has permission to set a new security provider may set a rogue provider that steals confidential information such as cryptographic private keys. In addition malicious code with permission to set the location of the system-wide security policy may point it to a security policy that grants the attacker all the necessary permissions it requires to successfully mount an attack on the system.
insertProvider.{provider name} Addition of a new provider with the specified name This would allow somebody to introduce a possibly malicious provider (e.g. one that discloses the private keys passed to it) as the highest-priority provider. This would be possible because the Security object (which manages the installed providers) currently does not check the integrity or authenticity of a provider before attaching it.
removeProvider.{provider name} Removal of the specified provider This may change the behavior or disable execution of other parts of the program. If a provider subsequently requested by the program has been removed execution may fail. Also if the removed provider is not explicitly requested by the rest of the program but it would normally be the provider chosen when a cryptography service is requested (due to its previous order in the list of providers) a different provider will be chosen instead or no suitable provider will be found thereby resulting in program failure.
setSystemScope Setting of the system identity scope This would allow an attacker to configure the system identity scope with certificates that should not be trusted thereby granting applet or application code signed with those certificates privileges that would have been denied by the system's original identity scope
setIdentityPublicKey Setting of the public key for an Identity If the identity is marked as "trusted" this allows an attacker to introduce a different public key (e.g. its own) that is not trusted by the system's identity scope thereby granting applet or application code signed with that public key privileges that would have been denied otherwise.
setIdentityInfo Setting of a general information string for an Identity This allows attackers to set the general description for an identity. This may trick applications into using a different identity than intended or may prevent applications from finding a particular identity.
addIdentityCertificate Addition of a certificate for an Identity This allows attackers to set a certificate for an identity's public key. This is dangerous because it affects the trust relationship across the system. This public key suddenly becomes trusted to a wider audience than it otherwise would be.
removeIdentityCertificate Removal of a certificate for an Identity This allows attackers to remove a certificate for an identity's public key. This is dangerous because it affects the trust relationship across the system. This public key suddenly becomes considered less trustworthy than it otherwise would be.
printIdentity Viewing the name of a principal and optionally the scope in which it is used and whether or not it is considered "trusted" in that scope The scope that is printed out may be a filename in which case it may convey local system information. For example here's a sample printout of an identity named "carol" who is marked not trusted in the user's identity database:
carol[/home/luehe/identitydb.obj][not trusted]
clearProviderProperties.{provider name} "Clearing" of a Provider so that it no longer contains the properties used to look up services implemented by the provider This disables the lookup of services implemented by the provider. This may thus change the behavior or disable execution of other parts of the program that would normally utilize the Provider as described under the "removeProvider.{provider name}" permission.
putProviderProperty.{provider name} Setting of properties for the specified Provider The provider properties each specify the name and location of a particular service implemented by the provider. By granting this permission you let code replace the service specification with another one thereby specifying a different implementation.
removeProviderProperty.{provider name} Removal of properties from the specified Provider This disables the lookup of services implemented by the provider. They are no longer accessible due to removal of the properties specifying their names and locations. This may change the behavior or disable execution of other parts of the program that would normally utilize the Provider as described under the "removeProvider.{provider name}" permission.
getSignerPrivateKey Retrieval of a Signer's private key It is very dangerous to allow access to a private key; private keys are supposed to be kept secret. Otherwise code can use the private key to sign various files and claim the signature came from the Signer.
setSignerKeyPair Setting of the key pair (public key and private key) for a Signer This would allow an attacker to replace somebody else's (the "target's") keypair with a possibly weaker keypair (e.g. a keypair of a smaller keysize). This also would allow the attacker to listen in on encrypted communication between the target and its peers. The target's peers might wrap an encryption session key under the target's "new" public key which would allow the attacker (who possesses the corresponding private key) to unwrap the session key and decipher the communication data encrypted under that session key.
@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.18 9921 00/0402/2202 @author Marianne Mueller @author Roland Schemers


Class Signature

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

The signature algorithm can be among others the NIST standard DSA using DSA and SHA-1. The DSA algorithm using the SHA-1 message digest algorithm can be specified as SHA1withDSA. In the case of RSA there are multiple choices for the message digest algorithm so the signing algorithm could be specified as for example MD2withRSA MD5withRSA or SHA1withRSA. The algorithm name must be specified as there is no default.

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

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

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

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

  1. Initialization with either
    • a public key which initializes the signature for verification (see initVerify or
    • a private key (and optionally a Secure Random Number Generator) which initializes the signature for signing (see #initSign(PrivateKey) and initSign(PrivateKey SecureRandom)}).

  2. Updating

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

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

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

Class Signature, void setParameter(String, Object)

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

Finishes the signature operation and stores the resulting signature bytes in the provided buffer outbuf starting at offset. The format of the signature depends on the underlying signature scheme.

This signature object is reset to its initial state (the state it was in after a call to one of the initSign methods) and can be reused to generate further signatures with the same private key. @param outbuf buffer for the signature result. @param offset offset into outbuf where the signature is stored. @param len number of bytes within outbuf allotted for the signature. @return the number of bytes placed into outbuf. @exception SignatureException if an error occurs or len is less than the actual signature length. @since JDK11.2

Class Signature, int SIGN

Possible #state value signifying that this signature object has been initialized for signing.
Class Signature, int UNINITIALIZED

Possible #state value signifying that this signature object has not yet been initialized.
Class Signature, int VERIFY

Possible #state value signifying that this signature object has been initialized for verification.

Class SignatureException

This is the generic Signature exception. @version 1.9 0911 02/2102/9800 @author Benjamin Renaud

Class SignatureSpi

This class defines the Service Provider Interface (SPI) for the Signature class which is used to provide the functionality of a digital signature algorithm. Digital signatures are used for authentication and integrity assurance of digital data. .

All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a particular signature algorithm. @author Benjamin Renaud @version 1.9 9814 02/1202/0300 @see Signature

Class SignatureSpi, void engineSetParameter(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. @deprecated Replaced by engineSetParameter.
Class SignatureSpi, int engineSign(byte[], int, int)

Finishes this signature operation and stores the resulting signature bytes in the provided buffer outbuf starting at offset. The format of the signature depends on the underlying signature scheme.

The signature implementation is reset to its initial state (the state it was in after a call to one of the engineInitSign methods) and can be reused to generate further signatures with the same private key. This method should be abstract but we leave it concrete for binary compatibility. Knowledgeable providers should override this method. @param outbuf buffer for the signature result. @param offset offset into outbuf where the signature is stored. @param len number of bytes within outbuf allotted for the signature. Both this default implementation and the SUN provider do not return partial digests. If the value of this parameter is less than the actual signature length this method will throw a SignatureException. This parameter is ignored if its value is greater than or equal to the actual signature length. @return the number of bytes placed into outbuf @exception SignatureException if an error occurs or len is less than the actual signature length. @since JDK11.2


Class SignedObject

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

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

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

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

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

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

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

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

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

The signature algorithm can be among others the NIST standard DSA using DSA and SHA-1. The algorithm is specified using the same convention as that for signatures. The DSA algorithm using the SHA-1 message digest algorithm can be specified for example as "SHA/DSA" or "SHA-1/DSA" (they are equivalent). In the case of RSA there are multiple choices for the message digest algorithm so the signing algorithm could be specified as for example "MD2/RSA" "MD5/RSA" or "SHA-1/RSA". The algorithm name must be specified as there is no default.

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

Potential applications of SignedObject include:

@see Signature @version 1.34 1037 02/2702/9800 @author Li Gong
Class SignedObject, boolean verify(PublicKey, Signature)

Verifies that the signature in this SignedObject is the valid signature for the object stored inside with the given verification key using the designated verification engine. @param verificationKey the public key for verification. @param verificationEngine the signature verification engine. @exception SignatureException if signature verification failed. @exception InvalidKeyException if the verification key is invalid. @return true if the signature is valid false otherwise

Class Signer

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

The management of a signer's private keys is an important and sensitive issue that should be handled by subclasses as appropriate to their intended use. @see Identity @version 1.35 9837 00/1202/0302 @author Benjamin Renaud @deprecated This class is no longer used. Its functionality has been replaced by java.security.KeyStore the java.security.cert package and java.security.Principal.


Class UnrecoverableKeyException

This exception is thrown if a key in the keystore cannot be recovered. @version 1.4 066 02/2902/9800 @since 1.2

Class UnresolvedPermission

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

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

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

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

Later when code calls AccessController.checkPermission on a permission of a type that was previously unresolved but whose class has since been loaded previously-unresolved permissions of that type are "resolved". That is for each such UnresolvedPermission a new object of the appropriate class type is instantiated based on the information in the UnresolvedPermission. This new object replaces the UnresolvedPermission which is removed. @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.security.Policy @version 1.15 9817 00/1202/1102 @author Roland Schemers