Added secureXML Dataformat docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/16b4d785 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/16b4d785 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/16b4d785 Branch: refs/heads/master Commit: 16b4d7854501ceb04038b2787a87175ba3b466c4 Parents: a5ef24b Author: Andrea Cosentino <anco...@gmail.com> Authored: Wed Aug 31 10:09:06 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Wed Aug 31 10:09:06 2016 +0200 ---------------------------------------------------------------------- .../src/main/docs/secureXML-dataformat.adoc | 279 +++++++++++++++++++ 1 file changed, 279 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/16b4d785/components/camel-xmlsecurity/src/main/docs/secureXML-dataformat.adoc ---------------------------------------------------------------------- diff --git a/components/camel-xmlsecurity/src/main/docs/secureXML-dataformat.adoc b/components/camel-xmlsecurity/src/main/docs/secureXML-dataformat.adoc new file mode 100644 index 0000000..5d65c99 --- /dev/null +++ b/components/camel-xmlsecurity/src/main/docs/secureXML-dataformat.adoc @@ -0,0 +1,279 @@ +[[XMLSecurityDataFormat-XMLSecurityDataFormat]] +XMLSecurity Data Format +~~~~~~~~~~~~~~~~~~~~~~~ + +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 link:xml-security-component.html[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. + +*Available as of 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. + +[[XMLSecurityDataFormat-Options]] +XMLSecurity Options +^^^^^^^^^^^^^^^^^^^ + +// dataformat options: START +The XML Security dataformat supports 11 options which are listed below. + + + +{% raw %} +[width="100%",cols="2s,1m,1m,6",options="header"] +|======================================================================= +| Name | Default | Java Type | Description +| xmlCipherAlgorithm | TRIPLEDES | 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 MLCipher.TRIPLEDES +| passPhrase | | String | 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 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. +| keyOrTrustStoreParametersId | | 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. +|======================================================================= +{% endraw %} +// dataformat options: END + + +[[XMLSecurityDataFormat-KeyCipherAlgorithm]] +Key Cipher Algorithm +++++++++++++++++++++ + +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. + +[[XMLSecurityDataFormat-Marshal]] +Marshal +^^^^^^^ + +In order to encrypt the payload, the `marshal` processor needs to be +applied on the route followed by the *`secureXML()`* tag. + +[[XMLSecurityDataFormat-Unmarshal]] +Unmarshal +^^^^^^^^^ + +In order to decrypt the payload, the `unmarshal` processor needs to be +applied on the route followed by the *`secureXML()`* tag. + +[[XMLSecurityDataFormat-Examples]] +Examples +^^^^^^^^ + +Given below are several examples of how marshalling could be performed +at the Document, Element, and Content levels. + +[[XMLSecurityDataFormat-FullPayloadencryptiondecryption]] +Full Payload encryption/decryption +++++++++++++++++++++++++++++++++++ + +[source,java] +---------------------------- +from("direct:start") + .marshal().secureXML() + .unmarshal().secureXML() + .to("direct:end"); +---------------------------- + +[[XMLSecurityDataFormat-PartialPayloadContentOnlyencryptiondecryption]] +Partial Payload Content Only encryption/decryption +++++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,java] +------------------------------------------------------ +String tagXPATH = "//cheesesites/italy/cheese"; +boolean secureTagContent = true; +... +from("direct:start") + .marshal().secureXML(tagXPATH, secureTagContent) + .unmarshal().secureXML(tagXPATH, secureTagContent) + .to("direct:end"); +------------------------------------------------------ + +[[XMLSecurityDataFormat-PartialMultiNodePayloadContentOnlyencryptiondecryption]] +Partial Multi Node Payload Content Only encryption/decryption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,java] +------------------------------------------------------ +String tagXPATH = "//cheesesites/*/cheese"; +boolean secureTagContent = true; +... +from("direct:start") + .marshal().secureXML(tagXPATH, secureTagContent) + .unmarshal().secureXML(tagXPATH, secureTagContent) + .to("direct:end"); +------------------------------------------------------ + +[[XMLSecurityDataFormat-PartialPayloadContentOnlyencryptiondecryptionwithchoiceofpassPhrasepassword]] +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"); +------------------------------------------------------------------ + +[[XMLSecurityDataFormat-PartialPayloadContentOnlyencryptiondecryptionwithpassPhrasepasswordandAlgorithm]] +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"); +----------------------------------------------------------------------------- + +[[XMLSecurityDataFormat-PartialPayloadContentwithNamespacesupport]] +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> + ... +--------------------------------------------------------------------------------- + +[[XMLSecurityDataFormat-AsymmetricKeyEncryption]] +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" + keyOrTrustStoreParametersId="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" + keyOrTrustStoreParametersId="keyStoreParams" + keyPassword="privateKeyPassword" /> + </unmarshal> + ... +---------------------------------------------------------------------------------------------- + +[[XMLSecurityDataFormat-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +This data format is provided within the *camel-xmlsecurity* component.
