XML Digital Signature Create Service

In this section:

Syntax: 

com.ibi.agents.XDXMLDSigCreateAgent

Description:

This service is used to generate an XML Digital Signature.

Parameters:

The following tables describe the parameters for the XML Digital Signature Create service. Each table is followed by a discussion of that parameter group.

Algorithms

Parameter Name

Description

XML Digital Signature JCE Provider

JCE Provider for the XMLSignatureFactory service.

Canonicalization Method

Algorithm used to canonicalize the SignedInfo element before it is digested as part of the signature operation.

Canonicalization Method Parameters

Parameters for the Canonicalization Method. For Inclusive Canonical XML, this is empty. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes.

Signature Method

Signature algorithm used to convert the canonicalized SignedInfo into the SignatureValue.

The JCE Provider for the XMLSignatureFactory service must be set to XMLDSig to select the XML Digital Signature implementation.

The Canonicalization Method is the Algorithm used to canonicalize the SignedInfo element before it is digested as part of the signature operation. It can be the URI for Inclusive Canonical XML with or without comments, or the URI for Exclusive Canonical XML with or without comments. For Inclusive Canonical XML, the Canonicalization Method Parameters are empty. For Exclusive Canonical XML, the Canonicalization Method Parameters hold a space-separated list of XML namespace prefixes.

The Signature Method is the Signature algorithm used to convert the canonicalized SignedInfo into the SignatureValue. It can be the full URI for rsa-sha1 or dsa-sha1.

Signature Key

Parameter Name

Description

KeyStore Provider

Provider for the keystore containing the signature private key.

Signing Key Alias

Private key alias used to sign the SignedInfo.

Signing Key Password

Password for the signing private key. If left blank, the password for accessing the keystore will be used.

Enforce KeyUsage Extension

If set to true, the verify certificates used for signing allow the digitalSignature KeyUsage extension.

The KeyStore Provider is the name of the provider that holds the private key. The Signing Key Alias and Signing Key Password are the Alias and Password for the private key. This key must be compatible with the signature algorithm chosen in the Signature Method parameter. When the Enforce KeyUsage Extension parameter is on, it will ensure certificates used for signing to allow the digitalSignature KeyUsage extension.

Signature Location

Parameter Name

Description

XML Namespace Provider

Provider for the mapping between XML namespace prefix and namespace URI. If left blank, elements in the XML Digital Signature will use the default namespace, and XPath expressions in the Parent and Next Sibling Paths cannot contain namespaces.

XPath Syntax

Determines which syntax level of XPath should be used. You can select the iWay abbreviated syntax or the XPath 1.0 full syntax. The default option selects the syntax level as set in the General Settings area of the iSM Administration Console.

Create Parent Element

Determines whether the parent element is created if it is missing. Select true or false (default) from the drop-down list.

Signature Parent Element

Path to the element where the signature will be inserted. If left blank, then the signature parent is the root element.

If the Create Parent Element parameter is set to true, then the expression must adhere to Restricted XPath syntax, otherwise the expression may adhere to the full syntax of the XPath engine selected by the XPath Syntax parameter.

Restricted XPath has the form /step1/step2/... where a step has the form ns:elem[predicate] or a pair of consecutive steps that has the form *[1]/self::ns:elem[predicate] to indicate the element must be the first child of its parent. The namespace prefixes are optional, but if present they must be declared in the XML Namespace provider. The predicate is optional, but when present it has the form [@ns1:attr1='val1' and @ns2:attr2='val2' and ...]. If no element matches the Restricted XPath expression and the Create Parent Element parameter is set to true, then the necessary elements and attributes will be created such that the expression would match successfully.

Signature Next Sibling

Path to the next sibling node. The signature will be inserted before this node. If left blank, the signature is added as the last child of the parent.

The XML Namespace Provider is optional. It is the name of the provider that gives the mapping between XML Namespace prefixes and XML Namespace URIs. If left blank, the Signature Parent Element and Signature Next Sibling path expressions cannot contain namespace prefixes. The XML Namespace Provider is also used to choose a prefix for the Signature elements. If the http://www.w3.org/2000/09/xmldsig# namespace is not found, the generated Signature element will re-declare the default namespace to this URI.

The Signature Parent Element is an XPath expression pointing to the element where the ds:Signature element will be inserted.

