iaik.ixsil.core

Class Signer

java.lang.Object

iaik.ixsil.core.Signer

public class Signer
extends java.lang.Object

Provides the basic entry point into IXSIL for the signature creation use case. Three constructors are available for the application:

Signer(URI)

Used to create a completely new XML document with the XML signature which is to be created as its root element.

Signer(Document, URI, Position)

Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position. The existing XML document is specified as a document object model.

Signer(InputStream, URI, Position)

Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position. The existing XML document is specified as an input stream.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List	addedNSDecls_ Contains all namespace nodes which have been added to signatureDocOM_.
protected SignerSignature	signature_ Represents the XML signature itself.
protected org.w3c.dom.Document	signatureDocOM_ Holds the object model (OM) representing the logical structure of the XML signature document.
protected static boolean	SIGNING_ Indicates the signature creation use case.
protected URIResolverParameters	uriResolverParameters_ Structure encapsulating some parameters for resolving URIs within the IXSIL core.
protected boolean	useCase_ Indicates if this object is used for signing or verifying.
protected boolean	validated_ Shows if the signature document could have been parsed with validation on, or has been parsed with validation off.
protected static boolean	VERIFYING_ Indicates the signature verification use case.

Constructor Summary

Constructors

Constructor and Description
Signer(org.w3c.dom.Document signatureDocOM, URI signatureDocBaseURI, Position signaturePosition) Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position.
Signer(org.w3c.dom.Element signatureParentElement, URI signatureDocBaseURI, int signatureChildIndex) Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position.
Signer(java.io.InputStream signatureDocStream, URI signatureDocBaseURI, Position signaturePosition) Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position.
Signer(java.io.InputStream signatureDocStream, URI signatureDocBaseURI, Position signaturePosition, java.lang.String noNamespaceSchemaLocation, java.lang.String schemaLocations) Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position.
Signer(URI signatureDocBaseURI) Used to create a completely new XML document with the XML signature which is to be created as its root element.

Method Summary

Modifier and Type	Method and Description
SignerManifest	createManifest() Used by the application to create a new, empty manifest.
SignatureProperties	createSignatureProperties() Used by the application to create a new, empty signature property container.
SignerSignature	getSignature() Gets an interface to the signature object for the signing use case.
protected void	initResolvers() Initializes the default implementations for the internal (XPointerReferenceResolver) and the external (ExternalReferenceResolverImpl) reference resolver.
protected void	insertSignature(org.w3c.dom.Element signatureParentElement, int signatureChildIndex) Inserts an empty DOM element for the XML signature as child of the given parent element at the specified position.
protected void	insertSignature(Position signaturePosition) Inserts an empty DOM element for the XML signature into the signature DOM document at the specified position.
void	setExternalRefResolver(ExternalReferenceResolverInterface externalRefResolver) Sets the object which is responsible for resolving external URIs, i.
void	setInternalRefResolver(InternalReferenceResolverInterface internalRefResolver) Sets the object which is responsible for resolving internal URIs, i.
org.w3c.dom.Document	toDocument() Gets the object model representation for the XML document containing the XML signature.
void	withdrawDistributedNSDeclarations() Removes namespace declarations which have eventually been inserted into the XML document bearing the XML signature by IXSIL during signature creation or signature validation respectively.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

signature_

protected SignerSignature signature_

Represents the XML signature itself.

SIGNING_

protected static final boolean SIGNING_

Indicates the signature creation use case.

See Also:

Constant Field Values

VERIFYING_

protected static final boolean VERIFYING_

Indicates the signature verification use case.

See Also:

Constant Field Values

validated_

protected boolean validated_

Shows if the signature document could have been parsed with validation on, or has been parsed with validation off.

signatureDocOM_

protected org.w3c.dom.Document signatureDocOM_

Holds the object model (OM) representing the logical structure of the XML signature document.

uriResolverParameters_

protected URIResolverParameters uriResolverParameters_

Structure encapsulating some parameters for resolving URIs within the IXSIL core.

