iaik.ixsil.core

Interface SignerReference

public interface SignerReference

This interface provides a specialized view on a Reference. This view is used by the application in the signature creation use case.

See Also:

SignerSignedInfo.createReference(), SignerSignedInfo.getSignerReferences(), SignerManifest.createReference(), SignerManifest.getSignerReferences()

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	EXPLICITDATATYPE_DIGESTINPUT_ Constant for type of data set with method setExplicitData(java.lang.Object, boolean).
static boolean	EXPLICITDATATYPE_RAW_ Constant for type of data set with method setExplicitData(java.lang.Object, boolean).

Method Summary

Modifier and Type	Method and Description
byte[]	getCalculatedDigest() Gets the digest value that has been calculated by this object.
DigestAlgorithm	getDigestAlgorithm() Gets the digest algorithm employed by this reference.
org.w3c.dom.Element	getDOMElement() Gets the DOM Element representing the reference.
java.io.InputStream	getExplicitData(boolean explicitDataType) Gets either the raw data (data resulting from resolving the URI attribute of the reference) or the digest input data (data resulting from the last of the specified transforms).
java.lang.String	getId() Gets the Id attribute value of the Reference element.
Transform[]	getTransforms() Gets an array with all Transform objects registerred for this reference.
int	getTransformsNumber() Gets the number of transforms inserted into this reference so far.
java.lang.String	getType() Gets the Type attribute value of the Reference Element.
java.lang.String	getURI() Gets the URI attribute value of the Reference Element.
void	insertTransformAt(Transform transform, int position) Inserts the specified transform at the specified position into the list of transforms which should be applied to the data refered by this reference to get the input for the digest algorithm.
java.lang.Object	processTransforms(int positionOfLastIncludedTransform, boolean applyFinalC14N) Resolves the Reference's URI (or takes the expicite data set previously respectively) and invokes all transforms starting with the first and ending with the one specified by means of the parameter positionOfLastIncludedTransform.
void	removeTransformAt(int position) Removes the transform at the specified position from the list of transforms which should be applied to the data refered by this reference to get the input for the digest algorithm.
void	setCalculatedDigest(byte[] calculatedDigestValue) Sets the digest value that has been calculated for this reference.
void	setDigestAlgorithm(DigestAlgorithm digestAlgorithm) Sets the digest algorithm for this reference.
void	setExplicitData(java.lang.Object explicitData, boolean explicitDataType) Sets one of two possible kinds of explicit data:
void	setId(java.lang.String id) Sets the Id attribute value of the reference.
void	setType(URI type) Sets the Type attribute value of the Reference Element.
void	setURI(URI uri) Sets the URI attribute value of the Reference Element.

Field Detail

EXPLICITDATATYPE_RAW_

static final boolean EXPLICITDATATYPE_RAW_

Constant for type of data set with method setExplicitData(java.lang.Object, boolean).

See Also:

Constant Field Values

EXPLICITDATATYPE_DIGESTINPUT_

static final boolean EXPLICITDATATYPE_DIGESTINPUT_

Constant for type of data set with method setExplicitData(java.lang.Object, boolean).

See Also:

Constant Field Values

Method Detail

setId

void setId(java.lang.String id)

Sets the Id attribute value of the reference. If the attribute has already been set, it will be overwritten. If the id parameter equals null, the possibly existing Id attribute will be removed. If the reference has already been added to a SignerManifest or SignerSignedInfo container, this method will have no effect.

Parameters:

id - The Id attribute value.

getId

java.lang.String getId()

Gets the Id attribute value of the Reference element.

Returns:

the attribute value or null if the Id attribute is not available.

setURI

void setURI(URI uri)

Sets the URI attribute value of the Reference Element. If the attribute has already been set, it will be overwritten. If the uri parameter equals null, the possibly existing URI attribute will be removed.

Parameters:

uri - The URI for the attribute value.

getURI

java.lang.String getURI()

Gets the URI attribute value of the Reference Element.

Returns:

the attribute value or null if the URI attribute is not available.

setType

void setType(URI type)

Sets the Type attribute value of the Reference Element. If the attribute has already been set, it will be overwritten. If the type parameter equals null, the possibly existing Type attribute will be removed.

Parameters:

type - The URI for the attribute value.

getType

java.lang.String getType()

Gets the Type attribute value of the Reference Element.

Returns:

the attribute value or null if the Type attribute is not available.

getDOMElement

org.w3c.dom.Element getDOMElement()

Gets the DOM Element representing the reference.

Returns:

the DOM Element representing the reference.

setDigestAlgorithm

void setDigestAlgorithm(DigestAlgorithm digestAlgorithm)
                 throws ReferenceException

Sets the digest algorithm for this reference. If the algorithm has already been set, the value will be overwritten.

Parameters:

digestAlgorithm - The digest algorithm used to create the message digest for the data refered by this reference. Must not be null.

Throws:

ReferenceException - if requesting the DOM element representation from the digest algorithm fails.

getDigestAlgorithm

DigestAlgorithm getDigestAlgorithm()

Gets the digest algorithm employed by this reference.

Returns:

The digest algorithm object, or null if it has not been specified yet.

insertTransformAt

