XML Security, 1.6

com.ibm.xml.crypto.spi
Interface SignatureEngine

All Known Implementing Classes:
SignatureEngineDSA, SignatureEngineECDSA, SignatureEngineGSSMIC, SignatureEngineHMAC, SignatureEngineRSA

public interface SignatureEngine

This defines an interface to sign or verify signature values of XML-Signature.

Our XML-Signature processor uses an instance as follows:

  1. The XML-Signature processor calls EngineFactory.getSignatureEngine(), which instanciates an instance of SignatureEngine
  2. Calls setParameter()
  3. Calls initSign() (or initVerify())
  4. Calls update() repeatedly
  5. Calls sign() (or verify())
  6. The instance is passed to EngineFactory.releaseSignatureEngine()

An EngineFactory implementation may recycle instances of SignatureEngine. In that case, the EngineFactory.getSignatureEngine() does not instanciate SignatureEngine, but returns existing instance which is passed by releaseSignatureEngine().

See Also:
EngineFactory.getSignatureEngine(String), EngineFactory.releaseSignatureEngine(SignatureEngine), Signature, Mac

Method Summary
 java.lang.String getURI()
          Return the algorithm identifier.
 void initSign(java.security.Key key)
          Initialize for signing.
 void initVerify(java.security.Key key)
          Initialize for verification.
 void setParameter(java.security.spec.AlgorithmParameterSpec spec)
          Set an instance of AlgorithmParameterSpec extracted from the content of<ds:SignatureMethod>.
 byte[] sign()
          Finish to sign, and return the signature value.
 void update(byte[] data)
          Add signed/verified data.
 void update(byte[] data, int off, int len)
          Add signed/verified data using the byte array, starting offset in the array, and the length.
 boolean verify(byte[] signature)
          Finish to verify, and return the validity against the specified signature value.
 

Method Detail

setParameter

void setParameter(java.security.spec.AlgorithmParameterSpec spec)
                  throws java.security.InvalidAlgorithmParameterException
Set an instance of AlgorithmParameterSpec extracted from the content of<ds:SignatureMethod>.

Parameters:
spec - algorithm parameter. It may be null
Throws:
java.security.InvalidAlgorithmParameterException
See Also:
EngineFactory.unmarshalParameter(String, org.w3c.dom.Element)

getURI

java.lang.String getURI()
Return the algorithm identifier.

Returns:
Algorithm identifier URI.

initSign

void initSign(java.security.Key key)
              throws java.security.InvalidKeyException
Initialize for signing.

Parameters:
key - Signing key. For asymmetric signature algorithms, it would be an instance of PrivateKey.
Throws:
java.security.InvalidKeyException
See Also:
Signature.initSign(java.security.PrivateKey)

initVerify

void initVerify(java.security.Key key)
                throws java.security.InvalidKeyException
Initialize for verification.

Parameters:
key - Verification key. For asymmetric signature algorithms, it would be an instance of PublicKey.
Throws:
java.security.InvalidKeyException
See Also:
Signature.initVerify(java.security.PublicKey)

update

void update(byte[] data)
            throws java.security.SignatureException
Add signed/verified data. This method must be equivalent to update(data, 0, data.length).

Parameters:
data - data to be signed or verified
Throws:
java.security.SignatureException
See Also:
Signature.update(byte[])

update

void update(byte[] data,
            int off,
            int len)
            throws java.security.SignatureException
Add signed/verified data using the byte array, starting offset in the array, and the length.

Parameters:
data - data to be signed or verified
off - starting offset in the data
len - the length to be processed
Throws:
java.security.SignatureException
See Also:
Signature.update(byte[], int, int)

sign

byte[] sign()
            throws java.security.SignatureException
Finish to sign, and return the signature value.

Returns:
signature value to be inserted to <ds:SignatureValue>
Throws:
java.security.SignatureException
See Also:
Signature.sign()

verify

boolean verify(byte[] signature)
               throws java.security.SignatureException
Finish to verify, and return the validity against the specified signature value.

Parameters:
signature - binary representation of the content of <ds:SignatureValue>
Returns:
true if the signature is matched.
Throws:
java.security.SignatureException
See Also:
Signature.verify(byte[])

XML Security, 1.6

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