codec.util
Class JCA

java.lang.Object
  codec.util.JCA

public class JCA
extends Object

A number of invariants must hold for the properties defined by the installed providers such that this class can work properly:

• Aliases must be mapped to standard JCA/JCE names whenever possible. All Aliases for an engine must map to the same name.
• Two OID mappings with the same OID must map to the same name.
• The slashed form of signature names must be set up as an alias.
• Signature engines that do not have a corresponding cipher engine still require a reverse OID mapping of the form Alg.Alias.Cipher.OID.oid = name, where name is the cipher name component of a slashed form alias for that signature engine.

Version:

"$Id: JCA.java 1913 2007-08-08 02:41:53Z jpeters $"

Author:

Volker Roth

Field Summary

protected static Map	aliases_ The root alias map.
private static Map	dc2s_ The digest/cipher name to signature algorithm name mapping.
protected static Provider[]	providers_ The current list of installed providers.
private static Map	s2dc_ The signature algorithm name to digest/cipher name mapping.

Constructor Summary

private

JCA() Let no-one create an instance.

Method Summary

static String	getCipherOID(String sigAlg) This method maps the given standard signature algorithm name to the string representation of the OID associated with the cipher algorithm of the given signature algorithm.
static String	getDigestOID(String sigAlg) This method maps the given standard signature algorithm name to the string representation of the OID associated with the digest algorithm of the given signature algorithm.
static String	getName(String oid) Returns the JCA standard name for a given OID.
static String	getOID(String algorithm) Returns the OID of the given algorithm name.
static String	getOID(String algorithm, String engine) Returns the OID of the given algorithm name.
static String	getSignatureName(String doid, String coid) This method maps a given digest algorithm OID and cipher algorithm OID onto the standard name of the combined signature algorithm.
static String	getSlashedForm(String sigAlg) This method maps the standard signature algorithm name to the digestAlg/cipherAlg format.
private static Map	initAliasLookup() Reads the properties of the installed providers and builds an optimized alias lookup table.
static String	resolveAlias(String engine, String alias) Resolves the given alias to the standard JCA name for the given engine type.
private static void	updateAliases() Re-builds the optimized alias lookup table by calling initAliasLookup(), in case the list of installed providers had been changed dynamically.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dc2s_

private static Map dc2s_

The digest/cipher name to signature algorithm name mapping.

s2dc_

private static Map s2dc_

The signature algorithm name to digest/cipher name mapping.

aliases_

protected static Map aliases_

The root alias map. Each map entry consists of the lower case engine name mapped to another map that holds the aliases for that engine.

providers_

protected static Provider[] providers_

The current list of installed providers.

Constructor Detail

JCA

private JCA()

Let no-one create an instance.

Method Detail

initAliasLookup

private static Map initAliasLookup()

Reads the properties of the installed providers and builds an optimized alias lookup table. All entries of the form

1. "Alg.Alias."+<engine>+"."+<alias> = <value>
2. "Alg.Alias."+<engine>+".OID."+<oid> = <value>
3. "Alg.Alias."+<engine>+"."+<oid> = <value>

are transformed and stored in a hashmap which is used by this class in order to do quick lookups of aliases and OID mappings. The stored entries are of the form:

1. <engine>+"."+<alias> = <value>
2. "oid."+<value> = <oid>
3. "oid."+<oid> = <value>

In case multiple providers define mappings for the same keys the mapping of the first registered provider wins.

updateAliases

private static void updateAliases()

Re-builds the optimized alias lookup table by calling initAliasLookup(), in case the list of installed providers had been changed dynamically.

getName

public static String getName(String oid)

Returns the JCA standard name for a given OID. The OID must be a string of numbers separated by dots, and can be preceded by the prefix "OID.". If the OID is not defined in a mapping of some registered provider then null is returned.

OID mappings are unambigous; no engine type is required for the mapping and no engine type is returned as part of the result. The returned string consists only of the name of the algorithm.

Parameters:

oid - The string with the OID that shall be resolved.

Returns:

The standard JCA engine name for the given OID or null if no such OID is defined.

Throws:

NullPointerException - if the oid is null.

resolveAlias

public static String resolveAlias(String engine,
                                  String alias)

