Monday Nov 16, 2015

Strengthening Signatures part 2

The scheduled Critical Patch Update of Oracle Java SE on January 19 2016 is planned to disable X.509 certificates signed with MD5. Plans are also being developed to disable X.509 certificates signed with SHA-1 and further details will be announced in a future post.

Specifically, this change will treat certificate chains containing a certificate with an MD5-based signature to be invalid and blocked by default. This affects Java clients and servers using TLS (via the JSSE API), signed applets and Web Start applications, and any application using the PKIX implementation of the CertPath API to validate certificate chains.

This was previously covered in a post, Strengthening Signatures, and is similar to announcements from other platform providers like Microsoft, which deprecated MD5 in June 2014 and is focusing on SHA-1 efforts for 2016.

System Administrators wanting to test their systems can update their JAVA_HOME/lib/security/ file and add MD5 into jdk.certpath.disabledAlgorithms.

Change "jdk.certpath.disabledAlgorithms=MD2, RSA keySize < 1024" to "jdk.certpath.disabledAlgorithms=MD2, MD5, RSA keySize < 1024"

After this change, the MD5 algorithm will still be available for other non-certificate uses. For example applications that use MessageDigest.getInstance("MD5") for alternate reasons will continue to function.

For System Administrators that must re-enable the weaker MD5 algorithm

In cases where a system authenticates itself through MD5 signatures, system administrators are encouraged to generate newer certificates that use SHA-256 or higher.

Users are encouraged to accept the default security settings and not re-enable MD5 in X.509 certificates. However, if necessary, MD5 can be re-enabled in either of the following ways:

 Option A (preferred if weak MD5 is needed), by using a startup flag that will only impact specific applications.
  1. Create a file that copies the jdk.certpath.disabledAlgorithms line from JAVA_HOME/lib/security/
  2. Remove MD5 from that line
  3. In your startup command, add
  4. Plan your migration away from weak algorithms and undoing this change.
 Option B, editing a configuration file that will affect all applications used by a JRE:
  1. Open JAVA_HOME/lib/security/
  2. Remove MD5 from the line jdk.certpath.disabledAlgorithms
  3. Plan your migration away from weak algorithms and undoing this change.

SHA-1 plans

We are also working with industry groups on a plan to migrate away from certificates signed with SHA-1. The Certificate Authority Browser Forum previously set guidance to avoid issuing new SHA-1 certificates after January 2016. This guidance assists in our planning, as well as that of peer programs such as Microsoft, Mozilla, and Google


Wednesday Aug 05, 2015

Strengthening Signatures

Later this year, the Oracle JDK team plans to restricting the use of MD5 signatures within X.509 certificates used by SSL/TLS and code-signing. This will take place in the public versions of JDK 9 (early access) and JDK 8, as well as the commercially supported JDK 7.

The IETF has recommended a move away from MD5 since 2011.

Most Certificate Authorities followed this guidance by requiring stronger signatures (typically in the SHA family). Although the default JDK options switched away from MD5 in the past, additional time was necessary for organizations to phase out their use of MD5 and reissue certificates with stronger hash algorithms.

System Administrators that still actively use certificates with MD5 hashes should consider revoking and/or re-issuing those certificates with stronger signatures. Developers that have previously signed artifacts with MD5 signatures should consider re-signing and timestamping these artifacts.

This change will only affect MD5 usage in regards to certificates. This will not affect other uses, such as MD5 hashing of files to generate checksums or perform simple checks.

System Administrators can control algorithm availability by adjusting their JRE configuration. For example, some organizations may still rely on internal systems that require MD5. Users of these systems will likely see a message "constraints check failed: MD5withRSA" in their application logs.

This configuration change takes place within the jre/lib/security/ file. The specific property is jdk.certpath.disabledAlgorithms.

Thursday Dec 11, 2014

That's so SecureRandom

