Skip to content

Java Tracer Manual

After you have downloaded the Tracer Agent, you need to run your application with the trace attached following the instructions below. Only cryptographic operations that appear in the trace will be analysed, so to get good coverage of all the crypto use, you'll likely want to invoke an existing test suite.

Prerequisites

  • Java 8 or higher.

Usage

To use the Tracer, you need to add some extra parameters to the invocation of your Java application.

If you invoke your application at the command line, use the Trace like this:

java \
    -Dcryptosense.agent.<PARAM1>=<VALUE1> \
    -Dcryptosense.agent.<PARAM2>=<VALUE2> \
    -javaagent:agent-VERSION.jar \
    -jar <application.jar>

The main -D parameters are:

  • cryptosense.agent.out : directory the trace should be written into (default is cs-tracer )

Make sure the application under test has the right to create a file in this directory.

  • cryptosense.agent.compress : gzip-compress output JSON files on-the-fly (default is true ). Note that traces can be uploaded to the analyzer in compressed or uncompressed form.
  • cryptosense.agent.unlimitedTraceSize : remove trace size limit (default is false ). Traces are limited to 4GB uncompressed by default. This parameter is deprecated: use cryptosense.agent.maxTraceSize instead.
  • cryptosense.agent.maxTraceSize : set a maxiumum uncompressed trace size. The value specified should be a whole number of MB. The default is 4096, i.e. 4GB. Setting a value of 0 means there is no limit.
  • cryptosense.agent.prefix : optional custom file name prefix for traces (default is cs-trace ). The file name will consist of this prefix followed by an underscore, followed by a timestamp, with extension .cst or .cst.gz depending on whether compression is turned on. For example, if the prefix is set to testprefix , the file name would look like testprefix_2018-12-13-08-42-33-428_11435.cst (depending on the date and time the trace was run).

The following parameters are usually only useful for debugging:

  • cryptosense.agent.trace : whether the report should include stack traces for each call (default is true ). Setting to false significantly reduces the size of the resulting trace files, but the report will lack important information.
  • cryptosense.agent.ignoreUpdate : whether the calls to various update() functions (like MessageDigest.update) should be discarded (default is false ). Setting to true significantly reduces the size of the resulting trace files, but the report will lack important information.
  • cryptosense.agent.excludeBuiltins : whether the calls to certain internal crypto functions in the JRE are included in the trace or not (default is false ). The excluded calls include hash function calls to verify JAR files on startup, and internal hash calls for certain internal PBKDFs that use a large number of iterations and can quickly fill up a trace. Note that this doesn't affect the results, since the calls are accounted for by Analyzer.

Using the Tracer with Build Systems

Gradle

Gradle can pass arguments to the JVM that runs the test suite. You can add the following line to your builde.gradle to trace your tests:

if (project.hasProperty('with-cryptosense')) {
    test.jvmArgs = ['-javaagent:/path/to/agent.jar']
}

If you use subprojects, you will need to apply this configuration to each of those you want to get traces.  A simple way of achieving this for all subprojects is to enclose the above snippet in a subprojects { ... } block.  The Gradle documentation has more information about the test task.

Then, you can get a trace by running the following command:

gradle cleanTest test -Pwith-cryptosense

See more detail here.

Maven

Maven integration is provided by our Maven plugin. Further details and installation instructions.

Using the Tracer in Application Frameworks

Java applications are often launched from within application servers. In this case, you will need to add the necessary parameters to a config file:

Tomcat

The file bin/setenv.sh should be created or edited to contain:

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/agent-VERSION.jar -Dcryptosense.agent.<PARAM>=<VALUE>"

JBoss

For JBoss it is necessary to whitelist the cryptosense package in standalone.conf :

JBOSS_MODULES_SYSTEM_PKGS="${JBOSS_MODULES_SYSTEM_PKGS:+$JBOSS_MODULES_SYSTEM_PKGS,}cryptosense"

You can then add:

JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/agent-VERSION.jar -Dcryptosense.agent.<PARAM>=<VALUE>"

WebLogic

The file startWebLogic.sh should be edited to contain (before Java is called):

export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/path/to/agent-VERSION.jar -Dcryptosense.agent.<PARAM>=<VALUE>"

Other frameworks

Our Tracer agent works with several other frameworks including WebSphere and Firefly. Contact us if you need help.