Java Tracer Manual
After you have downloaded the Tracer Agent, you need to run your application with the tracer attached following the instructions below. Only cryptographic operations that appear in the trace will be analysed, so to get good coverage of all the crypto use, you'll likely want to invoke an existing test suite.
Prerequisites
- Java 8 or higher.
Installation
The Cryptosense Java tracer is distributed as a Zip or tar archive. The easiest way to obtain it is by downloading it from the SaaS platform at analyzer.cryptosense.com. Navigate to any project, then to the Traces tab, and click the "Download Tracer Agent" button.
You will have a zip file cs-java-tracer-<VERSION>.zip
. When you unzip the package, you
will have a directory cs-java-tracer-<VERSION>
containing a Java jar file
cs-java-tracer.jar
, for example:
cs-java-tracer-1.8.2/
└── cs-java-tracer.jar
You may move the cs-java-tracer.jar
file to anywhere you want on your system. It does
not have to remain inside the cs-java-tracer-<VERSION>
directory.
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 Tracer like this:
java \
-Dcryptosense.agent.<PARAM1>=<VALUE1> \
-Dcryptosense.agent.<PARAM2>=<VALUE2> \
-javaagent:/path/to/cs-java-tracer.jar \
-jar <application.jar>
The main -D
parameters are:
cryptosense.agent.out
: directory the trace should be written into (default iscs-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 istrue
). Note that traces can be uploaded to the analyzer in compressed or uncompressed form.cryptosense.agent.unlimitedTraceSize
: remove trace size limit (default isfalse
). Traces are limited to 4GB uncompressed by default. This parameter is deprecated: usecryptosense.agent.maxTraceSize
instead.cryptosense.agent.maxTraceSize
: set a maximum uncompressed trace size. The value specified should be a whole number of MB. The default is 4096, i.e. 4GB. Setting a value of 0 means there is no limit.cryptosense.agent.prefix
: optional custom file name prefix for traces (default iscs-trace
). The file name will consist of this prefix followed by an underscore, followed by a timestamp, with extension.cst
or.cst.gz
depending on whether compression is turned on. For example, if the prefix is set totestprefix
, the file name would look liketestprefix_2018-12-13-08-42-33-428_11435.cst
(depending on the date and time the trace was run).
The following parameters are usually only useful for debugging:
cryptosense.agent.trace
: whether the report should include stack traces for each call (default istrue
). 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 variousupdate()
functions (like MessageDigest.update) should be discarded (default isfalse
). Setting totrue
significantly reduces the size of the resulting trace files, but the report will lack important information.cryptosense.agent.excludeBuiltins
: whether the calls to certain internal crypto functions in the JRE are included in the trace or not (default isfalse
). The excluded calls include hash function calls to verify JAR files on startup, and internal hash calls for certain internal PBKDFs that use a large number of iterations and can quickly fill up a trace. Note that this doesn't affect the results, since the calls are accounted for by Analyzer.
Using the Tracer with Build Systems
Gradle
Gradle can pass arguments to the JVM that runs the test suite. You can add the following
line to your build.gradle
to trace your tests:
if (project.hasProperty('with-cryptosense')) {
test.jvmArgs = ['-javaagent:/path/to/cs-java-tracer.jar']
}
If you use subprojects, you will need to apply this configuration to each of those you
want to get traces. A simple way of achieving this for all subprojects is to enclose the
above snippet in a subprojects { ... }
block. The Gradle documentation has more
information about the
test task.
Then, you can get a trace by running the following command:
gradle cleanTest test -Pwith-cryptosense
See more detail here.
Maven
Maven integration is provided by our Maven plugin. Further details and installation instructions.
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/cs-java-tracer.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/cs-java-tracer.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/cs-java-tracer.jar -Dcryptosense.agent.<PARAM>=<VALUE>"
Other frameworks
Our Java tracer works with several other frameworks including WebSphere and Firefly. Contact us if you need help.
Trace Streaming
The Java tracer supports streaming results directly to the Cryptosense Analyzer Platform instead of first creating a local file. Currently, this is only available for the SaaS version of CAP. In order to stream traces, the following options should be set :
cryptosense.agent.domain
: should be set toproxy.cryptosense.com
.cryptosense.agent.tls
: should be set totrue
.cryptosense.agent.port
: should be set to443
.cryptosense.agent.projectId
: should be set to the ID of the project to which the trace should be added. This ID is an integer and can be gathered from the URL of the projects root page (of the formathttps://analyzer.cryptosense.com/project/<project id>/dashboard
). The ID used for this option is not the same ID as the one returned by the GraphQL API.cryptosense.agent.apiKey
: should be set to the API key linked to a user that has sufficient privileges to write to the given project.
Renaming the tracer Jar file
It is not recommended to rename the Jar file. The reason is that the boot class path in the Jar manifest must match the file name exactly.
If you absolutely must rename the Jar file, you must also modify the manifest to match,
otherwise you will encounter java.lang.NoClassDefFoundError
while your application is
running. Your application may or may not crash, but the tracer will certainly not operate
correctly.
Suppose you want to change the name of the Jar file to new-name.jar
. You will need to
extract the file META-INF/MANIFEST.MF
from the Jar, and edit it, changing the boot class
path line to:
Boot-Class-Path: new-name.jar
You will then need to update the Jar file, replacing the old META-INF/MANIFEST.MF
with
the new modified version.