[[secureXML-dataformat]]
= XML Security DataFormat
:docTitle: XML Security
:artifactId: camel-xmlsecurity
:description: Encrypt and decrypt XML payloads using Apache Santuario.
:since: 2.0
:supportLevel: Stable
include::{cq-version}@camel-quarkus:ROOT:partial$reference/dataformats/secureXML.adoc[opts=optional]

*Since Camel {since}*

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

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.

*Since Camel 2.9* +
 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.

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.

== XMLSecurity Options

// dataformat options: START
The XML Security dataformat supports 12 options, which are listed below.



[width="100%",cols="2s,1m,1m,6",options="header"]
|===
| Name | Default | Java Type | Description
| xmlCipherAlgorithm | AES-256-GCM | String | The cipher algorithm to be used for encryption/decryption of the XML message content. The available choices are: XMLCipher.TRIPLEDES XMLCipher.AES_128 XMLCipher.AES_128_GCM XMLCipher.AES_192 XMLCipher.AES_192_GCM XMLCipher.AES_256 XMLCipher.AES_256_GCM XMLCipher.SEED_128 XMLCipher.CAMELLIA_128 XMLCipher.CAMELLIA_192 XMLCipher.CAMELLIA_256 The default value is XMLCipher.AES_256_GCM
| passPhrase |  | String | A String used as passPhrase to encrypt/decrypt content. The passPhrase has to be provided. The passPhrase needs to be put together in conjunction with the appropriate encryption algorithm. For example using TRIPLEDES the passPhase can be a Only another 24 Byte key
| passPhraseByte |  | byte[] | A byte used as passPhrase to encrypt/decrypt content. The passPhrase has to be provided. The passPhrase needs to be put together in conjunction with the appropriate encryption algorithm. For example using TRIPLEDES the passPhase can be a Only another 24 Byte key
| secureTag |  | String | The XPath reference to the XML Element selected for encryption/decryption. If no tag is specified, the entire payload is encrypted/decrypted.
| secureTagContents | false | Boolean | A boolean value to specify whether the XML Element is to be encrypted or the contents of the XML Element false = Element Level true = Element Content Level
| keyCipherAlgorithm | RSA_OAEP | String | The cipher algorithm to be used for encryption/decryption of the asymmetric key. The available choices are: XMLCipher.RSA_v1dot5 XMLCipher.RSA_OAEP XMLCipher.RSA_OAEP_11 The default value is XMLCipher.RSA_OAEP
| recipientKeyAlias |  | String | 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.
| keyOrTrustStoreParametersRef |  | String | Refers to a KeyStore instance to lookup in the registry, which is used for configuration options for creating and loading a KeyStore instance that represents the sender's trustStore or recipient's keyStore.
| keyPassword |  | String | The password to be used for retrieving the private key from the KeyStore. This key is used for asymmetric decryption.
| digestAlgorithm | SHA1 | String | The digest algorithm to use with the RSA OAEP algorithm. The available choices are: XMLCipher.SHA1 XMLCipher.SHA256 XMLCipher.SHA512 The default value is XMLCipher.SHA1
| mgfAlgorithm | MGF1_SHA1 | String | The MGF Algorithm to use with the RSA OAEP algorithm. The available choices are: EncryptionConstants.MGF1_SHA1 EncryptionConstants.MGF1_SHA256 EncryptionConstants.MGF1_SHA512 The default value is EncryptionConstants.MGF1_SHA1
| addKeyValueForEncryptedKey | true | Boolean | Whether to add the public key used to encrypt the session key as a KeyValue in the EncryptedKey structure or not.
|===
// dataformat options: END


=== Key Cipher Algorithm

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.

== Marshal

In order to encrypt the payload, the `marshal` processor needs to be
applied on the route followed by the *`secureXML()`* tag.

== Unmarshal

In order to decrypt the payload, the `unmarshal` processor needs to be
applied on the route followed by the *`secureXML()`* tag.

== Examples

Given below are several examples of how marshalling could be performed
at the Document, Element, and Content levels.

=== Full Payload encryption/decryption

[source,java]
----------------------------
KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
keyGenerator.init(256);
Key key = keyGenerator.generateKey();

from("direct:start")
    .marshal().secureXML(key.getEncoded())
    .unmarshal().secureXML(key.getEncoded()
    .to("direct:end");
----------------------------

=== Partial Payload Content Only encryption/decryption with choice of passPhrase(password)

[source,java]
------------------------------------------------------------------
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");
------------------------------------------------------------------

=== Partial Payload Content Only encryption/decryption with passPhrase(password) and Algorithm

[source,java]
-----------------------------------------------------------------------------
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");
-----------------------------------------------------------------------------

=== Partial Payload Content with Namespace support

[[XMLSecurityDataFormat-JavaDSL]]
Java DSL

[source,java]
------------------------------------------------------------------------------------------
final Map<String, String> namespaces = new HashMap<String, String>();
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");
    }
}
------------------------------------------------------------------------------------------

[[XMLSecurityDataFormat-SpringXML]]
Spring XML

A namespace prefix that is defined as part of the `camelContext`
definition can be re-used in context within the data format `secureTag`
attribute of the `secureXML` element.

[source,xml]
---------------------------------------------------------------------------------
<camelContext id="springXmlSecurityDataFormatTestCamelContext" 
              xmlns="http://camel.apache.org/schema/spring"
              xmlns:cheese="http://cheese.xmlsecurity.camel.apache.org/">        
    <route>
        <from uri="direct://start"/>
            <marshal>
                <secureXML secureTag="//cheese:cheesesites/italy"
                           secureTagContents="true"/>
            </marshal> 
            ...
---------------------------------------------------------------------------------

=== Asymmetric Key Encryption

[[XMLSecurityDataFormat-SpringXMLSender]]
Spring XML Sender

[source,xml]
--------------------------------------------------------------------------------------------------
<!--  trust store configuration -->                          
<camel:keyStoreParameters id="trustStoreParams" resource="./sender.ts" password="password"/>

<camelContext id="springXmlSecurityDataFormatTestCamelContext" 
              xmlns="http://camel.apache.org/schema/spring"
              xmlns:cheese="http://cheese.xmlsecurity.camel.apache.org/">        
    <route>
        <from uri="direct://start"/>
            <marshal>
                <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"
                           keyOrTrustStoreParametersRef="trustStoreParams"/>
            </marshal> 
            ...
--------------------------------------------------------------------------------------------------

[[XMLSecurityDataFormat-SpringXMLRecipient]]
Spring XML Recipient

[source,xml]
----------------------------------------------------------------------------------------------
 
<!--  key store configuration -->
<camel:keyStoreParameters id="keyStoreParams" resource="./recipient.ks" password="password" />

<camelContext id="springXmlSecurityDataFormatTestCamelContext" 
              xmlns="http://camel.apache.org/schema/spring"
              xmlns:cheese="http://cheese.xmlsecurity.camel.apache.org/">
    <route>    
        <from uri="direct://encrypted"/>
            <unmarshal>
                <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"
                           keyOrTrustStoreParametersRef="keyStoreParams"
                           keyPassword="privateKeyPassword" />
            </unmarshal>
            ...
----------------------------------------------------------------------------------------------

== Dependencies

This data format is provided within the *camel-xmlsecurity* component.

include::camel-spring-boot::page$xmlsecurity-starter.adoc[]