The Signature Next Sibling is an XPath expression that points to a child of the parent element. The signature will be inserted before this node. If left blank, the signature is added as the last child of the parent.

When the Create Parent Element parameter is true, the parent element will be created if needed, but the XPath expression must adhere to the Restricted XPath syntax. When the Create parent Element parameter is false, the parent element must exist but the expression may adhere to the full syntax of the XPath engine selected by the XPath VersionXPath Syntax parameter.

Key Info

Parameter Name

Description

Include Issuer Serial

Determines whether the X509IssuerSerial element is included in the KeyInfo X509Data element. Select true or false (default) from the drop-down list.

Include Subject Name

Determines whether the X509SubjectName element is included in the KeyInfo X509Data element. Select true (default) or false from the drop-down list.

Include Certificate Chain

Determines how much of the signer certificate chain is included in the KeyInfo X509Data element. Select one of the following values from the drop-down list:

  • Complete Certificate Chain {complete}
  • Signer Certificate Only {signer} (default)
  • No Certificates {none}

Include WSSE Security Token Reference

Determines whether a WSSE SecurityTokenReference is included in the KeyInfo element. Select true or false (default) from the drop-down list.

WSSE Security Token Id

The value of the BinarySecurityToken ID attribute referenced by the WSSE SecurityTokenReference. If left blank, the default value is x509_signer.

These parameters determine the content of the generated KeyInfo element. They can be used alone or in any combinations. If none of the parameters are used, the KeyInfo element will not appear.

The Include Issuer Serial boolean parameter determines whether a KeyInfo/X509Data/X509IssuerSerial element is generated. This element uniquely describes the signer certificate by listing the Issuer DN and the certificate Serial Number.

The Include Subject Name boolean parameter determines whether a KeyInfo/X509Data/X509SubjectName element is generated. This element contains the signer certificate subject DN.

The Include Certificate Chain parameter determines how many certificates in the certificate chain are included in the KeyInfo. The choices are: no certificates, just the signer certificate, or all certificates. Each certificate is base64 encoded in a separate KeyInfo/X509Data/X509Certificate element.

The Include WSSE Security Token Reference parameter determines whether a KeyInfo/SecurityTokenReference element is generated to point to a previously generated WSSE Binary Security Token. If on, the WSSE Security Token Id parameter specifies the Id of the existing Binary Security Token. The InsertWSSETokenAgent is a convenient way to pre generate the Binary Security Token. In that case, the Security Token Id can be retrieved with the expression SREG(wsse_token_id).

ID Attributes

Parameter Name

Description

Signature Id

The value of the Signature Id Attribute. If left blank, the generated Signature element will not have an Id attribute.

SignatureValue Id

The value of the SignatureValue Id Attribute. If left blank, the generated SignatureValue element will not have an Id attribute.

SignedInfo Id

The value of the SignedInfo Id Attribute. If left blank, the generated SignedInfo element will not have an Id attribute.

KeyInfo Id

The value of the KeyInfo Id Attribute. If left blank, the generated KeyInfo element will not have an Id attribute.

ID Attributes

Space-separated list of attributes that are considered type ID. The value of an ID attribute can be used in a same-document reference with a URI of the form #idvalue. Each attribute declaration has the form 

ns:*/@ns1:attrib

or 

@ns1:attrib

In this declaration, ns: and ns1: are optional. If used, the ns and ns1 prefixes must be declared in the XML Namespace Provider parameter.

The form @ns1:attrib means an attribute named attrib in XML Namespace ns1. The form ns:*/@ns1:attrib is similar except the attribute must also appear on an element of any name in the XML Namespace ns. The default value is: 

xml:id ds:*/@Id wsu:Id

The Signature Id, SignedInfo Id, SignatureValue Id and KeyInfo Id parameters specify the value of the Id attribute on the Signature, Signature/SignedInfo, Signature/SignatureValue and Signature/KeyInfo elements respectively. If left blank, the Id attribute will not appear.

The ID Attributes parameter is a space-separated list of attributes that are considered type ID. The value of an attribute can be used in a same-document reference with a URI of the form #idvalue but only if it declared of type ID. This parameter performs this type assignment. Each attribute declaration has the form ns:*/@ns1:attrib or @ns1:attrib where ns: and ns1: are optional. If used, the ns and ns1 prefixes must be declared in the XML Namespace Provider. The form @ns1:attrib means an Attribute named attrib in XML Namespace ns1. The form ns:*/@ns1:attrib is similar except the attribute must also appear on an element of any name in the XML Namespace ns. The default value is: xml:id ds:*/@Id wsu:Id. The namespace prefix actually used is not important. Only the namespace URI is used to find a match.

Reference 1

Parameter Name

Description

Reference 1 URI

URI to the first piece of data that will be digested and signed. If the left blank, the whole XML document will be digested and signed.

Reference 1 Digest Method

Digest algorithm applied to the first reference data (after Transforms are applied if specified) to yield the DigestValue.

Reference 1 Transform 1

First transform algorithm to apply to the first reference data.

Reference 1 Transform 1 Parameters

Parameters for the first transform algorithm to apply to the first reference data. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes. For XSLT, this is the name of a defined transform. For XPathFilter, this is an XPath expression. For XPathFilter2, this is the string intersect, subtract or union, followed by an XPath expression. For more XPathFilter2 XPathType clauses, create user parameters called ref1transform1parms[Z], ref1transform1parms[Z]nsmap where Z >= 2.

Reference 1 Transform 1 XML Namespace Provider

Provider for the XML Namespace Map for XPathFilter and XPathFilter2 transforms.

Reference 1 Transform 2

Second transform algorithm to apply to the first reference data.

Reference 1 Transform 2 Parameters

Parameters for the second transform algorithm to apply to the first reference data. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes. For XSLT, this is the name of a defined transform. For XPathFilter, this is an XPath expression. For XPathFilter2, this is the string intersect, subtract or union, followed by an XPath expression. For more XPathFilter2 XPathType clauses, create user parameters called ref1transform2parms[Z], ref1transform2parms[Z]nsmap where Z >= 2.

Reference 1 Transform 2 XML Namespace Provider

Provider for the XML Namespace Map for XPathFilter and XPathFilter2 transforms.

The reference URIs supported are: <empty string> for the whole XML document; #idattrib for the same-document sub-tree rooted at the element that has an ID attribute with value idattrib; cid:contentid for the attachment that has a Content-ID header with value <contentid>; http://host:port/page for the resource located at this HTTP address, and possibly other URLs built-in to the JDK 1.6.

The Reference 1 URI parameter is the URI to the first piece of data that will be digested and signed. If the left blank, the whole XML document will be digested and signed.

The Reference 1 Digest Method is the digest algorithm applied to the reference data (after Transforms are applied if specified) to yield the DigestValue. The choices are the full URI corresponding to sha1, sha256, or sha512.

The Reference 1 Transform 1 is the first transform algorithm to apply to the reference data. The Reference 1 Transform 1 Parameters contain the parameters for the transform.

The Reference 1 Transform 2 is the second transform and Reference 1 Transform 2 Parameters specify its parameters.

Reference 2

Parameter Name

Description

Reference 2 URI

URI to the second piece of data that will be digested and signed. If you need more references, create user parameters named ref[X]uri, ref[X]digest, ref[X]transform[Y], ref[X]transform[Y]parms[Z] where X >= 3, Y >= 1, Z >= 1.

For example, ref3transform2 is the second transform of the third reference.

Reference 2 Digest Method

Digest algorithm applied to the second reference data (after Transforms are applied if specified) to yield the DigestValue.

Reference 2 Transform 1

First transform algorithm to apply to the first reference data.

Reference 2 Transform 1 Parameters

Parameters for the first transform algorithm to apply to the second reference data. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes. For XSLT, this is the name of a defined transform. For XPathFilter, this is an XPath expression. For XPathFilter2, this is the string intersect, subtract or union, followed by an XPath expression. For more XPathFilter2 XPathType clauses, create user parameters called ref2transform1parms[Z], ref2transform1parms[Z]nsmap where Z >= 2.

Reference 2 Transform 1 XML Namespace Provider

Provider for the XML Namespace Map for XPathFilter and XPathFilter2 transforms.

Reference 2 Transform 2

Second transform algorithm to apply to the second reference data.

Reference 2 Transform 2 Parameters

Parameters for the second transform algorithm to apply to the second reference data. For Exclusive Canonical XML, this is a space-separated list of XML namespace prefixes. For XSLT, this is the name of a defined transform. For XPathFilter, this is an XPath expression. For XPathFilter2, this is the string intersect, subtract or union, followed by an XPath expression. For more XPathFilter2 XPathType clauses, create user parameters called ref2transform1parms[Z], ref2transform2parms[Z]nsmap where Z >= 2.

