com.ibm.xml.crypto.spi
Interface EngineFactory

All Known Implementing Classes:

AlgorithmFactory

public interface EngineFactory

This is a factory interface for pluggable XML-Signature/XML-Encryption algorithms.

How to implement your algorithms

1. Decide identifier URIs for algorithms which you implement

2. Decide XML representation of algorithm parameters

3. Implement algorithm classes

Define classes implements SignatureEngine, MessageDigest, EncryptionEngine, or KeyGenerationEngine. You may define their constructors at your discretion. Each of getURI() methods of *Engine interfaces should return its own identifier URI decidec at the step 1.

4. Implement a factory class

Define the constructor which takes another EngineFactory. It is the master EngineFactory used in the platform.

 public class EngineFactoryImpl implements EngineFactory {
     public EngineFactoryImpl(EngineFactory master) {
         ....
 

If one of your algorithms is SignatureEngine, return an instance of your implementation class of SignatureEngine in the getSignatureEngine() if the specified URI matches to your algorithm URI. If the URI does not match, throw NoSuchAlgorithmException.

Implement other getSomeEngine() methods like the above. If you have no implementation class for getSomeEngine(), the method simply throw NoSuchAlgorithmException.

 public SignatureEngine getSignatureEngine(String uri)
 throws NoSuchAlgorithmException {
     if (MY_ALGORITHM_URI.equals(uri)) {
         SignatureEngine engine = new SignatureEngineImpl(...);
         return engine;
     }
     throw NoSuchAlgorithmException(uri);
 }
 public EncryptionEngine getEncryptionEngine(String uri)
 throws NoSuchAlgorithmException {
     throw NoSuchAlgorithmException(uri);
 }
 

Implement getSomeAlgorithms methods so that they return the list of the supported algorithms by your factory. If they have no algorithms to be supported, these methods simply return null.

 public Set getSignatureAlgorithms() {
     Set supportedSignature = new HashSet();
     supportedSignature.add(MY_ALGORITHM_URI);
     return supportedSignature;
 }
 public Set getDataEncryptionAlgorithms() {
     return null;
 }
 

Implement releaseSomeEngine() methods so that they return true if instances generated by your factory are specified.

 public boolean releaseSignatureEngine(SignatureEngine eng) {
     if (MY_ALGORITHM_URI.equals(eng.getURI())
         return true;
     return false;
 }
 public boolean releaseEncryptionEngine(EncryptionEngine eng) {
     return false;
 }
 

Implement unmarshalParameter() method. The method is called to generate an AlgorithmParameterSpec from an element in XML-Signature or XML-Encryption document.

 public AlgorithmParameterSpec unmarshalParameter(String uri, Element el)
 throws ... {
     if (MY_ALGORITHM_URI.equals(uri)) {
         // Analyze DOM tree, and create an instance of
         // subclass of AlgorithmParameterSpec.  You have to define the subclass
         // so that your algorithm implementation can understand it.
         ...
         return new MyAlgorithmParameterSpec(...);
         // if your algorithm need no parameter, return null.
         // return null;
     }
     throw new NoSuchAlgorithmException(uri);
 }
 

Implement convertParameter() method. The method is called to generate an AlgorithmParameterSpec from key-value pairs in a configuration.

 public AlgorithmParameterSpec convertParameter(String uri, Map props)
 throws ... {
     if (MY_ALGORITHM_URI.equals(uri)) {
         // Analyze props, and create an instance of
         // subclass of AlgorithmParameterSpec.  You have to define the subclass
         // so that your algorithm implementation can understand it.
         ...
         return new MyAlgorithmParameterSpec(...);
         // if your algorithm need no parameter, return null.
         // return null;
     }
     throw new NoSuchAlgorithmException(uri);
 }
 

Implement marshalPaameter() method. The method is called to serialize an AlgorithmParameterSpec to a DOM tree.

 public void marshalParameter(String uri, AlgorithmParameterSpec spec, Element el)
 throws ... {
     if (MY_ALGORITHM_URI.equals(uri)) {
         MyAlgorithmParameterSpec mySpec;
         mySpec = (MyAlgorithmParameterSpec)spec;
         // Reverse conversion of unmarshalParameter()
         // spec may be null.
         ...
         return;
     }
     throw new NoSuchAlgorithmException(uri);
 }
 

5. Specify your EngineFactory class name in a configuration.

Note for concurrency

An isntance of EngineFactory may be accessed by multiple threads. If your EngineFactory has some data such as instance pool, appropriate synchronization is needed to protect the data.

Recycle of algorithm instances

An EngineFactory may reuse released algorithm instances. For example, releaseEncryptionEngine() method puts the specified instance into a pool, and getEncryptionEngine() dips up the instance from the pool and returns the instance.

Method Summary

java.security.spec.AlgorithmParameterSpec	convertParameter(java.lang.String uri, java.util.Map properties) Convert algorithm parameters from properties form to AlgorithmParameterSpec form.
java.util.Set	getDataEncryptionAlgorithms() Return a set of the supported data encryption algorithms by a factory implementation.
java.util.Set	getDigestAlgorithms() Return a set of the supported digest algorithms by a factory implementation.
EncryptionEngine	getEncryptionEngine(java.lang.String uri) Return an instance of EncryptionEngine implementation which handles the algorithm specified by uri.
java.util.Set	getKeyEncryptionAlgorithms() Return a set of the supported key encryption algorithms by a factory implementation.
KeyGenerationEngine	getKeyGenerationEngine(java.lang.String uri, java.lang.String type) Return an instance of KeyGenerationEngine implementation which handles the algorithm specified by uri.
java.security.MessageDigest	getMessageDigest(java.lang.String uri, java.security.spec.AlgorithmParameterSpec spec) Return an instance of MessageDigest implementation which handles the algorithm specified by uri.
java.util.Set	getSignatureAlgorithms() Return a set of the supported signature algorithms by a factory implementation.
SignatureEngine	getSignatureEngine(java.lang.String uri) Return an instance of SignatureEngine implementation which handles the algorithm specified by uri.
void	marshalParameter(java.lang.String uri, java.security.spec.AlgorithmParameterSpec spec, org.w3c.dom.Element el) Marshal the specified spec under the el element.
boolean	releaseEncryptionEngine(EncryptionEngine eng) This method is called when XML-Signature/XML-Encryption processors finish to use the specified engine instance.
boolean	releaseKeyGenerationEngine(KeyGenerationEngine eng) This method is called when XML-Signature/XML-Encryption processors finish to use the specified engine instance.
boolean	releaseMessageDigest(java.lang.String uri, java.security.MessageDigest d) This method is called when XML-Signature/XML-Encryption processors finish to use the specified engine instance.
boolean	releaseSignatureEngine(SignatureEngine eng) This method is called when XML-Signature/XML-Encryption processors finish to use the specified engine instance.
java.security.spec.AlgorithmParameterSpec	unmarshalParameter(java.lang.String uri, org.w3c.dom.Element el) Generate AlgorithmParameterSpec for uri from specified DOM element.

Method Detail

getSignatureEngine

SignatureEngine getSignatureEngine(java.lang.String uri)
                                   throws java.security.NoSuchAlgorithmException

Return an instance of SignatureEngine implementation which handles the algorithm specified by uri. A factory implementation may return a cached SignatureEngine instance, and MUST call SignatureEngine.setParameter().

Parameters:

uri - Algorithm identifier

Returns:

An instance of implementation class of SignatureEngine interface. It supports the algorithm specified by uri

Throws:

java.security.NoSuchAlgorithmException - This factory implementation does not support the specified URI.

java.security.InvalidAlgorithmParameterException - Invalid AlgorithmParameterSpec is specified.

getMessageDigest

java.security.MessageDigest getMessageDigest(java.lang.String uri,
                                             java.security.spec.AlgorithmParameterSpec spec)
                                             throws java.security.NoSuchAlgorithmException,
                                                    java.security.InvalidAlgorithmParameterException

Return an instance of MessageDigest implementation which handles the algorithm specified by uri. A factory implementation may return a cached MessageDigest instance.

Parameters:

uri - Algorithm identifier

spec - An isntance of algorithm-specific sub-class of AlgorithmParameterSpec. It may be null.

Returns:

An instance of implementation class of MessageDigest interface. It supports the algorithm specified by uri

Throws:

java.security.NoSuchAlgorithmException - This factory implementation does not support the specified URI.

java.security.InvalidAlgorithmParameterException - Invalid AlgorithmParameterSpec is specified.

getEncryptionEngine

EncryptionEngine getEncryptionEngine(java.lang.String uri)
                                     throws java.security.NoSuchAlgorithmException

Return an instance of EncryptionEngine implementation which handles the algorithm specified by uri. A factory implementation may return a cached EncryptionEngine instance.

Parameters:

uri - Algorithm identifier

Returns:

An instance of implementation class of EncryptionEngine interface. It supports the algorithm specified by uri

Throws:

java.security.NoSuchAlgorithmException - This factory implementation does not support the specified URI.

getKeyGenerationEngine

KeyGenerationEngine getKeyGenerationEngine(java.lang.String uri,
                                           java.lang.String type)
                                           throws java.security.NoSuchAlgorithmException

Return an instance of KeyGenerationEngine implementation which handles the algorithm specified by uri. A factory implementation may return a cached KeyGenerationEngine instance.

Parameters:

uri - Algorithm identifier

type - Type identifier specified as enc:EncryptedKey/@Type. This may be null.

Returns:

An instance of implementation class of KeyGenerationEngine interface. It supports the algorithm specified by uri

Throws:

java.security.NoSuchAlgorithmException - This factory implementation does not support the specified URI.

getSignatureAlgorithms

java.util.Set getSignatureAlgorithms()

Return a set of the supported signature algorithms by a factory implementation.

Returns:

A set of Strings representing the supported signature algorithms. If there is no algorithms to be supported, return null.

getDigestAlgorithms

java.util.Set getDigestAlgorithms()

Return a set of the supported digest algorithms by a factory implementation.

Returns:

A set of Strings representing the supported digest algorithms. If there is no algorithms to be supported, return null.

getDataEncryptionAlgorithms

java.util.Set getDataEncryptionAlgorithms()

Return a set of the supported data encryption algorithms by a factory implementation.

Returns:

A set of Strings representing the supported data encryption algorithms. If there is no algorithms to be supported, return null.

getKeyEncryptionAlgorithms

java.util.Set getKeyEncryptionAlgorithms()

Return a set of the supported key encryption algorithms by a factory implementation.

Returns:

A set of Strings representing the supported key encryption algorithms. If there is no algorithms to be supported, return null.

releaseSignatureEngine

boolean releaseSignatureEngine(SignatureEngine eng)

This method is called when XML-Signature/XML-Encryption processors finish to use the specified engine instance. A factory implementation may pool the speficied instance.

Parameters:

eng - An instance which is not used anymore.

Returns:

true if specified instance is generated by this EngineFactory.

releaseMessageDigest

boolean releaseMessageDigest(java.lang.String uri,
                             java.security.MessageDigest d)

This method is called when XML-Signature/XML-Encryption processors finish to use the specified engine instance. A factory implementation may pool the speficied instance.

Parameters:

uri - Algorithm identifier

eng - An instance which is not used anymore.

Returns:

true if specified instance is generated by this EngineFactory.

releaseEncryptionEngine

boolean releaseEncryptionEngine(EncryptionEngine eng)

This method is called when XML-Signature/XML-Encryption processors finish to use the specified engine instance. A factory implementation may pool the speficied instance.

Parameters:

eng - An instance which is not used anymore.

Returns:

true if specified instance is generated by this EngineFactory.

releaseKeyGenerationEngine

boolean releaseKeyGenerationEngine(KeyGenerationEngine eng)

This method is called when XML-Signature/XML-Encryption processors finish to use the specified engine instance. A factory implementation may pool the speficied instance.

Parameters:

eng - An instance which is not used anymore.

Returns:

true if specified instance is generated by this EngineFactory.

unmarshalParameter

java.security.spec.AlgorithmParameterSpec unmarshalParameter(java.lang.String uri,
                                                             org.w3c.dom.Element el)
                                                             throws java.security.NoSuchAlgorithmException,
                                                                    java.security.InvalidAlgorithmParameterException

Generate AlgorithmParameterSpec for uri from specified DOM element.

Parameters:

uri - Algorithm identifier

el - An element representing <ds:SingatureMethod>, <ds:DigestMethod>, or <enc:EncryptionMethod>.

Throws:

java.security.NoSuchAlgorithmException - This factory implementation does not support the specified URI.

java.security.InvalidAlgorithmParameterException - Parameters in el is invalid.

convertParameter

java.security.spec.AlgorithmParameterSpec convertParameter(java.lang.String uri,
                                                           java.util.Map properties)
                                                           throws java.security.NoSuchAlgorithmException,
                                                                  java.security.InvalidAlgorithmParameterException

Convert algorithm parameters from properties form to AlgorithmParameterSpec form.

Parameters:

uri - Algorithm identifier

properties - String => String map specified in a configuration. It may be null.

Returns:

An isntance of algorithm-specific sub-class of AlgorithmParameterSpec. It may be null.

Throws:

java.security.NoSuchAlgorithmException - This factory implementation does not support the specified URI.

java.security.InvalidAlgorithmParameterException - Invalid AlgorithmParameterSpec is specified.

marshalParameter

void marshalParameter(java.lang.String uri,
                      java.security.spec.AlgorithmParameterSpec spec,
                      org.w3c.dom.Element el)
                      throws java.security.NoSuchAlgorithmException,
                             java.security.InvalidAlgorithmParameterException

Marshal the specified spec under the el element.

Parameters:

uri - Algorithm identifier

spec - Algorithm parameter to be marshalled. It may be null.

el - An element representing <ds:SingatureMethod>, <ds:DigestMethod>, or <enc:EncryptionMethod>.

Throws:

java.security.NoSuchAlgorithmException - This factory implementation does not support the specified URI.

java.security.InvalidAlgorithmParameterException - Invalid AlgorithmParameterSpec is specified.