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

Trace streaming↑

By default, the Java Tracer saves a trace file to be uploaded to AQtive Guard for analysis. Alternatively, the tracer can stream the trace directly to AWS S3 while running.

Caution

Java Tracer streaming is designed for specific deployment pipelines. Before implementing trace streaming, discuss your configuration with your AQtive Guard contact. Visit our support portal if you have questions or need help.

Important

Java Tracer streaming requires AQtive Guard server version 24.09.1 or above. For version 24.09.1 you will need to enable it by setting ENABLE_STREAM_UPLOAD='true' in your configuration file. In later versions, streaming is enabled by default.

Use↑

Refer to these steps and the following example to implement Java Tracer streaming.

  1. Make your AQtive Guard API key available to the JVM in the AQG_API_KEY environment variable. Refer to Retrieve the API key.
  2. Make sure that the AQtive Guard server is configured to enable streaming.
  3. Put the tracer in streaming mode using -Dcryptosense.agent.logger=streaming.
  4. Add the required and desired optional trace streaming configuration parameters.
  5. Run the application with the tracer attached as usual.

Example↑

The following example will run an application with the streaming tracer attached and stream the trace to the Sandbox SaaS instance in project 17 with slot name “foo.”

AQG_API_KEY=your-api-key \
    java \
    -Dcryptosense.agent.logger=streaming \
    -Dcryptosense.agent.streamingApiBaseUrl=https://aqtiveguard.sandboxaq.com \
    -Dcryptosense.agent.streamingCaFile=/path/to/cacert.pem \
    -Dcryptosense.agent.streamingProjectId=17 \
    -Dcryptosense.agent.streamingSlotName=foo \
    -javaagent:/path/to/cs-java-tracer.jar \
    -jar /path/to/application.jar

Trace streaming parameters↑

  • cryptosense.agent.logger: Determines whether to save the trace to a file or stream it directly to an AQtive Guard instance. Allowed values are file or streaming. Default is file. If file is selected (either explicitly or by default), then the remaining parameters with streaming in their names will be ignored.
  • cryptosense.agent.streamingApiBaseUrl: URL for the server (e.g. https://aqtiveguard.internal:8443). For SaaS, use https://aqtiveguard.sandboxaq.com. If this parameter is provided, the other required streaming parameters must also be provided.
  • cryptosense.agent.streamingCaFile (optional): Path to a CA certificate bundle (concatenated PEM elements) to validate the server certificate(s). This includes the object storage service, if it is validated by a different CA.
  • cryptosense.agent.streamingProjectId: Numeric ID of the project to use for looking up and creating slots. (Note: This is the project number from the Web UI, not the Base64 GraphQL opaque ID.)
  • cryptosense.agent.streamingSlotName: Name of the slot where the trace will be created. If a slot with the given name doesn’t exist, it will be created.
  • cryptosense.agent.streamingCallMode (optional): Determines how the application handles full streaming buffers. The acceptable values are:
    • blocking (default): When buffers are full, the application blocks execution until space is available. The application exits if the buffers can’t be emptied (e.g., due to server unavailability).
    • nonblocking: Calls are dropped when buffers are full. Streaming will stop if the buffers can’t be emptied (e.g., due to server unavailability).
  • cryptosense.agent.streamingBufferSize (optional): Advanced. Size of buffers in the internal pool in MB. The default is 5, i.e. 5MB. Allowed values are 5 to 2047.
  • cryptosense.agent.streamingMaxBufferCount (optional): Advanced. Maximum number of buffers in the internal pool. The default value is 8 and the minimum is 2.

Proxy usage↑

To use a proxy for trace streaming, add the following JVM properties:

  • https.proxyHost: The proxy server’s hostname.
  • https.proxyPort: The proxy server’s port number. The default port is 80.

Example↑

AQG_API_KEY=your-api-key \
    java \
    -Dhttps.proxyHost=proxy.example.com \
    -Dhttps.proxyPort=8080 \
    -Dcryptosense.agent.logger=streaming \
    -Dcryptosense.agent.streamingApiBaseUrl=https://aqtiveguard.sandboxaq.com \
    -Dcryptosense.agent.streamingProjectId=17 \
    -Dcryptosense.agent.streamingSlotName=foo \
    -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.

Missing information in stack traces↑

The Java Tracer pulls line number and source file information from the debugging data generated during compilation. If the debug information is missing, your analysis won’t include line numbers or file names.

When compiling your Java source code, make sure to use an option that generates debugging data:

  • Line number and source file information is generated by default.
  • The -g option generates all debugging information, including local variables.
  • Don’t use -g:none, as this stops the required debug data from being generated.

Refer to the javac command documentation for more details.

Caution

Some third-party JAR files may not include any debugging information.

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 % AQG_API_KEY=XXXXX java -Dcryptosense.agent.logger=streaming -Dcryptosense.agent.streamingApiBaseUrl=https://localhost:8443 -Dcryptosense.agent.streamingProjectId=1 -Dcryptosense.agent.streamingSlotName=test1 -Dcryptosense.agent.streamingCaFile=cert.pem -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 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 Java Tracer also covers methods from the following classes from vendor-specific APIs: