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.

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

• com.amazonaws.services.kms.AWSKMSClient
• com.azure.security.keyvault.keys.cryptography.CryptographyClient