Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 138. XML Security component

XML Security component

Available as of Camel 2.12.0
With this Apache Camel component, you can generate and validate XML signatures as described in the W3C standard XML Signature Syntax and Processing or as described in the successor version 1.1. For XML Encryption support, please refer to the XML Security Data Format.
You can find an introduction to XML signature here. The implementation of the component is based on JSR 105, the Java API corresponding to the W3C standard and supports the Apache Santuario and the JDK provider for JSR 105. The implementation will first try to use the Apache Santuario provider; if it does not find the Santuario provider, it will use the JDK provider. Further, the implementation is DOM based.
Maven users will need to add the following dependency to their pom.xml for this component: 
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-xmlsecurity</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

XML Signature wrapping modes

XML Signature differs between enveloped, enveloping, and detached XML signature. In the enveloped XML signature case, the XML Signature is wrapped by the signed XML Document; which means that the XML signature element is a child element of a parent element, which belongs to the signed XML Document. In the enveloping XML signature case, the XML Signature contains the signed content. All other cases are called detached XML signatures. Detached XML signature are not supported in the current implementation.
In the enveloped XML signature case, the supported generated XML signature has the following structure (Variables are surrounded by []). 
    <[parent element]>
       ... <!-- Signature element is added as last child of the parent element-->
       <Signature Id="generated_unique_signature_id">
           <SignedInfo>
                 <Reference URI=""> 
                       <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                       (<Transform>)* <!-- By default "http://www.w3.org/2006/12/xml-c14n11" is also added to the transforms -->
                       <DigestMethod>
                       <DigestValue>
                 </Reference>
                 (<Reference URI="#[keyinfo_Id]">
                       <Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
                       <DigestMethod>
                       <DigestValue>
                 </Reference>)?
                 <!-- further references possible, see option 'properties' below -->
          </SignedInfo>
          <SignatureValue>
          (<KeyInfo Id="[keyinfo_id]">)?
          <!-- Object elements possible, see option 'properties' below -->
      </Signature>
    </[parent element]>
In the enveloping XML signature case, the supported generated XML signature has the structure: 
    <Signature Id="generate_unique_signature_id">
      <SignedInfo>
             <Reference URI="#generated_unique_object_id" type="[optional_type_value]"> 
                   (<Transform>)* <!-- By default "http://www.w3.org/2006/12/xml-c14n11" is added to the transforms -->
                   <DigestMethod>
                   <DigestValue>
             </Reference>
             (<Reference URI="#[keyinfo_id]">
                   <Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
                   <DigestMethod>
                   <DigestValue>
             </Reference>)?
              <!-- further references possible, see option 'properties' below  -->
      </SignedInfo>
      <SignatureValue>
      (<KeyInfo Id="[keyinfo_id]">)?
      <Object Id="generated_unique_object_id"/> <!-- The Object element contains the in-message body -->
      <!-- Further Object elements possible, see option 'properties' below -->
    </Signature>

URI format

The camel component consists of two endpoints which have the following URI format. 
    xmlsecurity:sign:name[?options]
    xmlsecurity:verify:name[?options]
  • With the signer endpoint, you can generate a XML signature for the body of the in-message which can be either a XML document or a plain text. The enveloped or enveloping XML signature will be set to the body of the out-message.
  • With the verifier endpoint, you can validate a enveloped or enveloping XML signature contained in the body of the in-message; if the validation is successful, then the original content is extracted from the XML signature and set to the body of the out-message.
  • The name part in the URI can be chosen by the user to distinguish between different signer/verifier endpoints within one camel context.

Basic Example

The following example shows the basic usage of the component. 
    from("direct:enveloping").to("xmlsecurity:sign://enveloping?keyAccessor=#accessor",
                                 "xmlsecurity:verify://enveloping?keySelector=#selector","mock:result")
In Spring XML: 
    <from uri="direct:enveloping" />
      <to uri="xmlsecurity:sign://enveloping?keyAccessor=#accessor" />
      <to uri="xmlsecurity:verify://enveloping?keySelector=#selector" />
    <to uri="mock:result" />
For the signing process, a private key is necessary. You specify a key accessor bean which provides this private key. For the validation, the corresponding public key is necessary; you specify a key selector bean which provides this public key.
The key accessor bean must implement the KeyAccessor interface. The package org.apache.camel.component.xmlsecurity.api contains the default implementation class DefaultKeyAccessor which reads the private key from a Java keystore.
The key selector bean must implement the javax.xml.crypto.KeySelector interface. The package org.apache.camel.component.xmlsecurity.api contains the default implementation class DefaultKeySelector which reads the public key from a keystore.
In the example, the default signature algorithm http://www.w3.org/2000/09/xmldsig#rsa-sha1 is used. You can set the signature algorithm of your choice by the option signatureAlgorithm (see below). The signer endpoint creates an enveloping XML signature. If you want to create an enveloped XML signature then you must specify the parent element of the Signature element; see option parentLocalName for more details.

