xjava.security

Class IJCE

public class IJCE extends Object

The IJCE class provides an interface to features that were not present in JavaSoft's initial version of JCE. Hopefully the getAlgorithms and/or the enable/disableTracing methods will be incorporated into a later version of the standard.

If you bundle this classfile, and the other classfiles in java.security.* that have names starting "IJCE_" with your application, these methods should work as documented even if linked against JavaSoft's implementation, so using them does not result in any loss of compatibility.

This class also defines the version number of the IJCE library:

Version numbers should be written as a triple of integers, not as a decimal. If the last number is omitted it is assumed to be 0, so for example, version 1.10 is after version 1.2.

The IJCE version number corresponding to this documentation is 1.1. (This is independent of the version numbers of any libraries that IJCE may be distributed with, such as Cryptix.)

Copyright © 1997 Systemics Ltd on behalf of the Cryptix Development Team.
All rights reserved.

$Revision: 1.5 $

Since: IJCE 1.0.1

Author: David Hopwood Raif S. Naffah

Method Summary
static voiddebug(String s)
Prints a debugging message that may be significant to a developer.
static voiddisableTracing(Object obj)
Disables tracing of SPI methods for obj.
static booleanenableTracing(Object obj, PrintWriter out)
Enables tracing of calls to SPI methods for the algorithm object obj.
static booleanenableTracing(Object obj)
Enables tracing of calls to SPI methods for the algorithm object obj, with Output sent to the default location, given by getDebugOutput().
static voiderror(String s)
Prints an error message that may be significant to a user.
static TargetfindTarget(String name)
Returns a Target that can be passed to PrivilegeManager.enablePrivilege(...), in order to request permission for an action that requires the user's trust.
static TargetfindTarget(String name, Object arg)
Reserved for future use, in case parameterized targets are needed.
static String[]getAlgorithms(Provider provider, String type)
Gets the standard names of all algorithms of the given type implemented by a provider.
static String[]getAlgorithms(String type)
Gets the standard names of all algorithms of the given type implemented by any installed provider.
static intgetDebugLevel(String label)
Returns the debug level for label.
static PrintWritergetDebugOutput()
Returns the PrintWriter that debugging Output is to be sent to.
static ObjectgetImplementation(String algorithm, String type)
Returns an object configured to the specified type.
static ObjectgetImplementation(String algorithm, String provider, String type)
Returns an object configured to the specified type.
static ClassgetImplementationClass(String algorithm, String type)
Given an algorithm name (which may be an alias) and type, returns the corresponding algorithm class from any provider.
static ClassgetImplementationClass(String algorithm, String provider, String type)
Given an algorithm name (which may be an alias), a provider name, and a type, returns the corresponding algorithm class.
static intgetIntermediateVersion()
Returns the intermediate version of this release of IJCE.
static intgetMajorVersion()
Returns the major version of this release of IJCE.
static intgetMinorVersion()
Returns the minor version of this release of IJCE.
static StringgetReleaseDate()
Returns the release date of this version of IJCE, as a string in the form "yyyy/mm/dd".
static StringgetStandardName(String algorithm, String type)
Expands the possible alias algorithm to a standard name.
static StringgetVersionString()
Returns a string describing this version of IJCE.
static booleanisProvidingJCA()
Returns true if IJCE is providing the implementations of the JCA classes (MessageDigest, Signature, etc).
static booleanisProvidingJCE()
Returns true if IJCE is providing the implementations of the JCE classes (Cipher, KeyGenerator, etc).
static booleanisVersionAtLeast(int major, int minor, int intermediate)
Returns true iff this version of IJCE is at least the given version.
static voidlistProviders()
Debugging method to list all providers.
static voidmain(String[] args)
Prints the IJCE version string, a list of statically configured providers, and the location of the library directory.
static voidreportBug(String s)
Prints a "can't happen" error, with a request to report this as a bug.

Method Detail

debug

static void debug(String s)
Prints a debugging message that may be significant to a developer.

disableTracing

public static void disableTracing(Object obj)
Disables tracing of SPI methods for obj. Returns silently if tracing was not enabled or is not supported for this object.

enableTracing

public static boolean enableTracing(Object obj, PrintWriter out)
Enables tracing of calls to SPI methods for the algorithm object obj. Output is sent to the PrintWriter out. This method will return true if tracing was enabled successfully, or false if it is not supported for this class.

Some trivial methods (such as those that get the block size) are not traced.

This can produce a lot of Output, and it should only be used for debugging, when the data being processed by the algorithm object is not secret.

Tracing only works for classes whose implementations are being provided by IJCE. If there is a non-IJCE implementation of the base class for obj (Cipher, MessageDigest, etc.) earlier in the CLASSPATH, it will probably not support tracing, and false will be returned.

Note that the IJCE library includes an implementation of java.io.PrintWriter that will be used automatically when running on Java 1.0.2.

enableTracing

public static boolean enableTracing(Object obj)
Enables tracing of calls to SPI methods for the algorithm object obj, with Output sent to the default location, given by getDebugOutput().

error

static void error(String s)
Prints an error message that may be significant to a user.

findTarget

public static Target findTarget(String name)
Returns a Target that can be passed to PrivilegeManager.enablePrivilege(...), in order to request permission for an action that requires the user's trust.