useCase_

protected boolean useCase_

Indicates if this object is used for signing or verifying. Will be set either by the Signer or Verifier subclass.

addedNSDecls_

protected java.util.List addedNSDecls_

Contains all namespace nodes which have been added to signatureDocOM_. This member variable is part of "TreeModelWorkaround".

Constructor Detail

Signer

public Signer(URI signatureDocBaseURI)
       throws SignatureHandlerException

Used to create a completely new XML document with the XML signature which is to be created as its root element.

Parameters:

signatureDocBaseURI - Holds the base URI for the signature document used to resolve relative URIs in several cases. Must either be null or an absolute URI.

Throws:

SignatureHandlerException - if creating the new XML document fails.

Signer

public Signer(org.w3c.dom.Document signatureDocOM,
              URI signatureDocBaseURI,
              Position signaturePosition)
       throws SignatureHandlerException

Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position. The existing XML document is specified as a document object model.

Parameters:

signatureDocOM - The object model of the XML document into which the XML signature is inserted. Must not be null.

signatureDocBaseURI - Holds the base URI for the signature document used to resolve relative URIs in several cases. Must either be null or an absolute URI.

signaturePosition - The position where to insert the XML signature into the existing XML document. Must not be null.

Throws:

SignatureHandlerException - if parsing the existing XML document fails, or if inserting the structures for the XML signature into the XML document fails.

Signer

public Signer(org.w3c.dom.Element signatureParentElement,
              URI signatureDocBaseURI,
              int signatureChildIndex)
       throws SignatureHandlerException

Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position. The existing XML document is specified as a document object model.

Parameters:

signatureParentElement - The parent element into which the XML signature is inserted as a child. Must not be null.

signatureDocBaseURI - Holds the base URI for the signature document used to resolve relative URIs in several cases. Must either be null or an absolute URI.

signatureChildIndex - The index where to insert the XML signature element as a child element of the element given as signatureParentElement. For example, if this index is 1, the signature element is inserted as the second child of the signatureParentElement element. If this index is -1, the signature will be appended as the last child of the signatureParentElement element.

Throws:

SignatureHandlerException - if parsing the existing XML document fails, or if inserting the structures for the XML signature into the XML document fails.

Signer

public Signer(java.io.InputStream signatureDocStream,
              URI signatureDocBaseURI,
              Position signaturePosition)
       throws SignatureHandlerException

Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position. The existing XML document is specified as an input stream. In a first try, IXSIL parses the existing XML document using a validating parser; if this fails, IXSIL parses the existing XML document using a non-validating parser.

Parameters:

signatureDocStream - The input stream of the XML document into which the XML signature is inserted. Must not be null.

signatureDocBaseURI - Holds the base URI for the signature document used to resolve relative URIs in several cases. Must either be null or an absolute URI.

signaturePosition - The position where to insert the XML signature into the existing XML document. Must not be null.

Throws:

SignatureHandlerException - if parsing the existing XML document fails, or if inserting the structures for the XML signature into the XML document fails.

Signer

public Signer(java.io.InputStream signatureDocStream,
              URI signatureDocBaseURI,
              Position signaturePosition,
              java.lang.String noNamespaceSchemaLocation,
              java.lang.String schemaLocations)
       throws SignatureHandlerException

Used to insert the XML signature which is to be created into an existing XML document at an arbitrary position. The existing XML document is specified as an input stream. In a first try, IXSIL parses the existing XML document using a validating parser; if this fails, IXSIL parses the existing XML document using a non-validating parser.

Parameters:

signatureDocStream - The input stream of the XML document into which the XML signature is inserted. Must not be null.

signatureDocBaseURI - Holds the base URI for the signature document used to resolve relative URIs in several cases. Must either be null or an absolute URI.

signaturePosition - The position where to insert the XML signature into the existing XML document. Must not be null.

noNamespaceSchemaLocation - This URI string can be used to provide a Schema for the no-namespace in cases where the DOM document should be created by a validating parser (see also parameter validate). May be null . Valid example: "http://repository.foo.org/mySchema.xsd".

