XML Security, 1.6

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.

XML Security, 1.6

Portions Copyright 2003, 2012 IBM Corporation.
Portions Copyright 2003, 2012 Oracle and/or its affiliates.