Skip to content

AQG Java Tracer reference↑

Configuration↑

You can configure the AQG Java Tracer with JVM properties using the -D parameter in the command line.

For instance, to specify the directory for trace writing, use the cryptosense.agent.out parameter as follows:

java \
    -Dcryptosense.agent.out=/path/to/trace-directory \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

With Java 9 and later, you can also pass these properties via the JDK_JAVA_OPTIONS environment variable. For example:

JDK_JAVA_OPTIONS='-javaagent:/path/to/cs-java-tracer.jar …' \
    java -jar /path/to/application.jar

This is more flexible as it allows you to set the properties without modifying your application startup script. However, it is not supported by all JREs.

If you’re not using the java command to launch your application directly, you can usually set those properties where you added the javaagent:/path/to/cs-java-tracer.jar parameter. Refer to the examples below.

Parameters↑

The supported properties are:

  • cryptosense.agent.out: path to the directory where traces are written. (default is cs-tracer). Make sure the application under test has write permissions in this directory.
  • cryptosense.agent.compress: on-the-fly gzip-compression of outputted JSON files (default is true). Note that you can upload either compressed or uncompressed traces to the analyzer.
  • cryptosense.agent.unlimitedTraceSize: Deprecated. Use cryptosense.agent.maxTraceSize.
  • cryptosense.agent.maxTraceSize: set a maximum uncompressed trace size in MB. The default is 4096, i.e. 4GB. Setting a value of 0 means there’s 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 and timestamp, and have a .cst or .cst.gz extension, depending on the compression. For example, if the prefix is testprefix, the file name would be testprefix_2018-12-13-08-42-33-428_11435.cst (depending on the trace time).
  • cryptosense.agent.trace: determines whether to include stack traces for each call in the report (default is true ). Setting this to false significantly reduces the trace file size, but the report will lack important information.
  • cryptosense.agent.ignoreUpdate: determines whether to discard the calls to various update() functions (such as MessageDigest.update). The default is false. Setting this to true significantly reduces the trace file size, but the report will lack important information.
  • cryptosense.agent.excludeBuiltins: determines whether to include the calls to certain internal crypto functions in the JRE in the trace (default is false ). The excluded calls consist of hash function calls to verify JAR files upon startup, and internal hash calls for certain internal PBKDFs with extensive iterations that might quickly fill up a trace. Note that this doesn’t affect the results since the calls are accounted for by the Analyzer.
  • cryptosense.agent.tags: comma-separated tags to include in the trace header. To include a space in the tag, uses single quotes like cryptosense.agent.tags='spaced tag 1','spaced tag 2'. The tags are written in the trace header as a list of strings (default is an empty list).

Here are some examples with different parameters:

Limiting the trace size:↑

java \
    -Dcryptosense.agent.out=/path/to/trace-directory \
    -Dcryptosense.agent.maxTraceSize=200 \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

Adding a prefix to the trace name:↑

java \
    -Dcryptosense.agent.out=/path/to/trace-directory \
    -Dcryptosense.agent.prefix=prefix \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

Excluding stack traces from calls:↑

java \
    -Dcryptosense.agent.out=/path/to/trace-directory \
    -Dcryptosense.agent.trace=false \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

Using the Tracer in Application Frameworks↑

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

Tomcat↑

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

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

JBoss↑

For JBoss, you need 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/cs-java-tracer.jar -Dcryptosense.agent.<PARAM>=<VALUE>"

WebLogic↑

Before calling Java, edit the startWebLogic.sh file to include:

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

Other frameworks↑

Our AQG Java Tracer works with several other frameworks, including WebSphere and Firefly. Visit our support portal if you have questions or need help.

Renaming the tracer JAR file↑

Renaming the JAR file is not recommended because the boot class path in the JAR manifest must match the file name exactly.

If you do rename the JAR file, you need to modify the manifest accordingly. Otherwise, you’ll encounter java.lang.NoClassDefFoundError during runtime. While your application may not crash, the tracer won’t function correctly.

You can rename the JAR file in one of two ways: adding a parameter to the JVM invocation or extracting and editing the JAR file manifest.

Add a parameter↑

You can rename the JAR file by adding the following parameter to the JVM invocation:

-Xbootclasspath/a:path/to/cs-java-tracer-2.2.4.jar

Important

This needs to be added in addition to -javaagent:path/to/cs-java-tracer-2.2.4.jar in JDK_JAVA_OPTIONS.

An example command when run directly on an app is shown below:

user@cs-java-tracer % java -javaagent:cs-java-tracer-2.2.4.jar -Xbootclasspath/a:cs-java-tracer-2.2.4.jar Demo

With this option, you don’t need to edit the manifest file.

Extract and edit the manifest file↑

You can rename the JAR file by extracting the META-INF/MANIFEST.MF file from the JAR and changing the boot class path line to:

Boot-Class-Path: new-name.jar

The command above renames the JAR file to new-name.jar.

You’ll then need to replace the old META-INF/MANIFEST.MF file with the modified version.

Supported operations↑

The AQG Java Tracer covers methods from the following classes for any cryptographic providers conforming to the Java Cryptography Architecture (JCA), for example, Bouncy Castle Java, conscrypt and other provider implementations. This coverage is at the JCA/JCE level, but there are some algorithm implementation specific parameters, from for example Bouncy Castle, that we also capture.

  • java.security.KeyPairGenerator
  • java.security.KeyStore
  • java.security.MessageDigest
  • java.security.Signature
  • javax.crypto.Cipher
  • javax.crypto.KeyAgreement
  • javax.crypto.KeyGenerator
  • javax.crypto.Mac
  • javax.crypto.SecretKeyFactory

From the Java Generic Security Services (Java GSS-API) we cover the following class:

  • javax.net.ssl.SSLServerSocket

The AQG Java Tracer also covers methods from the following classes from vendor-specific APIs: