Support – Java HOWTO

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.

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.

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.

Try a Free 14-day Trial

Cryptosense Analyzer audits your applications and infrastructure to find vulnerabilities and understand your crypto landscape. Use it to optimise bug-fix resources and demonstrate compliance.