void insertTransformAt(Transform transform,
                       int position)
                throws ReferenceException

Inserts the specified transform at the specified position into the list of transforms which should be applied to the data refered by this reference to get the input for the digest algorithm.

Parameters:

transform - The transform to be inserted. Must not be null.

position - The position where to insert the transform into the list. Must be greater or equal 0 and must be less or equal the number of transforms inserted so far.

Throws:

ReferenceException - if requesting the DOM element representation from the transform fails.

getTransformsNumber

int getTransformsNumber()

Gets the number of transforms inserted into this reference so far.

Returns:

the number of transforms inserted into this reference so far.

removeTransformAt

void removeTransformAt(int position)
                throws ReferenceException

Removes the transform at the specified position from the list of transforms which should be applied to the data refered by this reference to get the input for the digest algorithm.

Parameters:

position - The position of the tranform to be removed in the list. Must be greater or equal 0 and must be less than the number of transforms which have been inserted so far.

Throws:

ReferenceException - if removing the transform fails for any reason.

getTransforms

Transform[] getTransforms()

Gets an array with all Transform objects registerred for this reference.

Returns:

an array with all Transform objects, or null if there are no transforms.

setExplicitData

void setExplicitData(java.lang.Object explicitData,
                     boolean explicitDataType)

Sets one of two possible kinds of explicit data:

Raw data

This kind of data is equivalent to the result of resolving the URI specified for the reference. It forms the input of the first transform, or the input of the digest algorithm if there are no transforms specified.

Digest input data

This kind of data is equivalent to the output of the last transform specified for the reference, or to the result of resolving the URI specified for the reference if there are no transforms specified.

This method can be used for some reasons:

• It is useful to avoid either reference resolving, or transform computation, or both, if the result of these operations is already available for the application.
• For one Reference per Signature it is allowed to omit its URI attribute. In this case at least the raw data must be provided explicitely.

Parameters:

explicitData - The explicit data bytes to be set. Must not be null and must either be of type InputStream or NodeList.

explicitDataType - Determines the type of explicit data (raw or digest input). Please use the values EXPLICITDATATYPE_RAW_ or EXPLICITDATATYPE_DIGESTINPUT_.

getExplicitData

java.io.InputStream getExplicitData(boolean explicitDataType)

Gets either the raw data (data resulting from resolving the URI attribute of the reference) or the digest input data (data resulting from the last of the specified transforms). Which kind of data is desired must be indicated with the explicitDataType flag.

This method will not compute the desired data. If it is not available due to previous invokation of method setExplicitData(java.lang.Object, boolean) or SignerSignature.computeDigestInputs(), this method will return null.

Parameters:

explicitDataType - Determines the type of explicit data (raw or digest input). Please use the values EXPLICITDATATYPE_RAW_ or EXPLICITDATATYPE_DIGESTINPUT_.

Returns:

the desired kind of explicit data.

processTransforms

java.lang.Object processTransforms(int positionOfLastIncludedTransform,
                                   boolean applyFinalC14N)
                            throws ReferenceException

Resolves the Reference's URI (or takes the expicite data set previously respectively) and invokes all transforms starting with the first and ending with the one specified by means of the parameter positionOfLastIncludedTransform.

The result of this computation is returned; it can either be an java.io.InputStream or a org.w3c.dom.NodeList, depending on the result type of the last transform.

Further invokations of this method with a value of positionOfLastIncludedTransform higher than its current value, or the final computation of the digest value triggered by method SignerSignature.sign() or VerifierSignature.verify() will not reinvoke all the transforms, but use the (cached) result of this method instead.

Parameters:

positionOfLastIncludedTransform - The position of the last transform included in the computation described above. A value 0 means that no transform is invoked at all; in such a case the input for the first transform is returned.

applyFinalC14N - This parameter is evaluated only if the parameter positionOfLastIncludedTransform equals the number of transforms specified for this Reference and if the last transform provides the result as a NodeList. In such a case the parameter determines whether this method returns that NodeList or applies the final canonicalization and returns a InputStream instead.

Returns:

a clone of the computation result, if it is an java.io.InputStream, or the computation result itself, if it is a org.w3c.dom.NodeList.

Throws:

ReferenceException - if neither the URI attribute has been set nor a cached transform input exists, or if positionOfLastIncludedTransform contains a number higher than the number of specified transforms.

getCalculatedDigest

byte[] getCalculatedDigest()

Gets the digest value that has been calculated by this object. This may be null, if the digest has not yet been verified. If the digest has been verified successfully, this value must be the same as that returned by getDigest().

Returns:

The calculated digest value or null if it has not been calculated yet.

setCalculatedDigest

void setCalculatedDigest(byte[] calculatedDigestValue)

Sets the digest value that has been calculated for this reference. The application may use this method to set the calculated hash value explicitly; e.g. because it has already calculated it for its own. If the application sets a calculated hash value with this method, IXSIL will not calculated it again. It would use this value as if it would have had calculated on its own. This value may be null, to signal that the hash has not been calculated what would cause IXSIL to calculated the hash value next time it needs it.

Parameters:

calculatedDigestValue - The calculated digest value or null if it has not been calculated yet.