Random numbers are an important part of software systems, especially those that deal with security or encryption. The Java platform offers different types of randomness based on intent, and static typing can further guide that choice for library developers.

This post is intended to explain how the Oracle JDK provides random numbers, to guide their usage:

  • Developers building Java software, to use the right randomness in the right place.
  • Companies buying or running Java software to understand how to evaluate or control that software.
  • System Administrators tuning the security and performance of those systems, understanding why/where/how to make adjustments.

Randomness in the JDK

Java SE provides three mechanisms for generating random numbers based on their usage:

  1. A fast Random number designed for basic tasks where true randomness is not the main goal. This is useful for things like which shade of color to use, preventing overlap in force-directed layouts, or which picture to show from a list after evaluating demographic information.
  2. High-concurrency programs may also use ThreadLocalRandom if they value speed over true randomness. This is the same as above but will likely give better performance if simultaneous threads generate pseudo-random numbers at the same time.
  3. A slower but more random SecureRandom designed for important tasks where the inability to predict numbers is crucial to success. Examples include cases like gambling, scientific sampling, or any cryptographic operations. Although slower than the other two random number generators, its better randomness in many applications.

Having these choices allows developers to make the appropriate decision based on their application.

The Java Platform also allows software operators to override and control this behavior. For example improving true-ness of the Random generator or improving speed of SecureRandom with dedicated hardware.

Security through static typing

Java’s static typing can also enforce that program authors and library users apply the proper Random implementation. The random classes are designed with inheritance, allowing full interoperability across implementations. Both SecureRandom and ThreadLocalRandom inherit from Random, which means that implementations can be swapped or specified:

Random pseudoRandom = new Random();
Random pseudoRandomConcurrent = ThreadLocalRandom.current();
Random secureRandom = new SecureRandom();

For API design, developers can choose to only accept the appropriate version based on their use case. Given that true randomness is crucial to the success of cryptographic operations, it is critical that cryptographic APIs only accept SecureRandom arguments and never the super-class of Random. One example of this is KeyPairGenerator, which helps generate public/private keys that are used by many cryptographic systems. Users can only seed this with true-random values and not pseudo-random values.

KeyPairGenerator.initialize(int keysize, SecureRandom random);

Developers can only call this method by using statically-typed SecureRandom values. The super-type Random PRNG, which might make predictable keys, cannot work. Calling the overloaded KeyPairGenerator.initialize(int keysize) will also use a SecureRandom and is fine, the point here is that static typing prevents other types of Random from being used.

Using the previous example, one could call:

kpg.initialize(4096, (SecureRandom) secureRandom);

Or by specific static typing:

SecureRandom staticEnforcement = new SecureRandom();
kpg.initialize(4096, staticEnforcement);

API designers building secure systems should follow this example of statically typing SecureRandom in method signatures. When vetting secure software, look for usage of Random where a SecureRandom might be more appropriate. The US CERT Java coding guidelines offer additional guidance on evaluating the use of random numbers. Simon Kitching also has a good write-up about Using the SecureRandom Class.

Sources of Randomness

The sources for randomness are listed in the JDK’s security Standard Names documentation, identifying which are blocking or non-blocking. Although some sources rely on entropy pools, SecureRandoms like SHA1PRNG are quite fast once seeded and do not need additional entropy.

Blocking is especially important on Linux systems, where some calls to /dev/random may pause while the system generates a new true-random number. There is a trade-off /dev/urandom device that is non-blocking but somewhat less random.

Within a Java installation, the administrator can adjust various settings through the "JRE/lib/security/" configuration file. That file contains documentation about configuring securerandom.source and securerandom.strongAlgorithms. On Linux systems, the administrator may set their securerandom.source to  /dev/random or /dev/urandom accordingly.

Each operating system contains its recommended default value. System Administrators may edit that value, for example if their system has different RNGs or if they have a separate specialized hardware RNG.

JavaMex has a page describing the sources of entropy that Java uses on different operating systems.