Common Signing and Verifying Options

There are options which can be used for both endpoints, signer and verifier.
Name Type Default Description
uriDereferencer javax.xml.crypto.URIDereferencer null URI dereferencer. You can specify here your own URI dereferencer, if you want to restrict the dereferencing or have special requirements for dereferencing.
baseUri String null Base URI used in the URI dereferencer. Relative URIs are concatenated with the base URI.
cryptoContextProperties Map<String, ? extends Object> null Crypto context properties. See javax.xml.crypto.XMLCryptoContext.setProperty(String, Object). The properties can depend on the provider. For example, the JDK provider "XMLDSig" has the property "org.jcp.xml.dsig.validateManifests" for enabling manifest validation. The following properties are set by default to the value Boolean.TRUE for the XML validation: "org.jcp.xml.dsig.validateManifests", "javax.xml.crypto.dsig.cacheReference". If you want to switch these features off you must set the property values to Boolean.FALSE.
disallowDoctypeDecl Boolean Boolean.TRUE Indicator whether DTD DOCTYPE declarations shall be disallowed in the incoming XML message.
omitXmlDeclaration Boolean Boolean.FALSE Indicator whether the XML declaration header shall be omitted in the output XML message.
clearHeaders Boolean Boolean.TRUE Indicator whether the XML signature message headers defined in XmlSignatureConstants shall be deleted at the end of the signer or verifier processing.

Signing Options

