camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Colm O hEigeartaigh (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache Camel > XMLSecurity DataFormat
Date Mon, 02 Sep 2013 11:46:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/en/2176/1/1/_/styles/combined.css?spaceKey=CAMEL&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CAMEL/XMLSecurity+DataFormat">XMLSecurity
DataFormat</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~coheigea@apache.org">Colm
O hEigeartaigh</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-unchanged" >h2. XMLSecurity Data Format <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >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). <span class="diff-added-words"style="background-color:
#dfd;">To sign messages using the XML Signature specification, please see the Camel XML
Security [component|XML Security component].</span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br>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. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="XMLSecurityDataFormat-XMLSecurityDataFormat"></a>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 href="/confluence/display/CAMEL/XML+Security+component" title="XML Security
component">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><b>Available as of Camel 2.9</b><br/>
The XMLSecurity Data Format supports asymmetric 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><a name="XMLSecurityDataFormat-BasicOptions"></a>Basic Options</h3>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>secureTag</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> The XPath reference to the XML Element selected for encryption/decryption.
If no tag is specified, the entire payload is encrypted/decrypted. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>secureTagContents</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> A boolean value to specify whether the XML Element is to be
encrypted or the contents of the XML Element
<ul>
	<li><tt>false</tt> = Element Level</li>
	<li><tt>true</tt> = Element Content Level</li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>passPhrase</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> 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 <tt>TRIPLEDES</tt> the passPhase can be a <tt>"Only another
24 Byte key"</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>xmlCipherAlgorithm</tt> </td>
<td class='confluenceTd'> <tt>TRIPLEDES</tt> </td>
<td class='confluenceTd'> The cipher algorithm to be used for encryption/decryption
of the XML message content. The available choices are:
<ul>
	<li><tt>XMLCipher.TRIPLEDES</tt></li>
	<li><tt>XMLCipher.AES_128</tt></li>
	<li><tt>XMLCipher.AES_128_GCM</tt> <b>Camel 2.12</b></li>
	<li><tt>XMLCipher.AES_192</tt></li>
	<li><tt>XMLCipher.AES_192_GCM</tt> <b>Camel 2.12</b></li>
	<li><tt>XMLCipher.AES_256</tt></li>
	<li><tt>XMLCipher.AES_256_GCM</tt> <b>Camel 2.12</b></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>namespaces</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> A map of namespace values indexed by prefix. The index values
must match the prefixes used in the <tt>secureTag</tt> XPath query. </td>
</tr>
</tbody></table>
</div>


<h3><a name="XMLSecurityDataFormat-AsymmetricEncryptionOptions"></a>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 class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>recipientKeyAlias</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> 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. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>keyCipherAlgorithm</tt> </td>
<td class='confluenceTd'> <b>Camel 2.12</b> <tt>XMLCipher.RSA_OAEP</tt>
</td>
<td class='confluenceTd'> The cipher algorithm to be used for encryption/decryption
of the asymmetric key. The available choices are: 
<ul>
	<li><tt>XMLCipher.RSA_v1dot5</tt></li>
	<li><tt>XMLCipher.RSA_OAEP</tt></li>
	<li><tt>XMLCipher.RSA_OAEP_11</tt></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>keyOrTrustStoreParameters</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Configuration options for creating and loading a KeyStore
instance that represents the sender's trustStore or recipient's keyStore. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>keyPassword</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> <b>Camel 2.10.2 / 2.11:</b> The password to be
used for retrieving the private key from the KeyStore. This key is used for asymmetric decryption.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>digestAlgorithm</tt> </td>
<td class='confluenceTd'> XMLCipher.SHA1 </td>
<td class='confluenceTd'> <b>Camel 2.12</b> The digest algorithm to use
with the RSA OAEP algorithm. The available choices are:
<ul>
	<li><tt>XMLCipher.SHA1</tt></li>
	<li><tt>XMLCipher.SHA256</tt></li>
	<li><tt>XMLCipher.SHA512</tt></li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>mgfAlgorithm</tt> </td>
<td class='confluenceTd'> EncryptionConstants.MGF1_SHA1 </td>
<td class='confluenceTd'> <b>Camel 2.12</b> The MGF Algorithm to use with
the RSA OAEP algorithm. The available choices are:
<ul>
	<li><tt>EncryptionConstants.MGF1_SHA1</tt></li>
	<li><tt>EncryptionConstants.MGF1_SHA256</tt></li>
	<li><tt>EncryptionConstants.MGF1_SHA512</tt></li>
</ul>
</td>
</tr>
</tbody></table>
</div>


<h4><a name="XMLSecurityDataFormat-KeyCipherAlgorithm"></a>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><a name="XMLSecurityDataFormat-Marshal"></a>Marshal</h3>
<p>In order to encrypt the payload, the <tt>marshal</tt> processor needs
to be applied on the route followed by the <b><tt>secureXML()</tt></b>
tag.</p>

<h3><a name="XMLSecurityDataFormat-Unmarshal"></a>Unmarshal</h3>
<p>In order to decrypt the payload, the <tt>unmarshal</tt> processor needs
to be applied on the route followed by the <b><tt>secureXML()</tt></b>
tag.</p>

<h3><a name="XMLSecurityDataFormat-Examples"></a>Examples</h3>
<p>Given below are several examples of how marshalling could be performed at the Document,
Element, and Content levels.</p>

<h4><a name="XMLSecurityDataFormat-FullPayloadencryption%2Fdecryption"></a>Full
Payload encryption/decryption</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
from("direct:start")
    .marshal().secureXML()
    .unmarshal().secureXML()
    .to("direct:end");
</pre>
</div></div>

<h4><a name="XMLSecurityDataFormat-PartialPayloadContentOnlyencryption%2Fdecryption"></a>Partial
Payload Content Only encryption/decryption</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
String tagXPATH = "//cheesesites/italy/cheese";
boolean secureTagContent = true;
...
from("direct:start")
    .marshal().secureXML(tagXPATH, secureTagContent)
    .unmarshal().secureXML(tagXPATH, secureTagContent)
    .to("direct:end");
</pre>
</div></div>

<h4><a name="XMLSecurityDataFormat-PartialMultiNodePayloadContentOnlyencryption%2Fdecryption"></a>Partial
Multi Node Payload Content Only encryption/decryption</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
String tagXPATH = "//cheesesites/*/cheese";
boolean secureTagContent = true;
...
from("direct:start")
    .marshal().secureXML(tagXPATH, secureTagContent)
    .unmarshal().secureXML(tagXPATH, secureTagContent)
    .to("direct:end");
</pre>
</div></div>

<h4><a name="XMLSecurityDataFormat-PartialPayloadContentOnlyencryption%2FdecryptionwithchoiceofpassPhrase%28password%29"></a>Partial
Payload Content Only encryption/decryption with choice of passPhrase(password)</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
String tagXPATH = "//cheesesites/italy/cheese";
boolean secureTagContent = true;
...
String passPhrase = "Just another 24 Byte key";
from("direct:start")
    .marshal().secureXML(tagXPATH, secureTagContent, passPhrase)
    .unmarshal().secureXML(tagXPATH, secureTagContent, passPhrase)
    .to("direct:end");
</pre>
</div></div>

<h4><a name="XMLSecurityDataFormat-PartialPayloadContentOnlyencryption%2FdecryptionwithpassPhrase%28password%29andAlgorithm"></a>Partial
Payload Content Only encryption/decryption with passPhrase(password) and Algorithm</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
import org.apache.xml.security.encryption.XMLCipher;
....
String tagXPATH = "//cheesesites/italy/cheese";
boolean secureTagContent = true;
String passPhrase = "Just another 24 Byte key";
String algorithm= XMLCipher.TRIPLEDES;
from("direct:start")
    .marshal().secureXML(tagXPATH, secureTagContent, passPhrase, algorithm)
    .unmarshal().secureXML(tagXPATH, secureTagContent, passPhrase, algorithm)
    .to("direct:end");
</pre>
</div></div>

<h4><a name="XMLSecurityDataFormat-PartialPayloadContentwithNamespacesupport"></a>Partial
Payload Content with Namespace support</h4>
<h5><a name="XMLSecurityDataFormat-JavaDSL"></a>Java DSL</h5>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
final Map&lt;String, String&gt; namespaces = new HashMap&lt;String, String&gt;();
namespaces.put("cust", "http://cheese.xmlsecurity.camel.apache.org/");

final KeyStoreParameters tsParameters = new KeyStoreParameters();
tsParameters.setPassword("password");
tsParameters.setResource("sender.ts");

context.addRoutes(new RouteBuilder() {
    public void configure() {
        from("direct:start")
           .marshal().secureXML("//cust:cheesesites/italy", namespaces, true, "recipient",
                                testCypherAlgorithm, XMLCipher.RSA_v1dot5, tsParameters)
           .to("mock:encrypted");
    }
}
</pre>
</div></div>

<h5><a name="XMLSecurityDataFormat-SpringXML"></a>Spring XML</h5>
<p>A namespace prefix that is defined as part of the <tt>camelContext</tt>
definition can be re-used in context within the data format <tt>secureTag</tt>
attribute of the <tt>secureXML</tt> element.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: xml; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
&lt;camelContext id="springXmlSecurityDataFormatTestCamelContext" 
              xmlns="http://camel.apache.org/schema/spring"
              xmlns:cheese="http://cheese.xmlsecurity.camel.apache.org/"&gt;        
    &lt;route&gt;
        &lt;from uri="direct://start"/&gt;
            &lt;marshal&gt;
                &lt;secureXML secureTag="//cheese:cheesesites/italy"
                           secureTagContents="true"/&gt;
            &lt;/marshal&gt; 
            ...
</pre>
</div></div>

<h4><a name="XMLSecurityDataFormat-AsymmetricKeyEncryption"></a>Asymmetric
Key Encryption</h4>
<h5><a name="XMLSecurityDataFormat-SpringXMLSender"></a>Spring XML Sender</h5>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: xml; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
&lt;!--  trust store configuration --&gt;                          
&lt;camel:keyStoreParameters id="trustStoreParams" resource="./sender.ts" password="password"/&gt;

&lt;camelContext id="springXmlSecurityDataFormatTestCamelContext" 
              xmlns="http://camel.apache.org/schema/spring"
              xmlns:cheese="http://cheese.xmlsecurity.camel.apache.org/"&gt;        
    &lt;route&gt;
        &lt;from uri="direct://start"/&gt;
            &lt;marshal&gt;
                &lt;secureXML secureTag="//cheese:cheesesites/italy"
                           secureTagContents="true"
                           xmlCipherAlgorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"
      
                           keyCipherAlgorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"
                           recipientKeyAlias="recipient"
                           keyOrTrustStoreParametersId="trustStoreParams"/&gt;
            &lt;/marshal&gt; 
            ...
</pre>
</div></div>

<h5><a name="XMLSecurityDataFormat-SpringXMLRecipient"></a>Spring XML Recipient</h5>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: xml; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;"> 
&lt;!--  key store configuration --&gt;
&lt;camel:keyStoreParameters id="keyStoreParams" resource="./recipient.ks" password="password"
/&gt;

&lt;camelContext id="springXmlSecurityDataFormatTestCamelContext" 
              xmlns="http://camel.apache.org/schema/spring"
              xmlns:cheese="http://cheese.xmlsecurity.camel.apache.org/"&gt;
    &lt;route&gt;    
        &lt;from uri="direct://encrypted"/&gt;
            &lt;unmarshal&gt;
                &lt;secureXML secureTag="//cheese:cheesesites/italy"
                           secureTagContents="true"
                           xmlCipherAlgorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"
                           keyCipherAlgorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"
                           recipientKeyAlias="recipient"
                           keyOrTrustStoreParametersId="keyStoreParams"
                           keyPassword="privateKeyPassword" /&gt;
            &lt;/unmarshal&gt;
            ...
</pre>
</div></div>

<h3><a name="XMLSecurityDataFormat-Dependencies"></a>Dependencies</h3>

<p>This data format is provided within the <b>camel-xmlsecurity</b> component.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;" class="grey">
                        <a href="https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=CAMEL">Stop
watching space</a>
            <span style="padding: 0px 5px;">|</span>
                <a href="https://cwiki.apache.org/confluence/users/editmyemailsettings.action">Change
email notification preferences</a>
</div>
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/XMLSecurity+DataFormat">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=110832&revisedVersion=26&originalVersion=25">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/XMLSecurity+DataFormat?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message