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 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 by itself or if immediately preceded by a "." may appear at the end of the name to signify a wildcard match. For example "*" and "java.*" are valid while "*java" "a*b" and "java*" are not valid.

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

@see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.RuntimePermission @see java.security.SecurityPermission @see java.util.PropertyPermission @see java.awt.AWTPermission @see java.net.NetPermission @see java.lang.SecurityManager @version 1.32 0133 02/1202/0301 @author Marianne Mueller @author Roland Schemers

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 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.26 1228 05/0307/0102 @see Key @see PublicKey @see PrivateKey @see java.security.spec.KeySpec @see java.security.spec.DSAPublicKeySpec @see java.security.spec.X509EncodedKeySpec @since 1.2
Class KeyFactory, KeyFactory getInstance(String)

Generates a KeyFactory object that implements the specified digest algorithm. If the default provider package provides an implementation of the requested digest algorithm an instance of KeyFactory containing that implementation is returned. If the algorithm is not available in the default package other packages are searched. @param algorithm the name of the requested key algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names. @return a KeyFactory object for the specified algorithm. @exception NoSuchAlgorithmException if the requested algorithm is not available in the default provider package or any of the other provider packages that were searched.

Class Permissions

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

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

Enumerations returned via the elements method are not fail-fast. Modifications to a collection should not be performed while enumerating over that collection. @see Permission @see PermissionCollection @see AllPermission @version 1.49 0150 02/1202/0301 @author Marianne Mueller @author Roland Schemers @serial exclude


Class Provider

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

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

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


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.114 12117 04/2019/0102

Class Security, Provider[] getProviders(Map)

Returns an array containing all installed providers that satisfy the specified selection criteria or null if no such providers have been installed. The returned providers are ordered according to their preference order.

The selection criteria are represented by a map. Each map entry represents a selection criterion. A provider is selected iff it satisfies all selection criteria. The key for any entry in such a map must be in one of the following two formats:

See Appendix A in the Java Cryptogaphy Architecture API Specification & Reference for information about standard cryptographic service names standard algorithm names and standard attribute names. @param filter the criteria for selecting providers. The filter is case-insensitive. @return all the installed providers that satisfy the selection criteria or null if no such providers have been installed. @throws InvalidParameterException if the filter is not in the required format @ see #getProviders(java.lang.String)

Class Security, Provider[] getProviders(String)

Returns an array containing all installed providers that satisfy the specified selection criterion or null if no such providers have been installed. The returned providers are ordered according to their preference order.

A cryptographic service is always associated with a particular algorithm or type. For example a digital signature service is always associated with a particular algorithm (e.g. DSA) and a CertificateFactory service is always associated with a particular certificate type (e.g. X.509).

The selection criterion must be specified in one of the following two formats:

See Appendix A in the Java Cryptogaphy Architecture API Specification & Reference for information about standard cryptographic service names standard algorithm names and standard attribute names. @param filter the criterion for selecting providers. The filter is case-insensitive. @return all the installed providers that satisfy the selection criterion or null if no such providers have been installed. @throws InvalidParameterException if the filter is not in the required format @ see #getProviders(java.util.Map)


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.22 0123 02/1202/0301 @author Marianne Mueller @author Roland Schemers

Class SecurityPermission, constructor SecurityPermission(String, String)

Creates a new SecurityPermission object with the specified name. The name is the symbolic name of the SecurityPermission and the actions String is currently unused and should be null. This constructor exists for use by the Policy object to instantiate new Permission objects. @param name the name of the SecurityPermission @param actions should be null.

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.21 0122 02/1202/0301 @author Roland Schemers