Resolves the given alias to the standard JCA name for the given engine type. If no appropriate mapping is defined then null is returned. If the given alias is actually an OID string and there is an appropriate alias mapping defined for that OID by some provider then the corresponding JCA name is returned.

Parameters:

engine - The JCA engine type name.

alias - The alias to resolve for the given engine type.

Returns:

The standard JCA name or null if no appropriate mapping could be found.

Throws:

IllegalArgumentException - if the alias is an empty string.

NullPointerException - if the alias or engine name is null.

getOID

public static String getOID(String algorithm)

Returns the OID of the given algorithm name. The given name must be the JCA standard name of the algorithm and not an alias. Use resolveAlias to map aliases onto their standard names.

Parameters:

algorithm - The JCA standard name of the algorithm for which the OID should be returned.

Returns:

The OID or null if no appropriate mapping could be found.

Throws:

NullPointerException - if engine or algorithm is null.

getOID

public static String getOID(String algorithm,
                            String engine)

Returns the OID of the given algorithm name. The given engine name is taken as a hint if the given algorithm name is a non-standard name. In that case one shot is given to alias resolving before a second attempt is made to map the algorithm to an OID. Alias resolving is done by means of the resolveAlias method.

Parameters:

algorithm - The JCA standard name of the algorithm for which the OID should be returned.

engine - The engine name that is taken as a hint for alias resolving if the algorithm name cannot be resolved in the first attempt.

Returns:

The OID or null if no appropriate mapping could be found.

Throws:

NullPointerException - if engine or algorithm is null.

getSignatureName

public static String getSignatureName(String doid,
                                      String coid)

This method maps a given digest algorithm OID and cipher algorithm OID onto the standard name of the combined signature algorithm. For this to work the aliases must be well defined such as described below:

Digest Algorithm

Alg.Alias.MessageDigest.oid₁ = digestAlg

Cipher Algorithm

Alg.Alias.Cipher.oid₂ = cipherAlg

Signature Algorithm

Alg.Alias.Signature.digestAlg/cipherAlg = signatureAlg

The oid denotes the sequence of OID numbers separated by dots but without a leading "OID.". In some cases, such as the DSA, there is no cipher engine corresponding to oid₂. In this case, oid₂ must be mapped to the corresponding name by other engine types, such as a KeyFactory.

All found mappings are cached for future use, as well as the reverse mapping, which is much more complicated to synthesise.

Parameters:

doid - The string representation of the digest algorithm OID. The OID must have a "OID." prefix.

doid - The string representation of the cipher algorithm OID. The OID must have a "OID." prefix.

Returns:

The standard JCE name of the signature algorithm or null if no mapping could be found.

getSlashedForm

public static String getSlashedForm(String sigAlg)

This method maps the standard signature algorithm name to the digestAlg/cipherAlg format. This format can be used to retrieve the OID of the digest algorithm and cipher algorithm respectively. For this to work the aliases must be well defined such as described below:

Signature Algorithm

Alg.Alias.Signature.d/c = sigAlg where d denotes the digest algorithm and c the cipher algorithm. sigAlg must be the name under which the algorithm engine is published.

If sigAlg contains a "/" then we assume that the given algorithm name is already of the desired form and return sigAlg.

Parameters:

sigAlg - The standard signature algorithm name.

Returns:

The digestAlg/cipherAlg format of the given signature algorithm name or null if no suitable mapping could be found.

getDigestOID

public static String getDigestOID(String sigAlg)

This method maps the given standard signature algorithm name to the string representation of the OID associated with the digest algorithm of the given signature algorithm.

Parameters:

sigAlg - The standard signature algorithm name.

Returns:

The string representation of the OID associated with the digest alorithm used for sigAlg.

getCipherOID

public static String getCipherOID(String sigAlg)

This method maps the given standard signature algorithm name to the string representation of the OID associated with the cipher algorithm of the given signature algorithm.

This conversion is a bit tricky. In cases such as DSA, no corresponding Cipher engine exists, since DSA is not designed to be used as a cipher. In such cases, some provider needs to set up a bogus alias of the form:

Signature Algorithm

Alg.Alias.Cipher.OID.oid = DSA

The oid denotes the sequence of OID numbers separated by dots but without a leading "OID.".

Parameters:

sigAlg - The standard signature algorithm name.

Returns:

The string representation of the OID associated with the cipher alorithm used for sigAlg.