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 <anco...@gmail.com> Authored: Thu Apr 21 18:09:05 2016 +0200 Committer: Andrea Cosentino <anco...@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)
