iaik.ixsil.core

Interface VerifierReference

public interface VerifierReference

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

See Also:

VerifierSignedInfo.getVerifierReferences(), VerifierManifest.getVerifierReferences()

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
VerifierManifest	dereferenceManifest() Creates a manifest object from the data the reference points to.
Object	dereferenceObject() Creates an object container from the data the reference points to.
VerifierSignatureProperties	dereferenceSignatureProperties() Creates a signature property container from the data the reference points to.
SignatureProperty	dereferenceSignatureProperty() Creates a signature property from the data the reference points to.
byte[]	getCalculatedDigest() Gets the digest value that has been calculated by this object.
byte[]	getDigest() Get the digest value of this reference element.
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.
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.
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.
boolean	refersToManifest() Checks if the Type attribute of this reference indicates that the reference refers to a manifest.
boolean	refersToObject() Checks if the Type attribute of this reference indicates that the reference refers to an object container.
boolean	refersToSignatureProperties() Checks if the Type attribute of this reference indicates that the reference refers to a signature property container.
boolean	refersToSignatureProperty() Checks if the Type attribute of this reference indicates that the reference refers to a signature property.
void	setCalculatedDigest(byte[] calculatedDigestValue) Sets the digest value that has been calculated for this reference.
void	setExplicitData(java.lang.Object explicitData, boolean explicitDataType) Sets one of two possible kinds of explicit data:
boolean	verifyDigest() Verifies the digest value of this Reference.

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

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.

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.

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.

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.

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:

• If the verifying application already knows about the result of either the URI resolving or the transform computation, it is useful to skip these processes and instead provide the corresponding data explicitely.
• If no Reference URI has been provided by the Signer, the verifier is supposed to know about the raw data. In this case the verifier must have the possibility to provide at least the raw data.

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 VerifierSignature.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.

verifyDigest

boolean verifyDigest()
              throws ReferenceException

Verifies the digest value of this Reference.

Returns:

true, if verification succeeds, false otherwise.

Throws:

ReferenceException - if performing the verification of the digest value fails for any reason.

getDigest

byte[] getDigest()
          throws ReferenceException

Get the digest value of this reference element. This is the value as it is encoded in the DOM element.

Returns:

The digest of this reference as byte array; i.e. 20 byte for a SHA-1 digest.

Throws:

ReferenceException - Parsing or decoding the digest values fails.

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.

refersToManifest

boolean refersToManifest()

Checks if the Type attribute of this reference indicates that the reference refers to a manifest.

Returns:

true if the reference refers to a manifest, false otherwise.

refersToObject

boolean refersToObject()

Checks if the Type attribute of this reference indicates that the reference refers to an object container.

Returns:

true if the reference refers to an object container, false otherwise.

refersToSignatureProperties

boolean refersToSignatureProperties()

Checks if the Type attribute of this reference indicates that the reference refers to a signature property container.

Returns:

true if the reference refers to a signature property container, false otherwise.

refersToSignatureProperty

boolean refersToSignatureProperty()

Checks if the Type attribute of this reference indicates that the reference refers to a signature property.

Returns:

true if the reference refers to a signature property, false otherwise.

dereferenceManifest

VerifierManifest dereferenceManifest()
                              throws ReferenceException

Creates a manifest object from the data the reference points to. This data must be a Manifest XML element. The method can only be employed if the URI attribute of the reference is set.

Returns:

an interface to the manifest representing the Manifest XML data the reference points to, fitting for the verification use case.

Throws:

ReferenceException - if the URI attribute has not been set, or if the referenced data is not a Manifest XML element, or if creating the manifest object fails for any other reason.

dereferenceObject

Object dereferenceObject()
                  throws ReferenceException

Creates an object container from the data the reference points to. This data must be a Object XML element. The method can only be employed if the URI attribute of the reference is set.

Returns:

an object container representing the Object XML data the reference points to.

Throws:

ReferenceException - if the URI attribute has not been set, or if the referenced data is not an Object XML element, or if creating the object container fails for any other reason.

dereferenceSignatureProperties

VerifierSignatureProperties dereferenceSignatureProperties()
                                                    throws ReferenceException

Creates a signature property container from the data the reference points to. This data must be a SignatureProperties XML element. The method can only be employed if the URI attribute of the reference is set.

Returns:

an interface to the signature property container representing the SignatureProperties XML data the reference points to, fitting for the verification use case.

Throws:

ReferenceException - if the URI attribute has not been set, or if the referenced data is not a SignatureProperties XML element, or if creating the signature property container fails for any other reason.

dereferenceSignatureProperty

SignatureProperty dereferenceSignatureProperty()
                                        throws ReferenceException

Creates a signature property from the data the reference points to. This data must be a SignatureProperty XML element. The method can only be employed if the URI attribute of the reference is set.

Returns:

a signature property object representing the SignatureProperty XML data the reference points to.

Throws:

ReferenceException - if the URI attribute has not been set, or if the referenced data is not a SignatureProperty XML element, or if creating the signature property fails for any other reason.