SSerguey Asael Shinder
Java coding notes: the JVM, and writing software that lasts

Serguey Asael Shinder: In SSLSessionContext, zero means no limit and a negative timeout must throw

· by Serguey Asael Shinder / Serguey Shinder

This week Netty fixed its QUIC SSL context so that setSessionTimeout(-1) throws instead of storing -1 (pull request 18414). On the server side the stored value went to BoringSSL as an unsigned 32-bit number, which turned -1 into a session timeout of roughly 136 years. The fix is three lines. The reason it was needed is in the interface every implementation has to follow.

javax.net.ssl.SSLSessionContext has two setters, and the Java SE 25 javadoc gives both the same contract.

For setSessionTimeout(int seconds), the parameter is "the new session timeout limit in seconds; zero means there is no limit", and the method throws IllegalArgumentException "if the timeout specified is < 0". For setSessionCacheSize(int size), the parameter is "the new session cache size limit; zero means there is no limit", and it throws IllegalArgumentException "if the specified size is < 0".

So the int range is split three ways by the specification itself:

SSLSessionContext ctx = sslContext.getServerSessionContext();
ctx.setSessionTimeout(3600);   // sessions expire one hour after creation
ctx.setSessionTimeout(0);      // no timeout at all
ctx.setSessionTimeout(-1);     // must throw IllegalArgumentException
Serguey Asael Shinder: In SSLSessionContext, zero means no limit and a negative timeout must throw
In SSLSessionContext, zero means no limit and a negative timeout must throw — Serguey Asael Shinder

Two details in the same javadoc are easy to miss.

The first is what the timeout measures. A session "exceeds the timeout limit 't' seconds after its creation time", not after its last use. When that happens the session is marked so that future connections cannot resume or rejoin it, but active sessions continue as long as they do not try to resume. And the check is made immediately whenever the limit is changed, so lowering the timeout on a running context can invalidate sessions on the spot.

The second is the default. The implementation notes say the JDK returns a session timeout of 86,400 seconds, 24 hours, if none has been set, and a cache size taken from the javax.net.ssl.sessionCacheSize system property, or 20,480 if that is not set either. The API note on both setters suggests applications consider their performance needs and override the defaults if necessary.

Reading the contract this way explains why zero is dangerous in configuration code. A setting read from a file, where an empty value or a parse failure falls back to 0, does not produce an error here: it produces sessions that never expire, or an unbounded cache. That is legal according to the javadoc and probably not what anyone wanted.

If your code computes these values, validate them before they reach the setter, and decide explicitly what 0 should mean in your configuration. The interface has already decided what it means in the JDK.