Additional information is available in the SecureRandom javadoc.

Wednesday Jul 02, 2014

Diagnosing TLS, SSL, and HTTPS

When building inter-connected applications, developers frequently interact with TLS-enabled protocols like HTTPS. With recent emphasis on encrypted communications, I will cover the way in which the JDK evolves regarding protocols, algorithms, and changes, as well as some advanced diagnostics to better understand TLS connections like HTTPS.

Most developers will not have to do this level of diagnosis in the process of writing or running applications. In the event that you do, the following information should provide enough information to understand what's happening within secure connections.

Stability: The evolution of protocols and algorithms

For the last 15 years (since 1998), the Java platform has evolved through the Java Community Process where companies, organizations, and dedicated individuals develop and vote on specifications to determine what makes up the Java Platform. Much of the efforts are centered on compatibility, like the TCK, ensuring that different implementations are compatible with each-other and that developers can predict how their applications will run. We are not changing critical default options (like TLS protocol) within minor versions.

The following chart depicts the protocols and algorithms supported in each JDK version:

(March 2014 to present)
(July 2011 to present)
(2006 to end of public updates 2013)
TLS Protocols
TLSv1.2 (default)
TLSv1 (default)

TLS v1.1 (JDK 6 update 111 and above)
TLSv1 (default)
JSSE Ciphers:
Ciphers in JDK 8
Ciphers in JDK 7
Ciphers in JDK 6
Java Cryptography Extension, Unlimited Strength (explained later)
JCE for JDK 8 JCE for JDK 7 JCE for JDK 6

Sample Java code for making an HTTPS connection

Making an HTTPS connection in Java is relatively straight-forward. I will post the code here with the intent focused on tuning and understanding the underlying capabilities.

Sample back-end code for making an SSL connection:

