Modified: websites/production/camel/content/xmlsecurity-dataformat.html
==============================================================================
--- websites/production/camel/content/xmlsecurity-dataformat.html (original)
+++ websites/production/camel/content/xmlsecurity-dataformat.html Tue Dec 2
12:20:00 2014
@@ -85,7 +85,7 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><h2
id="XMLSecurityDataFormat-XMLSecurityDataFormat">XMLSecurity Data
Format</h2><p>The XMLSecurity Data Format facilitates encryption and decryption
of XML payloads at the Document, Element, and Element Content levels (including
simultaneous multi-node encryption/decryption using XPath). To sign messages
using the XML Signature specification, please see the Camel XML Security <a
shape="rect" href="xml-security-component.html">component</a>.</p><p>The
encryption capability is based on formats supported using the Apache XML
Security (Santuario) project. Symmetric encryption/decryption is currently
supported using Triple-DES and AES (128, 192, and 256) encryption formats.
Additional formats can be easily added later as needed. This capability allows
Camel users to encrypt/decrypt payloads while being dispatched or received
along a route.</p><p><strong>Available as of Camel 2.9</strong><br
clear="none"> The XMLSecurity Data Format supports asymmetr
ic key encryption. In this encryption model a symmetric key is generated and
used to perform XML content encryption or decryption. This "content encryption
key" is then itself encrypted using an asymmetric encryption algorithm that
leverages the recipient's public key as the "key encryption key". Use of an
asymmetric key encryption algorithm ensures that only the holder of the
recipient's private key can access the generated symmetric encryption key.
Thus, only the private key holder can decode the message. The XMLSecurity Data
Format handles all of the logic required to encrypt and decrypt the message
content and encryption key(s) using asymmetric key encryption.</p><p>The
XMLSecurity Data Format also has improved support for namespaces when
processing the XPath queries that select content for encryption. A namespace
definition mapping can be included as part of the data format configuration.
This enables true namespace matching, even if the prefix values in the XPath
query and the
target xml document are not equivalent strings.</p><h3
id="XMLSecurityDataFormat-BasicOptions">Basic Options</h3><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>secureTag</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The XPath reference to the XML
Element selected for encryption/decryption. If no tag is specified, the entire
payload is encrypted/decrypted.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>secureTagContents</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A boole
an value to specify whether the XML Element is to be encrypted or the contents
of the XML Element</p><ul><li><code>false</code> = Element
Level</li><li><code>true</code> = Element Content
Level</li></ul></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>passPhrase</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A String used as passPhrase to
encrypt/decrypt content. The passPhrase has to be provided. If no passPhrase is
specified, a default passPhrase is used. The passPhrase needs to be put
together in conjunction with the appropriate encryption algorithm. For example
using <code>TRIPLEDES</code> the passPhase can be a <code>"Only another 24 Byte
key"</code></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>xmlCipherAlgorithm</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>TRIPLEDES</code></p></td><td
colspan="1" rows
pan="1" class="confluenceTd"><p>The cipher algorithm to be used for
encryption/decryption of the XML message content. The available choices
are:</p><ul><li><code>XMLCipher.TRIPLEDES</code></li><li><code>XMLCipher.AES_128</code></li><li><code>XMLCipher.AES_128_GCM</code>
<strong>Camel
2.12</strong></li><li><code>XMLCipher.AES_192</code></li><li><code>XMLCipher.AES_192_GCM</code>
<strong>Camel
2.12</strong></li><li><code>XMLCipher.AES_256</code></li><li><code>XMLCipher.AES_256_GCM</code>
<strong>Camel 2.12</strong></li><li>XMLCipher.SEED_128 <strong>Camel
2.12</strong></li><li>XMLCipher.CAMELLIA_128, XMLCipher.CAMELLIA_192,
XMLCipher.CAMELLIA_256 <strong>Camel 2.12</strong></li></ul></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>namespaces</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A map of namespace values indexed by
prefix. The index values must match the pr
efixes used in the <code>secureTag</code> XPath
query.</p></td></tr></tbody></table></div><h3
id="XMLSecurityDataFormat-AsymmetricEncryptionOptions">Asymmetric Encryption
Options</h3><p>These options can be applied in addition to relevant the Basic
options to use asymmetric key encryption.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>recipientKeyAlias</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The key alias to be used when
retrieving the recipient's public or private key from a KeyStore when
performing asymmetric key encryption or decryption.</p></td></tr><tr><td
colspan="1" rowspan="1" cla
ss="confluenceTd"><p><code>keyCipherAlgorithm</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.12</strong>
<code>XMLCipher.RSA_OAEP</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The cipher algorithm to be used for
encryption/decryption of the asymmetric key. The available choices
are:</p><ul><li><code>XMLCipher.RSA_v1dot5</code></li><li><code>XMLCipher.RSA_OAEP</code></li><li><code>XMLCipher.RSA_OAEP_11</code></li></ul></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>keyOrTrustStoreParameters</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Configuration options for
creating and loading a KeyStore instance that represents the sender's
trustStore or recipient's keyStore.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>keyPassword</code></p></td><td
colspan="1" rowspan="1" class="conflue
nceTd"><p><code>null</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.10.2 / 2.11:</strong> The password to
be used for retrieving the private key from the KeyStore. This key is used for
asymmetric decryption.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>digestAlgorithm</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>XMLCipher.SHA1</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.12</strong> The digest
algorithm to use with the RSA OAEP algorithm. The available choices
are:</p><ul><li><code>XMLCipher.SHA1</code></li><li><code>XMLCipher.SHA256</code></li><li><code>XMLCipher.SHA512</code></li></ul></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>mgfAlgorithm</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>EncryptionConstants.MGF1_SHA1</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.12</strong> The
MGF Algori
thm to use with the RSA OAEP algorithm. The available choices
are:</p><ul><li><code>EncryptionConstants.MGF1_SHA1</code></li><li><code>EncryptionConstants.MGF1_SHA256</code></li><li><code>EncryptionConstants.MGF1_SHA512</code></li></ul></td></tr></tbody></table></div><h4
id="XMLSecurityDataFormat-KeyCipherAlgorithm">Key Cipher Algorithm</h4><p>As
of Camel 2.12.0, the default Key Cipher Algorithm is now XMLCipher.RSA_OAEP
instead of XMLCipher.RSA_v1dot5. Usage of XMLCipher.RSA_v1dot5 is discouraged
due to various attacks. Requests that use RSA v1.5 as the key cipher algorithm
will be rejected unless it has been explicitly configured as the key cipher
algorithm.</p><h3 id="XMLSecurityDataFormat-Marshal">Marshal</h3><p>In order to
encrypt the payload, the <code>marshal</code> processor needs to be applied on
the route followed by the <strong><code>secureXML()</code></strong> tag.</p><h3
id="XMLSecurityDataFormat-Unmarshal">Unmarshal</h3><p>In order to decrypt the
payload, the <code>unm
arshal</code> processor needs to be applied on the route followed by the
<strong><code>secureXML()</code></strong> tag.</p><h3
id="XMLSecurityDataFormat-Examples">Examples</h3><p>Given below are several
examples of how marshalling could be performed at the Document, Element, and
Content levels.</p><h4
id="XMLSecurityDataFormat-FullPayloadencryption/decryption">Full Payload
encryption/decryption</h4><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<div class="wiki-content maincontent"><h2
id="XMLSecurityDataFormat-XMLSecurityDataFormat">XMLSecurity Data
Format</h2><p>The XMLSecurity Data Format facilitates encryption and decryption
of XML payloads at the Document, Element, and Element Content levels (including
simultaneous multi-node encryption/decryption using XPath). To sign messages
using the XML Signature specification, please see the Camel XML Security <a
shape="rect" href="xml-security-component.html">component</a>.</p><p>The
encryption capability is based on formats supported using the Apache XML
Security (Santuario) project. Symmetric encryption/decryption is currently
supported using Triple-DES and AES (128, 192, and 256) encryption formats.
Additional formats can be easily added later as needed. This capability allows
Camel users to encrypt/decrypt payloads while being dispatched or received
along a route.</p><p><strong>Available as of Camel 2.9</strong><br
clear="none"> The XMLSecurity Data Format supports asymmetr
ic key encryption. In this encryption model a symmetric key is generated and
used to perform XML content encryption or decryption. This "content encryption
key" is then itself encrypted using an asymmetric encryption algorithm that
leverages the recipient's public key as the "key encryption key". Use of an
asymmetric key encryption algorithm ensures that only the holder of the
recipient's private key can access the generated symmetric encryption key.
Thus, only the private key holder can decode the message. The XMLSecurity Data
Format handles all of the logic required to encrypt and decrypt the message
content and encryption key(s) using asymmetric key encryption.</p><p>The
XMLSecurity Data Format also has improved support for namespaces when
processing the XPath queries that select content for encryption. A namespace
definition mapping can be included as part of the data format configuration.
This enables true namespace matching, even if the prefix values in the XPath
query and the
target xml document are not equivalent strings.</p><h3
id="XMLSecurityDataFormat-BasicOptions">Basic Options</h3><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>secureTag</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The XPath reference to the XML
Element selected for encryption/decryption. If no tag is specified, the entire
payload is encrypted/decrypted.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>secureTagContents</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A boole
an value to specify whether the XML Element is to be encrypted or the contents
of the XML Element</p><ul><li><code>false</code> = Element
Level</li><li><code>true</code> = Element Content
Level</li></ul></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>passPhrase</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A String used as passPhrase to
encrypt/decrypt content. The passPhrase has to be provided. If no passPhrase is
specified, a default passPhrase is used. The passPhrase needs to be put
together in conjunction with the appropriate encryption algorithm. For example
using <code>TRIPLEDES</code> the passPhase can be a <code>"Only another 24 Byte
key"</code></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>xmlCipherAlgorithm</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>TRIPLEDES</code></p></td><td
colspan="1" rows
pan="1" class="confluenceTd"><p>The cipher algorithm to be used for
encryption/decryption of the XML message content. The available choices
are:</p><ul><li><code>XMLCipher.TRIPLEDES</code></li><li><code>XMLCipher.AES_128</code></li><li><code>XMLCipher.AES_128_GCM</code>
<strong>Camel
2.12</strong></li><li><code>XMLCipher.AES_192</code></li><li><code>XMLCipher.AES_192_GCM</code>
<strong>Camel
2.12</strong></li><li><code>XMLCipher.AES_256</code></li><li><code>XMLCipher.AES_256_GCM</code>
<strong>Camel 2.12</strong></li><li>XMLCipher.SEED_128 <strong>Camel
2.15</strong></li><li>XMLCipher.CAMELLIA_128, XMLCipher.CAMELLIA_192,
XMLCipher.CAMELLIA_256 <strong>Camel 2.15</strong></li></ul></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>namespaces</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A map of namespace values indexed by
prefix. The index values must match the pr
efixes used in the <code>secureTag</code> XPath
query.</p></td></tr></tbody></table></div><h3
id="XMLSecurityDataFormat-AsymmetricEncryptionOptions">Asymmetric Encryption
Options</h3><p>These options can be applied in addition to relevant the Basic
options to use asymmetric key encryption.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>recipientKeyAlias</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The key alias to be used when
retrieving the recipient's public or private key from a KeyStore when
performing asymmetric key encryption or decryption.</p></td></tr><tr><td
colspan="1" rowspan="1" cla
ss="confluenceTd"><p><code>keyCipherAlgorithm</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.12</strong>
<code>XMLCipher.RSA_OAEP</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The cipher algorithm to be used for
encryption/decryption of the asymmetric key. The available choices
are:</p><ul><li><code>XMLCipher.RSA_v1dot5</code></li><li><code>XMLCipher.RSA_OAEP</code></li><li><code>XMLCipher.RSA_OAEP_11</code></li></ul></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>keyOrTrustStoreParameters</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Configuration options for
creating and loading a KeyStore instance that represents the sender's
trustStore or recipient's keyStore.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>keyPassword</code></p></td><td
colspan="1" rowspan="1" class="conflue
nceTd"><p><code>null</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.10.2 / 2.11:</strong> The password to
be used for retrieving the private key from the KeyStore. This key is used for
asymmetric decryption.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>digestAlgorithm</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>XMLCipher.SHA1</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.12</strong> The digest
algorithm to use with the RSA OAEP algorithm. The available choices
are:</p><ul><li><code>XMLCipher.SHA1</code></li><li><code>XMLCipher.SHA256</code></li><li><code>XMLCipher.SHA512</code></li></ul></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>mgfAlgorithm</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>EncryptionConstants.MGF1_SHA1</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.12</strong> The
MGF Algori
thm to use with the RSA OAEP algorithm. The available choices
are:</p><ul><li><code>EncryptionConstants.MGF1_SHA1</code></li><li><code>EncryptionConstants.MGF1_SHA256</code></li><li><code>EncryptionConstants.MGF1_SHA512</code></li></ul></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd">addKeyValueForEncryptedKey</td><td colspan="1" rowspan="1"
class="confluenceTd">true</td><td colspan="1" rowspan="1"
class="confluenceTd"><strong>Camel 2.14.1 </strong>Whether to add the public
key used to encrypt the session key as a KeyValue in the EncryptedKey structure
or not.</td></tr></tbody></table></div><h4
id="XMLSecurityDataFormat-KeyCipherAlgorithm">Key Cipher Algorithm</h4><p>As of
Camel 2.12.0, the default Key Cipher Algorithm is now XMLCipher.RSA_OAEP
instead of XMLCipher.RSA_v1dot5. Usage of XMLCipher.RSA_v1dot5 is discouraged
due to various attacks. Requests that use RSA v1.5 as the key cipher algorithm
will be rejected unless it has been explicitly configured as the key ci
pher algorithm.</p><h3 id="XMLSecurityDataFormat-Marshal">Marshal</h3><p>In
order to encrypt the payload, the <code>marshal</code> processor needs to be
applied on the route followed by the <strong><code>secureXML()</code></strong>
tag.</p><h3 id="XMLSecurityDataFormat-Unmarshal">Unmarshal</h3><p>In order to
decrypt the payload, the <code>unmarshal</code> processor needs to be applied
on the route followed by the <strong><code>secureXML()</code></strong>
tag.</p><h3 id="XMLSecurityDataFormat-Examples">Examples</h3><p>Given below are
several examples of how marshalling could be performed at the Document,
Element, and Content levels.</p><h4
id="XMLSecurityDataFormat-FullPayloadencryption/decryption">Full Payload
encryption/decryption</h4><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><