You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ja...@apache.org on 2024/01/24 11:43:55 UTC
(camel) branch main updated: CAMEL-20360: Improve and tidy camel-jasypt documentation
This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 9a10353ba1a CAMEL-20360: Improve and tidy camel-jasypt documentation
9a10353ba1a is described below
commit 9a10353ba1ade7dcf65c93347725c3f229255719
Author: James Netherton <ja...@gmail.com>
AuthorDate: Wed Jan 24 07:42:40 2024 +0000
CAMEL-20360: Improve and tidy camel-jasypt documentation
---
components/camel-jasypt/src/main/docs/jasypt.adoc | 228 ++++++++--------------
1 file changed, 76 insertions(+), 152 deletions(-)
diff --git a/components/camel-jasypt/src/main/docs/jasypt.adoc b/components/camel-jasypt/src/main/docs/jasypt.adoc
index bb51a37dfe9..4aeb2a19776 100644
--- a/components/camel-jasypt/src/main/docs/jasypt.adoc
+++ b/components/camel-jasypt/src/main/docs/jasypt.adoc
@@ -32,26 +32,11 @@ for this component:
</dependency>
------------------------------------------------------------
-If you are using an Apache Karaf container, you need to add the following dependency to your `pom.xml`
-for this component:
-
-[source,xml]
-------------------------------------------------------------
-<dependency>
- <groupId>org.apache.karaf.jaas</groupId>
- <artifactId>org.apache.karaf.jaas.jasypt</artifactId>
- <version>x.x.x.x</version>
- <!-- use the same version as your Camel core version -->
-</dependency>
-------------------------------------------------------------
-
-
== Tooling
-The Jasypt component provides a little command line
-tooling to encrypt or decrypt values.
+The Jasypt component is a runnable JAR that provides a command line utility to encrypt or decrypt values.
-The console output the syntax and which options it provides:
+The usage documentation can be output to the console to describe the syntax and options it provides:
[source,text]
--------------------------------------------------------------
@@ -66,15 +51,13 @@ Apache Camel Jasypt takes the following options
-riga or -algorithm <algorithm> = Optional random iv generator 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.
+A simple way of running the tool is with https://www.jbang.dev/[JBang].
+
+For example, to encrypt the value `tiger`, you can use the following parameters. Make sure to specify the version of camel-jasypt that you want to use.
[source,bash]
----------------------------------------------------------------
-$ cd <CAMEL_HOME>/lib
-$ java -jar camel-jasypt-2.5.0.jar -c encrypt -p secret -i tiger
+$ jbang org.apache.camel:camel-jasypt:<camel version here> -c encrypt -p secret -i tiger
----------------------------------------------------------------
Which outputs the following result
@@ -87,17 +70,16 @@ 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
+ 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
+You can test decrypting the value by running the tooling using the following
parameters:
[source,bash]
-----------------------------------------------------------------------------------
-$ cd <CAMEL_HOME>/lib
-$ java -jar camel-jasypt-2.5.0.jar -c decrypt -p secret -i qaEEacuW7BUti8LcMgyjKw==
+$ jbang org.apache.camel:camel-jasypt:<camel version here> -c decrypt -p secret -i qaEEacuW7BUti8LcMgyjKw==
-----------------------------------------------------------------------------------
Which outputs the following result:
@@ -107,37 +89,20 @@ Which outputs the following result:
Decrypted text: tiger
---------------------
-The idea is then to use those encrypted values in your
-xref:ROOT:properties-component.adoc[Properties] files. Notice how the password value is
-encrypted and the value has the tokens surrounding `ENC(value here)`
-
-[TIP]
-====
-When running jasypt tooling, if you come across `java.lang.NoClassDefFoundError: org/jasypt/encryption/pbe/StandardPBEStringEncryptor` this means you have to include jasypt\{version}.jar in your classpath. Example of adding jar to classpath may be copying jasypt\{version}.jar to $JAVA_HOME\jre\lib\ext if you are going to run as `java -jar ...`. The latter may be adding jasypt\{version}.jar to classpath using `-cp`, in that case you should provide main class to execute as eg: `java -cp ja [...]
-====
-
-== URI Options
-
-The options below are exclusive for the Jasypt
-component.
-
-[width="100%",cols="10%m,10%m,10%m,70%",options="header",]
-|=======================================================================
-|Name |Default Value |Type |Description
-
-| password | | string |Specifies the master password to use for decrypting. This option is
-mandatory. See below for more details.
-
-| algorithm | | string |Name of an optional algorithm to use.
-|=======================================================================
+The idea is to then use the encrypted values in your xref:ROOT:properties-component.adoc[Properties] files. For example.
+[source,text]
+---------------------
+# Encrypted value for 'tiger'
+my.secret = ENC(qaEEacuW7BUti8LcMgyjKw==)
+---------------------
== Protecting the master password
The master password used by 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 an OS
+you can provide it as a JVM system property or as an 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
@@ -160,23 +125,51 @@ When the application is up and running you can unset the environment
$ unset CAMEL_ENCRYPTION_PASSWORD
---------------------------------
-The `password` option is then a matter of defining as follows:
-`password=sysenv:CAMEL_ENCRYPTION_PASSWORD`.
+On runtimes like Spring Boot and Quarkus, you can configure a password property in `application.properties` as follows.
+
+[source,text]
+---------------------
+password=sysenv:CAMEL_ENCRYPTION_PASSWORD
+---------------------
-== Example with Java DSL
+Or if configuring `JasyptPropertiesParser` manually, you can set the password like this.
-In Java DSL you need to configure Jasypt as a
-`JasyptPropertiesParser` instance and set it on the
-xref:ROOT:properties-component.adoc[Properties] component as show below:
+[source,java]
+---------------------
+jasyptPropertiesParser.setPassword("sysenv:CAMEL_ENCRYPTION_PASSWORD");
+---------------------
-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)`
+== Example configuration
-[TIP]
+[tabs]
====
-It is possible to configure custom algorithms on the JasyptPropertiesParser like this
-
+Java::
++
+On the Spring Boot and Quarkus runtimes, Camel Jasypt can be configured via configuration properties. Refer to their respective documentation pages for more information.
++
+Else, in Java DSL you need to configure Jasypt as a `JasyptPropertiesParser` instance and set it on the xref:ROOT:properties-component.adoc[Properties] component as show below:
++
+[source,java]
+---------------------
+// create the jasypt properties parser
+JasyptPropertiesParser jasypt = new JasyptPropertiesParser();
+// set the master password (see above for how to do this in a secure way)
+jasypt.setPassword("secret");
+
+// create the properties component
+PropertiesComponent pc = new PropertiesComponent();
+pc.setLocation("classpath:org/apache/camel/component/jasypt/secret.properties");
+// and use the jasypt properties parser so we can decrypt values
+pc.setPropertiesParser(jasypt);
+// end enable nested placeholder support
+pc.setNestedPlaceholder(true);
+
+// add properties component to camel context
+context.setPropertiesComponent(pc);
+---------------------
++
+It is possible to configure custom algorithms on the JasyptPropertiesParser like this.
++
[source,java]
-----------------------------------------------------------------------------------------------------------
JasyptPropertiesParser jasyptPropertiesParser = new JasyptPropertiesParser();
@@ -185,39 +178,47 @@ jasyptPropertiesParser.setAlgorithm("PBEWithHmacSHA256AndAES_256");
jasyptPropertiesParser.setRandomSaltGeneratorAlgorithm("PKCS11");
jasyptPropertiesParser.setRandomIvGeneratorAlgorithm("PKCS11");
-----------------------------------------------------------------------------------------------------------
-====
-
-== Example with Spring XML
++
+The properties file `secret.properties` will contain your encrypted
+configuration values, such as shown below. Notice how the password value is encrypted
+and is surrounded like `ENC(value here)`.
++
+[source,text]
+---------------------
+my.secret.password=ENC(bsW9uV37gQ0QHFu7KO03Ww==)
+---------------------
+XML (Spring)::
++
In Spring XML you need to configure the `JasyptPropertiesParser` which
is shown below. Then the Camel xref:ROOT:properties-component.adoc[Properties]
component is told to use `jasypt` as the properties parser, which means
Jasypt has its chance to decrypt values looked up in
-the properties.
-
+the properties file.
++
[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"/>
+ <property name="location" value="classpath:org/apache/camel/component/jasypt/secret.properties"/>
<!-- and let it leverage the jasypt parser -->
<property name="propertiesParser" ref="jasypt"/>
<!-- end enable nested placeholder -->
<property name="nestedPlaceholder" value="true"/>
</bean>
-----------------------------------------------------------------------------------------------------------
-
++
The xref:ROOT:properties-component.adoc[Properties] component can also be inlined
inside the `<camelContext>` tag which is shown below. Notice how we use
the `propertiesParserRef` attribute to refer to
Jasypt.
-
++
[source,xml]
--------------------------------------------------------------------------------------------------------------
<!-- define the jasypt properties parser with the given password to be used -->
@@ -226,11 +227,11 @@ Jasypt.
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"
+ location="classpath:org/apache/camel/component/jasypt/secret.properties"
nestedPlaceholder="true"
propertiesParserRef="jasypt"/>
<route>
@@ -239,83 +240,6 @@ Jasypt.
</route>
</camelContext>
--------------------------------------------------------------------------------------------------------------
-
-== Example with Blueprint XML
-
-In Blueprint XML you need to configure
-the `JasyptPropertiesParser` which is shown below. Then the
-Camel xref:ROOT:properties-component.adoc[Properties] component is told to
-use `jasypt` as the properties parser, which
-means 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"
- nestedPlaceholder="true"
- propertiesParserRef="jasypt"/>
- <route>
- <from uri="direct:start"/>
- <to uri="{{cool.result}}"/>
- </route>
- </camelContext>
-
-</blueprint>
-----------------------------------------------------------------------------------------------------------------
-
-The xref:ROOT:properties-component.adoc[Properties] component can also be inlined
-inside the `<camelContext>` tag which is shown below. Notice how we use
-the `propertiesParserRef` attribute to refer
-to 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"
- nestedPlaceholder="true"
- propertiesParserRef="jasypt"/>
- <route>
- <from uri="direct:start"/>
- <to uri="{{cool.result}}"/>
- </route>
- </camelContext>
-
-</blueprint>
-----------------------------------------------------------------------------------------------------------------
+====
include::spring-boot:partial$starter.adoc[]