Currently the following target names are recognized:

Parameters: name the name of the target to be returned

Returns: the Target object

Throws: ForbiddenTargetException if name is not recognized.

findTarget

public static Target findTarget(String name, Object arg)
Reserved for future use, in case parameterized targets are needed. Currently this always throws a ForbiddenTargetException.

Parameters: name the name of the target to be returned arg a parameter object

Returns: the Target object

Throws: ForbiddenTargetException if name is not recognized.

getAlgorithms

public static String[] getAlgorithms(Provider provider, String type)
Gets the standard names of all algorithms of the given type implemented by a provider.

Possible values for type include "Cipher", "Mode", "PaddingScheme", "MessageDigest", "Signature", "KeyGenerator", and "KeyPairGenerator". Other types can be configured in the IJCE.properties file.

getAlgorithms

public static String[] getAlgorithms(String type)
Gets the standard names of all algorithms of the given type implemented by any installed provider. Algorithm names are not duplicated if they are supported by more than one provider (but specialized cipher/mode implementations are treated as distinct, for example "DES/CBC" is different from "DES").

Possible values for type include "Cipher", "Mode", "PaddingScheme", "MessageDigest", "Signature", "KeyGenerator", and "KeyPairGenerator". Other types can be configured in the IJCE.properties file.

The built-in padding scheme "NONE", or the built-in mode "ECB" are included if applicable.

getDebugLevel

static int getDebugLevel(String label)
Returns the debug level for label. Its value is normally given by the numeric provider property "Debug.Level.label".

If this property is not set, "Debug.Level.*" is searched next. If neither property is set, or if the first property found is not a valid decimal integer, then this method returns 0.

getDebugOutput

static PrintWriter getDebugOutput()
Returns the PrintWriter that debugging Output is to be sent to.

getImplementation

public static Object getImplementation(String algorithm, String type)
Returns an object configured to the specified type. All providers will be searched in order of preference.

Possible values for type include "Cipher", "Mode", "PaddingScheme", "MessageDigest", "Signature", "KeyGenerator", and "KeyPairGenerator". Other types can be configured in the IJCE.properties file.

Parameters: algorithm the standard name or an alias for the algorithm. type the type of algorithm.

Returns: the implementation object.

Throws: NoSuchAlgorithmException if the algorithm is not available in the environment.

getImplementation

public static Object getImplementation(String algorithm, String provider, String type)
Returns an object configured to the specified type. Provider can be null, in which case all providers will be searched in order of preference.

Possible values for type include "Cipher", "Mode", "PaddingScheme", "MessageDigest", "Signature", "KeyGenerator", and "KeyPairGenerator". Other types can be configured in the IJCE.properties file.

Parameters: algorithm the standard name or an alias for the algorithm. provider the string name of the provider. type the type of algorithm.

Returns: the implementation object.

Throws: NoSuchAlgorithmException if the algorithm is not available from the provider. NoSuchProviderException if the provider is not available in the environment.

getImplementationClass

public static Class getImplementationClass(String algorithm, String type)
Given an algorithm name (which may be an alias) and type, returns the corresponding algorithm class from any provider.

getImplementationClass

public static Class getImplementationClass(String algorithm, String provider, String type)
Given an algorithm name (which may be an alias), a provider name, and a type, returns the corresponding algorithm class.

getIntermediateVersion

public static int getIntermediateVersion()
Returns the intermediate version of this release of IJCE.

getMajorVersion

public static int getMajorVersion()
Returns the major version of this release of IJCE.

getMinorVersion

public static int getMinorVersion()
Returns the minor version of this release of IJCE.

getReleaseDate

public static String getReleaseDate()
Returns the release date of this version of IJCE, as a string in the form "yyyy/mm/dd".

getStandardName

public static String getStandardName(String algorithm, String type)
Expands the possible alias algorithm to a standard name. If algorithm is not an alias, it is returned as-is. This method does not check whether a corresponding algorithm implementation exists.

Possible values for type include "Cipher", "Mode", "PaddingScheme", "MessageDigest", "Signature", "KeyGenerator", and "KeyPairGenerator". Other types can be configured in the IJCE.properties file.

Parameters: algorithm the possible alias type the type of algorithm

Returns: the standard name

getVersionString

public static String getVersionString()
Returns a string describing this version of IJCE.

isProvidingJCA

public static boolean isProvidingJCA()
Returns true if IJCE is providing the implementations of the JCA classes (MessageDigest, Signature, etc). This will be false if another version of JCA (for example JavaSoft's) is installed earlier in the CLASSPATH.

isProvidingJCE

public static boolean isProvidingJCE()
Returns true if IJCE is providing the implementations of the JCE classes (Cipher, KeyGenerator, etc). This will be false if another version of JCE (for example JavaSoft's) is installed earlier in the CLASSPATH.

isVersionAtLeast

public static boolean isVersionAtLeast(int major, int minor, int intermediate)
Returns true iff this version of IJCE is at least the given version.

listProviders

static void listProviders()
Debugging method to list all providers.

main

public static void main(String[] args)
Prints the IJCE version string, a list of statically configured providers, and the location of the library directory.

reportBug

static void reportBug(String s)
Prints a "can't happen" error, with a request to report this as a bug. Always throws an InternalError.