Skip to content

Java Tracer referenceπŸ”—

ConfigurationπŸ”—

You can configure the 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 with Build SystemsπŸ”—

GradleπŸ”—

Gradle 5.6.3 or higher is required.

Gradle can pass arguments to the JVM that runs the test suite. To trace your tests, add the following to your build.gradle file:

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

If you use subprojects, you’ll need to apply this configuration to each one that you want to get traces for.

To configure this for all subprojects, enclose the previous snippet in a subprojects { ... } block. You can find more details about the test task in the Gradle documentation.

You can then get a trace by running the following command:

gradle cleanTest test -Pwith-cryptosense

You can also use our Gradle plugin.

MavenπŸ”—

Maven 3.3.9 or higher is required.

Maven integration is provided by our Maven plugin.

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

To rename the JAR file to new-name.jar, extract the META-INF/MANIFEST.MF file from the JAR, and edit it by changing the boot class path line to:

Boot-Class-Path: new-name.jar

Then, update the JAR file and replace the old META-INF/MANIFEST.MF file with the modified version.

Supported operationsπŸ”—

The Java Tracer covers methods from the following classes:

  • 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
  • javax.net.ssl.SSLServerSocket
  • com.amazonaws.services.kms.AWSKMSClient
  • com.azure.security.keyvault.keys.cryptography.CryptographyClient