Reference 2 Transform 2 XML Namespace Provider

Provider for the XML Namespace Map for XPathFilter and XPathFilter2 transforms.

Subsequent references 2, 3, ... are similar to reference 1 except a missing reference URI indicates the end of the list of references instead of the whole document.

The list of transforms per reference is not limited to 2. Any number of transforms can be specified using user parameters.

The list of references is not limited to 2. Any number of references can be specified using user parameters.

The following table lists the transforms available. Some transforms have implicit parameters and do not require any explicit parameters. Other transforms take parameters as described in the table.

Transforms Available to Digital Signature Service

Attachment Complete Signature Transform

http://docs.oasis-open.org/wss/oasis-wss-SwAProfile-1.1#Attachment-Complete-Signature-Transform

This transform indicates that both the content and selected headers of the MIME part are referenced for signing.

The following MIME headers are to be included(when present):

  • Content-Description
  • Content-Disposition
  • Content-ID
  • Content-Location
  • Content-Type

This transform takes no explicit parameters.

Attachment Content Signature Transform

http://docs.oasis-open.org/wss/oasis-wss-SwAProfile-1.1#Attachment-Content-Signature-Transform

This transform indicates that only the content of the MIME part is referenced for signing. All of the MIME headers associated with the MIME part are ignored and not included in the output octet stream.

This transform takes no explicit parameters

Base64

http://www.w3.org/2000/09/ xmldsig#base64

This transform decodes the Base64 encoded character data. If the input is a node-set, then the string-value of the node-set is decoded (ignoring the element tags, comments and processing instructions).

This transform takes no explicit parameters.

Enveloped Signature

http://www.w3.org/2000/09/ xmldsig#enveloped-signature

This transform removes the Signature element from the calculation of the signature when the signature is within the content that it is being signed.

This transform takes no explicit parameters.

Exclusive Canonical XML

http://www.w3.org/2001/10/xml-exc-c14n#

This transform is useful when message parts can be enveloped and stripped off to construct new messages. Exclusive Canonical XML ignores the namespace context inherited from parent elements. This keeps the digested data constant despite these operations.

This transform takes an optional space-separated list of XML namespace prefixes declared in the XML Namespace provider. These are additional prefixes to be ignored.

Exclusive Canonical XML With Comments

http://www.w3.org/2001/10/xml-exc-c14n#WithComments

This transform is similar to Exclusive Canonical XML except comments are preserved in the digested data.

This transform takes an optional space-separated list of XML namespace prefixes declared in the XML Namespace provider. These are additional prefixes to be ignored.

XPathFilter

http://www.w3.org/TR/1999/REC-xpath-19991116

This transform evaluates the XPath expression for each node in the input node-set and keeps only the nodes where the expression evaluated to true.

This transform takes the XPath expression in ref[X]transform[Y]parms1 and optionally an XML Namespace provider name in ref[X]transform[Y]parms1nsmap to declare a namespace map.

XPathFilter2

http://www.w3.org/2002/06/ xmldsig-filter2

This transform computes a filter node-set. The output is the intersection of the input node-set and the filter node-set. The filter node-set is computed by evaluating a sequence of XPath expressions and combining their result by intersection, subtraction or union.

Each XPathType can be declared by a pair of parameters: ref[X]transform[Y]parms[Z] and optionally ref[X]transform[Y]parms[Z]nsmap. ref[X]transform[Y]parms[Z] must start with the string intersect, subtract or union, followed by an XPath expression. ref[X]transform[Y]parms[Z]nsmap if present must be the name of an XML Namespace Provider to declare the Namespace map for this XPathType.

XSLTTransform

http://www.w3.org/TR/1999/REC-xslt-19991116

This transform indicates an XSLT stylesheet must be used and the result is what is referenced for signing.

This transform takes the name of a defined transform as parameter (similar to what is done with the XDGenTransform service). The defined transform must be an XSLT transform and return XML.

Inclusive Canonical XML

http://www.w3.org/TR/2001/REC-xml-c14n-20010315

This transform performs typical XML Canonicalization that attracts the xml namespace declarations from the inherited context. This canonicalization is the default if the last transform returns a node-set. This transform takes no parameters.

Inclusive Canonical XML With Comments

http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments

This transform is similar to Inclusive Canonical XML except comments are preserved.

