| [[xmlsecurity-sign-component]] |
| = XML Security Sign Component |
| //THIS FILE IS COPIED: EDIT THE SOURCE FILE: |
| :page-source: components/camel-xmlsecurity/src/main/docs/xmlsecurity-sign-component.adoc |
| :docTitle: XML Security Sign |
| :artifactId: camel-xmlsecurity |
| :description: Sign XML payloads using the XML signature specification. |
| :since: 2.12 |
| :supportLevel: Stable |
| :component-header: Only producer is supported |
| |
| |
| |
| *Since Camel {since}* |
| |
| *{component-header}* |
| |
| With this Apache Camel component, you can generate and validate XML |
| signatures as described in the W3C standard |
| http://www.w3.org/TR/xmldsig-core/[XML Signature Syntax and Processing] |
| or as described in the successor |
| http://www.w3.org/TR/xmldsig-core1/[version 1.1]. For XML Encryption |
| support, please refer to the XML Security xref:manual::data-format.adoc[Data |
| Format]. |
| |
| You can find an introduction to XML signature |
| http://www.oracle.com/technetwork/articles/javase/dig-signatures-141823.html[here]. |
| The implementation of the component is based on |
| http://docs.oracle.com/javase/6/docs/technotes/guides/security/xmldsig/overview.html[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. |
| |
| We also provide support for *XAdES-BES/EPES* for the |
| signer endpoint; see subsection "XAdES-BES/EPES for the Signer |
| Endpoint". |
| |
| Maven users will need to add the following dependency to their `pom.xml` |
| for this component: |
| |
| [source,xml] |
| ---- |
| <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 |
| http://www.w3.org/TR/xmldsig-core1/#def-SignatureEnveloped[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 |
| http://www.w3.org/TR/xmldsig-core1/#def-SignatureEnveloping[enveloping] |
| XML signature case, the XML Signature contains the signed content. All |
| other cases are called |
| http://www.w3.org/TR/xmldsig-core1/#def-SignatureDetached[detached] XML |
| signatures. |
| |
| In the *enveloped XML signature* case, the supported generated XML |
| signature has the following structure (Variables are surrounded by `[]`). |
| |
| [source,xml] |
| ---- |
| <[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 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: |
| |
| [source,xml] |
| ---- |
| <Signature Id="generated_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; the object ID can either be generated or set by the option parameter "contentObjectId" --> |
| <!-- Further Object elements possible, see option 'properties' below --> |
| </Signature> |
| ---- |
| |
| *Detached XML signatures* with the following structure |
| are supported (see also sub-chapter XML Signatures as Siblings of Signed |
| Elements): |
| |
| [source,xml] |
| ---- |
| (<[signed element] Id="[id_value]"> |
| <!-- signed element must have an attribute of type ID --> |
| ... |
| |
| </[signed element]> |
| <other sibling/>* |
| <!-- between the signed element and the corresponding signature element, there can be other siblings. |
| Signature element is added as last sibling. --> |
| <Signature Id="generated_unique_ID"> |
| <SignedInfo> |
| <CanonicalizationMethod> |
| <SignatureMethod> |
| <Reference URI="#[id_value]" type="[optional_type_value]"> |
| <!-- reference URI contains the ID attribute value of the signed element --> |
| (<Transform>)* <!-- By default "http://www.w3.org/2006/12/xml-c14n11" is added to the transforms --> |
| <DigestMethod> |
| <DigestValue> |
| </Reference> |
| (<Reference URI="#[generated_keyinfo_Id]"> |
| <Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/> |
| <DigestMethod> |
| <DigestValue> |
| </Reference>)? |
| </SignedInfo> |
| <SignatureValue> |
| (<KeyInfo Id="[generated_keyinfo_id]">)? |
| </Signature>)+ |
| ---- |
| |
| |
| |
| == URI Format |
| |
| The camel component consists of two endpoints which have the following |
| URI format: |
| |
| [source] |
| ---- |
| 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, enveloping, or detached (as of 12.14) XML |
| signature(s) will be set to the body of the out-message. |
| * With the verifier endpoint, you can validate an enveloped or |
| enveloping XML signature or even several detached XML |
| signatures 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 the camel context. |
| |
| == Basic Example |
| |
| The following example shows the basic usage of the component. |
| |
| [source,java] |
| ---- |
| from("direct:enveloping").to("xmlsecurity-sign://enveloping?keyAccessor=#accessor", |
| "xmlsecurity-verify://enveloping?keySelector=#selector", |
| "mock:result") |
| ---- |
| |
| In Spring XML: |
| |
| [source,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 |
| https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/KeyAccessor.java[`KeyAccessor`] |
| interface. The package `org.apache.camel.component.xmlsecurity.api` |
| contains the default implementation class |
| https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/DefaultKeyAccessor.java[`DefaultKeyAccessor`] |
| which reads the private key from a Java keystore. |
| |
| The key selector bean must implement the |
| http://docs.oracle.com/javase/6/docs/api/javax/xml/crypto/KeySelector.html[`javax.xml.crypto.KeySelector`] |
| interface. The package `org.apache.camel.component.xmlsecurity.api` |
| contains the default implementation class |
| https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/DefaultKeySelector.java[`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. |
| |
| For creating _detached_ XML signatures, see sub-chapter "Detached XML |
| Signatures as Siblings of the Signed Elements". |
| |
| == Component Options |
| |
| |
| |
| |
| |
| // component options: START |
| The XML Security Sign component supports 29 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *addKeyInfoReference* (producer) | In order to protect the KeyInfo element from tampering you can add a reference to the signed info element so that it is protected via the signature value. The default value is true. Only relevant when a KeyInfo is returned by KeyAccessor. and KeyInfo#getId() is not null. | true | Boolean |
| | *baseUri* (producer) | You can set a base URI which is used in the URI dereferencing. Relative URIs are then concatenated with the base URI. | | String |
| | *canonicalizationMethod* (producer) | 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 inclusiveNamespacePrefixes) to create a canonicalization method. | http://www.w3.org/TR/2001/REC-xml-c14n-20010315 | AlgorithmMethod |
| | *clearHeaders* (producer) | Determines if the XML signature specific headers be cleared after signing and verification. Defaults to true. | true | Boolean |
| | *contentObjectId* (producer) | Sets the content object Id attribute value. By default a UUID is generated. If you set the null value, then a new UUID will be generated. Only used in the enveloping case. | | String |
| | *contentReferenceType* (producer) | Type of the content reference. The default value is null. This value can be overwritten by the header XmlSignatureConstants#HEADER_CONTENT_REFERENCE_TYPE. | | String |
| | *contentReferenceUri* (producer) | Reference URI for the content to be signed. Only used in the enveloped case. If the reference URI contains an ID attribute value, then the resource schema URI ( setSchemaResourceUri(String)) must also be set because the schema validator will then find out which attributes are ID attributes. Will be ignored in the enveloping or detached case. | | String |
| | *cryptoContextProperties* (producer) | Sets the crypto context properties. See {link XMLCryptoContext#setProperty(String, Object)}. Possible properties are defined in XMLSignContext an XMLValidateContext (see Supported Properties). The following properties are set by default to the value Boolean#TRUE for the XML validation. If you want to switch these features off you must set the property value to Boolean#FALSE. org.jcp.xml.dsig.validateManifests javax.xml.crypto.dsig.cacheReference | | Map |
| | *digestAlgorithm* (producer) | Digest algorithm URI. Optional parameter. This digest algorithm is used for calculating the digest of the input message. If this digest algorithm is not specified then the digest algorithm is calculated from the signature algorithm. Example: \http://www.w3.org/2001/04/xmlenc#sha256 | | String |
| | *disallowDoctypeDecl* (producer) | Disallows that the incoming XML document contains DTD DOCTYPE declaration. The default value is Boolean#TRUE. | true | Boolean |
| | *keyAccessor* (producer) | For the signing process, a private key is necessary. You specify a key accessor bean which provides this private 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. | | KeyAccessor |
| | *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean |
| | *omitXmlDeclaration* (producer) | Indicator whether the XML declaration in the outgoing message body should be omitted. Default value is false. Can be overwritten by the header XmlSignatureConstants#HEADER_OMIT_XML_DECLARATION. | false | Boolean |
| | *outputXmlEncoding* (producer) | The character encoding of the resulting signed XML document. If null then the encoding of the original XML document is used. | | String |
| | *parentLocalName* (producer) | Local name of the parent element to which the XML signature element will be added. Only relevant for enveloped XML signature. Alternatively you can also use setParentXpath(XPathFilterParameterSpec). Default value is null. The value must be null for enveloping and detached XML signature. This parameter or the parameter setParentXpath(XPathFilterParameterSpec) for enveloped signature and the parameter setXpathsToIdAttributes(List) for detached signature must not be set in the same configuration. If the parameters parentXpath and parentLocalName are specified in the same configuration then an exception is thrown. | | String |
| | *parentNamespace* (producer) | Namespace of the parent element to which the XML signature element will be added. | | String |
| | *parentXpath* (producer) | Sets the XPath to find the parent node in the enveloped case. Either you specify the parent node via this method or the local name and namespace of the parent with the methods setParentLocalName(String) and setParentNamespace(String). Default value is null. The value must be null for enveloping and detached XML signature. If the parameters parentXpath and parentLocalName are specified in the same configuration then an exception is thrown. | | XPathFilterParameterSpec |
| | *plainText* (producer) | Indicator whether the message body contains plain text. The default value is false, indicating that the message body contains XML. The value can be overwritten by the header XmlSignatureConstants#HEADER_MESSAGE_IS_PLAIN_TEXT. | false | Boolean |
| | *plainTextEncoding* (producer) | Encoding of the plain text. Only relevant if the message body is plain text (see parameter plainText. Default value is UTF-8. | UTF-8 | String |
| | *prefixForXmlSignatureNamespace* (producer) | Namespace prefix for the XML signature namespace \http://www.w3.org/2000/09/xmldsig#. Default value is ds. If null or an empty value is set then no prefix is used for the XML signature namespace. See best practice \http://www.w3.org/TR/xmldsig-bestpractices/#signing-xml- without-namespaces | ds | String |
| | *properties* (producer) | For adding additional References and Objects to the XML signature which contain additional properties, you can provide a bean which implements the XmlSignatureProperties interface. | | XmlSignatureProperties |
| | *schemaResourceUri* (producer) | Classpath to the XML Schema. Must be specified in the detached XML Signature case for determining the ID attributes, might be set in the enveloped and enveloping case. If set, then the XML document is validated with the specified XML schema. The schema resource URI can be overwritten by the header XmlSignatureConstants#HEADER_SCHEMA_RESOURCE_URI. | | String |
| | *signatureAlgorithm* (producer) | Signature algorithm. Default value is \http://www.w3.org/2000/09/xmldsig#rsa-sha1. | http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 | String |
| | *signatureId* (producer) | Sets the signature Id. If this parameter is not set (null value) then a unique ID is generated for the signature ID (default). If this parameter is set to (empty string) then no Id attribute is created in the signature element. | | String |
| | *transformMethods* (producer) | 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. | | List |
| | *xpathsToIdAttributes* (producer) | Define the elements which are signed in the detached case via XPATH expressions to ID attributes (attributes of type ID). For each element found via the XPATH expression a detached signature is created whose reference URI contains the corresponding attribute value (preceded by '#'). The signature becomes the last sibling of the signed element. Elements with deeper hierarchy level are signed first. You can also set the XPATH list dynamically via the header XmlSignatureConstants#HEADER_XPATHS_TO_ID_ATTRIBUTES. The parameter setParentLocalName(String) or setParentXpath(XPathFilterParameterSpec) for enveloped signature and this parameter for detached signature must not be set in the same configuration. | | List |
| | *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean |
| | *signerConfiguration* (advanced) | To use a shared XmlSignerConfiguration configuration to use as base for configuring endpoints. | | XmlSignerConfiguration |
| | *uriDereferencer* (advanced) | If you want to restrict the remote access via reference URIs, you can set an own dereferencer. Optional parameter. If not set the provider default dereferencer is used which can resolve URI fragments, HTTP, file and XPpointer URIs. Attention: The implementation is provider dependent! | | URIDereferencer |
| |=== |
| // component options: END |
| |
| |
| |
| |
| |
| |
| == Endpoint Options |
| |
| |
| // endpoint options: START |
| The XML Security Sign endpoint is configured using URI syntax: |
| |
| ---- |
| xmlsecurity-sign:name |
| ---- |
| |
| with the following path and query parameters: |
| |
| === Path Parameters (1 parameters): |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *name* | *Required* The name part in the URI can be chosen by the user to distinguish between different signer endpoints within the camel context. | | String |
| |=== |
| |
| |
| === Query Parameters (29 parameters): |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *addKeyInfoReference* (producer) | In order to protect the KeyInfo element from tampering you can add a reference to the signed info element so that it is protected via the signature value. The default value is true. Only relevant when a KeyInfo is returned by KeyAccessor. and KeyInfo#getId() is not null. | true | Boolean |
| | *baseUri* (producer) | You can set a base URI which is used in the URI dereferencing. Relative URIs are then concatenated with the base URI. | | String |
| | *canonicalizationMethod* (producer) | 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 inclusiveNamespacePrefixes) to create a canonicalization method. | http://www.w3.org/TR/2001/REC-xml-c14n-20010315 | AlgorithmMethod |
| | *clearHeaders* (producer) | Determines if the XML signature specific headers be cleared after signing and verification. Defaults to true. | true | Boolean |
| | *contentObjectId* (producer) | Sets the content object Id attribute value. By default a UUID is generated. If you set the null value, then a new UUID will be generated. Only used in the enveloping case. | | String |
| | *contentReferenceType* (producer) | Type of the content reference. The default value is null. This value can be overwritten by the header XmlSignatureConstants#HEADER_CONTENT_REFERENCE_TYPE. | | String |
| | *contentReferenceUri* (producer) | Reference URI for the content to be signed. Only used in the enveloped case. If the reference URI contains an ID attribute value, then the resource schema URI ( setSchemaResourceUri(String)) must also be set because the schema validator will then find out which attributes are ID attributes. Will be ignored in the enveloping or detached case. | | String |
| | *cryptoContextProperties* (producer) | Sets the crypto context properties. See {link XMLCryptoContext#setProperty(String, Object)}. Possible properties are defined in XMLSignContext an XMLValidateContext (see Supported Properties). The following properties are set by default to the value Boolean#TRUE for the XML validation. If you want to switch these features off you must set the property value to Boolean#FALSE. org.jcp.xml.dsig.validateManifests javax.xml.crypto.dsig.cacheReference | | Map |
| | *digestAlgorithm* (producer) | Digest algorithm URI. Optional parameter. This digest algorithm is used for calculating the digest of the input message. If this digest algorithm is not specified then the digest algorithm is calculated from the signature algorithm. Example: \http://www.w3.org/2001/04/xmlenc#sha256 | | String |
| | *disallowDoctypeDecl* (producer) | Disallows that the incoming XML document contains DTD DOCTYPE declaration. The default value is Boolean#TRUE. | true | Boolean |
| | *keyAccessor* (producer) | For the signing process, a private key is necessary. You specify a key accessor bean which provides this private 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. | | KeyAccessor |
| | *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean |
| | *omitXmlDeclaration* (producer) | Indicator whether the XML declaration in the outgoing message body should be omitted. Default value is false. Can be overwritten by the header XmlSignatureConstants#HEADER_OMIT_XML_DECLARATION. | false | Boolean |
| | *outputXmlEncoding* (producer) | The character encoding of the resulting signed XML document. If null then the encoding of the original XML document is used. | | String |
| | *parentLocalName* (producer) | Local name of the parent element to which the XML signature element will be added. Only relevant for enveloped XML signature. Alternatively you can also use setParentXpath(XPathFilterParameterSpec). Default value is null. The value must be null for enveloping and detached XML signature. This parameter or the parameter setParentXpath(XPathFilterParameterSpec) for enveloped signature and the parameter setXpathsToIdAttributes(List) for detached signature must not be set in the same configuration. If the parameters parentXpath and parentLocalName are specified in the same configuration then an exception is thrown. | | String |
| | *parentNamespace* (producer) | Namespace of the parent element to which the XML signature element will be added. | | String |
| | *parentXpath* (producer) | Sets the XPath to find the parent node in the enveloped case. Either you specify the parent node via this method or the local name and namespace of the parent with the methods setParentLocalName(String) and setParentNamespace(String). Default value is null. The value must be null for enveloping and detached XML signature. If the parameters parentXpath and parentLocalName are specified in the same configuration then an exception is thrown. | | XPathFilterParameterSpec |
| | *plainText* (producer) | Indicator whether the message body contains plain text. The default value is false, indicating that the message body contains XML. The value can be overwritten by the header XmlSignatureConstants#HEADER_MESSAGE_IS_PLAIN_TEXT. | false | Boolean |
| | *plainTextEncoding* (producer) | Encoding of the plain text. Only relevant if the message body is plain text (see parameter plainText. Default value is UTF-8. | UTF-8 | String |
| | *prefixForXmlSignatureNamespace* (producer) | Namespace prefix for the XML signature namespace \http://www.w3.org/2000/09/xmldsig#. Default value is ds. If null or an empty value is set then no prefix is used for the XML signature namespace. See best practice \http://www.w3.org/TR/xmldsig-bestpractices/#signing-xml- without-namespaces | ds | String |
| | *properties* (producer) | For adding additional References and Objects to the XML signature which contain additional properties, you can provide a bean which implements the XmlSignatureProperties interface. | | XmlSignatureProperties |
| | *schemaResourceUri* (producer) | Classpath to the XML Schema. Must be specified in the detached XML Signature case for determining the ID attributes, might be set in the enveloped and enveloping case. If set, then the XML document is validated with the specified XML schema. The schema resource URI can be overwritten by the header XmlSignatureConstants#HEADER_SCHEMA_RESOURCE_URI. | | String |
| | *signatureAlgorithm* (producer) | Signature algorithm. Default value is \http://www.w3.org/2000/09/xmldsig#rsa-sha1. | http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 | String |
| | *signatureId* (producer) | Sets the signature Id. If this parameter is not set (null value) then a unique ID is generated for the signature ID (default). If this parameter is set to (empty string) then no Id attribute is created in the signature element. | | String |
| | *transformMethods* (producer) | 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. | | List |
| | *xpathsToIdAttributes* (producer) | Define the elements which are signed in the detached case via XPATH expressions to ID attributes (attributes of type ID). For each element found via the XPATH expression a detached signature is created whose reference URI contains the corresponding attribute value (preceded by '#'). The signature becomes the last sibling of the signed element. Elements with deeper hierarchy level are signed first. You can also set the XPATH list dynamically via the header XmlSignatureConstants#HEADER_XPATHS_TO_ID_ATTRIBUTES. The parameter setParentLocalName(String) or setParentXpath(XPathFilterParameterSpec) for enveloped signature and this parameter for detached signature must not be set in the same configuration. | | List |
| | *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean |
| | *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean |
| | *uriDereferencer* (advanced) | If you want to restrict the remote access via reference URIs, you can set an own dereferencer. Optional parameter. If not set the provider default dereferencer is used which can resolve URI fragments, HTTP, file and XPpointer URIs. Attention: The implementation is provider dependent! | | URIDereferencer |
| |=== |
| // endpoint options: END |
| |
| |
| |
| |
| === 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 |
| https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/DefaultXmlSignature2Message.java[`DefaultXmlSignature2Message`] |
| of |
| https://github.com/apache/camel/blob/master/components/camel-xmlsecurity/src/main/java/org/apache/camel/component/xmlsecurity/api/XmlSignature2Message.java[`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: |
| |
| [source,xml] |
| ---- |
| <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: |
| |
| [source,xml] |
| ---- |
| <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> |
| ---- |
| |
| == Detached XML Signatures as Siblings of the Signed Elements |
| |
| You can create detached signatures where the signature is a sibling of |
| the signed element. The following example contains two detached |
| signatures. The first signature is for the element `C` and the second |
| signature is for element `A`. The signatures are _nested_; the second |
| signature is for the element `A` which also contains the first signature. |
| |
| *Example Detached XML Signatures* |
| |
| [source,xml] |
| ---- |
| <?xml version="1.0" encoding="UTF-8" ?> |
| <root> |
| <A ID="IDforA"> |
| <B> |
| <C ID="IDforC"> |
| <D>dvalue</D> |
| </C> |
| <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" |
| Id="_6bf13099-0568-4d76-8649-faf5dcb313c0"> |
| <ds:SignedInfo> |
| <ds:CanonicalizationMethod |
| Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" /> |
| <ds:SignatureMethod |
| Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" /> |
| <ds:Reference URI="#IDforC"> |
| ... |
| </ds:Reference> |
| </ds:SignedInfo> |
| <ds:SignatureValue>aUDFmiG71</ds:SignatureValue> |
| </ds:Signature> |
| </B> |
| </A> |
| <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"Id="_6b02fb8a-30df-42c6-ba25-76eba02c8214"> |
| <ds:SignedInfo> |
| <ds:CanonicalizationMethod |
| Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" /> |
| <ds:SignatureMethod |
| Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" /> |
| <ds:Reference URI="#IDforA"> |
| ... |
| </ds:Reference> |
| </ds:SignedInfo> |
| <ds:SignatureValue>q3tvRoGgc8cMUqUSzP6C21zb7tt04riPnDuk=</ds:SignatureValue> |
| </ds:Signature> |
| <root> |
| ---- |
| |
| The example shows that you can sign several elements and that for each |
| element a signature is created as sibling. The elements to be signed |
| must have an attribute of type ID. The ID type of the attribute must be |
| defined in the XML schema (see option `schemaResourceUri`). You |
| specify a list of XPATH expressions pointing to attributes of type ID |
| (see option `xpathsToIdAttributes`). These attributes determine the |
| elements to be signed. The elements are signed by the same key given by |
| the `keyAccessor` bean. Elements with higher (i.e. deeper) hierarchy level |
| are signed first. In the example, the element `C` is signed before the |
| element `A`. |
| |
| *Java DSL Example* |
| |
| [source,java] |
| ---- |
| from("direct:detached") |
| .to("xmlsecurity-sign://detached?keyAccessor=#keyAccessorBeant&xpathsToIdAttributes=#xpathsToIdAttributesBean&schemaResourceUri=Test.xsd") |
| .to("xmlsecurity-verify://detached?keySelector=#keySelectorBean&schemaResourceUri=org/apache/camel/component/xmlsecurity/Test.xsd") |
| .to("mock:result"); |
| ---- |
| |
| *Spring Example* |
| |
| [source,xml] |
| ---- |
| |
| <bean id="xpathsToIdAttributesBean" class="java.util.ArrayList"> |
| <constructor-arg type="java.util.Collection"> |
| <list> |
| <bean |
| class="org.apache.camel.component.xmlsecurity.api.XmlSignatureHelper" |
| factory-method="getXpathFilter"> |
| <constructor-arg type="java.lang.String" |
| value="/ns:root/a/@ID" /> |
| <constructor-arg> |
| <map key-type="java.lang.String" value-type="java.lang.String"> |
| <entry key="ns" value="http://test" /> |
| </map> |
| </constructor-arg> |
| </bean> |
| </list> |
| </constructor-arg> |
| </bean> |
| ... |
| <from uri="direct:detached" /> |
| <to |
| uri="xmlsecurity-sign://detached?keyAccessor=#keyAccessorBean&xpathsToIdAttributes=#xpathsToIdAttributesBean&schemaResourceUri=Test.xsd" /> |
| <to |
| uri="xmlsecurity-verify://detached?keySelector=#keySelectorBean&schemaResourceUri=Test.xsd" /> |
| <to uri="mock:result" /> |
| ---- |
| |
| |
| == XAdES-BES/EPES for the Signer Endpoint |
| |
| *Since Camel 2.15.0* |
| |
| http://www.etsi.org/deliver/etsi_ts/101900_101999/101903/01.04.02_60/ts_101903v010402p.pdf[XML |
| Advanced Electronic Signatures (XAdES)] defines extensions to XML |
| Signature. This standard was defined by the |
| http://www.etsi.org/[European Telecommunication Standards Institute] and |
| allows you to create signatures which are compliant to the |
| http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2000:013:0012:0020:EN:PDF[European |
| Union Directive (1999/93/EC) on a Community framework for electronic |
| signatures]. XAdES defines different sets of signature properties which |
| are called signature forms. We support the signature forms *Basic |
| Electronic Signature* (XAdES-BES) and *Explicit Policy Based Electronic |
| Signature* (XAdES-EPES) for the Signer Endpoint. The forms |
| **Electronic ****Signature with Validation Data** XAdES-T and XAdES-C |
| are not supported. |
| |
| |
| We support the following properties of the XAdES-EPES form ("?" denotes |
| zero or one occurrence): |
| |
| |
| *Supported XAdES-EPES Properties* |
| |
| [source,xml] |
| ---- |
| <QualifyingProperties Target> |
| <SignedProperties> |
| <SignedSignatureProperties> |
| (SigningTime)? |
| (SigningCertificate)? |
| (SignaturePolicyIdentifier) |
| (SignatureProductionPlace)? |
| (SignerRole)? |
| </SignedSignatureProperties> |
| <SignedDataObjectProperties> |
| (DataObjectFormat)? |
| (CommitmentTypeIndication)? |
| </SignedDataObjectProperties> |
| </SignedProperties> |
| </QualifyingProperties> |
| ---- |
| |
| The properties of the XAdES-BES form are the same except that |
| the `SignaturePolicyIdentifier` property is not part of XAdES-BES. |
| |
| You can configure the XAdES-BES/EPES properties via the |
| bean `org.apache.camel.component.xmlsecurity.api.XAdESSignatureProperties` |
| or `org.apache.camel.component.xmlsecurity.api.DefaultXAdESSignatureProperties. XAdESSignatureProperties` does |
| support all properties mentioned above except |
| the `SigningCertificate` property. To get |
| the `SigningCertificate` property, you must overwrite either the |
| method `XAdESSignatureProperties.getSigningCertificate()` or `XAdESSignatureProperties.getSigningCertificateChain()`. The |
| class `DefaultXAdESSignatureProperties` overwrites the |
| method `getSigningCertificate()` and allows you to specify the signing |
| certificate via a keystore and alias. The following example shows all |
| parameters you can specify. If you do not need certain parameters you |
| can just omit them. |
| |
| *XAdES-BES/EPES Example in Java DSL* |
| |
| [source,java] |
| ---- |
| Keystore keystore = ... // load a keystore |
| DefaultKeyAccessor accessor = new DefaultKeyAccessor(); |
| accessor.setKeyStore(keystore); |
| accessor.setPassword("password"); |
| accessor.setAlias("cert_alias"); // signer key alias |
| |
| DefaultXAdESSignatureProperties props = new DefaultXAdESSignatureProperties(); |
| props.setNamespace("http://uri.etsi.org/01903/v1.3.2#"); // sets the namespace for the XAdES elements; the namspace is related to the XAdES version, default value is "http://uri.etsi.org/01903/v1.3.2#", other possible values are "http://uri.etsi.org/01903/v1.1.1#" and "http://uri.etsi.org/01903/v1.2.2#" |
| props.setPrefix("etsi"); // sets the prefix for the XAdES elements, default value is "etsi" |
| |
| // signing certificate |
| props.setKeystore(keystore)); |
| props.setAlias("cert_alias"); // specify the alias of the signing certificate in the keystore = signer key alias |
| props.setDigestAlgorithmForSigningCertificate(DigestMethod.SHA256); // possible values for the algorithm are "http://www.w3.org/2000/09/xmldsig#sha1", "http://www.w3.org/2001/04/xmlenc#sha256", "http://www.w3.org/2001/04/xmldsig-more#sha384", "http://www.w3.org/2001/04/xmlenc#sha512", default value is "http://www.w3.org/2001/04/xmlenc#sha256" |
| props.setSigningCertificateURIs(Collections.singletonList("http://certuri")); |
| |
| // signing time |
| props.setAddSigningTime(true); |
| |
| // policy |
| props.setSignaturePolicy(XAdESSignatureProperties.SIG_POLICY_EXPLICIT_ID); |
| // also the values XAdESSignatureProperties.SIG_POLICY_NONE ("None"), and XAdESSignatureProperties.SIG_POLICY_IMPLIED ("Implied")are possible, default value is XAdESSignatureProperties.SIG_POLICY_EXPLICIT_ID ("ExplicitId") |
| // For "None" and "Implied" you must not specify any further policy parameters |
| props.setSigPolicyId("urn:oid:1.2.840.113549.1.9.16.6.1"); |
| props.setSigPolicyIdQualifier("OIDAsURN"); //allowed values are empty string, "OIDAsURI", "OIDAsURN"; default value is empty string |
| props.setSigPolicyIdDescription("invoice version 3.1"); |
| props.setSignaturePolicyDigestAlgorithm(DigestMethod.SHA256);// possible values for the algorithm are "http://www.w3.org/2000/09/xmldsig#sha1", http://www.w3.org/2001/04/xmlenc#sha256", "http://www.w3.org/2001/04/xmldsig-more#sha384", "http://www.w3.org/2001/04/xmlenc#sha512", default value is http://www.w3.org/2001/04/xmlenc#sha256" |
| props.setSignaturePolicyDigestValue("Ohixl6upD6av8N7pEvDABhEL6hM="); |
| // you can add qualifiers for the signature policy either by specifying text or an XML fragment with the root element "SigPolicyQualifier" |
| props.setSigPolicyQualifiers(Arrays |
| .asList(new String[] { |
| "<SigPolicyQualifier xmlns=\"http://uri.etsi.org/01903/v1.3.2#\"><SPURI>http://test.com/sig.policy.pdf</SPURI><SPUserNotice><ExplicitText>display text</ExplicitText>" |
| + "</SPUserNotice></SigPolicyQualifier>", "category B" })); |
| props.setSigPolicyIdDocumentationReferences(Arrays.asList(new String[] {"http://test.com/policy.doc.ref1.txt", |
| "http://test.com/policy.doc.ref2.txt" })); |
| |
| // production place |
| props.setSignatureProductionPlaceCity("Munich"); |
| props.setSignatureProductionPlaceCountryName("Germany"); |
| props.setSignatureProductionPlacePostalCode("80331"); |
| props.setSignatureProductionPlaceStateOrProvince("Bavaria"); |
| |
| //role |
| // you can add claimed roles either by specifying text or an XML fragment with the root element "ClaimedRole" |
| props.setSignerClaimedRoles(Arrays.asList(new String[] {"test", |
| "<a:ClaimedRole xmlns:a=\"http://uri.etsi.org/01903/v1.3.2#\"><TestRole>TestRole</TestRole></a:ClaimedRole>" })); |
| props.setSignerCertifiedRoles(Collections.singletonList(new XAdESEncapsulatedPKIData("Ahixl6upD6av8N7pEvDABhEL6hM=", |
| "http://uri.etsi.org/01903/v1.2.2#DER", "IdCertifiedRole"))); |
| |
| // data object format |
| props.setDataObjectFormatDescription("invoice"); |
| props.setDataObjectFormatMimeType("text/xml"); |
| props.setDataObjectFormatIdentifier("urn:oid:1.2.840.113549.1.9.16.6.2"); |
| props.setDataObjectFormatIdentifierQualifier("OIDAsURN"); //allowed values are empty string, "OIDAsURI", "OIDAsURN"; default value is empty string |
| props.setDataObjectFormatIdentifierDescription("identifier desc"); |
| props.setDataObjectFormatIdentifierDocumentationReferences(Arrays.asList(new String[] { |
| "http://test.com/dataobject.format.doc.ref1.txt", "http://test.com/dataobject.format.doc.ref2.txt" })); |
| |
| //commitment |
| props.setCommitmentTypeId("urn:oid:1.2.840.113549.1.9.16.6.4"); |
| props.setCommitmentTypeIdQualifier("OIDAsURN"); //allowed values are empty string, "OIDAsURI", "OIDAsURN"; default value is empty string |
| props.setCommitmentTypeIdDescription("description for commitment type ID"); |
| props.setCommitmentTypeIdDocumentationReferences(Arrays.asList(new String[] {"http://test.com/commitment.ref1.txt", |
| "http://test.com/commitment.ref2.txt" })); |
| // you can specify a commitment type qualifier either by simple text or an XML fragment with root element "CommitmentTypeQualifier" |
| props.setCommitmentTypeQualifiers(Arrays.asList(new String[] {"commitment qualifier", |
| "<c:CommitmentTypeQualifier xmlns:c=\"http://uri.etsi.org/01903/v1.3.2#\"><C>c</C></c:CommitmentTypeQualifier>" })); |
| |
| beanRegistry.bind("xmlSignatureProperties",props); |
| beanRegistry.bind("keyAccessorDefault",keyAccessor); |
| |
| // you must reference the properties bean in the "xmlsecurity" URI |
| from("direct:xades").to("xmlsecurity-sign://xades?keyAccessor=#keyAccessorDefault&properties=#xmlSignatureProperties") |
| .to("mock:result"); |
| ---- |
| |
| *XAdES-BES/EPES Example in Spring XML* |
| |
| [source,xml] |
| ---- |
| ... |
| <from uri="direct:xades" /> |
| <to |
| uri="xmlsecurity-sign://xades?keyAccessor=#accessorRsa&properties=#xadesProperties" /> |
| <to uri="mock:result" /> |
| ... |
| <bean id="xadesProperties" |
| class="org.apache.camel.component.xmlsecurity.api.XAdESSignatureProperties"> |
| <!-- For more properties see the previous Java DSL example. |
| If you want to have a signing certificate then use the bean class DefaultXAdESSignatureProperties (see the previous Java DSL example). --> |
| <property name="signaturePolicy" value="ExplicitId" /> |
| <property name="sigPolicyId" value="http://www.test.com/policy.pdf" /> |
| <property name="sigPolicyIdDescription" value="factura" /> |
| <property name="signaturePolicyDigestAlgorithm" value="http://www.w3.org/2000/09/xmldsig#sha1" /> |
| <property name="signaturePolicyDigestValue" value="Ohixl6upD6av8N7pEvDABhEL1hM=" /> |
| <property name="signerClaimedRoles" ref="signerClaimedRoles_XMLSigner" /> |
| <property name="dataObjectFormatDescription" value="Factura electrónica" /> |
| <property name="dataObjectFormatMimeType" value="text/xml" /> |
| </bean> |
| <bean class="java.util.ArrayList" id="signerClaimedRoles_XMLSigner"> |
| <constructor-arg> |
| <list> |
| <value>Emisor</value> |
| <value><ClaimedRole |
| xmlns="http://uri.etsi.org/01903/v1.3.2#"><test |
| xmlns="http://test.com/">test</test></ClaimedRole></value> |
| </list> |
| </constructor-arg> |
| </bean> |
| ---- |
| |
| === Headers |
| |
| [width="100%",cols="1m,1m,4",options="header",] |
| |======================================================================= |
| |Header |Type |Description |
| |CamelXmlSignatureXAdESQualifyingPropertiesId |String |for the 'Id' |
| attribute value of `QualifyingProperties` element |
| |
| |CamelXmlSignatureXAdESSignedDataObjectPropertiesId |String |for the |
| 'Id' attribute value of `SignedDataObjectProperties` element |
| |
| |CamelXmlSignatureXAdESSignedSignaturePropertiesId |String |for the |
| 'Id' attribute value of `SignedSignatureProperties` element |
| |
| |CamelXmlSignatureXAdESDataObjectFormatEncoding |String |for the value |
| of the Encoding element of the `DataObjectFormat` element |
| |
| |CamelXmlSignatureXAdESNamespace |String | overwrites the XAdES |
| namespace parameter value |
| |
| |CamelXmlSignatureXAdESPrefix |String |overwrites the XAdES prefix |
| parameter value |
| |======================================================================= |
| |
| === Limitations with regard to XAdES version 1.4.2 |
| |
| * No support for signature form XAdES-T and XAdES-C |
| * Only signer part implemented. Verifier part currently not available. |
| * No support for the `QualifyingPropertiesReference` element (see |
| section 6.3.2 of spec). |
| * No support for the `Transforms` element contained in |
| the `SignaturePolicyId` element contained in |
| the `SignaturePolicyIdentifier element` |
| * No support of the `CounterSignature` element -> no support for |
| the `UnsignedProperties` element |
| * At most one `DataObjectFormat` element. More than one |
| `DataObjectFormat` element makes no sense because we have only one data |
| object which is signed (this is the incoming message body to the XML |
| signer endpoint). |
| * At most one `CommitmentTypeIndication` element. More than one |
| `CommitmentTypeIndication` element makes no sense because we have only |
| one data object which is signed (this is the incoming message body to |
| the XML signer endpoint). |
| * A `CommitmentTypeIndication` element contains always the |
| `AllSignedDataObjects` element. The `ObjectReference` element within |
| `CommitmentTypeIndication` element is not supported. |
| * The `AllDataObjectsTimeStamp` element is not supported |
| * The `IndividualDataObjectsTimeStamp` element is not supported |
| |
| |
| include::camel-spring-boot::page$xmlsecurity-starter.adoc[] |