XMLDSigCreateAgent

The XDXMLDSigCreateAgent is used to generate an XML Digital Signature.

The following table lists and describes XDXMLDSigCreateAgent parameters.

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.

Signature Key

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.

Signature Location

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.

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, the signature parent is the root element. If the Create Parent Element parameter is set to true, the XPATH expression must be of the form /comp1/comp2/... where each path component has the following form:

ns:elem[@ns1:attrib="attribValue"]

The ns: and ns1: namespace prefixes are optional, but if present they must be declared in the XML Namespace Provider parameter. The selector in square brackets is optional. If no element with a matching attribute is found and Create Parent Element is true, then both the element and the attribute will be created.

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.

Key Info

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.

ID Attributes

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

Reference 1

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.

Reference 2

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.

The parameters can be divided into the following groups: signature algorithm, signing key, parent element, KeyInfo content, Id Attributes, and References.

The signature algorithm parameters are:

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.

The signing key parameters are:

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.

The parent element parameters are:

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 redeclare the default namespace to this URI.

The Create Parent Element parameter is a boolean. If true, the Signature Parent Element will be created when missing from the XML document. To make the creation of the parent possible, the Signature Parent Element must be a restricted XPATH expression. For more information, see Restricted XPATH Expressions. If false, the Signature Parent Element can be any XPATH 1.0 expression, but the element must already exist in the XML document.

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.

The KeyInfo content parameters are:

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)

The Id Attribute parameters are:

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.

The Reference parameters are:

...

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. Many transforms have implicit parameters and do not require any explicit parameters. For Exclusive Canonical XML, this is a space separated list of XML namespace prefixes.

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

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.

Transforms Available to Digital Signature Agent

XPathFilter

The user must provide 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

Each XPathType can be declared by a pair of parms: 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

The parms to the transform is the name of a defined transform (similar to what is done with the XDGenTransform agent). The defined transform must be an XSLT transform and return XML.

Attachment Content Signature Transform

No parameters are required.

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 debug level is on, the agent will show the referenced data that was digested.

The following is an example of a signature over the entire document with some X509 information under the Signature/KeyInfo/X509Data element.

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


iWay Software