This transform takes no parameters.

If you need more references, create user parameters named ref[X]uri, ref[X]digest, ref[X]transform[Y], ref[X]transform[Y]parms where X >= 3 and Y >= 1, for example, ref3transform2 is the second transform of the third reference.

When the Tree level is selected in the trace settings, the service will log the referenced data that was actually digested.

Edges:

The following table lists and describes the edges that are returned by the XML Digital Signature Create service.

Edge

Description

success

The Signature was successfully inserted.

fail_parse

An iFL or XPath expression could not be evaluated.

fail_operation

The Signature could not be inserted.
x
Examples

The examples in this section are specific to the XML Digital Signature Create service. For your convenience, the sample input and output documents are attached to the PDF in unabbreviated form.

For PDF-compatibility purposes, the file extension of the xmldsig.zip file is temporarily renamed to .zap. After saving this file to your file system, you must rename this extension back to .zip before the file can be used.
x
Example 1: Enveloped Signature

The following example is a very simple Signature. There is only one reference that englobes the whole document. Since the Signature element will be covered by the reference, it needs to be removed by the Enveloped Signature Transform. The signing key is the private key entry at alias alias1 within the keystore specified by the KeyStore Provider ksprov. The KeyInfo mentions the Subject Name to help the verifier retrieve the signer certificate from a certificate store. The Subject Name is convenient for users but the Issuer Name and Serial Number would have made the certificate retrieval less ambiguous. Notice the use of the Signature Next Sibling parameter to insert the Signature before the current first child of the root element. By default, the Signature element would appear as the last child of the root element instead. Since the default empty reference URI is used to sign the whole document, you must also specify the Enveloped Signature transform.

This table lists the parameter values for this example. Other parameters that are not listed have their default value.

Parameter

Value

XML Digital Signature JCE Provider

XMLDSig

Canonicalization Method

http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Signature Method

http://www.w3.org/2000/09/xmldsig#rsa-sha1

KeyStore Provider

ksprov

Signing Key Alias

alias1

Signing Key Password

secret

Signature Next Sibling