final URL url = new URL("");
try(final InputStream in = url.openStream()){

Or the connection can be tuned through a cast:

final HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();
//operate on conn
try(final InputStream in = conn.getInputStream()){

Example: Qualys SSL Labs' "View My Client" Page

Qualys SSL Labs maintains a collection of tools that are helpful in understanding SSL/TLS connections. One in particular is a View My Client page, which will display information about the client connection. By integrating with that page, I was able to control the implementation as I used different Java tuning parameters.

To test parameter tuning, I implemented a small JavaFX application in JavaScript. It displays that page in a WebView, showing information about the underlying Java SSL/TLS client connection. You can find the code in the appendix.

JSSE Tuning Parameters

When diagnosing TLS-related issues, there are a number of helpful system properties. They are generally covered in their relevant sections of JSSE but this single collection may help anyone looking to understand the flexibility of Java’s implementation or diagnose connection details.
 Prints debugging details for connections made.
Example: or

Controls the protocol version used by Java clients which obtain https connections through use of the HttpsURLConnection class or via URL.openStream() operations. For older versions, this can update the default in case your Java 7 client wants to use TLS 1.2 as its default.
Example: -Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2

For non-HTTP protocols, this can be controlled through the SocketFactory's SSLContext.

jdk.tls.client.protocols Introduced in JDK 8, this controls the underlying platform TLS implementation. Additional information is available in the JSSE Reference Guide.
Example: -Djdk.tls.client.protocols=TLSv1.1,TLSv1.2
When initiating connections, Java will apply this as its user-agent string. Modifying this will handle cases where the receiving party responds differently based on the user-agent.
Example: -Dhttp.agent="known agent" proxy details from the operating system itself.
The proxy connection to use for HTTP connections.
Example: -Dhttp.proxyPort=8080
The same as above, except that configuration is separate between HTTP and HTTPS.
Password-based credentials for the above proxies.

Many other protocols and properties can be found within the following areas:

Example of diagnosing a problem

When making an HTTPS connection, let’s assume that the client threw the following exception due to a failed handshake with the server: Received fatal alert: handshake_failure 

SSLHandshakeException is a subclass of the IOException, so you do not need to catch is explicitly. Most developers will not need an explicit catch, but it may help you more easily diagnose the cause of any IOException.

When applying the property from above, the failure associated with this SSLHandshakeException would appear immediately after algorithm negotiation in the logs.

 JDK 7 (fails on unsupported algorithm) JDK 8 (works fine)
Cipher Suites: […Long list of ciphers…]
Compression Methods:  { 0 }
Extension elliptic_curves, curve names: {…}
Extension ec_point_formats, formats: [uncompressed]
Extension server_name, server_name: [host_name: HOST]
main, WRITE: TLSv1 Handshake, length = 168
main, READ: TLSv1 Alert, length = 2
main, RECV TLSv1 ALERT:  fatal, handshake_failure
main, called closeSocket()
main, handling exception: Received fatal alert: handshake_failure
Cipher Suites: […Long list of ciphers…]
Compression Methods:  { 0 }
Extension elliptic_curves, curve names: {…}
Extension ec_point_formats, formats: [uncompressed]
Extension signature_algorithms, signature_algorithms: …
Extension server_name, server_name: [type=host_name (0), value=HOST]
main, WRITE: TLSv1.2 Handshake, length = 226
main, READ: TLSv1.2 Handshake, length = 89
*** ServerHello, TLSv1.2
RandomCookie:  GMT: -1809079139 bytes = { …}
Session ID:  {…}
Compression Method: 0
Extension renegotiation_info, renegotiated_connection: <empty>
Extension ec_point_formats, formats: [uncompressed, ansiX962_compressed_prime, ansiX962_compressed_char2]
%% Initialized:  [Session-1, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256]
main, READ: TLSv1.2 Handshake, length = 2308

In the case above, the failure occurred during the handshake. The most likely cause for that is algorithm support. The JDK provides a separate package called JCE Unlimited Strength, designed to add stronger algorithm support than what’s available by default. Qualys SSL Labs provides a different server SSL test that will enumerate which algorithms a server supports.

Many TLS error messages are covered in a few pieces of documentation:

Adding stronger algorithms: JCE Unlimited Strength

In a high security environment, one way of strengthening algorithms in the JDK is through the JCE Unlimited Strength policy files. In this particular case, replacing those policy files within JDK 7 allows it to use the stronger variants of existing algorithms and connect successfully.

JCE Unlimited Strength downloads: JDK 8, JDK 7, or JDK 6.


The following code will open Qualys SSL Labs’ View My Client page within a Java client. To test configurations, run this like:

jjs -fx viewmyclient.js
jjs -fx -Dhttps.protocols=TLSv1 viewmyclient.js

var Scene = javafx.scene.Scene;
var WebView = javafx.scene.web.WebView;
var browser = new WebView();
$STAGE.scene = new Scene(browser);

Tuesday Sep 03, 2013

Code signing: Understanding who and when

Code signatures have become more commonplace for applications in recent years and especially so in Java 7 update 21 (April 16, 2013). The security notifications for Java help provide your users with an understanding of who wrote the application so that they can decide whether to run it or not. Through the default settings of the Java security slider, end-users are blocked from running unsigned or self-signed applets and prompted for running signed applets.

These cryptographic signatures are designed to provide a means of authentication, proving to users that they are indeed running the same application that you wrote and that it has not been modified in any way. Within information security threat modeling terms, this is a means of repudiation.

Developers must sign any browser applet or Web Start application that they produce. Signatures on other application types (such as back-end server applications) are optional.

System Administrators may be impacted and have a choice for what to do:

  1. For managed users, the system administrator can add a Deployment Rule Set to client systems and indicate which applets may run.
  2. For unmanaged or bring-your-own-device users, the system administrator may sign jars with their own certificate.

Several steps are involved to sign code:

  1. Determine who in your organization is responsible for code signing
  2. Purchase a signing certificate from a public Certificate Authority.
  3. System Administrators: sign a jar using normal commands
  4. Developers: integrate code signing into your build chain

Determine who in your organization is responsible for code signing

In corporate enterprises, there is often a technology group responsible for these signatures. This group is usually separate from most system administrators in order to keep the private key a secret. The goal is to decrease the number of people with access to the private key.

If you are in a corporate enterprise, please look internally for a code signing group and ask them for their signing process instead.

Purchase a signing certificate

If you or your group is identified as responsible for code signing, then the next step is to obtain a code signing certificate. If a different group provides signatures (as in many large organizations), follow their process instead.

All users (system administrators and developers) that intend to sign code must purchase a signing certificate from a known authority. Certificate authorities help manage trust across millions of systems and prevent identity spoofing, or cases where someone else generates their own certificate pretending to be you. Signing certificates are available from companies like GoDaddy, Symantec, or others. Each certificate authority provides instructions for generating a certificate signing request with the keytool command.

Code signing certificates are different from domain certificates normally used for HTTPS websites. Signing certificates must be purchased from a Certificate Authority -- Oracle is not a Certificate Authority.

System Administrators: sign a jar using normal commands

After receiving the signing certificate, system administrators can sign files using the following jarsigner command:

jarsigner -verbose -keystore "c:\Users\ecostlow\javakeystore_keepsecret.jks" -tsa -signedjar FILENAME.jar FILENAME.jar your-certificate-name
Enter Passphrase for keystore:
  signing: ruleset.xml

Developers: integrate code signing into your build chain

In an ideal environment, members of the development team would not have access to the private key and its password. The fewer people that have this private key, the better.

For build automation, you can create stubs that allow other members of the team to substitute the real private key and password, without exposing this sensitive information.

Please note that Oracle only maintains the default jarsigner command (described above for System Administrators) and does not manage or control build tools.


The ant build system provides a SignJar task to mimic the jarsigner command. When using this task, just be sure to call the ant sign target.

<property file="" />
<target name="sign">
		alias="${sign.alias}" keystore="${sign.keystore}"
		storepass="${sign.storepass}" tsaurl="">
		<fileset dir="dist" includes="**/*.jar" />

Then, both the development team and build team would have different entries for

 Dev would have this for testing
Build (continuous integration) would have this, keeping it secret

By taking these actions, developers can automate their build to sign jar files without exposing the private key to the entire development team.


Maven provides a maven-jarsigner plugin to mimic the jarsigner command.


Maven uses the idea of Profiles to externalize properties.

Dev would have this for testing
Build (continuous integration) would have this, keeping it secret

By taking these actions, developers can automate their build to sign jar files without exposing the private key to the entire development team.

Other build system

If your development team is using an alternate build system, please review its documentation for the appropriate call. Most build systems should have this, but the default jarsigner command will always work if you need.

Leveraging internal code signing authorities

Many large organizations have an internal code signing group. The benefit of these groups is that they help keep the private keys secret in a way that neither developers nor build integrators have access. Separation also allows this group to dedicate more time towards best practices, like keeping keys on tamper-proof hardware/smart-cards. If your organization has this group, the usual practice is to automate sending code artifacts to this team’s service and retrieving the resulting signed artifacts. Reference documentation for using separate hardware key components is available in the PKCS#11 Reference Guide.

A word on timestamps

The optional timestamping provides a notary-like capability of identifying when the signature was applied.

  • If a certificate passes its natural expiration date without revocation, trust is extended for the length of the timestamp.
  • Timestamps are not considered for certificates that have been revoked, as the actual date of compromise could have been before the timestamp occurred.

Although not required, it is a good practice to timestamp anything that you sign. Popular timestamping authority URLs include:


Science Duke
This blog contains topics related to Java SE, Java Security and Usability. The target audience is developers, sysadmins and architects that build, deploy and manage Java applications. Contributions come from the Java SE Product Management team.


« July 2016