TLS Channel is a library that implements a ByteChannel interface over a TLS (Transport Layer Security) connection. The library delegates all cryptographic operations to the standard Java TLS implementation: SSLEngine; effectively hiding it behind an easy-to-use streaming API, that allows to securitize JVM applications with minimal added complexity.
In other words, a simple library that allows the programmer to have TLS using the same standard socket API used for plaintext, just like OpenSSL does for C, only for Java, filling a specially painful missing feature of the standard Java library.
- Implements ByteChannel, GatheringByteChannel and ScatteringByteChannel, the same interfaces implemented by SocketChannel, effectively making encryption an implementation detail. There is no need to directly call SSLEngine except for the initial setup.
- Works for both client and server-side TLS.
- Server-side SNI: Supports choosing different SSLContexts according to the received Server Name Indication sent by incoming connections (not supported at all by SSLEngine but universally used by web browsers and servers).
- Supports both blocking and non-blocking modes, using the same API, just like SocketChannel does with unencrypted connections.
- Pluggable buffer strategy (to do buffer pooling, or to use direct buffers for IO).
- Full and automatic zeroing of all the plaintext contained in internal buffers right after the data stops being necessary.
- Opportunistic buffer release (akin to OpenSSL's SSL_MODE_RELEASE_BUFFERS option), which significantly reduces the memory footprint of idle cached connections.
- Full control over TLS shutdown to prevent truncation attacks.
Being a API layer, TLS Channel delegates all cryptographic operations to SSLEngine, leveraging it 100%. This implies that:
- With the exception of a few bytes of parsing at the beginning of the connection, to look for the SNI, the whole protocol implementation is done by the SSLEngine (this parsing is not done at all if SNI support is not required).
- Both the SSLContext and SSLEngine are supplied by the client; these classes are the ones responsible for protocol configuration, including hostname validation, client-side authentication, encryption, protocol implementation, etc.
By far, the most used cryptography solution is TLS (a.k.a. SSL). TLS works on top of the Transport Control Protocol (TCP), maintaining its core abstractions: two independent byte streams, one in each direction, with ordered at-most-once delivery.
Recent trends have increased the pressure to add encryption in even more use cases. There have been indeed many efforts to reduce friction regarding security. One example of this is the "Let's Encrypt" project. From the programming perspective, the overwhelming consensus has been to replicate the existing interface (that is, something similar to the highly successful and familiar Berkeley Sockets) for the cryptographic streams:
- The most used TLS library is OpenSSL. Written in C and (along with some forks) the de facto standard for C and C++. Also widely used in Python, PHP, Ruby and Node.js.
- The Go language has its own implementation, package crypto/tls.
- There is another C library by Mozilla, part of the "Network Security Services" (NSS) group of libraries. It's notoriously used by the Firefox browser.
And many more. All this libraries implement a streaming interface, and most let the user switch freely between blocking and non-blocking behavior. But in Java the history, unfortunately, is not so simple.
In Java, support for TLS (then SSL) was added in version 1.2 (as an optional package) in the form of a subclass of the Socket class: SSLSocket. Being a subclass, once instantiated, the mode of use was exactly the same as the unencrypted original. That worked (and still works) well enough. Nevertheless, the java IO API already had some limitations, and an update was due.
In version 1.4, a new IO API was launched (java.nio). It superseded the old IO API, starting an implicit (and very long) deprecation cycle. New features include:
- Non-blocking operations.
- A higher lever API, based on wrapped buffers (ByteBuffers).
- Direct IO, with "direct" ByteBuffers, that can live out of the heap. This is specially advantageous for sockets, as the JVM forces an extra copy of any heap-based array sent in a native call (to facilitate synchronization with the garbage collector). Not having the buffer in the heap avoids this copy, improving performance (at the cost of slightly more complicated memory management).
- "Scattering" and "gathering" API, that is, the ability to use more than one sequential buffer in the same IO operation.
But no TLS support, which was only available in old-style sockets.
Version 1.5 saw the advent of SSLEngine as the official way of doing TLS over NIO sockets. This API has been the official option for more than a decade. However, it has severe shortcomings:
- No streaming support. SSLEngine does not do any IO, or keep any buffers. It does all cryptographic operations on user-managed buffers (but, confusingly, at the same time keeps internal state associated with the TLS connection). This no-data—but stateful—API is just not what users expect or are used to, and indeed not what the rest of the industry has standarized on.
- Even considering the constrains, the API is unnecessarily convoluted, with too big a surface, and many incorrect interactions not constrained by the types.
- No support for server-side SNI handling.
Of course, many programmers don't manipulate TCP or TLS streams directly, but use protocol libraries (e.g., Apache HttpClient). However, in the case that direct socket-like access is needed, the programmer has essentially three alternatives:
- Use the old (implicitly deprecated) socket API. This implies being subject to its limitations, which means, among other things, only blocking behavior.
- Use SSLEngine directly. This is a hard task, which is very difficult to accomplish correctly, and in most cases completely out of proportion to the effort of writing the application code.
- Use some higher-level IO library, like Netty, Project Grizzly, Apache Mina or JBoss XNIO. These frameworks supply event architectures that intend to easy the task of writing programs that use non-blocking IO. They are big framework-like libraries, sometimes themselves with dependencies. Using one of these is the path chosen by many, but it is not an option if the programmer cannot commit to a particular event architecture, couple the application code to an idiosyncratic library, or include a big dependency.
All three alternatives have been taken by many Java libraries and applications, with no clear preference among leading open-source Java projects. Even though these options can work reasonable well, there was still no clear and standard solution.
There is of course no strict need to use SSLEngine. The two most common alternatives are:
- Use the Java Native Interface (JNI) and call OpenSSL. The Tomcat project has a widely used "native" library that easies that task. While using native code can work, this as obvious shortcomings, specially regarding distribution, type compatibility and safety.
- "The Legion of the Bouncy Castle" has a "lightweight" TLS API that supports streaming. This works but only in blocking mode, effectively just like using the old SSLSocket API.
Of course, these options imply using an alternative cryptographic implementation, which may not be desired.
The feat of using SSLEngine directly is indeed performed by several projects, both general purpose IO libraries and implementation of particular protocols. Below is an inevitably incomplete list of open-source examples. Every one in the list contains essentially the same general-purpose, SSLEngine-calling code, only embedded in custom types and semantics. That said, these examples, while not really suited for reuse, have been invaluable for both appreciating the difficulty of the task, and also as a source of ideas.
| Type | Project | Package/class |
|---|---|---|
| IO framework | Grizzly | org.glassfish.grizzly.ssl |
| IO framework | Netty | io.netty.handler.ssl.SslHandler |
| IO framework | Apache Mina | org.apache.mina.filter.ssl.SslHandler |
| IO framework | XNIO | org.xnio.ssl.JsseStreamConduit |
| HTTP server | Tomcat | org.apache.tomcat.util.net.SecureNio2Channel |
| HTTP server | OpenJDK | sun.net.httpserver.SSLStreams |
| HTTP client/server | Apache HttpComponents | org.apache.http.impl.nio.reactor.SSLIOSession |
| HTTP server | Jetty | org.eclipse.jetty.io.ssl.SslConnection |
| Distributed file system | XtreemFS | org.xtreemfs.foundation.pbrpc.channels.SSLChannelIO |
| Tor client | Orchid | com.subgraph.orchid.sockets.sslengine.SSLEngineManager |
Being an instance of ByteChannel, normal IO operations are just done in the usual way. For instantiation of both client and server connections, builders are used:
ByteChannel rawChannel = ...
SSLContext sslContext = ...
TlsChannel tlsChannel = ClientTlsChannel
.newBuilder(rawChannel, sslContext)
.build();ByteChannel rawChannel = ...
SSLContext sslContext = ...
TlsChannel tlsChannel = ServerTlsChannel
.newBuilder(rawChannel, sslContext)
.build();Typical usage involved creating either a ClientTlsChannel or a ServerTlsChannel, for client and server connections respectively. Both classes implement TlsChannel, where most of the methods are defined.
Complete examples:
Standard ByteChannel instances communicate the fact that operations would block—and so that they should be retried when the channel is ready—returning zero. However, as TLS handshakes happen transparently and involve multiple messages from each side, both a read and a write operation could be blocked waiting for either a read (byte available) or a write (buffer space available) in the underlying socket. That is, some way to distinguish between read- or write-related blocking is needed.
Ideally, a more complex return type would suffice—not merely an int but some object including more information. For instance, OpenSSL uses special error codes for these conditions: SSL_ERROR_WANT_READ and SSL_ERROR_WANT_WRITE.
In the case of TLS Channel, it is in practice necessary to maintain compatibility with the existing ByteChannel interface. That's why an somewhat unorthodox approach is used: when the operation would block, special exceptions are thrown: NeedsReadException and NeedsWriteException, meaning that the operation should be retried when the underlying channel is ready for reading or writing, respectively.
Typical usage inside a selector loop looks like this:
try {
int c = tlsChannel.read(buffer);
...
} catch (NeedsReadException e) {
key.interestOps(SelectionKey.OP_READ);
} catch (NeedsWriteException e) {
key.interestOps(SelectionKey.OP_WRITE);
}Complete example: non-blocking server
Selector loops work under the assumption that they don't (mostly) block. This is enough when it is possible to have as many loops as CPU cores. However, Java selectors don't work very well with multiple threads, requiring complicated synchronization; this leads to them being used almost universally from a single thread.
A single IO thread is in general enough for plaintext connections. But TLS can be CPU-intensive, in particular asymmetric cryptography when establishing sessions. Fortunately, SSLEngine encapsulates those, returning Runnable objects that the client code can run in any thread. TLS Channel can be configured to either run those as part of IO operations (that is, in-thread)—the default behavior—or not, letting the calling code handle them. The latter option should be enabled at construction time:
TlsChannel tlsChannel = ServerTlsChannel
.newBuilder(rawChannel, sslContext)
.withRunTasks(false)
.build();An exception (NeedsTaskException) is then used to communicate that a task is ready to run. (Using an exception is needed for the same reasons explained in the previous section):
try {
int c = tlsChannel.read(buffer);
...
} catch ...
} catch (NeedsTaskException e) {
taskExecutor.execute(() -> {
e.getTask().run();
// when the task finished, add it the the ready-set
// taskReadyKeys should be a concurrent set that shoud be checked
// and emptied as part of the selector loop
taskReadyKeys.add(key);
selector.wakeup(); // unblock the selector
});
}Complete example: non-blocking server with off-loop tasks
The Server Name Indication is a special TLS extension designed to solve a chicken-and-egg situation between the certificate offered by the server (depending on the host required by the client for multi-host servers) and the host name sent by client in HTTP request headers (necessarily after the connection is established). The extension allows the client to anticipate the required host in the ClientHello message.
Java added support for SNI in version 7. The feature can be accessed using the SSLParameters class. Sadly, this only works for the client side. For the server, the class allows only to accept or reject connections based on the host name, not to choose the certificate offered.
In TLS Channel, to use SNI-based selection of the SSLContext, a different builder factory method exists, receiving instances of SniSslContextFactory.
SniSslContextFactory contextFactory = (Optional<SNIServerName> sniServerName) -> {
Optional<SSLContext> ret = ...
return ret;
};
TlsChannel tlsChannel = ServerTlsChannel
.newBuilder(rawChannel, contextFactory)
.build();Complete example: SNI-aware server
TLS Channel uses buffers for its operation. Every channel uses at least two "encrypted" buffers that hold ciphertext, one for reading from the underlying channel and other for writing to it. Additionally, a third buffer may be needed for read operations when the user-supplied buffer is smaller than the minimum SSLEngine needs for placing the decrypted bytes.
All buffers are created from optionally user-supplied factories (instances of BufferAllocator). It is also possible to supply different allocators for plain and ciphertext. For example:
TlsChannel tlsChannel = ServerTlsChannel
.newBuilder(rawChannel, sslContext)
.withPlainBufferAllocator(new HeapBufferAllocator())
.withEncryptedBufferAllocator(new DirectBufferAllocator())
.build();This is indeed the default behavior. The rationale for the encrypted buffers is that, in the most common use case, the underlying channel is a SocketChannel. This channel actually does native IO operations, which are generally faster using direct buffers.
The plain buffers are not involved in IO, and so standard heap allocation is used by default.
Buffers containing plain text are always immediately zeroed after the bytes are returned.
TLS Channel supports opportunistic buffer release, a similar feature to OpenSSL's SSL_MODE_RELEASE_BUFFERS option. If, after any operation, a buffers does not contain any bytes pending, it is released back to the pool. This feature can reduce memory consumption dramatically in the case of long-lived idle connections, which tend to happen when implementing server-side HTTP.
The option is enabled by default, and could be disabled if desired:
TlsChannel tlsChannel = ServerTlsChannel
.newBuilder(rawChannel, sslContext)
.withReleaseBuffers(false)
.build();Because the protocol implementation is fully delegated to SSLEngine, there are no limitations regarding TLS versions: whatever is supported by the Java implementation used will work.
The same applies to certificate validation. All configuration is done using the SSLContext object, which TLS Channel takes as is.
TLS Channel requires Java 8.
The library has only one dependency: SLF4J. The main jar file size is below 50 KB.
The library uses SLF4J for logging, which is the most widely used pluggable logging framework for the JVM. As a policy, all logging event emitted are at TRACE level, which is below the default threshold in most logging implementations and thus completely silent by default.
- NIO SSL is a simple library with a similar purpose, written by Corey Baswell.
- sslfacade is an attempt to offer a more reasonable interface than SSLEngine, written by Kashif Razzaqui.
- sslengine.example shows how to use SSLEngine, wrapping it in custom classes. It was written by Alex Karnezis.
This work is based on a preliminary implementation by Claudio Martinez and Mariano Barrios at Despegar.