/*/*[1]

Include Subject Name

true

Include Certificate Chain

No Certificates

Reference 1 Transform 1

http://www.w3.org/2000/09/xmldsig#enveloped-signature

A sample input document is shown as follows (indented for display purposes only):

A sample output of the service is shown as follows (indented for display purposes only):
x
Example 2: Simple SOAP Message

The following example shows how to sign a SOAP message by inserting a digital signature in the SOAP Header. The WSSE Security profile suggests to create separate References for SOAP header blocks and the SOAP Body. Since our sample input document does not have a SOAP Header, a single reference to the SOAP Body is all that is required. Since the Body is a fragment of the whole document, it is recommended to apply an Exclusive Canonical XML transform. The reference URL has the form #id, where the id is the value of an ID attribute on the referenced node. By default, the service recognizes these ID attributes: xml:id, ds:Id, wsu:Id. In the sample input document below, the ID attribute on the SOAP Body is wsu:Id. Since this ID attribute is recognized by default, you do not need to declare a new ID attribute in the ID Attributes parameter. The path to the parent element of the Signature contains elements in namespaces, so an XML Namespace provider is necessary to define the prefixes used in the XPath expression. The SOAP Header element will be created automatically because the service is instructed to create the parent element. The syntax *[1]/self::soapenv:Header instructs the Restricted XPath engine to create the Header element as the first child of the SOAP Envelope before the Body element. The signing key is the private key entry at alias alias1 within the keystore specified by the KeyStore Provider ksprov. The KeyInfo contains the Issuer Name and Serial Number to unambiguously specify the signing certificate. The verifier will need to retrieve that certificate from a certificate store to verify the Signature.

It is assumed the XML Namespace provider xmlnsprov defines these prefixes:

Prefix

XML Namespace

soapenv

http://schemas.xmlsoap.org/soap/envelope/

wsse

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd

This table lists the parameter values for this example. Other parameters that are not listed have their default value.

Parameter

Value

XML Digital Signature JCE Provider

XMLDSig

Canonicalization Method

http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Signature Method

http://www.w3.org/2000/09/xmldsig#rsa-sha1

KeyStore Provider

ksprov

Signing Key Alias

alias1

Signing Key Password

secret

XML Namespace Provider

xmlnsprov

Create Parent Element

true

Signature Parent Element

/soapenv:Envelope/*[1]/self::soapenv:Header/wsse:Security

Include Issuer Serial

true

Include Subject Name

false

Include Certificate Chain

No Certificates

Reference 1 URI

#bodyid

Reference 1 Digest Method

http://www.w3.org/2000/09/xmldsig#sha1

Reference 1 Transform 1

http://www.w3.org/2001/10/xml-exc-c14n#

A sample input document is shown as follows (indented for display purposes only):

A sample output of the service is shown as follows (indented for display purposes only):
x
Example 3: WSSE SecurityTokenReference

The following is an example of a signature over the SOAP Body with a WSSE SecurityTokenReference in the KeyInfo pointing to a WSSE BinarySecurityToken previously generated in the SOAP Header. The security token and the digital signature appear in the same wsse:Security Header block. The signature has two references, one for the BinarySecurityToken in the header, and another for the SOAP Body.

The XDInsertWSSETokenAgent can create the BinarySecurityToken in the SOAP Header. For more information about the XDInsertWSSETokenAgent and an example, see Insert WSSE Token Service. The output of the XDInsertWSSETokenAgent example will be used as the input document of this digital signature example.

The following table lists the parameter values of the XDXMLDSigCreateAgent for this example.

Parameter

Value

XML Digital Signature JCE Provider

XMLDSig

Canonicalization Method

http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Signature Method

http://www.w3.org/2000/09/xmldsig#rsa-sha1

KeyStore Provider

ksprov

Signing Key Alias

alias1

Signing Key Password

secret

XML Namespace Provider

xmlnsprov

Create Parent Element

false

Signature Parent Element

/soapenv:Envelope/soapenv:Header/wsse:Security

Include Subject Name

false

Include Certificate Chain

No Certificates

Include WSSE Security Token Reference

true

WSSE Security Token Id

tokenid

Reference 1 URI

#tokenid

Reference 1 Digest Method

http://www.w3.org/2000/09/xmldsig#sha1

Reference 1 Transform 1

http://www.w3.org/2001/10/xml-exc-c14n#

Reference 2 URI

#bodyid

Reference 2 Digest Method

http://www.w3.org/2000/09/xmldsig#sha1

Reference 2 Transform 1

http://www.w3.org/2001/10/xml-exc-c14n#

The input document is shown as follows (indented for display purposes only):

The output of the XMLDSigCreateAgent is shown as follows (indented for display purposes only):
x
Example 4: Signed Attachment

The following example shows how to sign a MIME attachment. Assume that the Body of the XML document refers to the attachment, and therefore both must be signed. This requires at least two references, one for the Body and another for the attachment. The Reference URI to point to an attachment has the form cid:contentid. The cid URI scheme instructs the Reference to find the attachment with the Content-ID equal to <contentid>. The angle brackets are absent in the URI but must be present in the Content ID header. The Reference must choose one of the attachment transforms. The Attachment Complete Signature Transform (http://docs.oasis-open.org/wss/oasis-wss-SwAProfile-1.1#Attachment-Complete-Signature-Transform) indicates that the content and selected headers of the MIME part are referenced for signing, whereas, the Attachment Content Signature Transform (http://docs.oasis-open.org/wss/oasis-wss-SwAProfile-1.1#Attachment-Content-Signature-Transform) indicates that only the content of a MIME part is referenced for signing.

An attachment can be associated with a document directly from external input (for example, by the NHTTP listener reading an HTTP request), or with the help of one the attachment services (XDAddAttachmentAgent or XDAddAttachmentFromFileAgent). In this example, the XDAddAttachmentFromFileAgent is called to attach a JPEG image to the document. The binary Content-Transfer-Encoding is chosen to take advantage of the more compact format compared to what is possible within an XML document. Notice the explicit angle brackets in the value of the Content-ID parameter. These are part of the Content-ID syntax.

The following table lists the parameter values for the XDAddAttachmentFromFileAgent. Other parameters that are not listed have their default value.

Parameter

Value

Input File

pic.jpg

Content-Type

image/jpeg

Content-Transfer-Encoding

binary

Content-Disposition

attachment; filename=pic.jpg

Content-ID

<pic>

The following table lists the parameter values for the XMLDSigCreateAgent. Other parameters that are not listed have their default value.

Parameter

Value

XML Digital Signature JCE Provider

XMLDSig

Canonicalization Method

http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Signature Method

http://www.w3.org/2000/09/xmldsig#rsa-sha1

KeyStore Provider

ksprov

Signing Key Alias

alias1

Signing Key Password

secret

XML Namespace Provider

xmlnsprov

Create Parent Element

true

Signature Parent Element

/soapenv:Envelope/*[1]/self::soapenv:Header/wsse:Security

Include Subject Name

true

Include Certificate Chain

No Certificates

Reference 1 URI

#bodyid

Reference 1 Digest Method

http://www.w3.org/2000/09/xmldsig#sha1

Reference 1 Transform 1

http://www.w3.org/2001/10/xml-exc-c14n#

Reference 2 URI

cid:pic

Reference 2 Digest Method

http://www.w3.org/2000/09/xmldsig#sha1

Reference 2 Transform 1

http://docs.oasis-open.org/wss/oasis-wss-SwAProfile-1.1#Attachment-Complete-Signature-Transform

The input document of the XDAddAttachmentFromFileAgent is shown as follows (indented for display purposes only):

The output of the XDAddAttachmentFromFileAgent is used as the input of the XMLDSigCreateAgent. When the resulting document is sent by the XDXNHTTPEmitAgent, the HTTP request has the following structure (indented for display purposes only):
x
Example 5: Signature Transform Parameters

The following example shows how to specify a complex Signature Transform. In particular, it shows how user parameters are required to specify extra transform parameters. It also proves the transform worked by enabling the debugging aid to view the data digested by each Reference.

The Signature XPath Filter 2.0 Transform takes a sequence of one or more elements named XPath. The text value of the XPath element is an XPath expression. The XPath element has an attribute called Filter that specifies the set operation to apply to the node-set returned by the XPath expression. The possible values are intersect, subtract, or union.

The following is a sample XPath Filter 2.0 transform:

In the service configuration, each transform parameter becomes one XPath element. The parameter value consists of the chosen set operation followed by the XPath expression separated by a space. For example, the first XPath element above is configured with the following value:

intersect //ToBeSigned

If the XPath expression contains XML namespaces, the XML Namespace provider is specified in another related parameter. Because this transform can take more than one parameter, the extra parameters must be entered as user parameters. The name of the parameter contains an index to specify which reference and which transform it belongs to.

To simplify, this example signs the whole document and therefore requires the Enveloped Signature transform. The XPath Filter 2.0 transform becomes the second transform of the first Reference. The location of the Signature element is not specified, therefore it will appear as the last child of the root element.

The following table lists the parameter values of the XMLDSigCreateAgent. Other parameters that are not listed have their default value.

Parameter

Value

XML Digital Signature JCE Provider

XMLDSig

Canonicalization Method

http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Signature Method

http://www.w3.org/2000/09/xmldsig#rsa-sha1

KeyStore Provider

ksprov

Signing Key Alias

alias1

Signing Key Password

secret

Include Subject Name

true

Include Certificate Chain

No Certificates

Reference 1 URI

 

Reference 1 Digest Method

http://www.w3.org/2000/09/xmldsig#sha1

Reference 1 Transform 1

http://www.w3.org/2000/09/xmldsig#enveloped-signature

Reference 1 Transform 2

http://www.w3.org/2002/06/xmldsig-filter2

Reference 1 Transform 2 Parameters

intersect //ToBeSigned

The extra transform parameters are specified with these user parameters. The parameter name and the value must be entered as shown in the following table.

Parameter

Value

ref1transform2parms2

subtract //NotToBeSigned

ref1transform2parms3

union //ns1:ReallyToBeSigned

ref1transform2parms3nsmap

ns1prov

This example assumes there is an XML Namespace provider called ns1prov that defines a single mapping: alias ns1 to namespace http://ns1.com. The input document is shown in the following image (indented for display purposes only):

The following image shows the output of the service (indented for display purposes only):

To prove that the transform worked, you can enable logging at the Tree level. You should see a message similar to the following in your log:

TREE (W.file3.1) Digested input for signed reference '':
<ToBeSigned> <Data></Data><ns:ReallyToBeSigned
xmlns:ns="http://ns1.com"><Data></Data></ns:ReallyToBeSigned>
</ToBeSigned><ToBeSigned><Data></Data></ToBeSigned>

The Reference URI is shown within single quotes. In this case, the Reference URI was empty because the whole document is signed.

iWay Software