After you have the Tracer Agent installed, run the integration tests to get a good coverage of all the crypto used by the application.
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 Trace like this:
java \ -Dcryptosense.agent.<PARAM1>=<VALUE1> \ -Dcryptosense.agent.<PARAM2>=<VALUE2> \ -javaagent:agent-VERSION.jar \ -jar <application.jar>
-D parameters are:
cryptosense.agent.out: directory the trace should be written into (default is
cryptosense.agent.compress: gzip-compress output JSON files on-the-fly (default is
true). Note that traces can be uploaded to the analyzer in compressed or uncompressed form.
cryptosense.agent.unlimitedTraceSize: remove trace size limit (default is
false). Traces are limited to 4GB uncompressed by default.
Make sure the application under test has the right to create a file in this directory.
The following parameters are usually only useful for debugging:
cryptosense.agent.trace: whether the report should include stack traces for each call (default is
true). 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 various
update()functions (like MessageDigest.update) should be discarded (default is
false). Setting to
truesignificantly 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 is
false). 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 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:
bin/setenv.sh should be created or edited to contain:
CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/agent-VERSION.jar -Dcryptosense.agent.<PARAM>=<VALUE>"
For JBoss it is necessary to whitelist the cryptosense package in
You can then add:
JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/agent-VERSION.jar -Dcryptosense.agent.<PARAM>=<VALUE>"
startWebLogic.sh should be edited to contain (before Java is called):
export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/path/to/agent-VERSION.jar -Dcryptosense.agent.<PARAM>=<VALUE>"
Our Tracer agent works with several other frameworks including WebSphere and Firefly. Contact us if you need help.