Fulcrum YAAFI Crypto Library – Fulcrum Crypto Library Examples

Short Examples

Command line Usage

Encrypt with default PCM the string "mysecretgeheim" and meta password "changeit", outputs encrypted string to stdout.

                
 java -classpath target/classes org.apache.fulcrum.jce.crypto.cli.CLI2 string enc changeit mysecretgeheim

                
 java -jar target/fulcrum-yaafi-crypto-<version>.jar string enc:GCM changeit mysecretgeheim

This prints out the encrypted "mysecretgeheim".

                
 java -jar target/fulcrum-yaafi-crypto-<version>.jar string dec:GCM changeit 88f8ecc93cc921672e13862d75f90c55a4cc2d823c36e6ac3da0225e397770f45d3944f6be859fe25d053a8442313a5a2581e7edf081030e

This decrypts the result to stdout and prints information (supported type, matched type ..) to system.err.

CLI Usage Help:

                
 java -jar target/fulcrum-yaafi-crypto-<version>.jar help

Information about supported cipher libs:

                
 java -jar target/fulcrum-yaafi-crypto-<version>.jar info

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):

 
                
mvn integration-test -Dtest.password="xyz" -Dmeta.pw="abc"

Code Usage


    // 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) {
        ...
    }

Building a Project

Prepare the crypto-tool with Maven Assembly

First we build our crypto tool as executable jar in phase initialize (i.e. very early, to use it later) and name it crypto-tool using the assembly description saved in the file build/assembly.xml described below. Add this into your project pom.xml file.

                
<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>

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!

                
<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>

After executing the following command the crypto tool 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.

            
 mvn initialize

Integrate with Ant Tool - Extended

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.

First we encrypt 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.

              
 java -jar target/crypto-tool.jar string enc <master.pw> <unencrypted.password>

Save the encrypted password as value with key password_encrypted 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 decrypting process (see below paragraph).

Use the following ant build script (windows only) and save it into build/build-pw.xml. This is the ant build file we use to decrypt 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 "meta.pw". The already encrypted password is expected to be set in a source property file source.property.path (i.e. configuration file of your project) as value in key password_encrypted . It will be read in automatically as ant variable ${password_encrypted}. The decrypted password will be saved to key "password" in another property file (target.property.path), 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 .build.properties or integrate it in your pom.xml build process (see below).

     
<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>

Integration ANT Task into Maven Life cycle

Integrate the ant tool, check the file name and run maven command below after setting your configuration or filter files in source.property.path and target.property.path. 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.

            
<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>

You may add another execution definiton with id and target "init" and probably another skip property to initially or regularily update the encoded password.

Maven Command line examples

Save the decrypted password for the build

                
mvn clean test -Dmeta.pw=<securepwd>

Keep the unencrypted password in source property files to use it during development or later (you may add a profile).

                
mvn clean test install -Dskip.pw.gen=true

Clean up finally.

                
mvn clean

This example could be extended or adapted, eg. by using multiple passwords, or encrypting an entire file. Have fun!