How to configure the new properties 'jdk.tls.maxCertificateChainLength' and 'jdk.tls.maxHandshakeMessageSize'

Applies To

Java SE JDK and JRE - Version 8 and later
Any platform

Introduction

This article explains how to override the default settings of the new system properties: jdk.tls.maxCertificateChainLength and jdk.tls.maxHandshakeMessageSize.

These two system properties were introduced in Java SE 1.7.0_281 and 1.8.0_271.

Default Values

• jdk.tls.maxHandshakeMessageSize specifies the maximum handshake message size and default is 32768 (32 kilobytes)
• jdk.tls.maxCertificateChainLength specifies the maximum certificate chain length and default is 10

Explanation

There are two ways to configure these system properties.

1. Set them on the Java command line with the -D option. For example:

• -Djdk.tls.maxCertificateChainLength=<INTEGER>
• -Djdk.tls.maxHandshakeMessageSize=<INTEGER>

2. Programmatically by using the System.setProperties() method.

The default values were chosen for the following reasons:

• For better compatibility, the default for maximum handshake message size is limited to 2^14 bytes. This is because BoringSSL (a Google fork of OpenSSL) uses a hard-coded size limit 2^14 bytes (16KB).
• The default maximum certificate chain length is limited to 10 as OpenSSL’s default maximum chain length is 10

You can find these properties documented in the Java Secure Socket Extension (JSSE) chapter of the Java Security Guide.

• JDK 25 (LTS)
• JDK 21 (LTS)
• JDK 17 (LTS)
• JDK 11 (LTS)
• JDK 8 (LTS)

Last reviewed on Sat Feb 01 2025 00:00:00 GMT+0000 (Coordinated Universal Time)