The signer endpoint has the following options.
Name Type Default Description
keyAccessor KeyAccessor null Provides the signing key and the KeyInfo instance. There is an example implementation which uses a keystore, see DefaultKeyAccessor
addKeyInfoReference Boolean Boolean.TRUE Indicator whether the KeyInfo element provided by the key accessor should be added to the XML signature.
signatureAlgorithm String http://www.w3.org/2000/09/xmldsig#rsa-sha1 signature algorithm consisting of a digest and encryption algorithm. The digest algorithm is used to calculate the digest of the SignedInfo element and the encryption algorithm is used to sign this digest. Which algorithm are supported depends on the JSR 105 provider (see option provider).
digestAlgorithm String see description Digest algorithm for calculating the digest of the in-message body. If not specified then the digest algorithm of the signature algorithm is used (e.g. http://www.w3.org/2001/04/xmlenc#sha256). Which digest algorithm can be used depends on the JSR 105 provider (see option provider).
parentLocalName String null Local name of the parent of the Signature element. The Signature element will be added at the end of the children of the parent. Necessary for enveloped XML signature. If this option is null, then an enveloping XML signature is created. See also option parentNamespace.
parentNamespace String null Namespace of the parent of the Signature element. See option parentLocalName
canonicalizationMethod javax.xml.crypto.AlgorithmMethod C14n Canonicalization method used to canonicalize the SignedInfo element before the digest is calculated. You can use the helper methods XmlSignatureHelper.getCanonicalizationMethod(String algorithm) or getCanonicalizationMethod(String algorithm, List<String> inclusiveNamespacePrefixes) to create a canonicalization method.
transformMethods List<javax.xml.crypto.AlgorithmMethod> see description Transforms which are executed on the message body before the digest is calculated. By default, C14n is added and in the case of enveloped signature (see option parentLocalName) also http://www.w3.org/2000/09/xmldsig#enveloped-signature is added at position 0 of the list. Use methods in XmlSignatureHelper to create the transform methods.
prefixForXmlSignatureNamespace String ds Prefix for the XML signature namespace. If null is specified or an empty string then no prefix is used for the signature namespace.
contentReferenceUri String see description The URI of the reference to the signed content (in-message body). If null and we are in the enveloped XML signature case then the URI is set to "". If null and we are in the enveloping XML signature case then the URI is set to "#object_id" (where "object_id" is the value of the option contentObjectId which means that the reference points to the Object element containing the in-message body. You can use this option to reference a specific part in your in-message body if you do not want to sign the complete in-message body. This value can be overwritten by the header "CamelXmlSignatureContentReferenceUri".
contentReferenceType String null Value of the type attribute of the content reference. This value can be overwritten by the header "CamelXmlSignatureContentReferenceType"
plainText Boolean Boolean.FALSE Indicator whether the in-message body contains plain text. Normally, the signature generator treats the incoming message body as XML. If the message body is plain text, then you must set this option to true. The value can be overwritten by the header "CamelXmlSignatureMessageIsPlainText".
plainTextEncoding String null Only used when the option plainText is set to true. Then you can specify the encoding of the plain text. If null then UTF-8 is used. The value can be overwritten by the header "CamelXmlSignatureMessageIsPlainTextEncoding".
properties XmlSignatureProperties null For adding additional References and Objects to the XML signature which contain additional properties, you can provide a bean which implements the XmlSignatureProperties interface.

Verifying Options

The verifier endpoint has the following options.
Name Type Default Description
keySelector javax.xml.crypto.KeySelector null Provides the key for validating the XML signature. There is an example implementation which uses a keystore, see DefaultKeySelector.
xmlSignatureChecker XmlSignatureChecker null This interface allows the application to check the XML signature before the validation is executed. This step is recommended in http://www.w3.org/TR/xmldsig-bestpractices/#check-what-is-signed
validationFailedHandler ValidationFailedHandler DefaultValidationFailedHandler Handles the different validation failed situations. The default implementation throws specific exceptions for the different situations (All exceptions have the package name org.apache.camel.component.xmlsecurity.api and are a sub-class of XmlSignatureInvalidException. If the signature value validation fails, a XmlSignatureInvalidValueException. If a reference validation fails, a XmlSignatureInvalidContentHashException is thrown. For more detailed information, see the JavaDoc.
xmlSignature2Message XmlSignature2Message DefaultXmlSignature2Message Bean which maps the XML signature to the ouput-message after the validation. How this mapping should be done can be configured by the options outputNodeSearchType, outputNodeSearch, and removeSignatureElements. The default implementation offers three possibilities which are related to the three output node search types "Default", "ElementName", and "XPath". The default implementation determines a node which is then serialized and set to the body of the ouput message. If the search type is "ElementName" then the ouput node (which must be in this case an element) is determined by the local name and namespace defined in the search value (see option outputNodeSearch). If the search type is "XPath" then the output node is determined by the XPath specified in the search value (in this case the ouput node can be of type "Element", "TextNode" or "Document"). If the output node search type is "Default" then the following rules apply: In the enveloped XML signature case (there is a reference with URI="" and transform "http://www.w3.org/2000/09/xmldsig#enveloped-signature"), the incoming XML document without the Signature element is set to the output message body. In the non-enveloped XML signature case, the message body is determined from a referenced Object; this is explained in more detail in chapter "Output Node Determination in Enveloping XML Signature Case".
outputNodeSearchType String "Default" Determines the type of the search of the output node. See option xmlSignature2Message. The default implementation DefaultXmlSignature2Message supports the three search types "Default", "ElementName", and "XPath".
outputNodeSearch Object null Search value of the output node search. The type depends on the search type. For the default search implementation DefaultXmlSignature2Message the following values can be supplied. If the search type is "Default", then the search value is not used. If the search type is "ElementName", then the search value contains the namespace and local name of the output element. The namespace must be embraced in brackets. If the search type is "XPath", the search value contains an instance of javax.xml.crypto.dsig.spec.XPathFilterParameterSpec which represents an XPath. You can create such an instance via the method XmlSignatureHelper.getXpathFilter(String xpath, Map<String, String> namespaceMap). The XPath determines the output node which can be of type Element, TextNode, or Document.
removeSignatureElements Boolean Boolean.FALSE Indicator for removing Signature elements in the output message in the enveloped XML signature case. Used in the XmlSignature2Message instance. The default implementation does use this indicator for the two search types "ElementName" and "XPath".
secureValidation Boolean Boolean.TRUE Enables secure validation. If true then secure validation is enabled - see here for more information.

Output Node Determination in Enveloping XML Signature Case

After the validation the node is extracted from the XML signature document which is finally returned to the output-message body. In the enveloping XML signature case, the default implementation DefaultXmlSignature2Message of XmlSignature2Message does this for the node search type "Default" in the following way (see option xmlSignature2Message):
First an Object reference is determined:
  • Only same document references are taken into account (URI must start with '#')
  • Also indirect same document references to an object via manifest are taken into account.
  • The resulting number of Object references must be 1.
Then, the Object is dereferenced and the Object must only contain one XML element. This element is returned as output node.
This does mean that the enveloping XML signature must have either the structure 
    <Signature>
          <SignedInfo>
             <Reference URI="#object"/>       
             <!-- further references possible but they must not point to an Object or Manifest containing an object reference -->
             ...
          </SignedInfo>
      
          <Object Id="object">
               <!-- contains one XML element which is extracted to the message body -->
          <Object>
          <!-- further object elements possible which are not referenced-->
          ...
          (<KeyInfo>)?
    </Signature>
or the structure 
    <Signature>
          <SignedInfo>
             <Reference URI="#manifest"/>       
             <!-- further references  are possible but they must not point to an Object or other manifest containing an object reference -->
             ...
          </SignedInfo>
      
          <Object >
             <Manifest Id="manifest">
                <Reference URI=#object/>
             </Manifest>
          </Objet>
          <Object Id="object">
              <!-- contains the DOM node which is extracted to the message body -->
          </Object>
           <!-- further object elements possible which are not referenced -->
          ...
          (<KeyInfo>)?
    </Signature>

See Also