schemaLocations - This parameter can be used to provide schemas for various namespaces in cases where the DOM document should be created by a validating parser (see also parameter validate). Must either be null or conform to the following rules:

                           additionalSchemas ::= additionalSchema (space additionalSchema)*
                           additionalSchema ::= schemaNamespaceURI space schemaLocationURI
                         

For example, "http://foo.org/mySchema http://repository.foo.org/mySchema.xsd".

Throws:

SignatureHandlerException - if parsing the existing XML document fails, or if inserting the structures for the XML signature into the XML document fails.

Method Detail

createManifest

public SignerManifest createManifest()

Used by the application to create a new, empty manifest.

Returns:

a newly created, empty manifest for further configuration by the application.

createSignatureProperties

public SignatureProperties createSignatureProperties()

Used by the application to create a new, empty signature property container.

Returns:

a newly created, empty signature property container for further configuration by the application.

getSignature

public SignerSignature getSignature()

Gets an interface to the signature object for the signing use case.

Returns:

an interface to the signature object for the signing use case.

toDocument

public org.w3c.dom.Document toDocument()

Gets the object model representation for the XML document containing the XML signature. An invokation of this method only makes sense after the signature has been configured and signed. Namespace declarations which have eventually been inserted into the XML document by IXSIL are removed before the object model is passed back (see withdrawDistributedNSDeclarations()).

Returns:

the object model representation for the XML document containing the XML signature.

insertSignature

protected void insertSignature(org.w3c.dom.Element signatureParentElement,
                               int signatureChildIndex)
                        throws SignatureHandlerException

Inserts an empty DOM element for the XML signature as child of the given parent element at the specified position.

Parameters:

signatureParentElement - The parent element into which the XML signature is inserted as a child. Must not be null.

signatureChildIndex - The index where to insert the XML signature element as a child element of the element given as signatureParentElement. For example, if this index is 1, the signature element is inserted as the second child of the signatureParentElement element. If this index is -1, the signature will be appended as the last child of the signatureParentElement element.

Throws:

SignatureHandlerException - if inserting the empty Signature DOM element fails.

insertSignature

protected void insertSignature(Position signaturePosition)
                        throws SignatureHandlerException

Inserts an empty DOM element for the XML signature into the signature DOM document at the specified position.

Parameters:

signaturePosition - The position where to insert the XML signature DOM element.

Throws:

SignatureHandlerException - if inserting the empty Signature DOM element fails.

setInternalRefResolver

public void setInternalRefResolver(InternalReferenceResolverInterface internalRefResolver)

Sets the object which is responsible for resolving internal URIs, i. e. URIs pointing into the XML signature document. If this method is not invoked explicitely by the application, the default resolver for internal references InternalReferenceResolverImpl will be used.

Parameters:

internalRefResolver - The object which is responsible for resolving internal URIs. Must not be null.

setExternalRefResolver

public void setExternalRefResolver(ExternalReferenceResolverInterface externalRefResolver)

Sets the object which is responsible for resolving external URIs, i. e. URIs pointing outside the XML signature document. If this method is not invoked explicitely by the application, the default resolver for external references (ExternalReferenceResolverImpl) will be used.

Parameters:

externalRefResolver - The object which is responsible for resolving external URIs. Must not be null.

initResolvers

protected void initResolvers()

Initializes the default implementations for the internal (XPointerReferenceResolver) and the external (ExternalReferenceResolverImpl) reference resolver.

withdrawDistributedNSDeclarations

public void withdrawDistributedNSDeclarations()

Removes namespace declarations which have eventually been inserted into the XML document bearing the XML signature by IXSIL during signature creation or signature validation respectively. In most cases this should not be necessary since IXSIL only explicitly inserts namespace declarations which are in scope for a particular XML element anyway. However, if you need to restore the XML document into the state before IXSIL added namespace declarations, you can use this method.