You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/04/21 18:59:23 UTC
[2/5] camel git commit: Added camel-jasypt docs to gitbook
Added camel-jasypt 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/5a5fa393
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/5a5fa393
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/5a5fa393
Branch: refs/heads/master
Commit: 5a5fa393c09c032a353e711439e9bd67ff556869
Parents: a858596
Author: Andrea Cosentino <an...@gmail.com>
Authored: Thu Apr 21 18:09:05 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Thu Apr 21 18:09:05 2016 +0200
----------------------------------------------------------------------
.../camel-jasypt/src/main/docs/jasypt.adoc | 332 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 333 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/5a5fa393/components/camel-jasypt/src/main/docs/jasypt.adoc
----------------------------------------------------------------------
diff --git a/components/camel-jasypt/src/main/docs/jasypt.adoc b/components/camel-jasypt/src/main/docs/jasypt.adoc
new file mode 100644
index 0000000..f8467cb
--- /dev/null
+++ b/components/camel-jasypt/src/main/docs/jasypt.adoc
@@ -0,0 +1,332 @@
+[[Jasypt-Jasyptcomponent]]
+Jasypt component
+~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.5*
+
+http://www.jasypt.org/[Jasypt] is a simplified encryption library which
+makes encryption and decryption easy. Camel integrates with Jasypt to
+allow sensitive information in link:properties.html[Properties] files to
+be encrypted. By dropping *`camel-jasypt`* on the classpath those
+encrypted values will automatically be decrypted on-the-fly by Camel.
+This ensures that human eyes can't easily spot sensitive information
+such as usernames and passwords.
+
+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-jasypt</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------
+
+[[Jasypt-Tooling]]
+Tooling
+^^^^^^^
+
+The link:jasypt.html[Jasypt] component provides a little command line
+tooling to encrypt or decrypt values.
+
+The console output the syntax and which options it provides:
+
+[source,java]
+--------------------------------------------------------------
+Apache Camel Jasypt takes the following options
+
+ -h or -help = Displays the help screen
+ -c or -command <command> = Command either encrypt or decrypt
+ -p or -password <password> = Password to use
+ -i or -input <input> = Text to encrypt or decrypt
+ -a or -algorithm <algorithm> = Optional algorithm to use
+--------------------------------------------------------------
+
+For example to encrypt the value `tiger` you run with the following
+parameters. In the apache camel kit, you cd into the lib folder and run
+the following java cmd, where _<CAMEL_HOME>_ is where you have
+downloaded and extract the Camel distribution.
+
+[source,java]
+----------------------------------------------------------------
+$ cd <CAMEL_HOME>/lib
+$ java -jar camel-jasypt-2.5.0.jar -c encrypt -p secret -i tiger
+----------------------------------------------------------------
+
+Which outputs the following result
+
+[source,java]
+----------------------------------------
+Encrypted text: qaEEacuW7BUti8LcMgyjKw==
+----------------------------------------
+
+This means the encrypted representation `qaEEacuW7BUti8LcMgyjKw==` can
+be decrypted back to `tiger` if you know the master password which was
+`secret`. +
+ If you run the tool again then the encrypted value will return a
+different result. But decrypting the value will always return the
+correct original value.
+
+So you can test it by running the tooling using the following
+parameters:
+
+[source,java]
+-----------------------------------------------------------------------------------
+$ cd <CAMEL_HOME>/lib
+$ java -jar camel-jasypt-2.5.0.jar -c decrypt -p secret -i qaEEacuW7BUti8LcMgyjKw==
+-----------------------------------------------------------------------------------
+
+Which outputs the following result:
+
+[source,java]
+---------------------
+Decrypted text: tiger
+---------------------
+
+The idea is then to use those encrypted values in your
+link:properties.html[Properties] files. Notice how the password value is
+encrypted and the value has the tokens surrounding `ENC(value here)`
+
+[[Jasypt-ToolingdependenciesforCamel2.5and2.6]]
+Tooling dependencies for Camel 2.5 and 2.6
+++++++++++++++++++++++++++++++++++++++++++
+
+The tooling requires the following JARs in the classpath, which has been
+enlisted in the `MANIFEST.MF` file of `camel-jasypt` with `optional/` as
+prefix. Hence why the java cmd above can pickup the needed JARs from the
+Apache Distribution in the `optional` directory.
+
+[source,java]
+-------------------------------------------------------------------------
+jasypt-1.6.jar commons-lang-2.4.jar commons-codec-1.4.jar icu4j-4.0.1.jar
+-------------------------------------------------------------------------
+
+[Info]
+====
+ *Java 1.5 users*
+
+The `icu4j-4.0.1.jar` is only needed when running on JDK 1.5.
+
+This JAR is not distributed by Apache Camel and you have to download it
+manually and copy it to the `lib/optional` directory of the Camel
+distribution. +
+ You can download it from
+http://repo2.maven.org/maven2/com/ibm/icu/icu4j/4.0.1/[Apache Central
+Maven repo].
+
+====
+
+[[Jasypt-ToolingdependenciesforCamel2.7orbetter]]
+Tooling dependencies for Camel 2.7 or better
+++++++++++++++++++++++++++++++++++++++++++++
+
+Jasypt 1.7 onwards is now fully standalone so no additional JARs is
+needed.
+
+[[Jasypt-URIOptions]]
+URI Options
+^^^^^^^^^^^
+
+The options below are exclusive for the link:jasypt.html[Jasypt]
+component.
+
+[width="100%",cols="10%,10%,10%,70%",options="header",]
+|=======================================================================
+|Name |Default Value |Type |Description
+
+|`password` |`null` |`String` |Specifies the master password to use for decrypting. This option is
+mandatory. See below for more details.
+
+|`algorithm` |`null` |`String` |Name of an optional algorithm to use.
+|=======================================================================
+
+[[Jasypt-Protectingthemasterpassword]]
+Protecting the master password
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The master password used by link:jasypt.html[Jasypt] must be provided,
+so that it's capable of decrypting the values. However having this
+master password out in the open may not be an ideal solution. Therefore
+you could for example provide it as a JVM system property or as a OS
+environment setting. If you decide to do so then the `password` option
+supports prefixes which dictates this. `sysenv:` means to lookup the OS
+system environment with the given key. `sys:` means to lookup a JVM
+system property.
+
+For example you could provided the password before you start the
+application
+
+[source,java]
+-----------------------------------------
+$ export CAMEL_ENCRYPTION_PASSWORD=secret
+-----------------------------------------
+
+Then start the application, such as running the start script.
+
+When the application is up and running you can unset the environment
+
+[source,java]
+---------------------------------
+$ unset CAMEL_ENCRYPTION_PASSWORD
+---------------------------------
+
+The `password` option is then a matter of defining as follows:
+`password=sysenv:CAMEL_ENCRYPTION_PASSWORD`.
+
+[[Jasypt-ExamplewithJavaDSL]]
+Example with Java DSL
+^^^^^^^^^^^^^^^^^^^^^
+
+In Java DSL you need to configure link:jasypt.html[Jasypt] as a
+`JasyptPropertiesParser` instance and set it on the
+link:properties.html[Properties] component as show below:
+
+The properties file `myproperties.properties` then contain the encrypted
+value, such as shown below. Notice how the password value is encrypted
+and the value has the tokens surrounding `ENC(value here)`
+
+[[Jasypt-ExamplewithSpringXML]]
+Example with Spring XML
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In Spring XML you need to configure the `JasyptPropertiesParser` which
+is shown below. Then the Camel link:properties.html[Properties]
+component is told to use `jasypt` as the properties parser, which means
+link:jasypt.html[Jasypt] has its chance to decrypt values looked up in
+the properties.
+
+[source,xml]
+-----------------------------------------------------------------------------------------------------------
+<!-- define the jasypt properties parser with the given password to be used -->
+<bean id="jasypt" class="org.apache.camel.component.jasypt.JasyptPropertiesParser">
+ <property name="password" value="secret"/>
+</bean>
+
+<!-- define the camel properties component -->
+<bean id="properties" class="org.apache.camel.component.properties.PropertiesComponent">
+ <!-- the properties file is in the classpath -->
+ <property name="location" value="classpath:org/apache/camel/component/jasypt/myproperties.properties"/>
+ <!-- and let it leverage the jasypt parser -->
+ <property name="propertiesParser" ref="jasypt"/>
+</bean>
+-----------------------------------------------------------------------------------------------------------
+
+The link:properties.html[Properties] component can also be inlined
+inside the `<camelContext>` tag which is shown below. Notice how we use
+the `propertiesParserRef` attribute to refer to
+link:jasypt.html[Jasypt].
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------
+<!-- define the jasypt properties parser with the given password to be used -->
+<bean id="jasypt" class="org.apache.camel.component.jasypt.JasyptPropertiesParser">
+ <!-- password is mandatory, you can prefix it with sysenv: or sys: to indicate it should use
+ an OS environment or JVM system property value, so you dont have the master password defined here -->
+ <property name="password" value="secret"/>
+</bean>
+
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <!-- define the camel properties placeholder, and let it leverage jasypt -->
+ <propertyPlaceholder id="properties"
+ location="classpath:org/apache/camel/component/jasypt/myproperties.properties"
+ propertiesParserRef="jasypt"/>
+ <route>
+ <from uri="direct:start"/>
+ <to uri="{{cool.result}}"/>
+ </route>
+</camelContext>
+--------------------------------------------------------------------------------------------------------------
+
+[[Jasypt-ExamplewithBlueprintXML]]
+Example with Blueprint XML
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Blueprint XML you need to configure
+the `JasyptPropertiesParser` which is shown below. Then the
+Camel link:properties.html[Properties] component is told to
+use `jasypt` as the properties parser, which
+means link:jasypt.html[Jasypt] has its chance to decrypt values looked
+up in the properties.
+
+[source,xml]
+----------------------------------------------------------------------------------------------------------------
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
+ xsi:schemaLocation="
+ http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">
+
+ <cm:property-placeholder id="myblue" persistent-id="mypersistent">
+ <!-- list some properties for this test -->
+ <cm:default-properties>
+ <cm:property name="cool.result" value="mock:{{cool.password}}"/>
+ <cm:property name="cool.password" value="ENC(bsW9uV37gQ0QHFu7KO03Ww==)"/>
+ </cm:default-properties>
+ </cm:property-placeholder>
+
+ <!-- define the jasypt properties parser with the given password to be used -->
+ <bean id="jasypt" class="org.apache.camel.component.jasypt.JasyptPropertiesParser">
+ <property name="password" value="secret"/>
+ </bean>
+
+ <camelContext xmlns="http://camel.apache.org/schema/blueprint">
+ <!-- define the camel properties placeholder, and let it leverage jasypt -->
+ <propertyPlaceholder id="properties"
+ location="blueprint:myblue"
+ propertiesParserRef="jasypt"/>
+ <route>
+ <from uri="direct:start"/>
+ <to uri="{{cool.result}}"/>
+ </route>
+ </camelContext>
+
+</blueprint>
+----------------------------------------------------------------------------------------------------------------
+
+The link:properties.html[Properties] component can also be inlined
+inside the `<camelContext>` tag which is shown below. Notice how we use
+the `propertiesParserRef` attribute to refer
+to link:jasypt.html[Jasypt].
+
+[source,xml]
+----------------------------------------------------------------------------------------------------------------
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
+ xsi:schemaLocation="
+ http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">
+
+ <!-- define the jasypt properties parser with the given password to be used -->
+ <bean id="jasypt" class="org.apache.camel.component.jasypt.JasyptPropertiesParser">
+ <property name="password" value="secret"/>
+ </bean>
+
+ <camelContext xmlns="http://camel.apache.org/schema/blueprint">
+ <!-- define the camel properties placeholder, and let it leverage jasypt -->
+ <propertyPlaceholder id="properties"
+ location="classpath:org/apache/camel/component/jasypt/myproperties.properties"
+ propertiesParserRef="jasypt"/>
+ <route>
+ <from uri="direct:start"/>
+ <to uri="{{cool.result}}"/>
+ </route>
+ </camelContext>
+
+</blueprint>
+----------------------------------------------------------------------------------------------------------------
+
+
+
+[[Jasypt-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:security.html[Security]
+* link:properties.html[Properties]
+* http://activemq.apache.org/encrypted-passwords.html[Encrypted
+passwords in ActiveMQ] - ActiveMQ has a similar feature as this
+`camel-jasypt` component
+
http://git-wip-us.apache.org/repos/asf/camel/blob/5a5fa393/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 958f0f1..367d157 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -160,6 +160,7 @@
* [Infinispan](infinispan.adoc)
* [IRC](irc.adoc)
* [Ironmq](ironmq.adoc)
+ * [Jasypt](jasypt.adoc)
* [JMS](jms.adoc)
* [JMX](jmx.adoc)
* [JSON](json.adoc)