Software AG Products 10.7 | Integrating On-Premises and Cloud Applications | Integration Server Built-In Services | Security Folder | Summary of Elements in this Folder | pub.security.xml:signXML
 
pub.security.xml:signXML
WmPublic. Digitally sign an outgoing XML node or document.
Input Parameters
xmldata
String Optional. XML that needs to be signed.
xmlStream
InputStream Optional. Input stream containing the XML that needs to be signed.
Note:
If both xmldata and xmlStream are provided, xmlStream takes precedence.
uri
String Optional. URI to the element to be signed.
In combination with the nodeSelectors parameter, the uri identifies the nodes to be signed.

noNamespace SchemaLocation
String Optional. A URI that identifies the location of the XML schema definition that contains the ID attribute specified in uri.
Provide a noNamespaceSchemaLocation when specifying an ID attribute for uri and the ID attribute resides in an XML schema with no namespaces.
schemaLocations
Document Optional. Document (IData) containing name-value pairs for the XML namespace and the location of the XML schema definition that contains element declarations, attribute declarations, and type definitions for that namespace.
Provide a schemaLocation when specifying an ID attribute for uri and the ID attribute resides in an XML schema for a particular namespace.
For example,
*XML namespace = http://www.w3schools.com
*XML schema definition location = file:C:/note.xsd
nodeSelectors
String List XPath notation that identifies the nodes to be signed. The locations of the XPaths are not absolute, but relative, and work within the context of the node (an XPath Axes).
Important:
Do not use absolute location XPaths here.
nsDecls
Document Optional. Mapping of the namespace prefixes to the namespace URIs. The first column contains the prefixes and the second column contains the corresponding URIs.
isEnveloped
String Optional. Indicates whether the signature is enveloped or enveloping. Set to:
*True to indicate that the generated signature will be enveloped. This is the default.
*False to indicate that the generated signature will be enveloping, provided the isDetached parameter is set to False.
Unlike the detached signature, which is kept apart from the original document, enveloping and enveloped signatures are tightly coupled with the original document.
isDetached
String Optional. Indicates whether the signature is detached or not.
Integration Server uses <detached-signature> as the container for signature and the XML to be signed.
Set to:
*True to indicate that the generated signature will be detached.
*False to indicate that the generated signature will be enveloping or enveloped, based on the isEnveloped parameter setting. This is the default.
Note: 
*Setting isDetached to True and isEnveloped to False, indicates that the signature will be detached.
*Setting isDetached to False and isEnveloped to True, indicates that the signature will be enveloped.
*Setting isDetached to False and isEnveloped to False, indicates that the signature will be enveloping.
*Setting isDetached to True and isEnveloped to True, results in error.
signatureNodeSelector
String Optional. XPath to the node where the signature is entered. Applicable only for enveloped signatures. If no value is provided, the signature is placed as a first child of the root node.
signatureAlgorithm
String Optional. Signature algorithm to use when signing the XML node or document. Specify one of the following or use the default value (first algorithm):
*SHA1 (default)
*SHA256
*SHA384
*SHA512
digestAlgorithm
String Optional. Digest algorithm to use when signing the XML node or document. Specify one of the following or use the default value (first algorithm):
*SHA1 (default)
*SHA256
*SHA384
*SHA512
canonicalizationAlgorithm
String Optional. Canonical algorithm used with the XML. Specify one of the following or use the default value (first algorithm):
*http://www.w3.org/TR/2001/rec-xml-c14n-20010315 (default)
*http://www.w3.org/TR/2001/rec-xml-c14n-20010315#WithComments
*http://www.w3.org/2001/10/xml-exc-c14n#
*http://www.w3.org/2001/10/xml-exc-c14n#WithComments
signatureId
String Optional. ID attribute for the signature node.
keyStoreAlias
String Optional. Name (alias) of the keystore that contains the private key/certificate.
keyAlias
String Optional. Name (alias) of the private key, contained in the keystore specified by the keyStoreAlias parameter, that is used for signing.
keyName
String Optional. Name that is used by the signer to communicate a key identifier to the recipient.
includeKeyValue
String Optional. Indicates whether to include the key value (RSAKeyValue or DSAKeyValue), based on the certificate used for signing. The KeyValue element contains a single public key that can be used in validating the signature.
Set to:
*True to include the key value (RSAKeyValue or DSAKeyValue) based on the certificate used for signing.
*False to exclude the key value from the signature.
includeCertChain
String Optional. Indicates whether the certificate chain should be included in the signature. Set to:
*True to include the certificate chain in the signature.
*False to leave the certificate chain out of the signature. This is the default.
certData
String List Optional. Select the X509 certificate data to be entered into the signature's key information.
*X509_CERTIFICATE (default)
*X509_SUBJECT_NAME
*X509_ISSUER_SERIAL
*X509_SKI
*X509_CRL
Note that the initials "SKI" and "CRL"in denote "Subject Key Identifier" and Certificate Revocation List".
idXmlObject
String Optional. Specifies the ID for the node that holds the original XML that is signed. Applicable only for enveloping signatures.
encoding
String Optional. Specifies the encoding to use if the encoding cannot be extracted from the XML. If encoding is not specified in the XML document or in the encoding parameter, Integration Server uses UTF-8.
The encoding value must be a valid IANA encoding.
addSignatureAsLastElement
Boolean Optional. When isEnveloped is set to True, this parameter indicates the position at which Integration Server should add the signature element child to the root.
Set to:
*True to add the signature element as the last child of the root.
*False to add the signature element as the first child of the root. This is the default.
addDSPrefixToSignature
Boolean. Optional. Set to False to create a Signature element in the signed XML without any prefixes. By default, this input variable is set to True and the "ds:" prefix is added.
Output Parameters
signedXMLData
String Conditional. Signed XML data. signedXMLData is returned when xmlData is provided.
signedXMLStream
OutputStream Conditional. Signed XML in the form of an OutputSream. signedXMLStream is returned when xmlStream is provided.
Usage Notes
Before the signing/signature verification of XML can occur between Integration Server and an external system, the Integration Server must share the public key that corresponds to the private key with which the document is signed. Integration Server must share the public key with the external system that will be performing verification.
keyAlias and keyStoreAlias should either both be provided or both be absent from the input. If no value is provided for these parameters, Integration Server uses the private key/certificate specified for the Signing Key. If the Signing Key is not specified, Integration Server uses the SSL Key.
For information about configuring the Signing Key and SSL Key keystore aliases using the Security > Certificates page in Integration Server Administrator, refer to webMethods Integration Server Administrator’s Guide.
If both xmldata and xmlStream are provided, xmlStream takes precedence.
The uri and nodeSelectors parameters identify the nodes to be signed.
If uri is specified and nodeSelectors is not specified, Integration Server signs the entire node identified by uri.
If uri and nodeSelectors are specified, Integration Server determines which nodes to sign by locating the node specified by the uri and then applying the filter from nodeSelectors.
If uri is not specified and nodeSelectors is specified, Integration Server determines which nodes to sign by applying the filter in nodeSelectors to the entire XML.
If neither uri nor nodeSelectors are specified, Integration Server signs the entire XML.
You can use the value of an ID attribute as the uri.
For example, #sampleID
Where sampleID is an ID attribute that functions as a unique identifier for an element in an XML schema definition. In this example, Integration Server will locate the node with the ID attribute "sampleID" and then apply the filter specified by nodeSelectors to determine which nodes to sign.
Signature Types
As opposed to a detached signature, which is kept apart from the original document, enveloping and enveloped signatures are tightly coupled with the original document.
An enveloping signature must be a parent node of the data being signed:
<!-- Example of Enveloping Signature --> <Signature>
<my_document>. . . </my_document> </Signature>
The following input parameters and values are applicable only to enveloping signatures:
*isEnveloped. Specify a value of "false" for enveloping. If isEnveloped is set to false, then:
*If both uri and idXmlObject are null, Integration Server creates a dynamic unique value for both uri and idXmlObject and signs the XML.
*If idXmlObject is provided and uri is null, Integration Server creates a uri with a value of #idXmlObject_value and signs the XML.
*If both and uri and idXmlObject are provided and match the XML contract (for example, uri='#idXmlObject'), Integration Server signs the XML. If the uri and idXmlObject parameters do not match the contract, Integration Server issues an exception.
*idXmlObject. Specifies the ID for the node that holds the original, signed XML.
An enveloped signature must be a child node of the data being signed:
<!-- Example of Enveloped Signature --> <my_document>
<Signature> . . . </Signature> </my_document>
The following parameters and values are applicable only to enveloped signatures:
*isEnveloped. The default value of "true" specifies that the signature is enveloped.
*signatureNodeSelector. XPath to the node where the signature is entered. If no value is provided, the signature is placed as a first child of the root node.
Signing and Encrypting the Same XML Document
You can use both encryption and signing in the same XML document.
*If you sign and encrypt different XML elements in a document, you can run either pub.security.xml:signXML or pub.security.xml:encryptXML first.
*Typically, if you sign and encrypt the same XML elements in a document, you should sign the elements before encrypting them. That is, invoke pub.security.xml:signXML before invoking pub.security.xml:encryptXML.