To run the Java bytecode translator, just type:
java -jar vldy-tech-translator.jar [options] [class names]
It is also possible to put options and class names inside a text file and pass it to the translator using the @ character:
java -jar vldy-tech-translator.jar @optionfile.txt
The input classes can be selected by specifying either a base directory or a jar file. The output classes are written to either an output directory or a jar file. However, the combination of an input directory and an output jar file is not supported, please use the jar tool to package the classes after transformation instead. By default, all the classes found under the given directory or in the given jar file are processed but it is possible to restrict the transformation by adding the names of the classes to be transformed at the end of the command line, after all other options. The files or resources that are not class files and the class files that are not transformed are copied unchanged to the output directory or jar file.
The translator must also be able to find the bytecode of all
the classes used or referenced by the input classes. The class paths
used by the translator to lookup classes is specified using option
-a (--applicationpath), -l (--librarypath), and -s (--systempath).
They are not the class pathes used by the Java
virtual machine to run the translator itself. By default, the
application and library paths are empty and the system path is
initialized using the sun.boot.class.path
and java.ext.dirs system properties.
The translator accepts the following options:
- -i or --input
directory_nameorjar_file_name -
Specifies the directory or jar file containing the classes to be transformed.
- -o or --output
directory_nameorjar_file_name -
Specifies the directory or jar file where the transformed classes should be stored. The argument can be a jar file only if the input itself is a jar file. The translator cannot be used to create jars.
- -1
-
Specifies that the translator must target version 1 of the token instruction set.
- -2
-
Specifies that the translator must target version 2 of the token instruction set.
- -a or --applicationpath
class_path -
Specifies the path to the application classes. The input jar or directory is automatically prepended to the application path.
- -l or --librarypath
class_path -
Specifies the path to the library classes referenced by the application classes.
- -s or --systempath
class_path -
Specifies the path to the Java runtime classes referenced by the application or library classes. This makes it possible to protect an application that relies on a runtime different from the one used to run the translator itself (Java 5 or later). If this option is not specified, the system path defaults to the path defined by the
sun.boot.class.pathsystem property and the jar files found in the directories defined by thejava.ext.dirssystem property. - -c or --classpath
class_path[deprecated] -
Specifies the path the translator should use to lookup classes referenced by the input classes. This option is deprecated and is now an alias for option --librarypath, please specify the application, library, and system paths instead.
- -m or --markers
file_name -
Specifies the name of a file containing a list of fields and methods to protect (or not to protect). This option can be used several times if there are several markers files.
- -x or --disassemble
directory_name -
Instructs the translator to save a disassembled copy of the class files it processes before and after transformation. These files are produced using ASM's TraceVisitor.
- -h or --help
-
Lists the translator options with a short description.
- -v or --verbose
-
Instructs the translator to output progress messages.
- -e or --warningaserror
-
Instructs the translator to fail when a warning is produced. The default behavior is to output the warning to the standard error.
- -r or --rseed
integer_value -
Specifies the seed value for the random number generator used to choose some of the tags in the instructions executed by the token. This option makes reproducible builds possible.
Note
Some tags are not chosen at random because they are of a global nature and the same tags must be used when an application is made of several protected jars processed separately. They are the tags used when storing secured fields or performing the handshake for a secured method call. These tags are derived from the field or the method signature using the secret protection key.
- -k or --key hexadecimal_string
-
Specifies the key used to cipher instructions. The translator uses the Triple DES algorithm to cipher instructions so the key should be a 48 character long hexadecimal string (192 bits). The default value of the key is
000000000000000000000000000008020000000000000000.Note
The virtual coprocessor uses the default key to decipher instructions. If you change the translator key, the transformed application will not run with it.
- --bcSerialization
-
Generate code that accepts clear values for secured fields in serialization streams making it possible to reconstruct objects that were serialized before the application was transformed by the translator. By default, the generated
readObjectmethod does not initialize fields for which no ciphered value is available in the serialization stream.
For example, to protect the classes located in the directory
./buid/classes using the fields and methods
listed in the file ./secured.txt while setting
the random seed, the following command can be used:
java -jar vldy-tech-translator.jar -i ./build/classes -o ./build/classes.secured
-s $(JAVA_HOME)/jre/lib/rt.jar -m ./secured.txt -r 20061118
The bytecode translator can also be integrated to an Ant build script (version 1.6
and higher) using the vldy custom task provided in
vldy-tech-ant.jar.
To be able to use this task, it must be declared by
inserting the following definition in your
build.xml file:
<taskdef resource="tasks.properties" classpath="${vldy.home}/vldy-tech-ant.jar"/>where the property ${vldy.home} is set to
point to the directory where Validy SoftNaos has been installed.
The task definition can be placed at the top level or inside a
target.
The path to the translator jar
vldy-tech-translator.jar must be added to the
class path of the vldy task. To simplify the build script, a path
to this jar can be defined:
<path id="validy.translator.path">
<pathelement location="${vldy.home}/vldy-tech-translator.jar" />
</path>The following tables list the supported parameters.
Table 4.1. Attributes for the vldy task
The vldy task is an extension of the standard java task and as such supports many of its parameters. The exceptions are classname and jar which are hard coded to run the translator.
Table 4.2. Some attributes inherited from the java task
| Attribute | Description |
|---|---|
| classpathref | The class path to use, given as reference to a PATH
defined elsewhere. This path should contain the
vldy-tech-translator.jar
file.
|
| fork | If enabled, triggers the execution in another VM (disabled by default). |
| maxmemory | Max amount of memory to allocate to the forked VM (ignored if fork is disabled) |
| failonerror | Stop the build process if the command exits with a return code other than 0. Default is "false". |
| resultproperty | The name of a property in which the return code of the command should be stored. Only of interest if failonerror=false and if fork=true. |
For the complete list of attributes, please refer to the documentation of the java Ant task.
The following parameters can be specified as nested elements:
- applicationpath
-
Use a nested <applicationpath> element to specify the path to the application classes. It is a path like structure.
- librarypath
-
Use a nested <librarypath> element to specify the path to the library classes used or referenced by the application classes. It is a path like structure.
- systempath
-
Use a nested <systempath> element to specify the path to the Java runtime classes used or referenced by the application or library classes. It is a path like structure.
- pclasspath
-
Use a nested <pclasspath> element to specify the path used by the translator to lookup classes used or referenced by the input classes (see option classpath). This parameter is deprecated, please use <applicationpath>, <librarypath>, and <systempath> instead.
- indirset
-
Use a nested <indirset> element as an alternative to the indir attribute that can be used to apply a filter to select the classes to transform. It is a fileset like structure.
- markers
-
Use a nested <markers> element as an alternative to the markers attribute when there are several markers files. It is a patternset like structure.
The following nested elements are inherited from the standard java task:
- jvmarg
-
Use nested <jvmarg> elements to specify arguments for the forked VM.
- sysproperty
-
Use nested <sysproperty> elements to specify system properties required by the class. These properties will be made available to the VM during the execution of the class (either ANT's VM or the forked VM). The attributes for this element are the same as for environment variables.
The translator run shown at the end of section can be replicated as an Ant task that forks the translator as follows:
<vldy indir="./build/classes" outdir="./build/classes.secured"
markers="./secured.txt" classpathref="validy.translator.path"
fork="true" failonerror="true">
<systempath>
<pathelement location="${java.home}/jre/lib/rt.jar" />
</systempath>
</vldy>Before running the translator, the vldy task checks its dependencies. If one of the expected output file is missing or is older than any of the input files, the translator is run. All the files listed below are considered as input files to the translator:
-
the input jar file, any class file found under the input directory, or any class file listed in the <indirset> nested element,
-
the jar files listed in the application path and any class file found under a directory listed in the application path,
-
the files containing protection markers.
The call graph builder tool is stored in the same jar file as the translator. To run it, just type:
java -classpath vldy-tech-translator.jar com.validy.technology.hekla.SecureCallGraph [options]
It is also possible to put options inside a text file and pass it to the builder tool using the @ character:
java -classpath vldy-tech-translator.jar com.validy.technology.hekla.SecureCallGraph @optionfile.txt
The builder tool does not take a jar or directory as input. All the classes found in the application class path are considered to build the graphs starting from the entry points provided as input. It is important that the graph builder has access to the definition of secured fields to check that a call graph is secure (see option -m).
The call graph builder tool accepts the following options:
- -e or --entrypoints
entry_points_file -
Specifies the name of a file containing a list of entry point methods. Each method will be the root of one call graph. This file must have the same format as a markers file (see Section 2.5, “Markers”).
- -o or --output
markers_file -
Specifies the name of the file where the methods selected by the tool will be listed. This file can then be used as an input markers file for the translator using option -m. If the entry point for a call graph is given on a line starting with a + or a - character, the methods from the graph will be listed starting with the same character. If this option is omitted, the methods are listed on the standard output.
- -d or --depth
max_depth -
Specifies the maximum depth of the call graphs that will be built. The maximum depth may not be reached because the computed graphs are constrained to remain within application classes only. The maximum depth is set to 5 by default.
- -a or --applicationpath
class_path -
Specifies the path to the application classes.
- -l or --librarypath
class_path -
Specifies the path to the library classes referenced by the application classes.
- -s or --systempath
class_path -
Specifies the path to the Java runtime classes referenced by the application or library classes. This makes it possible to protect an application that relies on a runtime different from the one used to run the translator itself (Java 5 or later). If this option is not specified, the system path defaults to the path defined by the
sun.boot.class.pathsystem property and the jar files found in the directories defined by thejava.ext.dirssystem property. - -m or --markers
file_name -
Specifies the name of a file containing a list of fields and methods to protect (or not to protect). This option can be used several times if there are several markers files.
- -f or --force
-
Specifies that the methods of all the computed call graphs should be included in the output. By default, the methods of call graphs that are not linked to original secure code are not listed.
- -h or --help
-
Lists the builder options with a short description.
- -v or --verbose
-
Instructs the builder to output progress messages.
The call graph builder tool can also be integrated to an
Ant build script
(version 1.6 and higher) using the vldygraph custom
task provided in vldy-tech-ant.jar.
The following table lists the supported parameters.
Table 4.3. Attributes for the vldygraph task
| Attribute | Description |
|---|---|
| entrypoints | The file that contains the list of call graph entry points. |
| output | The file in which to list selected methods. |
| maxdepth | The maximum depth of the call graph that will be computed. |
| markers | The jar file in which to place the transformed class files. Only one of outjar and destdir can be specified. Must be used with injar. |
| force | If true, the methods in the call
graphs that are not linked to original secure code are
included in the output. If false they
are ignored.
|
| verbose | If true, the builder tool will
output progress messages.
|
The vldygraph task is an extension of the standard java task and as such supports many of its parameters. The exceptions are classname and jar which are hard coded to run the call graph builder tool. See Table 4.2, “Some attributes inherited from the java task” for a list of useful attributes.
The following parameters can be specified as nested elements:
- applicationpath
-
Use a nested <applicationpath> element to specify the path to the application classes. It is a path like structure.
- librarypath
-
Use a nested <librarypath> element to specify the path to the library classes used or referenced by the application classes. It is a path like structure.
- systempath
-
Use a nested <systempath> element to specify the path to the Java runtime classes used or referenced by the application or library classes. It is a path like structure.
- markers
-
Use a nested <markers> element as an alternative to the markers attribute when there are several markers files. It is a patternset like structure.
Other nested elements are inherited from the standard java task, see Section 3.1.2.3, “Parameters specified as Nested Elements” for more information.