yaafi-crypto/xdocs/examples.xml - turbine-fulcrum-intake - Git at Google

 <?xml version="1.0"?>
 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->
 <document>

   <properties>
     <title>Fulcrum Crypto Library Examples</title>
      <author email="gk@apache.org">Georg Kallidis</author>
   </properties>

   <body>
     <section name="Short Examples">
           <subsection name="Command line Usage">
               <p>
 Encrypt with default PCM the string "mysecretgeheim" and meta password "changeit", outputs encrypted string to stdout.
                 <source>
                 <![CDATA[
  java -classpath target/classes org.apache.fulcrum.jce.crypto.cli.CLI2 string enc changeit mysecretgeheim
  ]]>
                 </source>
  <source>
                 <![CDATA[
  java -jar target/fulcrum-yaafi-crypto-<version>.jar string enc:GCM changeit mysecretgeheim
  ]]>
                 </source>
 This prints out the encrypted "mysecretgeheim".
  <source>
                 <![CDATA[
  java -jar target/fulcrum-yaafi-crypto-<version>.jar string dec:GCM changeit 88f8ecc93cc921672e13862d75f90c55a4cc2d823c36e6ac3da0225e397770f45d3944f6be859fe25d053a8442313a5a2581e7edf081030e
  ]]>
                 </source>
 This decrypts the result to stdout and prints information (supported type, matched type ..) to system.err.
          </p>
 	<p>CLI Usage Help:
  <source>
                 <![CDATA[
  java -jar target/fulcrum-yaafi-crypto-<version>.jar help
  ]]>
                 </source>
  Information about supported cipher libs:
                 <source>
                 <![CDATA[
  java -jar target/fulcrum-yaafi-crypto-<version>.jar info
  ]]>
                 </source>
 	</p>
           <p>An example using an ant build tool and property file is provided in pom-xml with phase integration-test.
           By default running this will write the encrypted password to target/integration-test/filter-integration-test.properties and the decrypted password to target/integration-test/filtered-pw.properties. You could play with this toll on the command line providing a custom secret and meta password like this (assuming -Dskip.pw.gen=false -Dskip.pw.encrypt=false):
                 <source>
                 <![CDATA[
 mvn integration-test -Dtest.password="xyz" -Dmeta.pw="abc"
  ]]>
                 </source>
          </p>


             </subsection>
      <subsection name="Code Usage">
        <p>
           <source>
 <![CDATA[
     // provide target_password, meta_password

     char[] password = meta_password.toCharArray();
     // default
     CryptoUtilJ8 cryptoUtilJ8 = CryptoUtilJ8.getInstance();

     String result = null;
     String encryptedValue;targetValue

     try {
         encryptedValue = cryptoUtilJ8.encryptString(target_password, password);
         System.out.println("encrypted:" + encryptedValue);
     } catch (GeneralSecurityException | IOException e) {
         // fail();
     }
     try {
         String encryptedValue = target_password_encrypted;
         result = cryptoUtilJ8.decryptString(encryptedValue, password);
         // should equal targetValue
         System.out.println("decrypted result:" + result);
     } catch (GeneralSecurityException | IOException e) {
         ...
     }
   ]]>
               </source>
            </p>
       </subsection>
    </section>
    <section name="Building a Project">
       <subsection name="Prepare the crypto-tool with Maven Assembly">
          <p>First we build our crypto tool as executable jar in phase initialize (i.e. very early, to use it later) and name it <i>crypto-tool</i>
             using the assembly description saved in the file <i>build/assembly.xml</i> described below.
             Add this into your project pom.xml file.
             <source>
                 <![CDATA[
 <plugin>
     <artifactId>maven-assembly-plugin</artifactId>
     <version>3.3.0</version>
     <configuration>
        <finalName>crypto-tool</finalName>
         <archive>
             <manifest>
                 <mainClass>org.apache.fulcrum.jce.crypto.cli.CLI2</mainClass>
             </manifest>
         </archive>
         <descriptors>
             <descriptor>build/assembly.xml</descriptor>
           </descriptors>
         <appendAssemblyId>false</appendAssemblyId>
     </configuration>
     <executions>
   <execution>
     <id>make-assembly</id> <!-- this is used for inheritance merges -->
     <phase>initialize</phase> <!-- bind to the packaging phase -->
     <goals>
       <goal>single</goal>
     </goals>
    </execution>
   </executions>
 </plugin>
                 ]]>
       </source>
    </p>
    <p>Using this assembly description (adapted to our needs from the descriptor-ref jar-with-dependencies) the executable jar will be generated
        in target folder and will just include fulcrum yaafi-crypto classes.
        Here you will get a very tiny jar (build with java 8 on windows less than 45kb), as the tool has no library dependencies!
       <source>
                 <![CDATA[
 <assembly xmlns="http://maven.apache.org/ASSEMBLY/2.1.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.1.0 http://maven.apache.org/xsd/assembly-2.1.0.xsd">
   <id>crypto-tool-jar-with-dependencies</id>
   <formats>
     <format>jar</format>
   </formats>
   <includeBaseDirectory>false</includeBaseDirectory>
   <dependencySets>
     <dependencySet>
       <outputDirectory>/</outputDirectory>
       <useProjectArtifact>true</useProjectArtifact>
       <unpack>true</unpack>
       <scope>runtime</scope>
       <includes>
         <include>org.apache.fulcrum:fulcrum-yaafi-crypto</include>
       </includes>
     </dependencySet>
   </dependencySets>
 </assembly>
                 ]]>
      </source>
  </p>
  <p>After executing the following command the <i>crypto tool</i> is available in your project and
    we could use it to generate an encrypted password using a master password (to be saved separately and not in the project).
    This is done in the following step.
    <source>
             <![CDATA[
  mvn initialize
                ]]>
     </source>
     </p>
   </subsection>
   <subsection name="Integrate with Ant Tool - Extended">
     <p>Check the pom.xml's integration test ant calls. The following is an extended version using its own assembly, but is very similar to the integration test.</p>
     <p>First we <i>encrypt</i> the password on the command line using our master password and after that we copy and save the encrypted password in one of our project's configuration files.
       Running the following command will show the encrypted password.
       <source>
             <![CDATA[
  java -jar target/crypto-tool.jar string enc <master.pw> <unencrypted.password>
  ]]>
        </source>
        Save the encrypted password as value with key <i>password_encrypted</i>
       in an existing configuration file of your project, which will be used later.
       You may include this process into your build tool (by invoking target init) similar as we do it for the <i>decrypting</i> process (see below paragraph).
    </p>
    <p>Use the following ant build script (windows only) and save it into <i>build/build-pw.xml</i>. This is the ant build file we use to <i>decrypt</i> the encrypted password and
       use it while building the project. The example is configured as follows:
       The global master password is set as environment variable "<i>meta.pw</i>". The already encrypted password is expected to be set in a source property file <i>source.property.path</i>
       (i.e. configuration file of your project) as value in key <i>password_encrypted</i> .  It will be read in automatically as ant variable ${password_encrypted}.
       The <i>decrypted</i> password will be saved to key "<i>password</i>" in another property file (<i>target.property.path</i>), which should not be set into version control. You may need to create it new.
       You may use the ant tool as is setting the variables in <i>.build.properties</i> or integrate it in your pom.xml build process (see below).
        <source>
    <![CDATA[
 <project basedir="."  default="build" name="build">
   <property environment="env"/>
    <property file=".build.properties"/>
    <!-- reading from the file properties: password_encrypted, password -->
    <property file="${source.property.path}"/>
    <property name="meta.pw" value="${env.meta.pw}"/>

    <target name="testjava">
       <echo message="executing java -version"/>
       <exec executable="cmd" dir="" osfamily="windows" >
         <arg value="/c"/>
          <arg value="java -version"/>
       </exec>
     </target>

    <target name="decrypt">
       <echo message="executing java -jar target/${jarname}.jar string dec ${meta.pw} ${password_encrypted}."/>
       <exec executable="cmd" dir="${build.path}/../" osfamily="windows" resultproperty="success" outputproperty="decoded.pw">
         <arg value="/c"/>
          <arg value="java -jar target/${jarname}.jar string dec ${meta.pw} ${password_encrypted}"/>
       </exec>
     </target>

    <target name="update">
        <echo message="updating password in properties file: ${target.property.path}."/>
        <propertyfile file="${target.property.path}" >
           <entry  key="password" value="${decoded.pw}"/>
         </propertyfile>
     </target>

    <target name="encrypt">
       <echo message="executing java -jar target/${jarname}.jar string enc ${meta.pw} ${password}"/>
       <exec executable="cmd" dir="${build.path}/../" osfamily="windows" resultproperty="success" outputproperty="encoded.pw">
         <arg value="/c"/>
          <arg value="java -jar target/${jarname}.jar string enc ${meta.pw} ${password}"/>
       </exec>
     </target>

   <target name="init-update">
        <echo message="updating password_encrypted in properties file: ${target.property.path}."/>
        <propertyfile file="${target.property.path}" >
           <entry  key="password_encrypted" value="${encoded.pw}"/>
         </propertyfile>
     </target>

   <target name="clean">
    <echo message="cleaning up key password in propert file: ${target.property.path}."/>
        <propertyfile file="${target.property.path}" >
           <entry  key="password" value=""/>
         </propertyfile>
   </target>

   <!-- target name="run">
         <echo message="test output java -jar target/${jarname}.jar string dec ${meta.pw} ${password_encrypted}."/>
         <java jar="./../target/${jarname}.jar" fork="true">
         <arg value="string"/>
         <arg value="dec"/>
         <arg value="${meta_password}"/>
         <arg value="${password_encrypted}"/>
         </java>
   </target-->

   <!-- decrypt to password -->
    <target name="build" depends="testjava, decrypt, update">
   </target>

   <!-- encrypt to password_encrypted -->
     <target name="init" depends="testjava, encrypt, init-update">
   </target>

  </project>
                 ]]>
          </source>
      </p>
   </subsection>
   <subsection name="Integration ANT Task into Maven Life cycle">
     <p>Integrate the ant tool, check the file name and run maven command below after setting your configuration or filter files in <i>source.property.path</i> and <i>target.property.path</i>.
     You may add another clean-up in a later life cycle phase, e.g. post-integration-test.
     You may also simplify the process by cleaning always and using the same source and target property file.
       <source>
             <![CDATA[
 <plugin>
    <artifactId>maven-antrun-plugin</artifactId>
     <version>3.0.0</version>
     <executions>
         <execution>
             <id>build</id>
             <phase>process-sources</phase>
             <configuration>
                <skip>${skip.pw.gen}</skip>
                <target>
                 <ant antfile="${basedir}/build/build-pw.xml" target="build">
                       <property name="build.path" value="${basedir}/build" />
                       <property name="meta.pw" value="${meta.pw}" /><!-- provided by env variable -->
                        <property name="jarname" value="crypto-tool" /><!-- by default ${project.build.finalName} -->
                       <!-- contains encrypted password, saved in vcs: -->
                       <property name="source.property.path" value="${basedir}/src/main/filters/${env}-app.properties" />
                       <!-- should NOT be saved in vcs: -->
                       <property name="target.property.path" value="${basedir}/src/main/filters/${env}-pw.properties" />
                   </ant>
                 </target>
             </configuration>
             <goals>
               <goal>run</goal>
             </goals>
         </execution>
         <execution>
             <id>clean</id>
             <phase>clean</phase>
             <configuration>
                 <skip>${skip.pw.gen}</skip>
                <target>
                 <ant antfile="${basedir}/build/build-pw.xml" target="clean">
                       <property name="build.path" value="${basedir}/build" />
                       <property name="target.property.path" value="${basedir}/src/main/filters/filter-${env}-pw.properties" />
                   </ant>
                 </target>
             </configuration>
             <goals>
               <goal>run</goal>
             </goals>
         </execution>
     </executions>
   </plugin>
             ]]>
        </source>
    You may add another  execution definiton with id and target "init" and probably another skip property to initially or regularily update the encoded password.
      </p>
   </subsection>
   <subsection name="Maven Command line examples">
      <p>Save the decrypted password for the build
          <source>
                 <![CDATA[
 mvn clean test -Dmeta.pw=<securepwd>
                 ]]>
                 </source>
                     </p>
               <p>Keep the unencrypted password in source property files to use it during development or later (you may add a profile).
                 <source>
                 <![CDATA[
 mvn clean test install -Dskip.pw.gen=true
                 ]]>
                 </source>
                     </p>
  <p>Clean up finally.
                 <source>
                 <![CDATA[
 mvn clean
                ]]>
         </source>
     </p>
     <p>This example could be extended or adapted, eg. by using multiple passwords, or encrypting an entire file.
        Have fun!
     </p>

     </subsection>
    </section>

   </body>

 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<document>

	<properties>
	<title>Fulcrum Crypto Library Examples</title>
	<author email="gk@apache.org">Georg Kallidis</author>
	</properties>

	<body>
	<section name="Short Examples">
	<subsection name="Command line Usage">
	<p>
	Encrypt with default PCM the string "mysecretgeheim" and meta password "changeit", outputs encrypted string to stdout.
	<source>
	<![CDATA[
	java -classpath target/classes org.apache.fulcrum.jce.crypto.cli.CLI2 string enc changeit mysecretgeheim
	]]>
	</source>
	<source>
	<![CDATA[
	java -jar target/fulcrum-yaafi-crypto-<version>.jar string enc:GCM changeit mysecretgeheim
	]]>
	</source>
	This prints out the encrypted "mysecretgeheim".
	<source>
	<![CDATA[
	java -jar target/fulcrum-yaafi-crypto-<version>.jar string dec:GCM changeit 88f8ecc93cc921672e13862d75f90c55a4cc2d823c36e6ac3da0225e397770f45d3944f6be859fe25d053a8442313a5a2581e7edf081030e
	]]>
	</source>
	This decrypts the result to stdout and prints information (supported type, matched type ..) to system.err.
	</p>
	<p>CLI Usage Help:
	<source>
	<![CDATA[
	java -jar target/fulcrum-yaafi-crypto-<version>.jar help
	]]>
	</source>
	Information about supported cipher libs:
	<source>
	<![CDATA[
	java -jar target/fulcrum-yaafi-crypto-<version>.jar info
	]]>
	</source>
	</p>
	<p>An example using an ant build tool and property file is provided in pom-xml with phase integration-test.
	By default running this will write the encrypted password to target/integration-test/filter-integration-test.properties and the decrypted password to target/integration-test/filtered-pw.properties. You could play with this toll on the command line providing a custom secret and meta password like this (assuming -Dskip.pw.gen=false -Dskip.pw.encrypt=false):
	<source>
	<![CDATA[
	mvn integration-test -Dtest.password="xyz" -Dmeta.pw="abc"
	]]>
	</source>
	</p>


	</subsection>
	<subsection name="Code Usage">
	<p>
	<source>
	<![CDATA[
	// provide target_password, meta_password

	char[] password = meta_password.toCharArray();
	// default
	CryptoUtilJ8 cryptoUtilJ8 = CryptoUtilJ8.getInstance();

	String result = null;
	String encryptedValue;targetValue

	try {
	encryptedValue = cryptoUtilJ8.encryptString(target_password, password);
	System.out.println("encrypted:" + encryptedValue);
	} catch (GeneralSecurityException \| IOException e) {
	// fail();
	}
	try {
	String encryptedValue = target_password_encrypted;
	result = cryptoUtilJ8.decryptString(encryptedValue, password);
	// should equal targetValue
	System.out.println("decrypted result:" + result);
	} catch (GeneralSecurityException \| IOException e) {
	...
	}
	]]>
	</source>
	</p>
	</subsection>
	</section>
	<section name="Building a Project">
	<subsection name="Prepare the crypto-tool with Maven Assembly">
	<p>First we build our crypto tool as executable jar in phase initialize (i.e. very early, to use it later) and name it <i>crypto-tool</i>
	using the assembly description saved in the file <i>build/assembly.xml</i> described below.
	Add this into your project pom.xml file.
	<source>
	<![CDATA[
	<plugin>
	<artifactId>maven-assembly-plugin</artifactId>
	<version>3.3.0</version>
	<configuration>
	<finalName>crypto-tool</finalName>
	<archive>
	<manifest>
	<mainClass>org.apache.fulcrum.jce.crypto.cli.CLI2</mainClass>
	</manifest>
	</archive>
	<descriptors>
	<descriptor>build/assembly.xml</descriptor>
	</descriptors>
	<appendAssemblyId>false</appendAssemblyId>
	</configuration>
	<executions>
	<execution>
	<id>make-assembly</id> <!-- this is used for inheritance merges -->
	<phase>initialize</phase> <!-- bind to the packaging phase -->
	<goals>
	<goal>single</goal>
	</goals>
	</execution>
	</executions>
	</plugin>
	]]>
	</source>
	</p>
	<p>Using this assembly description (adapted to our needs from the descriptor-ref jar-with-dependencies) the executable jar will be generated
	in target folder and will just include fulcrum yaafi-crypto classes.
	Here you will get a very tiny jar (build with java 8 on windows less than 45kb), as the tool has no library dependencies!
	<source>
	<![CDATA[
	<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.1.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.1.0 http://maven.apache.org/xsd/assembly-2.1.0.xsd">
	<id>crypto-tool-jar-with-dependencies</id>
	<formats>
	<format>jar</format>
	</formats>
	<includeBaseDirectory>false</includeBaseDirectory>
	<dependencySets>
	<dependencySet>
	<outputDirectory>/</outputDirectory>
	<useProjectArtifact>true</useProjectArtifact>
	<unpack>true</unpack>
	<scope>runtime</scope>
	<includes>
	<include>org.apache.fulcrum:fulcrum-yaafi-crypto</include>
	</includes>
	</dependencySet>
	</dependencySets>
	</assembly>
	]]>
	</source>
	</p>
	<p>After executing the following command the <i>crypto tool</i> is available in your project and
	we could use it to generate an encrypted password using a master password (to be saved separately and not in the project).
	This is done in the following step.
	<source>
	<![CDATA[
	mvn initialize
	]]>
	</source>
	</p>
	</subsection>
	<subsection name="Integrate with Ant Tool - Extended">
	<p>Check the pom.xml's integration test ant calls. The following is an extended version using its own assembly, but is very similar to the integration test.</p>
	<p>First we <i>encrypt</i> the password on the command line using our master password and after that we copy and save the encrypted password in one of our project's configuration files.
	Running the following command will show the encrypted password.
	<source>
	<![CDATA[
	java -jar target/crypto-tool.jar string enc <master.pw> <unencrypted.password>
	]]>
	</source>
	Save the encrypted password as value with key <i>password_encrypted</i>
	in an existing configuration file of your project, which will be used later.
	You may include this process into your build tool (by invoking target init) similar as we do it for the <i>decrypting</i> process (see below paragraph).
	</p>
	<p>Use the following ant build script (windows only) and save it into <i>build/build-pw.xml</i>. This is the ant build file we use to <i>decrypt</i> the encrypted password and
	use it while building the project. The example is configured as follows:
	The global master password is set as environment variable "<i>meta.pw</i>". The already encrypted password is expected to be set in a source property file <i>source.property.path</i>
	(i.e. configuration file of your project) as value in key <i>password_encrypted</i> . It will be read in automatically as ant variable ${password_encrypted}.
	The <i>decrypted</i> password will be saved to key "<i>password</i>" in another property file (<i>target.property.path</i>), which should not be set into version control. You may need to create it new.
	You may use the ant tool as is setting the variables in <i>.build.properties</i> or integrate it in your pom.xml build process (see below).
	<source>
	<![CDATA[
	<project basedir="." default="build" name="build">
	<property environment="env"/>
	<property file=".build.properties"/>
	<!-- reading from the file properties: password_encrypted, password -->
	<property file="${source.property.path}"/>
	<property name="meta.pw" value="${env.meta.pw}"/>

	<target name="testjava">
	<echo message="executing java -version"/>
	<exec executable="cmd" dir="" osfamily="windows" >
	<arg value="/c"/>
	<arg value="java -version"/>
	</exec>
	</target>

	<target name="decrypt">
	<echo message="executing java -jar target/${jarname}.jar string dec ${meta.pw} ${password_encrypted}."/>
	<exec executable="cmd" dir="${build.path}/../" osfamily="windows" resultproperty="success" outputproperty="decoded.pw">
	<arg value="/c"/>
	<arg value="java -jar target/${jarname}.jar string dec ${meta.pw} ${password_encrypted}"/>
	</exec>
	</target>

	<target name="update">
	<echo message="updating password in properties file: ${target.property.path}."/>
	<propertyfile file="${target.property.path}" >
	<entry key="password" value="${decoded.pw}"/>
	</propertyfile>
	</target>

	<target name="encrypt">
	<echo message="executing java -jar target/${jarname}.jar string enc ${meta.pw} ${password}"/>
	<exec executable="cmd" dir="${build.path}/../" osfamily="windows" resultproperty="success" outputproperty="encoded.pw">
	<arg value="/c"/>
	<arg value="java -jar target/${jarname}.jar string enc ${meta.pw} ${password}"/>
	</exec>
	</target>

	<target name="init-update">
	<echo message="updating password_encrypted in properties file: ${target.property.path}."/>
	<propertyfile file="${target.property.path}" >
	<entry key="password_encrypted" value="${encoded.pw}"/>
	</propertyfile>
	</target>

	<target name="clean">
	<echo message="cleaning up key password in propert file: ${target.property.path}."/>
	<propertyfile file="${target.property.path}" >
	<entry key="password" value=""/>
	</propertyfile>
	</target>

	<!-- target name="run">
	<echo message="test output java -jar target/${jarname}.jar string dec ${meta.pw} ${password_encrypted}."/>
	<java jar="./../target/${jarname}.jar" fork="true">
	<arg value="string"/>
	<arg value="dec"/>
	<arg value="${meta_password}"/>
	<arg value="${password_encrypted}"/>
	</java>
	</target-->

	<!-- decrypt to password -->
	<target name="build" depends="testjava, decrypt, update">
	</target>

	<!-- encrypt to password_encrypted -->
	<target name="init" depends="testjava, encrypt, init-update">
	</target>

	</project>
	]]>
	</source>
	</p>
	</subsection>
	<subsection name="Integration ANT Task into Maven Life cycle">
	<p>Integrate the ant tool, check the file name and run maven command below after setting your configuration or filter files in <i>source.property.path</i> and <i>target.property.path</i>.
	You may add another clean-up in a later life cycle phase, e.g. post-integration-test.
	You may also simplify the process by cleaning always and using the same source and target property file.
	<source>
	<![CDATA[
	<plugin>
	<artifactId>maven-antrun-plugin</artifactId>
	<version>3.0.0</version>
	<executions>
	<execution>
	<id>build</id>
	<phase>process-sources</phase>
	<configuration>
	<skip>${skip.pw.gen}</skip>
	<target>
	<ant antfile="${basedir}/build/build-pw.xml" target="build">
	<property name="build.path" value="${basedir}/build" />
	<property name="meta.pw" value="${meta.pw}" /><!-- provided by env variable -->
	<property name="jarname" value="crypto-tool" /><!-- by default ${project.build.finalName} -->
	<!-- contains encrypted password, saved in vcs: -->
	<property name="source.property.path" value="${basedir}/src/main/filters/${env}-app.properties" />
	<!-- should NOT be saved in vcs: -->
	<property name="target.property.path" value="${basedir}/src/main/filters/${env}-pw.properties" />
	</ant>
	</target>
	</configuration>
	<goals>
	<goal>run</goal>
	</goals>
	</execution>
	<execution>
	<id>clean</id>
	<phase>clean</phase>
	<configuration>
	<skip>${skip.pw.gen}</skip>
	<target>
	<ant antfile="${basedir}/build/build-pw.xml" target="clean">
	<property name="build.path" value="${basedir}/build" />
	<property name="target.property.path" value="${basedir}/src/main/filters/filter-${env}-pw.properties" />
	</ant>
	</target>
	</configuration>
	<goals>
	<goal>run</goal>
	</goals>
	</execution>
	</executions>
	</plugin>
	]]>
	</source>
	You may add another execution definiton with id and target "init" and probably another skip property to initially or regularily update the encoded password.
	</p>
	</subsection>
	<subsection name="Maven Command line examples">
	<p>Save the decrypted password for the build
	<source>
	<![CDATA[
	mvn clean test -Dmeta.pw=<securepwd>
	]]>
	</source>
	</p>
	<p>Keep the unencrypted password in source property files to use it during development or later (you may add a profile).
	<source>
	<![CDATA[
	mvn clean test install -Dskip.pw.gen=true
	]]>
	</source>
	</p>
	<p>Clean up finally.
	<source>
	<![CDATA[
	mvn clean
	]]>
	</source>
	</p>
	<p>This example could be extended or adapted, eg. by using multiple passwords, or encrypting an entire file.
	Have fun!
	</p>

	</subsection>
	</section>

	</body>

	</document>